AIclinicalresearch/docs/03-业务模块/IIT Manager Agent/06-开发记录/2026-02-07-实时质控系统开发记录.md

2026-02-07 实时质控系统开发记录

开发日期： 2026-02-07
开发者： AI Assistant
开发时长： 约 4 小时
主要内容： 实时质控系统核心功能实现

---

一、开发背景

根据 06-实时质控系统开发计划.md 的设计，今天完成了实时质控系统的核心功能开发，包括：

• 数据库表创建
• Webhook 防抖机制
• Worker 双产出改造
• AI 查询优化
• 管理端批量操作功能

---

二、完成的开发任务

2.1 数据库表创建（Phase 1 & 2）

新增 4 个质控相关表到 iit_schema：

表名	Prisma 模型	用途
field_metadata	IitFieldMetadata	REDCap 字段元数据同步
qc_logs	IitQcLog	质控日志（仅新增，审计轨迹）
record_summary	IitRecordSummary	录入汇总（upsert，最新状态）
qc_project_stats	IitQcProjectStats	项目级统计（Dashboard 用）

核心设计原则：

• qc_logs：仅新增，不覆盖，保留完整审计轨迹
• record_summary：upsert，每个记录只有一条汇总
• 支持 formName 字段，用于单表质控规则过滤

2.2 WebhookController 重构

文件： backend/src/modules/iit-manager/controllers/WebhookController.ts

改动：

1. 移除旧的 checkDuplicate() 方法
2. 使用 pg-boss singletonKey 实现防抖
3. Payload 精简：移除 records 数据，改在 Worker 中获取

关键代码：

await jobQueue.push('iit_quality_check', {
  projectId: projectConfig.id,
  recordId: payload.record,
  instrument: payload.instrument,
  eventId: payload.redcap_event_name,
  triggeredBy: 'webhook',
  // pg-boss 防抖参数
  __singletonKey: `qc-${projectConfig.id}-${payload.record}`,
  __singletonSeconds: 300,  // 5分钟
  __expireInSeconds: 15 * 60,  // 15分钟过期
});

2.3 PgBossQueue 增强

文件： backend/src/common/jobs/PgBossQueue.ts

改动：

• 支持通过 data 中的特殊字段传递 pg-boss options
• 新增字段：__singletonKey, __singletonSeconds, __expireInSeconds

2.4 Worker 双产出改造

文件： backend/src/modules/iit-manager/index.ts

改动：

• 一次 Worker 执行，两个产出：
  • 产出1: iit_qc_logs（仅新增，审计轨迹）
  • 产出2: iit_record_summary（upsert，最新状态）
• 分级干预：只有 FAIL 状态才发企业微信通知

2.5 HardRuleEngine 增强

文件： backend/src/modules/iit-manager/engines/HardRuleEngine.ts

改动：

• createHardRuleEngine() 新增可选参数 formName
• 支持按表单名过滤规则（用于单表实时质控）

2.6 QcService 创建

文件： backend/src/modules/iit-manager/services/QcService.ts（新建）

功能：

• queryQcLogs() - 查询质控日志
• getRecordQcSummary() - 获取记录质控摘要
• getRecordSummary() - 获取录入汇总
• getProjectStats() - 获取项目统计
• getProblematicRecords() - 获取问题记录
• getQcTrend() - 获取质控趋势

2.7 ChatService 优化

文件： backend/src/modules/iit-manager/services/ChatService.ts

改动：

1. 新增意图识别：
   • query_enrollment - 录入进度查询
   • query_qc_status - 质控状态查询
2. 优先查询汇总表/质控表，而不是每次都调用 REDCap
3. qcSingleRecord() 优先返回缓存的质控结果（1小时内）

2.8 管理端批量操作功能

后端 API

新增文件：

• backend/src/modules/admin/iit-projects/iitBatchController.ts
• backend/src/modules/admin/iit-projects/iitBatchRoutes.ts

API 端点：

• POST /api/v1/admin/iit-projects/:projectId/batch-qc - 一键全量质控
• POST /api/v1/admin/iit-projects/:projectId/batch-summary - 一键全量数据汇总

前端 UI

修改文件：

• frontend-v2/src/modules/admin/pages/IitProjectDetailPage.tsx
• frontend-v2/src/modules/admin/api/iitProjectApi.ts

