Files

HaHafeng 7a299e8562 feat(iit): Implement event-level QC architecture V3.1 with dynamic rule filtering, report deduplication and AI intent enhancement

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-02-08 21:22:11 +08:00

22 KiB

Raw Blame History

CRA 智能质控引擎开发计划

版本： V1.0
日期： 2026-02-08
基于： V2.6 综合开发计划、CRA Agent 业务逻辑与执行架构书、Skills 配置实施指南
核心目标： 实现基于规则的智能质控引擎 + 报告驱动的 LLM 问答

1. 背景与目标

1.1 业务需求

针对 CRA（临床研究助理）的质控工作，基于 REDCap 系统的数据结构，建立以下规则体系：

编号	规则类型	说明	来源
1	变量质控	针对每个变量的数据校验（空值、范围、格式）	自动从 Metadata 同步
2	入排标准	判断是否符合入组/排除标准	AI 解析 Protocol + 人工确认
3	方案偏离 (PD)	检测访视超窗、漏做检查等	人工配置逻辑
4	AE 事件	检测未报告的不良事件	预置医学 Prompt
5	伦理合规	ICF 签署时间、隐私保护等	预置硬规则

1.2 核心目标

┌─────────────────────────────────────────────────────────────────┐
│  🎯 目标：报告驱动的智能质控                                      │
│                                                                 │
│  后台预计算 → 生成结构化报告 → LLM 阅读报告 → 回答用户问题         │
│                                                                 │
│  ✅ 快速（报告已预生成）                                          │
│  ✅ 全面（后台执行所有规则）                                       │
│  ✅ 省钱（LLM 只做阅读理解）                                       │
└─────────────────────────────────────────────────────────────────┘

1.3 与 V2.6 计划的关系

本计划是 V2.6 综合开发计划的专项实施细化，聚焦于：

Phase 1 的 HardRuleEngine 深化
Phase 2 的 SoftRuleEngine 实现
Phase 4 的 SchedulerService 和 ReportService 实现

2. 架构设计

2.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                        触发层 (Trigger)                          │
├──────────────────┬──────────────────┬───────────────────────────┤
│  🟢 Webhook       │  🔵 Cron          │  🟠 Manual                 │
│  REDCap DET      │  每日凌晨         │  一键全量质控              │
│  单记录实时       │  全量扫描         │  按需执行                  │
└──────────────────┴──────────────────┴───────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    🎯 SkillRunner (调度器)                        │
│                                                                 │
│  1. 加载启用的 Skills                                            │
│  2. 根据 triggerType 过滤                                        │
│  3. 路由到对应 Engine                                            │
│  4. 聚合结果                                                     │
└─────────────────────────────────────────────────────────────────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│  HardRuleEngine  │ │  SoftRuleEngine  │ │  HybridEngine    │
│  (已实现 ✅)      │ │  (待实现 ❌)      │ │  (待实现 ❌)     │
│                  │ │                  │ │                  │
│  - 变量质控      │ │  - 入排标准      │ │  - 方案偏离      │
│  - 伦理合规      │ │  - AE 检测       │ │  - Hard + Soft   │
│                  │ │                  │ │                  │
│  JSON Logic      │ │  LLM 推理        │ │  条件分支        │
└──────────────────┘ └──────────────────┘ └──────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    📊 结果存储 & 报告生成                          │
├─────────────────────────────────────────────────────────────────┤
│  iit_qc_logs          → 详细质控日志                              │
│  iit_qc_project_stats → 项目统计摘要                              │
│  iit_qc_report (新)   → LLM 友好的结构化报告                      │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    💬 用户问答 (实时)                              │
│                                                                 │
│  用户提问 → ContextBuilder 加载报告 → LLM 阅读 → 回答             │
└─────────────────────────────────────────────────────────────────┘

2.2 漏斗式执行策略

为每个受试者执行以下管道，分级检查，逐层深入：

