# 质控因子等级评判测试使用说明

## 一、概述

`QualityLevelEvaluationTest` 是一个基于质控因子等级的影像质量评判测试用例。与原有的简单通过/不通过评判不同，本测试使用五个质量等级对影像质量进行精细化的评判，并生成详细的质控报告文件。

## 二、质量等级说明

测试使用以下五个质量等级进行评判：

| 等级 | 分数 | 描述 | 是否否决项 |
|------|------|------|-----------|
| **EXCELLENT** (优秀) | 5分 | 图像清晰可辨，能为诊断提供高质量依据 | 否 |
| **GOOD** (良好) | 4分 | 图像清晰明确，略有瑕疵但不影响诊断 | 否 |
| **MEDIUM** (中等) | 3分 | 图像清晰度一般，瑕疵较多，勉强能为诊断提供依据 | 否 |
| **POOR** (差) | 2分 | 图像清晰度很差，瑕疵非常多，不能为诊断提供依据 | **是** |
| **TERRIBLE** (极差) | 1分 | 图像清晰度极差，有全黑、全白等无效影像 | **是** |

## 三、评判逻辑

### 3.1 图像指标分析

测试会分析以下图像指标：

- **亮度 (brightness)**: 图像的平均亮度值 (0-255)
- **对比度 (contrast)**: 图像的对比度值 (0-100)
- **清晰度/锐度 (sharpness)**: 图像的锐度值 (0-150)
- **标准差 (stdDev)**: 像素值的标准差 (0-60)
- **伪影比率 (artifactRatio)**: 伪影占图像的比例 (0-1.0)

### 3.2 等级判定规则

#### EXCELLENT (优秀) - 5分
```
亮度: 20-235
对比度: ≥50
清晰度: ≥100
标准差: ≥40
伪影比率: ≤0.05
```

#### GOOD (良好) - 4分
```
亮度: 15-240
对比度: ≥40
清晰度: ≥80
标准差: ≥30
伪影比率: ≤0.10
```

#### MEDIUM (中等) - 3分
```
亮度: 12-243
对比度: ≥30
清晰度: ≥60
标准差: ≥25
伪影比率: ≤0.15
```

#### POOR (差) - 2分 (否决项)
```
亮度: 10-245
对比度: ≥20
清晰度: ≥40
标准差: ≥20
伪影比率: ≤0.20
```

#### TERRIBLE (极差) - 1分 (否决项)
```
不满足上述任一等级的条件
```

## 四、使用方法

### 4.1 配置测试参数

在测试类中修改以下配置：

```java
/**
 * 测试影像文件路径
 */
private static final String DICOM_FILE_PATH =
    "/Users/geng/qconline/dicom/INST011/1.2.156.14702.1.1005.128.0.20210128094934016/";

/**
 * 质控报告输出目录
 */
private static final String REPORT_OUTPUT_DIR =
    System.getProperty("user.home") + "/qc_reports/";
```

### 4.2 运行测试

在 IDEA 中：
1. 打开 `QualityLevelEvaluationTest.java`
2. 右键点击 `testQualityLevelEvaluation()` 方法
3. 选择 "Run 'testQualityLevelEvaluation()'"

或者在命令行中：
```bash
mvn test -Dtest=QualityLevelEvaluationTest#testQualityLevelEvaluation
```

### 4.3 查看结果

测试完成后会：

1. **控制台输出**：实时显示测试过程和结果
2. **报告文件**：在 `~/qc_reports/` 目录下生成详细的质控报告文件

报告文件命名格式：`qc_report_YYYYMMDD_HHMMSS.txt`

## 五、测试流程

### 步骤 1: 解析 DICOM 影像文件
```
═══════════════════════════════════════════════════════════════════════════════════
步骤 1: 解析 DICOM 影像文件
═══════════════════════════════════════════════════════════════════════════════════

解析结果：
  - 模态 (Modality): CT
  - 检查部位 (Body Part): HEAD
  - 检查项目 (Exam Item): 头颅平扫
  - 体位 (Position): SUPINE
  - 检查描述 (Description): 颅脑CT
```

### 步骤 2: 自动匹配质控标准
```
═══════════════════════════════════════════════════════════════════════════════════
步骤 2: 自动匹配质控标准
═══════════════════════════════════════════════════════════════════════════════════

✅ 找到匹配的质控标准：
  - 标准ID: STD_001
  - 标准代码: CT_HEAD
  - 标准名称: CT头颅平扫
  - 模态: CT
  - 检查部位: HEAD
  - 合格分数: 80 分
```

