HaHafeng
0b29fe88b5
QC System Deep Fix: - HardRuleEngine: add null tolerance + field availability pre-check (skipped status) - SkillRunner: baseline data merge for follow-up events + field availability check - QcReportService: record-level pass rate calculation + accurate LLM XML report - iitBatchController: legacy log cleanup (eventId=null) + upsert RecordSummary - seed-iit-qc-rules: null/empty string tolerance + applicableEvents config V3.1 Architecture Design (docs only, no code changes): - QC engine V3.1 plan: 5-level data structure (CDISC ODM) + D1-D7 dimensions - Three-batch implementation strategy (A: foundation, B: bubbling, C: new engines) - Architecture team review: 4 whitepapers reviewed + feedback doc + 4 critical suggestions - CRA Agent strategy roadmap + CRA 4-tool explanation doc for clinical experts Project Member Management: - Cross-tenant member search and assignment (remove tenant restriction) - IIT project detail page enhancement with tabbed layout (KB + members) - IitProjectContext for business-side project selection - System-KB route access control adjustment for project operators Frontend: - AdminLayout sidebar menu restructure - IitLayout with project context provider - IitMemberManagePage new component - Business-side pages adapt to project context Prisma: - 2 new migrations (user-project RBAC + is_demo flag) - Schema updates for project member management Made-with: Cursor
100 lines
6.0 KiB
Markdown
100 lines
6.0 KiB
Markdown
# 五层数据架构方案评审反馈
|
||
|
||
> **评审对象**：架构团队提交的 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）。
|