# CRA 智能质控引擎开发计划 > **版本：** V1.0 > **日期：** 2026-02-08 > **基于：** V2.6 综合开发计划、CRA Agent 业务逻辑与执行架构书、Skills 配置实施指南 > **核心目标：** 实现基于规则的智能质控引擎 + 报告驱动的 LLM 问答 --- ## 📋 目录 1. [背景与目标](#1-背景与目标) 2. [架构设计](#2-架构设计) 3. [五大规则体系](#3-五大规则体系) 4. [当前代码现状](#4-当前代码现状) 5. [开发任务清单](#5-开发任务清单) 6. [数据库设计补充](#6-数据库设计补充) 7. [验收标准](#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) ```json { "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) ```json { "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) ```json { "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 设计 ```typescript // 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; confidence: number; } export class SoftRuleEngine { private projectId: string; private llmClient: LLMClient; async execute( recordId: string, data: Record, checks: SoftRuleCheck[] ): Promise; } ``` #### 1.2 SkillRunner 设计 ```typescript // 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; /** * 执行单个 Skill */ private async executeSkill( skill: IitSkill, recordId: string, data: Record ): Promise; } ``` ### 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 设计 ```typescript // 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; /** * 获取缓存的报告（用于 LLM 问答） */ async getCachedReport(projectId: string): Promise; /** * 构建 LLM 友好的 XML 报告 */ private buildLlmXmlReport(stats: ProjectStats, issues: QcIssue[]): string; } ``` #### LLM 阅读版报告格式 ```xml 50 3 12 85.2% 知情同意书签署日期(2026-01-15)晚于首次访视(2026-01-10) 2026-01-15 2026-01-10 受试者确诊时间超过入组标准（确诊日期距入组已超过3个月） 2025-10-01 2026-02-01 BMI 值偏高(42.5)，请核实
``` ### 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 表 ```prisma 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 表 ```prisma /// 质控报告存储表 - 存储预生成的 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. 参考文档 - [CRA Agent 业务逻辑与执行架构书](../02-技术设计/CRA%20Agent%20业务逻辑与执行架构书%20(1).md) - [基于 Skills 的 CRA 规则配置实施指南](../02-技术设计/docs_03-业务模块_IIT%20Manager%20Agent_02-技术设计_11-基于Skills的CRA规则配置实施指南.md) - [V2.6 综合开发计划](./IIT%20Manager%20Agent%20V2.6%20综合开发计划.md) - [02-核心引擎实现指南](./02-核心引擎实现指南.md) --- **文档维护人**：AI Agent **最后更新**：2026-02-08 ### 更新日志 | 版本 | 日期 | 更新内容 | |------|------|----------| | V1.0 | 2026-02-08 | 初始版本，基于方案审查和代码分析 |