AIclinicalresearch/docs/09-架构实施/后端代码分层-迁移计划.md

# 后端代码分层 - 详细迁移计划

> **文档版本：** v1.0  
> **创建日期：** 2025-11-13  
> **任务编号：** 任务19（Week 2 Day 8-9）  
> **目标：** 将现有扁平化后端代码重组为 platform/common/modules 三层架构

---

## 📋 总体目标

### 设计原则
1. ✅ **稳妥第一** - 一步一步迁移，每步验证
2. ✅ **只做重组** - 不增加新功能，不修改业务逻辑
3. ✅ **保持兼容** - API路径不变，功能不变
4. ✅ **可回退** - Git commit记录每一步，可随时回退

### 目标架构
```
backend/src/
├── platform/          # 🏛️ 平台层（本次只创建目录，暂不实现）
│   ├── auth/
│   └── users/
│
├── common/            # 🔧 通用能力层
│   ├── llm/           # LLM适配器和Gateway
│   ├── document/      # 文档处理客户端
│   ├── rag/           # RAG/Dify客户端
│   ├── middleware/    # 中间件
│   ├── utils/         # 工具函数
│   └── types/         # 通用类型
│
├── modules/           # 📦 业务模块层
│   ├── aia/           # AI智能问答模块
│   ├── pkb/           # 个人知识库模块
│   └── rvw/           # 稿件审查模块
│
├── config/            # 配置（保留）
└── index.ts           # 主入口（重写）
```

---

## 📊 现有代码清单

### 1. adapters/ - LLM适配器（4个文件）
- ✅ `DeepSeekAdapter.ts` - DeepSeek-V3适配器
- ✅ `QwenAdapter.ts` - Qwen3/Qwen-Long适配器
- ✅ `LLMFactory.ts` - LLM工厂类
- ✅ `types.ts` - 适配器接口定义

### 2. clients/ - 外部服务客户端（3个文件）
- ✅ `DifyClient.ts` - Dify RAG客户端
- ✅ `ExtractionClient.ts` - Python文档提取服务客户端
- ✅ `types.ts` - 客户端类型定义

### 3. controllers/ - 控制器（8个文件）
- ✅ `projectController.ts` - 项目管理
- ✅ `agentController.ts` - 智能体管理
- ✅ `conversationController.ts` - 对话管理
- ✅ `chatController.ts` - 通用对话
- ✅ `knowledgeBaseController.ts` - 知识库管理
- ✅ `documentController.ts` - 文档管理
- ✅ `batchController.ts` - 批处理
- ✅ `reviewController.ts` - 稿件审查

### 4. services/ - 服务（8个文件）
- ✅ `projectService.ts` - 项目服务
- ✅ `agentService.ts` - 智能体服务
- ✅ `conversationService.ts` - 对话服务
- ✅ `knowledgeBaseService.ts` - 知识库服务
- ✅ `documentService.ts` - 文档服务
- ✅ `batchService.ts` - 批处理服务
- ✅ `tokenService.ts` - Token计数服务
- ✅ `reviewService.ts` - 审查服务

### 5. routes/ - 路由（7个文件）
- ✅ `projects.ts` - 项目路由
- ✅ `agents.ts` - 智能体路由
- ✅ `conversations.ts` - 对话路由
- ✅ `chatRoutes.ts` - 通用对话路由
- ✅ `knowledgeBases.ts` - 知识库路由
- ✅ `batchRoutes.ts` - 批处理路由
- ✅ `reviewRoutes.ts` - 审查路由

### 6. middleware/ - 中间件（1个文件）
- ✅ `validateProject.ts` - 项目验证中间件

### 7. utils/ - 工具函数（1个文件）
- ✅ `jsonParser.ts` - JSON解析工具

### 8. templates/ - 模板（1个文件）
- ✅ `clinicalResearch.ts` - 临床研究模板

