AIclinicalresearch/docs/00-系统总体设计/前后端模块化架构设计-V2.md

前后端模块化架构设计 V2.0

版本： V2.3
创建日期： 2025-11-12
实施阶段： Week 23（2025-11-1317）
维护者： 开发团队
状态： ✅ Week 2 Day 6-9 + 平台基础设施 全部完成 ⭐⭐⭐

---

📋 文档说明

本文档是AI临床研究平台的模块化架构设计总纲，定义了：

1. 前端架构：全新的 frontend-v2 模块化架构
2. 后端架构：基于Schema隔离的分层架构
3. 前后端对应关系：模块化的组织方式
4. 开发规范：统一的代码组织和命名规范
5. 实施路线：渐进式的架构改造计划

适用对象：

• 新加入的开发人员（快速了解系统架构）
• AI助手（理解代码组织结构）
• 技术决策者（架构演进参考）

---

🎯 架构演进历史

V1.0 阶段（2025-10之前）

• ❌ 单体前端应用（所有功能耦合）
• ❌ 后端代码平铺（无模块划分）
• ❌ 数据库表全在public schema

V1.5 阶段（2025-11-12完成）

• ✅ 数据库Schema隔离（10个Schema）
• ✅ Prisma多Schema配置
• ✅ 数据100%迁移成功
• ⚠️ 前后端代码仍需模块化

V2.0 阶段（2025-11-13~14完成）⭐

• ✅ 前端模块化架构（frontend-v2）- Day 6-7完成
• ✅ 模块注册机制（权限控制+错误边界+路由守卫）- Day 7完成
• ✅ 后端增量演进架构（legacy/common/modules）- Day 8-9完成
• ✅ 前后端模块对应
• ✅ 支持模块独立开发和部署
• ✅ 所有功能测试通过（包括批处理修复）⭐⭐⭐

V2.1 阶段（2025-11-17完成）⭐⭐⭐ 最新

• ✅ 平台基础设施实施完成（8个核心模块）
• ✅ 存储服务：LocalAdapter + OSSAdapter（预留）
• ✅ 日志系统：Winston + 结构化JSON日志
• ✅ 缓存服务：MemoryCache + Redis（预留）
• ✅ 异步任务：MemoryQueue + DatabaseQueue（预留）
• ✅ 健康检查：Liveness + Readiness + 详细检查
• ✅ 监控指标：数据库连接/内存/API监控
• ✅ 数据库连接池：Serverless优化（防止连接数超限）
• ✅ 环境配置管理：统一的配置加载和验证
• ✅ 适配器模式：零代码环境切换（本地 ↔ 云端）
• ✅ 全部测试验证通过：100%测试覆盖率
• ✅ 代码统计：2,532行新代码，22个新文件
• ✅ 文档完善：11个文档更新，3个报告生成

核心成果：

• 🎯 为云原生部署（阿里云SAE）做好准备
• 🎯 ASL模块开发可直接使用平台能力
• 🎯 支持本地开发和云端部署无缝切换

---

📸 当前架构真实状态（2025-11-17）

⭐ 重要提示：本章节描述当前实际运行的架构状态
适用对象：新开发人员、新AI助手、快速上手
更新频率：架构变更时立即更新

---

🎯 架构概览

【当前状态】增量演进架构（新旧并存）

Frontend-v2 (新)          Backend (混合)              Database (隔离)
    ↓                         ↓                           ↓
顶部导航 + 6模块          legacy/ + common/         10个独立 Schema
   占位                   + modules/asl               (3详细 + 7空)

核心策略：

• ✅ 前端：全新架构（frontend-v2）
• ✅ 后端：新旧并存（legacy保持稳定，新模块标准化）
• ✅ 数据库：Schema隔离完成

---

📁 前端真实架构（Frontend-v2）

目录结构（实际存在）

frontend-v2/
├── src/
│   ├── framework/                      # 🏗️ 框架层（已实现）
│   │   ├── layout/                     
│   │   │   ├── MainLayout.tsx          # ✅ 主布局
│   │   │   ├── TopNavigation.tsx       # ✅ 顶部导航
│   │   │   └── UserMenu.tsx            # ✅ 用户菜单
│   │   │
│   │   ├── modules/                    
│   │   │   ├── moduleRegistry.ts       # ✅ 模块注册中心
│   │   │   ├── ErrorBoundary.tsx       # ✅ 错误边界
│   │   │   └── ModuleErrorFallback.tsx # ✅ 错误回退UI
│   │   │
│   │   ├── router/                     
│   │   │   ├── RouteGuard.tsx          # ✅ 路由守卫
│   │   │   └── PermissionDenied.tsx    # ✅ 权限拒绝页
│   │   │
│   │   └── permission/                 
│   │       ├── PermissionContext.tsx   # ✅ 权限上下文
│   │       ├── usePermission.ts        # ✅ 权限Hook
│   │       └── types.ts                # ✅ 权限类型
│   │
│   ├── modules/                        # 📦 业务模块（占位）
│   │   ├── asl/                        # 🚧 Week 3开发
│   │   │   └── index.tsx               # ✅ 占位页面
│   │   ├── aia/                        # 📋 占位
│   │   ├── pkb/                        # 📋 占位
│   │   ├── dc/                         # 📋 占位
│   │   ├── ssa/                        # 📋 占位
│   │   └── st/                         # 📋 占位
│   │
│   ├── pages/                          
│   │   └── Home.tsx                    # ✅ 首页
│   │
│   └── App.tsx                         # ✅ 应用入口
│
├── package.json                        # ✅ React 19
└── vite.config.ts                      # ✅ Vite配置

当前运行状态：

• ✅ 访问地址：http://localhost:3000
• ✅ 顶部导航显示6个模块
• ✅ 权限控制工作正常（mock premium用户）
• ✅ 路由守卫生效
• ✅ 错误边界正常捕获

---

🗄️ 后端真实架构（Backend）

目录结构（实际存在）⭐ 关键

