Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(iit): QC deep fix + V3.1 architecture plan + project member management

Browse Source 
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:
HaHafeng
2026-03-01 15:27:05 +08:00
parent c3f7d54fdf
commit 0b29fe88b5
61 changed files with 6877 additions and 524 deletions
Download Patch File Download Diff File Expand all files Collapse all files

479
docs/03-业务模块/IIT Manager Agent/00-系统设计/CRA Agent 质控体系全景技术路径（策略评审稿）.md Normal file
View File

@@ -0,0 +1,479 @@
# CRA Agent 质控体系全景技术路径（策略评审稿）
> **文档性质**：策略与路径评审文档，供团队内部和临床研究专家讨论可行性
> **版本**：V1.0 | 2026-03-01
> **目标读者**：技术团队、产品负责人、临床研究顾问
> **下一步**：经评审认可后，基于本文档形成具体开发计划
---
## 一、背景与核心问题
### 1.1 CRA 做什么
临床监查员（CRA）的工作本质上是一个**多维度的数据质量守门人**。参照行业标准（ICH-GCP E6 R2/R3），CRA 在常规监查阶段的工作可以分解为以下 7 个维度：
| 维度 | CRA 具体工作 | 输出物 |
|------|------------|--------|
| **D1 入组质量** | 核查入排标准、知情同意时序、筛选流程 | 筛选与入组日志 |
| **D2 数据完整性** | 检查缺失字段、录入时效、分支逻辑完整性 | 数据缺失率报表 |
| **D3 变量准确性** | 极值校验、时序逻辑、跨表单关联 | 变量质控清单 |
| **D4 数据质疑管理** | 生成 Query、跟踪回复、二次复核、关闭 | eQuery 清单 |
| **D5 安全性监测** | AE/SAE 识别、编码、分级、因果判定、时效监管 | AE/SAE 追踪表 |
| **D6 方案偏离侦测** | 访视超窗、剂量偏差、操作遗漏、CAPA 跟踪 | 方案偏离记录 |
| **D7 药物管理** | 发药/回收核算、依从性计算、批号追踪 | IP 管理明细 |
以上 7 个维度最终汇聚为一张 **项目健康度评分卡**，供 PI 和项目管理层决策。
### 1.2 我们现在能做什么
当前 CRA Agent 系统已实现的能力：
```
┌──────────────────────────────────────────┐
│ CRA 工作全景（7 维度） │
│ │
已实现 ──────► │ ■ D1 入组质量（入排标准规则已有） │
│ □ D2 数据完整性 │
部分实现 ────► │ ■ D3 变量准确性（基础范围检查） │
│ □ D4 数据质疑管理（eQuery 表已建） │
│ □ D5 安全性监测 │
│ □ D6 方案偏离侦测 │
未涉及 ─────► │ □ D7 药物管理 │
│ │
│ □ 项目健康度评分卡 │
└──────────────────────────────────────────┘
■ 已实现 ■ 部分实现 □ 未涉及
```
**覆盖率估算**：约 20-25%（仅 D1 部分 + D3 基础），距离替代 CRA 70-80% 工作的目标差距明显。
### 1.3 差距的根源
差距不仅是"规则数量不够"，而是**架构层面的三个结构性问题**：
| 问题 | 影响 |
|------|------|
| **规则体系缺乏分类** | 所有规则混在一起，无法按 CRA 工作维度组织和统计 |
| **数据结构粒度不足** | 只有记录级状态，缺少事件级和变量级独立状态表 |
| **报告缺乏维度** | 只有一张扁平的"通过/不通过"报告，无法反映 7 个维度的各自状况 |
---
## 二、核心认知：一条完整的链路
### 2.1 从方案到报告的 1:1 映射链
```
研究方案（Protocol）
│
│ "年龄 16-35 岁、已签知情同意、无排除标准..."
│
▼
变量清单（Data Dictionary）
│
│ age(数值型)、consent_date(日期型)、exclusion_criteria(选择型)...
│
▼
质控规则（QC Rules）──── 按 7 大维度分类
│
│ D1: { "and": [{">=": ["age", 16]}, {"<=": ["age", 35]}] }
│ D3: { "<": ["consent_date", "screening_date"] }
│ D6: { "<=": [{"abs_diff": ["visit_date", "target_date"]}, 3] }
│
▼
三级质控状态（变量级 → 事件级 → 记录级）
│
│ record_3 / baseline / exclusion_criteria → FAIL (D1:排除标准)
│ record_3 / baseline → FAIL
│ record_3 → FAIL
│
▼
多维质控报告（7 个维度各自独立汇总）
│
│ D1 入组质量: 13/14 通过 (92.9%)
│ D3 变量准确性: 98.5% 合格率
│ D5 安全性: 0 例未报告 AE
│ ...
│
▼
项目健康度评分（加权综合）
│
│ 综合评分: 87/100
│ 建议: 关注 3 号受试者入组资格
│
▼
行动（eQuery 派发 / 告警推送 / 监查报告）
```
**关键洞察**：这条链路中的每一环都需要"维度（category）"这根线串起来。变量清单中的字段属于哪个表单→ 规则属于哪个维度→ 质控结果按维度汇总→ 报告按维度呈现。
### 2.2 IIT 场景的特殊性
我们的目标用户是 IIT（研究者发起的试验），与注册临床试验有显著区别：
| 特征 | 注册试验 | IIT 项目 |
|------|---------|---------|
| 有无专职 CRA | 有，全职 CRA 团队 | 通常没有，或仅兼职 |
| 监管严格度 | 极高（FDA/NMPA 审查） | 中等（伦理委员会审查） |
| EDC 系统 | 商业 EDC（Medidata 等） | 多用 REDCap（免费） |
| 预算 | 充足 | 有限 |
| AI 替代的意义 | 从 100% 提升到 110%（锦上添花） | **从 0% 提升到 70%（雪中送炭）** |
**这意味着**：
- 我们不需要追求注册试验级别的完美覆盖
- 优先覆盖 IIT 中**最常出问题、最容易被忽视**的维度
- 先做"有胜于无"的基础覆盖，再做精细化提升
---
## 三、技术路径：三阶段演进
### 阶段一：数据质量基石（当前 → 近期）
**目标**：把已有的能力做扎实，建立正确的数据基础架构。
#### 核心工作
```
1. 三级质控数据结构
├── 变量级状态表（qc_field_status）
├── 事件级状态表（qc_event_status）
└── 记录级状态表（record_summary 改造）
2. 规则分类体系
└── 每条规则标注所属维度（D1-D7）
3. 多模式触发
├── 实时触发（REDCap DET Webhook，已有代码）
├── 定时触发（项目级 Cron 配置，取代全局硬编码）
└── 手动触发（一键全量质控 + AI 对话）
4. 报告结构升级
└── 从扁平报告 → 多维度报告框架
```
#### 覆盖的 CRA 维度
| 维度 | 阶段一目标 |
|------|-----------|
| D1 入组质量 | 已有入排规则，补充知情同意时序检查 |
| D3 变量准确性 | 已有范围检查，补充时序逻辑和跨表单关联 |
| D4 数据质疑 | 已有 eQuery 表，补充闭环状态机 |
#### 需要确认的问题
> **问临床专家**：
> 1. IIT 项目中，入排标准检查和变量范围检查是否是最高优先级？
> 2. 知情同意日期 < 筛选日期 < 基线日期的时序校验，在 IIT 中是否必须？
> 3. 跨表单校验（如性别 vs 妊娠检查）在 IIT 中常见吗？
---
### 阶段二：方案合规覆盖（中期）
**目标**：覆盖 CRA 日常监查中最高频的工作——数据完整性检查和方案偏离侦测。
#### 核心工作
```
1. 数据完整性引擎（D2）
├── 按事件/表单统计应填字段 vs 实际已填
├── 分支逻辑感知（排除不应填的字段）
├── 录入时效统计（REDCap 审计日志 → 计算延迟天数）
└── 缺失率阈值告警
2. 方案偏离侦测引擎（D6）
├── 访视窗口检查（目标日 ± 允许天数）
├── 操作遗漏检查（Schedule of Assessment 对照）
└── 偏离严重性自动分级（Major / Minor）
3. 报告增强
├── 新增"数据完整性"章节
├── 新增"方案偏离"章节
└── 健康度评分初版（D1+D2+D3+D6 加权）
```
#### 覆盖的 CRA 维度
| 维度 | 阶段二目标 |
|------|-----------|
| D2 数据完整性 | **新增**：缺失率、录入时效、分支逻辑计算 |
| D6 方案偏离 | **新增**：超窗检测、操作遗漏、偏离分级 |
#### 需要确认的问题
> **问临床专家**：
> 1. IIT 项目中最常见的方案偏离类型是什么？（超窗？漏检？用药偏差？）
> 2. 访视窗口 ±N 天的 N 值，一般如何确定？是每个方案不同还是有通用标准？
> 3. 数据缺失率到多少算"红灯"？IIT 行业有没有通用标准（如 3%、5%）？
> 4. 分支逻辑的处理——REDCap 中的分支逻辑字段在 Data Dictionary 中是否完整可读？
#### 技术前提
- **依赖阶段一**的三级数据结构和规则分类体系
- 需要从 REDCap 拉取 Schedule of Assessment（表单-事件映射 + 必填字段清单）
- 需要从 REDCap 审计日志（Logging API）获取录入时间信息
---
### 阶段三：安全性与药物管理（远期）
**目标**：覆盖 CRA 工作中专业性最强的部分——不良事件监测和药物管理。
#### 核心工作
```
1. AE/SAE 安全性引擎（D5）
├── AE 识别触发（实验室异常自动触发 AE 检查）
├── 严重程度分级（CTCAE 标准内嵌）
├── 时序逻辑（AE 起止时间 vs 用药时间）
├── SAE 时效监控（发现后 24h 上报 deadline）
└── LLM 辅助：因果关系初步评估（概率性判断）
2. 药物依从性引擎（D7）
├── 发药/回收核算
├── 依从性 = (发药量 - 回收量) / 预期量 × 100%
├── 80%-120% 合格区间判定
└── 批号有效期交叉比对
3. 实验室预警增强
├── 绝对值 vs 正常范围
├── 基线变化率监测（连续升高趋势）
└── DILI（药物性肝损伤）早期预警模型
4. 合并用药核查
├── 方案禁忌药物比对
├── 新增用药 ↔ AE 关联推断
└── 洗脱期计算
5. 完整健康度评分
└── 7 维度加权综合评分 + AI 建议后续行动
```
#### 覆盖的 CRA 维度
| 维度 | 阶段三目标 |
|------|-----------|
| D5 安全性监测 | **新增**：AE/SAE 追踪、时效监控、因果评估 |
| D7 药物管理 | **新增**：依从性计算、批号追踪 |
#### 需要确认的问题
> **问临床专家**：
> 1. IIT 项目中，AE/SAE 的管理是由 PI 团队自行负责还是有外部安全委员会？
> 2. IIT 项目中是否普遍使用 CTCAE 分级？还是只在肿瘤相关 IIT 中常用？
> 3. 药物依从性在 IIT 中的重要性如何？是否每个 IIT 都涉及试验药物管理？
> 4. AI 做因果关系"初步评估"（而非最终判定），这在临床上能否被接受？
> 5. 合并用药的禁忌药物清单，是每个方案自定义还是有标准数据库可以引用？
#### 技术前提
- 依赖阶段一、二的基础设施
- AE/SAE 需要 REDCap 中有对应的 CRF 表单（不是所有 IIT 项目都有）
- 因果关系评估涉及 LLM 概率性推理（SoftRuleEngine），需要人类确认机制
- 药物管理需要 IWRS 或 REDCap 药物管理模块的数据接口
---
## 四、三级数据架构概要
三个阶段共用同一套数据架构，一次设计到位：
```
┌──────────────────────────────────┐
│ qc_field_status │
│ (变量级，保持最新) │
│ │
│ project × record × event × field │
│ + status + rule_category │
│ + actual_value + expected_value │
└───────────────┬──────────────────┘
│ 聚合
┌───────────────▼──────────────────┐
│ qc_event_status │
│ (事件级，保持最新) │
│ │
│ project × record × event │
│ + status (所有变量中最严重的) │
│ + 各维度计数 (d1_issues, d2_...) │
└───────────────┬──────────────────┘
│ 聚合
┌───────────────▼──────────────────┘
│ record_summary │
│ (记录级，保持最新) │
│ │
│ project × record │
│ + overall_status (所有事件最严重) │
│ + events_total / passed / failed │
└───────────────┬──────────────────┘
│ 聚合
┌───────────────▼──────────────────┐
│ 多维度质控报告 │
│ │
│ D1 入组质量: 92.9% │
│ D2 数据完整性: --（阶段二） │
│ D3 变量准确性: 98.5% │
│ D4 eQuery: 3 Open / 12 Closed │
│ D5 安全性: --（阶段三） │
│ D6 方案偏离: --（阶段二） │
│ D7 药物管理: --（阶段三） │
│ ───────────────────────── │
│ 健康度评分: 87 / 100 │
└──────────────────────────────────┘
```
**关键设计决策**：`rule_category` 字段贯穿整个体系，阶段一只用到 `inclusion`/`exclusion`/`variable`，阶段二加入 `completeness`/`protocol_deviation`，阶段三加入 `ae_safety`/`ip_compliance`。**表结构不需要改，只是规则类别在扩展**。
---
## 五、规则类型与引擎匹配
不同维度的规则，其"确定性"不同，需要匹配不同的执行引擎：
| 维度 | 规则性质 | 适用引擎 | 举例 |
|------|---------|---------|------|
| D1 入组质量 | 确定性 100% | HardRuleEngine (JSON Logic) | age ∈ [16,35] |
| D2 数据完整性 | 确定性 100% | 专用 CompletenessEngine | 必填字段 A 为空 |
| D3 变量准确性 | 确定性 90%+ | HardRuleEngine | consent_date < screening_date |
| D4 数据质疑 | 管理流程 | 状态机 (eQuery Workflow) | Open→Answered→Closed |
| D5 安全性 | 确定性 60-80% | HardRule + SoftRuleEngine (LLM) | CTCAE 分级确定，因果关系需 LLM |
| D6 方案偏离 | 确定性 95% | HardRuleEngine + 日历引擎 | visit_date 超出窗口 ±3 天 |
| D7 药物管理 | 确定性 100% | HardRuleEngine | 依从性 = 85% ∈ [80,120] |
**核心原则**：
- **确定性规则用硬引擎**（HardRuleEngine / JSON Logic）——结果可审计、可复现
- **概率性判断用软引擎**（SoftRuleEngine / LLM）——必须附带"AI 建议 + 人类确认"机制
- **D4 不是规则引擎问题**，而是流程管理问题（状态机）
---
## 六、覆盖率演进预期
```
100%─┬─────────────────────────────────────────────
│ ┌───────
80%─┤ ┌────────┤ 阶段三
│ │ D5+D7 │ 70-80%
60%─┤ ┌───────────┤ │
│ │ D2+D6 │ 阶段二 │
40%─┤ │ │ 50-60% │
│ ┌──────────┤ │ │
20%─┤ │ D1+D3+D4 │ 阶段一 │ │
│ │ │ 25-35% │ │
0%─┴──┴──────────┴───────────┴────────┴─────────
现状 阶段一 阶段二 阶段三
```
**说明**：百分比是估算值，表示对 CRA 可替代工作（70-80%）的覆盖程度。阶段三完成后，系统应能覆盖 CRA 可替代工作的绝大部分。
---
## 七、与现有四大工具的关系
当前对话层的 4 个工具（`read_report`、`look_up_data`、`check_quality`、`search_knowledge`）在三个阶段中保持稳定，**工具不变，内涵在扩展**：
| 工具 | 阶段一 | 阶段二 | 阶段三 |
|------|--------|--------|--------|
| `read_report` | D1+D3 报告 | + D2+D6 章节 | + D5+D7 章节 + 健康度评分 |
| `look_up_data` | 原始数据 + 质控标注 | + 缺失率标注 | + AE/ConMed 数据 |
| `check_quality` | 入排 + 变量检查 | + 完整性 + 偏离检查 | + AE + 依从性检查 |
| `search_knowledge` | 研究方案/CRF 搜索 | + Schedule of Assessment | + IB（研究者手册） |
**这是一个很好的设计**——对 LLM 来说，工具数量和接口不变，它不需要"学习"新工具。内部的规则引擎和报告内容在持续丰富，对 LLM 透明。
---
## 八、风险与约束
### 8.1 数据源约束
| 数据需求 | 来源 | 约束 |
|---------|------|------|
| 变量值 | REDCap Record API | ✅ 已打通 |
| 变量定义（Data Dictionary） | REDCap Metadata API | ✅ 已打通 |
| 表单-事件映射 | REDCap Form-Event API | ✅ 已打通 |
| 录入时间（审计日志） | REDCap Logging API | ✅ 已实现（exportLogging） |
| 分支逻辑 | Data Dictionary.branching_logic | ⚠️ 需解析 REDCap 分支逻辑语法 |
| Schedule of Assessment | 研究方案 PDF + 人工配置 | ⚠️ 需要项目管理员手动配置 |
| AE/SAE 表单 | REDCap CRF | ⚠️ 取决于项目是否建了 AE 表单 |
| 药物管理数据 | REDCap CRF 或外部 IWRS | ❌ 可能不在 REDCap 中 |
### 8.2 IIT 场景的现实约束
- **不是所有 IIT 都有 AE 表单**：观察性研究可能没有不良事件采集
- **不是所有 IIT 都涉及试验药物**：非药物干预研究（如手术方案对比）无 D7
- **方案复杂度差异大**：简单的 IIT 可能只有 2 个访视，复杂的可能有 20+
- **REDCap 配置标准化程度低**：不同机构的 REDCap 项目结构差异很大
**应对策略**：系统必须支持"维度可选"——管理员在项目配置时勾选本项目适用的维度，未勾选的维度不执行、不展示。
### 8.3 LLM 在临床决策中的边界
| 场景 | LLM 角色 | 人类角色 |
|------|---------|---------|
| 数值范围检查 | 直接判定 | 不需要 |
| 时序逻辑检查 | 直接判定 | 不需要 |
| 数据缺失统计 | 直接计算 | 不需要 |
| AE 严重程度分级 | 根据 CTCAE 标准建议分级 | PI 确认 |
| AE 因果关系 | **初步评估（建议）** | **PI 必须确认** |
| 方案偏离严重性 | 按规则初分 Major/Minor | PI 可修正 |
| 综合健康度建议 | 提供建议行动 | PI 决策 |
**铁律**：凡涉及医学判断的结论，AI 只提供建议，必须经人类确认后才能写入正式记录。
---
## 九、待讨论的关键问题
以下问题需要在技术评审中与临床研究专家确认：
### 优先级与范围
1. **IIT 项目中，以下 7 个维度的重要性排序是什么？** 哪些是"必须有"，哪些是"有了更好"？
2. **D5（安全性）和 D7（药物管理）在 IIT 中的覆盖率有多高？** 是不是很多 IIT 项目并不涉及？
3. **三个阶段的划分是否合理？** 是否有维度需要提前或推迟？
### 规则可行性
4. **时序逻辑的通用性**：知情同意日 < 筛选日 < 基线日，这个时序在所有 IIT 中都成立吗？
5. **访视窗口**：IIT 中 ±N 天的窗口一般怎么定？是写在方案里的还是有行业惯例？
6. **数据缺失率的"红线"**：IIT 行业是否有通用的缺失率阈值标准？
7. **跨表单校验的实用性**：性别 vs 妊娠检查这类跨表单逻辑在 IIT 中常见吗？
### 临床接受度
8. **AI 做因果关系"初步评估"**，PI 是否愿意参考？还是更倾向完全自行判断？
9. **自动生成的 eQuery 语气和内容**，是否需要 PI 先审核再发给 CRC？
10. **健康度评分**：PI 能否接受一个 AI 打分？评分维度和权重怎么定才合理？
### 数据源
11. **REDCap 中 Schedule of Assessment 的信息**是否足够完整？还是需要额外配置？
12. **AE 表单在 IIT REDCap 项目中的标准化程度如何？** 字段命名是否有规范？
---
## 十、总结
```
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ 研究方案 ──→ 变量清单 ──→ 质控规则 ──→ 三级质控状态 ──→ 多维报告 │
│ (7大维度) (变量/事件/记录) (7大章节) │
│ │
│ 阶段一：D1 入组 + D3 变量 + D4 eQuery ── 数据质量基石 │
│ 阶段二：D2 完整性 + D6 方案偏离 ── 方案合规覆盖 │
│ 阶段三：D5 安全性 + D7 药物管理 ── 全维度覆盖 │
│ │
│ 确定性规则 → HardRuleEngine（可审计、可复现） │
│ 概率性判断 → SoftRuleEngine + LLM（AI 建议 + 人类确认） │
│ │
│ 工具层不变（4 工具），内涵逐步扩展 │
│ 数据架构一次设计到位（三级状态表 + rule_category 字段） │
│ │
└──────────────────────────────────────────────────────────────────────┘
```
**本文档的目的不是确定"怎么做"，而是确定"做什么、按什么顺序做、做到什么程度"。** 经团队和临床专家评审认可后，再基于此形成具体的开发计划和技术设计。