AIclinicalresearch/docs/00-系统总体设计/前后端模块化架构设计-V2.md

# 前后端模块化架构设计 V2.0

> **版本：** V2.2  
> **创建日期：** 2025-11-12  
> **实施阶段：** Week 2（2025-11-13开始）  
> **维护者：** 开发团队  
> **状态：** ✅ Week 2 Day 6-9 全部完成（前端架构+模块注册+后端分层）⭐⭐⭐  

---

## 📋 文档说明

本文档是**AI临床研究平台的模块化架构设计总纲**，定义了：

1. **前端架构**：全新的 frontend-v2 模块化架构
2. **后端架构**：基于Schema隔离的分层架构
3. **前后端对应关系**：模块化的组织方式
4. **开发规范**：统一的代码组织和命名规范
5. **实施路线**：渐进式的架构改造计划

**适用对象：**
- 新加入的开发人员（快速了解系统架构）
- AI助手（理解代码组织结构）
- 技术决策者（架构演进参考）

---

## 🎯 架构演进历史

### V1.0 阶段（2025-10之前）
- ❌ 单体前端应用（所有功能耦合）
- ❌ 后端代码平铺（无模块划分）
- ❌ 数据库表全在public schema

### V1.5 阶段（2025-11-12完成）
- ✅ **数据库Schema隔离**（10个Schema）
- ✅ Prisma多Schema配置
- ✅ 数据100%迁移成功
- ⚠️ 前后端代码仍需模块化

### V2.0 阶段（2025-11-13~14完成）⭐
- ✅ **前端模块化架构**（frontend-v2）- Day 6-7完成
- ✅ **模块注册机制**（权限控制+错误边界+路由守卫）- Day 7完成
- ✅ **后端增量演进架构**（legacy/common/modules）- Day 8-9完成
- ✅ 前后端模块对应
- ✅ 支持模块独立开发和部署
- ✅ **所有功能测试通过**（包括批处理修复）⭐⭐⭐

---

## 📸 当前架构真实状态（2025-11-14）

> **⭐ 重要提示：本章节描述当前实际运行的架构状态**  
> **适用对象：新开发人员、新AI助手、快速上手**  
> **更新频率：架构变更时立即更新**

---

### 🎯 架构概览

```
【当前状态】增量演进架构（新旧并存）

Frontend-v2 (新)          Backend (混合)              Database (隔离)
    ↓                         ↓                           ↓
顶部导航 + 6模块          legacy/ + common/         10个独立 Schema
   占位                   + modules/asl               (3详细 + 7空)
```

**核心策略：**
- ✅ 前端：全新架构（frontend-v2）
- ✅ 后端：新旧并存（legacy保持稳定，新模块标准化）
- ✅ 数据库：Schema隔离完成

---

### 📁 前端真实架构（Frontend-v2）

#### **目录结构（实际存在）**

```bash
frontend-v2/
├── src/
│   ├── framework/                      # 🏗️ 框架层（已实现）
│   │   ├── layout/                     
│   │   │   ├── MainLayout.tsx          # ✅ 主布局
│   │   │   ├── TopNavigation.tsx       # ✅ 顶部导航
│   │   │   └── UserMenu.tsx            # ✅ 用户菜单
│   │   │
│   │   ├── modules/                    
│   │   │   ├── moduleRegistry.ts       # ✅ 模块注册中心
│   │   │   ├── ErrorBoundary.tsx       # ✅ 错误边界
│   │   │   └── ModuleErrorFallback.tsx # ✅ 错误回退UI
│   │   │
│   │   ├── router/                     
│   │   │   ├── RouteGuard.tsx          # ✅ 路由守卫
│   │   │   └── PermissionDenied.tsx    # ✅ 权限拒绝页
│   │   │
│   │   └── permission/                 
│   │       ├── PermissionContext.tsx   # ✅ 权限上下文
│   │       ├── usePermission.ts        # ✅ 权限Hook
│   │       └── types.ts                # ✅ 权限类型
│   │
│   ├── modules/                        # 📦 业务模块（占位）
│   │   ├── asl/                        # 🚧 Week 3开发
│   │   │   └── index.tsx               # ✅ 占位页面
│   │   ├── aia/                        # 📋 占位
│   │   ├── pkb/                        # 📋 占位
│   │   ├── dc/                         # 📋 占位
│   │   ├── ssa/                        # 📋 占位
│   │   └── st/                         # 📋 占位
│   │
│   ├── pages/                          
│   │   └── Home.tsx                    # ✅ 首页
│   │
│   └── App.tsx                         # ✅ 应用入口
│
├── package.json                        # ✅ React 19
└── vite.config.ts                      # ✅ Vite配置
```

**当前运行状态：**
- ✅ 访问地址：http://localhost:3000
- ✅ 顶部导航显示6个模块
- ✅ 权限控制工作正常（mock premium用户）
- ✅ 路由守卫生效
- ✅ 错误边界正常捕获

---

### 🗄️ 后端真实架构（Backend）

#### **目录结构（实际存在）⭐ 关键**

```bash
backend/
├── src/
│   ├── legacy/                         # 🔸 现有业务代码（稳定运行）
│   │   ├── routes/                     # 7个路由文件
│   │   │   ├── agents.ts               # AIA: 智能体路由
│   │   │   ├── conversations.ts        # AIA: 对话路由
│   │   │   ├── chatRoutes.ts           # AIA: 通用对话路由
│   │   │   ├── projects.ts             # AIA: 项目路由
│   │   │   ├── knowledgeBases.ts       # PKB: 知识库路由
│   │   │   ├── batchRoutes.ts          # PKB: 批处理路由
│   │   │   └── reviewRoutes.ts         # RVW: 稿件审查路由
│   │   │
│   │   ├── controllers/                # 8个控制器
│   │   │   ├── agentController.ts
│   │   │   ├── conversationController.ts
│   │   │   ├── chatController.ts
│   │   │   ├── projectController.ts
│   │   │   ├── knowledgeBaseController.ts
│   │   │   ├── documentController.ts
│   │   │   ├── batchController.ts
│   │   │   └── reviewController.ts
│   │   │
│   │   ├── services/                   # 8个服务
│   │   │   ├── agentService.ts
│   │   │   ├── conversationService.ts
│   │   │   ├── projectService.ts
│   │   │   ├── knowledgeBaseService.ts
│   │   │   ├── documentService.ts
│   │   │   ├── batchService.ts
│   │   │   ├── reviewService.ts
│   │   │   └── tokenService.ts
│   │   │
│   │   └── templates/
│   │       └── clinicalResearch.ts     # 批处理模板
│   │
│   ├── common/                         # 🔧 通用能力层（共享）+ ⭐ 平台基础设施（云原生）
│   │   │                               # 📋 详见：docs/09-架构实施/04-平台基础设施规划.md
│   │   ├── llm/                        
│   │   │   └── adapters/               # LLM适配器
│   │   │       ├── DeepSeekAdapter.ts  # ✅ DeepSeek-V3
│   │   │       ├── QwenAdapter.ts      # ✅ Qwen3-72B + Qwen-Long
│   │   │       ├── LLMFactory.ts       # ✅ 工厂类
│   │   │       └── types.ts            # ✅ LLM类型定义
│   │   │
│   │   ├── rag/                        # RAG能力
│   │   │   ├── DifyClient.ts           # ✅ Dify客户端
│   │   │   └── types.ts                # ✅ RAG类型
│   │   │
│   │   ├── document/                   # 文档处理
│   │   │   └── ExtractionClient.ts     # ✅ 文档提取客户端
│   │   │
│   │   ├── storage/                    # ⭐ 存储抽象层（云原生）
│   │   │   ├── StorageAdapter.ts       # ⭐ 接口定义
│   │   │   ├── LocalAdapter.ts         # ⭐ 本地实现
│   │   │   ├── OSSAdapter.ts           # ⭐ OSS实现
│   │   │   ├── StorageFactory.ts       # ⭐ 工厂类
│   │   │   └── index.ts                # ⭐ 统一导出
│   │   │
│   │   ├── logging/                    # ⭐ 日志系统（云原生）
│   │   │   ├── logger.ts               # ⭐ Winston日志配置
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── cache/                      # ⭐ 缓存服务（云原生）
│   │   │   ├── CacheAdapter.ts         # ⭐ 接口定义
│   │   │   ├── MemoryCacheAdapter.ts   # ⭐ 内存实现
│   │   │   ├── RedisCacheAdapter.ts    # ⭐ Redis实现
│   │   │   ├── CacheFactory.ts         # ⭐ 工厂类
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── jobs/                       # ⭐ 异步任务（云原生）
│   │   │   ├── JobQueue.ts             # ⭐ 任务队列接口
│   │   │   ├── MemoryQueue.ts          # ⭐ 内存队列
│   │   │   ├── DatabaseQueue.ts        # ⭐ 数据库队列
│   │   │   ├── JobProcessor.ts         # ⭐ 任务处理器
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── health/                     # ⭐ 健康检查（云原生）
│   │   │   ├── healthCheck.ts          # ⭐ 健康检查路由
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── monitoring/                 # ⭐ 监控指标（云原生）
│   │   │   ├── metrics.ts              # ⭐ 指标收集
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── middleware/                 
│   │   │   └── validateProject.ts      # ✅ 项目验证中间件
│   │   │
│   │   └── utils/                      
│   │       └── jsonParser.ts           # ✅ JSON解析工具
│   │
│   ├── modules/                        # 🌟 新架构模块（标准化）
│   │   └── asl/                        # ⭐ AI智能文献（占位，Week 3开发）
│   │       └── (空目录，等待开发)
│   │
│   ├── config/                         # ⚙️ 配置层
│   │   ├── database.ts                 # ✅ 数据库配置
│   │   └── env.ts                      # ✅ 环境变量
│   │
│   ├── scripts/                        # 🛠️ 工具脚本
│   │   ├── create-mock-user.ts
│   │   └── test-dify-client.ts
│   │
│   └── index.ts                        # ✅ 主入口（统一注册）
│
├── config/                             # 外部配置文件
│   └── agents.yaml                     # ✅ 智能体配置（348行）
│
├── prompts/                            # Prompt模板
│   ├── topic_evaluation_system.txt
│   ├── review_editorial_system.txt
│   └── review_methodology_system.txt
│
├── prisma/
│   ├── schema.prisma                   # ✅ 10个Schema定义
│   └── migrations/                     # ✅ 4个迁移文件
│
├── package.json                        # ✅ Fastify + Prisma
└── .env                                # ✅ 环境变量
```