### 9. config/ - 配置（2个文件）
- ✅ `database.ts` - 数据库配置
- ✅ `env.ts` - 环境变量配置

### 10. types/ - 类型（空目录）

### 11. scripts/ - 脚本（2个文件）
- ✅ `create-mock-user.ts` - 创建模拟用户
- ✅ `test-dify-client.ts` - 测试Dify客户端

---

## 🗺️ 详细迁移映射表

### 阶段1：迁移 common/ 通用能力层

#### 1.1 common/llm/ - LLM适配器
| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `src/adapters/types.ts` | `src/common/llm/adapters/types.ts` | 适配器接口 |
| `src/adapters/DeepSeekAdapter.ts` | `src/common/llm/adapters/DeepSeekAdapter.ts` | DeepSeek适配器 |
| `src/adapters/QwenAdapter.ts` | `src/common/llm/adapters/QwenAdapter.ts` | Qwen适配器 |
| `src/adapters/LLMFactory.ts` | `src/common/llm/adapters/LLMFactory.ts` | LLM工厂 |

#### 1.2 common/document/ - 文档处理
| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `src/clients/ExtractionClient.ts` | `src/common/document/ExtractionClient.ts` | 文档提取客户端 |
| `src/services/tokenService.ts` | `src/common/document/TokenService.ts` | Token计数服务 |
| `src/clients/types.ts` | `src/common/document/types.ts` | 文档相关类型 |

#### 1.3 common/rag/ - RAG引擎
| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `src/clients/DifyClient.ts` | `src/common/rag/DifyClient.ts` | Dify客户端 |

#### 1.4 common/middleware/ - 中间件
| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `src/middleware/validateProject.ts` | `src/common/middleware/validateProject.ts` | 项目验证中间件 |

#### 1.5 common/utils/ - 工具函数
| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `src/utils/jsonParser.ts` | `src/common/utils/jsonParser.ts` | JSON解析工具 |

#### 1.6 common/types/ - 通用类型
| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `src/types/` | `src/common/types/` | （目前为空，预留） |

---

### 阶段2：迁移 modules/ 业务模块层

#### 2.1 modules/aia/ - AI智能问答模块

**Controllers:**
| 原路径 | 新路径 |
|--------|--------|
| `src/controllers/projectController.ts` | `src/modules/aia/controllers/projectController.ts` |
| `src/controllers/agentController.ts` | `src/modules/aia/controllers/agentController.ts` |
| `src/controllers/conversationController.ts` | `src/modules/aia/controllers/conversationController.ts` |
| `src/controllers/chatController.ts` | `src/modules/aia/controllers/chatController.ts` |

**Services:**
| 原路径 | 新路径 |
|--------|--------|
| `src/services/projectService.ts` | `src/modules/aia/services/projectService.ts` |
| `src/services/agentService.ts` | `src/modules/aia/services/agentService.ts` |
| `src/services/conversationService.ts` | `src/modules/aia/services/conversationService.ts` |

**Routes:**
| 原路径 | 新路径 |
|--------|--------|
| `src/routes/projects.ts` | `src/modules/aia/routes/projects.ts` |
| `src/routes/agents.ts` | `src/modules/aia/routes/agents.ts` |
| `src/routes/conversations.ts` | `src/modules/aia/routes/conversations.ts` |
| `src/routes/chatRoutes.ts` | `src/modules/aia/routes/chatRoutes.ts` |

**其他：**
| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `src/templates/clinicalResearch.ts` | `src/modules/aia/templates/clinicalResearch.ts` | 批处理模板 |

**新增文件：**
- `src/modules/aia/routes/index.ts` - 模块路由统一导出

---

#### 2.2 modules/pkb/ - 个人知识库模块

**Controllers:**
| 原路径 | 新路径 |
|--------|--------|
| `src/controllers/knowledgeBaseController.ts` | `src/modules/pkb/controllers/knowledgeBaseController.ts` |
| `src/controllers/documentController.ts` | `src/modules/pkb/controllers/documentController.ts` |
| `src/controllers/batchController.ts` | `src/modules/pkb/controllers/batchController.ts` |

