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 新增配置

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@platform/*": ["src/platform/*"],
      "@common/*": ["src/common/*"],
      "@modules/*": ["src/modules/*"],
      "@config/*": ["src/config/*"]
    }
  }
}

---

📝 导入路径更新规则

1. common层内部导入

// 旧：
import { LLMFactory } from '../adapters/LLMFactory.js'

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

2. modules层导入common层

// 旧：
import { LLMFactory } from '../../adapters/LLMFactory.js'

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

3. 模块内部导入

// 旧：
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 导入

// 保持不变：
import { prisma } from '@config/database.js'

3. 外部依赖导入

// Fastify、Prisma等外部包导入不变
import Fastify from 'fastify'
import { PrismaClient } from '@prisma/client'

4. 类型导入

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

---

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

✅ 阶段1：代码调研与规划（已完成）

• 了解现有代码结构
• 创建迁移映射表
• 制定详细计划

⏳ 阶段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天