backend/
├── src/
│   ├── legacy/                         # 🔸 现有业务代码（稳定运行）
│   │   ├── routes/                     # 7个路由文件
│   │   │   ├── agents.ts               # AIA: 智能体路由
│   │   │   ├── conversations.ts        # AIA: 对话路由
│   │   │   ├── chatRoutes.ts           # AIA: 通用对话路由
│   │   │   ├── projects.ts             # AIA: 项目路由
│   │   │   ├── knowledgeBases.ts       # PKB: 知识库路由
│   │   │   ├── batchRoutes.ts          # PKB: 批处理路由
│   │   │   └── reviewRoutes.ts         # RVW: 稿件审查路由
│   │   │
│   │   ├── controllers/                # 8个控制器
│   │   │   ├── agentController.ts
│   │   │   ├── conversationController.ts
│   │   │   ├── chatController.ts
│   │   │   ├── projectController.ts
│   │   │   ├── knowledgeBaseController.ts
│   │   │   ├── documentController.ts
│   │   │   ├── batchController.ts
│   │   │   └── reviewController.ts
│   │   │
│   │   ├── services/                   # 8个服务
│   │   │   ├── agentService.ts
│   │   │   ├── conversationService.ts
│   │   │   ├── projectService.ts
│   │   │   ├── knowledgeBaseService.ts
│   │   │   ├── documentService.ts
│   │   │   ├── batchService.ts
│   │   │   ├── reviewService.ts
│   │   │   └── tokenService.ts
│   │   │
│   │   └── templates/
│   │       └── clinicalResearch.ts     # 批处理模板
│   │
│   ├── common/                         # 🔧 通用能力层（共享）+ ⭐ 平台基础设施（云原生）
│   │   │                               # 📋 详见：docs/09-架构实施/04-平台基础设施规划.md
│   │   ├── llm/                        
│   │   │   └── adapters/               # LLM适配器
│   │   │       ├── DeepSeekAdapter.ts  # ✅ DeepSeek-V3
│   │   │       ├── QwenAdapter.ts      # ✅ Qwen3-72B + Qwen-Long
│   │   │       ├── LLMFactory.ts       # ✅ 工厂类
│   │   │       └── types.ts            # ✅ LLM类型定义
│   │   │
│   │   ├── rag/                        # RAG能力
│   │   │   ├── DifyClient.ts           # ✅ Dify客户端
│   │   │   └── types.ts                # ✅ RAG类型
│   │   │
│   │   ├── document/                   # 文档处理
│   │   │   └── ExtractionClient.ts     # ✅ 文档提取客户端
│   │   │
│   │   ├── storage/                    # ⭐ 存储抽象层（云原生）
│   │   │   ├── StorageAdapter.ts       # ⭐ 接口定义
│   │   │   ├── LocalAdapter.ts         # ⭐ 本地实现
│   │   │   ├── OSSAdapter.ts           # ⭐ OSS实现
│   │   │   ├── StorageFactory.ts       # ⭐ 工厂类
│   │   │   └── index.ts                # ⭐ 统一导出
│   │   │
│   │   ├── logging/                    # ⭐ 日志系统（云原生）
│   │   │   ├── logger.ts               # ⭐ Winston日志配置
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── cache/                      # ⭐ 缓存服务（云原生）
│   │   │   ├── CacheAdapter.ts         # ⭐ 接口定义
│   │   │   ├── MemoryCacheAdapter.ts   # ⭐ 内存实现
│   │   │   ├── RedisCacheAdapter.ts    # ⭐ Redis实现
│   │   │   ├── CacheFactory.ts         # ⭐ 工厂类
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── jobs/                       # ⭐ 异步任务（云原生）
│   │   │   ├── types.ts                # ⭐ 任务类型定义（Job/JobQueue接口）
│   │   │   ├── MemoryQueue.ts          # ⭐ 内存队列实现
│   │   │   ├── JobFactory.ts           # ⭐ 队列工厂类
│   │   │   └── index.ts                # ⭐ 统一导出
│   │   │
│   │   ├── health/                     # ⭐ 健康检查（云原生）
│   │   │   ├── healthCheck.ts          # ⭐ 健康检查路由
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── monitoring/                 # ⭐ 监控指标（云原生）
│   │   │   ├── metrics.ts              # ⭐ 指标收集
│   │   │   └── index.ts                # ⭐ 导出
│   │   │
│   │   ├── middleware/                 
│   │   │   └── validateProject.ts      # ✅ 项目验证中间件
│   │   │
│   │   └── utils/                      
│   │       └── jsonParser.ts           # ✅ JSON解析工具
│   │
│   ├── modules/                        # 🌟 新架构模块（标准化）
│   │   └── asl/                        # ⭐ AI智能文献（占位，Week 3开发）
│   │       └── (空目录，等待开发)
│   │
│   ├── config/                         # ⚙️ 配置层
│   │   ├── database.ts                 # ✅ 数据库配置（⭐ 云原生连接池优化）
│   │   └── env.ts                      # ✅ 环境变量管理（⭐ 统一配置加载）
│   │
│   ├── scripts/                        # 🛠️ 工具脚本
│   │   ├── create-mock-user.ts
│   │   ├── test-dify-client.ts
│   │   └── test-platform-infrastructure.ts  # ⭐ 平台基础设施测试
│   │
│   ├── test-platform-api.ts            # ⭐ 临时测试API（/test/platform）
│   │
│   └── index.ts                        # ✅ 主入口（统一注册）
│
├── config/                             # 外部配置文件
│   └── agents.yaml                     # ✅ 智能体配置（348行）
│
├── prompts/                            # Prompt模板
│   ├── topic_evaluation_system.txt
│   ├── review_editorial_system.txt
│   └── review_methodology_system.txt
│
├── prisma/
│   ├── schema.prisma                   # ✅ 10个Schema定义
│   └── migrations/                     # ✅ 4个迁移文件
│
├── package.json                        # ✅ Fastify + Prisma
└── .env                                # ✅ 环境变量

当前运行状态：

• ✅ 访问地址：http://localhost:3001
• ✅ 健康检查：http://localhost:3001/health (简化版)
• ✅ 健康检查（详细）：http://localhost:3001/health/liveness
• ✅ 健康检查（详细）：http://localhost:3001/health/readiness
• ✅ 测试API：http://localhost:3001/test/platform （验证平台基础设施）
• ✅ Legacy模块（AIA/PKB/RVW）正常运行
• ✅ Common层通用能力可用
• ✅ ⭐ 平台基础设施：8个模块全部测试通过（100%）
• ✅ Modules/asl 占位就绪，等待Week 3开发

主入口（index.ts）实际代码：

// ============================================
// 【旧架构】Legacy 模块 - 保持不变
// ============================================
import { projectRoutes } from './legacy/routes/projects.js';
import { agentRoutes } from './legacy/routes/agents.js';
import { conversationRoutes } from './legacy/routes/conversations.js';
import knowledgeBaseRoutes from './legacy/routes/knowledgeBases.js';
import { chatRoutes } from './legacy/routes/chatRoutes.js';
import { batchRoutes } from './legacy/routes/batchRoutes.js';
import reviewRoutes from './legacy/routes/reviewRoutes.js';

// 注册 Legacy 模块路由
await fastify.register(projectRoutes, { prefix: '/api/v1/aia' });
await fastify.register(agentRoutes, { prefix: '/api/v1/aia' });
await fastify.register(conversationRoutes, { prefix: '/api/v1/aia' });
await fastify.register(chatRoutes, { prefix: '/api/v1/aia' });
await fastify.register(knowledgeBaseRoutes, { prefix: '/api/v1/pkb' });
await fastify.register(batchRoutes, { prefix: '/api/v1/pkb' });
await fastify.register(reviewRoutes, { prefix: '/api/v1/rvw' });

---

🗃️ 数据库真实架构（PostgreSQL 15）

Schema 结构（实际存在）

-- ==================== 平台层 Schema ====================
platform_schema (平台基础表)
  └── users                    # ✅ 用户表（已实现）

-- ==================== 详细 Schema（数据已迁移）====================
aia_schema (AI智能问答)
  ├── projects                 # ✅ 项目表
  ├── agents                   # ✅ 智能体配置表
  ├── conversations            # ✅ 对话表
  └── messages                 # ✅ 消息表

pkb_schema (个人知识库)
  ├── knowledge_bases          # ✅ 知识库表
  ├── documents                # ✅ 文档表
  ├── batch_tasks              # ✅ 批处理任务表
  ├── batch_results            # ✅ 批处理结果表
  └── task_templates           # ✅ 任务模板表

rvw_schema (稿件审查)
  ├── review_tasks             # ✅ 审查任务表
  └── (在public schema中)      # ⚠️ 历史原因

-- ==================== 占位 Schema（数据结构未定义）====================
asl_schema (AI智能文献)         # 🚧 Week 3开发
  └── (空，等待定义)

common_schema (通用工具)         # 📋 占位
dc_schema (数据采集)            # 📋 占位
ssa_schema (统计分析)           # 📋 占位
st_schema (研究工具)            # 📋 占位
admin_schema (运营管理)         # 📋 占位