**当前运行状态：**
- ✅ 访问地址：http://localhost:3001
- ✅ 健康检查：http://localhost:3001/health
- ✅ Legacy模块（AIA/PKB/RVW）正常运行
- ✅ Common层通用能力可用
- ✅ Modules/asl 占位就绪

**主入口（index.ts）实际代码：**
```typescript
// ============================================
// 【旧架构】Legacy 模块 - 保持不变
// ============================================
import { projectRoutes } from './legacy/routes/projects.js';
import { agentRoutes } from './legacy/routes/agents.js';
import { conversationRoutes } from './legacy/routes/conversations.js';
import knowledgeBaseRoutes from './legacy/routes/knowledgeBases.js';
import { chatRoutes } from './legacy/routes/chatRoutes.js';
import { batchRoutes } from './legacy/routes/batchRoutes.js';
import reviewRoutes from './legacy/routes/reviewRoutes.js';

// 注册 Legacy 模块路由
await fastify.register(projectRoutes, { prefix: '/api/v1/aia' });
await fastify.register(agentRoutes, { prefix: '/api/v1/aia' });
await fastify.register(conversationRoutes, { prefix: '/api/v1/aia' });
await fastify.register(chatRoutes, { prefix: '/api/v1/aia' });
await fastify.register(knowledgeBaseRoutes, { prefix: '/api/v1/pkb' });
await fastify.register(batchRoutes, { prefix: '/api/v1/pkb' });
await fastify.register(reviewRoutes, { prefix: '/api/v1/rvw' });
```

---

### 🗃️ 数据库真实架构（PostgreSQL 15）

#### **Schema 结构（实际存在）**

```sql
-- ==================== 平台层 Schema ====================
platform_schema (平台基础表)
  └── users                    # ✅ 用户表（已实现）

-- ==================== 详细 Schema（数据已迁移）====================
aia_schema (AI智能问答)
  ├── projects                 # ✅ 项目表
  ├── agents                   # ✅ 智能体配置表
  ├── conversations            # ✅ 对话表
  └── messages                 # ✅ 消息表

pkb_schema (个人知识库)
  ├── knowledge_bases          # ✅ 知识库表
  ├── documents                # ✅ 文档表
  ├── batch_tasks              # ✅ 批处理任务表
  ├── batch_results            # ✅ 批处理结果表
  └── task_templates           # ✅ 任务模板表

rvw_schema (稿件审查)
  ├── review_tasks             # ✅ 审查任务表
  └── (在public schema中)      # ⚠️ 历史原因

-- ==================== 占位 Schema（数据结构未定义）====================
asl_schema (AI智能文献)         # 🚧 Week 3开发
  └── (空，等待定义)

common_schema (通用工具)         # 📋 占位
dc_schema (数据采集)            # 📋 占位
ssa_schema (统计分析)           # 📋 占位
st_schema (研究工具)            # 📋 占位
admin_schema (运营管理)         # 📋 占位
```

**Prisma Schema 配置：**
```prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  schemas  = [
    "platform_schema",  # ✅ 平台
    "aia_schema",       # ✅ 智能问答
    "pkb_schema",       # ✅ 知识库
    "asl_schema",       # 🚧 智能文献（Week 3）
    "common_schema",    # 📋 占位
    "dc_schema",        # 📋 占位
    "rvw_schema",       # 📋 占位
    "admin_schema",     # 📋 占位
    "ssa_schema",       # 📋 占位
    "st_schema",        # 📋 占位
    "public"            # ✅ 历史遗留
  ]
}
```

---

### 🔌 API 真实路由（当前可用）

#### **AIA 模块（AI智能问答）**
```
基础路径：/api/v1/aia

项目管理：
  ✅ GET    /projects              # 获取项目列表
  ✅ POST   /projects              # 创建项目
  ✅ GET    /projects/:id          # 获取项目详情
  ✅ PUT    /projects/:id          # 更新项目
  ✅ DELETE /projects/:id          # 删除项目

智能体管理：
  ✅ GET    /agents                # 获取智能体列表
  ✅ GET    /agents/enabled        # 获取启用的智能体
  ✅ GET    /agents/:id            # 获取智能体详情

对话管理：
  ✅ POST   /conversations         # 创建对话
  ✅ GET    /conversations         # 获取对话列表
  ✅ GET    /conversations/:id     # 获取对话详情
  ✅ POST   /conversations/:id/messages/stream  # 流式发送消息
  ✅ POST   /conversations/:id/messages         # 非流式发送消息
  ✅ DELETE /conversations/:id     # 删除对话

通用对话：
  ✅ POST   /chat/stream           # 通用流式对话
  ✅ POST   /chat                  # 通用非流式对话
```

