docs(platform): Add database documentation system and restructure deployment docs

Completed: - Add 6 core database documents (docs/01-平台基础层/07-数据库/) Architecture overview, migration history, environment comparison, tech debt tracking, seed data management, PostgreSQL extensions - Restructure deployment docs: archive 20 legacy files to _archive-2025/ - Create unified daily operations manual (01-日常更新操作手册.md) - Add pending deployment change tracker (03-待部署变更清单.md) - Update database development standard to v3.0 (three iron rules) - Fix Prisma schema type drift: align @db.* annotations with actual DB IIT: UUID/Timestamptz(6), SSA: Timestamp(6)/VarChar(20/50/100) - Add migration: 20260227_align_schema_with_db_types (idempotent ALTER) - Add Cursor Rule for auto-reminding deployment change documentation - Update system status guide v6.4 with deployment and DB doc references - Add architecture consultation docs (Prisma guide, SAE deployment guide) Technical details: - Manual migration due to shadow DB limitation (TD-001 in tech debt) - Deployment docs reduced from 20+ scattered files to 3 core documents - Cursor Rule triggers on schema.prisma, package.json, Dockerfile changes Made-with: Cursor
2026-02-27 14:35:25 +08:00
parent 9b8490b4d0
commit 6124c7abc6
48 changed files with 3009 additions and 582 deletions
--- a/docs/05-部署文档/0227部署/02-部署完成总结.md
+++ b/docs/05-部署文档/0227部署/02-部署完成总结.md
@@ -0,0 +1,355 @@
+# 2026年2月27日部署完成总结
+
+> **部署日期**：2026-02-27  
+> **部署范围**：数据库迁移 + R统计引擎（新增） + Python微服务 + Node.js后端 + 前端Nginx 全量更新  
+> **部署状态**：✅ 全部完成，所有功能测试通过  
+> **文档日期**：2026-02-27
+
+---
+
+## 部署成果一览
+
+### 服务版本对比
+
+| 服务 | 部署前 | 部署后 | 变更类型 |
+|------|--------|--------|---------|
+| PostgreSQL（RDS） | 16 Schema / 63 表 | 16 Schema / 84 表 | Schema迁移 |
+| R统计引擎 | 无 | **v1.0.1** | **全新部署** |
+| Python微服务 | v1.1 | **v1.2** | 依赖+代码更新 |
+| Node.js后端 | v1.7 | **v2.2** | 大版本更新（5万行新增） |
+| 前端Nginx | v1.3 | **v1.8** | 大版本更新（3.2万行新增） |
+
+### 内网地址总览
+
+| 服务 | 内网地址 | 端口 | 状态 |
+|------|---------|------|------|
+| R统计引擎（新） | `172.17.173.101` | 8080 | ✅ 新增 |
+| Python微服务 | `172.17.173.102` | 8000 | ✅ 地址变更 |
+| Node.js后端 | `172.17.197.28` | 3001 | ✅ 地址变更 |
+| 前端Nginx | `172.17.197.29` | 80 | ✅ 地址变更 |
+
+---
+
+## 一、数据库迁移
+
+### 1.1 迁移背景
+
+自 0126 部署以来，本地开发环境新增了大量功能模块（IIT Agent、SSA统计分析、ASL提取工作台等），导致本地数据库与RDS之间存在显著差异。部分变更通过 `prisma db push` 直接推送，未生成迁移文件，造成 Schema Drift。
+
+### 1.2 迁移内容
+
+**应用的 Prisma 迁移文件**（5个）：
+
+| 迁移文件 | 内容 | 新增表数 |
+|---------|------|---------|
+| `20260207_add_iit_manager_agent_tables` | IIT Agent 8张表 | 8 |
+| `20260208_add_cra_qc_engine_support` | CRA智能质控 | 1 |
+| `20260219_add_ssa_module` | SSA统计分析模块 9张表 | 9 |
+| `20260223_add_deep_research_v2_fields` | Deep Research V2.0 字段 | 0（列变更） |
+| `20260225_add_extraction_template_engine` | 全文智能提取工作台 4张表 | 4 |
+
+**Drift 补丁迁移**（1个）：
+
+| 迁移文件 | 内容 |
+|---------|------|
+| `20260227_patch_db_push_drift` | 修复 `prisma db push` 造成的 drift：`field_metadata`、`qc_logs`、`record_summary`、`qc_project_stats`、`ssa_workflows`、`ssa_workflow_steps` 等表 + `knowledge_base_id` 列 |
+
+**Seed 数据同步**：
+
+| 数据 | 条目数 | 目标表 |
+|------|-------|-------|
+| SSA 工具库 | 13条 | `ssa_schema.ssa_tools_library` |
+| IIT 技能库 | 8条 | `iit_schema.iit_skills` |
+
+### 1.3 迁移结果
+
+| 验证项 | 结果 |
+|-------|------|
+| Schema 数量 | 16 ✅ |
+| 表总数 | 84 ✅ |
+| Prisma 迁移记录 | 11条（含6条新增） ✅ |
+| SSA 工具库数据 | 13条 ✅ |
+| IIT 技能库数据 | 8条 ✅ |
+| 已有数据完整性 | Prompt模板、用户数据零丢失 ✅ |
+
+> 详细方案见 `01-数据库迁移方案.md`
+
+---
+
+## 二、R统计引擎部署（全新服务）
+
+### 2.1 服务概述
+
+R统计引擎是 SSA（智能统计分析）模块的核心计算后端，采用 Brain-Hand 架构：Node.js 后端作为 Brain 负责调度，R Docker 作为 Hand 负责统计计算。
+
+### 2.2 镜像信息
+
+| 项目 | 值 |
+|------|---|
+| ACR 仓库 | `ssa-r-statistics` |
+| 镜像版本 | `v1.0.1` |
+| 镜像地址 | `crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ssa-r-statistics:v1.0.1` |
+| 镜像大小 | ~1.8GB |
+| 基础镜像 | `rocker/r-ver:4.3` |
+| R版本 | 4.3.3 |
+
+### 2.3 内置工具（13个）
+
+| 工具代码 | 功能 |
+|---------|------|
+| `descriptive` | 描述性统计 |
+| `t_test_ind` | 独立样本T检验 |
+| `t_test_paired` | 配对T检验 |
+| `mann_whitney` | Mann-Whitney U检验 |
+| `wilcoxon` | Wilcoxon符号秩检验 |
+| `chi_square` | 卡方检验 |
+| `fisher` | Fisher精确检验 |
+| `anova_one` | 单因素方差分析 |
+| `correlation` | 相关性分析 |
+| `linear_reg` | 线性回归 |
+| `logistic_binary` | 二元Logistic回归 |
+| `baseline_table` | 基线特征表 |
+| `meta_analysis` | Meta分析 |
+
+### 2.4 SAE 应用配置
+
+| 配置项 | 值 |
+|-------|---|
+| 应用名称 | `r-statistics-test` |
+| 实例规格 | 1核2GB |
+| 实例数量 | 1 |
+| 容器端口 | 8080 |
+| 内网地址 | `http://172.17.173.101:8080` |
+| 健康检查方式 | HTTP 检查 |
+| 健康检查路径 | `/health` |
+
+### 2.5 部署过程中的问题与解决
+
+**问题**：SAE HTTP 健康检查返回 404
+
+- **现象**：Readiness probe 报 `HTTP status code: 404, body: {"error":"404 - Resource Not Found"}`
+- **验证**：通过 SAE Webshell 执行 `curl http://localhost:8080/health` 返回 200 OK，确认服务本身正常
+- **解决**：最终 HTTP 健康检查配置调整后恢复正常
+
+---
+
+## 三、Python微服务更新
+
+### 3.1 更新内容
+
+**依赖变更**（requirements-prod.txt）：
+
+| 变更 | 包名 | 用途 |
+|------|-----|------|
+| 新增 | `scipy>=1.11.0` | RVW V2.0 数据侦探：T检验、卡方检验逆向计算 |
+
+**代码变更**：
+
+| 模块 | 变更 |
+|------|------|
+| `forensics/` | 全新模块 - RVW V2.0 数据取证（5个文件） |
+| `main.py` | 注册 forensics API 路由 |
+| `operations/data_profile.py` | 新增 scipy 统计验证 |
+
+### 3.2 镜像信息
+
+| 项目 | 值 |
+|------|---|
+| ACR 仓库 | `python-extraction` |
+| 镜像版本 | v1.1 → **v1.2** |
+| 镜像地址 | `crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.2` |
+| Digest | `sha256:be8612976255d706d652c5d16cb2e32c6e25b61a863d26c1ea7f63a9e0c95c86` |
+| 基础镜像 | `python:3-slim` |
+
+### 3.3 SAE 应用配置
+
+| 配置项 | 0126 部署 | 0227 部署 |
+|-------|----------|----------|
+| 应用名称 | `python-extraction-test` | `python-extraction-test` |
+| 实例规格 | 1核2GB | **2核4GB** |
+| 实例数量 | 1 | 1 |
+| 容器端口 | 8000 | 8000 |
+| 内网地址 | `172.17.173.84` | **`172.17.173.102`** |
+| 镜像版本 | v1.1 | **v1.2** |
+
+> 规格从 1核2GB 升至 2核4GB，因为新增的 scipy、pandas、numpy 等科学计算库在 2 个 worker 下内存占用较高。
+
+---
+
+## 四、Node.js后端更新
+
+### 4.1 更新内容
+
+**271个文件变更，50972行新增代码**，主要包括：
+
+| 类别 | 变更 |
+|------|------|
+| 新增依赖 | `adm-zip`（ZIP处理）、`json-logic-js`（规则引擎） |
+| 新增模块 | SSA 统计分析、ASL 图表/提取/Meta分析、RVW Skills、系统知识库 |
+| 重大更新 | IIT CRA Agent V3.0（自主QC+Function Calling）、Deep Research V2.0 |
+
+### 4.2 镜像信息
+
+| 项目 | 值 |
+|------|---|
+| ACR 仓库 | `backend-service` |
+| 镜像版本 | v1.7 → **v2.2** |
+| 镜像地址 | `crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v2.2` |
+| Digest | `sha256:5f5ede30c5ff107018176622c674b53c640816f288d49912434303d8a5253211` |
+| 构建方式 | `tsc --noCheck` + Docker 多阶段构建 |
+
+### 4.3 SAE 应用配置
+
+| 配置项 | 0126 部署 | 0227 部署 |
+|-------|----------|----------|
+| 应用名称 | `nodejs-backend-test` | `nodejs-backend-test` |
+| 实例规格 | 1核2GB | **2核4GB** |
+| 实例数量 | 1 | 1 |
+| 容器端口 | 3001 | 3001 |
+| 内网地址 | `172.17.173.89` | **`172.17.197.28`** |
+| 镜像版本 | v1.7 | **v2.2** |
+
+### 4.4 新增环境变量
+
+| 环境变量 | 值 | 说明 |
+|---------|---|------|
+| `EXTRACTION_SERVICE_URL` | `http://172.17.173.102:8000` | Python 新地址 |
+| `R_SERVICE_URL` | `http://172.17.173.101:8080` | R统计引擎（新增） |
+| `UNIFUNCS_API_KEY` | `sk-2fNwqUH7...` | Deep Research（新增） |
+| `MINERU_API_TOKEN` | （长token） | MinerU PDF提取（新增） |
+| `MINERU_API_BASE` | `https://mineru.net/api/v4` | MinerU地址（新增） |
+| `STORAGE_TYPE` | `oss` | 存储类型（新增） |
+
+---
+
+## 五、前端Nginx更新
+
+### 5.1 更新内容
+
+**129个文件变更，32365行新增代码**，主要包括：
+
+| 类别 | 变更 |
+|------|------|
+| 新增依赖 | `react-markdown`、`remark-gfm`（Markdown渲染） |
+| 新增模块 | SSA统计分析前端、ASL图表生成器/Meta分析引擎、IIT AI对话页 |
+| nginx.conf | `client_max_body_size 50M`、新增 `/wechat/` 代理路由 |
+
+### 5.2 镜像信息
+
+| 项目 | 值 |
+|------|---|
+| ACR 仓库 | `ai-clinical_frontend-nginx` |
+| 镜像版本 | v1.3 → **v1.8** |
+| Digest | `sha256:0a12b017ac6c85305fc5a716c5da245318c595fafd828c1222dd1a8ae79cfb26` |
+
+### 5.3 SAE 应用配置
+
+| 配置项 | 0126 部署 | 0227 部署 |
+|-------|----------|----------|
+| 应用名称 | `frontend-nginx-service` | `frontend-nginx-service` |
+| 实例规格 | 0.5核1GB | 0.5核1GB |
+| 容器端口 | 80 | 80 |
+| 内网地址 | `172.17.173.90` | **`172.17.197.29`** |
+| 镜像版本 | v1.3 | **v1.8** |
+| BACKEND_SERVICE_HOST | `172.17.173.89` | **`172.17.197.28`** |
+
+---
+
+## 六、部署过程中的问题与解决
+
+本次部署遇到 4 个问题，均已解决：
+
+### 6.1 前端登录报错：Unexpected token '<' is not valid JSON
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 登录页报 `Unexpected token '<', "<html> <h"... is not valid JSON`，`api/v1/auth/refresh` 返回 504 |
+| **原因** | 前端 `frontend-nginx-service` 环境变量 `BACKEND_SERVICE_HOST` 未更新为后端新地址，Nginx 代理到旧 IP 超时，返回 HTML 错误页 |
+| **解决** | 更新 `BACKEND_SERVICE_HOST` 为 `172.17.197.28`，重新部署前端 |
+
+### 6.2 SSA 上传数据报错：column `ssa_sessions.data_profile` does not exist
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 智能统计分析上传 CSV 后返回 500，`prisma.ssaSession.create()` 失败 |
+| **原因** | `data_profile` 列是 Phase 2A 通过 `prisma db push` 新增的，drift patch 迁移中遗漏了该列 |
+| **解决** | 通过 SAE Webshell 执行 `ALTER TABLE ssa_schema.ssa_sessions ADD COLUMN IF NOT EXISTS data_profile JSONB` |
+
+### 6.3 SSA 分析方案不推送：JSON 配置文件缺失
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 上传数据成功并获得数据报告，但提交分析需求后无分析方案卡片，日志报 `ENOENT: no such file or directory, open '/app/dist/modules/ssa/config/tools_registry.json'` |
+| **原因** | `tsc` 编译只处理 `.ts` 文件，不会复制 `.json` 配置文件到 `dist/` 目录。SSA 模块依赖 5 个 JSON 配置文件（`tools_registry.json`、`decision_tables.json`、`flow_templates.json`、`intent_rules.json`、`tool_param_constraints.json`） |
+| **解决** | 修改 Dockerfile 增加 JSON 文件复制步骤，重新构建 v2.2 并部署 |
+| **长期修复** | Dockerfile 中增加 `COPY src/modules/ssa/config/*.json ./dist/modules/ssa/config/` |
+
+### 6.4 RVW 上传文件报错：column `review_tasks.context_data` does not exist
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 智能审稿上传 docx 文件后返回 500，`prisma.reviewTask.create()` 失败 |
+| **原因** | `review_tasks` 表在 0126 部署后通过 `prisma db push` 新增了 8 个列（`selected_agents`、`editorial_score`、`methodology_score`、`methodology_status`、`pico_extract`、`context_data`、`is_archived`、`archived_at`），drift patch 中全部遗漏 |
+| **解决** | 通过 SAE Webshell 执行 8 条 `ALTER TABLE ADD COLUMN IF NOT EXISTS` 语句补齐 |
+
+### 6.5 经验教训
+
+| 教训 | 改进措施 |
+|------|---------|
+| `prisma db push` 造成大量 Schema Drift | 开发环境也应使用 `prisma migrate dev` 生成迁移文件 |
+| `tsc` 不复制非 TS 文件 | Dockerfile 中显式 COPY JSON/YAML 等资源文件 |
+| SAE 每次部署 IP 会变 | 部署后立即检查所有服务间的 IP 依赖并同步更新 |
+| drift patch 容易遗漏 | 部署前用脚本对比本地和 RDS 的完整列清单 |
+
+---
+
+## 七、CLB 负载均衡器更新
+
+前端内网地址变更，CLB 后端服务器需同步更新：
+
+| 配置项 | 旧值 | 新值 |
+|-------|------|------|
+| CLB 后端服务器 | `172.17.173.90:80` | **`172.17.197.29:80`** |
+
+> 如不更新，公网域名 `https://iit.xunzhengyixue.com/` 将无法访问。
+
+---
+
+## 八、当前系统配置速查
+
+### 数据库连接（测试环境）
+
+```
+postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research_test?connection_limit=18&pool_timeout=10
+```
+
+### 服务内网地址
+
+```
+R统计引擎: http://172.17.173.101:8080  (新增)
+Python:    http://172.17.173.102:8000  (更新)
+后端:      http://172.17.197.28:3001   (更新)
+前端:      http://172.17.197.29:80    (更新)
+```
+
+### ACR 镜像版本
+
+| 仓库 | 版本 |
+|------|-----|
+| `ssa-r-statistics` | v1.0.1 |
+| `python-extraction` | v1.2 |
+| `backend-service` | v2.2 |
+| `ai-clinical_frontend-nginx` | v1.8 |
+
+### 公网访问
+
+```
+CLB:  http://8.140.53.236/
+域名: https://iit.xunzhengyixue.com/
+```
+
+---
+
+> **文档版本**：v1.1  
+> **最后更新**：2026-02-27（补充部署问题与解决记录）  
+> **维护人员**：开发团队