Prisma Schema 配置：

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  schemas  = [
    "platform_schema",  # ✅ 平台
    "aia_schema",       # ✅ 智能问答
    "pkb_schema",       # ✅ 知识库
    "asl_schema",       # 🚧 智能文献（Week 3）
    "common_schema",    # 📋 占位
    "dc_schema",        # 📋 占位
    "rvw_schema",       # 📋 占位
    "admin_schema",     # 📋 占位
    "ssa_schema",       # 📋 占位
    "st_schema",        # 📋 占位
    "public"            # ✅ 历史遗留
  ]
}

---

🔌 API 真实路由（当前可用）

AIA 模块（AI智能问答）

基础路径：/api/v1/aia

项目管理：
  ✅ GET    /projects              # 获取项目列表
  ✅ POST   /projects              # 创建项目
  ✅ GET    /projects/:id          # 获取项目详情
  ✅ PUT    /projects/:id          # 更新项目
  ✅ DELETE /projects/:id          # 删除项目

智能体管理：
  ✅ GET    /agents                # 获取智能体列表
  ✅ GET    /agents/enabled        # 获取启用的智能体
  ✅ GET    /agents/:id            # 获取智能体详情

对话管理：
  ✅ POST   /conversations         # 创建对话
  ✅ GET    /conversations         # 获取对话列表
  ✅ GET    /conversations/:id     # 获取对话详情
  ✅ POST   /conversations/:id/messages/stream  # 流式发送消息
  ✅ POST   /conversations/:id/messages         # 非流式发送消息
  ✅ DELETE /conversations/:id     # 删除对话

通用对话：
  ✅ POST   /chat/stream           # 通用流式对话
  ✅ POST   /chat                  # 通用非流式对话

PKB 模块（个人知识库）

基础路径：/api/v1/pkb

知识库管理：
  ✅ GET    /knowledge-bases       # 获取知识库列表
  ✅ POST   /knowledge-bases       # 创建知识库
  ✅ GET    /knowledge-bases/:id   # 获取知识库详情
  ✅ PUT    /knowledge-bases/:id   # 更新知识库
  ✅ DELETE /knowledge-bases/:id   # 删除知识库

文档管理：
  ✅ POST   /knowledge-bases/:id/documents       # 上传文档
  ✅ GET    /knowledge-bases/:id/documents       # 获取文档列表
  ✅ DELETE /knowledge-bases/:kbId/documents/:docId  # 删除文档

批处理：
  ✅ POST   /batch/execute                       # 执行批处理任务
  ✅ GET    /batch/tasks/:taskId                 # 获取任务状态
  ✅ GET    /batch/tasks/:taskId/results         # 获取任务结果
  ✅ POST   /batch/tasks/:taskId/retry-failed    # 重试失败项

RVW 模块（稿件审查）

基础路径：/api/v1/rvw

稿件审查：
  ✅ POST   /review/upload         # 上传稿件并开始审查
  ✅ GET    /review/tasks/:taskId  # 查询任务状态
  ✅ GET    /review/tasks/:taskId/report  # 获取完整报告
  ✅ GET    /review/tasks          # 获取任务列表
  ✅ DELETE /review/tasks/:taskId  # 删除任务

系统端点

✅ GET  /health                    # 健康检查
✅ GET  /api/v1                    # API信息

---

📊 技术栈真实配置

前端（Frontend-v2）

{
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "react-router-dom": "^6.x",
  "typescript": "^5.x",
  "vite": "^6.x",
  "antd": "^5.x",
  "tailwindcss": "^3.x"
}

后端（Backend）

{
  "fastify": "^4.x",
  "typescript": "^5.x",
  "prisma": "^6.17.0",
  "@prisma/client": "^6.17.0",
  "tsx": "^4.x",
  "axios": "^1.x",
  "js-yaml": "^4.x",
  "p-queue": "^8.x"
}

数据库

PostgreSQL: 15.x
Schema数量: 10个（3详细 + 7占位）
迁移文件: 4个

LLM 集成（CloseAI）

✅ DeepSeek-V3      (主力，性价比)
✅ Qwen3-72B        (备用，中文理解)
✅ Qwen-Long        (超长上下文1M)
✅ GPT-4o           (可选，高质量)

---

🔄 前后端模块对应关系（当前）