#### **PKB 模块（个人知识库）**
```
基础路径：/api/v1/pkb

知识库管理：
  ✅ GET    /knowledge-bases       # 获取知识库列表
  ✅ POST   /knowledge-bases       # 创建知识库
  ✅ GET    /knowledge-bases/:id   # 获取知识库详情
  ✅ PUT    /knowledge-bases/:id   # 更新知识库
  ✅ DELETE /knowledge-bases/:id   # 删除知识库

文档管理：
  ✅ POST   /knowledge-bases/:id/documents       # 上传文档
  ✅ GET    /knowledge-bases/:id/documents       # 获取文档列表
  ✅ DELETE /knowledge-bases/:kbId/documents/:docId  # 删除文档

批处理：
  ✅ POST   /batch/execute                       # 执行批处理任务
  ✅ GET    /batch/tasks/:taskId                 # 获取任务状态
  ✅ GET    /batch/tasks/:taskId/results         # 获取任务结果
  ✅ POST   /batch/tasks/:taskId/retry-failed    # 重试失败项
```

#### **RVW 模块（稿件审查）**
```
基础路径：/api/v1/rvw

稿件审查：
  ✅ POST   /review/upload         # 上传稿件并开始审查
  ✅ GET    /review/tasks/:taskId  # 查询任务状态
  ✅ GET    /review/tasks/:taskId/report  # 获取完整报告
  ✅ GET    /review/tasks          # 获取任务列表
  ✅ DELETE /review/tasks/:taskId  # 删除任务
```

#### **系统端点**
```
✅ GET  /health                    # 健康检查
✅ GET  /api/v1                    # API信息
```

---

### 📊 技术栈真实配置

#### **前端（Frontend-v2）**
```json
{
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "react-router-dom": "^6.x",
  "typescript": "^5.x",
  "vite": "^6.x",
  "antd": "^5.x",
  "tailwindcss": "^3.x"
}
```

#### **后端（Backend）**
```json
{
  "fastify": "^4.x",
  "typescript": "^5.x",
  "prisma": "^6.17.0",
  "@prisma/client": "^6.17.0",
  "tsx": "^4.x",
  "axios": "^1.x",
  "js-yaml": "^4.x",
  "p-queue": "^8.x"
}
```

#### **数据库**
```
PostgreSQL: 15.x
Schema数量: 10个（3详细 + 7占位）
迁移文件: 4个
```

#### **LLM 集成（CloseAI）**
```
✅ DeepSeek-V3      (主力，性价比)
✅ Qwen3-72B        (备用，中文理解)
✅ Qwen-Long        (超长上下文1M)
✅ GPT-4o           (可选，高质量)
```

---

### 🔄 前后端模块对应关系（当前）

