docs: Update architecture docs with platform infrastructure details

- Add platform infrastructure chapter to frontend-backend architecture design - Update system architecture document with 6 new infrastructure modules - Update AI onboarding guide with infrastructure overview - Link to backend/src/common/README.md for detailed usage guide Key Updates: - Storage service (LocalAdapter + OSSAdapter) - Logging system (Winston + JSON format) - Cache service (Memory + Redis) - Async job queue (Memory + Database) - Health check endpoints - Monitoring metrics - Database connection pool - Environment config management All modules support zero-code switching between local and cloud environments. Related: #Platform-Infrastructure
2025-11-17 08:36:10 +08:00
parent 8bba33ac89
commit 31d555f7bb
88 changed files with 490 additions and 8 deletions
--- a/docs/00-系统总体设计/前后端模块化架构设计-V2.md
+++ b/docs/00-系统总体设计/前后端模块化架构设计-V2.md
@@ -554,6 +554,210 @@ Schema数量: 10个（3详细 + 7占位）

 ---

+## ⚙️ 平台基础设施（2025-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响应（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）**
+
+```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模块按需迁移（预计5小时）
+
+#### **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)
+- **开发规范：** [云原生开发规范](../04-开发规范/08-云原生开发规范.md)
+
+---
+
 ## 🌥️ 云原生部署架构（2025-11-16 新增）

 > **⭐ 重要提示：本章节定义平台的云原生部署策略，适用于所有业务模块**