前端模块	后端位置	数据库Schema	API路由	状态
frontend-v2/modules/asl/	backend/modules/asl/	asl_schema	/api/v1/asl/*	🚧 Week 3开发
frontend-v2/modules/aia/	backend/legacy/routes/agents.ts等	aia_schema	/api/v1/aia/*	✅ 运行中
frontend-v2/modules/pkb/	backend/legacy/routes/knowledgeBases.ts等	pkb_schema	/api/v1/pkb/*	✅ 运行中
frontend-v2/modules/rvw/	backend/legacy/routes/reviewRoutes.ts	public + rvw_schema	/api/v1/rvw/*	✅ 运行中
frontend-v2/modules/dc/	(未实现)	dc_schema	/api/v1/dc/*	📋 占位
frontend-v2/modules/ssa/	(未实现)	ssa_schema	/api/v1/ssa/*	📋 占位
frontend-v2/modules/st/	(未实现)	st_schema	/api/v1/st/*	📋 占位

---

📋 功能测试清单（已验证）

功能	测试项	状态	备注
智能问答	创建项目	✅
智能问答	对话模式	✅	流式+非流式
智能问答	知识库模式	✅	RAG检索
智能问答	批处理模式	✅	修复rawOutput问题后正常
知识库	创建知识库	✅
知识库	上传文档	✅	PDF/Word/TXT/MD
知识库	文档管理	✅	列表/删除
稿件审查	上传稿件	✅
稿件审查	审查报告	✅
前端	顶部导航	✅	6个模块
前端	权限控制	✅	mock premium
前端	路由守卫	✅
前端	错误边界	✅

---

🎯 新模块开发指南（以ASL为例）

开发流程（Week 3）：

第1步：数据库设计
  ├─ 设计 asl_schema 表结构
  ├─ 在 Prisma schema 中定义模型
  └─ 运行迁移创建表

第2步：后端开发
  ├─ 在 backend/src/modules/asl/ 下开发
  ├─ 创建 routes/（路由）
  ├─ 创建 controllers/（控制器）
  ├─ 创建 services/（服务）
  └─ 注册路由到 index.ts

第3步：前端开发
  ├─ 在 frontend-v2/src/modules/asl/ 下开发
  ├─ 创建 pages/（页面）
  ├─ 创建 components/（组件）
  ├─ 创建 api/（API调用）
  └─ 更新 index.tsx（模块注册）

第4步：联调测试
  ├─ 前后端联调
  └─ 功能验收

---

📚 相关文档索引

快速上手：

• ⭐ 本文档 - 架构总纲 + 当前状态
• ⭐ docs/09-架构实施/后端架构增量演进方案.md - 后端详细说明（450行）

任务记录：

• docs/08-项目管理/下一阶段行动计划-V2.2-完整版.md - 项目计划
• docs/09-架构实施/前端模块注册机制实施报告.md - 前端任务17（Week 2 Day 6-7）
• docs/08-项目管理/2025-11-14-任务19完成总结.md - 后端任务19（Week 2 Day 8-9）
• docs/08-项目管理/03-每周计划/2025-11-17-平台基础设施实施完成报告.md - ⭐ 平台基础设施实施
• docs/08-项目管理/03-每周计划/2025-11-17-平台基础设施验证报告.md - ⭐ 验证测试报告

技术规范：

• docs/04-开发规范/08-云原生开发规范.md - ⭐ 云原生开发规范（必读）
• docs/04-开发规范/06-Git提交规范.md - Git提交规范（含提交频率规则）
• docs/09-架构实施/编码规范-UTF8最佳实践.md - 编码规范
• .editorconfig - 编辑器配置
• .gitattributes - Git配置

---

本章节更新日期： 2025-11-17
下次更新时机： ASL模块开发完成后
最新变更： 添加平台基础设施实施和验证状态（V2.1阶段）

---

⚙️ 平台基础设施（2025-11-17 新增）✅

⭐ 重要提示：平台基础设施提供云原生的通用能力，所有业务模块直接复用
详细规划： 参见 平台基础设施规划
使用指南： 参见 backend/src/common/README.md
开发规范： 参见 云原生开发规范

---

🎯 设计目标

核心原则： 通过**适配器模式（Adapter Pattern）**实现本地开发和云端部署零代码切换

┌─────────────────────────────────────────────────────────┐
│                   业务模块层                             │
│   ASL | AIA | PKB | DC | SSA | ST | UAM                │
│   只关注业务逻辑，复用平台能力                            │
└─────────────────────────────────────────────────────────┘
                    ↓ import from '@/common/'
┌─────────────────────────────────────────────────────────┐
│              平台基础设施层（Adapter Pattern）            │
├─────────────────────────────────────────────────────────┤
│ 存储：LocalAdapter ←→ OSSAdapter                        │
│ 缓存：MemoryCacheAdapter ←→ RedisCacheAdapter           │
│ 任务：MemoryQueueAdapter ←→ DatabaseQueueAdapter        │
│ 日志：ConsoleLogger ←→ 阿里云SLS                         │
│ 数据库：本地PostgreSQL ←→ 阿里云RDS（连接池）            │
└─────────────────────────────────────────────────────────┘
                    ↓ 环境变量切换
┌─────────────────────────────────────────────────────────┐
│         部署环境（零代码改动）                            │
│  本地开发 | 云端SaaS | 私有化部署 | 单机版               │
└─────────────────────────────────────────────────────────┘

---

📦 核心模块清单

模块	路径	状态	说明	环境切换
存储服务	common/storage/	✅ 完成	文件上传下载	STORAGE_TYPE=local/oss
数据库连接池	config/database.ts	✅ 完成	Prisma连接池	DATABASE_URL
日志系统	common/logging/	✅ 完成	结构化日志	自动切换（根据NODE_ENV）
环境配置	config/env.ts	✅ 完成	统一配置管理	.env文件或环境变量
异步任务	common/jobs/	✅ 完成	长时间任务处理	QUEUE_TYPE=memory/database
缓存服务	common/cache/	✅ 完成	内存/Redis缓存	CACHE_TYPE=memory/redis
健康检查	common/health/	✅ 完成	SAE健康检查	N/A
监控指标	common/monitoring/	✅ 完成	关键指标监控	N/A

---

💻 使用示例

1. 存储服务（零代码切换）

import { storage } from '@/common/storage'

// 业务代码（完全相同）
const buffer = await readFile('example.pdf')
const url = await storage.upload('literature/123.pdf', buffer)

// 环境切换：
// 本地开发：STORAGE_TYPE=local → 存储到 backend/uploads/
// 云端部署：STORAGE_TYPE=oss → 存储到阿里云OSS

2. 日志系统（结构化日志）

import { logger } from '@/common/logging'

// 基础日志
logger.info('User logged in', { userId: 123 })
logger.error('Database error', { error: err.message })

// 带上下文的日志
const aslLogger = logger.child({ module: 'ASL', projectId: 456 })
aslLogger.info('Screening started', { count: 100 })

// 输出格式：
// 本地开发：彩色可读格式
// 生产环境：JSON格式（便于阿里云SLS解析）

3. 异步任务（避免Serverless超时）

import { jobQueue } from '@/common/jobs'

// 创建任务（立即返回）
const job = await jobQueue.push('asl:screening', {
  projectId: 123,
  literatureIds: [1, 2, 3]
})

// 返回任务ID给前端
res.send({ jobId: job.id })

// 前端轮询任务状态
const status = await jobQueue.getJob(job.id)
// { status: 'processing', progress: 45 }

4. 缓存服务（减少LLM调用成本）

import { cache } from '@/common/cache'

// 缓存LLM响应（1小时）
const cacheKey = `llm:${model}:${hash(prompt)}`
const cached = await cache.get(cacheKey)

if (!cached) {
  const response = await llm.chat(prompt)
  await cache.set(cacheKey, response, 60 * 60)
  return response
}

return cached

---

🌍 多环境配置

本地开发（.env.development）

# 存储：本地文件系统
STORAGE_TYPE=local
LOCAL_STORAGE_DIR=uploads

# 缓存：内存缓存
CACHE_TYPE=memory

# 任务队列：内存队列
QUEUE_TYPE=memory

# 日志：彩色输出
LOG_LEVEL=debug

云端部署（.env.production）

# 存储：阿里云OSS
STORAGE_TYPE=oss
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-prod
OSS_ACCESS_KEY_ID=your-key-id
OSS_ACCESS_KEY_SECRET=your-key-secret

# 缓存：阿里云Redis
CACHE_TYPE=redis
REDIS_HOST=r-xxx.redis.aliyuncs.com
REDIS_PORT=6379
REDIS_PASSWORD=your-password

# 任务队列：数据库队列
QUEUE_TYPE=database

# 日志：JSON输出
LOG_LEVEL=info

---

⚠️ 重要注意事项

1. Winston依赖未安装

# 需要安装
cd backend
npm install winston
npm install -D @types/winston

2. Legacy模块兼容性

• ✅ Legacy模块（PKB、AIA、DC）保持现状，正常运行
• ✅ 新模块（ASL）使用平台基础设施
• 🔄 可选迁移：Legacy模块按需迁移（预计5小时）

3. 云端实现预留

• OSSAdapter、RedisCacheAdapter 当前为预留实现
• 云端部署前需安装依赖并取消注释
• 详见实施文档

---

📚 相关文档

• 详细规划： 平台基础设施规划
• 使用指南： backend/src/common/README.md
• 实施报告： 2025-11-17-平台基础设施实施完成报告
• 验证报告： 2025-11-17-平台基础设施验证报告 ⭐ 新增
• 开发规范： 云原生开发规范

---

✅ 测试验证状态（2025-11-17）

测试覆盖率： 100%（8/8模块全部通过）

模块	测试状态	测试端点/方法	结果
存储服务	✅ 通过	storage.upload/download/delete/exists	功能正常
日志系统	✅ 通过	logger.info/warn/error + context	输出正确
缓存服务	✅ 通过	cache.set/get/has/delete/mset/mget	全部正常
异步任务	✅ 通过	jobQueue.push/getJob/process	队列工作正常
健康检查	✅ 通过	/health/liveness, /health/readiness	200 OK
数据库连接池	✅ 通过	连接数监控、优雅关闭	1/400连接
环境配置	✅ 通过	config 对象加载	所有变量正常
监控指标	✅ 通过	Metrics.recordDBConnectionCount()	数据采集正常

测试方式：

• 单元测试：通过测试API /test/platform 自动化验证
• 集成测试：所有模块实际调用验证
• 健康检查：3个端点全部响应正常

下一步：

• ✅ 本地开发环境已就绪，可以开始ASL模块开发
• 🔄 云端部署需要安装 ali-oss 和 ioredis 依赖

---

🌥️ 云原生部署架构（2025-11-16 新增）

⭐ 重要提示：本章节定义平台的云原生部署策略，适用于所有业务模块
详细指南： 参见 云原生部署架构指南
开发规范： 参见 云原生开发规范

---

🎯 部署架构选型

目标平台：阿里云 Serverless 应用引擎 (SAE) + 云数据库 RDS + 对象存储 OSS

选型理由：

• ✅ 按需付费：初期成本低（¥500/月起），无需预付大量服务器成本
• ✅ 自动扩缩容：高峰期不宕机，低谷期不浪费，适合创业公司流量不确定的场景
• ✅ 国内访问优化：阿里云国内节点多，医疗用户访问速度快
• ✅ 适合AI任务：异步批量任务（LLM筛选、PDF提取）天然契合 Serverless
• ✅ 降低运维成本：无需专职运维人员，团队专注业务开发

架构图：

┌──────────────────────────────────────────────────┐
│              云原生部署架构                         │
├──────────────────────────────────────────────────┤
│  用户浏览器                                        │
│     ↓                                            │
│  CDN加速（可选）                                   │
│     ↓                                            │
│  阿里云 SAE (Serverless 应用引擎)                 │
│  ├── 自动扩缩容（0-100实例）                      │
│  ├── 内置负载均衡                                 │
│  └── Docker 容器运行                             │
│     ↓                                            │
│  云数据库 RDS (PostgreSQL 15)                    │
│  ├── 10个Schema隔离                              │
│  ├── 自动备份                                     │
│  └── 连接池管理                                   │
│     ↓                                            │
│  对象存储 OSS                                     │
│  ├── PDF/Excel 文件存储                          │
│  ├── 11个9可靠性                                 │
│  └── 内网访问免流量费                             │
└──────────────────────────────────────────────────┘

---

🏗️ 核心设计原则（所有模块必须遵守）

原则1：无状态应用设计

要求：应用不能依赖本地文件系统或内存状态

禁止做法 ❌	正确做法 ✅	说明
文件存储到 ./uploads/	上传到 OSS 或 内存处理	容器重启会丢失本地文件
Session 存内存	Session 存 Redis/数据库	多实例间无法共享内存
缓存存内存变量	使用 Redis	扩容后缓存失效
依赖 /tmp 长期存储	用完立即删除	/tmp 容量有限且不持久

示例：

// ❌ 禁止：本地文件存储
fs.writeFileSync('./uploads/file.pdf', buffer)

// ✅ 正确：OSS存储或内存处理
const storage = StorageFactory.create()
const url = await storage.upload('files/file.pdf', buffer)

---

原则2：存储抽象层设计

要求：通过抽象层支持本地开发 + 云端部署无缝切换

架构：

StorageFactory
    ↓
StorageAdapter (接口)
    ↓
├── LocalAdapter (本地开发)
└── OSSAdapter (生产环境)

使用：

// 代码中统一使用工厂类，环境自动切换
const storage = StorageFactory.create()
const url = await storage.upload(key, buffer)

环境配置：

# 本地开发
STORAGE_TYPE=local

# 生产环境
STORAGE_TYPE=oss

---

原则3：数据库连接池管理

风险：Serverless 扩容后连接数暴增，超过 RDS 最大连接数

解决方案：

// 计算公式：每实例连接数 = RDS最大连接数 / SAE最大实例数
// 示例：RDS 400连接 / SAE 20实例 = 每实例20连接

const prisma = new PrismaClient({
  connectionPool: {
    connectionLimit: 20,      // 每实例最多20连接
    idleTimeout: 60000,       // 空闲60秒释放
    maxWait: 5000,            // 等待最多5秒
  }
})

监控：定期检查数据库连接数，接近上限时告警

---

原则4：环境变量配置

要求：所有配置（密钥、IP、端口）必须通过环境变量管理

# ❌ 禁止硬编码
const apiKey = 'sk-xxx'
const dbHost = '192.168.1.100'

# ✅ 环境变量
const apiKey = process.env.LLM_API_KEY
const dbHost = process.env.DB_HOST

---

原则5：异步任务处理

风险：SAE 默认请求超时 30 秒

解决方案：长时间任务（> 10秒）必须异步处理

// ✅ 正确：异步任务模式
app.post('/screening/start', async (req, res) => {
  const task = await prisma.aslScreeningTask.create({...})
  res.send({ taskId: task.id })  // 立即返回
  
  // 后台执行
  processScreeningAsync(task.id)
})

// 前端轮询进度
app.get('/screening/tasks/:id', async (req, res) => {
  const task = await prisma.aslScreeningTask.findUnique({...})
  res.send({ progress: task.completedItems / task.totalItems })
})

---

📊 开发环境 vs 生产环境

本地开发环境（无需云服务）

# 使用 Docker 本地服务
docker run -d --name postgres -p 5432:5432 postgres:15
docker run -d --name redis -p 6379:6379 redis:7

# 环境变量
STORAGE_TYPE=local
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/dev_db

优势：

• ✅ 完全离线开发
• ✅ 无云服务费用
• ✅ 调试方便

---

生产环境（阿里云）

# SAE 控制台配置环境变量
STORAGE_TYPE=oss
DATABASE_URL=postgresql://user:pass@rm-xxx.aliyuncs.com:5432/prod_db
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-prod

切换方式：

• ✅ 代码零改动
• ✅ 仅修改环境变量
• ✅ 重新部署即可

---

🚀 部署流程（简要）

1. 本地开发：使用 Docker + LocalAdapter
2. 代码提交：Git push
3. 构建镜像：Docker build
4. 推送镜像：推送到阿里云容器镜像服务
5. SAE 部署：配置环境变量，自动拉取镜像部署
6. 验证部署：健康检查通过，流量切换

详细流程见：云原生部署架构指南

---

📋 开发检查清单

在提交代码前，请确认：

• 是否使用 StorageFactory 而非直接 fs.writeFile？
• 是否使用全局 prisma 实例而非新建连接？
• 是否所有配置都从环境变量读取？
• 是否长时间任务都改为异步处理？
• 是否日志都输出到 stdout？
• 是否 /tmp 目录使用后立即清理？
• 是否避免依赖本地文件路径？

完整检查清单见：云原生开发规范

---

📚 相关文档

• ⭐ 云原生部署架构指南 - 包含完整代码示例和部署流程
• ⭐ 云原生开发规范 - DO/DON'T 检查清单
• Schema隔离架构设计
• 数据库连接配置

---

本章节创建日期： 2025-11-16
维护者： 架构团队
适用范围： 所有业务模块（ASL、AIA、PKB、DC等）

---

🏗️ 整体架构设计

系统架构图

┌─────────────────────────────────────────────────────────────────┐
│                         AI临床研究平台                            │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┴─────────────────────┐
        │                                           │
   ┌────▼─────┐                              ┌─────▼────┐
   │  前端层   │                              │  后端层   │
   │frontend-v2│◄────────── HTTP API ────────►│ backend  │
   └──────────┘                              └──────────┘
        │                                           │
        │ 模块化                                    │ 模块化 + Schema隔离
        │                                           │
   ┌────┴────────────────────────┐         ┌───────┴──────────────────┐
   │                             │         │                          │
   │  ┌─────┐  ┌─────┐  ┌─────┐ │         │  ┌─────────────────────┐ │
   │  │ ASL │  │ AIA │  │ PKB │ │         │  │ PostgreSQL          │ │
   │  │模块 │  │模块 │  │模块 │ │         │  │  ┌─────────────────┐│ │
   │  └─────┘  └─────┘  └─────┘ │         │  │  │ platform_schema ││ │
   │  ┌─────┐  ┌─────┐          │         │  │  │ aia_schema      ││ │
   │  │ RVW │  │ DC  │  ...     │         │  │  │ pkb_schema      ││ │
   │  │模块 │  │模块 │          │         │  │  │ asl_schema      ││ │
   │  └─────┘  └─────┘          │         │  │  │ ...             ││ │
   │                             │         │  │  └─────────────────┘│ │
   └─────────────────────────────┘         │  └─────────────────────┘ │
                                           └──────────────────────────┘

---

📁 前端架构设计（frontend-v2）

设计原则

1. 彻底的模块化 - 每个业务模块完全独立
2. 框架与业务分离 - 框架层提供基础能力，业务模块专注功能
3. 渐进式开发 - 新架构与旧代码并存，逐步替换
4. 独立部署支持 - 模块可独立打包和部署

目录结构

frontend-v2/
├── src/
│   ├── framework/                      # 🏗️ 框架层（平台级基础设施）
│   │   │
│   │   ├── layout/                     # 布局系统
│   │   │   ├── MainLayout.tsx          # 主布局（顶部导航+内容区）
│   │   │   ├── TopNavigation.tsx       # 顶部导航栏
│   │   │   ├── UserMenu.tsx            # 用户菜单
│   │   │   └── ModuleContainer.tsx     # 模块容器
│   │   │
│   │   ├── modules/                    # 模块管理系统
│   │   │   ├── moduleRegistry.ts       # 模块注册中心
│   │   │   ├── ModuleLoader.tsx        # 动态模块加载器
│   │   │   ├── types.ts                # 模块接口定义
│   │   │   └── config.ts               # 模块配置
│   │   │
│   │   ├── router/                     # 路由系统
│   │   │   ├── AppRouter.tsx           # 应用路由配置
│   │   │   ├── RouteGuard.tsx          # 路由守卫
│   │   │   └── routes.ts               # 路由定义
│   │   │
│   │   ├── permission/                 # 权限控制（预留）
│   │   │   ├── PermissionProvider.tsx  # 权限上下文
│   │   │   ├── usePermission.ts        # 权限Hook
│   │   │   └── config.ts               # 权限配置
│   │   │
│   │   └── config/                     # 全局配置
│   │       ├── env.ts                  # 环境变量
│   │       ├── api.ts                  # API配置
│   │       └── theme.ts                # 主题配置
│   │
│   ├── modules/                        # 📦 业务模块（完全独立）
│   │   │
│   │   ├── asl/                        # ⭐ AI智能文献模块（优先开发）
│   │   │   ├── index.tsx               # 模块入口（导出ModuleDefinition）
│   │   │   ├── routes.tsx              # 模块路由配置
│   │   │   │
│   │   │   ├── layouts/                # 模块布局
│   │   │   │   └── ASLLayout.tsx       # ASL左侧导航布局
│   │   │   │
│   │   │   ├── pages/                  # 模块页面
│   │   │   │   ├── ProjectList.tsx            # 项目列表
│   │   │   │   ├── ProjectCreate.tsx          # 创建项目
│   │   │   │   ├── TitleScreening/            # 标题摘要初筛
│   │   │   │   │   ├── index.tsx
│   │   │   │   │   ├── ScreeningWorkbench.tsx
│   │   │   │   │   └── ResultsView.tsx
│   │   │   │   ├── FullTextScreening/         # 全文复筛
│   │   │   │   │   └── ...
│   │   │   │   ├── DataExtraction/            # 数据提取
│   │   │   │   │   └── ...
│   │   │   │   └── Analysis/                  # 综合分析
│   │   │   │       └── ...
│   │   │   │
│   │   │   ├── components/             # 模块组件（仅本模块使用）
│   │   │   │   ├── LiteratureCard.tsx
│   │   │   │   ├── ScreeningPanel.tsx
│   │   │   │   ├── LLMSelector.tsx
│   │   │   │   └── ...
│   │   │   │
│   │   │   ├── api/                    # 模块API（对接后端）
│   │   │   │   ├── projectApi.ts
│   │   │   │   ├── screeningApi.ts
│   │   │   │   ├── extractionApi.ts
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   ├── hooks/                  # 模块Hooks
│   │   │   │   ├── useProject.ts
│   │   │   │   ├── useScreening.ts
│   │   │   │   └── useLLMScreening.ts
│   │   │   │
│   │   │   ├── store/                  # 模块状态管理
│   │   │   │   ├── projectStore.ts
│   │   │   │   ├── screeningStore.ts
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   ├── types/                  # 模块类型定义
│   │   │   │   ├── project.ts
│   │   │   │   ├── literature.ts
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   └── utils/                  # 模块工具函数
│   │   │       ├── fileParser.ts
│   │   │       └── exportHelper.ts
│   │   │
│   │   ├── aia/                        # 📋 AI智能问答模块（后续重写）
│   │   │   ├── index.tsx
│   │   │   └── Placeholder.tsx         # 临时占位页面
│   │   │
│   │   ├── pkb/                        # 📋 个人知识库模块（后续重写）
│   │   │   ├── index.tsx
│   │   │   └── Placeholder.tsx
│   │   │
│   │   ├── rvw/                        # 📋 审稿系统模块（后续重写）
│   │   │   ├── index.tsx
│   │   │   └── Placeholder.tsx
│   │   │
│   │   └── dc/                         # 📋 数据清洗模块（占位）
│   │       ├── index.tsx
│   │       └── Placeholder.tsx
│   │
│   ├── shared/                         # 🔧 共享资源（跨模块使用）
│   │   ├── components/                 # 通用UI组件
│   │   │   ├── Button/
│   │   │   ├── Table/
│   │   │   ├── Modal/
│   │   │   └── ...
│   │   │
│   │   ├── hooks/                      # 通用Hooks
│   │   │   ├── useDebounce.ts
│   │   │   ├── useAsync.ts
│   │   │   └── ...
│   │   │
│   │   ├── utils/                      # 工具函数
│   │   │   ├── date.ts
│   │   │   ├── format.ts
│   │   │   ├── validation.ts
│   │   │   └── ...
│   │   │
│   │   └── api/                        # API客户端
│   │       ├── client.ts               # Axios实例
│   │       ├── request.ts              # 请求拦截器
│   │       └── types.ts                # API类型
│   │
│   ├── App.tsx                         # 应用根组件
│   ├── main.tsx                        # 应用入口
│   └── vite-env.d.ts
│
├── public/                             # 静态资源
├── package.json
├── vite.config.ts                      # Vite配置
├── tsconfig.json                       # TypeScript配置
├── tailwind.config.js                  # Tailwind配置
└── README.md

模块定义接口

// framework/modules/types.ts

/**
 * 模块定义接口
 * 每个业务模块必须实现这个接口
 */