| 前端模块 | 后端位置 | 数据库Schema | API路由 | 状态 |
|---------|---------|-------------|---------|------|
| frontend-v2/modules/asl/ | backend/modules/asl/ | asl_schema | /api/v1/asl/* | 🚧 Week 3开发 |
| frontend-v2/modules/aia/ | backend/legacy/routes/agents.ts等 | aia_schema | /api/v1/aia/* | ✅ 运行中 |
| frontend-v2/modules/pkb/ | backend/legacy/routes/knowledgeBases.ts等 | pkb_schema | /api/v1/pkb/* | ✅ 运行中 |
| frontend-v2/modules/rvw/ | backend/legacy/routes/reviewRoutes.ts | public + rvw_schema | /api/v1/rvw/* | ✅ 运行中 |
| frontend-v2/modules/dc/ | (未实现) | dc_schema | /api/v1/dc/* | 📋 占位 |
| frontend-v2/modules/ssa/ | (未实现) | ssa_schema | /api/v1/ssa/* | 📋 占位 |
| frontend-v2/modules/st/ | (未实现) | st_schema | /api/v1/st/* | 📋 占位 |

---

### 📋 功能测试清单（已验证）

| 功能 | 测试项 | 状态 | 备注 |
|------|--------|------|------|
| 智能问答 | 创建项目 | ✅ | |
| 智能问答 | 对话模式 | ✅ | 流式+非流式 |
| 智能问答 | 知识库模式 | ✅ | RAG检索 |
| 智能问答 | 批处理模式 | ✅ | 修复rawOutput问题后正常 |
| 知识库 | 创建知识库 | ✅ | |
| 知识库 | 上传文档 | ✅ | PDF/Word/TXT/MD |
| 知识库 | 文档管理 | ✅ | 列表/删除 |
| 稿件审查 | 上传稿件 | ✅ | |
| 稿件审查 | 审查报告 | ✅ | |
| 前端 | 顶部导航 | ✅ | 6个模块 |
| 前端 | 权限控制 | ✅ | mock premium |
| 前端 | 路由守卫 | ✅ | |
| 前端 | 错误边界 | ✅ | |

---

### 🎯 新模块开发指南（以ASL为例）

#### **开发流程（Week 3）：**

```
第1步：数据库设计
  ├─ 设计 asl_schema 表结构
  ├─ 在 Prisma schema 中定义模型
  └─ 运行迁移创建表

第2步：后端开发
  ├─ 在 backend/src/modules/asl/ 下开发
  ├─ 创建 routes/（路由）
  ├─ 创建 controllers/（控制器）
  ├─ 创建 services/（服务）
  └─ 注册路由到 index.ts

第3步：前端开发
  ├─ 在 frontend-v2/src/modules/asl/ 下开发
  ├─ 创建 pages/（页面）
  ├─ 创建 components/（组件）
  ├─ 创建 api/（API调用）
  └─ 更新 index.tsx（模块注册）

第4步：联调测试
  ├─ 前后端联调
  └─ 功能验收
```

---

### 📚 相关文档索引

**快速上手：**
- ⭐ **本文档** - 架构总纲 + 当前状态
- ⭐ `docs/09-架构实施/后端架构增量演进方案.md` - 后端详细说明（450行）

**任务记录：**
- `docs/08-项目管理/下一阶段行动计划-V2.2-完整版.md` - 项目计划
- `docs/09-架构实施/前端模块注册机制实施报告.md` - 前端任务17
- `docs/08-项目管理/2025-11-14-任务19完成总结.md` - 后端任务19

**技术规范：**
- `docs/09-架构实施/编码规范-UTF8最佳实践.md` - 编码规范
- `.editorconfig` - 编辑器配置
- `.gitattributes` - Git配置

---

**本章节更新日期：** 2025-11-14  
**下次更新时机：** ASL模块开发完成后

---

## ⚙️ 平台基础设施（2025-11-17 新增）✅

> **⭐ 重要提示：平台基础设施提供云原生的通用能力，所有业务模块直接复用**  
> **详细规划：** 参见 [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)  
> **使用指南：** 参见 [backend/src/common/README.md](../../backend/src/common/README.md)  
> **开发规范：** 参见 [云原生开发规范](../04-开发规范/08-云原生开发规范.md)

---

### 🎯 设计目标

**核心原则：** 通过**适配器模式（Adapter Pattern）**实现本地开发和云端部署零代码切换

```
┌─────────────────────────────────────────────────────────┐
│                   业务模块层                             │
│   ASL | AIA | PKB | DC | SSA | ST | UAM                │
│   只关注业务逻辑，复用平台能力                            │
└─────────────────────────────────────────────────────────┘
                    ↓ import from '@/common/'
┌─────────────────────────────────────────────────────────┐
│              平台基础设施层（Adapter Pattern）            │
├─────────────────────────────────────────────────────────┤
│ 存储：LocalAdapter ←→ OSSAdapter                        │
│ 缓存：MemoryCacheAdapter ←→ RedisCacheAdapter           │
│ 任务：MemoryQueueAdapter ←→ DatabaseQueueAdapter        │
│ 日志：ConsoleLogger ←→ 阿里云SLS                         │
│ 数据库：本地PostgreSQL ←→ 阿里云RDS（连接池）            │
└─────────────────────────────────────────────────────────┘
                    ↓ 环境变量切换
┌─────────────────────────────────────────────────────────┐
│         部署环境（零代码改动）                            │
│  本地开发 | 云端SaaS | 私有化部署 | 单机版               │
└─────────────────────────────────────────────────────────┘
```

---

### 📦 核心模块清单

| 模块 | 路径 | 状态 | 说明 | 环境切换 |
|------|------|------|------|---------|
| **存储服务** | `common/storage/` | ✅ 完成 | 文件上传下载 | `STORAGE_TYPE=local/oss` |
| **数据库连接池** | `config/database.ts` | ✅ 完成 | Prisma连接池 | `DATABASE_URL` |
| **日志系统** | `common/logging/` | ✅ 完成 | 结构化日志 | 自动切换（根据NODE_ENV） |
| **环境配置** | `config/env.ts` | ✅ 完成 | 统一配置管理 | `.env`文件或环境变量 |
| **异步任务** | `common/jobs/` | ✅ 完成 | 长时间任务处理 | `QUEUE_TYPE=memory/database` |
| **缓存服务** | `common/cache/` | ✅ 完成 | 内存/Redis缓存 | `CACHE_TYPE=memory/redis` |
| **健康检查** | `common/health/` | ✅ 完成 | SAE健康检查 | N/A |
| **监控指标** | `common/monitoring/` | ✅ 完成 | 关键指标监控 | N/A |

---

### 💻 使用示例

#### **1. 存储服务（零代码切换）**

```typescript
import { storage } from '@/common/storage'

// 业务代码（完全相同）
const buffer = await readFile('example.pdf')
const url = await storage.upload('literature/123.pdf', buffer)

// 环境切换：
// 本地开发：STORAGE_TYPE=local → 存储到 backend/uploads/
// 云端部署：STORAGE_TYPE=oss → 存储到阿里云OSS
```

#### **2. 日志系统（结构化日志）**

```typescript
import { logger } from '@/common/logging'

// 基础日志
logger.info('User logged in', { userId: 123 })
logger.error('Database error', { error: err.message })

// 带上下文的日志
const aslLogger = logger.child({ module: 'ASL', projectId: 456 })
aslLogger.info('Screening started', { count: 100 })

// 输出格式：
// 本地开发：彩色可读格式
// 生产环境：JSON格式（便于阿里云SLS解析）
```

#### **3. 异步任务（避免Serverless超时）**

```typescript
import { jobQueue } from '@/common/jobs'

// 创建任务（立即返回）
const job = await jobQueue.push('asl:screening', {
  projectId: 123,
  literatureIds: [1, 2, 3]
})

// 返回任务ID给前端
res.send({ jobId: job.id })

// 前端轮询任务状态
const status = await jobQueue.getJob(job.id)
// { status: 'processing', progress: 45 }
```

#### **4. 缓存服务（减少LLM调用成本）**

```typescript
import { cache } from '@/common/cache'

// 缓存LLM响应（1小时）
const cacheKey = `llm:${model}:${hash(prompt)}`
const cached = await cache.get(cacheKey)

if (!cached) {
  const response = await llm.chat(prompt)
  await cache.set(cacheKey, response, 60 * 60)
  return response
}

return cached
```

---

### 🌍 多环境配置

#### **本地开发（.env.development）**

```bash
# 存储：本地文件系统
STORAGE_TYPE=local
LOCAL_STORAGE_DIR=uploads

# 缓存：内存缓存
CACHE_TYPE=memory

# 任务队列：内存队列
QUEUE_TYPE=memory

# 日志：彩色输出
LOG_LEVEL=debug
```

#### **云端部署（.env.production）**

```bash
# 存储：阿里云OSS
STORAGE_TYPE=oss
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-prod
OSS_ACCESS_KEY_ID=your-key-id
OSS_ACCESS_KEY_SECRET=your-key-secret

# 缓存：阿里云Redis
CACHE_TYPE=redis
REDIS_HOST=r-xxx.redis.aliyuncs.com
REDIS_PORT=6379
REDIS_PASSWORD=your-password

# 任务队列：数据库队列
QUEUE_TYPE=database

# 日志：JSON输出
LOG_LEVEL=info
```

---

### ⚠️ 重要注意事项

#### **1. Winston依赖未安装**

```bash
# 需要安装
cd backend
npm install winston
npm install -D @types/winston
```

#### **2. Legacy模块兼容性**

- ✅ **Legacy模块**（PKB、AIA、DC）保持现状，正常运行
- ✅ **新模块**（ASL）使用平台基础设施
- 🔄 **可选迁移**：Legacy模块按需迁移（预计5小时）

#### **3. 云端实现预留**

- `OSSAdapter`、`RedisCacheAdapter` 当前为预留实现
- 云端部署前需安装依赖并取消注释
- 详见实施文档

---

### 📚 相关文档

- **详细规划：** [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)
- **使用指南：** [backend/src/common/README.md](../../backend/src/common/README.md)
- **实施报告：** [2025-11-17-平台基础设施实施完成报告](../08-项目管理/03-每周计划/2025-11-17-平台基础设施实施完成报告.md)
- **开发规范：** [云原生开发规范](../04-开发规范/08-云原生开发规范.md)

---

## 🌥️ 云原生部署架构（2025-11-16 新增）

> **⭐ 重要提示：本章节定义平台的云原生部署策略，适用于所有业务模块**  
> **详细指南：** 参见 [云原生部署架构指南](../09-架构实施/03-云原生部署架构指南.md)  
> **开发规范：** 参见 [云原生开发规范](../04-开发规范/08-云原生开发规范.md)

---

### 🎯 部署架构选型

**目标平台**：阿里云 Serverless 应用引擎 (SAE) + 云数据库 RDS + 对象存储 OSS

**选型理由**：
- ✅ **按需付费**：初期成本低（¥500/月起），无需预付大量服务器成本
- ✅ **自动扩缩容**：高峰期不宕机，低谷期不浪费，适合创业公司流量不确定的场景
- ✅ **国内访问优化**：阿里云国内节点多，医疗用户访问速度快
- ✅ **适合AI任务**：异步批量任务（LLM筛选、PDF提取）天然契合 Serverless
- ✅ **降低运维成本**：无需专职运维人员，团队专注业务开发

**架构图**：
```
┌──────────────────────────────────────────────────┐
│              云原生部署架构                         │
├──────────────────────────────────────────────────┤
│  用户浏览器                                        │
│     ↓                                            │
│  CDN加速（可选）                                   │
│     ↓                                            │
│  阿里云 SAE (Serverless 应用引擎)                 │
│  ├── 自动扩缩容（0-100实例）                      │
│  ├── 内置负载均衡                                 │
│  └── Docker 容器运行                             │
│     ↓                                            │
│  云数据库 RDS (PostgreSQL 15)                    │
│  ├── 10个Schema隔离                              │
│  ├── 自动备份                                     │
│  └── 连接池管理                                   │
│     ↓                                            │
│  对象存储 OSS                                     │
│  ├── PDF/Excel 文件存储                          │
│  ├── 11个9可靠性                                 │
│  └── 内网访问免流量费                             │
└──────────────────────────────────────────────────┘
```

---

### 🏗️ 核心设计原则（所有模块必须遵守）

#### **原则1：无状态应用设计**

**要求**：应用不能依赖本地文件系统或内存状态

| 禁止做法 ❌ | 正确做法 ✅ | 说明 |
|-----------|-----------|------|
| 文件存储到 `./uploads/` | 上传到 OSS 或 内存处理 | 容器重启会丢失本地文件 |
| Session 存内存 | Session 存 Redis/数据库 | 多实例间无法共享内存 |
| 缓存存内存变量 | 使用 Redis | 扩容后缓存失效 |
| 依赖 `/tmp` 长期存储 | 用完立即删除 | /tmp 容量有限且不持久 |

**示例**：
```typescript
// ❌ 禁止：本地文件存储
fs.writeFileSync('./uploads/file.pdf', buffer)

// ✅ 正确：OSS存储或内存处理
const storage = StorageFactory.create()
const url = await storage.upload('files/file.pdf', buffer)
```

---

#### **原则2：存储抽象层设计**

**要求**：通过抽象层支持本地开发 + 云端部署无缝切换

**架构**：
```typescript
StorageFactory
    ↓
StorageAdapter (接口)
    ↓
├── LocalAdapter (本地开发)
└── OSSAdapter (生产环境)
```

**使用**：
```typescript
// 代码中统一使用工厂类，环境自动切换
const storage = StorageFactory.create()
const url = await storage.upload(key, buffer)
```

**环境配置**：
```bash
# 本地开发
STORAGE_TYPE=local

# 生产环境
STORAGE_TYPE=oss
```

---

#### **原则3：数据库连接池管理**

**风险**：Serverless 扩容后连接数暴增，超过 RDS 最大连接数

**解决方案**：
```typescript
// 计算公式：每实例连接数 = RDS最大连接数 / SAE最大实例数
// 示例：RDS 400连接 / SAE 20实例 = 每实例20连接

const prisma = new PrismaClient({
  connectionPool: {
    connectionLimit: 20,      // 每实例最多20连接
    idleTimeout: 60000,       // 空闲60秒释放
    maxWait: 5000,            // 等待最多5秒
  }
})
```

**监控**：定期检查数据库连接数，接近上限时告警

---

#### **原则4：环境变量配置**

**要求**：所有配置（密钥、IP、端口）必须通过环境变量管理

```bash
# ❌ 禁止硬编码
const apiKey = 'sk-xxx'
const dbHost = '192.168.1.100'

# ✅ 环境变量
const apiKey = process.env.LLM_API_KEY
const dbHost = process.env.DB_HOST
```

---

#### **原则5：异步任务处理**

**风险**：SAE 默认请求超时 30 秒

**解决方案**：长时间任务（> 10秒）必须异步处理

```typescript
// ✅ 正确：异步任务模式
app.post('/screening/start', async (req, res) => {
  const task = await prisma.aslScreeningTask.create({...})
  res.send({ taskId: task.id })  // 立即返回
  
  // 后台执行
  processScreeningAsync(task.id)
})

// 前端轮询进度
app.get('/screening/tasks/:id', async (req, res) => {
  const task = await prisma.aslScreeningTask.findUnique({...})
  res.send({ progress: task.completedItems / task.totalItems })
})
```

---

### 📊 开发环境 vs 生产环境

#### **本地开发环境（无需云服务）**

```bash
# 使用 Docker 本地服务
docker run -d --name postgres -p 5432:5432 postgres:15
docker run -d --name redis -p 6379:6379 redis:7

# 环境变量
STORAGE_TYPE=local
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/dev_db
```

**优势**：
- ✅ 完全离线开发
- ✅ 无云服务费用
- ✅ 调试方便

---

#### **生产环境（阿里云）**

```bash
# SAE 控制台配置环境变量
STORAGE_TYPE=oss
DATABASE_URL=postgresql://user:pass@rm-xxx.aliyuncs.com:5432/prod_db
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-prod
```

**切换方式**：
- ✅ 代码零改动
- ✅ 仅修改环境变量
- ✅ 重新部署即可

---

### 🚀 部署流程（简要）

1. **本地开发**：使用 Docker + LocalAdapter
2. **代码提交**：Git push
3. **构建镜像**：Docker build
4. **推送镜像**：推送到阿里云容器镜像服务
5. **SAE 部署**：配置环境变量，自动拉取镜像部署
6. **验证部署**：健康检查通过，流量切换

详细流程见：[云原生部署架构指南](../09-架构实施/03-云原生部署架构指南.md)

---

### 📋 开发检查清单

在提交代码前，请确认：

- [ ] 是否使用 `StorageFactory` 而非直接 `fs.writeFile`？
- [ ] 是否使用全局 `prisma` 实例而非新建连接？
- [ ] 是否所有配置都从环境变量读取？
- [ ] 是否长时间任务都改为异步处理？
- [ ] 是否日志都输出到 stdout？
- [ ] 是否 `/tmp` 目录使用后立即清理？
- [ ] 是否避免依赖本地文件路径？

完整检查清单见：[云原生开发规范](../04-开发规范/08-云原生开发规范.md)

---

### 📚 相关文档

- ⭐ **[云原生部署架构指南](../09-架构实施/03-云原生部署架构指南.md)** - 包含完整代码示例和部署流程
- ⭐ **[云原生开发规范](../04-开发规范/08-云原生开发规范.md)** - DO/DON'T 检查清单
- [Schema隔离架构设计](../09-架构实施/01-Schema隔离架构设计（10个）.md)
- [数据库连接配置](../09-架构实施/02-数据库连接配置.md)

---

**本章节创建日期：** 2025-11-16  
**维护者：** 架构团队  
**适用范围：** 所有业务模块（ASL、AIA、PKB、DC等）

---

## 🏗️ 整体架构设计

### 系统架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                         AI临床研究平台                            │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┴─────────────────────┐
        │                                           │
   ┌────▼─────┐                              ┌─────▼────┐
   │  前端层   │                              │  后端层   │
   │frontend-v2│◄────────── HTTP API ────────►│ backend  │
   └──────────┘                              └──────────┘
        │                                           │
        │ 模块化                                    │ 模块化 + Schema隔离
        │                                           │
   ┌────┴────────────────────────┐         ┌───────┴──────────────────┐
   │                             │         │                          │
   │  ┌─────┐  ┌─────┐  ┌─────┐ │         │  ┌─────────────────────┐ │
   │  │ ASL │  │ AIA │  │ PKB │ │         │  │ PostgreSQL          │ │
   │  │模块 │  │模块 │  │模块 │ │         │  │  ┌─────────────────┐│ │
   │  └─────┘  └─────┘  └─────┘ │         │  │  │ platform_schema ││ │
   │  ┌─────┐  ┌─────┐          │         │  │  │ aia_schema      ││ │
   │  │ RVW │  │ DC  │  ...     │         │  │  │ pkb_schema      ││ │
   │  │模块 │  │模块 │          │         │  │  │ asl_schema      ││ │
   │  └─────┘  └─────┘          │         │  │  │ ...             ││ │
   │                             │         │  │  └─────────────────┘│ │
   └─────────────────────────────┘         │  └─────────────────────┘ │
                                           └──────────────────────────┘
```

---

## 📁 前端架构设计（frontend-v2）

### 设计原则

1. **彻底的模块化** - 每个业务模块完全独立
2. **框架与业务分离** - 框架层提供基础能力，业务模块专注功能
3. **渐进式开发** - 新架构与旧代码并存，逐步替换
4. **独立部署支持** - 模块可独立打包和部署

### 目录结构

```
frontend-v2/
├── src/
│   ├── framework/                      # 🏗️ 框架层（平台级基础设施）
│   │   │
│   │   ├── layout/                     # 布局系统
│   │   │   ├── MainLayout.tsx          # 主布局（顶部导航+内容区）
│   │   │   ├── TopNavigation.tsx       # 顶部导航栏
│   │   │   ├── UserMenu.tsx            # 用户菜单
│   │   │   └── ModuleContainer.tsx     # 模块容器
│   │   │
│   │   ├── modules/                    # 模块管理系统
│   │   │   ├── moduleRegistry.ts       # 模块注册中心
│   │   │   ├── ModuleLoader.tsx        # 动态模块加载器
│   │   │   ├── types.ts                # 模块接口定义
│   │   │   └── config.ts               # 模块配置
│   │   │
│   │   ├── router/                     # 路由系统
│   │   │   ├── AppRouter.tsx           # 应用路由配置
│   │   │   ├── RouteGuard.tsx          # 路由守卫
│   │   │   └── routes.ts               # 路由定义
│   │   │
│   │   ├── permission/                 # 权限控制（预留）
│   │   │   ├── PermissionProvider.tsx  # 权限上下文
│   │   │   ├── usePermission.ts        # 权限Hook
│   │   │   └── config.ts               # 权限配置
│   │   │
│   │   └── config/                     # 全局配置
│   │       ├── env.ts                  # 环境变量
│   │       ├── api.ts                  # API配置
│   │       └── theme.ts                # 主题配置
│   │
│   ├── modules/                        # 📦 业务模块（完全独立）
│   │   │
│   │   ├── asl/                        # ⭐ AI智能文献模块（优先开发）
│   │   │   ├── index.tsx               # 模块入口（导出ModuleDefinition）
│   │   │   ├── routes.tsx              # 模块路由配置
│   │   │   │
│   │   │   ├── layouts/                # 模块布局
│   │   │   │   └── ASLLayout.tsx       # ASL左侧导航布局
│   │   │   │
│   │   │   ├── pages/                  # 模块页面
│   │   │   │   ├── ProjectList.tsx            # 项目列表
│   │   │   │   ├── ProjectCreate.tsx          # 创建项目
│   │   │   │   ├── TitleScreening/            # 标题摘要初筛
│   │   │   │   │   ├── index.tsx
│   │   │   │   │   ├── ScreeningWorkbench.tsx
│   │   │   │   │   └── ResultsView.tsx
│   │   │   │   ├── FullTextScreening/         # 全文复筛
│   │   │   │   │   └── ...
│   │   │   │   ├── DataExtraction/            # 数据提取
│   │   │   │   │   └── ...
│   │   │   │   └── Analysis/                  # 综合分析
│   │   │   │       └── ...
│   │   │   │
│   │   │   ├── components/             # 模块组件（仅本模块使用）
│   │   │   │   ├── LiteratureCard.tsx
│   │   │   │   ├── ScreeningPanel.tsx
│   │   │   │   ├── LLMSelector.tsx
│   │   │   │   └── ...
│   │   │   │
│   │   │   ├── api/                    # 模块API（对接后端）
│   │   │   │   ├── projectApi.ts
│   │   │   │   ├── screeningApi.ts
│   │   │   │   ├── extractionApi.ts
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   ├── hooks/                  # 模块Hooks
│   │   │   │   ├── useProject.ts
│   │   │   │   ├── useScreening.ts
│   │   │   │   └── useLLMScreening.ts
│   │   │   │
│   │   │   ├── store/                  # 模块状态管理
│   │   │   │   ├── projectStore.ts
│   │   │   │   ├── screeningStore.ts
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   ├── types/                  # 模块类型定义
│   │   │   │   ├── project.ts
│   │   │   │   ├── literature.ts
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   └── utils/                  # 模块工具函数
│   │   │       ├── fileParser.ts
│   │   │       └── exportHelper.ts
│   │   │
│   │   ├── aia/                        # 📋 AI智能问答模块（后续重写）
│   │   │   ├── index.tsx
│   │   │   └── Placeholder.tsx         # 临时占位页面
│   │   │
│   │   ├── pkb/                        # 📋 个人知识库模块（后续重写）
│   │   │   ├── index.tsx
│   │   │   └── Placeholder.tsx
│   │   │
│   │   ├── rvw/                        # 📋 审稿系统模块（后续重写）
│   │   │   ├── index.tsx
│   │   │   └── Placeholder.tsx
│   │   │
│   │   └── dc/                         # 📋 数据清洗模块（占位）
│   │       ├── index.tsx
│   │       └── Placeholder.tsx
│   │
│   ├── shared/                         # 🔧 共享资源（跨模块使用）
│   │   ├── components/                 # 通用UI组件
│   │   │   ├── Button/
│   │   │   ├── Table/
│   │   │   ├── Modal/
│   │   │   └── ...
│   │   │
│   │   ├── hooks/                      # 通用Hooks
│   │   │   ├── useDebounce.ts
│   │   │   ├── useAsync.ts
│   │   │   └── ...
│   │   │
│   │   ├── utils/                      # 工具函数
│   │   │   ├── date.ts
│   │   │   ├── format.ts
│   │   │   ├── validation.ts
│   │   │   └── ...
│   │   │
│   │   └── api/                        # API客户端
│   │       ├── client.ts               # Axios实例
│   │       ├── request.ts              # 请求拦截器
│   │       └── types.ts                # API类型
│   │
│   ├── App.tsx                         # 应用根组件
│   ├── main.tsx                        # 应用入口
│   └── vite-env.d.ts
│
├── public/                             # 静态资源
├── package.json
├── vite.config.ts                      # Vite配置
├── tsconfig.json                       # TypeScript配置
├── tailwind.config.js                  # Tailwind配置
└── README.md
```

### 模块定义接口

```typescript
// framework/modules/types.ts

/**
 * 模块定义接口
 * 每个业务模块必须实现这个接口
 */
