# 2026-02-07 实时质控系统开发记录 > **开发日期：** 2026-02-07 > **开发者：** AI Assistant > **开发时长：** 约 4 小时 > **主要内容：** 实时质控系统核心功能实现 --- ## 一、开发背景 根据 [06-实时质控系统开发计划.md](../04-开发计划/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 中获取 **关键代码：** ```typescript 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 | --- ## 四、数据库变更 ### 数据库备份 ```bash # 备份位置（Docker 容器内） /tmp/backup_iit_schema_20260207.dump ``` ### 执行命令 ```bash 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