**Services:**
| 原路径 | 新路径 |
|--------|--------|
| `src/services/knowledgeBaseService.ts` | `src/modules/pkb/services/knowledgeBaseService.ts` |
| `src/services/documentService.ts` | `src/modules/pkb/services/documentService.ts` |
| `src/services/batchService.ts` | `src/modules/pkb/services/batchService.ts` |

**Routes:**
| 原路径 | 新路径 |
|--------|--------|
| `src/routes/knowledgeBases.ts` | `src/modules/pkb/routes/knowledgeBases.ts` |
| `src/routes/batchRoutes.ts` | `src/modules/pkb/routes/batchRoutes.ts` |

**新增文件：**
- `src/modules/pkb/routes/index.ts` - 模块路由统一导出

---

#### 2.3 modules/rvw/ - 稿件审查模块

**Controllers:**
| 原路径 | 新路径 |
|--------|--------|
| `src/controllers/reviewController.ts` | `src/modules/rvw/controllers/reviewController.ts` |

**Services:**
| 原路径 | 新路径 |
|--------|--------|
| `src/services/reviewService.ts` | `src/modules/rvw/services/reviewService.ts` |

**Routes:**
| 原路径 | 新路径 |
|--------|--------|
| `src/routes/reviewRoutes.ts` | `src/modules/rvw/routes/reviewRoutes.ts` |

**新增文件：**
- `src/modules/rvw/routes/index.ts` - 模块路由统一导出

---

### 阶段3：创建 platform/ 平台层（仅骨架）

**目录结构：**
```
src/platform/
├── auth/
│   └── README.md          # 说明：Week 3实现
└── users/
    └── README.md          # 说明：Week 3实现
```

---

### 阶段4：保留原位置的文件

| 路径 | 说明 |
|------|------|
| `src/config/` | 配置文件保持原位 |
| `src/index.ts` | 主入口文件（需要重写导入路径） |
| `src/scripts/` | 工具脚本保持原位 |

---

## 🔧 TypeScript路径别名配置

### tsconfig.json 新增配置
```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@platform/*": ["src/platform/*"],
      "@common/*": ["src/common/*"],
      "@modules/*": ["src/modules/*"],
      "@config/*": ["src/config/*"]
    }
  }
}
```

---

## 📝 导入路径更新规则

### 1. common层内部导入
```typescript
// 旧：
import { LLMFactory } from '../adapters/LLMFactory.js'

// 新：
import { LLMFactory } from '@common/llm/adapters/LLMFactory.js'
```

### 2. modules层导入common层
```typescript
// 旧：
import { LLMFactory } from '../../adapters/LLMFactory.js'

// 新：
import { LLMFactory } from '@common/llm/adapters/LLMFactory.js'
```

### 3. 模块内部导入
```typescript
// 旧：
import { projectService } from '../services/projectService.js'

// 新：
import { projectService } from '@modules/aia/services/projectService.js'
// 或者相对路径（如果在同一模块内）：
import { projectService } from '../services/projectService.js'
```

---

## ⚠️ 关键注意事项

### 1. 保持 .js 扩展名
- ✅ TypeScript ES模块需要保留 `.js` 扩展名
- ✅ 所有导入路径末尾必须加 `.js`

### 2. Prisma Client 导入
```typescript
// 保持不变：
import { prisma } from '@config/database.js'
```

### 3. 外部依赖导入
```typescript
// Fastify、Prisma等外部包导入不变
import Fastify from 'fastify'
import { PrismaClient } from '@prisma/client'
```

### 4. 类型导入
```typescript
// 使用 type 关键字导入类型
import type { FastifyRequest, FastifyReply } from 'fastify'
```

---

## 🚀 执行步骤（分11个阶段）

