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

docs/09-架构实施/J技术架构咨询/数据库同步规范与 Prisma 操作指南.md

@@ -0,0 +1,96 @@
+# **Prisma 数据库同步与生产部署规范 (SOP)**
+
+针对本地 schema.prisma 与真实数据库不同步（Schema Drift）的问题，结合我们平台的“Postgres-Only”架构特性（存在大量非 Prisma 管理的底层函数，如 pg-boss），特制定本规范。
+
+## **一、 当前差距有多大？如何安全评估？**
+
+由于我无法直接连接您的本地数据库，当前的“具体差距”需要您通过命令行来测量。基于系统近期的 V2.1 迭代（引入了 SSA QPER 架构、RVW 模块 Schema 隔离、IIT 模块表等），大概率存在未提交的 Migration 或手动修改的字段。
+
+### **安全测量差距的指令（只读，绝对安全）**
+
+请在 backend 目录下运行以下命令来查看差距，**不要直接跑 push**：
+
+\# 查看本地 Schema 与当前数据库的差异 (Diff)  
+npx prisma migrate diff \--from-schema-datamodel prisma/schema.prisma \--to-schema-datamodel prisma/schema.prisma
+
+\# 或者更直观地查看哪些迁移尚未应用  
+npx prisma migrate status
+
+**差距通常分为三类：**
+
+1. **Prisma 超前**：你在 schema.prisma 里加了新模型（如 IitProject），但还没在数据库建表。  
+2. **数据库超前**：你或队友手动在数据库里跑了 SQL 加了字段，但没更新到 schema.prisma。  
+3. **平台边界对象（预期内差距）**：数据库中存在 platform\_schema.job\_common 表和 create\_queue() 函数。由于我们是 Postgres-Only 架构使用了 pg-boss，这些对象**不由 Prisma 管理**，在对比时 Prisma 可能会认为这些是“多余的”，这是正常的，**绝对不能让 Prisma 删掉它们**。
+
+## **二、 如何彻底解决并确立规范操作？**
+
+要彻底解决不同步问题，必须明确\*\*“唯一事实来源 (Single Source of Truth)”**。在现代 ORM 开发流程中，**schema.prisma 必须是数据库结构的唯一事实来源\*\*。
+
+### **🔴 绝对红线（重申 2026-01-11 事故教训）**
+
+任何情况下，**严禁**使用以下命令（除非是全新的空数据库）：
+
+* ❌ npx prisma db push \--force-reset （会清空所有数据并删除 pg-boss 队列！）  
+* ❌ npx prisma migrate reset （会重置整个数据库）  
+* ❌ npx prisma db push （在生产环境**绝对禁用**，在本地也尽量少用，因为它不生成迁移历史，容易导致状态撕裂）
+
+### **✅ 规范 1：本地开发环境同步 SOP（解决当前不同步）**
+
+当你在本地发现 schema.prisma 和数据库不一致时，请严格按照以下 4 步操作：
+
+**Step 1: 强制备份（生命线）**
+
+docker exec ai-clinical-postgres pg\_dump \-U postgres \-d ai\_clinical\_research \> backup\_$(date \+%Y%m%d).sql
+
+**Step 2: 确定谁才是对的？**
+
+* **情况 A（正常开发）：schema.prisma 是最新的，数据库旧了。**  
+  执行生成迁移文件的命令：  
+  npx prisma migrate dev \--name describe\_your\_changes
+
+  *说明：这会根据 Prisma Schema 生成一段完整的 SQL (.sql 文件)，并安全地应用到本地数据库。如果报错说有冲突，通常是因为存在手动修改的数据。*  
+* **情况 B（特殊情况）：数据库是最新的（比如 DBA 直接改了库），schema.prisma 旧了。**  
+  执行反向拉取：  
+  npx prisma db pull
+
+  *说明：这会将数据库当前的真实结构覆盖写入你的 schema.prisma 中。完成后别忘了执行 npx prisma generate 更新 Node.js 客户端。*
+
+**Step 3: 重新生成 Client**
+
+无论采用哪种情况，同步完成后必须刷新客户端：
+
+npx prisma generate
+
+### **✅ 规范 2：生产环境部署 SOP（未来如何部署）**
+
+在云端（阿里云 SAE \+ RDS）部署时，数据库的操作极其敏感。生产环境**只允许通过标准的 SQL 迁移文件进行变更**。
+
+**Step 1: 确保本地已生成 Migration**
+
+在本地开发完成后，所有的变更都应该已经通过 npx prisma migrate dev 生成在了 prisma/migrations/ 目录下，并随代码提交到了 Git 仓库。
+
+**Step 2: 生产环境应用迁移**
+
+在后端服务部署时（可以通过 CI/CD 管道，或在单独的部署容器中），执行以下命令：
+
+\# 设置生产环境变量  
+export DATABASE\_URL="postgresql://user:password@rds-host:5432/ai\_clinical\_research"
+
+\# 执行生产部署专属命令  
+npx prisma migrate deploy
+
+*原理：migrate deploy **不会**去对比 schema.prisma，它只会傻瓜式地检查 \_prisma\_migrations 表，把还没跑过的 .sql 脚本按顺序执行一遍。这是业界最安全、最规范的做法。*
+
+### **✅ 规范 3：Postgres-Only 架构特殊边界守护**
+
+因为我们平台利用了 PostgreSQL 作为队列（pg-boss）和缓存，Prisma 在执行某些深度同步时，可能会误删这些非 Prisma 表。
+
+**防范策略：**
+
+1. 始终保留恢复脚本（目前我们已有 restore\_job\_common.sql 和 restore\_pgboss\_functions.sql）。  
+2. 在执行 migrate dev 之后，如果发现 pg-boss 服务崩溃，立即通过 psql 执行上述恢复脚本，将函数重新注入到 platform\_schema 中。  
+3. 团队成员之间必须达成共识：所有针对业务表的修改必须走 schema.prisma；所有针对平台底层调度机制（如缓存、队列函数）的修改，直接走原生 SQL，并将其文档化。
+
+## **结语**
+
+遵循 **“以 schema.prisma 为核心 \-\> 生成 Migration \-\> 本地 migrate dev \-\> 生产 migrate deploy”** 这条标准流水线，就能彻底告别环境撕裂，且为百人并发、多实例部署提供最坚实的数据底座。

