# 质控任务首次运行检查清单

## 📋 前置条件检查

### 1. 数据库准备 ✅

#### 已创建的表（4个新表）
- ✅ `qc_task_overall_result` - 整体质控结果表
- ✅ `qc_task_image_result` - 图像质控结果表
- ✅ `qc_task_image_factor_result` - 图像因子结果表
- ✅ `qc_execution_log` - 质控执行日志表

#### 需要确认的现有表
确保以下表存在且有数据：
- `qc_task` - 质控任务表
- `qc_standard` - 质控标准表（需要有启用的标准）
- `qc_standard_factor` - 质控标准因子关联表
- `qc_factor` - 质控因子表
- `study_info` - 检查信息表（需要有已治理的检查数据）
- `dicom_instance_info` - DICOM实例信息表（需要关联到检查）

### 2. 后端配置检查 ✅

#### 核心组件（已实现）
- ✅ `QcStandardMatcher` - 自动匹配质控标准
- ✅ `DicomMetadataParser` - 解析DICOM元数据
- ✅ `QcLevelEvaluator` - 5级质量评价器
- ✅ `QcExecutionService` - 质控执行服务

#### 编译错误修复（已修复）
- ✅ DicomParser 方法调用错误
- ✅ OpenCVImageAnalyzer 方法参数错误
- ✅ 路由映射冲突

### 3. 前端修改（已完成）

#### 新建任务弹窗修改
- ✅ 删除了"质控标准"选择字段
- ✅ 删除了"检查类型"选择字段
- ✅ 添加了质控说明提示框（系统将根据DICOM标签自动匹配标准）
- ✅ 移除了相关字段的表单验证
- ✅ 更新了提交逻辑（不传standardId和modality）
- ✅ 更新了表单重置逻辑
- ✅ 更新了编辑任务逻辑

## 🚀 首次运行步骤

### Step 1: 准备测试数据

#### 1.1 确保质控标准数据
```sql
-- 检查是否有启用的质控标准
SELECT id, standard_name, standard_code, modality, body_part, exam_item, status
FROM qc_standard
WHERE status = 1;
```

**要求**：
- 至少有1条启用的质控标准
- 标准的 `modality`、`body_part`、`exam_item` 字段有值
- 建议准备CT头部平扫的标准

#### 1.2 确认检查数据
```sql
-- 检查是否有已治理的检查数据
SELECT s.study_id, s.modality, s.study_date, s.institution_id,
       COUNT(dii.id) as instance_count
FROM study_info s
LEFT JOIN dicom_instance_info dii ON s.study_id = dii.study_id
WHERE s.study_date BETWEEN '2025-01-01' AND '2025-12-31'
GROUP BY s.study_id
HAVING instance_count > 0
LIMIT 10;
```

**要求**：
- 至少有1条检查数据
- 检查数据必须关联DICOM实例（`dicom_instance_info`表中有对应记录）
- DICOM实例必须有有效的文件路径

### Step 2: 启动应用

#### 2.1 启动后端
```bash
cd /Users/geng/Documents/IdeaProjects/qc-ns
mvn clean package
# 或直接在IDE中运行 QcnsApplication
```

**检查点**：
- ✅ Spring Boot 成功启动，无编译错误
- ✅ 无路由映射冲突错误
- ✅ 数据库连接成功

#### 2.2 启动前端
```bash
cd /Users/geng/Documents/WebstormProjects/qc_web
npm run dev
```

**检查点**：
- ✅ 前端成功启动
- ✅ 可以登录系统
- ✅ 可以访问"质控任务管理"页面

### Step 3: 创建质控任务

#### 3.1 通过界面创建任务
1. 点击"新建任务"按钮
2. 填写必填字段：
   - **任务名称**：例如"测试自动匹配质控"
   - **任务类型**：自动质控 / 手动质控
   - **质控机构**：选择一个机构
   - **计划数量**：例如 10
   - **抽样类型**：随机抽样 / 顺序抽样
   - **数据范围**：
     - 选择"时间范围"，选择开始和结束日期
     - 或选择"患者列表"，输入患者ID