export interface ModuleDefinition {
  /** 模块唯一标识 */
  id: string
  
  /** 模块名称（显示在导航栏） */
  name: string
  
  /** 模块路由前缀 */
  path: string
  
  /** 模块图标（可选） */
  icon?: ReactNode
  
  /** 模块入口组件（懒加载） */
  component: LazyExoticComponent<ComponentType<any>>
  
  /** 模块路由配置 */
  routes?: RouteObject[]
  
  /** 模块是否有左侧导航 */
  hasSideNav?: boolean
  
  /** 左侧导航配置（如果有） */
  sideNavConfig?: SideNavItem[]
  
  /** 权限要求（可选） */
  requiredVersion?: UserVersion
  
  /** 是否为占位模块 */
  placeholder?: boolean
  
  /** 是否支持独立部署 */
  standalone?: boolean
}

/**
 * 左侧导航项
 */
export interface SideNavItem {
  id: string
  label: string
  path: string
  icon?: ReactNode
  children?: SideNavItem[]
}
```

### 模块注册示例

```typescript
// modules/asl/index.tsx

import { lazy } from 'react'
import { ModuleDefinition } from '@/framework/modules/types'
import routes from './routes'
import { sideNavConfig } from './config'

const ASLModule: ModuleDefinition = {
  id: 'asl',
  name: 'AI智能文献',
  path: '/literature',
  icon: <FileTextOutlined />,
  component: lazy(() => import('./layouts/ASLLayout')),
  routes,
  hasSideNav: true,
  sideNavConfig,
  requiredVersion: 'advanced',
}

