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:
198
docs/03-业务模块/IIT Manager Agent/09-技术评审报告/CRA AI 替代工作梳理2.md
Normal file
198
docs/03-业务模块/IIT Manager Agent/09-技术评审报告/CRA AI 替代工作梳理2.md
Normal file
File diff suppressed because one or more lines are too long
@@ -0,0 +1,106 @@
|
||||
# **CRA 质控报告自动化生成与 LLM 友好型设计规范**
|
||||
|
||||
**文档版本**：V2.1 (5 层架构剪枝与 LLM 实战版)
|
||||
|
||||
**设计目标**：利用“五层数据坐标剪枝”与“语义组装”，形成对大模型（LLM）极度友好、绝不产生幻觉的 Payload。
|
||||
|
||||
## **核心设计原则：LLM 友好性 (LLM Readiness)**
|
||||
|
||||
要让 LLM 稳定输出，必须遵循“三不”原则：
|
||||
|
||||
1. **不喂全量数据**：依托 5 层架构执行 JSON 树剪枝，只提取 status \= FAIL 的切片。
|
||||
2. **不喂物理字段**：所有的 lb\_alt\_v 必须经过 AutoMapper 映射为 谷丙转氨酶(ALT)。
|
||||
3. **不让 LLM 算数**：日期差、缺失率由 Node.js 算好，直接把“结论标签”喂给 LLM。
|
||||
|
||||
## **报告生成链路与 LLM 模拟实战 (基于 5 层坐标)**
|
||||
|
||||
### **场景一：数据质疑管理 (eQuery Log) \- D3 规则**
|
||||
|
||||
**【业务场景】** D3 逻辑发现异常，生成一条像资深 CRA 写的质疑描述。
|
||||
|
||||
**【剪枝后的 5层 LLM 友好输入片段 ✅】**
|
||||
|
||||
{
|
||||
"system\_instruction": "你是一个严谨的临床数据经理。请根据下方异常数据，生成一条专业的电子质疑（eQuery）。指出矛盾点并给建议，100字以内。",
|
||||
"clinical\_context": {
|
||||
"受试者ID": "P005",
|
||||
"访视阶段": "随访2 (Week 4)",
|
||||
"触发表单": "实验室检查",
|
||||
"数据实例": "Instance 1"
|
||||
},
|
||||
"anomaly\_data": {
|
||||
"异常指标": "谷丙转氨酶 (ALT)",
|
||||
"当前录入值": "150 U/L",
|
||||
"HardRuleEngine\_计算结论": "超出正常上限 (50 U/L) 的 3 倍",
|
||||
"跨表核查结果": "查询《不良事件(AE)表》所有 Instance，当前记录数为 0"
|
||||
}
|
||||
}
|
||||
|
||||
**【LLM 输出示例】**
|
||||
|
||||
“检测到该受试者在「随访2」的「实验室检查」中，谷丙转氨酶(ALT)为 150 U/L，已超出正常上限 3 倍。经跨表核查，未发现对应的《不良事件(AE)》记录。请核实检验结果是否录入无误；若无误，请评估是否需要补充填报 AE。”
|
||||
|
||||
### **场景二：不良事件风险评估 (AE Log) \- D5 规则**
|
||||
|
||||
**【业务场景】** 提取录入的 AE，结合患者的其他重复表单（如多次服药），提示风险。
|
||||
|
||||
**【应对重复表单 (Repeating Forms) 的完美 JSON 结构 ✅】**
|
||||
|
||||
系统精确拉取 AE\_Log 和 ConMed\_Log 下的不同 InstanceID：
|
||||
|
||||
{
|
||||
"system\_instruction": "作为临床安全评估助手，请分析患者新发的 AE，结合既往病史和用药，提示潜在风险关联。你无权下定论，仅供 PI 参考。",
|
||||
"patient\_context": {
|
||||
"受试者": "P012",
|
||||
"合并用药表 (ConMed\_Log)": \[
|
||||
{"instance\_id": 1, "药物名称": "阿司匹林"},
|
||||
{"instance\_id": 2, "药物名称": "布洛芬"}
|
||||
\]
|
||||
},
|
||||
"不良事件表 (AE\_Log)": \[
|
||||
{"instance\_id": 3, "事件名称": "消化道出血", "严重程度": "CTCAE 3级"}
|
||||
\],
|
||||
"rag\_knowledge\_retrieval": "方案规定：非甾体抗炎药（NSAIDs）如布洛芬、阿司匹林联用会显著增加消化道出血风险。"
|
||||
}
|
||||
|
||||
**【LLM 输出示例】**
|
||||
|
||||
“该受试者新发 3 级「消化道出血」(Instance 3)。系统监测到患者正在同时服用「阿司匹林」(Instance 1)与「布洛芬」(Instance 2)。结合方案提示，非甾体抗炎药联用是高危出血因素。建议 PI 重点关注该 AE 是否与合并用药具有因果关系。”
|
||||
|
||||
### **场景三：方案偏离记录 (PD Log) \- D6 规则**
|
||||
|
||||
**【喂给 LLM 的切片 ✅】**
|
||||
|
||||
{
|
||||
"system\_instruction": "请根据硬逻辑引擎计算出的偏差事实，撰写连贯的方案偏离描述，并提出纠正预防措施(CAPA)。",
|
||||
"deviation\_facts": {
|
||||
"坐标": "Record:P002 \-\> Event:随访3 \-\> Form:访视表 \-\> Instance:1",
|
||||
"偏离类型": "访视超窗",
|
||||
"HardRuleEngine\_计算依据": {
|
||||
"方案允许窗口": "2026-02-15 ±3天",
|
||||
"实际发生日期": "2026-02-25",
|
||||
"计算结果": "延误 10 天"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
### **场景四：数据缺失率总结 (Missing Rate Log) \- D2 规则**
|
||||
|
||||
**【特殊说明：此报告尽量不用 LLM】**
|
||||
|
||||
数据缺失率表严禁使用 LLM 计算百分比！完全由 Node.js CompletenessEngine 根据 Instance 和分支逻辑动态计算完成。LLM 仅根据最终聚合数值生成执行摘要。
|
||||
|
||||
**【喂给 LLM 的切片 ✅】**
|
||||
|
||||
{
|
||||
"report\_type": "数据完整性摘要",
|
||||
"total\_missing\_rate": "5.0%",
|
||||
"top\_missing\_forms": \[
|
||||
{"form": "SF-36 生活质量问卷", "missing\_rate": "40%"}
|
||||
\],
|
||||
"task": "基于以上统计数据，写两句话的执行摘要。"
|
||||
}
|
||||
|
||||
**技术收益总结**：
|
||||
|
||||
五层架构（特别是 InstanceID 实例层）的引入，让发给 LLM 的 JSON 数据结构具备了完美的数组映射能力，彻底消灭了多行数据相互覆盖的 Bug，并最大程度防范了 AI 幻觉！
|
||||
99
docs/03-业务模块/IIT Manager Agent/09-技术评审报告/Skill化配置架构技术设计.md
Normal file
99
docs/03-业务模块/IIT Manager Agent/09-技术评审报告/Skill化配置架构技术设计.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# **Skill 化配置架构与业务流转技术设计文档**
|
||||
|
||||
**文档版本**：V2.1 (5层架构与语义解耦全景版)
|
||||
|
||||
**核心理念**：规则必须脱离底层代码；质控逻辑必须基于“医学语义”而非“物理字段”进行配置，以适应不同的 IIT 项目。
|
||||
|
||||
## **第一章 架构总览：从“硬编码”到“Skill 驱动”**
|
||||
|
||||
我们将数据、规则与报告的生成链路设计为高度解耦的三段式架构：
|
||||
|
||||
\[阶段一：基建与抽象\] \[阶段二：Skill 编排配置\] \[阶段三：执行与映射\]
|
||||
(项目前置准备) (DM 规则配置) (引擎自动计算)
|
||||
|
||||
1\. REDCap 字典同步 1\. 选择 Skill 模板 1\. 监听数据变化 (Webhook)
|
||||
2\. 知识库向量化 (RAG) \-\> 2\. 绑定语义标签 \-\> 2\. 提取 5 层级联坐标
|
||||
3\. LLM 语义映射对齐 3\. 设定阈值与报警级别 3\. 引擎执行逻辑 (硬/软)
|
||||
(AutoMapper) (赋能 D1-D7 维度) 4\. 结果落入 5层数据底座
|
||||
5\. 自动组装 5大 GCP 报告
|
||||
|
||||
## **第二章 配置前置准备 (Project Initialization)**
|
||||
|
||||
在配置具体的质控 Skill 前，系统必须完成项目的“数字孪生”构建：
|
||||
|
||||
### **2.1 结构化数据基建：REDCap 元数据同步**
|
||||
|
||||
* **动作**：调用 exportMetadata 获取字典，包含分支逻辑（Branching Logic）。这为 D2 (缺失率) 计算打下基石。
|
||||
|
||||
### **2.2 非结构化知识基建：建立专属 RAG 大脑**
|
||||
|
||||
* **动作**：上传方案 Protocol、ICF，进行向量化。为 D5/D6 的 SoftRule 模糊推理提供依据。
|
||||
|
||||
### **2.3 核心解耦：AutoMapper 语义映射 (重中之重)**
|
||||
|
||||
* **动作**：利用 LLM，将 REDCap 毫无规律的物理变量名（如 ie\_01, ae\_term），映射为**系统内置标准医学语义标签**（如 \[入选标准\_年龄\], \[不良事件\_名称\]）。
|
||||
* **价值**：DM 面向通用语义配置规则，无需关心物理表名，实现通用 Skill 的跨项目复用。
|
||||
|
||||
## **第三章 Skill 核心数据模型设计 (The Skill Schema)**
|
||||
|
||||
### **3.1 数据库表结构 (iit\_skills)**
|
||||
|
||||
model IitSkill {
|
||||
id String @id @default(cuid())
|
||||
projectId String // 绑定到具体项目
|
||||
name String // e.g., "ALT 重度异常监测"
|
||||
|
||||
category String // 关键！挂载到 7 大维度: D1, D2, D3, D5, D6
|
||||
// 质控深度，全面升级支持 5 层架构
|
||||
targetLevel String // RECORD, EVENT, FORM, INSTANCE, FIELD
|
||||
|
||||
engineType String // HARD\_RULE (JSON Logic) 或 SOFT\_RULE (LLM)
|
||||
triggerType String // WEBHOOK (实时) 或 CRON (定时)
|
||||
|
||||
configuration Json // JSON 配置体
|
||||
isActive Boolean @default(true)
|
||||
}
|
||||
|
||||
### **3.2 Configuration 字段设计 (配置解析)**
|
||||
|
||||
**A. HardRule (硬规则 \- 适用于 D1, D3, D7)**
|
||||
|
||||
采用 JSON Logic 语法，实现毫秒级绝对判定。
|
||||
|
||||
{
|
||||
"semantic\_tags": \["实验室\_谷丙转氨酶"\],
|
||||
"logic": {
|
||||
"\>": \[{"var": "实验室\_谷丙转氨酶"}, 150\]
|
||||
},
|
||||
"on\_fail\_message": "谷丙转氨酶(ALT)达到重度异常标准，触发安全预警。",
|
||||
"severity": "CRITICAL"
|
||||
}
|
||||
|
||||
**B. SoftRule (软规则 \- 适用于 D5, D6)**
|
||||
|
||||
采用 Prompt 模板，供 LLM 结合 RAG 在各个 Instance 间进行推理。
|
||||
|
||||
{
|
||||
"semantic\_tags": \["不良事件\_症状描述", "合并用药\_药物名称"\],
|
||||
"prompt\_template": "患者主诉发生了 {不良事件\_症状描述}，请检索知识库禁忌药目录，评估这是否与患者填报的第 {InstanceID} 行用药 {合并用药\_药物名称} 存在禁忌冲突？",
|
||||
"rag\_enabled": true,
|
||||
"severity": "WARNING"
|
||||
}
|
||||
|
||||
## **第四章 配置工作流与执行链路 (How it works in action)**
|
||||
|
||||
### **4.1 DM 配置工作流 (UI 交互层)**
|
||||
|
||||
1. **选择维度**：DM 选择配置【D1 入排标准】。
|
||||
2. **选择模板**：选择“数值范围检验”。
|
||||
3. **绑定语义**：下拉选择 \[入选标准\_年龄\]。
|
||||
4. **设置条件**：\>= 18 且 \<= 75。保存发布。
|
||||
|
||||
### **4.2 引擎自动化执行链路 (Execution Pipeline)**
|
||||
|
||||
1. **触发与拦截**：REDCap Webhook 抵达。
|
||||
2. **提取五层坐标**：解析出 Record:P005 \-\> Event:V2 \-\> Form:AE\_Log \-\> Instance:2 \-\> Field:ae\_term。
|
||||
3. **加载 Skills**：查询匹配的 active Skills。
|
||||
4. **装填数据**：按 AutoMapper 映射装填数值。
|
||||
5. **引擎计算**：调起 HardRuleEngine 或 SoftRuleEngine。
|
||||
6. **状态回写**：若失败，将原因写入 qc\_field\_status，携带 Category (如 D5)，红灯沿五层坐标向上一路冒泡至 Record 级。
|
||||
99
docs/03-业务模块/IIT Manager Agent/09-技术评审报告/五层数据架构方案评审反馈.md
Normal file
99
docs/03-业务模块/IIT Manager Agent/09-技术评审报告/五层数据架构方案评审反馈.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# 五层数据架构方案评审反馈
|
||||
|
||||
> **评审对象**：架构团队提交的 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）。
|
||||
111
docs/03-业务模块/IIT Manager Agent/09-技术评审报告/核心数据架构与业务落地白皮书.md
Normal file
111
docs/03-业务模块/IIT Manager Agent/09-技术评审报告/核心数据架构与业务落地白皮书.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# **纯数字 CRA 平台：五层数据底座与核心引擎技术白皮书**
|
||||
|
||||
**文档版本**：V2.1 (CDISC ODM 国际标准 5 层全景版)
|
||||
|
||||
**核心理念**：以 CDISC ODM 国际标准为底座，彻底解决重复表单问题，打造对人类透明、符合 GCP 规范、对 LLM 友好的临床质控体系。
|
||||
|
||||
## **第一章 核心数据架构：五层状态级联树 (The 5-Layer Hierarchy)**
|
||||
|
||||
为了支撑前端的“受试者 × 表单”热力图，并彻底解决重复表单（Repeating Forms，如多次发生的 AE、多次服药记录）的数据覆盖与追踪问题，我们严格对齐 CDISC ODM 标准，采用 **5 层状态级联架构**作为系统的影子质控底座。
|
||||
|
||||
### **1.1 数据实体定义与 GPS 坐标**
|
||||
|
||||
系统中的任何一个质控状态、任何一条 eQuery，都必须唯一且绝对精确地绑定在这个五维坐标上：
|
||||
|
||||
1. **RecordID (受试者级)**：例如 P005。反映该患者的整体健康度。
|
||||
2. **EventID (访视/事件级)**：例如 Visit\_2（随访2）。反映特定时间点的数据质量。
|
||||
3. **FormID (表单级)**：例如 AE\_Log（不良事件表）。**（前端风险热力图的 X 轴核心来源）**
|
||||
4. **InstanceID (实例/行号级)**：例如 1, 2, 3。**（核心突破！用于区分同一患者填写的第 1 个 AE、第 2 个 AE。非重复表单默认值为 1）**
|
||||
5. **FieldID (字段/变量级)**：例如 ae\_name（不良事件名称）。最底层的原子数据。
|
||||
|
||||
### **1.2 状态级联与冒泡机制 (State Bubbling)**
|
||||
|
||||
当后台的 HardRuleEngine 或 SoftRuleEngine 发现数据异常时：
|
||||
|
||||
1. **精准打标**：系统首先在最底层的 qc\_field\_status 表中，将坐标 P005 \-\> Visit\_2 \-\> AE\_Log \-\> Instance\_2 \-\> ae\_name 标记为 FAIL，并生成一条 eQuery。
|
||||
2. **状态冒泡 (自动向上传递)**：
|
||||
* 包含该字段的实例 Instance\_2 (第2条不良事件) 状态变为 FAIL。
|
||||
* 包含该实例的表单 AE\_Log 的状态自动变为 FAIL（热力图该格子变红）。
|
||||
* 包含该表单的访视 Visit\_2 自动变为 FAIL。
|
||||
* 受试者 P005 的全局状态自动变为 FAIL。
|
||||
3. **闭环消警**：当 CRC 在 REDCap 修改了该实例 Instance\_2 的值，引擎复核通过，底层 Field 变绿，绿灯逐级向上点亮，直至受试者恢复健康状态。
|
||||
|
||||
## **第二章 CRA 质控工作优先级策略**
|
||||
|
||||
面对庞杂的临床规则，我们应遵循\*\*“高频易错、AI 擅长、IIT 痛点”\*\*的原则排定工作优先级：
|
||||
|
||||
### **📌 优先级一：P0 级（系统上线必须具备的核心基石）**
|
||||
|
||||
这些是 IIT 试验中最容易崩盘，且传统 CRC 最头疼的硬逻辑工作。AI 处理这些具有 100% 的准确性和碾压级效率。
|
||||
|
||||
1. **D2 数据完整性 (Completeness)**：扫描 Form、Instance 和 Field 级数据，基于 REDCap 的分支逻辑（Branching Logic）计算真实的缺失率。
|
||||
2. **D3 逻辑准确性 (Accuracy \- Edit Checks)**：时序校验（知情同意 \< 筛选 \< 首次用药）、数值极值校验、跨表单关联必填项校验。
|
||||
3. **D1 入排合规性 (Eligibility)**：对入选/排除标准表单进行强逻辑逆向校验。
|
||||
|
||||
### **📌 优先级二：P1 级（建立系统护城河的亮点功能）**
|
||||
|
||||
1. **D8 核心数据 SDV 强制核对 (AI Vision)**：针对主要研究终点（如肿瘤大小、关键生化指标），强制要求 CRC 在前端上传原始影像/化验单。AI 通过多模态视觉比对。
|
||||
2. **D5 安全性事件漏报侦测 (Safety)**：跨表单与跨实例关联。AI 发现化验单达到 3 级毒性，但 AE\_Log 表中没有任何一个 Instance 记录该事件，立刻触发告警。
|
||||
|
||||
### **📌 优先级三：P2 级（锦上添花的拓展功能）**
|
||||
|
||||
* **D6 方案偏离 (超窗检测)** 与 **D7 试验药物依从性管理**。由于 IIT 很多是非药物研究且随访不严，可作为可选模块后期加入。
|
||||
|
||||
## **第三章 以终为始：多维 CRA 质控报告体系设计**
|
||||
|
||||
结合系统化的 SaaS 管理看板与极其严谨的 GCP 规范要求，我们将最终输出的质控报告划分为两大层级：**“宏观管理驾驶舱层”与“核心业务报表层”**。
|
||||
|
||||
### **3.1 宏观管理层 (Executive Dashboard)**
|
||||
|
||||
用于系统前台实时展示，提供全局项目健康度：
|
||||
|
||||
* **项目综合健康度评分**（基于 D1\~D6 加权计算）。
|
||||
* **受试者风险热力图**（直观展示哪位受试者的哪个表单异常）。
|
||||
* **CRC 数据录入绩效**（eQuery 平均关闭时间、录入时效）。
|
||||
|
||||
### **3.2 核心业务报表层 (GCP 规范自动化日志)**
|
||||
|
||||
这是数字 CRA 真正替代人工的交付物。系统基于“五层数据底座”结合 AI 判定，**自动生成以下 5 张标准化的临床记录表**：
|
||||
|
||||
#### **表 1：筛选与入选登记表 (对应 D1)**
|
||||
|
||||
* **涵盖字段**：筛选编号、性别/年龄、诊断、纳入/排除标准是否符合（AI 判定）、筛选结果（入组/失败）、失败原因（AI 自动抓取不符条款）、电子签名。
|
||||
|
||||
#### **表 2：数据录入率 & 缺失率记录表 (对应 D2)**
|
||||
|
||||
* **涵盖字段**：表格名称、应录入总字段数（基于 Branching Logic 动态计算）、实际已录入字段数、**数据录入率 & 缺失率 %**、缺失变量与原因、审核时间戳。
|
||||
|
||||
#### **表 3：数据质疑管理跟踪表 (eQuery Log) (对应 D3/D4)**
|
||||
|
||||
* **涵盖字段**：质疑编号、5层精确坐标定位、AI 质疑描述（客观描述矛盾点）、发现日期/发现人(AI)、CRC 解释与回复、二次复核状态、关闭日期。
|
||||
|
||||
#### **表 4：AE 不良事件记录与监查表 (对应 D5 \- 核心合规文件)**
|
||||
|
||||
* **涵盖字段**：受试者信息、AE 名称/症状、起止日期、严重程度、**与干预的因果关系（AI 提示禁忌，PI 最终定性）**、处理措施与转归、SAE 时效监控、**⚠️ AI 挖掘出的疑似漏报事件高亮**。
|
||||
|
||||
#### **表 5：方案偏离记录表 (PD Log) (对应 D6)**
|
||||
|
||||
* **涵盖字段**：偏离编号、发生日期、**偏离类型（AI 自动分类：超窗/禁忌用药/未采集等）**、偏离描述、对安全性影响评估（AI 初判，人工复核）、纠正预防措施(CAPA)。
|
||||
|
||||
## **第四章 架构的 LLM 友好性设计与优化 (LLM Readiness)**
|
||||
|
||||
我们的 5 层级联树状架构，天生就是为了喂给 LLM 而设计的最佳结构。采用四大 LLM 优化策略：
|
||||
|
||||
### **优化 1：语义化映射网关 (AutoMapper) —— 解决 LLM 看不懂**
|
||||
|
||||
* **痛点**：REDCap 导出的变量名叫 lb\_dt, ae\_yn。
|
||||
* **优化**：通过 iit\_field\_mapping 表，将其转换为具有临床语义的键：{"采样日期": "2026-02-25", "是否发生不良事件": "否"}。
|
||||
|
||||
### **优化 2：基于实例的剪枝 (Instance-Level Pruning) —— 解决 Token 溢出**
|
||||
|
||||
* **痛点**：写报告时没必要把 95% 正确的数据喂给模型。
|
||||
* **优化**：执行 JSON 树剪枝。只 query 出 qc\_field\_status \= 'FAIL' 的那一小块实例分支：
|
||||
{"受试者\_P005": {"不良事件表": \[{"Instance\_2": {"事件": "发烧", "质控": "未填严重程度"}}\]}}。
|
||||
|
||||
### **优化 3：XML 提示词封装 —— 解决上下文幻觉**
|
||||
|
||||
* 利用 \<record\>, \<event\>, \<form\>, \<instance\> 严格包裹数据，先进的大模型对 XML 层级的理解极佳，能完美规避张冠李戴。
|
||||
|
||||
### **优化 4：计算下放 (CPU over GPU) —— 解决算术薄弱**
|
||||
|
||||
* LLM 绝对不做日期和数值计算（如算缺失率百分比、算超窗天数）。所有硬核计算由 Node.js HardRuleEngine 算好，直接把“结论标签”传给 LLM 组装文字。
|
||||
@@ -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