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

@@ -521,3 +521,4 @@ ASL、DC、SSA、ST、RVW、ADMIN等模块

View File

@@ -696,3 +696,4 @@ P0文档必须完成

View File

@@ -172,3 +172,4 @@

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 完成
---

View File

@@ -445,3 +445,4 @@ await fetch(`http://localhost/v1/datasets/${datasetId}/document/create-by-file`,

View File

@@ -870,3 +870,4 @@ backend/src/admin/

View File

@@ -1053,3 +1053,4 @@ async function testSchemaIsolation() {

View File

@@ -1552,3 +1552,4 @@ export function setupAutoUpdater() {

View File

@@ -566,3 +566,4 @@ git reset --hard HEAD

View File

@@ -682,3 +682,4 @@ Week 7-8第7-8周运营管理端P0功能

View File

@@ -628,3 +628,4 @@ Day 6测试验证

View File

@@ -17,10 +17,13 @@
## 📊 核心信息卡片
### 项目状态
- **当前阶段:** 架构设计完成,文档重构中
- **已完成:** AIA(AI问答)、PKB(知识库)、RVW(审稿)核心功能
- **下一步:** ASL(AI智能文献)模块开发
- **技术栈:** Node.js + React + PostgreSQL + Python微服务
- **当前阶段:** ✅ 平台基础设施完成准备ASL模块开发
- **已完成:**
- AIA(AI问答)、PKB(知识库)、RVW(审稿)核心功能
- ⭐ 平台基础设施2025-11-178个云原生模块
- Schema隔离、前后端模块化架构
- **下一步:** ASL(AI智能文献)模块开发(使用平台基础设施)
- **技术栈:** Node.js + React + PostgreSQL + Python微服务 + 云原生架构
### 8个业务模块优先级排序
@@ -37,9 +40,38 @@
### 关键架构决策
1.**三层架构:** 平台层 + 通用能力层 + 业务模块层
2. **Schema隔离** 即将实施1周
3. **Monorepo** 即将转换2-3天
4.**4种部署模式** SaaS + 独立产品 + 单机版 + 私有化
2. **Schema隔离** 已完成10个Schema
3. **前后端模块化:** Frontend-v2 + Backend分层架构
4.**平台基础设施** ⭐ 2025-11-17 新增 - 云原生基础能力
5.**4种部署模式** SaaS + 独立产品 + 单机版 + 私有化
### ⭐ 平台基础设施2025-11-17 新增)
**8个核心模块全部完成**
-**存储服务**:本地/OSS零代码切换
-**数据库连接池**防止Serverless连接数超限
-**日志系统**Winston+JSON格式
-**缓存服务**:内存/Redis切换
-**异步任务**:避免超时
-**健康检查**SAE探测
-**监控指标**:数据库/内存/API监控
-**环境配置**:统一管理
**设计原则:** 适配器模式实现本地开发和云端部署零代码切换
**使用示例:**
```typescript
import { storage, logger, cache, jobQueue } from '@/common'
// 零代码环境切换
await storage.upload('file.pdf', buffer) // local/oss
await cache.set('key', value, 3600) // memory/redis
const job = await jobQueue.push('task', data) // memory/database
```
**详细文档:**
- [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)
- [backend/src/common/README.md](../../backend/src/common/README.md)
---

View File

@@ -552,3 +552,4 @@ RAG引擎43%3/7模块依赖

View File

@@ -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 新增)
> **⭐ 重要提示:本章节定义平台的云原生部署策略,适用于所有业务模块**

View File

@@ -496,3 +496,4 @@ F1. 智能统计分析 (SSA)

View File

@@ -1346,3 +1346,4 @@ P3K8s、Electron、私有化阶段二

View File

@@ -1602,3 +1602,4 @@ batchService.executeBatchTask()

View File

@@ -46,5 +46,6 @@

View File

@@ -63,3 +63,4 @@

View File

@@ -49,3 +49,4 @@

View File

@@ -45,3 +45,4 @@

View File

@@ -575,3 +575,4 @@ export const ModuleLayout = ({ module }: { module: ModuleDefinition }) => {

View File

@@ -388,3 +388,4 @@ const handleSideNavClick = (item: SideNavItem) => {

View File

@@ -53,3 +53,4 @@

View File

@@ -76,3 +76,4 @@

View File

@@ -133,3 +133,4 @@ Feature Flag = 商业模式技术基础

View File

@@ -522,3 +522,4 @@ async chatWithRetry(provider: LLMProvider, prompt: string, maxRetries = 3) {

View File

@@ -533,3 +533,4 @@ function estimateTokens(text: string, model: string): number {

View File

@@ -105,3 +105,4 @@ GET /health - 健康检查

View File

@@ -100,3 +100,4 @@ interface RAGEngine {

View File

@@ -86,3 +86,4 @@ class ETLEngine:

View File

@@ -93,3 +93,4 @@

View File

@@ -99,3 +99,4 @@ ADMIN-运营管理端/

View File

@@ -502,3 +502,4 @@ async function getOverviewReport() {

View File

@@ -525,3 +525,4 @@ id String @id @default(uuid())

View File

@@ -68,3 +68,4 @@ AIA-AI智能问答/

View File

@@ -80,3 +80,4 @@ ASL-AI智能文献/

View File

@@ -319,3 +319,4 @@ A: 降级策略Nougat → PyMuPDF → 提示用户手动处理

View File

@@ -414,3 +414,4 @@ A✅ T1.1.1 - 在 `backend/prisma/schema.prisma` 中定义4个模型
**🎉 祝开发顺利!从 T1.1.1 开始吧!**

View File

@@ -96,3 +96,4 @@ DC-数据清洗整理/

View File

@@ -60,3 +60,4 @@ PKB-个人知识库/

View File

@@ -117,3 +117,4 @@

View File

@@ -93,3 +93,4 @@ RVW-稿件审查系统/

View File

@@ -82,3 +82,4 @@ SSA-智能统计分析/

View File

@@ -80,3 +80,4 @@ ST-统计分析工具/

View File

@@ -495,3 +495,4 @@ content TEXT -- 内容

View File

@@ -525,3 +525,4 @@ If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

View File

@@ -347,3 +347,4 @@ CREATE TABLE ssa_schema.analysis_projects (

View File

@@ -391,3 +391,4 @@

View File

@@ -855,3 +855,4 @@ git push-current # 推送当前分支
**版本历史:**
- v1.0 (2025-11-16): 初始版本,包含完整的 Git 规范和中文乱码解决方案

View File

@@ -38,3 +38,4 @@

View File

@@ -60,3 +60,4 @@

View File

@@ -63,3 +63,4 @@

View File

@@ -206,3 +206,4 @@ npm run dev

View File

@@ -886,3 +886,4 @@ Week 1结束时应达到

View File

@@ -763,3 +763,4 @@ Day 3: 文档更新 4小时
**文档结束**

View File

@@ -202,3 +202,4 @@ model Project {

View File

@@ -300,3 +300,4 @@ DROP SCHEMA IF EXISTS st_schema CASCADE;

View File

@@ -126,3 +126,4 @@ ORDER BY nspname;

View File

@@ -144,3 +144,4 @@ FROM platform_schema.users;

View File

@@ -337,3 +337,4 @@ FROM aia_schema.messages;

View File

@@ -410,3 +410,4 @@ FROM pkb_schema.batch_tasks;

View File

@@ -542,3 +542,4 @@ SELECT

View File

@@ -266,3 +266,4 @@ Write-Host "脚本执行完成!" -ForegroundColor Green

View File

@@ -555,3 +555,4 @@ const MyComponent = () => {

View File

@@ -458,3 +458,4 @@ import type { FastifyRequest, FastifyReply } from 'fastify'

View File

@@ -409,3 +409,4 @@ curl http://localhost:3001/api/v1/review

View File

@@ -448,3 +448,4 @@ modules/ ← 新代码,标准化

View File

@@ -242,3 +242,4 @@ Prisma Client在生成时已经读取了每个model的`@@schema()`标签,

View File

@@ -85,3 +85,4 @@

View File

@@ -233,3 +233,4 @@ isExternal?: boolean

View File

@@ -230,3 +230,4 @@ sed -i '1s/^\xEF\xBB\xBF//' file.txt

View File

@@ -675,3 +675,4 @@ DELETE /api/v1/[module]/resources/:id # 删除

View File

@@ -364,3 +364,4 @@ L2模块5分钟 → 深入了解具体模块

View File

@@ -473,3 +473,4 @@ curl -X POST "http://localhost:3001/api/v1/xxx/resources" \

View File

@@ -77,3 +77,4 @@

View File

@@ -178,3 +178,4 @@ POST /api/v1/[module]/[resource2]

View File

@@ -218,3 +218,4 @@ INSERT INTO xxx_schema.xxx_table_name (field_name, status) VALUES

View File

@@ -85,3 +85,4 @@