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

> **版本�?* V2.3  
> **创建日期�?* 2025-11-12  
> **实施阶段�?* Week 2~3�?025-11-13~17�? 
> **维护者：** 开发团�? 
> **状态：** �?Week 2 Day 6-9 + 平台基础设施 全部完成 ⭐⭐�? 

---

## 📋 文档说明

本文档是**AI临床研究平台的模块化架构设计总纲**，定义了�?
1. **前端架构**：全新的 frontend-v2 模块化架�?2. **后端架构**：基于Schema隔离的分层架�?3. **前后端对应关�?*：模块化的组织方�?4. **开发规�?*：统一的代码组织和命名规范
5. **实施路线**：渐进式的架构改造计�?
**适用对象�?*
- 新加入的开发人员（快速了解系统架构）
- AI助手（理解代码组织结构）
- 技术决策者（架构演进参考）

---

## 🎯 架构演进历史

### V1.0 阶段�?025-10之前�?- �?单体前端应用（所有功能耦合�?- �?后端代码平铺（无模块划分�?- �?数据库表全在public schema

### V1.5 阶段�?025-11-12完成�?- �?**数据库Schema隔离**�?0个Schema�?- �?Prisma多Schema配置
- �?数据100%迁移成功
- ⚠️ 前后端代码仍需模块�?
### V2.0 阶段�?025-11-13~14完成）⭐
- �?**前端模块化架�?*（frontend-v2�? Day 6-7完成
- �?**模块注册机制**（权限控�?错误边界+路由守卫�? Day 7完成
- �?**后端增量演进架构**（legacy/common/modules�? Day 8-9完成
- �?前后端模块对�?- �?支持模块独立开发和部署
- �?**所有功能测试通过**（包括批处理修复）⭐⭐⭐

### V2.1 阶段�?025-11-17完成）⭐⭐⭐ 最�?- �?**平台基础设施实施完成**�?个核心模块）
- �?**存储服务**：LocalAdapter + OSSAdapter（预留）
- �?**日志系统**：Winston + 结构化JSON日志
- �?**缓存服务**：MemoryCache + Redis（预留）
- �?**异步任务**：MemoryQueue + DatabaseQueue（预留）
- �?**健康检�?*：Liveness + Readiness + 详细检�?- �?**监控指标**：数据库连接/内存/API监控
- �?**数据库连接池**：Serverless优化（防止连接数超限�?- �?**环境配置管理**：统一的配置加载和验证
- �?**适配器模�?*：零代码环境切换（本�?�?云端�?- �?**全部测试验证通过**�?00%测试覆盖�?- �?**代码统计**�?,532行新代码�?2个新文件
- �?**文档完善**�?1个文档更新，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�?
#### **目录结构（实际存在）**