┌─────────────────────────────────────────────────────────────────┐
│  Level 1: 阻断性检查 (Blocking)                                  │
│  - 伦理合规 (ICF 日期)                                           │
│  - 关键字段缺失                                                  │
│  如果 FAIL → 直接标记 Critical，跳过后续 AI 检查（省钱）           │
├─────────────────────────────────────────────────────────────────┤
│  Level 2: 基础清洗 (Hard Rules)                                  │
│  - 所有变量质控规则                                               │
│  - 生成基础错误日志                                               │
├─────────────────────────────────────────────────────────────────┤
│  Level 3: AI 深度监查 (Soft Rules)                               │
│  - 入排标准判断                                                  │
│  - 方案偏离检测                                                  │
│  - AE 事件核查                                                   │
│  - 输出证据链                                                    │
└─────────────────────────────────────────────────────────────────┘

3. 五大规则体系

3.1 规则类型与执行引擎

编号	规则类型	执行引擎	触发时机	典型示例
1	变量质控	HardRuleEngine	实时 + 定时	空值检查、0 < BMI < 50
2	入排标准	SoftRuleEngine	定时 + 人工	确诊时间 < 3个月
3	方案偏离	HybridEngine	定时	访视超窗 (Date2 - Date1 > 28+3)
4	AE 事件	SoftRuleEngine	定时	Lab 异常 vs AE 记录一致性
5	伦理合规	HardRuleEngine	实时	ICF 签署日期 > 首次访视

3.2 Skill 配置示例

3.2.1 变量质控 Skill (HARD_RULE)

{
  "skillType": "VARIABLE_QC",
  "name": "变量质控",
  "type": "HARD_RULE",
  "triggerType": "webhook",
  "config": {
    "engine": "HardRuleEngine",
    "rules": [
      {
        "id": "VQ-001",
        "name": "年龄范围检查",
        "field": "age",
        "formName": "demographics",
        "logic": { "and": [{ ">=": [{ "var": "age" }, 18] }, { "<=": [{ "var": "age" }, 80] }] },
        "message": "年龄必须在 18-80 岁之间",
        "severity": "error",
        "category": "lab_values"
      },
      {
        "id": "VQ-002",
        "name": "BMI 范围检查",
        "field": "bmi",
        "formName": "demographics",
        "logic": { "and": [{ ">": [{ "var": "bmi" }, 0] }, { "<": [{ "var": "bmi" }, 50] }] },
        "message": "BMI 值异常",
        "severity": "warning",
        "category": "lab_values"
      }
    ]
  }
}

3.2.2 入排标准 Skill (LLM_CHECK)

{
  "skillType": "INCLUSION_EXCLUSION",
  "name": "入排标准核查",
  "type": "LLM_CHECK",
  "triggerType": "cron",
  "config": {
    "engine": "SoftRuleEngine",
    "model": "deepseek-v3",
    "systemPrompt": "你是一个专业的临床研究监查员，负责核查受试者是否符合入组标准。",
    "checks": [
      {
        "id": "IE-001",
        "name": "确诊时间核查",
        "promptTemplate": "基于以下数据，判断受试者的确诊时间是否在 3 个月内：\n{{#demographics}}\n{{#medical_history}}\n\n请给出判断结果 (PASS/FAIL) 和理由。",
        "requiredTags": ["#demographics", "#medical_history"]
      }
    ]
  },
  "requiredTags": ["#demographics", "#medical_history", "#lab"]
}

3.2.3 伦理合规 Skill (HARD_RULE)

{
  "skillType": "ETHICS_COMPLIANCE",
  "name": "伦理合规检查",
  "type": "HARD_RULE",
  "triggerType": "webhook",
  "config": {
    "engine": "HardRuleEngine",
    "level": "blocking",
    "rules": [
      {
        "id": "EC-001",
        "name": "知情同意书签署时间",
        "field": ["icf_date", "first_visit_date"],
        "logic": { "<=": [{ "var": "icf_date" }, { "var": "first_visit_date" }] },
        "message": "知情同意书签署日期必须早于或等于首次访视日期",
        "severity": "error",
        "category": "ethics"
      }
    ]
  }
}

