# 功能测试用例 Excel 格式适配 · 需求文档（PRD）

> **文档状态**：已定稿 · **版本**：v1.0 · **最后更新**：2026-08-17  
> **维护者**：czj · **所属模块**：报告中心-功能测试

---

## 1. 背景与目标

### 1.1 背景

功能测试报告模块当前**只读取 Excel 的 active sheet**（Sheet 1），且测试结果归一化映射表覆盖的枚举值有限：

| 现状 | 说明 |
|------|------|
| 单 Sheet 读取 | `read_test_cases()` 使用 `wb.active`，只读第一个 Sheet |
| 测试结果映射不全 | `pass_aliases` 未包含"功能验证"等新枚举值 |

近期收到新的测试用例文件 **「大亚湾一体化会议系统测试用例-260811.xlsx」**，其格式与现有模板格式存在差异，当前代码无法正确处理：

1. **多 Sheet 结构**：文件包含 3 个 Sheet（预约会议 / 会议看板 / 会议室管理），每个 Sheet 都是完整独立的测试用例表，需要全部读取合并
2. **新增测试结果枚举**：Sheet 中出现 `"功能验证"` 值（语义 = 通过），当前映射表未识别，会作为原始字符串返回导致统计错误
3. **其他格式要素与现有模板一致**：列结构（17 列）、表头行（Row 3）、数据起始行（Row 4）均与现有模板相同

### 1.2 目标

使功能测试报告模块能够**无缝适配新格式**的测试用例 Excel 文件：

```
读取全部 Sheet → 合并所有测试用例 → 识别新增测试结果枚举 → 正常统计分析 → 生成报告
```

具体目标：

1. **多 Sheet 读取**：`read_test_cases()` 遍历工作簿所有 Sheet，合并读取所有测试用例
2. **新增结果映射**：`normalize_test_result()` 增加 `"功能验证"` → `通过` 映射
3. **兼容性**：不破坏现有单 Sheet 格式文件的读取行为

### 1.3 参考文件

| 文件 | 说明 |
|------|------|
| `E:\GithubData\ubains-module-test\platform-auto-test\临时目录\大亚湾一体化会议系统测试用例-260811.xlsx` | 新格式样例（3 Sheet / 280 行数据） |
| `backend/app/services/functional/excel_reader.py` | 现有读取逻辑（单 Sheet） |
| `backend/app/services/functional/config.py` | 现有常量与映射配置 |

---

## 2. 功能需求

### 2.1 功能清单

| 编号 | 功能 | 说明 | 优先级 |
|------|------|------|--------|
| E1 | 多 Sheet 读取 | `read_test_cases()` 遍历所有 Sheet 合并读取 | **P0** |
| E2 | 新增"功能验证"映射 | `normalize_test_result()` 将"功能验证"归一化为"通过" | **P0** |
| E3 | 向后兼容 | 单 Sheet 旧格式文件读取行为不改变 | P0 |
| E4 | 数据验证 | 对 3 个 Sheet 均执行现有行跳过逻辑（序号为空跳过） | P1 |

### 2.2 功能详细说明

#### E1. 多 Sheet 读取

**现状**：`read_test_cases()` 中 `ws = wb.active` 只读取第一个 Sheet。

**改造**：遍历 `wb.sheetnames` 中所有 Sheet，对每个 Sheet 执行相同的数据行读取逻辑（`min_row=CASE_DATA_START_ROW`，序号为 0 跳过），按 Sheet 顺序拼接所有测试用例。

**结果**：3 个 Sheet 合计 277 条数据全部读入，`module` 字段自动分组统计（报告按模块分布统计不受影响）。

#### E2. 新增测试结果映射

**现状**：`pass_aliases` 包含 `{"通过", "Pass", "PASS", "pass", "成功", "P", "√", "✓", "是", "yes", "Yes", "YES"}`。

**改造**：新增 `"功能验证"` 别名。

**结果**：`"功能验证"` → `TEST_RESULT_PASS`（"通过"），通过率统计正确。

#### E3. 向后兼容

- 单 Sheet 文件：遍历只有一个 Sheet，行为与现在完全一致
- 多参数 `skip` 逻辑不变：仅对 `serial_number` 为 0 的行跳过

#### E4. 数据验证

- 每个 Sheet 独立判断数据起始行（Row 4）
- 遇空行继续向下（不做提前 break，避免 Sheet 间数据遗漏）
- 用例编号生成规则不变（如 `HYKB-001`、`YYHY-001`），供 BUG 关联使用

---

## 3. 非功能需求

| 项 | 说明 |
|----|------|
| 性能 | 多 Sheet 合并后仍为单次读取，无额外 IO |
| 兼容 | 不影响 BUG 列表 Excel 读取（仍为单 Sheet） |
| 回归 | 现有 17 列模板文件（`data/input/用例模板.xlsx`）可正常读取 |

---

## 4. 验收标准

| # | 验收点 | 预期结果 |
|---|--------|----------|
| 1 | 上传新格式文件（3 Sheet） | 后端成功解析，读取全部 277 条用例 |
| 2 | 数据统计 | 通过/失败/未验证/未开发四类统计正确，"功能验证"计入通过 |
| 3 | 生成报告 | 10 章节报告正常生成，模块分布覆盖 3 个 Sheet 的模块 |
| 4 | 旧格式文件回归 | 原单 Sheet 模板文件读取与统计结果不变 |

---

*本 PRD 由 Claude Code 编写，供 prd-plan / prd-code 流程使用。*