export interface ModuleDefinition {
  /** 模块唯一标识 */
  id: string
  
  /** 模块名称（显示在导航栏） */
  name: string
  
  /** 模块路由前缀 */
  path: string
  
  /** 模块图标（可选） */
  icon?: ReactNode
  
  /** 模块入口组件（懒加载） */
  component: LazyExoticComponent<ComponentType<any>>
  
  /** 模块路由配置 */
  routes?: RouteObject[]
  
  /** 模块是否有左侧导航 */
  hasSideNav?: boolean
  
  /** 左侧导航配置（如果有） */
  sideNavConfig?: SideNavItem[]
  
  /** 权限要求（可选） */
  requiredVersion?: UserVersion
  
  /** 是否为占位模块 */
  placeholder?: boolean
  
  /** 是否支持独立部署 */
  standalone?: boolean
}

/**
 * 左侧导航项
 */
export interface SideNavItem {
  id: string
  label: string
  path: string
  icon?: ReactNode
  children?: SideNavItem[]
}

模块注册示例

// modules/asl/index.tsx

import { lazy } from 'react'
import { ModuleDefinition } from '@/framework/modules/types'
import routes from './routes'
import { sideNavConfig } from './config'

const ASLModule: ModuleDefinition = {
  id: 'asl',
  name: 'AI智能文献',
  path: '/literature',
  icon: <FileTextOutlined />,
  component: lazy(() => import('./layouts/ASLLayout')),
  routes,
  hasSideNav: true,
  sideNavConfig,
  requiredVersion: 'advanced',
}

