Implement IIT quality workflow hardening across eQuery deduplication, guard metadata validation, timeline/readability improvements, and chat evidence fallbacks, then synchronize release and development documentation for deployment handoff. Includes migration/scripts for open eQuery dedupe guards, orchestration/status semantics, report/tool readability fixes, and updated module status plus deployment checklist. Made-with: Cursor
487 lines
21 KiB
Markdown
487 lines
21 KiB
Markdown
# IIT / CRA Agent 最小复现项目对账结果(Phase 1)
|
||
|
||
> 执行日期:2026-03-08
|
||
> 环境:本地开发环境(backend + postgres docker + local REDCap)
|
||
> 目标:验证“报告/大盘/流水/对话”异常是否来自 REDCap 联通、规则执行、聚合链路或展示口径。
|
||
|
||
---
|
||
|
||
## 1. 本次对账对象
|
||
|
||
- IIT 项目名称:`原发性痛经0302`
|
||
- IIT 项目 ID:`1d80f270-6a02-4b58-9db3-6af176e91f3c`
|
||
- 项目 REDCap PID:`18`
|
||
- 项目 REDCap URL:`http://localhost:8080`
|
||
- 数据库:`ai_clinical_research`(`ai-clinical-postgres`)
|
||
|
||
项目映射校验结果:
|
||
|
||
- `iit_schema.projects` 中存在且唯一:
|
||
- `id=1d80f270-6a02-4b58-9db3-6af176e91f3c`
|
||
- `name=原发性痛经0302`
|
||
- `redcap_project_id=18`
|
||
- `status=active`
|
||
|
||
---
|
||
|
||
## 2. 第一轮 SQL 证据(核心)
|
||
|
||
### 2.1 聚合结果与原始质控事实明显不一致
|
||
|
||
- `iit_schema.qc_project_stats`(该项目):
|
||
- `total_records=0`
|
||
- `passed_records=0`
|
||
- `failed_records=0`
|
||
- `warning_records=0`
|
||
- `health_score=82.3`
|
||
- `d1_pass_rate=41.2`, `d2=100`, `d3=100`, `d5=100`, `d6=69.6`, `d7=100`
|
||
- `iit_schema.record_summary`(该项目):
|
||
- `COUNT(DISTINCT record_id)=0`
|
||
- `iit_schema.qc_field_status`(该项目):
|
||
- `COUNT(*)=713`
|
||
- `COUNT(DISTINCT record_id)=12`
|
||
- 存在 FAIL/WARNING/PASS 混合状态,且 D1/D2/D3/D5/D6 均有数据
|
||
- `iit_schema.qc_event_status`(该项目):
|
||
- `COUNT(*)=25`
|
||
- `iit_schema.equery`(该项目):
|
||
- `pending=262`
|
||
|
||
判定:`qc_field_status/qc_event_status/equery` 已有大量有效数据,但 `record_summary` 为空,导致项目级统计口径断裂。
|
||
|
||
### 2.2 历史项目残留与项目隔离异常迹象
|
||
|
||
- `record_summary` 总表仅有 14 行,且全部属于旧项目 ID:`test0102-pd-study`
|
||
- 当前项目(UUID)在 `record_summary` 无行
|
||
|
||
判定:当前项目未建立或未插入 `record_summary` 基础行,后续“仅 UPDATE 的聚合语句”无法生效。
|
||
|
||
---
|
||
|
||
## 3. 第一轮 API 证据(核心)
|
||
|
||
使用管理员账号登录后,调用 `/api/v1/admin/iit-projects/:projectId/...`。
|
||
|
||
### 3.1 Dashboard / Report / Trend 三口径冲突
|
||
|
||
- `qc-cockpit` 返回:
|
||
- `qualityScore=82`
|
||
- `totalRecords=0`
|
||
- `passRate=100`
|
||
- `criticalCount=137`
|
||
- `queryCount=262`
|
||
- `qc-cockpit/report` 返回:
|
||
- `totalRecords=0`
|
||
- `criticalIssues=156`
|
||
- `warningIssues=284`
|
||
- `passRate=0`
|
||
- `qc-cockpit/trend` 返回:
|
||
- 最新点:`total=148`, `passed=48`, `passRate=32`
|
||
|
||
判定:同一项目同一时间,`passRate` 至少出现 `100 / 0 / 32` 三个版本,属于 P0 级口径漂移。
|
||
|
||
### 3.2 时间线日期筛选无效(复现)
|
||
|
||
调用 `qc-cockpit/timeline`:
|
||
|
||
- 不带日期:`total=12`
|
||
- `startDate=2026-03-01&endDate=2026-03-02`:`total=12`
|
||
- `startDate=2026-03-08&endDate=2026-03-08`:`total=12`
|
||
|
||
判定:前端传 `startDate/endDate` 未在后端生效,日期筛选失效可稳定复现。
|
||
|
||
---
|
||
|
||
## 4. 对话层冒烟(第一轮)
|
||
|
||
调用 `/api/v1/iit/chat` 的典型问答可得到答复,但存在“解释与口径不稳定”的风险:
|
||
|
||
- “签署知情人数”问题:答复给出“表单通过数 10/12”,但承认无法直接给出人数。
|
||
- “最新质控报告”问题:引用了健康分、严重问题、警告问题、待处理 eQuery,整体和 `qc_report` 可对齐。
|
||
- “患者访视次数”问题:返回“第2次访视”,但需和 REDCap 事件表进一步逐条对账(Phase 2 再做字段级真值核验)。
|
||
|
||
判定:对话层主要风险当前不是“工具不可用”,而是上游口径漂移会向下传导。
|
||
|
||
---
|
||
|
||
## 5. 根因初判(带代码入口)
|
||
|
||
### 根因 A(P0):`record_summary` 聚合是“仅 UPDATE”,无 UPSERT
|
||
|
||
- 代码入口:`backend/src/modules/iit-manager/engines/QcAggregator.ts`
|
||
- `aggregateRecordSummary()` 当前逻辑:
|
||
- 只执行 `UPDATE iit_schema.record_summary rs ... FROM agg`
|
||
- 依赖 `rs` 预先存在
|
||
- 当项目没有预写 `record_summary` 行时:
|
||
- 聚合更新行数为 0
|
||
- `HealthScoreEngine.queryRecordStats()` 基于 `record_summary` 得到 `totalRecords=0`
|
||
- Dashboard/Report 中基于该数据的统计出现“0记录 + 非0问题”的冲突
|
||
|
||
### 根因 B(P0):时间线接口参数约定不一致
|
||
|
||
- 代码入口:`backend/src/modules/admin/iit-projects/iitQcCockpitController.ts`
|
||
- `getTimeline` 仅读取 `query.date`,未处理 `startDate/endDate`
|
||
- 前端使用区间筛选时,后端实际不生效
|
||
|
||
### 根因 C(P1):同名指标多来源并行,无统一冻结口径
|
||
|
||
- `passRate` 在 cockpit/report/trend 来源不一致
|
||
- 导致用户看到“同一页不同值”的信任问题
|
||
|
||
---
|
||
|
||
## 6. 与三大类问题的对应关系(第一轮)
|
||
|
||
- 第一大类(报告/关键事件):
|
||
- 已确认强相关于根因 A + 根因 C
|
||
- 第二大类(AI 实时工作流水):
|
||
- 已确认日期筛选问题由根因 B 直接导致
|
||
- 总问题数差异与根因 C 强相关
|
||
- 第三大类(AI 对话助手):
|
||
- 目前更像“上游口径漂移传导”而非对话工具不可用
|
||
- 仍需在 Phase 2 做患者级真值核验
|
||
|
||
---
|
||
|
||
## 7. 下一步(建议立即执行)
|
||
|
||
1. P0 修复 `QcAggregator.aggregateRecordSummary`:改为 UPSERT(或先补齐 record_summary 基础行再 UPDATE)。
|
||
2. P0 修复 `getTimeline`:支持 `startDate/endDate`,并与 `date` 兼容。
|
||
3. P0 统一 `passRate` 口径(按 Phase0 SSOT),至少先让 cockpit/report/trend 展示同一主口径。
|
||
4. 修复后回归本项目 3 个关键断言:
|
||
- `record_summary` 记录数应为 `12`
|
||
- Dashboard/Report/Trend 的主通过率在同一时间窗内一致
|
||
- 时间线区间筛选对 `2026-03-08` 返回 `0`(当前数据下)
|
||
|
||
---
|
||
|
||
## 8. 第二轮回归看板(18 问题闭环状态)
|
||
|
||
> 执行日期:2026-03-08(第二轮)
|
||
> 结论口径:
|
||
> - `已闭环`:问题已修复并复测通过
|
||
> - `部分闭环`:核心问题缓解,但仍有体验/口径尾项
|
||
> - `未闭环`:仍存在明确缺陷或未完成验证
|
||
|
||
### 8.1 第一大类:报告与关键事件(11 项)
|
||
|
||
| # | 问题 | 当前状态 | 证据 / 说明 |
|
||
|---|---|---|---|
|
||
| 1 | D1/D2/D3D4/D6 与维度评分不一致 | **部分闭环** | 主通过率口径已统一;但 D2 的 `eventsChecked=1` 仍需继续核验业务定义。 |
|
||
| 2 | 质控 0 个受试者 | **已闭环** | `record_summary` 已恢复 `12` 条,`qc_project_stats.total_records=12`。 |
|
||
| 3 | 健康分与问题规模冲突(如健康分高但问题多) | **部分闭环** | 评分与问题计数可同时存在(不同公式);需补“评分解释文案”避免误读。 |
|
||
| 4 | 上方通过率 100 / 下方趋势 33 | **已闭环** | 当前 cockpit/report/trend 均为 `passRate=0`(同一快照)。 |
|
||
| 5 | 质控完成无热力图 | **已闭环** | cockpit 返回 heatmap `rows/columns` 非空。 |
|
||
| 6 | 执行摘要无信息 | **已闭环** | report summary 可稳定返回 `totalRecords/criticalIssues/warningIssues/pendingQueries`。 |
|
||
| 7 | 报告分数 vs 大盘分数冲突 | **部分闭环** | 主指标已一致;健康分展示仍建议增加“更新时间+公式说明”。 |
|
||
| 8 | D1 无数据 | **已闭环** | D1 报表已恢复:`eligible=0, ineligible=11, incomplete=1`。 |
|
||
| 9 | D2 事件数=1、明细异常 | **部分闭环** | 已修复 `eventsChecked=5`(按活跃事件);同时新增 `d2EventsChecked=1` 标识 D2 覆盖事件数,避免误读。 |
|
||
| 10 | 已回复仍显示 0 | **已闭环** | 已执行 `pending -> responded -> closed(ai_review)` 实流回归,`equeries/stats` 与 D3D4 报表最终一致。 |
|
||
| 11 | 无“重开质疑”操作 | **未闭环** | 前端仍缺 reopen 操作入口(后端状态机支持)。 |
|
||
|
||
### 8.2 第二大类:AI 实时工作流水(3 项)
|
||
|
||
| # | 问题 | 当前状态 | 证据 / 说明 |
|
||
|---|---|---|---|
|
||
| 12 | 流水问题总数 vs 待处理总数不一致 | **部分闭环** | 已在口径上解释为“字段问题数 vs eQuery 数”;需在 UI 文案继续强化区分。 |
|
||
| 13 | 事件编码生成逻辑不明 | **部分闭环** | 已补齐后端 `event_id -> event_label` 统一映射(报表/对话可显示“筛选期”等);仍保留 event_id 作为证据辅助。 |
|
||
| 14 | 日期筛选按钮无效 | **已闭环** | timeline 支持 `startDate/endDate`,`2026-03-01~03-02` 返回 `0`。 |
|
||
|
||
### 8.3 第三大类:AI 对话助手(5 项)
|
||
|
||
| # | 问题 | 当前状态 | 证据 / 说明 |
|
||
|---|---|---|---|
|
||
| 15 | 已签署知情显示 0 | **已闭环** | 回归问答返回 `11/12`(签署率 91.7%)。 |
|
||
| 16 | 3号患者被误判为无问题 | **已闭环** | 回归问答已返回“不符合”并列出 rule 证据。 |
|
||
| 17 | 总体通过率答复异常 | **已闭环** | 回归问答返回 `0%`,并给出公式 `passedRecords/totalRecords`。 |
|
||
| 18 | 患者2信息不全 / 患者4访视描述偏差 | **已闭环** | 患者2信息完整度提升;患者4访视描述已优先输出业务事件名(保留 event_id 仅作证据)。 |
|
||
|
||
---
|
||
|
||
## 9. 严重未闭环问题(当前 P0/P1)
|
||
|
||
### P0(必须优先清零)
|
||
|
||
1. ~~**D2 统计口径残留问题**:`eventsChecked=1` 与多事件现实不一致。~~(已完成:`eventsChecked` 修复 + `d2EventsChecked` 解释字段)
|
||
2. ~~**“已回复仍为0”缺少场景化回归**:需要构造 responded/reviewing/closed 数据流转验证。~~(已完成:状态流转回归通过)
|
||
|
||
### P1(应在下一轮完成)
|
||
|
||
1. ~~**事件标签可读性**:technical event_id 需稳定映射到 eventLabel(报表 + 对话统一)。~~(已完成第一阶段:后端统一映射,前端显示可读事件名)
|
||
2. **EQuery 重开操作入口**:前端补 `reopen` 按钮与状态回流。
|
||
3. **评分解释文案**:健康分与问题数量并存时给出公式与更新时间提示。
|
||
|
||
---
|
||
|
||
## 10. 下一步执行计划(建议)
|
||
|
||
1. **P0-A:D2 口径修复**
|
||
- 明确 activeEvents 定义(按患者真实到访事件)
|
||
- 修正 `getCompletenessReport()` 的 `eventsChecked` 计算
|
||
- 回归断言:`eventsChecked` 与 `qc_event_status` 的 D2 事件集合一致
|
||
|
||
2. **P0-B:eQuery 状态流转回归**
|
||
- 构造一条 `pending -> responded -> reviewing/closed` 流程
|
||
- 验证:eQuery 列表、stats、D3D4 报表、对话回答四处一致
|
||
|
||
3. **P1:事件标签统一**
|
||
- 补全 `event_id -> event_label` 映射策略(优先 metadata,其次兜底格式化)
|
||
- 前端与 AI 对话统一使用 `eventLabel`,避免技术 ID 直出
|
||
|
||
---
|
||
|
||
## 11. 本轮执行证据(新增)
|
||
|
||
### 11.1 D2 口径修复结果
|
||
|
||
- 接口:`GET /api/v1/admin/iit-projects/:projectId/qc-cockpit/report/completeness`
|
||
- 修复后结果:
|
||
- `eventsChecked=5`(项目活跃事件数)
|
||
- `d2EventsChecked=1`(D2 当前覆盖事件数)
|
||
- 受试者样例 `recordId=1`:`activeEvents=5`,`d2CoveredEvents=1`
|
||
|
||
### 11.2 eQuery 状态流转回归结果
|
||
|
||
- 操作:选取一条 pending eQuery,调用 `POST /equeries/:id/respond`
|
||
- 实际状态流:
|
||
- `pending -> responded -> closed (ai_review)`(异步作业触发)
|
||
- 最终一致性(等待异步稳定后):
|
||
- `GET /equeries/stats`: `pending=261, closed=1, responded=0`
|
||
- `GET /qc-cockpit/report/equery-log`: 同步为 `pending=261, closed=1, responded=0`
|
||
|
||
|
||
---
|
||
|
||
## 12. eQuery 专项 P0 修复(2026-03-08 夜间增量)
|
||
|
||
### 12.1 已落地代码改动
|
||
|
||
1. **eQuery 生成去重策略升级(后端)**
|
||
- 文件:`backend/src/modules/iit-manager/services/DailyQcOrchestrator.ts`
|
||
- 从原来的 `recordId + fieldName` 去重,升级为 `recordId + eventId + ruleName` 去重。
|
||
- 目的:减少“同一业务问题因不同字段重复建单”(对应问题 9)。
|
||
|
||
2. **高噪音规则抑制(后端)**
|
||
- 文件:`backend/src/modules/iit-manager/services/DailyQcOrchestrator.ts`
|
||
- 新增 `shouldSuppressIssue()`,当前先抑制三类已确认噪音:
|
||
- `不良事件记录与知情同意状态一致性检查`(缺上下文时高频误报)
|
||
- `所有纳入标准完整性检查` 且实际值为全 `1,1,...` 的错误告警
|
||
- `访视日期早于知情同意书签署日期` 但两日期相同的误报文本
|
||
|
||
3. **eQuery 文案可读性增强(后端)**
|
||
- 文件:`backend/src/modules/iit-manager/services/DailyQcOrchestrator.ts`
|
||
- 新增 `normalizeQueryText()`:
|
||
- 清理 `(标准: [object Object])`
|
||
- 去掉 markdown `**` 噪音
|
||
- 对“入组状态与排除标准冲突检查”改写为业务可读提示语
|
||
|
||
4. **eQuery 上下文字段补齐(后端)**
|
||
- 文件:`backend/src/modules/iit-manager/services/DailyQcOrchestrator.ts`
|
||
- 创建 eQuery 时补写 `eventId/formName`,并在 `expectedAction` 中带出事件上下文。
|
||
- 目的:缓解“详情中表单/访视点显示不全(-)”。
|
||
|
||
5. **规则消息层通用序列化修复(后端)**
|
||
- 文件:
|
||
- `backend/src/modules/iit-manager/engines/HardRuleEngine.ts`
|
||
- `backend/src/modules/iit-manager/engines/SkillRunner.ts`
|
||
- 新增逻辑字面量与实际值格式化,避免 `expectedValue`/`actualValue` 落成 `[object Object]` 或不可读数组。
|
||
|
||
6. **eQuery 列表可用性增强(前端)**
|
||
- 文件:`frontend-v2/src/modules/iit/pages/EQueryPage.tsx`
|
||
- 新增:
|
||
- 质疑序号列
|
||
- 访视点列(eventId)
|
||
- 按严重程度过滤
|
||
- 按受试者号过滤
|
||
- 前端默认排序:按受试者号升序、同受试者按创建时间降序
|
||
|
||
### 12.2 状态评估(对应 14 条中的关键项)
|
||
|
||
- **部分闭环(需复测)**
|
||
- #4 排序混乱 / 建议增加序号:已实现前端排序+序号
|
||
- #9 同一目的重复记录:已增强去重键
|
||
- #10/#14 事件/表单显示不足:新单已补上下文,历史单仍需数据回填
|
||
- #12 告警文案与全 1 误报:已在派单前抑制
|
||
|
||
- **仍需继续(下一轮 P0)**
|
||
- #3/#7/#11 的“规则本体逻辑”仍建议在规则配置层做根因修正(当前先做了派单层防噪)
|
||
- #5 纳入标准检查覆盖不全:仍需补齐规则集合与事件适用范围
|
||
- #13 缺少访视定位的业务解释:需在报表与详情页增加 eventLabel 映射显示
|
||
|
||
### 12.3 第二批 P0(规则执行层护栏)已落地
|
||
|
||
1. **规则执行层新增业务护栏(HardRuleEngine / SkillRunner 双端一致)**
|
||
- 文件:
|
||
- `backend/src/modules/iit-manager/engines/HardRuleEngine.ts`
|
||
- `backend/src/modules/iit-manager/engines/SkillRunner.ts`
|
||
- 新增 `forcePassByBusinessGuard()`,在规则命中前做语义纠偏:
|
||
- `访视日期早于知情同意书签署日期`:当访视日期 >= 签署日期(含同日)直接判通过
|
||
- `SF-MPQ和CMSS评估日期与访视日期不一致`:存在缺失值时不判“不一致”
|
||
- `所有纳入标准完整性检查`:实际值全 1 时直接判通过
|
||
- `入组状态与排除标准冲突检查`:实际值全 0 时直接判通过
|
||
|
||
2. **D2 缺失告警事件名可读化**
|
||
- 文件:`backend/src/modules/iit-manager/engines/CompletenessEngine.ts`
|
||
- 告警文案从技术事件码切换为 `eventLabel`(如“筛选期”),减少 `65a64dbbd9_arm_1` 直接暴露。
|
||
|
||
> 注:以上为执行层兜底,能立即压误报;下一步仍建议在规则配置(skill.config.rules)层做同名规则逻辑重构,避免长期依赖护栏。
|
||
|
||
### 12.4 同步完成 P1:eQuery 重开入口
|
||
|
||
- 后端新增 `POST /api/v1/admin/iit-projects/:projectId/equeries/:equeryId/reopen`
|
||
- 文件:
|
||
- `backend/src/modules/admin/iit-projects/iitEqueryService.ts`
|
||
- `backend/src/modules/admin/iit-projects/iitEqueryController.ts`
|
||
- `backend/src/modules/admin/iit-projects/iitEqueryRoutes.ts`
|
||
- 状态流:`closed -> reopened`
|
||
|
||
- 前端已接入“重开”按钮
|
||
- 文件:
|
||
- `frontend-v2/src/modules/iit/api/iitProjectApi.ts`
|
||
- `frontend-v2/src/modules/iit/pages/EQueryPage.tsx`
|
||
- 仅在 `closed` 状态显示“重开”操作,执行后刷新列表。
|
||
|
||
---
|
||
|
||
## 13. 执行验证与卡点结论(2026-03-08 晚)
|
||
|
||
### 13.1 复跑验证结论
|
||
|
||
- 脚本:`backend/scripts/run_iit_qc_once.ts`
|
||
- 项目:`1d80f270-6a02-4b58-9db3-6af176e91f3c`(原发性痛经0302)
|
||
- 结果(成功):
|
||
- `batch.totalRecords=12`
|
||
- `batch.totalEvents=37`
|
||
- `batch.fieldStatusWrites=1015`
|
||
- `orchestrate.pushSent=true`
|
||
- `orchestrate.equeriesCreated=0`
|
||
|
||
### 13.2 “卡在哪里”的根因
|
||
|
||
- 本次并非主流程卡死,`QcExecutor -> DailyQcOrchestrator` 已完整跑通并返回结果。
|
||
- 之前观察到的告警根因是:
|
||
- 审计日志 SQL 使用了旧列 `action`
|
||
- 当前表 `iit_schema.audit_logs` 实际列为 `action_type`
|
||
- 已修复后复跑,相关 `audit_logs.action` 报错未再出现。
|
||
|
||
### 13.3 历史 eQuery 上下文回填结果
|
||
|
||
- 脚本:`backend/scripts/backfill_equery_context.ts`
|
||
- 回填结果:
|
||
- `missingBefore=262`
|
||
- `updatedRows=203`
|
||
- `missingAfter=59`
|
||
|
||
### 13.4 剩余 59 条未回填原因
|
||
|
||
- 脚本:`backend/scripts/analyze_missing_equery_context.ts`
|
||
- 统计:`B_RULE_MATCH_FIELD_MISMATCH = 59`(100%)
|
||
- 含义:
|
||
- 能匹配到同受试者 + 同规则名
|
||
- 但匹配不到同字段名(历史 eQuery 以 `exclusion_criteria2/3/4/5` 多字段拆条,现有 `qc_field_status` 粒度/字段记录不一致)
|
||
- 代表样例:`category=入组状态与排除标准冲突检查` 且 `event_id/form_name` 为空。
|
||
|
||
### 13.5 容错回填(二阶段)执行结果
|
||
|
||
- 已升级脚本:`backend/scripts/backfill_equery_context.ts`
|
||
- Phase 1:严格匹配(`record + rule + field`)
|
||
- Phase 2:容错匹配(`record + rule`,取最近 QC 事件/表单)
|
||
- 本次执行结果:
|
||
- `missingBefore=59`
|
||
- `strictUpdatedRows=0`
|
||
- `relaxedUpdatedRows=59`
|
||
- `missingAfter=0`
|
||
- 复核脚本:`backend/scripts/analyze_missing_equery_context.ts`
|
||
- `reasonStats=[]`
|
||
- `sample=[]`
|
||
- 结论:历史 eQuery 的 `event_id/form_name` 缺失已清零。
|
||
|
||
---
|
||
|
||
## 14. 新增端到端脚本(四流程一体)
|
||
|
||
- 脚本:`backend/scripts/e2e_iit_full_flow.ts`
|
||
- 运行方式:
|
||
- `npx tsx scripts/e2e_iit_full_flow.ts 1d80f270-6a02-4b58-9db3-6af176e91f3c`
|
||
- 可选:`--with-chat`(增加 LLM 问答链路)
|
||
|
||
### 14.1 覆盖的 4 个流程
|
||
|
||
1. REDCap 结构与真实数据拉取(metadata/events/form-event/records-by-event)
|
||
2. 规则配置加载与覆盖校验(`qc_process` 活跃规则)
|
||
3. 执行质控与报告编排(`QcExecutor` + `DailyQcOrchestrator`)
|
||
4. 多消费端一致性校验(Cockpit / Report / Tools 的通过率一致)
|
||
|
||
### 14.2 本次执行结果(通过)
|
||
|
||
- Stage1_REDCap:通过
|
||
- `metadata=74`, `events=5`, `formEventMapping=19`, `recordEventRows=37`, `uniqueRecords=12`
|
||
- Stage2_Rules:通过
|
||
- `ruleCount=79`, `multiFieldRules=29`, `categories={D1,D3,D5,D6}`
|
||
- Stage3_Execution:通过
|
||
- `totalRecords=12`, `totalEvents=37`, `fieldStatusWrites=1015`
|
||
- DB:`qc_field_status=713`, `qc_event_status=25`, `record_summary=12`
|
||
- Stage4_Consumption:通过
|
||
- `reportPassRate=0`, `cockpitPassRate=0`, `toolPassRate=0`(一致)
|
||
|
||
---
|
||
|
||
## 15. 元数据驱动护栏落地(去硬编码)
|
||
|
||
### 15.1 执行内核收敛
|
||
|
||
- 已完成:`SkillRunner` 的 HARD_RULE 执行改为单路径复用 `HardRuleEngine.executeWithRules()`。
|
||
- 价值:删除重复实现,避免“同一规则两套行为”。
|
||
|
||
### 15.2 guardType 元数据写回(项目级)
|
||
|
||
- 脚本:`backend/scripts/suggest_guard_types_for_project.ts`
|
||
- 运行:`npx tsx scripts/suggest_guard_types_for_project.ts 1d80f270-6a02-4b58-9db3-6af176e91f3c --apply`
|
||
- 结果:`updated=5`
|
||
- `date_not_before_or_equal` ×1
|
||
- `pass_if_exclusion_all_zero` ×1
|
||
- `pass_if_all_ones` ×1
|
||
- `skip_if_any_missing` ×2
|
||
|
||
### 15.3 回归脚本拆分(职责清晰)
|
||
|
||
- 引擎机制 smoke:`backend/scripts/regression_hardrule_guards.ts`(可写死样例)
|
||
- 项目动态回归:`backend/scripts/regression_hardrule_guards_by_project.ts`(从 `qc_process` 读取规则)
|
||
- 项目动态回归结果:`skipped=[]`,核心 guard 断言全部通过。
|
||
|
||
### 15.4 复跑端到端验证
|
||
|
||
- 脚本:`backend/scripts/e2e_iit_full_flow.ts`
|
||
- 结果:Stage1~Stage4 全部通过(口径一致性维持)。
|
||
- 备注:本次编排阶段 `pushSent=false`(非主流程阻断项),不影响质控执行与报告一致性断言。
|
||
|
||
---
|
||
|
||
## 16. 守护门禁与兼容开关(新增)
|
||
|
||
### 16.1 guardType 门禁脚本
|
||
|
||
- 新增:`backend/scripts/validate_guard_types_for_project.ts`
|
||
- 用法:
|
||
- 检查:`npx tsx scripts/validate_guard_types_for_project.ts <projectId>`
|
||
- 严格失败:`npx tsx scripts/validate_guard_types_for_project.ts <projectId> --strict`
|
||
- 本项目执行结果(strict):`missingCount=0`, `mismatchCount=0`
|
||
|
||
### 16.2 E2E 增加严格 guard 覆盖断言
|
||
|
||
- 脚本:`backend/scripts/e2e_iit_full_flow.ts`
|
||
- 新增参数:
|
||
- `--strict-guards`
|
||
- 或环境变量 `E2E_REQUIRE_GUARD_TYPES=1`
|
||
- 严格模式下,Stage2 会校验 guardType 候选规则的覆盖率(未覆盖即 fail)。
|
||
|
||
### 16.3 兼容兜底可控下线
|
||
|
||
- 文件:`backend/src/modules/iit-manager/engines/HardRuleEngine.ts`
|
||
- 新增开关:`IIT_GUARD_LEGACY_NAME_FALLBACK`
|
||
- 默认开启(兼容历史规则名)
|
||
- 设为 `0` 可关闭规则名兜底,仅按 `metadata.guardType` 生效
|
||
- 目的:支持“先迁移配置,再逐步下线兼容逻辑”的平滑策略。
|
||
|
||
|
||
|