Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(admin): Add user management and upgrade to module permission system

Browse Source 
Features - User Management (Phase 4.1):
- Database: Add user_modules table for fine-grained module permissions
- Database: Add 4 user permissions (view/create/edit/delete) to role_permissions
- Backend: UserService (780 lines) - CRUD with tenant isolation
- Backend: UserController + UserRoutes (648 lines) - 13 API endpoints
- Backend: Batch import users from Excel
- Frontend: UserListPage (412 lines) - list/filter/search/pagination
- Frontend: UserFormPage (341 lines) - create/edit with module config
- Frontend: UserDetailPage (393 lines) - details/tenant/module management
- Frontend: 3 modal components (592 lines) - import/assign/configure
- API: GET/POST/PUT/DELETE /api/admin/users/* endpoints

Architecture Upgrade - Module Permission System:
- Backend: Add getUserModules() method in auth.service
- Backend: Login API returns modules array in user object
- Frontend: AuthContext adds hasModule() method
- Frontend: Navigation filters modules based on user.modules
- Frontend: RouteGuard checks requiredModule instead of requiredVersion
- Frontend: Remove deprecated version-based permission system
- UX: Only show accessible modules in navigation (clean UI)
- UX: Smart redirect after login (avoid 403 for regular users)

Fixes:
- Fix UTF-8 encoding corruption in ~100 docs files
- Fix pageSize type conversion in userService (String to Number)
- Fix authUser undefined error in TopNavigation
- Fix login redirect logic with role-based access check
- Update Git commit guidelines v1.2 with UTF-8 safety rules

Database Changes:
- CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled)
- ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code)
- INSERT 4 permissions + role assignments
- UPDATE PUBLIC tenant with 8 module subscriptions

Technical:
- Backend: 5 new files (~2400 lines)
- Frontend: 10 new files (~2500 lines)
- Docs: 1 development record + 2 status updates + 1 guideline update
- Total: ~4900 lines of code

Status: User management 100% complete, module permission system operational
This commit is contained in:
HaHafeng
2026-01-16 13:42:10 +08:00
parent 98d862dbd4
commit 66255368b7
560 changed files with 70424 additions and 52353 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,42 +1,42 @@
# 后端代码分层 - 详细迁移计划
> **鏂囨。鐗堟湰锛?* v1.0
> **鍒涘缓鏃ユ湡锛?* 2025-11-13
> **浠诲姟缂栧彿锛?* 浠诲姟19锛圵eek 2 Day 8-9锛?
> **鐩<EFBFBD>爣锛?* 灏嗙幇鏈夋墎骞冲寲鍚庣<E98D9A>浠ｇ爜閲嶇粍涓?platform/common/modules 涓夊眰鏋舵瀯
> **文档版本：** v1.0
> **创建日期：** 2025-11-13
> **任务编号：** 任务19（Week 2 Day 8-9）
> **目标：** 将现有扁平化后端代码重组为 platform/common/modules 三层架构
---
## 📋 总体目标
### 设计原则
1. 鉁?**绋冲Ε绗<CE95>竴** - 涓€姝ヤ竴姝ヨ縼绉伙紝姣忔<EFBFBD>楠岃瘉
2. 鉁?**鍙<>仛閲嶇粍** - 涓嶅<EFBFBD>鍔犳柊鍔熻兘锛屼笉淇<EFBFBD>敼涓氬姟閫昏緫
3. 鉁?**淇濇寔鍏煎<E98D8F>** - API璺<EFBFBD>緞涓嶅彉锛屽姛鑳戒笉鍙?
4. 鉁?**鍙<>洖閫€** - Git commit璁板綍姣忎竴姝ワ紝鍙<EFBFBD>殢鏃跺洖閫€
1. ✅ **稳妥第一** - 一步一步迁移，每步验证
2. ✅ **只做重组** - 不增加新功能，不修改业务逻辑
3. ✅ **保持兼容** - API路径不变，功能不变
4. ✅ **可回退** - Git commit记录每一步，可随时回退
### 目标架构
```
backend/src/
鈹溾攢鈹€ platform/ # 馃彌锔?骞冲彴灞傦紙鏈<E7B499><E98F88>鍙<EFBFBD>垱寤虹洰褰曪紝鏆備笉瀹炵幇锛?
鈹? 鈹溾攢鈹€ auth/
鈹? 鈹斺攢鈹€ users/
鈹?
鈹溾攢鈹€ common/ # 馃敡 閫氱敤鑳藉姏灞?
鈹? 鈹溾攢鈹€ llm/ # LLM閫傞厤鍣ㄥ拰Gateway
鈹? 鈹溾攢鈹€ document/ # 鏂囨。澶勭悊瀹㈡埛绔?
鈹? 鈹溾攢鈹€ rag/ # RAG/Dify瀹㈡埛绔?
鈹? 鈹溾攢鈹€ middleware/ # 涓<EFBFBD>棿浠?
鈹? 鈹溾攢鈹€ utils/ # 宸ュ叿鍑芥暟
鈹? 鈹斺攢鈹€ types/ # 閫氱敤绫诲瀷
鈹?
鈹溾攢鈹€ modules/ # 馃摝 涓氬姟妯″潡灞?
鈹? 鈹溾攢鈹€ aia/ # AI鏅鸿兘闂<EFBFBD>瓟妯″潡
鈹? 鈹溾攢鈹€ pkb/ # 涓<EFBFBD>汉鐭ヨ瘑搴撴ā鍧?
鈹? 鈹斺攢鈹€ rvw/ # 绋夸欢瀹℃煡妯″潡
鈹?
├── platform/ # 🏛️ 平台层（本次只创建目录，暂不实现）
│ ├── auth/
│ └── users/
│
├── common/ # 🔧 通用能力层
│ ├── llm/ # LLM适配器和Gateway
│ ├── document/ # 文档处理客户端
│ ├── rag/ # RAG/Dify客户端
│ ├── middleware/ # 中间件
│ ├── utils/ # 工具函数
│ └── types/ # 通用类型
│
├── modules/ # 📦 业务模块层
│ ├── aia/ # AI智能问答模块
│ ├── pkb/ # 个人知识库模块
│ └── rvw/ # 稿件审查模块
│
├── config/ # 配置（保留）
鈹斺攢鈹€ index.ts # 涓诲叆鍙ｏ紙閲嶅啓锛?
└── index.ts # 主入口（重写）
```
---
@@ -44,113 +44,113 @@ backend/src/
## 📊 现有代码清单
### 1. adapters/ - LLM适配器（4个文件）
- 鉁?`DeepSeekAdapter.ts` - DeepSeek-V3閫傞厤鍣?
- 鉁?`QwenAdapter.ts` - Qwen3/Qwen-Long閫傞厤鍣?
- 鉁?`LLMFactory.ts` - LLM宸ュ巶绫?
- 鉁?`types.ts` - 閫傞厤鍣ㄦ帴鍙ｅ畾涔?
- ✅ `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` - 瀹㈡埛绔<EFBFBD>被鍨嬪畾涔?
- ✅ `DifyClient.ts` - Dify RAG客户端
- ✅ `ExtractionClient.ts` - Python文档提取服务客户端
- ✅ `types.ts` - 客户端类型定义
### 3. controllers/ - 控制器（8个文件）
- 鉁?`projectController.ts` - 椤圭洰绠＄悊
- 鉁?`agentController.ts` - 鏅鸿兘浣撶<EFBFBD>鐞?
- 鉁?`conversationController.ts` - 瀵硅瘽绠＄悊
- 鉁?`chatController.ts` - 閫氱敤瀵硅瘽
- 鉁?`knowledgeBaseController.ts` - 鐭ヨ瘑搴撶<EFBFBD>鐞?
- 鉁?`documentController.ts` - 鏂囨。绠＄悊
- 鉁?`batchController.ts` - 鎵瑰<EFBFBD>鐞?
- 鉁?`reviewController.ts` - 绋夸欢瀹℃煡
- ✅ `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` - 鎵瑰<EFBFBD>鐞嗘湇鍔?
- 鉁?`tokenService.ts` - Token璁℃暟鏈嶅姟
- 鉁?`reviewService.ts` - 瀹℃煡鏈嶅姟
### 4. services/ - 服务（8个文件）
- ✅ `projectService.ts` - 项目服务
- ✅ `agentService.ts` - 智能体服务
- ✅ `conversationService.ts` - 对话服务
- ✅ `knowledgeBaseService.ts` - 知识库服务
- ✅ `documentService.ts` - 文档服务
- ✅ `batchService.ts` - 批处理服务
- ✅ `tokenService.ts` - Token计数服务
- ✅ `reviewService.ts` - 审查服务
### 5. routes/ - 璺<EFBFBD>敱锛?涓<>枃浠讹級
- 鉁?`projects.ts` - 椤圭洰璺<EFBFBD>敱
- 鉁?`agents.ts` - 鏅鸿兘浣撹矾鐢?
- 鉁?`conversations.ts` - 瀵硅瘽璺<EFBFBD>敱
- 鉁?`chatRoutes.ts` - 閫氱敤瀵硅瘽璺<EFBFBD>敱
- 鉁?`knowledgeBases.ts` - 鐭ヨ瘑搴撹矾鐢?
- 鉁?`batchRoutes.ts` - 鎵瑰<EFBFBD>鐞嗚矾鐢?
- 鉁?`reviewRoutes.ts` - 瀹℃煡璺<EFBFBD>敱
### 5. routes/ - 路由（7个文件）
- ✅ `projects.ts` - 项目路由
- ✅ `agents.ts` - 智能体路由
- ✅ `conversations.ts` - 对话路由
- ✅ `chatRoutes.ts` - 通用对话路由
- ✅ `knowledgeBases.ts` - 知识库路由
- ✅ `batchRoutes.ts` - 批处理路由
- ✅ `reviewRoutes.ts` - 审查路由
### 6. middleware/ - 中间件（1个文件）
- 鉁?`validateProject.ts` - 椤圭洰楠岃瘉涓<EFBFBD>棿浠?
- ✅ `validateProject.ts` - 项目验证中间件
### 7. utils/ - 宸ュ叿鍑芥暟锛?涓<>枃浠讹級
- 鉁?`jsonParser.ts` - JSON瑙ｆ瀽宸ュ叿
### 7. utils/ - 工具函数（1个文件）
- ✅ `jsonParser.ts` - JSON解析工具
### 8. templates/ - 妯℃澘锛?涓<>枃浠讹級
- 鉁?`clinicalResearch.ts` - 涓村簥鐮旂┒妯℃澘
### 8. templates/ - 模板（1个文件）
- ✅ `clinicalResearch.ts` - 临床研究模板
### 9. config/ - 閰嶇疆锛?涓<>枃浠讹級
- 鉁?`database.ts` - 鏁版嵁搴撻厤缃?
- 鉁?`env.ts` - 鐜<EFBFBD><EFBFBD>鍙橀噺閰嶇疆
### 9. config/ - 配置（2个文件）
- ✅ `database.ts` - 数据库配置
- ✅ `env.ts` - 环境变量配置
### 10. types/ - 绫诲瀷锛堢┖鐩<EFBFBD>綍锛?
### 10. types/ - 类型（空目录）
### 11. scripts/ - 鑴氭湰锛?涓<>枃浠讹級
- 鉁?`create-mock-user.ts` - 鍒涘缓妯℃嫙鐢ㄦ埛
- 鉁?`test-dify-client.ts` - 娴嬭瘯Dify瀹㈡埛绔?
### 11. scripts/ - 脚本（2个文件）
- ✅ `create-mock-user.ts` - 创建模拟用户
- ✅ `test-dify-client.ts` - 测试Dify客户端
---
## 馃椇锔?璇︾粏杩佺Щ鏄犲皠琛?
## 🗺️ 详细迁移映射表
### 闃舵<EFBFBD>1锛氳縼绉?common/ 閫氱敤鑳藉姏灞?
### 阶段1：迁移 common/ 通用能力层
#### 1.1 common/llm/ - LLM閫傞厤鍣?
| 鍘熻矾寰?| 鏂拌矾寰?| 璇存槑 |
#### 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/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/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瀹㈡埛绔?|
| `src/clients/DifyClient.ts` | `src/common/rag/DifyClient.ts` | Dify客户端 |
#### 1.4 common/middleware/ - 涓<EFBFBD>棿浠?
| 鍘熻矾寰?| 鏂拌矾寰?| 璇存槑 |
#### 1.4 common/middleware/ - 中间件
| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `src/middleware/validateProject.ts` | `src/common/middleware/validateProject.ts` | 椤圭洰楠岃瘉涓<EFBFBD>棿浠?|
| `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/` | 锛堢洰鍓嶄负绌猴紝棰勭暀锛?|
| `src/types/` | `src/common/types/` | （目前为空，预留） |
---
### 闃舵<EFBFBD>2锛氳縼绉?modules/ 涓氬姟妯″潡灞?
### 阶段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` |
@@ -158,53 +158,53 @@ backend/src/
| `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` | 鎵瑰<EFBFBD>鐞嗘ā鏉?|
| `src/templates/clinicalResearch.ts` | `src/modules/aia/templates/clinicalResearch.ts` | 批处理模板 |
**鏂板<EFBFBD>鏂囦欢锛?*
**新增文件：**
- `src/modules/aia/routes/index.ts` - 模块路由统一导出
---
#### 2.2 modules/pkb/ - 涓<EFBFBD>汉鐭ヨ瘑搴撴ā鍧?
#### 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` |
**鏂板<EFBFBD>鏂囦欢锛?*
**新增文件：**
- `src/modules/pkb/routes/index.ts` - 模块路由统一导出
---
@@ -212,39 +212,39 @@ backend/src/
#### 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` |
**鏂板<EFBFBD>鏂囦欢锛?*
**新增文件：**
- `src/modules/rvw/routes/index.ts` - 模块路由统一导出
---
### 闃舵<EFBFBD>3锛氬垱寤?platform/ 骞冲彴灞傦紙浠呴<EFBFBD>鏋讹級
### 阶段3：创建 platform/ 平台层（仅骨架）
**鐩<EFBFBD>綍缁撴瀯锛?*
**目录结构：**
```
src/platform/
├── auth/
鈹? 鈹斺攢鈹€ README.md # 璇存槑锛歐eek 3瀹炵幇
│ └── README.md # 说明：Week 3实现
└── users/
└── README.md # 说明：Week 3实现
```
---
### 闃舵<EFBFBD>4锛氫繚鐣欏師浣嶇疆鐨勬枃浠?
### 阶段4：保留原位置的文件
| 路径 | 说明 |
|------|------|
@@ -275,7 +275,7 @@ src/platform/
## 📝 导入路径更新规则
### 1. common灞傚唴閮ㄥ<EFBFBD>鍏?
### 1. common层内部导入
```typescript
// 旧：
import { LLMFactory } from '../adapters/LLMFactory.js'
@@ -284,7 +284,7 @@ import { LLMFactory } from '../adapters/LLMFactory.js'
import { LLMFactory } from '@common/llm/adapters/LLMFactory.js'
```
### 2. modules灞傚<EFBFBD>鍏<EFBFBD>ommon灞?
### 2. modules层导入common层
```typescript
// 旧：
import { LLMFactory } from '../../adapters/LLMFactory.js'
@@ -300,7 +300,7 @@ import { projectService } from '../services/projectService.js'
// 新：
import { projectService } from '@modules/aia/services/projectService.js'
// 鎴栬€呯浉瀵硅矾寰勶紙濡傛灉鍦ㄥ悓涓€妯″潡鍐咃級锛?
// 或者相对路径（如果在同一模块内）：
import { projectService } from '../services/projectService.js'
```
@@ -308,13 +308,13 @@ import { projectService } from '../services/projectService.js'
## ⚠️ 关键注意事项
### 1. 淇濇寔 .js 鎵╁睍鍚?
- 鉁?TypeScript ES妯″潡闇€瑕佷繚鐣?`.js` 鎵╁睍鍚?
- 鉁?鎵€鏈夊<E98F88>鍏ヨ矾寰勬湯灏惧繀椤诲姞 `.js`
### 1. 保持 .js 扩展名
- ✅ TypeScript ES模块需要保留 `.js` 扩展名
- ✅ 所有导入路径末尾必须加 `.js`
### 2. Prisma Client 导入
```typescript
// 淇濇寔涓嶅彉锛?
// 保持不变：
import { prisma } from '@config/database.js'
```
@@ -327,7 +327,7 @@ import { PrismaClient } from '@prisma/client'
### 4. 类型导入
```typescript
// 浣跨敤 type 鍏抽敭瀛楀<EFBFBD>鍏ョ被鍨?
// 使用 type 关键字导入类型
import type { FastifyRequest, FastifyReply } from 'fastify'
```
@@ -335,125 +335,125 @@ import type { FastifyRequest, FastifyReply } from 'fastify'
## 🚀 执行步骤（分11个阶段）
### 鉁?闃舵<E99783>1锛氫唬鐮佽皟鐮斾笌瑙勫垝锛堝凡瀹屾垚锛?
### ✅ 阶段1：代码调研与规划（已完成）
- [x] 了解现有代码结构
- [x] 鍒涘缓杩佺Щ鏄犲皠琛?
- [x] 创建迁移映射表
- [x] 制定详细计划
### 鈴?闃舵<E99783>2锛氬<E9949B>浠戒笌瀹夊叏
- [ ] Git status 妫€鏌ュ伐浣滃尯鐘舵€?
### ⏳ 阶段2：备份与安全
- [ ] Git status 检查工作区状态
- [ ] Git commit 当前代码（作为回退点）
- [ ] 鍒涘缓鏂板垎鏀?`feature/backend-layering`
- [ ] 创建新分支 `feature/backend-layering`
### 鈴?闃舵<E99783>3锛氬垱寤烘柊鐩<E69F8A>綍缁撴瀯
- [ ] 鍒涘缓 `src/platform/`锛堢┖锛?
### ⏳ 阶段3：创建新目录结构
- [ ] 创建 `src/platform/`（空）
- [ ] 创建 `src/common/` 及子目录
- [ ] 创建 `src/modules/` 及子目录
### 鈴?闃舵<E99783>4锛氶厤缃甌ypeScript璺<EFBFBD>緞鍒<EFBFBD>悕
### ⏳ 阶段4：配置TypeScript路径别名
- [ ] 更新 `tsconfig.json`
- [ ] 测试编译
### 鈴?闃舵<E99783>5锛氳縼绉籧ommon灞?
### ⏳ 阶段5：迁移common层
- [ ] 迁移 `common/llm/`
- [ ] 迁移 `common/document/`
- [ ] 迁移 `common/rag/`
- [ ] 迁移 `common/middleware/`
- [ ] 迁移 `common/utils/`
- [ ] 鏇存柊鎵€鏈夊<EFBFBD>鍏ヨ矾寰?
- [ ] 更新所有导入路径
### 鈴?闃舵<E99783>6锛氳縼绉籱odules灞?
### ⏳ 阶段6：迁移modules层
- [ ] 迁移 `modules/aia/`
- [ ] 迁移 `modules/pkb/`
- [ ] 迁移 `modules/rvw/`
- [ ] 创建各模块的 `routes/index.ts`
- [ ] 鏇存柊鎵€鏈夊<EFBFBD>鍏ヨ矾寰?
- [ ] 更新所有导入路径
### 鈴?闃舵<E99783>7锛氬垱寤簆latform灞傞<EFBFBD>鏋?
### ⏳ 阶段7：创建platform层骨架
- [ ] 创建 `platform/auth/README.md`
- [ ] 创建 `platform/users/README.md`
### 鈴?闃舵<E99783>8锛氭洿鏂颁富鍏ュ彛鏂囦欢
### ⏳ 阶段8：更新主入口文件
- [ ] 重写 `src/index.ts`
- [ ] 更新路由注册逻辑
### 鈴?闃舵<E99783>9锛氱紪璇戞祴璇曚笌楠岃瘉
### ⏳ 阶段9：编译测试与验证
- [ ] 运行 `npm run build`
- [ ] 妫€鏌ョ紪璇戦敊璇?
- [ ] 检查编译错误
- [ ] 修复类型错误
### 鈴?闃舵<E99783>10锛氬姛鑳芥祴璇曪紙API鍐掔儫娴嬭瘯锛?
### ⏳ 阶段10：功能测试（API冒烟测试）
- [ ] 启动后端服务 `npm run dev`
- [ ] 娴嬭瘯鍋ュ悍妫€鏌?`/health`
- [ ] 娴嬭瘯AIA妯″潡API锛堣嚦灏?涓<><E6B693>鐐癸級
- [ ] 娴嬭瘯PKB妯″潡API锛堣嚦灏?涓<><E6B693>鐐癸級
- [ ] 娴嬭瘯RVW妯″潡API锛堣嚦灏?涓<><E6B693>鐐癸級
- [ ] 测试健康检查 `/health`
- [ ] 测试AIA模块API（至少1个端点）
- [ ] 测试PKB模块API（至少1个端点）
- [ ] 测试RVW模块API（至少1个端点）
### 鈴?闃舵<E99783>11锛氭枃妗ｆ洿鏂颁笌鎬荤粨
### ⏳ 阶段11：文档更新与总结
- [ ] 更新 `前后端模块化架构设计-V2.md`
- [ ] 创建 `后端代码分层实施报告.md`
- [ ] 鏇存柊 `涓嬩竴闃舵<E99783>琛屽姩璁″垝-V2.2-瀹屾暣鐗?md`
- [ ] Git commit 鏈€缁堜唬鐮?
- [ ] 更新 `下一阶段行动计划-V2.2-完整版.md`
- [ ] Git commit 最终代码
- [ ] 标记任务19完成
---
## 馃搳 椋庨櫓璇勪及涓庡簲瀵?
## 📊 风险评估与应对
### 椋庨櫓1锛氬<EFBFBD>鍏ヨ矾寰勯敊璇<EFBFBD><EFBFBD>鑷寸紪璇戝け璐?
**搴斿<EFBFBD>锛?*
- 鉁?姣忚縼绉讳竴涓<E7ABB4>枃浠讹紝绔嬪嵆鏇存柊鍏跺<E98D8F>鍏ヨ矾寰?
- 鉁?闃舵<E99783>鎬х紪璇戦獙璇侊紙姣忓畬鎴愪竴灞傚氨缂栬瘧涓€娆★級
### 风险1：导入路径错误导致编译失败
**应对：**
- ✅ 每迁移一个文件，立即更新其导入路径
- ✅ 阶段性编译验证（每完成一层就编译一次）
### 风险2：运行时错误（路径解析问题）
**搴斿<EFBFBD>锛?*
- 鉁?淇濈暀 `.js` 鎵╁睍鍚?
- 鉁?閰嶇疆 `tsconfig.json` 鐨?`paths` 鏄犲皠
- 鉁?鍚<>姩娴嬭瘯楠岃瘉
**应对：**
- ✅ 保留 `.js` 扩展名
- ✅ 配置 `tsconfig.json` 的 `paths` 映射
- ✅ 启动测试验证
### 椋庨櫓3锛氬惊鐜<EFBFBD>緷璧?
**搴斿<EFBFBD>锛?*
- 鉁?閬靛惊渚濊禆鏂瑰悜锛歮odules 鈫?common 鈫?platform
- 鉁?涓嶅厑璁稿弽鍚戜緷璧?
### 风险3：循环依赖
**应对：**
- ✅ 遵循依赖方向：modules → common → platform
- ✅ 不允许反向依赖
### 椋庨櫓4锛氬姛鑳藉洖褰?
**搴斿<EFBFBD>锛?*
- 鉁?淇濇寔涓氬姟閫昏緫瀹屽叏涓嶅彉
- 鉁?API鍐掔儫娴嬭瘯楠岃瘉鏍稿績鍔熻兘
- 鉁?Git璁板綍姣忔<EFBFBD>锛屽彲闅忔椂鍥為€€
### 风险4：功能回归
**应对：**
- ✅ 保持业务逻辑完全不变
- ✅ API冒烟测试验证核心功能
- ✅ Git记录每步，可随时回退
---
## 🎯 成功标准
### 编译成功
- 鉁?`npm run build` 鏃犻敊璇?
- 鉁?鏃燭ypeScript绫诲瀷閿欒<EFBFBD>
- 鉁?鏃燛SLint閿欒<EFBFBD>
- ✅ `npm run build` 无错误
- ✅ 无TypeScript类型错误
- ✅ 无ESLint错误
### 运行成功
- 鉁?`npm run dev` 姝ｅ父鍚<EFBFBD>姩
- 鉁?鍋ュ悍妫€鏌ヨ繑鍥炴<E98DA5>甯?
- 鉁?鏁版嵁搴撹繛鎺ユ<E98EBA>甯?
- ✅ `npm run dev` 正常启动
- ✅ 健康检查返回正常
- ✅ 数据库连接正常
### 功能正常
- 鉁?AIA妯″潡API姝ｅ父鍝嶅簲
- 鉁?PKB妯″潡API姝ｅ父鍝嶅簲
- 鉁?RVW妯″潡API姝ｅ父鍝嶅簲
- 鉁?娴佸紡杈撳嚭姝ｅ父
- 鉁?鏂囦欢涓婁紶姝ｅ父
- ✅ AIA模块API正常响应
- ✅ PKB模块API正常响应
- ✅ RVW模块API正常响应
- ✅ 流式输出正常
- ✅ 文件上传正常
### 架构清晰
- 鉁?涓夊眰鏋舵瀯鐩<E780AF>綍娓呮櫚
- 鉁?妯″潡杈圭晫鏄庣‘
- 鉁?瀵煎叆璺<E58F86>緞涓€鑷?
- ✅ 三层架构目录清晰
- ✅ 模块边界明确
- ✅ 导入路径一致
---
**创建人：** AI助手
**瀹℃牳浜猴細** 寰呭<EFBFBD>鏍?
**审核人：** 待审核
**开始时间：** 2025-11-13
**棰勮<EFBFBD>瀹屾垚鏃堕棿锛?* 1-2澶?
**预计完成时间：** 1-2天