AIclinicalresearch/docs/00-系统总体设计/00-系统当前状态与开发指南.md

# AI临床研究平台 - 系统当前状态与开发指南

> **版本：** V2.5.0  
> **创建日期：** 2025-11-17  
> **更新日期：** 2025-11-23  
> **适用对象：** 新开发人员、AI助手、技术决策者  
> **阅读时间：** 20分钟  
> **文档定位：** 系统真实状态 + 核心开发规范 ⭐ 必读

**📝 版本历史：**
- V2.5.0 (2025-11-23): 更新ASL模块状态（全文复筛后端完成，Day 2-5，2500+行代码）
- V2.4.0 (2025-11-18): 更新ASL模块状态（Week 1完成，4个表+10个API+双模型筛选）
- V2.3.1 (2025-11-18): 更新LLM模型支持（添加CloseAI集成说明）
- V2.3.0 (2025-11-17): 初始创建，基于平台基础设施完成后的真实状态

---

## 📋 快速导航

| 章节 | 内容 | 阅读时间 |
|------|------|---------|
| [Part 1](#part-1-系统当前状态) | 系统架构真实状态（前端/后端/数据库/API） | 10分钟 |
| [Part 2](#part-2-开发规范速查) | 核心开发规范（代码/Git/云原生/数据库/API） | 7分钟 |
| [Part 3](#part-3-重要原则与禁忌) | 必须遵守的原则和禁止的操作 | 3分钟 |
| [附录](#附录详细文档索引) | 详细文档索引 | - |

**⚡ 快速上手路径：**
1. 阅读 [1.3 后端架构 - 平台基础设施](#13-后端架构真实状态) ⭐ 最重要
2. 阅读 [LLM模型支持](#llm模型支持) - 了解可用的AI模型
3. 阅读 [2.3 云原生开发规范](#23-云原生开发规范-) ⭐ 必读
4. 阅读 [Part 3 原则与禁忌](#part-3-重要原则与禁忌) ⭐ 必须遵守
5. 开始开发！

---

# Part 1: 系统当前状态（2025-11-17）

> **⭐ 本章节描述系统的真实状态，所有信息基于实际代码**  
> **💡 不包含历史演进，只关注"现在是什么样"**

---

## 1.1 三层架构设计

### 架构概览

```
┌─────────────────────────────────────────────────────────┐
│                   业务模块层                             │
│   ASL | AIA | PKB | DC | SSA | ST | UAM                │
│   (AI智能文献 | AI问答 | 知识库 | 数据清洗 | 统计...)    │
└─────────────────────────────────────────────────────────┘
                         ↓ 调用
┌─────────────────────────────────────────────────────────┐
│                 通用能力层                               │
│   LLM适配器 | RAG引擎 | 文档处理 | 医学NLP             │
└─────────────────────────────────────────────────────────┘
                         ↓ 调用
┌─────────────────────────────────────────────────────────┐
│              平台基础层（Platform Infrastructure）        │
│  存储 | 日志 | 缓存 | 任务队列 | 健康检查 | 监控 | 数据库  │
│  ⭐ 2025-11-17完成，8个核心模块，100%测试通过            │
└─────────────────────────────────────────────────────────┘
```

### 核心设计原则

1. **Schema隔离**：10个独立Schema，模块数据完全隔离
2. **模块独立**：每个业务模块可独立开发、部署、销售
3. **适配器模式**：零代码环境切换（本地 ↔ 云端）
4. **云原生优先**：为阿里云Serverless SAE部署优化

---

## 1.2 前端架构真实状态

### 目录结构（Frontend-v2）

```bash
frontend-v2/src/
├── framework/                      # ✅ 框架层（2025-11-14完成）
│   ├── layout/
│   │   ├── MainLayout.tsx          # 主布局（顶部导航）
│   │   ├── TopNavigation.tsx       # 6个模块导航栏
│   │   └── UserMenu.tsx            # 用户菜单
│   │
│   ├── modules/
│   │   ├── moduleRegistry.ts       # 模块注册中心
│   │   ├── ErrorBoundary.tsx       # 错误边界
│   │   └── types.ts                # ModuleDefinition接口
│   │
│   ├── router/
│   │   ├── RouteGuard.tsx          # 路由守卫
│   │   └── PermissionDenied.tsx    # 权限拒绝页
│   │
│   └── permission/
│       ├── PermissionContext.tsx   # 权限上下文
│       └── usePermission.ts        # 权限Hook
│
├── modules/                        # 📦 业务模块（7个目录，6个已注册）
│   ├── aia/                        # ✅ AI智能问答（占位）
│   │   └── index.tsx
│   ├── asl/                        # 🚧 AI智能文献（标题摘要初筛完成✅，全文复筛后端完成✅，待前端）
│   │   └── index.tsx
│   ├── pkb/                        # ✅ 个人知识库（占位）
│   │   └── index.tsx
│   ├── dc/                         # ✅ 数据清洗（占位）
│   │   └── index.tsx
│   ├── ssa/                        # ✅ 智能统计（占位，Java团队）
│   │   └── index.tsx
│   ├── st/                         # ✅ 统计工具（占位，Java团队）
│   │   └── index.tsx
│   └── rvw/                        # 📋 预留目录（稿件审查，未来开发）
│       └── （空目录，待添加到moduleRegistry）
│
└── shared/                         # 共享资源
    ├── components/                 # 通用组件
    ├── hooks/                      # 通用Hooks
    └── utils/                      # 工具函数
```

### 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| React | 19 | 前端框架 |
| TypeScript | 5.x | 类型系统 |
| Ant Design | 5.x | UI组件库 |
| Vite | 5.x | 构建工具 |
| React Router | 6.x | 路由管理 |

### 当前运行状态

- ✅ 访问地址：http://localhost:5173
- ✅ 顶部导航：6个模块导航正常
- ✅ 模块目录：7个模块目录
  - 6个已注册（在moduleRegistry.ts中）
  - 1个预留（rvw - 稿件审查，未来开发）
- ✅ 模块注册表：6个模块已注册（moduleRegistry.ts）
  - AI问答（aia）
  - AI智能文献（asl）- 标题摘要初筛完成✅，全文复筛后端完成✅，待前端开发
  - 知识库（pkb）
  - 智能数据清洗（dc）
  - 智能统计分析（ssa）- Java团队
  - 统计分析工具（st）- Java团队
- 📋 预留模块：稿件审查（rvw）- 目录已创建，待添加到注册表
- ✅ 权限系统：3级版本控制（basic/advanced/premium）
- ✅ 错误边界：模块级错误隔离
- 🚧 模块开发：ASL模块Day 2-5完成✅（全文复筛后端2500+行代码），Day 6-8待前端开发

---

## 1.3 后端架构真实状态

### 目录结构（Backend）

```bash
backend/src/
├── legacy/                         # 🔸 现有业务代码（稳定运行）
│   ├── routes/                     # 7个路由文件
│   │   ├── projects.ts             # AIA: 项目管理
│   │   ├── agents.ts               # AIA: 智能体
│   │   ├── conversations.ts        # AIA: 对话管理
│   │   ├── chatRoutes.ts           # AIA: 通用对话
│   │   ├── knowledgeBases.ts       # PKB: 知识库
│   │   ├── batchRoutes.ts          # PKB: 批处理
│   │   └── reviewRoutes.ts         # RVW: 稿件审查
│   │
│   ├── controllers/                # 8个控制器
│   └── services/                   # 8个服务
│
├── common/                         # ⭐ 平台基础设施（2025-11-17完成）
│   │
│   ├── llm/adapters/               # LLM适配器（通用能力）
│   │   ├── DeepSeekAdapter.ts      # ✅ DeepSeek-V3（直连）
│   │   ├── QwenAdapter.ts          # ✅ Qwen3-72B + Qwen-Long（阿里云）
│   │   ├── LLMFactory.ts           # ✅ 工厂类（支持4个模型）
│   │   ├── types.ts                # ✅ 类型定义
│   │   └── ⚠️ TODO:                # GPT-5 + Claude-4.5（通过CloseAI）
│   │
│   ├── rag/                        # RAG引擎（通用能力）
│   │   ├── DifyClient.ts           # ✅ Dify客户端
│   │   └── types.ts
│   │
│   ├── document/                   # 文档处理（通用能力）
│   │   └── ExtractionClient.ts     # ✅ Python微服务客户端
│   │
│   ├── 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          # 3个端点（已测试✅）
│   │   └── index.ts
│   │
│   ├── monitoring/                 # ⭐ 监控指标（平台基础设施）
│   │   ├── metrics.ts              # 指标采集（已测试✅）
│   │   └── index.ts
│   │
│   ├── middleware/                 # 中间件
│   │   └── validateProject.ts
│   │
│   └── utils/                      # 工具函数
│       └── jsonParser.ts
│
├── modules/                        # 🌟 新模块开发区（标准化架构）
│   └── asl/                        # 🚧 AI智能文献（标题摘要初筛完成✅，全文复筛后端完成✅）
│       ├── controllers/            # ✅ 3个控制器（项目、文献、标题初筛、全文复筛）
│       ├── services/               # ✅ LLM筛选服务（双模型+三种风格+全文12字段）
│       ├── routes/                 # ✅ 15个API接口（10个标题初筛 + 5个全文复筛）
│       ├── schemas/                # ✅ JSON Schema + Prompt生成
│       ├── types/                  # ✅ TypeScript类型定义
│       ├── common/                 # ✅ 全文复筛通用能力层（PDF、LLM、验证）
│       └── fulltext-screening/     # ✅ 全文复筛模块（Day 2-5完成，2500+行代码）
│
├── config/                         # ⚙️ 配置层
│   ├── database.ts                 # ⭐ 数据库配置（Serverless连接池优化）
│   └── env.ts                      # ⭐ 环境变量管理（统一配置加载）
│
├── scripts/                        # 🛠️ 工具脚本
│   ├── create-mock-user.ts
│   ├── test-dify-client.ts
│   └── test-platform-infrastructure.ts  # 平台基础设施测试
│
├── test-platform-api.ts            # ⭐ 临时测试API（/test/platform）
│
└── index.ts                        # 主入口（路由注册）
```

### ⭐ 平台基础设施详解（核心）

**实施完成日期：** 2025-11-17  
**测试覆盖率：** 100%（8/8模块全部通过）  
**代码统计：** 2,532行新代码，22个新文件

#### 8个核心模块

| # | 模块 | 路径 | 功能 | 环境切换 | 测试状态 |
|---|------|------|------|---------|---------|
| 1 | **存储服务** | `common/storage/` | 文件上传下载 | `STORAGE_TYPE=local/oss` | ✅ 100% |
| 2 | **日志系统** | `common/logging/` | 结构化日志 | 自动（根据NODE_ENV） | ✅ 100% |
| 3 | **缓存服务** | `common/cache/` | 内存/Redis缓存 | `CACHE_TYPE=memory/redis` | ✅ 100% |
| 4 | **异步任务** | `common/jobs/` | 长时间任务处理 | `QUEUE_TYPE=memory/database` | ✅ 100% |
| 5 | **健康检查** | `common/health/` | SAE健康检查 | N/A | ✅ 100% |
| 6 | **监控指标** | `common/monitoring/` | 关键指标监控 | N/A | ✅ 100% |
| 7 | **数据库连接池** | `config/database.ts` | Prisma连接池 | `DATABASE_URL` | ✅ 100% |
| 8 | **环境配置** | `config/env.ts` | 统一配置管理 | `.env`文件 | ✅ 100% |

#### 核心设计：适配器模式

**原理：** 通过适配器模式实现零代码环境切换

```
业务代码（完全相同）
    ↓ import from '@/common/'
适配器接口（统一API）
    ↓ 环境变量切换
具体实现（本地 or 云端）
```

#### 使用示例

**1. 存储服务 - 零代码切换**

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

// 业务代码（完全相同，无需改动）
const buffer = await readFile('example.pdf')
const url = await storage.upload('literature/123.pdf', buffer)
const downloaded = await storage.download('literature/123.pdf')
await storage.delete('literature/123.pdf')

// 环境切换（只需修改环境变量）
// 本地开发：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. 缓存服务 - 减少LLM成本**

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

// 环境切换：
// 本地开发：CACHE_TYPE=memory → 内存缓存
// 云端部署：CACHE_TYPE=redis  → Redis缓存
```

**4. 异步任务 - 避免Serverless超时**

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

// 创建任务（立即返回，避免超时）
const job = await jobQueue.push('asl:screening', {
  projectId: 123,
  literatureIds: [1, 2, 3, ..., 1000]  // 大量数据
})

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

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

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

**测试API：** `GET http://localhost:3001/test/platform`

**测试结果：**
```json
{
  "overall": "ALL_PASSED",
  "tests": {
    "storage": { "status": "passed", "contentMatch": true },
    "logging": { "status": "passed" },
    "cache": { "status": "passed", "contentMatch": true },
    "jobQueue": { "status": "passed", "jobStatus": "pending" }
  }
}
```

**健康检查端点：**
- `GET /health` - 简化版（向后兼容）
- `GET /health/liveness` - SAE存活检查（响应时间<10ms）
- `GET /health/readiness` - SAE就绪检查（含数据库/内存/缓存）

### LLM模型支持

**当前已实现：**

| 模型 | 供应商 | 模型ID | 状态 | 适用场景 |
|------|--------|--------|------|---------|
| **DeepSeek-V3** | DeepSeek | `deepseek-chat` | ✅ 已实现 | 快速初筛、成本优化 |
| **Qwen3-72B** | 阿里云 | `qwen-plus` | ✅ 已实现 | 中文理解、通用任务 |
| **Qwen-Long** | 阿里云 | `qwen-long` | ✅ 已实现 | 超长上下文（1M tokens） |
| Gemini-Pro | Google | `gemini-pro` | 🚧 预留 | 待实现 |

**通过CloseAI代理（2025-11-18完成）：** ✅

| 模型 | 供应商 | 实际模型ID | 状态 | 响应时间 | 适用场景 |
|------|--------|-----------|------|---------|---------|
| **GPT-4o** | OpenAI | `gpt-4o` | ✅ 已实现 | 1.5秒 ⭐ | 高质量筛选、复杂推理 |
| **Claude-4.5** | Anthropic | `claude-sonnet-4-5-20250929` | ✅ 已实现 | 2.8秒 | 第三方仲裁、结构化输出 |

**配置说明：**
```bash
# env.ts 已配置 CloseAI
CLOSEAI_API_KEY=sk-cu0iepbXYGGx2jc7...
CLOSEAI_OPENAI_BASE_URL=https://api.openai-proxy.org/v1
CLOSEAI_CLAUDE_BASE_URL=https://api.openai-proxy.org/anthropic
```

**✅ 已完成工作（2025-11-18）：**
- ✅ 创建 `CloseAIAdapter.ts` 核心适配器（支持OpenAI和Claude双格式）
- ✅ 创建 `GPT5Adapter.ts` 和 `ClaudeAdapter.ts` 便捷封装
- ✅ 更新 `LLMFactory.ts` 支持 `gpt-5` 和 `claude-4.5`
- ✅ 性能优化：使用 `gpt-4o` 替代 `gpt-5-pro`（性能提升25倍）
- ✅ 测试验证：所有测试通过，支持双模型对比筛选
- ✅ **ASL模块集成**：双模型筛选（DeepSeek-V3 + Qwen-Max）已在生产使用 ⭐

**性能测试结果：**
- GPT-4o: 1.5秒（快25倍于gpt-5-pro）
- Claude-4.5: 2.8秒
- 双模型并行筛选: 4.8秒（快10倍于之前）
- **ASL实际使用**: DeepSeek-V3 + Qwen-Max 平均16秒/篇 ⭐

**参考文档：** [CloseAI集成指南](../02-通用能力层/01-LLM大模型网关/03-CloseAI集成指南.md)

### 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Node.js | 22.18.0 | 运行时 |
| Fastify | 5.x | Web框架 |
| Prisma | 6.17.0 | ORM |
| PostgreSQL | 15 | 数据库 |
| Winston | 3.x | 日志库 |
| TypeScript | 5.x | 类型系统 |

### 当前运行状态

- ✅ 访问地址：http://localhost:3001
- ✅ 健康检查：http://localhost:3001/health （3个端点全部正常）
- ✅ 测试API：http://localhost:3001/test/platform
- ✅ Legacy模块：AIA/PKB/RVW 正常运行
- ✅ **平台基础设施：8个模块测试通过（100%）**
- ✅ 数据库连接：1/400（正常）
- ✅ ASL模块：标题摘要初筛完成✅，全文复筛后端完成✅（Day 2-5，2500+行代码），待前端开发

---

## 1.4 数据库真实状态

### Schema隔离（10个独立Schema）

```sql
-- PostgreSQL 15 + Prisma 6.17.0

✅ platform_schema   -- 平台层：用户、角色、权限
✅ aia_schema        -- AI问答：项目、对话、消息
✅ pkb_schema        -- 知识库：文档、批处理、知识图谱
✅ asl_schema        -- AI智能文献：6个表已创建（2025-11-23）
                        - screening_projects（筛选项目）
                        - literatures（文献条目，+13个全文字段）
                        - screening_results（标题摘要初筛结果）
                        - screening_tasks（标题摘要初筛任务）
                        - fulltext_screening_tasks（全文复筛任务）
                        - fulltext_screening_results（全文复筛结果，12字段）
📋 rvw_schema        -- 稿件审查：预留
📋 dc_schema         -- 数据清洗：预留
📋 admin_schema      -- 运营管理：预留
📋 ssa_schema        -- 统计分析：预留
📋 st_schema         -- 统计工具：预留
📋 common_schema     -- 通用能力：预留
```

### 连接池配置（Serverless优化）

**问题：** SAE自动扩容可能导致数据库连接数超限

**解决方案：** 动态连接池配置

```typescript
// backend/src/config/database.ts

// 连接限制 = (RDS最大连接数 / SAE最大实例数) - 预留
const connectionLimit = Math.floor(
  (DB_MAX_CONNECTIONS / MAX_INSTANCES) - 2
)

// 示例计算：
// RDS最大连接：400
// SAE最大实例：20
// 每实例连接：(400 / 20) - 2 = 18个
```

**环境变量：**
```bash
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
DB_MAX_CONNECTIONS=400  # RDS最大连接数
MAX_INSTANCES=20        # SAE最大实例数
```

**优雅关闭：**
- 监听 `SIGTERM` 信号（SAE容器关闭）
- 自动关闭Prisma连接
- 确保不会泄露连接

### 当前状态

| 指标 | 值 | 说明 |
|------|---|------|
| 总Schema | 10个 | Schema隔离完成 |
| 已实现Schema | 4个 | platform/aia/pkb/asl ⭐ |
| 待开发Schema | 6个 | dc_schema, ssa_schema等 |
| 当前连接数 | 1/400 | 0.2%使用率 |
| 数据库响应时间 | 2ms | 优秀 |

---

## 1.5 API当前状态

### Legacy模块API（7个路由文件）

**前缀：** `/api/v1`

| 模块 | 路由文件 | 主要端点 | 状态 |
|------|---------|---------|------|
| **AIA** | `projects.ts` | `/api/v1/projects` | ✅ 运行中 |
| **AIA** | `agents.ts` | `/api/v1/agents` | ✅ 运行中 |
| **AIA** | `conversations.ts` | `/api/v1/conversations` | ✅ 运行中 |
| **AIA** | `chatRoutes.ts` | `/api/v1/chat` | ✅ 运行中 |
| **PKB** | `knowledgeBases.ts` | `/api/v1/knowledge-bases` | ✅ 运行中 |
| **PKB** | `batchRoutes.ts` | `/api/v1/batch` | ✅ 运行中 |
| **RVW** | `reviewRoutes.ts` | `/api/v1/reviews` | ✅ 运行中 |

### 健康检查API（3个端点）

| 端点 | 用途 | 响应时间 | 状态 |
|------|------|---------|------|
| `/health` | 简化版（向后兼容） | <5ms | ✅ 200 OK |
| `/health/liveness` | SAE存活检查 | <10ms | ✅ 200 OK |
| `/health/readiness` | SAE就绪检查 | <50ms | ✅ 200 OK |

### 测试API（临时）

| 端点 | 用途 | 状态 |
|------|------|------|
| `/test/platform` | 平台基础设施验证 | ✅ ALL_PASSED |

**⚠️ 注意：** 测试API仅用于开发验证，生产部署前需删除

### ASL模块API（标准化架构）⭐ **2025-11-23更新**

**前缀：** `/api/v1/asl`

| 接口分类 | 数量 | 功能 | 状态 |
|---------|------|------|------|
| 项目管理 | 5个 | CRUD项目（含PICOS、纳排标准、筛选风格） | ✅ 已测试 |
| 文献管理 | 4个 | 导入文献（JSON/Excel）、查询、删除 | ✅ 已测试 |
| 标题摘要初筛 | 4个 | 任务创建、进度查询、结果获取、人工复核 | ✅ 已测试 |
| **全文复筛（NEW）** | **5个** | **任务管理、进度、结果、决策、Excel导出** | **✅ 已完成** |
| 健康检查 | 1个 | 模块健康状态 | ✅ 已测试 |

**核心接口**:
```
# 项目与文献
POST   /api/v1/asl/projects                         # 创建项目（含PICOS、筛选风格）
GET    /api/v1/asl/projects                         # 项目列表
POST   /api/v1/asl/projects/:id/literatures/import-excel  # 导入Excel文献

# 全文复筛（Day 5新增）
POST   /api/v1/asl/fulltext-screening/tasks                        # 创建任务
GET    /api/v1/asl/fulltext-screening/tasks/:taskId/progress       # 获取进度
GET    /api/v1/asl/fulltext-screening/tasks/:taskId/results        # 获取结果
PUT    /api/v1/asl/fulltext-screening/results/:resultId/decision   # 更新决策
GET    /api/v1/asl/fulltext-screening/tasks/:taskId/export         # 导出Excel
```

**测试报告**: 
- 标题摘要初筛: `backend/ASL-API-测试报告.md` (10/10接口，100%通过)
- 全文复筛: `backend/src/modules/asl/fulltext-screening/__tests__/` (31个测试用例)

### API文档

详细API文档参见：
- [API路由总览](../04-开发规范/04-API路由总览.md)
- [API设计规范](../04-开发规范/02-API设计规范.md)

---

# Part 2: 开发规范速查

> **⭐ 只列核心要点，详细内容链接到完整文档**  
> **💡 每个规范都有DO/DON'T清单**

---

## 2.1 代码规范

### ✅ 必须遵守

#### 1. **复用平台基础设施**

```typescript
// ✅ 正确：使用平台提供的服务
import { storage, logger, cache, jobQueue } from '@/common'

await storage.upload('file.pdf', buffer)
logger.info('Upload complete')

// ❌ 错误：重复实现
import fs from 'fs'
fs.writeFileSync('./uploads/file.pdf', buffer)  // 禁止！
```

#### 2. **模块目录规范**

```
modules/asl/
├── routes/         # 路由定义
├── controllers/    # 控制器
├── services/       # 业务逻辑
├── types/          # TypeScript类型
└── index.ts        # 模块导出
```

#### 3. **TypeScript严格模式**

```typescript
// ✅ 正确：明确类型
interface User {
  id: number
  name: string
}

// ❌ 错误：any类型
function getUser(): any { ... }  // 禁止！
```

### ❌ 禁止的操作

1. ❌ 在业务模块中实现存储/日志/缓存（必须使用平台服务）
2. ❌ 直接操作文件系统（`fs.writeFile`等）
3. ❌ 硬编码配置（必须使用环境变量）
4. ❌ 创建新的Prisma实例（必须使用全局实例）
5. ❌ 使用`any`类型（必须明确类型）

### 📚 详细规范

[完整代码规范 →](../04-开发规范/05-代码规范.md)

---

## 2.2 Git提交规范

### ✅ 核心原则

#### 1. **批量提交，避免频繁提交**

```bash
# ✅ 正确：一天工作结束后统一提交
git add .
git commit -m "feat(asl): 完成标题摘要初筛功能

- 实现Excel解析逻辑
- 添加LLM异步任务处理
- 完善存储服务调用
- 更新相关文档

Tested: 本地验证通过"

# ❌ 错误：频繁碎片化提交
git commit -m "fix bug"           # 每改一次就提交
git commit -m "update"
git commit -m "fix another bug"
```

**推荐频率：**
- ✅ 一天工作结束时统一提交
- ✅ 完成一个完整功能时提交
- ❌ 每次小改动就提交

#### 2. **必须测试验证后才能提交**

**提交前检查清单：**
- [ ] ✅ 代码已完成
- [ ] ✅ 本地测试通过
- [ ] ✅ 功能验证通过
- [ ] ✅ 代码风格检查通过
- [ ] ✅ 文档已更新
- [ ] ✅ Commit信息规范

#### 3. **Commit Message格式**

```
<type>(<scope>): <subject>

<body>

<footer>
```

**常用Type：**
- `feat`: 新功能
- `fix`: Bug修复
- `docs`: 文档更新
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关

**示例：**
```
feat(asl): 完成标题摘要初筛功能

实现内容：
- Excel解析和验证
- LLM异步任务处理
- 集成平台基础设施
- 完善API和数据库Schema

Tested: 本地测试通过，功能验证完成
```

### ❌ 禁止的操作

1. ❌ 提交未测试的代码
2. ❌ 提交一半的功能
3. ❌ 频繁的碎片化提交
4. ❌ Commit信息不规范
5. ❌ 直接force push到master

### 📚 详细规范

[完整Git提交规范 →](../04-开发规范/06-Git提交规范.md)

---

## 2.3 云原生开发规范 ⭐

> **⭐⭐⭐ 非常重要！所有新模块必须遵守**

### ✅ 核心原则

#### 1. **无状态应用设计**

| 禁止做法 ❌ | 正确做法 ✅ | 原因 |
|-----------|-----------|------|
| 文件存储到 `./uploads/` | 使用 `storage.upload()` | 容器重启会丢失 |
| Excel保存到磁盘再解析 | 内存解析 `xlsx.read(buffer)` | Serverless无持久化存储 |
| Session存内存 | Session存Redis/数据库 | 多实例无法共享 |
| `new PrismaClient()` | 使用全局 `prisma` | 避免连接数暴增 |

#### 2. **使用平台基础设施**

```typescript
// ✅ 正确：使用平台服务
import { storage, logger, cache, jobQueue } from '@/common'

// Excel导入：内存解析，不落盘
const workbook = xlsx.read(buffer, { type: 'buffer' })

// 文件上传：自动切换本地/OSS
const url = await storage.upload('literature/123.pdf', pdfBuffer)

// 日志记录：结构化JSON
logger.info('Screening started', { projectId, count })

// 缓存LLM响应：减少成本
await cache.set(`llm:${key}`, response, 3600)

// 异步任务：避免超时
const job = await jobQueue.push('asl:screening', data)
```

#### 3. **异步处理长时间任务**

```typescript
// ✅ 正确：异步处理（避免Serverless超时）
app.post('/api/v1/asl/screening/start', async (req, reply) => {
  // 立即创建任务（< 1秒）
  const job = await jobQueue.push('asl:screening', {
    projectId: req.body.projectId,
    literatureIds: req.body.literatureIds  // 可能有1000+条
  })
  
  // 立即返回任务ID
  return { jobId: job.id, status: 'processing' }
})

// 前端轮询任务进度
app.get('/api/v1/asl/jobs/:id', async (req, reply) => {
  const job = await jobQueue.getJob(req.params.id)
  return job  // { status, progress, result }
})

// ❌ 错误：同步处理（会超时）
app.post('/api/v1/asl/screening/start', async (req, reply) => {
  // 处理1000条文献，可能需要5分钟！
  for (const lit of literatures) {
    await llm.screen(lit)  // Serverless会超时！
  }
  return { success: true }
})
```

### ❌ 禁止的操作

| 禁止操作 | 后果 | 正确做法 |
|---------|------|---------|
| `fs.writeFileSync()` | 文件丢失 | `xlsx.read(buffer)` 内存解析 |
| 同步处理LLM批量任务 | Serverless超时 | 异步任务 + 进度轮询 |
| 硬编码 `apiKey = 'sk-xxx'` | 配置泄露 | `process.env.LLM_API_KEY` |
| `new PrismaClient()` | 连接数暴增 | 使用全局 `prisma` |
| 依赖 `/tmp` 长期存储 | 容器重启丢失 | 使用OSS |

### 🌍 环境切换配置

**本地开发（.env.development）：**
```bash
STORAGE_TYPE=local           # 本地文件系统
CACHE_TYPE=memory            # 内存缓存
QUEUE_TYPE=memory            # 内存队列
LOG_LEVEL=debug              # 详细日志
```

**云端部署（.env.production）：**
```bash
STORAGE_TYPE=oss             # 阿里云OSS
CACHE_TYPE=redis             # Redis缓存
QUEUE_TYPE=database          # 数据库队列
LOG_LEVEL=info               # 生产日志
```

### 📋 开发检查清单

- [ ] ✅ Excel内存解析（不落盘）
- [ ] ✅ 使用平台存储服务
- [ ] ✅ 异步处理LLM任务
- [ ] ✅ 所有配置使用环境变量
- [ ] ✅ 使用全局Prisma实例
- [ ] ✅ 结构化日志输出

### 📚 详细规范

[完整云原生开发规范 →](../04-开发规范/08-云原生开发规范.md)  
[云原生部署架构指南 →](../09-架构实施/03-云原生部署架构指南.md)

---

## 2.4 数据库设计规范

### ✅ Schema隔离原则

```prisma
// backend/prisma/schema.prisma

model AslProject {
  @@schema("asl_schema")      // ✅ 必须指定Schema
  
  id          Int      @id @default(autoincrement())
  name        String
  userId      Int
  createdAt   DateTime @default(now())
  
  // ✅ 跨Schema关联（使用外键）
  user        User     @relation(fields: [userId], references: [id])
}

// ❌ 错误：不指定Schema
model AslProject {
  // 默认会放到public，违反隔离原则！
}
```

### ✅ 命名规范

- **表名**：PascalCase，模块前缀（`AslProject`, `AslLiterature`）
- **字段名**：camelCase（`userId`, `createdAt`）
- **关系名**：复数（`literatures`, `screeningResults`）

### 📚 详细规范

[完整数据库设计规范 →](../04-开发规范/01-数据库设计规范.md)

---

## 2.5 API设计规范

### ✅ RESTful约定

```typescript
// ✅ 正确：RESTful风格
GET    /api/v1/asl/projects              // 列表
POST   /api/v1/asl/projects              // 创建
GET    /api/v1/asl/projects/:id          // 详情
PUT    /api/v1/asl/projects/:id          // 更新
DELETE /api/v1/asl/projects/:id          // 删除

// ✅ 正确：嵌套资源
GET    /api/v1/asl/projects/:id/literatures
POST   /api/v1/asl/projects/:id/screening/start

// ❌ 错误：不规范的URL
GET    /api/v1/asl/get-projects            // 动词在URL中
POST   /api/v1/asl/project-create          // 不符合RESTful
```

### ✅ 响应格式

```typescript
// ✅ 成功响应
{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

// ✅ 错误响应
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": { ... }
  }
}
```

### 📚 详细规范

[完整API设计规范 →](../04-开发规范/02-API设计规范.md)

---

# Part 3: 重要原则与禁忌

> **⭐ 所有开发必须遵守，没有例外**

---

## 3.1 核心开发原则（5条）

### 1. **复用平台基础设施** ⭐⭐⭐

**原则：** 永远不要重复实现存储/日志/缓存/任务队列

```typescript
// ✅ 正确
import { storage, logger, cache, jobQueue } from '@/common'

// ❌ 错误
import fs from 'fs'
import winston from 'winston'  // 重复实现！
```

---

### 2. **零代码环境切换** ⭐⭐⭐

**原则：** 通过环境变量切换，业务代码不变

```typescript
// 业务代码（完全相同）
await storage.upload('file.pdf', buffer)

// 环境切换（只需修改.env）
// STORAGE_TYPE=local  → 本地开发
// STORAGE_TYPE=oss    → 云端部署
```

---

### 3. **Schema隔离** ⭐⭐⭐

**原则：** 每个模块的数据必须在独立Schema中

```prisma
model AslProject {
  @@schema("asl_schema")  // 必须指定！
}
```

---

### 4. **模块独立** ⭐⭐

**原则：** 模块间低耦合，可独立开发、部署、销售

```
modules/asl/     # 完全独立
modules/aia/     # 完全独立
modules/pkb/     # 完全独立
```

---

### 5. **云原生优先** ⭐⭐⭐

**原则：** 所有新功能优先考虑Serverless部署

- 无状态应用设计
- 异步处理长任务
- 使用托管服务（OSS/Redis/RDS）

---

## 3.2 禁止的操作（10条）

### ❌ 1. 禁止频繁Git提交

```bash
# ❌ 错误
git commit -m "fix"
git commit -m "update"
git commit -m "fix again"

# ✅ 正确
# 一天工作结束后统一提交
```

---

### ❌ 2. 禁止本地文件存储

```typescript
// ❌ 错误
fs.writeFileSync('./uploads/file.pdf', buffer)

// ✅ 正确
await storage.upload('literature/file.pdf', buffer)
```

---

### ❌ 3. 禁止重复实现平台服务

```typescript
// ❌ 错误：在业务模块中实现存储
class AslStorageService {
  async upload(file) { ... }  // 重复实现！
}

// ✅ 正确：使用平台服务
import { storage } from '@/common'
await storage.upload(...)
```

---

### ❌ 4. 禁止同步处理长时间任务

```typescript
// ❌ 错误：同步处理（会超时）
for (const lit of 1000条文献) {
  await llm.screen(lit)  // 可能需要5分钟！
}

// ✅ 正确：异步处理
const job = await jobQueue.push('screening', data)
```

---

### ❌ 5. 禁止硬编码配置

```typescript
// ❌ 错误
const apiKey = 'sk-xxx'
const dbUrl = 'postgresql://...'

// ✅ 正确
const apiKey = process.env.LLM_API_KEY
const dbUrl = process.env.DATABASE_URL
```

---

### ❌ 6. 禁止创建新的Prisma实例

```typescript
// ❌ 错误
const prisma = new PrismaClient()  // 连接数暴增！

// ✅ 正确
import { prisma } from '@/config/database'
```

---

### ❌ 7. 禁止使用any类型

```typescript
// ❌ 错误
function getUser(): any { ... }

// ✅ 正确
interface User { id: number; name: string }
function getUser(): User { ... }
```

---

### ❌ 8. 禁止跨Schema直接查询

```typescript
// ❌ 错误
await prisma.$queryRaw`
  SELECT * FROM platform_schema.users
  JOIN asl_schema.projects ...
`

// ✅ 正确
// 使用Prisma关系查询或分别查询后在代码中组合
```

---

### ❌ 9. 禁止提交未测试的代码

```bash
# ❌ 错误
git add .
git commit -m "feat: 新功能"  # 未测试！

# ✅ 正确
npm run test     # 先测试
npm run lint     # 检查代码
git add .
git commit -m "feat: 新功能 (Tested: 全部通过)"
```

---

### ❌ 10. 禁止强制推送到master

```bash
# ❌ 错误（危险！）
git push --force origin master

# ✅ 正确
git pull origin master     # 先拉取
git push origin master     # 正常推送
```

---

## 3.3 常见注意事项

### ⚠️ 1. Excel导入必须内存解析

```typescript
// ✅ 正确
const workbook = xlsx.read(buffer, { type: 'buffer' })

// ❌ 错误
fs.writeFileSync('./temp.xlsx', buffer)
const workbook = xlsx.readFile('./temp.xlsx')
```

---

### ⚠️ 2. LLM调用必须异步

```typescript
// ✅ 正确：创建异步任务
const job = await jobQueue.push('llm:screening', {
  literatures: [...1000条]
})

// ❌ 错误：同步处理会超时
for (const lit of literatures) {
  await llm.screen(lit)  // Serverless超时限制：30秒
}
```

---

### ⚠️ 3. 环境变量必须在.env中

```bash
# .env.development
STORAGE_TYPE=local
LLM_API_KEY=sk-xxx
DATABASE_URL=postgresql://...

# 代码中使用
const storageType = process.env.STORAGE_TYPE
```

---

### ⚠️ 4. 数据库连接必须使用全局实例

```typescript
// ✅ 正确
import { prisma } from '@/config/database'
await prisma.aslProject.findMany()

// ❌ 错误
const prisma = new PrismaClient()  // 每次创建新连接！
```

---

### ⚠️ 5. 健康检查端点必须快速响应

```typescript
// ✅ 正确：< 10ms
app.get('/health/liveness', async () => {
  return { status: 'ok' }
})

// ❌ 错误：查询大量数据
app.get('/health/liveness', async () => {
  await prisma.aslProject.findMany()  // 太慢！
})
```

---

# 附录：详细文档索引

## 系统架构

| 文档 | 说明 | 重要性 |
|------|------|--------|
| [前后端模块化架构设计-V2](./前后端模块化架构设计-V2.md) | 完整架构（含历史演进） | ⭐⭐ |
| [系统架构分层设计](./01-系统架构分层设计.md) | 三层架构详解 | ⭐⭐ |

## 平台基础设施 ⭐

| 文档 | 说明 | 重要性 |
|------|------|--------|
| [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md) | 详细设计方案 | ⭐⭐⭐ |
| [平台基础设施实施报告](../08-项目管理/03-每周计划/2025-11-17-平台基础设施实施完成报告.md) | 实施过程记录 | ⭐⭐ |
| [平台基础设施验证报告](../08-项目管理/03-每周计划/2025-11-17-平台基础设施验证报告.md) | 测试验证结果 | ⭐⭐ |
| [backend/src/common/README.md](../../backend/src/common/README.md) | 使用指南 | ⭐⭐⭐ |

## 开发规范

| 文档 | 说明 | 重要性 |
|------|------|--------|
| [代码规范](../04-开发规范/05-代码规范.md) | 代码风格和最佳实践 | ⭐⭐⭐ |
| [Git提交规范](../04-开发规范/06-Git提交规范.md) | Commit规范和频率 | ⭐⭐⭐ |
| [云原生开发规范](../04-开发规范/08-云原生开发规范.md) | Serverless开发指南 | ⭐⭐⭐ |
| [数据库设计规范](../04-开发规范/01-数据库设计规范.md) | Schema隔离和命名 | ⭐⭐ |
| [API设计规范](../04-开发规范/02-API设计规范.md) | RESTful API设计 | ⭐⭐ |

## 云原生部署

| 文档 | 说明 | 重要性 |
|------|------|--------|
| [云原生部署架构指南](../09-架构实施/03-云原生部署架构指南.md) | 阿里云SAE部署 | ⭐⭐ |
| [数据库连接配置](../09-架构实施/02-数据库连接配置.md) | 连接池优化 | ⭐⭐ |
| [环境配置指南](../07-运维文档/01-环境配置指南.md) | 环境变量配置 | ⭐⭐ |

## 通用能力层

| 文档 | 说明 | 重要性 |
|------|------|--------|
| [CloseAI集成指南](../02-通用能力层/01-LLM大模型网关/03-CloseAI集成指南.md) | GPT-5 + Claude-4.5 集成 | ⭐⭐ |
| [LLM网关快速上下文](../02-通用能力层/01-LLM大模型网关/[AI对接]%20LLM网关快速上下文.md) | LLM网关总览 | ⭐⭐ |

## 业务模块开发

| 文档 | 说明 | 重要性 |
|------|------|--------|
| [ASL模块开发计划](../03-业务模块/ASL-AI智能文献/04-开发计划/) | ASL开发指南 | ⭐⭐⭐ |
| [业务模块快速上下文](../03-业务模块/[AI对接]%20业务模块快速上下文.md) | 业务模块总览 | ⭐⭐ |

---

## 🚀 快速上手清单（新人第一天）

### 步骤 1：环境准备（30分钟）

- [ ] 克隆代码仓库
- [ ] 安装依赖（`npm install`）
- [ ] 配置数据库（PostgreSQL 15）
- [ ] 复制环境变量（`.env.example` → `.env`）

### 步骤 2：阅读文档（1小时）

- [ ] **本文档** - 系统当前状态与开发指南 ⭐ 最重要
- [ ] [云原生开发规范](../04-开发规范/08-云原生开发规范.md) ⭐ 必读
- [ ] [backend/src/common/README.md](../../backend/src/common/README.md) ⭐ 平台服务使用

### 步骤 3：运行项目（30分钟）

- [ ] 启动后端：`cd backend && npm run dev`
- [ ] 启动前端：`cd frontend-v2 && npm run dev`
- [ ] 访问前端：http://localhost:5173
- [ ] 访问后端：http://localhost:3001
- [ ] 测试健康检查：http://localhost:3001/health
- [ ] 测试平台基础设施：http://localhost:3001/test/platform

### 步骤 4：开始开发（2小时）

- [ ] 阅读业务模块文档（如ASL模块）
- [ ] 创建开发分支
- [ ] 开始编写代码
- [ ] 使用平台基础设施（`storage`/`logger`/`cache`/`jobQueue`）

---

**文档维护：** 每次重大架构调整后更新  
**最后更新：** 2025-11-18  
**更新内容：**
- V2.3.1: 添加LLM模型支持详情（CloseAI集成）
- V2.3.0: 添加平台基础设施详解（V2.1阶段完成）

**维护者：** 开发团队

**✅ 代码验证状态（2025-11-18）：**
- ✅ 后端目录结构：已验证一致
- ✅ 前端目录结构：已验证一致（7个模块目录，6个已注册，1个预留）
- ✅ 平台基础设施：8个模块验证通过（100%）
- ✅ **LLM适配器：CloseAI集成完成并性能优化**
  - GPT-4o: 1.5秒响应（25倍性能提升）
  - Claude-4.5: 2.8秒响应
  - 双模型对比筛选：4.8秒（10倍性能提升）
- 📋 预留模块：rvw（稿件审查）目录已创建，待未来添加到注册表

---

**🎉 准备好了吗？开始开发吧！**