```bash
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�?
#### **目录结构（实际存在）�?关键**

```bash
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层通用能力可用
- �?**�?平台基础设施**�?个模块全部测试通过�?00%�?- �?Modules/asl 占位就绪，等待Week 3开�?
**主入口（index.ts）实际代码：**
```typescript
// ============================================
// 【旧架构】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 结构（实际存在）**

```sql
-- ==================== 平台�?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 配置�?*
```prisma
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�?*
```json
{
  "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�?*
```json
{
  "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        (超长上下�?M)
�?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）：**

```
�?步：数据库设�?  ├─ 设计 asl_schema 表结�?  ├─ �?Prisma schema 中定义模�?  └─ 运行迁移创建�?
�?步：后端开�?  ├─ �?backend/src/modules/asl/ 下开�?  ├─ 创建 routes/（路由）
  ├─ 创建 controllers/（控制器�?  ├─ 创建 services/（服务）
  └─ 注册路由�?index.ts

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

�?步：联调测试
  ├─ 前后端联�?  └─ 功能验收
```

---

### 📚 相关文档索引

**快速上手：**
- �?**本文�?* - 架构总纲 + 当前状�?- �?`docs/09-架构实施/后端架构增量演进方案.md` - 后端详细说明�?50行）

**任务记录�?*
- `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阶段�?
---

## ⚙️ 平台基础设施�?025-11-17 新增）✅

> **�?重要提示：平台基础设施提供云原生的通用能力，所有业务模块直接复�?*  
> **详细规划�?* 参见 [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)  
> **使用指南�?* 参见 [backend/src/common/README.md](../../backend/src/common/README.md)  
> **开发规范：** 参见 [云原生开发规范](../04-开发规�?08-云原生开发规�?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. 存储服务（零代码切换�?*

```typescript
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. 日志系统（结构化日志�?*

```typescript
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超时�?*

```typescript
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调用成本�?*

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

// 缓存LLM响应�?小时�?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�?*

```bash
# 存储：本地文件系�?STORAGE_TYPE=local
LOCAL_STORAGE_DIR=uploads

# 缓存：内存缓�?CACHE_TYPE=memory

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

# 日志：彩色输�?LOG_LEVEL=debug
```

#### **云端部署�?env.production�?*

```bash
# 存储：阿里云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依赖未安�?*

```bash
# 需要安�?cd backend
npm install winston
npm install -D @types/winston
```

#### **2. Legacy模块兼容�?*

- �?**Legacy模块**（PKB、AIA、DC）保持现状，正常运行
- �?**新模�?*（ASL）使用平台基础设施
- 🔄 **可选迁�?*：Legacy模块按需迁移（预�?小时�?
#### **3. 云端实现预留**

- `OSSAdapter`、`RedisCacheAdapter` 当前为预留实�?- 云端部署前需安装依赖并取消注�?- 详见实施文档

---

### 📚 相关文档

- **详细规划�?* [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)
- **使用指南�?* [backend/src/common/README.md](../../backend/src/common/README.md)
- **实施报告�?* [2025-11-17-平台基础设施实施完成报告](../08-项目管理/03-每周计划/2025-11-17-平台基础设施实施完成报告.md)
- **验证报告�?* [2025-11-17-平台基础设施验证报告](../08-项目管理/03-每周计划/2025-11-17-平台基础设施验证报告.md) �?新增
- **开发规范：** [云原生开发规范](../04-开发规�?08-云原生开发规�?md)

---

### �?测试验证状态（2025-11-17�?
**测试覆盖率：** 100%�?/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 新增�?
> **�?重要提示：本章节定义平台的云原生部署策略，适用于所有业务模�?*  
> **详细指南�?* 参见 [云原生部署架构指南](../09-架构实施/03-云原生部署架构指�?md)  
> **开发规范：** 参见 [云原生开发规范](../04-开发规�?08-云原生开发规�?md)

---

### 🎯 部署架构选型

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

**选型理由**�?- �?**按需付费**：初期成本低（�?00/月起），无需预付大量服务器成�?- �?**自动扩缩�?*：高峰期不宕机，低谷期不浪费，适合创业公司流量不确定的场景
- �?**国内访问优化**：阿里云国内节点多，医疗用户访问速度�?- �?**适合AI任务**：异步批量任务（LLM筛选、PDF提取）天然契�?Serverless
- �?**降低运维成本**：无需专职运维人员，团队专注业务开�?
**架构�?*�?```
┌──────────────────────────────────────────────────�?�?             云原生部署架�?                        �?├──────────────────────────────────────────────────�?�? 用户浏览�?                                       �?�?    �?                                           �?�? CDN加速（可选）                                   �?�?    �?                                           �?�? 阿里�?SAE (Serverless 应用引擎)                 �?�? ├── 自动扩缩容（0-100实例�?                     �?�? ├── 内置负载均衡                                 �?�? └── Docker 容器运行                             �?�?    �?                                           �?�? 云数据库 RDS (PostgreSQL 15)                    �?�? ├── 10个Schema隔离                              �?�? ├── 自动备份                                     �?�? └── 连接池管�?                                  �?�?    �?                                           �?�? 对象存储 OSS                                     �?�? ├── PDF/Excel 文件存储                          �?�? ├── 11�?可靠�?                                �?�? └── 内网访问免流量费                             �?└──────────────────────────────────────────────────�?```

---

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

#### **原则1：无状态应用设�?*

**要求**：应用不能依赖本地文件系统或内存状�?
| 禁止做法 �?| 正确做法 �?| 说明 |
|-----------|-----------|------|
| 文件存储�?`./uploads/` | 上传�?OSS �?内存处理 | 容器重启会丢失本地文�?|
| Session 存内�?| Session �?Redis/数据�?| 多实例间无法共享内存 |
| 缓存存内存变�?| 使用 Redis | 扩容后缓存失�?|
| 依赖 `/tmp` 长期存储 | 用完立即删除 | /tmp 容量有限且不持久 |

**示例**�?```typescript
// �?禁止：本地文件存�?fs.writeFileSync('./uploads/file.pdf', buffer)

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

---

#### **原则2：存储抽象层设计**

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

**架构**�?```typescript
StorageFactory
    �?StorageAdapter (接口)
    �?├── LocalAdapter (本地开�?
└── OSSAdapter (生产环境)
```

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

**环境配置**�?```bash
# 本地开�?STORAGE_TYPE=local

# 生产环境
STORAGE_TYPE=oss
```

---

#### **原则3：数据库连接池管�?*

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

**解决方案**�?```typescript
// 计算公式：每实例连接�?= RDS最大连接数 / SAE最大实例数
// 示例：RDS 400连接 / SAE 20实例 = 每实�?0连接

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

**监控**：定期检查数据库连接数，接近上限时告�?
---

#### **原则4：环境变量配�?*

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

```bash
# �?禁止硬编�?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秒）必须异步处理

```typescript
// �?正确：异步任务模�?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 生产环境

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

```bash
# 使用 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
```

**优势**�?- �?完全离线开�?- �?无云服务费用
- �?调试方便

---

#### **生产环境（阿里云�?*

```bash
# 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. **验证部署**：健康检查通过，流量切�?
详细流程见：[云原生部署架构指南](../09-架构实施/03-云原生部署架构指�?md)

---

### 📋 开发检查清�?
在提交代码前，请确认�?
- [ ] 是否使用 `StorageFactory` 而非直接 `fs.writeFile`�?- [ ] 是否使用全局 `prisma` 实例而非新建连接�?- [ ] 是否所有配置都从环境变量读取？
- [ ] 是否长时间任务都改为异步处理�?- [ ] 是否日志都输出到 stdout�?- [ ] 是否 `/tmp` 目录使用后立即清理？
- [ ] 是否避免依赖本地文件路径�?
完整检查清单见：[云原生开发规范](../04-开发规�?08-云原生开发规�?md)

---

### 📚 相关文档

- �?**[云原生部署架构指南](../09-架构实施/03-云原生部署架构指�?md)** - 包含完整代码示例和部署流�?- �?**[云原生开发规范](../04-开发规�?08-云原生开发规�?md)** - DO/DON'T 检查清�?- [Schema隔离架构设计](../09-架构实施/01-Schema隔离架构设计�?0个）.md)
- [数据库连接配置](../09-架构实施/02-数据库连接配�?md)

---

**本章节创建日期：** 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
```

### 模块定义接口

```typescript
// 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[]
}
```

### 模块注册示例

```typescript
// 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
```

### 模块路由示例

```typescript
// 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
```

### 模块路由注册

```typescript
// 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调用示例

```typescript
// 前端：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   # 删除
```

**响应格式�?*
```typescript
// 成功响应
{
  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�?1-13）：前端架构基础 �?4-6小时

**上午：项目创建和框架�?*
- [x] 创建 frontend-v2 项目（Vite + React + TS�?- [x] 安装依赖（Antd、Router、Zustand、React Query�?- [x] 配置 Tailwind CSS
- [x] 创建目录结构（framework/modules/shared�?- [x] 实现 TopNavigation.tsx
- [x] 实现 MainLayout.tsx
- [x] 定义模块接口（ModuleDefinition�?
**下午：模块占�?*
- [x] �?个模块创建目�?- [x] 创建 Placeholder.tsx 组件
- [x] 配置基本路由
- [x] 测试导航切换

**交付物：**
- �?可运行的 frontend-v2 项目
- �?顶部导航正常工作
- �?5个模块占位页�?
#### Day 7�?1-14）：模块注册机制 �?6-8小时

**上午：注册系�?*
- [ ] 实现 moduleRegistry.ts
- [ ] 实现 ModuleLoader.tsx
- [ ] 实现动态路由加�?- [ ] 实现懒加载机�?
**下午：测试和文档**
- [ ] 测试模块注册
- [ ] 测试路由切换
- [ ] 编写开发文�?- [ ] 更新 README

**交付物：**
- �?完整的模块注册系�?- �?动态路由加�?- �?开发文�?
#### Day 8-9�?1-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�?1-17）：Week 2 验收 �?4小时

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

---

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

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

详见：[下一阶段行动计划-V2.2-完整�?md](../08-项目管理/下一阶段行动计划-V2.2-完整�?md)

---

## 📝 旧代码处�?
### frontend/ 目录

**状态：** ⏸️ 保留，不再开�?
**处理方式�?*
1. 添加 `README-ARCHIVED.md` 说明文件
2. 在根目录 `package.json` 中区分启动命�?3. 保留3-6个月，作为参考和应急备�?4. 新架构稳定后再删�?
**参考价值：**
- UI交互设计
- 某些组件实现
- API调用逻辑
- 业务流程

### 启动命令

```json
{
  "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 验收标准

**前端�?*
- [x] frontend-v2 项目可运�?- [x] 顶部导航正常工作
- [x] 模块注册系统完整
- [x] 5个模块占位页�?- [x] 路由切换正常
- [x] 完整的开发文�?
**后端�?*
- [ ] 代码分层完成（platform/common/modules�?- [ ] 所有现有API正常工作
- [ ] 路由前缀统一�?api/v1/[module]/*�?- [ ] import路径全部更新
- [ ] API文档更新

**文档�?*
- [x] 本架构设计文�?- [ ] 前端开发规范文�?- [ ] 后端开发规范文�?- [ ] Week 2总结报告

---

## 📚 相关文档

### 架构设计
- [Schema隔离架构设计�?0个）](../09-架构实施/01-Schema隔离架构设计�?0个）.md)
- [前端总体架构设计](../01-平台基础�?06-前端架构/01-前端总体架构设计.md)
- [导航结构设计](../01-平台基础�?06-前端架构/02-导航结构设计.md)

### 数据库设�?- [AIA数据库设计](../03-业务模块/AIA-AI智能问答/02-技术设�?01-数据库设�?md)
- [PKB数据库设计](../03-业务模块/PKB-个人知识�?02-技术设�?01-数据库设�?md)

### 实施报告
- [Schema迁移完成报告](../09-架构实施/Schema迁移完成报告.md)
- [Prisma配置完成报告](../09-架构实施/Prisma配置完成报告.md)

### 项目管理
- [下一阶段行动计划-V2.2-完整版](../08-项目管理/下一阶段行动计划-V2.2-完整�?md)

---

## 🔄 版本历史

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

---

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

**🎉 这是系统架构演进的重要里程碑�?*