功能：

• 在 IIT 项目详情页顶部添加两个按钮
• ⚡ 一键全量质控 - 对所有记录执行质控
• 📊 一键全量汇总 - 同步所有记录的录入状态

---

三、修改文件清单

文件路径	操作	说明
backend/prisma/schema.prisma	修改	新增 4 个质控相关表
backend/src/modules/iit-manager/controllers/WebhookController.ts	修改	pg-boss 防抖
backend/src/common/jobs/PgBossQueue.ts	修改	支持自定义 singletonKey
backend/src/modules/iit-manager/index.ts	修改	Worker 双产出
backend/src/modules/iit-manager/engines/HardRuleEngine.ts	修改	按表单过滤规则
backend/src/modules/iit-manager/services/QcService.ts	新建	质控查询服务
backend/src/modules/iit-manager/services/ChatService.ts	修改	意图识别优化
backend/src/modules/admin/iit-projects/iitBatchController.ts	新建	批量操作 Controller
backend/src/modules/admin/iit-projects/iitBatchRoutes.ts	新建	批量操作路由
backend/src/modules/admin/iit-projects/index.ts	修改	导出新模块
backend/src/index.ts	修改	注册批量操作路由
frontend-v2/src/modules/admin/pages/IitProjectDetailPage.tsx	修改	添加批量操作按钮
frontend-v2/src/modules/admin/api/iitProjectApi.ts	修改	添加批量操作 API

---

四、数据库变更

数据库备份

# 备份位置（Docker 容器内）
/tmp/backup_iit_schema_20260207.dump

执行命令

npx prisma db push --accept-data-loss
npx prisma generate

---

五、待测试内容

1. 端到端测试：REDCap 录入 → Webhook → Worker → 质控日志 + 录入汇总
2. 批量操作测试：一键全量质控、一键全量汇总
3. AI 查询测试：验证优先查询汇总表的效果
4. 防抖测试：5分钟内重复 Webhook 不重复执行

---

六、架构图

┌─────────────────────────────────────────────────────────────────────────────┐
│                          实时质控系统架构                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐    ┌───────────────────┐    ┌──────────────────────────┐  │
│  │   REDCap    │───▶│ WebhookController │───▶│   pg-boss Queue          │  │
│  │  (DET)      │    │ (singletonKey防抖)│    │ (iit_quality_check)      │  │
│  └─────────────┘    └───────────────────┘    └────────────┬─────────────┘  │
│                                                            │                 │
│                                                            ▼                 │
│                                              ┌──────────────────────────┐  │
│                                              │    QC Worker             │  │
│                                              │  (一次执行，双产出)        │  │
│                                              └────────────┬─────────────┘  │
│                                                           │                 │
│                              ┌────────────────────────────┼────────────┐   │
│                              ▼                            ▼            ▼   │
│                    ┌─────────────────┐     ┌─────────────────┐  ┌──────┐  │
│                    │  iit_qc_logs    │     │iit_record_summary│  │ 企微 │  │
│                    │ (仅新增，审计)   │     │  (upsert，汇总)  │  │ 通知 │  │
│                    └─────────────────┘     └─────────────────┘  └──────┘  │
│                              ▲                            ▲                 │
│                              │                            │                 │
│                              └──────────────┬─────────────┘                │
│                                             │                               │
│                                             ▼                               │
│                    ┌────────────────────────────────────────────────────┐  │
│                    │              ChatService / QcService               │  │
│                    │          (优先查询汇总表，而非每次调 REDCap)          │  │
│                    └────────────────────────────────────────────────────┘  │
│                                             ▲                               │
│                                             │                               │
│              ┌──────────────────────────────┴──────────────────────────┐   │
│              │                                                          │   │
│              ▼                                                          ▼   │
│    ┌─────────────────┐                                    ┌─────────────┐  │
│    │   企业微信端     │                                    │  管理端     │  │
│    │  (AI 问答)      │                                    │ (批量操作)  │  │
│    └─────────────────┘                                    └─────────────┘  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

七、下一步计划

1. 重启前后端服务进行端到端测试
2. 验证质控闭环功能
3. 验证 AI 回答问题的准确性提升
4. 考虑实现日批量质控（Cron Job）

---

记录人： AI Assistant
记录时间： 2026-02-07