Files

HaHafeng e3e7e028e8 feat(platform): Complete platform infrastructure implementation and verification

Platform Infrastructure - 8 Core Modules Completed:
- Storage Service (LocalAdapter + OSSAdapter stub)
- Logging System (Winston + JSON format)
- Cache Service (MemoryCache + Redis stub)
- Async Job Queue (MemoryQueue + DatabaseQueue stub)
- Health Check Endpoints (liveness/readiness/detailed)
- Database Connection Pool (with Serverless optimization)
- Environment Configuration Management
- Monitoring Metrics (DB connections/memory/API)

Key Features:
- Adapter Pattern for zero-code environment switching
- Full backward compatibility with legacy modules
- 100% test coverage (all 8 modules verified)
- Complete documentation (11 docs updated)

Technical Improvements:
- Fixed duplicate /health route registration issue
- Fixed TypeScript interface export (export type)
- Installed winston dependency
- Added structured logging with context support
- Implemented graceful shutdown for Serverless
- Added connection pool optimization for SAE

Documentation Updates:
- Platform infrastructure planning (04-骞冲彴鍩虹璁炬柦瑙勫垝.md)
- Implementation report (2025-11-17-骞冲彴鍩虹璁炬柦瀹炴柦瀹屾垚鎶ュ憡.md)
- Verification report (2025-11-17-骞冲彴鍩虹璁炬柦楠岃瘉鎶ュ憡.md)
- Git commit guidelines (06-Git鎻愪氦瑙勮寖.md) - Added commit frequency rules
- Updated 3 core architecture documents

Code Statistics:
- New code: 2,532 lines
- New files: 22
- Updated files: 130+
- Test pass rate: 100% (8/8 modules)

Deployment Readiness:
- Local environment: 鉁?Ready
- Cloud environment: 馃攧 Needs OSS/Redis dependencies

Next Steps:
- Ready to start ASL module development
- Can directly use storage/logger/cache/jobQueue

Tested: Local verification 100% passed
Related: #Platform-Infrastructure

2025-11-18 08:00:41 +08:00

13 KiB

Raw Blame History

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

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

📋 总体目标

设计原则

✅ 稳妥第一 - 一步一步迁移，每步验证
✅ 只做重组 - 不增加新功能，不修改业务逻辑
✅ 保持兼容 - API路径不变，功能不变
✅ 可回退 - 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天

13 KiB Raw Blame History Unescape Escape

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

📋 总体目标

设计原则

目标架构

📊 现有代码清单

1. adapters/ - LLM适配器（4个文件）

2. clients/ - 外部服务客户端（3个文件）

3. controllers/ - 控制器（8个文件）

4. services/ - 服务（8个文件）

5. routes/ - 路由（7个文件）

6. middleware/ - 中间件（1个文件）

7. utils/ - 工具函数（1个文件）

8. templates/ - 模板（1个文件）

9. config/ - 配置（2个文件）

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

11. scripts/ - 脚本（2个文件）

🗺️ 详细迁移映射表

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

1.1 common/llm/ - LLM适配器

1.2 common/document/ - 文档处理

1.3 common/rag/ - RAG引擎

1.4 common/middleware/ - 中间件

1.5 common/utils/ - 工具函数

1.6 common/types/ - 通用类型

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

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

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

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

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

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

🔧 TypeScript路径别名配置

tsconfig.json 新增配置

📝 导入路径更新规则

1. common层内部导入

2. modules层导入common层

3. 模块内部导入

⚠️ 关键注意事项

1. 保持 .js 扩展名

2. Prisma Client 导入

3. 外部依赖导入

4. 类型导入

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

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

⏳ 阶段2：备份与安全

⏳ 阶段3：创建新目录结构

⏳ 阶段4：配置TypeScript路径别名

⏳ 阶段5：迁移common层

⏳ 阶段6：迁移modules层

⏳ 阶段7：创建platform层骨架

⏳ 阶段8：更新主入口文件

⏳ 阶段9：编译测试与验证

⏳ 阶段10：功能测试（API冒烟测试）

⏳ 阶段11：文档更新与总结

📊 风险评估与应对

风险1：导入路径错误导致编译失败

风险2：运行时错误（路径解析问题）

风险3：循环依赖

风险4：功能回归

🎯 成功标准

编译成功

运行成功

功能正常

架构清晰

13 KiB

Raw Blame History