docs: complete documentation system (250+ files)

- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
2025-11-16 15:43:55 +08:00
parent 0fe6821a89
commit e52020409c
173 changed files with 46227 additions and 11964 deletions
--- a/docs/09-架构实施/后端代码分层-迁移计划.md
+++ b/docs/09-架构实施/后端代码分层-迁移计划.md
@@ -0,0 +1,460 @@
+# 后端代码分层 - 详细迁移计划
+
+> **文档版本：** 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天
+
+
+
+