4. 当前代码现状

4.1 已实现组件 ✅

组件	路径	说明
`IitSkill` 表	`prisma/schema.prisma`	已定义，支持 triggerType
`IitFieldMapping` 表	`prisma/schema.prisma`	字段映射表
`HardRuleEngine`	`engines/HardRuleEngine.ts`	基于 JSON Logic，支持 formName 过滤
`QcService`	`services/QcService.ts`	基础查询服务
`PromptBuilder`	`services/PromptBuilder.ts`	XML Clinical Slice 格式
`RedcapAdapter`	`adapters/RedcapAdapter.ts`	REDCap API 适配
QC Cockpit UI	`frontend-v2/.../IitQcCockpitPage.tsx`	热力图 + 详情抽屉
字段元数据同步	`iitProjectService.syncMetadata`	含 Form Labels

4.2 缺失组件 ❌

组件	优先级	依赖	说明
`SoftRuleEngine`	P0	LLMFactory	LLM 推理引擎
`HybridEngine`	P1	HardRule + SoftRule	混合执行引擎
`SkillRunner`	P0	所有 Engine	规则调度器
`QcReportService`	P0	SkillRunner	LLM 友好报告生成
`iit_qc_report` 表	P0	-	报告存储
定时调度	P1	pg-boss / node-cron	Cron 触发
增量检查	P2	-	数据 Hash 策略
Rule Studio UI	P2	-	规则配置界面
默认规则配置	P0	-	5 大规则的初始 JSON

5. 开发任务清单

Phase 1: 核心引擎 (Week 1)

任务	优先级	预估	产出
1.1 实现 `SoftRuleEngine`	P0	2天	LLM 推理引擎
1.2 实现 `SkillRunner`	P0	1天	规则调度器
1.3 扩展 `IitSkill` Schema	P0	0.5天	添加 `requiredTags` 字段
1.4 创建默认规则配置	P0	1天	5 大规则的 Seed 数据

1.1 SoftRuleEngine 设计

// backend/src/modules/iit-manager/engines/SoftRuleEngine.ts

export interface SoftRuleCheck {
  id: string;
  name: string;
  promptTemplate: string;
  requiredTags: string[];
}

export interface SoftRuleResult {
  checkId: string;
  status: 'PASS' | 'FAIL' | 'UNCERTAIN';
  reason: string;
  evidence: Record<string, any>;
  confidence: number;
}

export class SoftRuleEngine {
  private projectId: string;
  private llmClient: LLMClient;
  
  async execute(
    recordId: string, 
    data: Record<string, any>,
    checks: SoftRuleCheck[]
  ): Promise<SoftRuleResult[]>;
}

1.2 SkillRunner 设计

// backend/src/modules/iit-manager/engines/SkillRunner.ts

export class SkillRunner {
  /**
   * 按触发类型执行 Skills
   */
  async runByTrigger(
    triggerType: 'webhook' | 'cron' | 'manual',
    projectId: string,
    options?: {
      recordId?: string;      // webhook 时必传
      formName?: string;      // webhook 时过滤相关规则
    }
  ): Promise<SkillRunResult>;
  
  /**
   * 执行单个 Skill
   */
  private async executeSkill(
    skill: IitSkill,
    recordId: string,
    data: Record<string, any>
  ): Promise<SkillResult>;
}

Phase 2: 报告系统 (Week 2)

任务	优先级	预估	产出
2.1 设计 `iit_qc_report` 表	P0	0.5天	报告存储 Schema
2.2 实现 `QcReportService`	P0	2天	报告生成服务
2.3 集成到 Cockpit UI	P1	1天	报告查看入口
2.4 实现 LLM 问答集成	P1	1天	基于报告回答

2.2 QcReportService 设计

// backend/src/modules/iit-manager/services/QcReportService.ts

