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
This commit is contained in:
2025-11-17 08:36:10 +08:00
parent 8bba33ac89
commit 31d555f7bb
88 changed files with 490 additions and 8 deletions

View File

@@ -170,7 +170,168 @@ const url = await storage.upload('literature/123.pdf', pdfBuffer)
- ✅ 所有模块复用同一套代码
- ✅ 支持PRD定义的4种部署形态
**实施文档** [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)
**实施状态** ✅ 2025-11-17 完成LocalAdapter + OSSAdapter预留
**实施文档:**
- [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)
- [backend/src/common/README.md](../../backend/src/common/README.md)
- [平台基础设施实施完成报告](../08-项目管理/03-每周计划/2025-11-17-平台基础设施实施完成报告.md)
---
#### 2.1. 日志系统Logging Service⭐ 2025-11-17 新增
**职责:**
- 结构化日志输出JSON格式
- 支持本地开发和云端部署
- 集成阿里云SLS生产环境
**实现方式:**
```typescript
// Winston配置
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解析
**实施状态:** ✅ 2025-11-17 完成需安装winston依赖
---
#### 2.2. 缓存服务Cache Service⭐ 2025-11-17 新增
**职责:**
- LLM响应缓存减少API调用成本
- 数据库查询结果缓存
- Session缓存
**实现方式:**
```typescript
// 适配器模式MemoryCacheAdapter | RedisCacheAdapter
import { cache } from '@/common/cache'
// 缓存LLM响应1小时
const cacheKey = `llm:${model}:${hash(prompt)}`
await cache.set(cacheKey, response, 60 * 60)
const cached = await cache.get(cacheKey)
```
**环境切换:**
- 本地开发:`CACHE_TYPE=memory`
- 云端部署:`CACHE_TYPE=redis`
**实施状态:** ✅ 2025-11-17 完成MemoryCache + RedisCache预留
---
#### 2.3. 异步任务Job Queue⭐ 2025-11-17 新增
**职责:**
- 长时间任务异步处理避免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 }
```
**环境切换:**
- 本地开发:`QUEUE_TYPE=memory`
- 云端部署:`QUEUE_TYPE=database`
**实施状态:** ✅ 2025-11-17 完成MemoryQueue + DatabaseQueue预留
---
#### 2.4. 健康检查Health Check⭐ 2025-11-17 新增
**职责:**
- SAE存活检查Liveness Probe
- SAE就绪检查Readiness Probe
- 数据库连接监控
**端点:**
- `GET /health/liveness` - 简单响应
- `GET /health/readiness` - 检查数据库、内存等
- `GET /health` - 详细健康信息(开发用)
**实施状态:** ✅ 2025-11-17 完成
---
#### 2.5. 监控指标Monitoring⭐ 2025-11-17 新增
**职责:**
- 数据库连接数监控(带告警)
- 内存使用监控(带告警)
- API响应时间监控
- LLM调用统计
**使用方式:**
```typescript
import { Metrics } from '@/common/monitoring'
// 记录数据库连接数(带告警)
await Metrics.recordDBConnectionCount()
// 记录API响应时间
Metrics.recordAPIResponseTime('GET', '/api/projects', 200, 150)
// 记录LLM调用
Metrics.recordLLMCall('deepseek', 'chat', 1500, true, { total: 300 })
```
**实施状态:** ✅ 2025-11-17 完成
---
#### 2.6. 数据库连接池Connection Pool⭐ 2025-11-17 新增
**职责:**
- 防止Serverless扩容导致连接数超限
- 优雅关闭连接SIGTERM信号处理
- 连接数监控
**配置:**
```bash
# 动态连接限制计算
# connectionLimit = (RDS_MAX_CONNECTIONS / MAX_INSTANCES) - 预留
DB_MAX_CONNECTIONS=400 # RDS最大连接数
MAX_INSTANCES=20 # SAE最大实例数
# 每实例推荐18个连接
```
**实施状态:** ✅ 2025-11-17 完成
---