Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(deploy): Complete 0302 deployment documentation for IIT V3.1 QC engine upgrade

Browse Source 
Summary:
- Create 0302 deployment summary (6 DB migrations + backend v2.4 + frontend v2.0)
- Update SAE status record with new IPs (172.17.197.32), versions, and history
- Update daily operations manual with incremented version numbers (backend v2.5, frontend v2.1)
- Clear pending deployment checklist and archive to history section
- Fix stale schema table counts (iit_schema 5->22, ssa_schema 0->11)

Deployment details:
- Database: 6 Prisma migrations applied (84->86 tables, 442 columns verified identical)
- Backend: v2.3->v2.4 (27 changes, IIT V3.1 QC engine + GCP report APIs)
- Frontend: v1.9->v2.0 (17 changes, GCP 5-tab reports + V3.1 dashboard)
- Both services deployed to SAE at 172.17.197.32

Made-with: Cursor
This commit is contained in:
HaHafeng
2026-03-02 08:36:56 +08:00
parent 2030ebe28f
commit 72928d3116
5 changed files with 262 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/05-部署文档/03-待部署变更清单.md
View File

@@ -3,7 +3,7 @@
> **用途**: 开发过程中实时记录所有待部署的变更，下次部署时按此清单逐项执行
> **维护规则**: 每次修改 Schema / 新增依赖 / 改配置时，**立即**在此文档追加记录
> **Cursor Rule**: `.cursor/rules/deployment-change-tracking.mdc` 会自动提醒
> **最后清零**: 2026-02-27（0227 部署完成后清零）
> **最后清零**: 2026-03-02（0302 部署完成后清零）
---
@@ -15,66 +15,19 @@
| # | 变更内容 | 迁移文件 | 优先级 | 备注 |
|---|---------|---------|--------|------|
| DB-1 | ssa_workflows 类型精度对齐 + 清理重复 FK | `20260227_align_schema_with_db_types` | 低 | 幂等 SQL，RDS 上执行无副作用 |
| DB-2 | Phase 2: user_mappings 加 user_id FK + projects 加 tenant_id FK + UserRole 加 IIT_OPERATOR | `20260228_add_iit_phase2_user_project_rbac` | 高 | nullable 列，不破坏现有数据 |
| DB-3 | IIT projects 加 is_demo 标记 | `20260228_add_iit_project_is_demo` | 低 | nullable boolean DEFAULT false，无破坏 |
| DB-4 | V3.1 QC 引擎架构升级：新建 qc_field_status 五级坐标表 + qc_logs/equery 加 instance_id + field_mapping 加 semantic_label/form_name/rule_category | `20260301_add_v31_qc_field_status_and_instance_columns` | 高 | 全部 ADD COLUMN / CREATE TABLE，向后兼容，零停机 |
| DB-5 | V3.1 Batch B：新建 qc_event_status 事件级聚合表 + record_summary 加 events/fields/d1-d7 聚合列 + top_issues | `20260301_add_v31_qc_event_status_and_record_summary_aggregation` | 高 | 全部 ADD COLUMN / CREATE TABLE，IF NOT EXISTS，零停机 |
| DB-6 | V3.1 Batch C：qc_project_stats 加 d1-d7 pass_rate + health_score + health_grade + dimension_detail | `20260301_add_v31_project_stats_health_score` | 中 | 全部 ADD COLUMN，DEFAULT 值，零停机 |
| — | *暂无* | | | |
### 后端变更 (Node.js)
| # | 变更内容 | 涉及文件 | 需要操作 | 备注 |
|---|---------|---------|---------|------|
| BE-1 | V3.1 RedcapAdapter: normalizeInstances() + exportRecordsNormalized() 五级坐标标准化 | `adapters/RedcapAdapter.ts` | 重新构建镜像 | 新增公共方法，不破坏现有调用 |
| BE-2 | V3.1 QC 分类体系升级：D1-D7 七维分类 + toDimensionCode() 转换函数 | `engines/HardRuleEngine.ts`, `engines/SoftRuleEngine.ts` | 重新构建镜像 | 扩展联合类型，旧值 → D-code 自动映射 |
| BE-3 | V3.1 QcExecutor 统一质控执行入口：executeSingle/executeBatch + qc_field_status upsert | `engines/QcExecutor.ts` (新文件) | 重新构建镜像 | 包装 SkillRunner，新增字段级状态写入 |
| BE-4 | V3.1 SyncManager: syncSemanticLabels() 语义标签自动同步 | `services/SyncManager.ts` | 重新构建镜像 | 从 REDCap 元数据填充 field_mapping.semantic_label |
| BE-5 | 种子规则 D-code 迁移（inclusion→D1, exclusion→D1, lab_values→D3） | `prisma/seed-iit-qc-rules.ts` | 重新执行种子脚本 | 下次重新初始化项目时生效 |
| BE-6 | V3.1 QcAggregator: aggregateDeferred() + aggregateForRecord() 异步防抖聚合 | `engines/QcAggregator.ts` (新文件) | 重新构建镜像 | 纯 SQL INSERT...ON CONFLICT 聚合，field→event→record 三级冒泡 |
| BE-7 | V3.1 QcExecutor 集成聚合 + State Transition Hook（FAIL→PASS 自动关闭 eQuery） | `engines/QcExecutor.ts` | 重新构建镜像 | executeSingle 推 pg-boss 防抖；executeBatch 直接聚合；PASS-flip 覆盖旧 FAIL |
| BE-8 | V3.1 pg-boss Worker: iit_qc_aggregate 受试者粒度防抖聚合 | `modules/iit-manager/index.ts` | 重新构建镜像 | singletonKey 防抖 10s，多 CRC 并发录入互不干扰 |
| BE-9 | V3.1 D2 CompletenessEngine: 绝对必填字段缺失率 + 双重过滤（字段+时序） | `engines/CompletenessEngine.ts` (新文件) | 重新构建镜像 | 排除 branching_logic/calc/descriptive 字段 + 排除未来访视 |
| BE-10 | V3.1 D6 ProtocolDeviationEngine: 访视超窗检测 | `engines/ProtocolDeviationEngine.ts` (新文件) | 重新构建镜像 | 基于项目 cachedRules.visitWindows 配置，支持早到/迟到检测 |
| BE-11 | V3.1 C4 HealthScoreEngine: D1-D7 加权综合健康度评分 | `engines/HealthScoreEngine.ts` (新文件) | 重新构建镜像 | 0-100 评分 + A-F 等级，持久化到 qc_project_stats |
| BE-12 | V3.1 Webhook Worker 接入 QcExecutor.executeSingle() | `modules/iit-manager/index.ts` | 重新构建镜像 | 替换 HardRuleEngine 旧路径 |
| BE-13 | V3.1 batchQualityCheck 接入 QcExecutor.executeBatch() | `admin/iitBatchController.ts` | 重新构建镜像 | 替换 SkillRunner 直接调用 |
| BE-14 | V3.1 QcExecutor 集成 D2/D6 维度引擎 | `engines/QcExecutor.ts` | 重新构建镜像 | 自动运行 CompletenessEngine + ProtocolDeviationEngine |
| BE-15 | V3.1 QcAggregator 集成 HealthScoreEngine | `engines/QcAggregator.ts` | 重新构建镜像 | aggregateDeferred 末尾自动刷新健康度 |
| BE-16 | V3.1 QcReportService 数据源升级 | `services/QcReportService.ts` | 重新构建镜像 | qc_field_status + event_overview + dimension_summary |
| BE-17 | V3.1 iitQcCockpitService 升级 | `admin/iitQcCockpitService.ts` | 重新构建镜像 | 热力图 record×event + healthScore/维度 |
| BE-18 | V3.1 新增 API: dimensions / completeness / field-status | `admin/iitQcCockpitRoutes.ts` + Controller | 重新构建镜像 | 3 个新 GET 端点 |
| BE-19 | V3.1 ToolsService check_quality → QcExecutor | `services/ToolsService.ts` | 重新构建镜像 | + read_report dimension_summary/event_overview |
| BE-20 | B4: 项目级 cronExpression 持久化 + 调度器重构 | `iitProjectService.ts`, `iit-manager/index.ts` | 重新构建镜像 | 旧全局 cron → dispatcher 每分钟轮询 + per-project 匹配 |
| BE-21 | B4: iit_scheduled_qc Worker V3.1 升级 | `iit-manager/index.ts` | 重新构建镜像 | 替换 HardRuleEngine → QcExecutor.executeBatch |
| BE-22 | P0-A: SkillRunner evidence 传播 category + subType | `engines/SkillRunner.ts` | 重新构建镜像 | D1 规则不再被错误存为 D3；需重跑全量 QC |
| BE-23 | P0-A: QcExecutor dimCode 回退逻辑增强 | `engines/QcExecutor.ts` | 重新构建镜像 | 优先取 evidence.category |
| BE-24 | P0-B: ProtocolDeviationEngine 输出结构化 JSON actual_value | `engines/ProtocolDeviationEngine.ts` | 重新构建镜像 | D6 API 零正则零脆断 |
| BE-25 | GCP D1 筛选入选表 API + D2 完整性总览/字段懒加载 API | `iitQcCockpitService/Controller/Routes` | 重新构建镜像 | 5 层数据 + L4/L5 按需加载 |
| BE-26 | GCP D3/D4 eQuery 全生命周期跟踪 API | `iitQcCockpitService/Controller/Routes` | 重新构建镜像 | 统计+分组+全量明细+时间线 |
| BE-27 | GCP D6 方案偏离报表增强 API | `iitQcCockpitService/Controller/Routes` | 重新构建镜像 | JSON.parse(actual_value) 结构化超窗数据 |
| — | *暂无* | | | |
### 前端变更
| # | 变更内容 | 涉及文件 | 需要操作 | 备注 |
|---|---------|---------|---------|------|
| FE-1 | V3.1 DashboardPage: 后端 healthScore + D1-D7 维度条 | `DashboardPage.tsx` | 重新构建前端 | 替换客户端健康度计算 |
| FE-2 | V3.1 热力图 record×event 矩阵 | `DashboardPage.tsx` | 重新构建前端 | cells 用 eventId |
| FE-3 | V3.1 ReportsPage: 维度分析 + 事件概览 tab | `ReportsPage.tsx` | 重新构建前端 | 2 新 Tab + 五级坐标列 |
| FE-4 | V3.1 API 客户端 + 类型定义 | `iitProjectApi.ts`, `qcCockpit.ts` | 重新构建前端 | 3 个新 API + V3.1 类型 |
| FE-5 | B4: 管理端项目配置页 cron UI 增强 | `IitProjectDetailPage.tsx`, `iitProject.ts` | 重新构建前端 | 更多预设选项 + 自定义 cron 输入框 |
| FE-6 | V3.1 管理端类型 V3.1 升级 | `qcCockpit.ts` | 重新构建前端 | HeatmapCell.eventId + DimensionBreakdown + DeviationItem + RecordDetail 五级坐标 |
| FE-7 | V3.1 管理端 API 客户端升级 | `iitProjectApi.ts` | 重新构建前端 | getQcRecordDetail(eventId) + getDeviations + getDimensions + getCompleteness + getFieldStatus |
| FE-8 | V3.1 QcDetailDrawer 事件级详情 + 维度标签 | `QcDetailDrawer.tsx` | 重新构建前端 | eventId 传参 + 语义标签 + D-code Tag |
| FE-9 | V3.1 RiskHeatmap 列头中文化 | `RiskHeatmap.tsx` | 重新构建前端 | 使用后端 columnLabels 映射 + Tooltip 显示原始 eventId |
| FE-10 | V3.1 IitQcCockpitPage 方案偏离弹窗升级 | `IitQcCockpitPage.tsx` | 重新构建前端 | 调用 D6 deviations API + 五级坐标定位表格 |
| FE-11 | V3.1 QcReportDrawer 维度分析 + 事件概览 Tab | `QcReportDrawer.tsx` | 重新构建前端 | 新增维度分析(D1-D7)和事件概览(按受试者缺失率)Tab |
| FE-12 | GCP 业务端 API 类型定义 | `iit/api/iitProjectApi.ts` | 重新构建前端 | 5 个报表接口 + 完整 TS 类型 |
| FE-13 | GCP ReportsPage 重构为 5 Tab | `iit/pages/ReportsPage.tsx` | 重新构建前端 | 执行摘要 + D1/D2/D3D4/D6 四张 GCP 报表 |
| FE-14 | GCP D1 EligibilityTable 组件 | `iit/components/reports/EligibilityTable.tsx` | 重新构建前端 | 纳入/排除逐条判定 + 受试者展开 |
| FE-15 | GCP D2 CompletenessTable 组件 | `iit/components/reports/CompletenessTable.tsx` | 重新构建前端 | L2/L3 统计 + L4/L5 懒加载展开 |
| FE-16 | GCP D3/D4 EqueryLogTable 组件 | `iit/components/reports/EqueryLogTable.tsx` | 重新构建前端 | eQuery 生命周期时间线 + 筛选 |
| FE-17 | GCP D6 DeviationLogTable 组件 | `iit/components/reports/DeviationLogTable.tsx` | 重新构建前端 | 结构化超窗数据 + 影响评估/CAPA 预留 |
| — | *暂无* | | | |
### Python 微服务变更
@@ -130,6 +83,16 @@
## 历史（已部署，仅供追溯）
### 0302 部署已清零项
| # | 变更内容 | 部署日期 | 结果 |
|---|---------|---------|------|
| DB | 6 个 Prisma 迁移（SSA 类型对齐 + IIT RBAC + is_demo + V3.1 QC 三批） | 2026-03-02 | ✅ |
| DB | 新建 qc_field_status、qc_event_status 2 张表（84 → 86） | 2026-03-02 | ✅ |
| BE | Node.js v2.3 → v2.4（IIT V3.1 QC引擎全面升级，27 项变更） | 2026-03-02 | ✅ |
| FE | 前端 v1.9 → v2.0（GCP 报表 + V3.1 前端，17 项变更） | 2026-03-02 | ✅ |
| ENV | frontend-nginx-service: BACKEND_SERVICE_HOST → 172.17.197.32 | 2026-03-02 | ✅ |
### 0227 部署已清零项
| # | 变更内容 | 部署日期 | 结果 |