export interface QcReport {
  projectId: string;
  generatedAt: Date;
  summary: {
    totalRecords: number;
    criticalIssues: number;
    pendingQueries: number;
    passRate: number;
  };
  criticalList: QcIssue[];
  warningList: QcIssue[];
  llmFriendlyXml: string;  // LLM 阅读版
}

export class QcReportService {
  /**
   * 生成项目质控报告
   */
  async generateReport(projectId: string): Promise<QcReport>;
  
  /**
   * 获取缓存的报告（用于 LLM 问答）
   */
  async getCachedReport(projectId: string): Promise<string>;
  
  /**
   * 构建 LLM 友好的 XML 报告
   */
  private buildLlmXmlReport(stats: ProjectStats, issues: QcIssue[]): string;
}

LLM 阅读版报告格式

<qc_report project="PD-001" generated="2026-02-08T10:00:00Z">
  <summary>
    <total_records>50</total_records>
    <critical_issues>3</critical_issues>
    <pending_queries>12</pending_queries>
    <pass_rate>85.2%</pass_rate>
  </summary>
  
  <critical_list>
    <issue record="P001" rule="EC-001" severity="RED">
      <description>知情同意书签署日期(2026-01-15)晚于首次访视(2026-01-10)</description>
      <evidence>
        <field name="icf_date">2026-01-15</field>
        <field name="first_visit_date">2026-01-10</field>
      </evidence>
    </issue>
    <issue record="P003" rule="IE-001" severity="RED">
      <description>受试者确诊时间超过入组标准（确诊日期距入组已超过3个月）</description>
      <evidence>
        <field name="diagnosis_date">2025-10-01</field>
        <field name="enrollment_date">2026-02-01</field>
      </evidence>
    </issue>
  </critical_list>
  
  <warning_list>
    <issue record="P007" rule="VQ-002" severity="YELLOW">
      <description>BMI 值偏高(42.5)，请核实</description>
    </issue>
  </warning_list>
  
  <by_form>
    <form name="人口学" total="50" pass="48" fail="2" />
    <form name="实验室检查" total="150" pass="142" fail="8" />
  </by_form>
</qc_report>

Phase 3: 定时调度 (Week 3)

任务	优先级	预估	产出
3.1 集成 node-cron	P1	0.5天	定时任务框架
3.2 实现 Cron 触发逻辑	P1	1天	定时全量质控
3.3 实现增量检查	P2	1天	数据 Hash 跳过
3.4 实现 Webhook 触发	P2	1天	REDCap DET 集成

Phase 4: 规则配置 UI (Week 4)

任务	优先级	预估	产出
4.1 Rule Studio 页面框架	P2	1天	规则列表 + 详情
4.2 规则编辑器	P2	2天	JSON 可视化编辑
4.3 规则测试功能	P2	1天	单条规则验证

6. 数据库设计补充

6.1 扩展 IitSkill 表

model IitSkill {
  id           String   @id @default(uuid())
  projectId    String   @map("project_id")
  skillType    String   @map("skill_type")
  name         String
  description  String?
  
  // 规则类型
  ruleType     String   @default("HARD_RULE") @map("rule_type")  // 'HARD_RULE' | 'LLM_CHECK' | 'HYBRID'
  
  // 执行级别
  level        String   @default("normal")  // 'blocking' | 'normal'
  
  // 核心配置
  config       Json     @db.JsonB
  
  // 数据依赖（智能路由用）
  requiredTags String[] @map("required_tags")  // 新增：e.g., ['#lab', '#demographics']
  
  // 触发配置
  triggerType  String   @default("webhook") @map("trigger_type")
  cronSchedule String?  @map("cron_schedule")
  
  isActive     Boolean  @default(true) @map("is_active")
  priority     Int      @default(100)  // 新增：执行优先级
  
  createdAt    DateTime @default(now()) @map("created_at")
  updatedAt    DateTime @updatedAt @map("updated_at")

  @@unique([projectId, skillType], map: "unique_iit_skill_project_type")
  @@index([projectId], map: "idx_iit_skill_project")
  @@index([isActive, triggerType], map: "idx_iit_skill_active_trigger")
  @@map("skills")
  @@schema("iit_schema")
}

