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

feat(iit): Complete V3.1 QC engine + GCP business reports + AI timeline + bug fixes

Browse Source 
V3.1 QC Engine:
- QcExecutor unified entry + D1-D7 dimension engines + three-level aggregation
- HealthScoreEngine + CompletenessEngine + ProtocolDeviationEngine + QcAggregator
- B4 flexible cron scheduling (project-level cronExpression + pg-boss dispatcher)
- Prisma migrations for qc_field_status, event_status, project_stats

GCP Business Reports (Phase A - 4 reports):
- D1 Eligibility: record_summary full list + qc_field_status D1 overlay
- D2 Completeness: data entry rate and missing rate aggregation
- D3/D4 Query Tracking: severity distribution from qc_field_status
- D6 Protocol Deviation: D6 dimension filtering
- 4 frontend table components + ReportsPage 5-tab restructure

AI Timeline Enhancement:
- SkillRunner outputs totalRules (33 actual rules vs 1 skill)
- iitQcCockpitController severity mapping fix (critical->red, warning->yellow)
- AiStreamPage expandable issue detail table with Chinese labels
- Event label localization (eventLabel from backend)

Business-side One-click Batch QC:
- DashboardPage batch QC button with SyncOutlined icon
- Auto-refresh QcReport cache after batch execution

Bug Fixes:
- dimension_code -> rule_category in 4 SQL queries
- D1 eligibility data source: record_summary full + qc_field_status overlay
- Timezone UTC -> Asia/Shanghai (QcReportService toBeijingTime helper)
- Pass rate calculation: passed/totalEvents instead of passed/totalRecords

Docs:
- Update IIT module status with GCP reports and bug fix milestones
- Update system status doc v6.6 with IIT progress

Tested: Backend compiles, frontend linter clean, batch QC verified
Made-with: Cursor
This commit is contained in:
HaHafeng
2026-03-01 22:49:49 +08:00
parent 0b29fe88b5
commit 2030ebe28f
50 changed files with 8687 additions and 1492 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -17,18 +17,64 @@
|---|---------|---------|--------|------|
| 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 微服务变更