export default ASLModule

模块路由示例

// modules/asl/routes.tsx

import { lazy } from 'react'
import { RouteObject } from 'react-router-dom'

const routes: RouteObject[] = [
  {
    path: '',
    element: lazy(() => import('./pages/ProjectList')),
  },
  {
    path: 'project/:projectId',
    children: [
      {
        path: 'title-screening',
        element: lazy(() => import('./pages/TitleScreening')),
      },
      {
        path: 'fulltext-screening',
        element: lazy(() => import('./pages/FullTextScreening')),
      },
      {
        path: 'extraction',
        element: lazy(() => import('./pages/DataExtraction')),
      },
      {
        path: 'analysis',
        element: lazy(() => import('./pages/Analysis')),
      },
    ],
  },
]

export default routes

---

📁 后端架构设计（backend）

设计原则

1. Schema隔离 - 数据库层面的模块隔离（已完成）
2. 代码分层 - platform/common/modules三层架构
3. 模块独立 - 每个模块的API和逻辑独立
4. 保持兼容 - 轻度重构，不破坏现有功能

目录结构

backend/
├── src/
│   ├── platform/                       # 🏛️ 平台层（基础设施）
│   │   ├── auth/                       # 认证授权
│   │   │   ├── authController.ts
│   │   │   ├── authService.ts
│   │   │   ├── authMiddleware.ts
│   │   │   └── routes.ts
│   │   │
│   │   └── users/                      # 用户管理
│   │       ├── userController.ts
│   │       ├── userService.ts
│   │       └── routes.ts
│   │
│   ├── common/                         # 🔧 通用层（共享能力）
│   │   ├── middleware/                 # 中间件
│   │   │   ├── errorHandler.ts
│   │   │   ├── logger.ts
│   │   │   ├── validation.ts
│   │   │   └── cors.ts
│   │   │
│   │   ├── utils/                      # 工具函数
│   │   │   ├── date.ts
│   │   │   ├── encryption.ts
│   │   │   └── format.ts
│   │   │
│   │   ├── errors/                     # 错误处理
│   │   │   ├── AppError.ts
│   │   │   ├── errorTypes.ts
│   │   │   └── errorHandler.ts
│   │   │
│   │   └── types/                      # 通用类型
│   │       ├── request.ts
│   │       ├── response.ts
│   │       └── common.ts
│   │
│   ├── modules/                        # 📦 业务模块
│   │   │
│   │   ├── aia/                        # AI智能问答模块
│   │   │   ├── controllers/            # 控制器
│   │   │   │   ├── projectController.ts
│   │   │   │   ├── agentController.ts
│   │   │   │   ├── conversationController.ts
│   │   │   │   └── chatController.ts
│   │   │   │
│   │   │   ├── services/               # 业务逻辑
│   │   │   │   ├── projectService.ts
│   │   │   │   ├── conversationService.ts
│   │   │   │   └── llmService.ts
│   │   │   │
│   │   │   ├── routes/                 # 路由配置
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   ├── types/                  # 模块类型
│   │   │   │   ├── project.ts
│   │   │   │   └── conversation.ts
│   │   │   │
│   │   │   └── utils/                  # 模块工具
│   │   │       └── prompt.ts
│   │   │
│   │   ├── pkb/                        # 个人知识库模块
│   │   │   ├── controllers/
│   │   │   │   ├── knowledgeBaseController.ts
│   │   │   │   ├── documentController.ts
│   │   │   │   └── batchController.ts
│   │   │   │
│   │   │   ├── services/
│   │   │   │   ├── kbService.ts
│   │   │   │   ├── documentService.ts
│   │   │   │   ├── batchService.ts
│   │   │   │   └── difyService.ts
│   │   │   │
│   │   │   ├── routes/
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   └── types/
│   │   │       ├── knowledgeBase.ts
│   │   │       └── document.ts
│   │   │
│   │   ├── rvw/                        # 审稿系统模块
│   │   │   ├── controllers/
│   │   │   │   └── reviewController.ts
│   │   │   │
│   │   │   ├── services/
│   │   │   │   ├── reviewService.ts
│   │   │   │   └── extractionService.ts
│   │   │   │
│   │   │   ├── routes/
│   │   │   │   └── index.ts
│   │   │   │
│   │   │   └── types/
│   │   │       └── review.ts
│   │   │
│   │   └── asl/                        # ⭐ AI智能文献模块（Week 3新建）
│   │       ├── controllers/
│   │       │   ├── projectController.ts
│   │       │   ├── literatureController.ts
│   │       │   ├── screeningController.ts
│   │       │   └── extractionController.ts
│   │       │
│   │       ├── services/
│   │       │   ├── projectService.ts
│   │       │   ├── literatureService.ts
│   │       │   ├── screeningService.ts
│   │       │   ├── llmScreeningService.ts
│   │       │   └── extractionService.ts
│   │       │
│   │       ├── routes/
│   │       │   └── index.ts
│   │       │
│   │       ├── types/
│   │       │   ├── project.ts
│   │       │   ├── literature.ts
│   │       │   └── screening.ts
│   │       │
│   │       └── utils/
│   │           ├── fileParser.ts
│   │           ├── llmPrompts.ts
│   │           └── exportHelper.ts
│   │
│   ├── config/                         # 配置文件（现有）
│   │   ├── database.ts
│   │   ├── env.ts
│   │   └── ...
│   │
│   └── index.ts                        # 应用入口
│
├── prisma/
│   └── schema.prisma                   # Prisma Schema（已配置10个Schema）
│
├── package.json
└── tsconfig.json