6.2 新增 IitQcReport 表

/// 质控报告存储表 - 存储预生成的 LLM 友好报告
model IitQcReport {
  id           String   @id @default(uuid())
  projectId    String   @map("project_id")
  
  // 报告类型
  reportType   String   @default("daily") @map("report_type")  // 'daily' | 'weekly' | 'on_demand'
  
  // 统计摘要
  summary      Json     @db.JsonB  // { totalRecords, criticalIssues, pendingQueries, passRate }
  
  // 详细问题列表
  issues       Json     @db.JsonB  // [{ record, rule, severity, description, evidence }]
  
  // LLM 友好的 XML 报告
  llmReport    String   @map("llm_report") @db.Text
  
  // 报告生成时间
  generatedAt  DateTime @default(now()) @map("generated_at")
  
  // 报告有效期
  expiresAt    DateTime? @map("expires_at")
  
  @@index([projectId, reportType], map: "idx_qc_report_project_type")
  @@index([generatedAt], map: "idx_qc_report_generated")
  @@map("qc_reports")
  @@schema("iit_schema")
}

7. 验收标准

7.1 功能验收

功能	验收标准
变量质控	单记录质控 < 100ms；批量 50 记录 < 2s
入排标准	LLM 判断准确率 > 90%；单记录 < 3s
报告生成	50 记录的项目报告生成 < 5s
LLM 问答	基于报告回答延迟 < 2s
定时任务	每日凌晨自动执行，连续 7 天无故障

7.2 性能指标

指标	目标值
HardRuleEngine 执行时间	< 100ms / 记录
SoftRuleEngine 执行时间	< 3s / 记录
报告加载时间	< 200ms
端到端问答延迟	< 3s

7.3 业务验收

CRA 可以通过 Cockpit 查看所有严重问题
点击问题可以查看详细数据和证据
用户可以通过对话询问质控问题，LLM 基于报告回答
定时任务每日自动执行，生成最新报告
规则可以通过配置界面增删改

8. 风险与应对

风险	影响	应对措施
LLM 判断不准确	入排/AE 检测误报	三态管理（Pending → 人工确认）
规则配置复杂	用户上手困难	提供预置规则模板
数据量大时性能下降	质控变慢	增量检查 + 分批执行
REDCap Webhook 不稳定	实时质控失效	定时任务兜底

9. 参考文档

文档维护人：AI Agent
最后更新：2026-02-08

更新日志

版本	日期	更新内容
V1.0	2026-02-08	初始版本，基于方案审查和代码分析

22 KiB Raw Blame History Unescape Escape

CRA 智能质控引擎开发计划

📋 目录

1. 背景与目标

1.1 业务需求

1.2 核心目标

1.3 与 V2.6 计划的关系

2. 架构设计

2.1 整体架构

2.2 漏斗式执行策略

3. 五大规则体系

3.1 规则类型与执行引擎

3.2 Skill 配置示例

3.2.1 变量质控 Skill (HARD_RULE)

3.2.2 入排标准 Skill (LLM_CHECK)

3.2.3 伦理合规 Skill (HARD_RULE)

4. 当前代码现状

4.1 已实现组件 ✅

4.2 缺失组件 ❌

5. 开发任务清单

Phase 1: 核心引擎 (Week 1)

1.1 SoftRuleEngine 设计

1.2 SkillRunner 设计

Phase 2: 报告系统 (Week 2)

2.2 QcReportService 设计

LLM 阅读版报告格式

Phase 3: 定时调度 (Week 3)

Phase 4: 规则配置 UI (Week 4)

6. 数据库设计补充

6.1 扩展 IitSkill 表

6.2 新增 IitQcReport 表

7. 验收标准

7.1 功能验收

7.2 性能指标

7.3 业务验收

8. 风险与应对

9. 参考文档

更新日志

22 KiB

Raw Blame History