HaHafeng
5db4a7064c
Summary: - Add 4 new database tables: iit_field_metadata, iit_qc_logs, iit_record_summary, iit_qc_project_stats - Implement pg-boss debounce mechanism in WebhookController - Refactor QC Worker for dual output: QC logs + record summary - Enhance HardRuleEngine to support form-based rule filtering - Create QcService for QC data queries - Optimize ChatService with new intents: query_enrollment, query_qc_status - Add admin batch operations: one-click full QC + one-click full summary - Create IIT Admin management module: project config, QC rules, user mapping Status: Code complete, pending end-to-end testing Co-authored-by: Cursor <cursoragent@cursor.com>
244 lines
11 KiB
Markdown
244 lines
11 KiB
Markdown
# 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
|