### 步骤 3: 获取质控因子列表
```
═══════════════════════════════════════════════════════════════════════════════════
步骤 3: 获取质控因子列表
═══════════════════════════════════════════════════════════════════════════════════

共找到 7 个质控因子：
  1. BASIC_4_1 - 有效图像 (权重: 10, 必需: 是)
  2. BASIC_4_2 - 真实人体图像 (权重: 10, 必需: 是)
  3. BASIC_4_3 - 原始完整图像 (权重: 10, 必需: 是)
  4. CT_5_3_1 - CT图像信息完整性 (权重: 15, 必需: 是)
  5. CT_5_4_1_1_1 - 检查范围（颅脑） (权重: 20, 必需: 是)
  6. CT_5_4_1_1_2 - 图像偏中心 (权重: 15, 必需: 否)
  7. CT_5_4_1_1_3 - 重建参数 (权重: 20, 必需: 否)
```

### 步骤 4: 基于等级的质控评判
```
═══════════════════════════════════════════════════════════════════════════════════
步骤 4: 基于等级的质控评判
═══════════════════════════════════════════════════════════════════════════════════

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
检查因子: 有效图像
因子代码: BASIC_4_1
数据源: image_quality
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

图像指标分析完成:
{
  "brightness": 125.5,
  "contrast": 65.2,
  "sharpness": 105.8,
  "stdDev": 42.3,
  "artifactRatio": 0.03
}

等级判定: EXCELLENT - 5分

评判结果:
  - 质量等级: EXCELLENT
  - 等级分数: 5 分
  - 是否否决项: 否
  - 评判依据: 图像清晰可辨，能为诊断提供高质量依据
```

### 步骤 5: 质控结果汇总
```
═══════════════════════════════════════════════════════════════════════════════════
步骤 5: 质控结果汇总
═══════════════════════════════════════════════════════════════════════════════════

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
质控结果汇总
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
质控标准: CT头颅平扫
合格分数: 80 分
实际得分: 92.50 分
质控结果: ✅ 通过 PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

等级分布：
  - 优秀 (EXCELLENT): 3 个
  - 良好 (GOOD): 2 个
  - 中等 (MEDIUM): 1 个
  - 差 (POOR): 1 个
  - 极差 (TERRIBLE): 0 个
```

### 步骤 6: 生成质控报告文件
```
═══════════════════════════════════════════════════════════════════════════════════
步骤 6: 生成质控报告文件
═══════════════════════════════════════════════════════════════════════════════════

✅ 质控报告已生成: /Users/geng/qc_reports/qc_report_20260126_143522.txt
```

## 六、报告文件示例

质控报告文件包含以下内容：

```
╔════════════════════════════════════════════════════════════════════════════════════╗
║                      医学影像质控系统 - 质控因子等级评判报告                      ║
╚════════════════════════════════════════════════════════════════════════════════════╝

报告生成时间: 2026-01-26 14:35:22

═══════════════════════════════════════════════════════════════════════════════════
步骤 1: 解析 DICOM 影像文件
═══════════════════════════════════════════════════════════════════════════════════

影像解析结果：
  - 模态 (Modality): CT
  - 检查部位 (Body Part): HEAD
  - 检查项目 (Exam Item): 头颅平扫
  - 体位 (Position): SUPINE
  - 检查描述 (Description): 颅脑CT

... (详细的质控过程和结果)

═══════════════════════════════════════════════════════════════════════════════════
报告结束
═══════════════════════════════════════════════════════════════════════════════════

报告文件路径: /Users/geng/qc_reports/qc_report_20260126_143522.txt
```

## 七、与原有测试的对比

| 特性 | AutoQcStandardMatchTest | QualityLevelEvaluationTest |
|------|------------------------|----------------------------|
| 评判方式 | 通过/不通过（二元） | 五级质量等级 |
| 评分 | 简单的权重计算 | 加权平均 + 等级评分 |
| 否决项 | 不支持 | 支持（POOR和TERRIBLE为否决项） |
| 图像分析 | 基本检查 | 详细的图像指标分析 |
| 结果输出 | 仅控制台 | 控制台 + 详细报告文件 |
| 过程记录 | 简单日志 | 详细的过程日志和评判依据 |

## 八、常见问题

### Q1: 如何修改质量等级的阈值？

A: 在 `QualityLevelEvaluationTest.java` 的 `determineQualityLevel()` 方法中修改对应的阈值条件。

### Q2: 如何添加新的图像指标？

A: 在 `analyzeImageMetrics()` 方法中添加新的指标计算逻辑。

### Q3: 报告文件在哪里？

A: 默认在用户主目录下的 `qc_reports/` 文件夹中，可以通过修改 `REPORT_OUTPUT_DIR` 常量来更改。

### Q4: 测试失败怎么办？

A: 检查以下几点：
1. DICOM 文件路径是否正确
2. 数据库中是否存在对应的质控标准和因子
3. OpenCV 库是否正确加载

## 九、后续扩展

1. **集成真实的图像分析**：使用 `OpenCVImageAnalyzer` 进行真实的图像分析，而不是模拟数据
2. **从数据库读取等级配置**：从 `qc_factor_level_config` 表中读取等级配置，而不是硬编码
3. **支持多种报告格式**：除了文本文件，还可以生成 HTML、PDF 等格式的报告
4. **图表展示**：在报告中添加质量等级分布图表

## 十、技术支持

如有问题或建议，请联系开发团队。