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:
@@ -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 完成
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user