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

📋 前置条件检查

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 确保质控标准数据

-- 检查是否有启用的质控标准
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 确认检查数据

-- 检查是否有已治理的检查数据
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 启动后端

cd /Users/geng/Documents/IdeaProjects/qc-ns
mvn clean package
# 或直接在IDE中运行 QcnsApplication

检查点：

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

2.2 启动前端

cd /Users/geng/Documents/WebstormProjects/qc_web
npm run dev

检查点：

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

Step 3: 创建质控任务

3.1 通过界面创建任务

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

预期结果：

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

3.2 验证任务数据（可选）

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 通过界面执行

在任务列表中找到新创建的任务
点击"开始执行"按钮
确认提示框

预期过程：

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

4.2 查看执行日志

-- 查看执行日志
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 通过界面查看

任务状态变为"已完成"后，点击"查看结果"按钮
或者在任务列表中点击"任务数据"查看具体检查数据

预期显示：

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

5.2 查询结果数据

-- 整体结果
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分析失败

排查步骤：

-- 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;

查看执行日志：

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标签解析失败
没有对应的质控标准

排查步骤：

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

解决方法：

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

问题4：OpenCV分析失败

可能原因：

DICOM文件路径不存在
OpenCV库未正确安装
图像格式不支持

排查步骤：

-- 检查文件路径
SELECT file_path FROM dicom_instance_info WHERE study_id = '<检查ID>';

验证文件存在：

ls -lh /path/to/dicom/file

解决方法：

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

问题5：质控结果为空

可能原因：

质控因子未配置
阈值配置错误
数据类型不匹配

排查步骤：

-- 检查质控标准关联的因子
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环境正确配置
数据库连接正常
前后端通信正常

🎯 成功标志

质控任务首次运行成功的标志：

✅ 任务状态变为"已完成"（status=2）
✅ pass_count + fail_count = total_count
✅ qc_task_overall_result 表有记录（整体结果）
✅ qc_task_image_result 表有记录（图像结果）
✅ qc_task_image_factor_result 表有记录（因子结果）
✅ qc_execution_log 表有记录（执行日志）
✅ 可以在前端查看完整结果

📝 备注

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

文档创建时间：2025-12-27 适用版本：质控系统重新设计后 相关文档：

/doc/质控系统重新设计-全部完成总结.md
/doc/编译错误修复总结.md

质控任务首次运行检查清单.md 10 KB History Raw

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

📋 前置条件检查

1. 数据库准备 ✅

已创建的表（4个新表）

需要确认的现有表

2. 后端配置检查 ✅

核心组件（已实现）

编译错误修复（已修复）

3. 前端修改（已完成）

新建任务弹窗修改

🚀 首次运行步骤

Step 1: 准备测试数据

1.1 确保质控标准数据

1.2 确认检查数据

Step 2: 启动应用

2.1 启动后端

2.2 启动前端

Step 3: 创建质控任务

3.1 通过界面创建任务

3.2 验证任务数据（可选）

Step 4: 执行质控任务

4.1 通过界面执行

4.2 查看执行日志

Step 5: 查看质控结果

5.1 通过界面查看

5.2 查询结果数据

⚠️ 常见问题排查

问题1：任务创建失败

问题2：任务执行失败

问题3：无法匹配质控标准

问题4：OpenCV分析失败

问题5：质控结果为空

📊 数据验证检查清单

最小验证集

完整验证集

🎯 成功标志

📝 备注

质控任务首次运行检查清单.md 10 KB

History Raw