docs/09-架构实施/J技术架构咨询/阿里云 SAE 全栈部署与高并发弹性策略指南.md

@@ -0,0 +1,112 @@
+# **阿里云 SAE 全栈部署与高并发弹性策略指南**
+
+基于 AIclinicalresearch 平台当前的四层架构（前端、Node.js 后端、Python 微服务、R 统计引擎），本指南旨在统筹规划阿里云 Serverless App Engine (SAE) 的使用策略。不仅涵盖了 R 引擎的单线程阻断解法，更扩展至全栈模块的弹性配置、潮汐流量应对 SOP，以及 SAE 高阶功能的深度利用。
+
+## **一、 全系统 SAE 规格与弹性扩容指标配置**
+
+针对不同模块的技术特性，SAE 的**弹性扩容指标**（触发 Scale-out 的阈值）必须差异化配置，切忌一刀切。
+
+### **1\. R 统计引擎 (ssa-r-statistics)**
+
+* **特性**：R 语言和 Plumber 框架默认单线程阻塞。复杂矩阵运算消耗大量 CPU 和内存。镜像极大（1.81GB）。  
+* **基础规格**：2 vCPU, 4 GB （绝对下限）。  
+* **实例数策略**：最小实例 \= 1，最大实例 \= 5。  
+* **🔥 弹性扩容指标**：**基于并发请求数 (QPS / 并发连接数)**。  
+  * **策略**：当单实例并发请求数 \> 1 或 \> 2 时，立即触发扩容。因为 CPU 还没跑满时，请求已经在排队了，必须用并发数来敏锐感知阻塞。
+
+### **2\. Node.js 后端 (backend-service)**
+
+* **特性**：异步非阻塞，擅长高并发 I/O。持有大量 SSE 长链接（AI 流式对话）。包含 pg-boss 队列。  
+* **基础规格**：2 vCPU, 4 GB。  
+* **实例数策略**：最小实例 \= 1，最大实例 \= 5。  
+* **🔥 弹性扩容指标**：**基于 CPU 和内存使用率**。  
+  * **策略**：当 CPU 使用率 \> 70% 或 内存使用率 \> 80% 时触发扩容。Fastify 框架抗并发极强，通常是 JSON 序列化或 Prisma 并发查询导致 CPU 飙升。
+
+### **3\. Python 微服务 (python-extraction)**
+
+* **特性**：PDF 解析（PyMuPDF）和数据清洗（Pandas）是内存消耗大户。  
+* **基础规格**：1 vCPU, 2 GB 或 2 vCPU, 4 GB（取决于平均 PDF 大小）。  
+* **实例数策略**：最小实例 \= 1，最大实例 \= 3。  
+* **🔥 弹性扩容指标**：**基于内存使用率**。  
+  * **策略**：当内存使用率 \> 85% 时扩容。Python 数据处理极易引发 OOM，需通过扩容分散大文件处理压力。
+
+### **4\. 前端 Nginx (frontend-nginx)**
+
+* **特性**：静态资源分发，极度轻量。  
+* **基础规格**：1 vCPU, 2 GB（甚至更低）。  
+* **实例数策略**：最小实例 \= 1，最大实例 \= 3。  
+* **🔥 弹性扩容指标**：**基于 CPU 或出网流量**。  
+  * **策略**：CPU \> 60% 或 出网带宽达到瓶颈时扩容。
+
+## **二、 高并发场景操作 SOP（以“培训班”潮汐流量为例）**
+
+面对培训班（如 50-100 人同时操作统计模块）产生的突发流量，**千万不能依赖临时的自动扩容**（拉取 1.8GB 镜像需要时间，会导致大规模 504 超时）。必须采用\*\*定时弹性伸缩（Cron HPA）\*\*进行预热。
+
+### **🎯 操作时间线与策略**
+
+#### **1\. 培训班开始前 1 天（配置策略）**
+
+* **动作**：登录阿里云 SAE 控制台，进入 R 统计引擎和 Node.js 后端的【弹性伸缩】配置页面。  
+* **配置**：添加“定时弹性策略”（Cron HPA）。  
+  * 设定执行时间：例如 2026-03-01 08:30（提前半小时）。  
+  * 设定目标实例数：强制将实例数扩展至 3 或 5 个。
+
+#### **2\. 培训班开始前 30 分钟（系统预热）**
+
+* **动作**：SAE 会根据设定的 Cron 规则自动启动新实例。  
+* **效果**：系统完成 1.8GB 镜像拉取、环境初始化、加载 R/Python 依赖包。所有实例状态变为 Healthy，提前排兵布阵完毕。
+
+#### **3\. 培训班进行中（9:00 \- 17:00）**
+
+* **动作**：无需人工干预。  
+* **效果**：50 名学员同时点击“运行 T 检验”，SAE 网关将请求均匀分发给 5 个预热好的 R 引擎实例。单线程阻塞被完美的物理隔离化解。
+
+#### **4\. 培训班结束后（17:30 以后）**
+
+* **动作**：依靠 SAE 的定时策略或自动缩容策略自动执行。  
+* **效果**：实例数恢复至最小 1 个，立刻停止多余计费。整体成本开销仅为 5 个实例运行 8 小时的费用（极具性价比）。
+
+## **三、 全栈架构如何深度利用 SAE 高阶功能**
+
+除了弹性扩容，结合你们的系统状态，强烈建议启用 SAE 的以下功能来提升系统的企业级稳定性：
+
+### **1\. 开启“镜像加速”（针对大镜像冷启动）**
+
+* **适用模块**：Python 微服务 (1.1GB)、R 统计引擎 (1.81GB)。  
+* **配置与价值**：在 SAE 应用配置中勾选【镜像加速】。SAE 底层会通过按需加载数据块的技术（如 DADI），将几分钟的冷启动时间压缩到秒级。这是应对偶发流量突增的核心兜底技术。
+
+### **2\. 优雅上下线与无损发布 (Graceful Shutdown)**
+
+* **适用模块**：Node.js 后端（特别是 pg-boss 队列）。  
+* **配置与价值**：  
+  * 目前你们的 ASL 和 DC 模块深度依赖 pg-boss 处理异步任务。  
+  * 如果 SAE 突然缩容杀掉 Node 实例，运行中的文献抓取任务会中断。  
+  * **操作**：在 SAE 中配置优雅下线时间（如 30 秒）。在 Node.js 代码中监听 SIGTERM 信号，收到信号后，停止接收新 HTTP 请求，但**等待 pg-boss 正在处理的 job 执行完毕**后再退出容器。
+
+### **3\. Liveness 与 Readiness 探针 (健康检查)**
+
+* **适用模块**：全模块。  
+* **配置与价值**：  
+  * **Liveness (存活探针)**：配置在 GET /health。如果 R 引擎死锁，探针连续 3 次失败，SAE 会自动重启该容器（自愈能力）。  
+  * **Readiness (就绪探针)**：在应用刚启动、正在建立 PostgreSQL 数据库连接池或加载 R 语言模型时，Readiness 返回 false，SAE 不会把用户流量打过来，避免报错。
+
+### **4\. 长链接防断开配置 (针对 SSE 架构)**
+
+* **适用模块**：Node.js 后端、R 统计引擎、前端 Nginx。  
+* **配置与价值**：系统中有大量的打字机效果（AI 流式对话）和进度条流式推送（SSE）。必须在 SAE 的网关层（如 ALB/CLB）调整 **闲置超时时间 (Idle Timeout)**，建议设置为 120秒 或更长，防止长时间推理时网络连接被强制切断。
+
+### **5\. 一体化可观测性 (SLS 日志与 APM 链路监控)**
+
+* **适用模块**：全模块。  
+* **配置与价值**：  
+  * **日志采集**：将各容器的 stdout 日志一键收集到阿里云 SLS，所有报错无需 SSH 登录服务器，直接在网页端关键词检索（如 \[ERROR\] R引擎）。  
+  * **链路追踪**：SAE 支持无侵入式 APM。你能清晰看到一条请求：从 前端 \-\> Node.js (消耗 50ms) \-\> R 引擎 (消耗 2000ms) 的全链路耗时，精准定位系统性能瓶颈。
+
+## **四、 总结：运维与管理策略时间线**
+
+1. **日常平峰期**：所有微服务维持 最小实例 1，最大实例 3/5。通过“并发数”和“CPU”的双重自动弹性指标应对日常零星的并发波动。  
+2. **大版本更新日**：利用 SAE 的“分批发布”或“灰度发布”功能。先替换 1 个实例为 v2.0，测试无误后再全量更新，实现业务零停机。  
+3. **大中型活动（培训班）**：提前在日历上标记，通过 SAE 【定时弹性策略】提前 30 分钟扩容预热大容器，活动后自动缩容。  
+4. **故障排查时**：不再去看单机日志，直接利用 SAE 挂载的 ARMS（应用实时监控服务）查看错误率飙升的模块，或者进入 SLS 搜索 TraceID。
+
+这套体系将彻底把你们的研发团队从繁琐的运维、服务器抗压焦虑中解放出来，让 "Serverless (无服务器)" 的红利在你们的临床 AI 系统中最大化展现。