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

> **文档版本�?* 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/ - 服务�?个文件）
- �?`projectService.ts` - 项目服务
- �?`agentService.ts` - 智能体服�?
- �?`conversationService.ts` - 对话服务
- �?`knowledgeBaseService.ts` - 知识库服�?
- �?`documentService.ts` - 文档服务
- �?`batchService.ts` - 批处理服�?
- �?`tokenService.ts` - Token计数服务
- �?`reviewService.ts` - 审查服务

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

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

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

### 8. templates/ - 模板�?个文件）
- �?`clinicalResearch.ts` - 临床研究模板

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

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

### 11. scripts/ - 脚本�?个文件）
- �?`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（至�?个端点）
- [ ] 测试PKB模块API（至�?个端点）
- [ ] 测试RVW模块API（至�?个端点）

### �?阶段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�?