Files

HaHafeng 0b29fe88b5 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

2026-03-01 15:27:05 +08:00

6.0 KiB

Raw Blame History

核心转换机制白皮书：从五层数据底座到多维质控报告的生成逻辑

文档定位：系统设计核心枢纽，连接底层数据库、规则引擎与前台业务报表。

阅读对象：后端架构师、规则配置工程师（DM）、产品经理

核心理念：质控的本质是“坐标映射与计算”

在我们的系统中，没有任何一份报告是凭空“写”出来的。所有的报告，其本质都是：

取出特定 五层坐标 (Record -> Event -> Form -> Instance -> Field) 上的数据。
放入特定的 规则引擎 (D1~D7) 进行计算。
将计算结果（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)

底层地基 (数据坐标)：CDISC 5层架构提供了极其精确的 GPS 定位，彻底搞定了重复表单数据覆盖问题。
流水线加工 (规则引擎)：当 Webhook 带着 InstanceID 涌入时，系统调取 D1~D7 规则。算缺失率用 D2 解析分支；查超窗用 D6 算日期；查漏报 AE 用 D5 跨 Instance 匹配。
顶层组装 (质控报告与 LLM)：引擎产生带标签的坐标点（如 P005-V2-AE_Log-Instance_3: 严重程度未填）。系统将这些剪枝后的碎片喂给 LLM，LLM “翻译”并填入 5 张标准的 GCP 报表。

6.0 KiB Raw Blame History Unescape Escape