3. 点击"选择检查数据"按钮
4. 在弹出的对话框中，至少选择1条检查数据
5. 点击"确定"
6. 点击"创建"按钮

**预期结果**：
- ✅ 任务创建成功，显示成功提示
- ✅ 任务列表中出现新创建的任务
- ✅ 任务状态为"待执行"
- ✅ 注意：`standard_id` 字段应该为NULL（自动匹配）

#### 3.2 验证任务数据（可选）
```sql
SELECT id, task_name, task_type, institution_id, standard_id,
       exam_ids, status, create_time
FROM qc_task
ORDER BY create_time DESC
LIMIT 1;
```

**确认**：
- `standard_id` 为 NULL（表示使用自动匹配）
- `exam_ids` 包含选择的检查ID（JSON数组格式）
- `status` = 0（待执行）

### Step 4: 执行质控任务

#### 4.1 通过界面执行
1. 在任务列表中找到新创建的任务
2. 点击"开始执行"按钮
3. 确认提示框

**预期过程**：
- ✅ 按钮显示loading状态
- ✅ 30秒内完成执行（或显示"后台运行中"提示）
- ✅ 任务状态变为"已完成"或"执行中"

#### 4.2 查看执行日志
```sql
-- 查看执行日志
SELECT task_id, study_id, log_level, log_message, create_time
FROM qc_execution_log
WHERE task_id = '<你的任务ID>'
ORDER BY create_time DESC
LIMIT 20;
```

**关键日志检查**：
- ✅ "开始执行质控任务"
- ✅ "成功匹配质控标准：standardId=XXX, standardName=XXX"
- ✅ "质控因子数量：X"
- ✅ "检查质控完成：studyId=XXX, pass=X, fail=X"

### Step 5: 查看质控结果

#### 5.1 通过界面查看
1. 任务状态变为"已完成"后，点击"查看结果"按钮
2. 或者在任务列表中点击"任务数据"查看具体检查数据

**预期显示**：
- ✅ 显示患者基本信息
- ✅ 显示检查信息
- ✅ 显示使用的质控标准
- ✅ 显示整体质控结果（按因子汇总）
- ✅ 显示图像详细结果
- ✅ 显示执行日志

#### 5.2 查询结果数据
```sql
-- 整体结果
SELECT factor_name, is_pass, quality_level, score,
       total_image_count, pass_image_count, fail_image_count
FROM qc_task_overall_result
WHERE task_id = '<你的任务ID>';

-- 图像结果
SELECT study_id, sop_instance_uid, image_index,
       pass_factor_count, fail_factor_count,
       total_score, quality_level, is_qualified
FROM qc_task_image_result
WHERE task_id = '<你的任务ID>';

-- 图像因子结果
SELECT factor_name, is_pass, quality_level, score,
       metric_value, threshold_value, analysis_log
FROM qc_task_image_factor_result
WHERE task_id = '<你的任务ID>'
LIMIT 10;
```

## ⚠️ 常见问题排查

### 问题1：任务创建失败
**可能原因**：
- 没有选择检查数据
- 表单验证失败

**解决方法**：
- 确保至少选择了1条检查数据
- 检查浏览器控制台错误信息

### 问题2：任务执行失败
**可能原因**：
- 检查数据没有对应的DICOM实例
- DICOM文件路径不存在
- 无法匹配到质控标准
- OpenCV分析失败

**排查步骤**：
```sql
-- 1. 检查检查数据是否有DICOM实例
SELECT s.study_id, COUNT(dii.id) as instance_count
FROM study_info s
LEFT JOIN dicom_instance_info dii ON s.study_id = dii.study_id
WHERE s.study_id IN ('<检查ID1>', '<检查ID2>')
GROUP BY s.study_id;

-- 2. 检查DICOM文件路径
SELECT sop_instance_uid, file_path
FROM dicom_instance_info
WHERE study_id = '<检查ID>'
LIMIT 5;

-- 3. 检查质控标准是否存在
SELECT id, standard_name, modality, body_part, exam_item
FROM qc_standard
WHERE status = 1;
```