export default ASLModule
```

### 模块路由示例

```typescript
// modules/asl/routes.tsx

import { lazy } from 'react'
import { RouteObject } from 'react-router-dom'

const routes: RouteObject[] = [
  {
    path: '',
    element: lazy(() => import('./pages/ProjectList')),
  },
  {
    path: 'project/:projectId',
    children: [
      {
        path: 'title-screening',
        element: lazy(() => import('./pages/TitleScreening')),
      },
      {
        path: 'fulltext-screening',
        element: lazy(() => import('./pages/FullTextScreening')),
      },
      {
        path: 'extraction',
        element: lazy(() => import('./pages/DataExtraction')),
      },
      {
        path: 'analysis',
        element: lazy(() => import('./pages/Analysis')),
      },
    ],
  },
]

export default routes
```

---

## 📁 后端架构设计（backend）

### 设计原则

1. **Schema隔离** - 数据库层面的模块隔离（已完成）
2. **代码分层** - platform/common/modules三层架构
3. **模块独立** - 每个模块的API和逻辑独立
4. **保持兼容** - 轻度重构，不破坏现有功能

### 目录结构

```
backend/
├── src/
│   ├── platform/                       # 🏛️ 平台层（基础设施）
│   │   ├── auth/                       # 认证授权
│   │   │   ├── authController.ts
│   │   │   ├── authService.ts
│   │   │   ├── authMiddleware.ts
│   │   │   └── routes.ts
│   │   │
│   │   └── users/                      # 用户管理
│   │       ├── userController.ts
│   │       ├── userService.ts
│   │       └── routes.ts
│   │
│   ├── common/                         # 🔧 通用层（共享能力）
│   │   ├── middleware/                 # 中间件
│   │   │   ├── errorHandler.ts
│   │   │   ├── logger.ts
│   │   │   ├── validation.ts
│   │   │   └── cors.ts
│   │   │
│   │   ├── utils/                      # 工具函数
│   │   │   ├── date.ts
│   │   │   ├── encryption.ts
│   │   │   └── format.ts
│   │   │
│   │   ├── errors/                     # 错误处理
│   │   │   ├── AppError.ts
│   │   │   ├── errorTypes.ts
│   │   │   └── errorHandler.ts
│   │   │
│   │   └── types/                      # 通用类型
│   │       ├── request.ts
│   │       ├── response.ts
│   │       └── common.ts
│   │
│   ├── modules/                        # 📦 业务模块
│   │   │
│   │   ├── aia/                        # AI智能问答模块
│   │   │   ├── controllers/            # 控制器
│   │   │   │   ├── projectController.ts
│   │   │   │   ├── agentController.ts
│   │   │   │   ├── conversationController.ts
│   │   │   │   └── chatController.ts
│   │   │   │
│   │   │   ├── services/               # 业务逻辑
│   │   │   │   ├── projectService.ts
│   │   │   │   ├── conversationService.ts
│   │   │   │   └── llmService.ts
│   │   │   │
│   │   │   ├── routes/                 # 路由配置
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   ├── types/                  # 模块类型
│   │   │   │   ├── project.ts
│   │   │   │   └── conversation.ts
│   │   │   │
│   │   │   └── utils/                  # 模块工具
│   │   │       └── prompt.ts
│   │   │
│   │   ├── pkb/                        # 个人知识库模块
│   │   │   ├── controllers/
│   │   │   │   ├── knowledgeBaseController.ts
│   │   │   │   ├── documentController.ts
│   │   │   │   └── batchController.ts
│   │   │   │
│   │   │   ├── services/
│   │   │   │   ├── kbService.ts
│   │   │   │   ├── documentService.ts
│   │   │   │   ├── batchService.ts
│   │   │   │   └── difyService.ts
│   │   │   │
│   │   │   ├── routes/
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   └── types/
│   │   │       ├── knowledgeBase.ts
│   │   │       └── document.ts
│   │   │
│   │   ├── rvw/                        # 审稿系统模块
│   │   │   ├── controllers/
│   │   │   │   └── reviewController.ts
│   │   │   │
│   │   │   ├── services/
│   │   │   │   ├── reviewService.ts
│   │   │   │   └── extractionService.ts
│   │   │   │
│   │   │   ├── routes/
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   └── types/
│   │   │       └── review.ts
│   │   │
│   │   └── asl/                        # ⭐ AI智能文献模块（Week 3新建）
│   │       ├── controllers/
│   │       │   ├── projectController.ts
│   │       │   ├── literatureController.ts
│   │       │   ├── screeningController.ts
│   │       │   └── extractionController.ts
│   │       │
│   │       ├── services/
│   │       │   ├── projectService.ts
│   │       │   ├── literatureService.ts
│   │       │   ├── screeningService.ts
│   │       │   ├── llmScreeningService.ts
│   │       │   └── extractionService.ts
│   │       │
│   │       ├── routes/
│   │       │   └── index.ts
│   │       │
│   │       ├── types/
│   │       │   ├── project.ts
│   │       │   ├── literature.ts
│   │       │   └── screening.ts
│   │       │
│   │       └── utils/
│   │           ├── fileParser.ts
│   │           ├── llmPrompts.ts
│   │           └── exportHelper.ts
│   │
│   ├── config/                         # 配置文件（现有）
│   │   ├── database.ts
│   │   ├── env.ts
│   │   └── ...
│   │
│   └── index.ts                        # 应用入口
│
├── prisma/
│   └── schema.prisma                   # Prisma Schema（已配置10个Schema）
│
├── package.json
└── tsconfig.json
```

### 模块路由注册

```typescript
// src/index.ts

