feat(iit): QC deep fix + V3.1 architecture plan + project member management
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
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
# **核心转换机制白皮书：从五层数据底座到多维质控报告的生成逻辑**
|
||||
|
||||
**文档定位**：系统设计核心枢纽，连接底层数据库、规则引擎与前台业务报表。
|
||||
|
||||
**阅读对象**：后端架构师、规则配置工程师（DM）、产品经理
|
||||
|
||||
## **核心理念：质控的本质是“坐标映射与计算”**
|
||||
|
||||
在我们的系统中，没有任何一份报告是凭空“写”出来的。所有的报告，其本质都是：
|
||||
|
||||
1. 取出特定 **五层坐标 (Record \-\> Event \-\> Form \-\> Instance \-\> Field)** 上的数据。
|
||||
2. 放入特定的 **规则引擎 (D1\~D7)** 进行计算。
|
||||
3. 将计算结果（PASS/FAIL/数值）**组装并投影**到 5 张标准化 GCP 报告的单元格中。
|
||||
|
||||
## **逐表拆解：5大核心报告的生成机制与数据链路**
|
||||
|
||||
### **报告一：筛选与入选登记表 (对应 D1 规则)**
|
||||
|
||||
**业务目的**：证明患者入组是完全合规的，没有放错人进来。
|
||||
|
||||
| 报告显示的列 (微小内容) | 依赖的 5 层数据坐标 (查什么) | 调用的质控规则与逻辑 (算什么) | 执行引擎 |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **筛选日期** | Event=筛选期 \-\> Form=知情同意表 \-\> Instance=1 \-\> Field=签署日期 | 提取知情书的签署日期。 | 基础查询 |
|
||||
| **纳入/排除是否符合** | Event=基线 \-\> Form=入排标准表 \-\> Instance=1 \-\> Field=所有入排项 | **\[D1 逻辑\]** 验证纳入标准是否全为“是”，排除标准是否全为“否”。 | HardRuleEngine |
|
||||
| **时序合规校验** | Form=知情表 vs Form=基线表 | **\[D1 逻辑\]** 校验 知情签署日期 \<= 筛选检查发生日期。违规即阻断。 | HardRuleEngine |
|
||||
| **失败原因** | qc\_field\_status \= 'FAIL' 的具体 Field | 提取亮红灯的 FieldID 对应的字典标签（如：排除标准3不符）。 | AutoMapper |
|
||||
|
||||
### **报告二：数据录入率 & 缺失率记录表 (对应 D2 规则)**
|
||||
|
||||
**业务目的**：证明数据的完整性。最考验系统工程能力的一张表。
|
||||
|
||||
| 报告显示的列 | 依赖的 5 层数据坐标 (查什么) | 调用的质控规则与逻辑 (算什么) | 执行引擎 |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **应录入总字段数** | REDCap 字典 & Branching Logic | **\[D2 逻辑 \- 极度核心\]** 代入患者其他字段值，解析分支逻辑。例如：如果 性别=男，则该患者所有 妊娠检查 相关的 Instance 应录入数 \= 0。 | CompletenessEngine |
|
||||
| **实际已录入字段数** | 遍历当前 Form 下所有 Instance 的所有 Field | 计算非空 (value \!= null) 的字段总数。 | 基础查询 |
|
||||
| **数据缺失率 (%)** | 上述两个计算结果 | 公式：(应录入 \- 实录入) / 应录入 \* 100%。 | CPU 计算 |
|
||||
|
||||
### **报告三：数据质疑管理跟踪表 (eQuery Log) (对应 D3/D4 规则)**
|
||||
|
||||
**业务目的**：记录逻辑矛盾和笔误的闭环过程。
|
||||
|
||||
| 报告显示的列 | 依赖的 5 层数据坐标 (查什么) | 调用的质控规则与逻辑 (算什么) | 执行引擎 |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **质疑编号 & 定位** | 取 status \= 'FAIL' 的 5 层全路径 | 拼接坐标：\[Record\]-\[Event\]-\[Form\]-\[Instance\]-\[Field\]。 | 基础查询 |
|
||||
| **问题描述 (AI 生成)** | 提取异常 Field 的 actual\_value，预期规则 | **\[D3 逻辑\]** 极值/关联校验。 **LLM组装**：将硬规则警报抛给 LLM，翻译成严谨的人类句子。 | HardRule \+ SoftRule |
|
||||
| **当前状态 & 解决时间** | pending\_actions 表流转状态 | **\[D4 逻辑\]** 监听该 Instance 的数据变更。复核通过，状态从 OPEN 变 CLOSED。 | 状态机 |
|
||||
|
||||
### **报告四：AE 不良事件记录表 (对应 D5 规则 \- 核心亮点)**
|
||||
|
||||
**业务目的**：展现 AI 作为“数字 CRA”挖掘隐患的强大能力。
|
||||
|
||||
| 报告显示的列 | 依赖的 5 层数据坐标 (查什么) | 调用的质控规则与逻辑 (算什么) | 执行引擎 |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **显性 AE 记录** | Form=不良事件表 的所有 Instance | 遍历每个独立 Instance（第 1 次 AE, 第 2 次 AE），提取名称、开始/结束日期。 | 基础查询 |
|
||||
| **⚠️ 疑似漏报 AE 挖掘** | 遍历 Form=实验室检查 等表单的 Field | **\[D5 逻辑\]** 发现化验数值达到 2 级及以上异常，跨表检索 AE表 所有 Instance，若无匹配记录，触发告警。 | HardRule |
|
||||
| **与干预的因果关系** | Form=不良事件表 \+ Form=合并用药表(所有Instance) | 提取患者服用的所有药物。**LLM知识库比对**，若属禁忌，提示 PI 关注。 | SoftRule (RAG) |
|
||||
|
||||
### **报告五：方案偏离记录表 (PD Log) (对应 D6 规则)**
|
||||
|
||||
**业务目的**：抓取不按方案日历和标准操作的违规行为。
|
||||
|
||||
| 报告显示的列 | 依赖的 5 层数据坐标 (查什么) | 调用的质控规则与逻辑 (算什么) | 执行引擎 |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **偏离类型：访视超窗** | Event=本次随访 实际日期 vs Event=基线 日期 | **\[D6 逻辑\]** 依据方案 SoA，计算天数差。若超窗则判定为偏离。 | HardRule |
|
||||
| **偏离类型：禁忌药** | Form=合并用药表 \-\> 所有 Instance \-\> 药物名称 | **\[D6 逻辑\]** 将各 Instance 录入药物名与方案知识库比对。 | SoftRule (RAG) |
|
||||
| **偏离描述与分级建议** | 综合上述计算结果 | LLM 将“超窗 5 天”总结为连贯描述，并根据规则库预判 Major/Minor 偏离。 | SoftRule (LLM) |
|
||||
|
||||
## **终极总结：这三者是如何协同工作的？(The Orchestration)**
|
||||
|
||||
1. **底层地基 (数据坐标)**：CDISC 5层架构提供了极其精确的 GPS 定位，彻底搞定了重复表单数据覆盖问题。
|
||||
2. **流水线加工 (规则引擎)**：当 Webhook 带着 InstanceID 涌入时，系统调取 D1\~D7 规则。算缺失率用 D2 解析分支；查超窗用 D6 算日期；查漏报 AE 用 D5 跨 Instance 匹配。
|
||||
3. **顶层组装 (质控报告与 LLM)**：引擎产生带标签的坐标点（如 P005-V2-AE\_Log-Instance\_3: 严重程度未填）。系统将这些剪枝后的碎片喂给 LLM，LLM “翻译”并填入 5 张标准的 GCP 报表。
|
||||
Reference in New Issue
Block a user