**查看执行日志**：
```sql
SELECT log_level, log_message, stack_trace
FROM qc_execution_log
WHERE task_id = '<任务ID>' AND log_level IN ('ERROR', 'WARN')
ORDER BY create_time DESC;
```

### 问题3：无法匹配质控标准
**可能原因**：
- DICOM标签解析失败
- 没有对应的质控标准

**排查步骤**：
1. 检查 `modality`、`body_part_examined` 标签是否存在
2. 检查质控标准的 `modality`、`body_part`、`exam_item` 配置
3. 参考自动匹配逻辑（优先级：精确匹配 → 模糊匹配exam_item → 模糊匹配body_part）

**解决方法**：
- 如果DICOM标签缺失，需要检查DICOM文件
- 如果标准缺失，需要创建对应的质控标准
- 临时方案：手动创建任务并指定standardId

### 问题4：OpenCV分析失败
**可能原因**：
- DICOM文件路径不存在
- OpenCV库未正确安装
- 图像格式不支持

**排查步骤**：
```sql
-- 检查文件路径
SELECT file_path FROM dicom_instance_info WHERE study_id = '<检查ID>';
```

**验证文件存在**：
```bash
ls -lh /path/to/dicom/file
```

**解决方法**：
- 确保DICOM文件存在于文件系统
- 检查OpenCV Native库是否正确加载
- 查看后端日志中的详细错误信息

### 问题5：质控结果为空
**可能原因**：
- 质控因子未配置
- 阈值配置错误
- 数据类型不匹配

**排查步骤**：
```sql
-- 检查质控标准关联的因子
SELECT sf.factor_id, f.factor_name, f.factor_type,
       sf.threshold_value, f.weight
FROM qc_standard_factor sf
JOIN qc_factor f ON sf.factor_id = f.id
WHERE sf.standard_id = '<标准ID>'
AND f.status = 1;
```

**解决方法**：
- 确保质控标准至少关联了1个启用的因子
- 检查因子阈值配置格式是否正确（JSON格式）
- 查看图像因子结果表中的 `metric_value` 和 `threshold_value`

## 📊 数据验证检查清单

### 最小验证集
- [ ] 至少1条质控标准（status=1）
- [ ] 至少1条检查数据
- [ ] 检查数据至少有1张DICOM图像
- [ ] DICOM文件路径有效且文件存在
- [ ] 质控标准至少关联1个因子

### 完整验证集
- [ ] 质控标准配置完整（modality、body_part、exam_item、因子、阈值）
- [ ] 检查数据metadata完整（modality、body_part_examined等标签）
- [ ] DICOM实例数据完整（sop_instance_uid、file_path等）
- [ ] OpenCV环境正确配置
- [ ] 数据库连接正常
- [ ] 前后端通信正常

## 🎯 成功标志

质控任务首次运行成功的标志：
1. ✅ 任务状态变为"已完成"（status=2）
2. ✅ `pass_count` + `fail_count` = `total_count`
3. ✅ `qc_task_overall_result` 表有记录（整体结果）
4. ✅ `qc_task_image_result` 表有记录（图像结果）
5. ✅ `qc_task_image_factor_result` 表有记录（因子结果）
6. ✅ `qc_execution_log` 表有记录（执行日志）
7. ✅ 可以在前端查看完整结果

## 📝 备注

- **自动匹配标准模式**：创建任务时不传 `standardId`，后端自动匹配
- **手动指定标准模式**：创建任务时传入 `standardId`，使用指定标准
- **两种模式可以共存**：通过 `standardId` 是否为空来判断使用哪种模式
- **编辑任务时**：如果任务已经执行过，保留原有的 `standardId`

---

**文档创建时间**：2025-12-27
**适用版本**：质控系统重新设计后
**相关文档**：
- `/doc/质控系统重新设计-全部完成总结.md`
- `/doc/编译错误修复总结.md`