Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
AIclinicalresearch/docs/03-业务模块/IIT Manager Agent/04-开发计划/08-CRA智能质控引擎开发计划.md

22 KiB
Raw Permalink Blame History

CRA 智能质控引擎开发计划

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

📋 目录

  1. 背景与目标
  2. 架构设计
  3. 五大规则体系
  4. 当前代码现状
  5. 开发任务清单
  6. 数据库设计补充
  7. 验收标准

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 初始版本，基于方案审查和代码分析
Reference in New Issue View Git Blame Copy Permalink