feat(platform): Complete Postgres-Only architecture refactoring (Phase 1-7)

Major Changes: - Implement Platform-Only architecture pattern (unified task management) - Add PostgresCacheAdapter for unified caching (platform_schema.app_cache) - Add PgBossQueue for job queue management (platform_schema.job) - Implement CheckpointService using job.data (generic for all modules) - Add intelligent threshold-based dual-mode processing (THRESHOLD=50) - Add task splitting mechanism (auto chunk size recommendation) - Refactor ASL screening service with smart mode selection - Refactor DC extraction service with smart mode selection - Register workers for ASL and DC modules Technical Highlights: - All task management data stored in platform_schema.job.data (JSONB) - Business tables remain clean (no task management fields) - CheckpointService is generic (shared by all modules) - Zero code duplication (DRY principle) - Follows 3-layer architecture principle - Zero additional cost (no Redis needed, save 8400 CNY/year) Code Statistics: - New code: ~1750 lines - Modified code: ~500 lines - Test code: ~1800 lines - Documentation: ~3000 lines Testing: - Unit tests: 8/8 passed - Integration tests: 2/2 passed - Architecture validation: passed - Linter errors: 0 Files: - Platform layer: PostgresCacheAdapter, PgBossQueue, CheckpointService, utils - ASL module: screeningService, screeningWorker - DC module: ExtractionController, extractionWorker - Tests: 11 test files - Docs: Updated 4 key documents Status: Phase 1-7 completed, Phase 8-9 pending
2025-12-13 16:10:04 +08:00
parent a3586cdf30
commit fa72beea6c
135 changed files with 17508 additions and 91 deletions
--- a/部署检查清单.md
+++ b/部署检查清单.md
@@ -0,0 +1,351 @@
+# 🚀 SAE部署检查清单
+
+> **用途：** 部署前的最后检查，确保不遗漏任何步骤  
+> **使用方法：** 打印或在另一个屏幕上打开，逐项勾选  
+> **预计时间：** 10分钟检查
+
+---
+
+## 📋 阶段1：阿里云服务准备
+
+### 云数据库 RDS
+
+- [ ] RDS实例已创建（PostgreSQL 15+）
+- [ ] 数据库 `aiclinical_dev` 已创建
+- [ ] 数据库用户 `aiclinical` 已创建
+- [ ] 用户已授权读写权限
+- [ ] 白名单已添加（可以先设置为 `0.0.0.0/0`）
+- [ ] 已获取内网连接地址（`rm-xxxx.mysql.rds.aliyuncs.com`）
+- [ ] 已测试连接成功
+
+**快速验证命令：**
+```bash
+# 使用 psql 或任何PostgreSQL客户端
+psql "postgresql://aiclinical:密码@rm-xxxx.mysql.rds.aliyuncs.com:5432/aiclinical_dev"
+```
+
+---
+
+### 对象存储 OSS
+
+- [ ] Bucket `aiclinical-dev` 已创建
+- [ ] Bucket区域与RDS相同
+- [ ] 存储类型设置为「标准存储」
+- [ ] 读写权限设置为「私有」
+- [ ] RAM用户 `aiclinical-oss` 已创建
+- [ ] RAM用户已授权 `AliyunOSSFullAccess`
+- [ ] 已获取 AccessKeyId 和 AccessKeySecret
+- [ ] 已保存密钥到安全的地方（只显示一次！）
+
+**快速验证：**
+```bash
+# 使用ossutil测试
+ossutil ls oss://aiclinical-dev
+```
+
+---
+
+### 容器镜像服务 ACR
+
+- [ ] 容器镜像服务已开通
+- [ ] 命名空间 `aiclinical` 已创建
+- [ ] 镜像仓库 `backend-dev` 已创建
+- [ ] 镜像仓库类型为「私有」
+- [ ] 已设置镜像仓库登录密码
+- [ ] 已测试Docker登录成功
+
+**快速验证：**
+```powershell
+docker login --username=你的阿里云账号 registry.cn-hangzhou.aliyuncs.com
+# 输入密码，看是否 "Login Succeeded"
+```
+
+---
+
+## 📦 阶段2：Docker镜像准备
+
+### 后端镜像
+
+- [ ] `backend/Dockerfile` 文件已创建
+- [ ] `backend/.dockerignore` 文件已创建
+- [ ] Docker Desktop 已启动
+- [ ] 镜像构建成功（`docker build -t aiclinical-backend:dev .`）
+- [ ] 镜像标签已创建（`docker tag ...`）
+- [ ] 镜像已推送到ACR（`docker push ...`）
+- [ ] 在ACR控制台确认镜像版本存在
+
+**快速验证：**
+```powershell
+# 查看本地镜像
+docker images | Select-String "aiclinical-backend"
+
+# 查看ACR远程镜像
+# 登录ACR控制台 → 镜像仓库 → backend-dev → 镜像版本
+```
+
+---
+
+### Python微服务镜像（可选）
+
+- [ ] `extraction_service/Dockerfile` 文件已创建
+- [ ] 镜像构建成功
+- [ ] 镜像已推送到ACR
+- [ ] 镜像仓库 `python-dev` 已创建
+
+**临时方案：** 如果Python服务还在本地运行，可以先跳过，等后端部署成功后再处理
+
+---
+
+## ⚙️ 阶段3：环境变量准备
+
+### 必填变量（缺一不可）
+
+- [ ] `NODE_ENV=development`
+- [ ] `DATABASE_URL=postgresql://...`（替换为真实RDS地址）
+- [ ] `OSS_REGION=oss-cn-hangzhou`
+- [ ] `OSS_BUCKET=aiclinical-dev`
+- [ ] `OSS_ACCESS_KEY_ID=你的ID`
+- [ ] `OSS_ACCESS_KEY_SECRET=你的Secret`
+- [ ] `DEEPSEEK_API_KEY=你的Key`（或其他LLM API Key）
+- [ ] `JWT_SECRET=随机字符串32位以上`
+
+### 推荐配置
+
+- [ ] `CACHE_TYPE=memory`（初期不用Redis）
+- [ ] `QUEUE_TYPE=memory`
+- [ ] `LOG_LEVEL=debug`（开发环境）
+- [ ] `CORS_ORIGIN=*`（开发环境）
+
+### 特殊字符检查
+
+- [ ] 所有密码和密钥不包含 `@ # $ % & 空格`
+- [ ] DATABASE_URL中的密码已正确转义（如果有特殊字符）
+- [ ] JWT_SECRET是随机生成的（不要用默认值！）
+
+**快速验证：**
+```bash
+# 复制 .env.sae.example 内容到文本编辑器
+# 逐行替换所有"你的XXX"
+# 确认没有遗漏
+```
+
+---
+
+## 🚀 阶段4：SAE应用创建
+
+### 基本配置
+
+- [ ] 应用名称：`aiclinical-backend-dev`
+- [ ] VPC 与 RDS 在同一个VPC
+- [ ] 镜像地址：`registry.cn-hangzhou.aliyuncs.com/aiclinical/backend-dev:v1.0.0`
+- [ ] 端口：`3001`
+- [ ] 实例规格：`1核2GB`
+- [ ] 实例数：`1`（固定）
+
+### 网络配置
+
+- [ ] 已勾选「公网访问」
+- [ ] 公网SLB已自动创建
+- [ ] 端口映射：`3001 → 3001`
+
+### 健康检查
+
+- [ ] 检查方式：`HTTP`
+- [ ] 检查路径：`/health`
+- [ ] 端口：`3001`
+- [ ] 初始延迟：`30秒`
+- [ ] 检查间隔：`10秒`
+- [ ] 超时时间：`3秒`
+
+### 环境变量
+
+- [ ] 所有必填环境变量已配置
+- [ ] 环境变量值已替换为真实值
+- [ ] 数据库URL格式正确
+- [ ] OSS密钥正确
+- [ ] JWT_SECRET已修改
+
+---
+
+## ✅ 阶段5：部署验证
+
+### 部署状态
+
+- [ ] SAE应用状态显示「运行中」
+- [ ] 健康检查显示「通过」
+- [ ] 实时日志无ERROR
+- [ ] 日志显示「✅ 数据库连接成功」
+- [ ] 日志显示「📦 使用阿里云 OSS 存储」或「📁 使用本地文件存储」
+
+### 接口测试
+
+- [ ] `/health` 接口返回 200
+- [ ] 返回JSON包含 `{"status":"ok"}`
+- [ ] 返回JSON包含 `"database":"connected"`
+
+**测试命令：**
+```powershell
+# 替换为你的SAE公网地址
+curl http://你的SAE地址:3001/health
+
+# 或在浏览器访问
+```
+
+### 数据库验证
+
+- [ ] 数据库Schema已创建
+- [ ] 必要的表已创建（prisma_migrations等）
+- [ ] 测试数据可以插入
+
+**验证SQL：**
+```sql
+-- 连接到RDS
+\c aiclinical_dev
+
+-- 查看Schema
+SELECT schema_name FROM information_schema.schemata;
+
+-- 查看表
+\dt platform_schema.*
+\dt aia_schema.*
+```
+
+### OSS验证
+
+- [ ] 测试文件上传成功
+- [ ] 在OSS控制台能看到上传的文件
+- [ ] 文件可以正常下载
+
+---
+
+## 🌐 阶段6：前端部署
+
+### 构建准备
+
+- [ ] `frontend-v2/vite.config.ts` 已配置正确的后端地址
+- [ ] 环境变量 `VITE_API_BASE_URL` 已设置
+- [ ] 依赖已安装（`npm install`）
+- [ ] 构建成功（`npm run build`）
+- [ ] `dist/` 目录生成
+
+### OSS上传
+
+- [ ] 前端文件已上传到OSS
+- [ ] 文件路径正确（可以放在 `frontend/` 目录下）
+- [ ] `index.html` 设置为默认首页
+- [ ] 静态网站托管已开启
+
+### 访问验证
+
+- [ ] 前端URL可以访问
+- [ ] 页面正常显示（无404）
+- [ ] 前端可以连接后端API
+- [ ] 登录功能正常
+- [ ] 文件上传功能正常
+
+**快速验证：**
+```
+访问：http://aiclinical-dev.oss-cn-hangzhou.aliyuncs.com/
+或：https://aiclinical-dev.oss-cn-hangzhou.aliyuncs.com/（如果配置了CDN）
+```
+
+---
+
+## 📊 阶段7：监控配置（可选）
+
+### SAE监控
+
+- [ ] 应用监控已开启
+- [ ] CPU使用率图表正常
+- [ ] 内存使用率图表正常
+- [ ] QPS图表正常
+
+### 日志查询
+
+- [ ] 实时日志可查看
+- [ ] 历史日志可查询
+- [ ] 日志级别设置正确
+
+### 告警配置（可选）
+
+- [ ] CPU告警（>80%）
+- [ ] 内存告警（>80%）
+- [ ] 错误率告警（>5%）
+
+---
+
+## 🎉 完成！
+
+### 最终验证清单
+
+- [ ] 后端健康检查通过
+- [ ] 前端页面可访问
+- [ ] 前后端通信正常
+- [ ] 数据库读写正常
+- [ ] OSS文件上传下载正常
+- [ ] 日志记录正常
+- [ ] 无ERROR日志
+
+### 重要信息记录
+
+请将以下信息保存到安全的地方（推荐使用密码管理器）：
+
+```
+【部署信息】
+
+后端地址：http://_______________:3001
+前端地址：http://_______________
+
+RDS连接：
+- 地址：_______________
+- 数据库：aiclinical_dev
+- 用户名：aiclinical
+- 密码：_______________
+
+OSS配置：
+- Bucket：aiclinical-dev
+- AccessKeyId：_______________
+- AccessKeySecret：_______________
+
+镜像仓库：
+- 命名空间：aiclinical
+- 仓库：backend-dev
+- 最新版本：_______________
+- 登录密码：_______________
+
+部署时间：_______________
+部署人：_______________
+```
+
+---
+
+## 🆘 遇到问题？
+
+### 快速排查步骤
+
+1. **查看实时日志**
+   - SAE控制台 → 应用详情 → 实时日志
+   - 找红色ERROR关键词
+
+2. **检查环境变量**
+   - SAE控制台 → 应用详情 → 环境变量
+   - 确认所有变量正确
+
+3. **测试网络连通性**
+   - 后端能否连接RDS
+   - 后端能否连接OSS
+   - 前端能否连接后端
+
+4. **查看详细文档**
+   - `docs/05-部署文档/02-SAE部署完全指南(产品经理版).md`
+   - 里面有详细的问题排查方法
+
+---
+
+**版本：** v1.0  
+**最后更新：** 2025-12-11  
+**维护者：** 技术架构师
+
+
+
+