# 五层数据架构方案评审反馈

> **评审对象**：架构团队提交的 4 份技术文档  
> 1. 核心数据架构与业务落地白皮书  
> 2. 核心转换机制白皮书：数据·规则·报告链路设计  
> 3. Skill 化配置架构技术设计  
> 4. CRA 质控报告自动化生成与 LLM 友好型设计规范  
>
> **评审日期**：2026-03-01  
> **评审结论**：方向认可，分层落地

---

## 一、总体评价

方案方向正确、视野开阔，5 层数据架构和 7 维度报告体系在理论上完整且符合 CDISC 标准。但它是一份**理想态蓝图**，与系统实际现状有较大距离，需要区分"方向性采纳"和"现阶段过度设计"。

---

## 二、值得借鉴的建议（采纳）

| # | 建议 | 采纳理由 | 系统现状差距 |
|---|------|---------|-------------|
| 1 | **InstanceID 实例层（第 4 层）** | AE、合并用药等重复表单必须精确到"第几条"才能定位问题，这是架构方案中**最有价值的贡献** | `IitQcLog`、`IitEquery` 均缺少 `instanceId` 字段 |
| 2 | **规则按 D1-D7 维度分类** | 多维报告的前提，也是上轮内部讨论的共识 | 当前 `QCRule.category` 仅 4 种值，未对齐 D1-D7 |
| 3 | **状态冒泡机制** | Field → Instance → Form → Event → Record 的级联逻辑清晰，便于前端热力图展示和报告聚合 | 仅有记录级 `IitRecordSummary`，无独立的事件级/变量级状态表 |
| 4 | **LLM 三不原则** | "不喂全量、不喂物理字段、不让 LLM 算数"与我们已有实践高度一致，值得正式化为设计规范 | 已有剪枝和预计算，但字段语义化尚未实现 |
| 5 | **AutoMapper 语义映射** | REDCap 字段名（如 `ie_01`、`ae_term`）对 LLM 不友好，反向语义化是必要的 | `IitFieldMapping` 表已有 alias→actual 映射，缺 actual→semantic 方向 |
| 6 | **优先级调整：D2 提至 P0** | IIT 中数据缺失率是最普遍的问题，D2 重要性应高于 D6/D7 | 我们原规划将 D2 放在阶段二，可考虑提前 |

---

## 三、暂不采纳的建议

| # | 建议 | 暂不采纳的理由 |
|---|------|---------------|
| 1 | **D8 核心数据 SDV（AI 多模态视觉比对）** | 这是一个独立产品功能（前端上传 + OCR + 比对），不是质控引擎的架构问题。技术难度极高，且 IIT 场景 SDV 比率不高，应单独立项 |
| 2 | **AutoMapper 全自动 LLM 映射** | 用 LLM 自动将物理变量名映射为医学语义标签，准确率不可控。建议改为**半自动**：系统基于 Data Dictionary 的 `field_label` 提供建议，DM 人工确认 |
| 3 | **5 张 GCP 报表同时规划** | 系统连 D2（缺失率）都还未实现，一次性规划 5 张完整 GCP 报表脱离现实。数据底座做好后，报告生成是顺水推舟的事 |
| 4 | **Branching Logic 解析器（阶段一）** | REDCap 分支逻辑语法是非标准格式，解析器开发成本高。阶段一先用简单统计替代，分支逻辑解析推迟到 D2 专项实现时 |

---

## 四、落地策略：分 3 个批次

**不建议一次性修复。** 原因：改动范围涉及 schema + 引擎 + 报告服务 + 前端，回归测试压力大；D5/D6/D7 的规则尚无临床专家输入，空设架构无意义。

### 批次 A：数据底座加固（1-2 周）

让现有功能的数据粒度正确。

- `IitQcLog` + `IitEquery` 增加 `instanceId` 字段
- `QCRule.category` 扩展为 D1-D7 维度枚举
- `IitFieldMapping` 增加 `semanticLabel`（反向语义化）
- 新建 `qc_field_status` 表（5 层坐标 + category + status）
- `HardRuleEngine` 执行结果写入 `qc_field_status`
- `QcReportService` 基于 `qc_field_status` 生成语义化报告

**验收标准**：一键全量质控后 `qc_field_status` 有正确的 5 层坐标数据；LLM 报告中字段名为中文语义。

### 批次 B：聚合层与冒泡机制（1-2 周）

完成五级聚合，支撑多维报告和前端热力图。

- 新建 `qc_event_status` 表（由 `field_status` 聚合）
- 改造 `IitRecordSummary`（由 `event_status` 聚合）
- 实现状态冒泡逻辑（field → instance → form → event → record）
- 多维报告框架（按 D1-D7 分章节）
- 前端：受试者×表单热力图原型

**验收标准**：字段 FAIL 后对应 event 和 record 自动变红；报告按维度分章节。

### 批次 C：新维度引擎（按需）

扩展质控覆盖面，**依赖临床专家确认规则可行性**。

- D2 CompletenessEngine（先简单统计，后续加分支逻辑解析）
- D6 方案偏离引擎（访视超窗检测）
- D5 SoftRule + RAG 联动（AE 漏报侦测）
- 项目健康度评分模型

**前提条件**：临床专家已确认各维度规则；有真实 IIT 项目数据验证；批次 A+B 已稳定运行。

---

## 五、架构团队二次评审补充建议（4 条，全部采纳）

| # | 建议 | 采纳结论 | 落地位置 |
|---|------|---------|---------|
| 1 | **跨表单"上下文断层"**：Webhook 只带单表单数据，跨表规则（D5 AE 漏报）无法执行 | 完全采纳。`QcExecutor.executeSingle()` 一律拉取该患者全量数据（Record-Level Context） | 开发计划 3.7 节 |
| 2 | **eQuery 自动闭环缺失**：Field 从 FAIL 变 PASS 时无人关闭关联 eQuery | 完全采纳。新增 State Transition Hook，用 `auto_closed` 状态区分人工关闭 | 开发计划 3.8 节 |
| 3 | **D2 缺失率"未来时空"陷阱**：新入组患者未来访视的必填字段被算作缺失 | 完全采纳。增加 Event-Aware 时序过滤，只统计已到达事件的必填字段 | 开发计划 6.3 节 |
| 4 | **聚合防抖锁粒度**：项目级聚合在多 CRC 并发录入时有行锁竞争 | 部分采纳。实时触发用受试者级防抖，项目级统计独立低频刷新 | 开发计划 3.3 节 |

---

## 六、一句话总结

> 5 层数据架构方向正确，**InstanceID** 和 **rule_category** 是我们最缺的两块拼图，必须尽快补上。表结构可以一次设计到位，但填充内容要一层一层来——先底座（批次 A），再聚合（批次 B），最后扩维度（批次 C）。