模块路由注册

// src/index.ts

import { platformRoutes } from './platform/routes'
import { aiaRoutes } from './modules/aia/routes'
import { pkbRoutes } from './modules/pkb/routes'
import { rvwRoutes } from './modules/rvw/routes'
import { aslRoutes } from './modules/asl/routes'

// 注册平台路由
fastify.register(platformRoutes, { prefix: '/api/v1/platform' })

// 注册业务模块路由
fastify.register(aiaRoutes, { prefix: '/api/v1/aia' })
fastify.register(pkbRoutes, { prefix: '/api/v1/pkb' })
fastify.register(rvwRoutes, { prefix: '/api/v1/rvw' })
fastify.register(aslRoutes, { prefix: '/api/v1/asl' })

---

🔗 前后端对应关系

模块映射表

前端模块	后端模块	数据库Schema	路由前缀	开发状态
frontend-v2/src/modules/asl/	backend/src/modules/asl/	asl_schema	/api/v1/asl/*	🚧 Week 3开发
frontend-v2/src/modules/aia/	backend/src/modules/aia/	aia_schema	/api/v1/aia/*	📋 后续重写
frontend-v2/src/modules/pkb/	backend/src/modules/pkb/	pkb_schema	/api/v1/pkb/*	📋 后续重写
frontend-v2/src/modules/rvw/	backend/src/modules/rvw/	public.review_tasks	/api/v1/rvw/*	📋 后续重写
frontend-v2/src/modules/dc/	backend/src/modules/dc/	dc_schema	/api/v1/dc/*	📋 占位

API调用示例

// 前端：frontend-v2/src/modules/asl/api/projectApi.ts
import { apiClient } from '@/shared/api/client'

export const aslProjectApi = {
  // 创建项目
  create: (data: CreateProjectDTO) => 
    apiClient.post('/api/v1/asl/projects', data),
  
  // 获取项目列表
  list: () => 
    apiClient.get('/api/v1/asl/projects'),
  
  // 获取项目详情
  getById: (id: string) => 
    apiClient.get(`/api/v1/asl/projects/${id}`),
}

// 后端：backend/src/modules/asl/routes/index.ts
import { FastifyInstance } from 'fastify'
import { aslProjectController } from '../controllers/projectController'

export async function aslRoutes(fastify: FastifyInstance) {
  fastify.post('/projects', aslProjectController.create)
  fastify.get('/projects', aslProjectController.list)
  fastify.get('/projects/:id', aslProjectController.getById)
}

---

📐 开发规范

命名规范

前端

文件命名：

• 组件：PascalCase（ProjectList.tsx）
• Hooks：camelCase + use前缀（useProject.ts）
• 工具函数：camelCase（formatDate.ts）
• 类型定义：PascalCase（Project.ts）

代码命名：

• 组件：PascalCase（ProjectList）
• 函数：camelCase（fetchProjects）
• 常量：UPPER_SNAKE_CASE（API_BASE_URL）
• 接口：PascalCase + I前缀（IProject）
• 类型：PascalCase（Project）

后端

文件命名：

• Controller：camelCase + Controller后缀（projectController.ts）
• Service：camelCase + Service后缀（projectService.ts）
• Routes：index.ts 或 routes.ts
• Types：camelCase（project.ts）

代码命名：

• 类：PascalCase（ProjectService）
• 函数：camelCase（createProject）
• 常量：UPPER_SNAKE_CASE（MAX_FILE_SIZE）
• 接口：PascalCase（ProjectDTO）

模块开发规范

1. 新模块开发流程

第一步：数据库设计
├─ 在 docs/03-业务模块/[模块名]/02-技术设计/01-数据库设计.md
├─ 设计表结构
├─ 在 Prisma schema 中定义模型
└─ 运行迁移

第二步：后端开发
├─ 创建 backend/src/modules/[模块名]/
├─ 编写 controllers/
├─ 编写 services/
├─ 编写 routes/
└─ 测试 API

第三步：前端开发
├─ 创建 frontend-v2/src/modules/[模块名]/
├─ 定义模块接口（index.tsx）
├─ 编写 pages/
├─ 编写 components/
├─ 编写 api/
├─ 编写 hooks/
└─ 测试功能

第四步：集成测试
├─ 端到端测试
└─ 性能测试

2. 模块独立性原则

DO ✅：

• 模块内的组件只在模块内使用
• 模块有自己的状态管理
• 模块有自己的API调用
• 模块有自己的类型定义
• 模块可以独立运行和部署

DON'T ❌：

• 不要在模块间直接import组件
• 不要在模块间共享状态
• 不要在模块间直接调用API
• 共享的逻辑放在 shared/ 目录

3. API设计规范

RESTful风格：

GET    /api/v1/[module]/resources       # 列表
GET    /api/v1/[module]/resources/:id   # 详情
POST   /api/v1/[module]/resources       # 创建
PUT    /api/v1/[module]/resources/:id   # 更新
DELETE /api/v1/[module]/resources/:id   # 删除

响应格式：

// 成功响应
{
  success: true,
  data: any,
  message?: string
}

// 错误响应
{
  success: false,
  error: {
    code: string,
    message: string,
    details?: any
  }
}

---

🚀 实施计划

Week 2：架构改造（2025-11-13 至 2025-11-17）

Day 6（11-13）：前端架构基础 ⏰ 4-6小时

上午：项目创建和框架层

• 创建 frontend-v2 项目（Vite + React + TS）
• 安装依赖（Antd、Router、Zustand、React Query）
• 配置 Tailwind CSS
• 创建目录结构（framework/modules/shared）
• 实现 TopNavigation.tsx
• 实现 MainLayout.tsx
• 定义模块接口（ModuleDefinition）

下午：模块占位

• 为5个模块创建目录
• 创建 Placeholder.tsx 组件
• 配置基本路由
• 测试导航切换

交付物：

• ✅ 可运行的 frontend-v2 项目
• ✅ 顶部导航正常工作
• ✅ 5个模块占位页面

Day 7（11-14）：模块注册机制 ⏰ 6-8小时

上午：注册系统

• 实现 moduleRegistry.ts
• 实现 ModuleLoader.tsx
• 实现动态路由加载
• 实现懒加载机制

下午：测试和文档

• 测试模块注册
• 测试路由切换
• 编写开发文档
• 更新 README

交付物：

• ✅ 完整的模块注册系统
• ✅ 动态路由加载
• ✅ 开发文档

Day 8-9（11-15 至 11-16）：后端代码分层 ⏰ 1-2天

Day 8 上午：创建目录结构

• 创建 platform/ 目录
• 创建 common/ 目录
• 创建 modules/ 目录

Day 8 下午：迁移 AIA 模块

• 创建 modules/aia/ 结构
• 迁移 projectController.ts
• 迁移 conversationController.ts
• 更新路由注册

Day 9 上午：迁移 PKB 和 RVW

• 迁移 PKB 模块代码
• 迁移 RVW 模块代码
• 更新所有 import 路径

Day 9 下午：测试和文档

• 测试所有 API
• 更新 API 文档
• 编写迁移说明

交付物：

• ✅ 完成后端代码分层
• ✅ 所有API正常工作
• ✅ 更新文档

Day 10（11-17）：Week 2 验收 ⏰ 4小时

• 前端架构验收
• 后端分层验收
• 集成测试
• 编写 Week 2 总结报告
• 规划 Week 3 ASL 任务

---

Week 3-4：ASL模块开发（在新架构下）

在全新的 frontend-v2 和分层后的 backend 中开发 ASL 模块

详见：下一阶段行动计划-V2.2-完整版.md

---

📝 旧代码处理

frontend/ 目录

状态： ⏸️ 保留，不再开发

处理方式：

1. 添加 README-ARCHIVED.md 说明文件
2. 在根目录 package.json 中区分启动命令
3. 保留3-6个月，作为参考和应急备份
4. 新架构稳定后再删除

参考价值：

• UI交互设计
• 某些组件实现
• API调用逻辑
• 业务流程

启动命令

{
  "scripts": {
    "dev:frontend-old": "cd frontend && npm run dev",
    "dev:frontend-new": "cd frontend-v2 && npm run dev",
    "dev:frontend": "npm run dev:frontend-new",
    "dev:backend": "cd backend && npm run dev",
    "dev": "concurrently \"npm run dev:backend\" \"npm run dev:frontend\""
  }
}

---

🎯 成功标准

Week 2 验收标准

前端：

• frontend-v2 项目可运行
• 顶部导航正常工作
• 模块注册系统完整
• 5个模块占位页面
• 路由切换正常
• 完整的开发文档

后端：

• 代码分层完成（platform/common/modules）
• 所有现有API正常工作
• 路由前缀统一（/api/v1/[module]/*）
• import路径全部更新
• API文档更新

文档：

• 本架构设计文档
• 前端开发规范文档
• 后端开发规范文档
• Week 2总结报告

---

📚 相关文档

架构设计

• Schema隔离架构设计（10个）
• 前端总体架构设计
• 导航结构设计

数据库设计

• AIA数据库设计
• PKB数据库设计

实施报告

• Schema迁移完成报告
• Prisma配置完成报告

项目管理

• 下一阶段行动计划-V2.2-完整版

---

🔄 版本历史

版本	日期	变更内容	维护者
V2.0	2025-11-12	创建本文档，定义前后端模块化架构	AI助手
V2.1	2025-11-13	完成权限系统、错误边界、路由守卫实施	AI助手

---

文档维护者： AI助手 + 开发团队
最后更新： 2025-11-13
文档状态： ✅ 已完成，Week 2 Day 7实施完成

🎉 这是系统架构演进的重要里程碑！