### ✅ 阶段1：代码调研与规划（已完成）
- [x] 了解现有代码结构
- [x] 创建迁移映射表
- [x] 制定详细计划

### ⏳ 阶段2：备份与安全
- [ ] Git status 检查工作区状态
- [ ] Git commit 当前代码（作为回退点）
- [ ] 创建新分支 `feature/backend-layering`

### ⏳ 阶段3：创建新目录结构
- [ ] 创建 `src/platform/`（空）
- [ ] 创建 `src/common/` 及子目录
- [ ] 创建 `src/modules/` 及子目录

### ⏳ 阶段4：配置TypeScript路径别名
- [ ] 更新 `tsconfig.json`
- [ ] 测试编译

### ⏳ 阶段5：迁移common层
- [ ] 迁移 `common/llm/`
- [ ] 迁移 `common/document/`
- [ ] 迁移 `common/rag/`
- [ ] 迁移 `common/middleware/`
- [ ] 迁移 `common/utils/`
- [ ] 更新所有导入路径

### ⏳ 阶段6：迁移modules层
- [ ] 迁移 `modules/aia/`
- [ ] 迁移 `modules/pkb/`
- [ ] 迁移 `modules/rvw/`
- [ ] 创建各模块的 `routes/index.ts`
- [ ] 更新所有导入路径

### ⏳ 阶段7：创建platform层骨架
- [ ] 创建 `platform/auth/README.md`
- [ ] 创建 `platform/users/README.md`

### ⏳ 阶段8：更新主入口文件
- [ ] 重写 `src/index.ts`
- [ ] 更新路由注册逻辑

### ⏳ 阶段9：编译测试与验证
- [ ] 运行 `npm run build`
- [ ] 检查编译错误
- [ ] 修复类型错误

### ⏳ 阶段10：功能测试（API冒烟测试）
- [ ] 启动后端服务 `npm run dev`
- [ ] 测试健康检查 `/health`
- [ ] 测试AIA模块API（至少1个端点）
- [ ] 测试PKB模块API（至少1个端点）
- [ ] 测试RVW模块API（至少1个端点）

### ⏳ 阶段11：文档更新与总结
- [ ] 更新 `前后端模块化架构设计-V2.md`
- [ ] 创建 `后端代码分层实施报告.md`
- [ ] 更新 `下一阶段行动计划-V2.2-完整版.md`
- [ ] Git commit 最终代码
- [ ] 标记任务19完成

---

## 📊 风险评估与应对

### 风险1：导入路径错误导致编译失败
**应对：** 
- ✅ 每迁移一个文件，立即更新其导入路径
- ✅ 阶段性编译验证（每完成一层就编译一次）

### 风险2：运行时错误（路径解析问题）
**应对：**
- ✅ 保留 `.js` 扩展名
- ✅ 配置 `tsconfig.json` 的 `paths` 映射
- ✅ 启动测试验证

### 风险3：循环依赖
**应对：**
- ✅ 遵循依赖方向：modules → common → platform
- ✅ 不允许反向依赖

### 风险4：功能回归
**应对：**
- ✅ 保持业务逻辑完全不变
- ✅ API冒烟测试验证核心功能
- ✅ Git记录每步，可随时回退

---

## 🎯 成功标准

### 编译成功
- ✅ `npm run build` 无错误
- ✅ 无TypeScript类型错误
- ✅ 无ESLint错误

### 运行成功
- ✅ `npm run dev` 正常启动
- ✅ 健康检查返回正常
- ✅ 数据库连接正常

### 功能正常
- ✅ AIA模块API正常响应
- ✅ PKB模块API正常响应
- ✅ RVW模块API正常响应
- ✅ 流式输出正常
- ✅ 文件上传正常

### 架构清晰
- ✅ 三层架构目录清晰
- ✅ 模块边界明确
- ✅ 导入路径一致

---

**创建人：** AI助手  
**审核人：** 待审核  
**开始时间：** 2025-11-13  
**预计完成时间：** 1-2天