import { platformRoutes } from './platform/routes'
import { aiaRoutes } from './modules/aia/routes'
import { pkbRoutes } from './modules/pkb/routes'
import { rvwRoutes } from './modules/rvw/routes'
import { aslRoutes } from './modules/asl/routes'

// 注册平台路由
fastify.register(platformRoutes, { prefix: '/api/v1/platform' })

// 注册业务模块路由
fastify.register(aiaRoutes, { prefix: '/api/v1/aia' })
fastify.register(pkbRoutes, { prefix: '/api/v1/pkb' })
fastify.register(rvwRoutes, { prefix: '/api/v1/rvw' })
fastify.register(aslRoutes, { prefix: '/api/v1/asl' })
```

---

## 🔗 前后端对应关系

### 模块映射表

| 前端模块 | 后端模块 | 数据库Schema | 路由前缀 | 开发状态 |
|---------|---------|-------------|---------|---------|
| `frontend-v2/src/modules/asl/` | `backend/src/modules/asl/` | `asl_schema` | `/api/v1/asl/*` | 🚧 Week 3开发 |
| `frontend-v2/src/modules/aia/` | `backend/src/modules/aia/` | `aia_schema` | `/api/v1/aia/*` | 📋 后续重写 |
| `frontend-v2/src/modules/pkb/` | `backend/src/modules/pkb/` | `pkb_schema` | `/api/v1/pkb/*` | 📋 后续重写 |
| `frontend-v2/src/modules/rvw/` | `backend/src/modules/rvw/` | `public.review_tasks` | `/api/v1/rvw/*` | 📋 后续重写 |
| `frontend-v2/src/modules/dc/` | `backend/src/modules/dc/` | `dc_schema` | `/api/v1/dc/*` | 📋 占位 |

### API调用示例

```typescript
// 前端：frontend-v2/src/modules/asl/api/projectApi.ts
import { apiClient } from '@/shared/api/client'

export const aslProjectApi = {
  // 创建项目
  create: (data: CreateProjectDTO) => 
    apiClient.post('/api/v1/asl/projects', data),
  
  // 获取项目列表
  list: () => 
    apiClient.get('/api/v1/asl/projects'),
  
  // 获取项目详情
  getById: (id: string) => 
    apiClient.get(`/api/v1/asl/projects/${id}`),
}

// 后端：backend/src/modules/asl/routes/index.ts
import { FastifyInstance } from 'fastify'
import { aslProjectController } from '../controllers/projectController'

export async function aslRoutes(fastify: FastifyInstance) {
  fastify.post('/projects', aslProjectController.create)
  fastify.get('/projects', aslProjectController.list)
  fastify.get('/projects/:id', aslProjectController.getById)
}
```

---

## 📐 开发规范

### 命名规范

#### 前端

**文件命名：**
- 组件：PascalCase（`ProjectList.tsx`）
- Hooks：camelCase + use前缀（`useProject.ts`）
- 工具函数：camelCase（`formatDate.ts`）
- 类型定义：PascalCase（`Project.ts`）

**代码命名：**
- 组件：PascalCase（`ProjectList`）
- 函数：camelCase（`fetchProjects`）
- 常量：UPPER_SNAKE_CASE（`API_BASE_URL`）
- 接口：PascalCase + I前缀（`IProject`）
- 类型：PascalCase（`Project`）

#### 后端

**文件命名：**
- Controller：camelCase + Controller后缀（`projectController.ts`）
- Service：camelCase + Service后缀（`projectService.ts`）
- Routes：`index.ts` 或 `routes.ts`
- Types：camelCase（`project.ts`）

**代码命名：**
- 类：PascalCase（`ProjectService`）
- 函数：camelCase（`createProject`）
- 常量：UPPER_SNAKE_CASE（`MAX_FILE_SIZE`）
- 接口：PascalCase（`ProjectDTO`）

### 模块开发规范

#### 1. 新模块开发流程

```
第一步：数据库设计
├─ 在 docs/03-业务模块/[模块名]/02-技术设计/01-数据库设计.md
├─ 设计表结构
├─ 在 Prisma schema 中定义模型
└─ 运行迁移

第二步：后端开发
├─ 创建 backend/src/modules/[模块名]/
├─ 编写 controllers/
├─ 编写 services/
├─ 编写 routes/
└─ 测试 API

第三步：前端开发
├─ 创建 frontend-v2/src/modules/[模块名]/
├─ 定义模块接口（index.tsx）
├─ 编写 pages/
├─ 编写 components/
├─ 编写 api/
├─ 编写 hooks/
└─ 测试功能

第四步：集成测试
├─ 端到端测试
└─ 性能测试
```

#### 2. 模块独立性原则

**DO ✅：**
- 模块内的组件只在模块内使用
- 模块有自己的状态管理
- 模块有自己的API调用
- 模块有自己的类型定义
- 模块可以独立运行和部署

**DON'T ❌：**
- 不要在模块间直接import组件
- 不要在模块间共享状态
- 不要在模块间直接调用API
- 共享的逻辑放在 `shared/` 目录

#### 3. API设计规范

**RESTful风格：**
```
GET    /api/v1/[module]/resources       # 列表
GET    /api/v1/[module]/resources/:id   # 详情
POST   /api/v1/[module]/resources       # 创建
PUT    /api/v1/[module]/resources/:id   # 更新
DELETE /api/v1/[module]/resources/:id   # 删除
```

**响应格式：**
```typescript
// 成功响应
{
  success: true,
  data: any,
  message?: string
}

// 错误响应
{
  success: false,
  error: {
    code: string,
    message: string,
    details?: any
  }
}
```

---

## 🚀 实施计划

### Week 2：架构改造（2025-11-13 至 2025-11-17）

#### Day 6（11-13）：前端架构基础 ⏰ 4-6小时

**上午：项目创建和框架层**
- [x] 创建 frontend-v2 项目（Vite + React + TS）
- [x] 安装依赖（Antd、Router、Zustand、React Query）
- [x] 配置 Tailwind CSS
- [x] 创建目录结构（framework/modules/shared）
- [x] 实现 TopNavigation.tsx
- [x] 实现 MainLayout.tsx
- [x] 定义模块接口（ModuleDefinition）

**下午：模块占位**
- [x] 为5个模块创建目录
- [x] 创建 Placeholder.tsx 组件
- [x] 配置基本路由
- [x] 测试导航切换

**交付物：**
- ✅ 可运行的 frontend-v2 项目
- ✅ 顶部导航正常工作
- ✅ 5个模块占位页面

#### Day 7（11-14）：模块注册机制 ⏰ 6-8小时

**上午：注册系统**
- [ ] 实现 moduleRegistry.ts
- [ ] 实现 ModuleLoader.tsx
- [ ] 实现动态路由加载
- [ ] 实现懒加载机制

**下午：测试和文档**
- [ ] 测试模块注册
- [ ] 测试路由切换
- [ ] 编写开发文档
- [ ] 更新 README

**交付物：**
- ✅ 完整的模块注册系统
- ✅ 动态路由加载
- ✅ 开发文档

#### Day 8-9（11-15 至 11-16）：后端代码分层 ⏰ 1-2天

**Day 8 上午：创建目录结构**
- [ ] 创建 platform/ 目录
- [ ] 创建 common/ 目录
- [ ] 创建 modules/ 目录

**Day 8 下午：迁移 AIA 模块**
- [ ] 创建 modules/aia/ 结构
- [ ] 迁移 projectController.ts
- [ ] 迁移 conversationController.ts
- [ ] 更新路由注册

**Day 9 上午：迁移 PKB 和 RVW**
- [ ] 迁移 PKB 模块代码
- [ ] 迁移 RVW 模块代码
- [ ] 更新所有 import 路径

**Day 9 下午：测试和文档**
- [ ] 测试所有 API
- [ ] 更新 API 文档
- [ ] 编写迁移说明

**交付物：**
- ✅ 完成后端代码分层
- ✅ 所有API正常工作
- ✅ 更新文档

#### Day 10（11-17）：Week 2 验收 ⏰ 4小时

- [ ] 前端架构验收
- [ ] 后端分层验收
- [ ] 集成测试
- [ ] 编写 Week 2 总结报告
- [ ] 规划 Week 3 ASL 任务

---

### Week 3-4：ASL模块开发（在新架构下）

**在全新的 frontend-v2 和分层后的 backend 中开发 ASL 模块**

详见：[下一阶段行动计划-V2.2-完整版.md](../08-项目管理/下一阶段行动计划-V2.2-完整版.md)

---

## 📝 旧代码处理

### frontend/ 目录

**状态：** ⏸️ 保留，不再开发

**处理方式：**
1. 添加 `README-ARCHIVED.md` 说明文件
2. 在根目录 `package.json` 中区分启动命令
3. 保留3-6个月，作为参考和应急备份
4. 新架构稳定后再删除

**参考价值：**
- UI交互设计
- 某些组件实现
- API调用逻辑
- 业务流程

### 启动命令

```json
{
  "scripts": {
    "dev:frontend-old": "cd frontend && npm run dev",
    "dev:frontend-new": "cd frontend-v2 && npm run dev",
    "dev:frontend": "npm run dev:frontend-new",
    "dev:backend": "cd backend && npm run dev",
    "dev": "concurrently \"npm run dev:backend\" \"npm run dev:frontend\""
  }
}
```

---

## 🎯 成功标准

### Week 2 验收标准

**前端：**
- [x] frontend-v2 项目可运行
- [x] 顶部导航正常工作
- [x] 模块注册系统完整
- [x] 5个模块占位页面
- [x] 路由切换正常
- [x] 完整的开发文档

**后端：**
- [ ] 代码分层完成（platform/common/modules）
- [ ] 所有现有API正常工作
- [ ] 路由前缀统一（/api/v1/[module]/*）
- [ ] import路径全部更新
- [ ] API文档更新

**文档：**
- [x] 本架构设计文档
- [ ] 前端开发规范文档
- [ ] 后端开发规范文档
- [ ] Week 2总结报告

---

## 📚 相关文档

### 架构设计
- [Schema隔离架构设计（10个）](../09-架构实施/01-Schema隔离架构设计（10个）.md)
- [前端总体架构设计](../01-平台基础层/06-前端架构/01-前端总体架构设计.md)
- [导航结构设计](../01-平台基础层/06-前端架构/02-导航结构设计.md)

### 数据库设计
- [AIA数据库设计](../03-业务模块/AIA-AI智能问答/02-技术设计/01-数据库设计.md)
- [PKB数据库设计](../03-业务模块/PKB-个人知识库/02-技术设计/01-数据库设计.md)

### 实施报告
- [Schema迁移完成报告](../09-架构实施/Schema迁移完成报告.md)
- [Prisma配置完成报告](../09-架构实施/Prisma配置完成报告.md)

### 项目管理
- [下一阶段行动计划-V2.2-完整版](../08-项目管理/下一阶段行动计划-V2.2-完整版.md)

---

## 🔄 版本历史

| 版本 | 日期 | 变更内容 | 维护者 |
|------|------|---------|--------|
| V2.0 | 2025-11-12 | 创建本文档，定义前后端模块化架构 | AI助手 |
| V2.1 | 2025-11-13 | 完成权限系统、错误边界、路由守卫实施 | AI助手 |

---

**文档维护者：** AI助手 + 开发团队  
**最后更新：** 2025-11-13  
**文档状态：** ✅ 已完成，Week 2 Day 7实施完成  

**🎉 这是系统架构演进的重要里程碑！**