# 报告中心-功能测试模块 · 需求文档（PRD）

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

---

## 1. 背景与目标

### 1.1 背景

平台现阶段已支持 UI 自动化测试报告（HTML iframe 渲染）和安全测试报告（Markdown 渲染）。功能测试作为软件测试的核心环节，目前完全依赖人工：

- 测试人员手动整理 Excel 测试用例执行结果
- 手动汇总 BUG 列表数据
- 手动编写 Word 格式功能测试报告
- 手动将报告上传至 ERP 系统

流程重复、效率低、格式不统一，且易出错。

### 1.2 目标

在平台中集成**功能测试报告自动生成**能力，实现：

```
上传 Excel（测试用例 + BUG 列表）→ 自动分析数据 → 生成统计图表 →
生成 Word/Markdown 报告 → 一键上传 ERP
```

### 1.3 参考实现

本模块参考独立工具 `FunctionalTestReportGeneration`（位于 `E:/GithubData/ubains-module-test/develop/AuxiliaryTool/FunctionalTestReportGeneration/`），将其核心能力迁移至平台后端服务，并适配平台的前端交互体系。

---

## 2. 功能需求

### 2.1 功能清单

| 编号 | 功能 | 说明 | 优先级 |
|------|------|------|--------|
| F1 | Excel 上传 | 支持上传测试用例 Excel 和 BUG 列表 Excel | P0 |
| F2 | 项目配置 | 输入项目名称、选择报告格式（docx / md / both） | P0 |
| F3 | 数据分析 | 自动统计用例通过率、执行率、模块分布、BUG 等级/状态/类型分布、遗留 BUG | P0 |
| F4 | 图表生成 | 生成 4 张统计图表（BUG 等级饼图、测试结果饼图、通过率柱状图、BUG 按模块堆叠柱状图） | P0 |
| F5 | 报告生成 | 生成 Word 报告（10 章节）和/或 Markdown 报告 | P0 |
| F6 | 报告预览/下载 | 提供报告下载链接，Markdown 报告可在线预览 | P0 |
| F7 | ERP 上传 | 支持将报告上传至 ERP 测试单（Word→HTML→图片上传→创建报告），以及项目资料和协作文档 | P1 |
| F8 | ERP 配置管理 | ERP 配置（API Key、基础 URL、测试单 ID 默认值）可配置化 | P1 |

### 2.2 功能详细说明

#### F1. Excel 上传

- 支持上传**测试用例 Excel** 和 **BUG 列表 Excel** 两个文件
- 文件格式：`.xlsx`
- 文件大小限制：**10MB**
- 上传后保存到 `data/functional_report/{session_id}/` 目录
- 支持同一 session 内重新上传覆盖

#### F2. 项目配置

- **项目名称**：用户输入，用于报告标题和文件命名
- **报告格式**：下拉选择 `Word (.docx)` / `Markdown (.md)` / `两者都生成`
- 配置信息与上传的文件关联到同一 session

#### F3. 数据分析

自动分析以下指标：

**测试用例分析**：
- 总用例数 / 已执行数 / 通过数 / 失败数 / 未验证数 / 未开发数
- 通过率 = 通过数 / 已执行数
- 执行率 = 已执行数 / 总用例数
- 按模块统计（模块名 → 总数/通过/失败/未验证/未开发）

**BUG 分析**：
- BUG 总数 / 遗留数（激活+已解决）/ 已关闭数
- BUG 等级分布（1级致命 / 2级严重 / 3级一般 / 4级轻微）
- BUG 状态分布（激活 / 已解决 / 已关闭）
- BUG 类型分布
- BUG 按模块分布
- 各等级遗留 BUG 数量

**用例-BUG 关联**：
- 从 BUG 复现步骤中提取用例编号正则匹配 `[A-Z]+-\d{3,}`
- 建立用例与 BUG 的关联关系

#### F4. 图表生成

生成 4 张 matplotlib 图表（PNG 格式）：

| 图表 | 类型 | 说明 |
|------|------|------|
| 图1 | 饼图 | BUG 等级分布（1-4级，含百分比） |
| 图2 | 饼图 | 测试结果分布（通过/失败/未验证/未开发，含百分比） |
| 图3 | 柱状图 | 各模块通过率对比（柱状+百分比标签） |
| 图4 | 堆叠柱状图 | BUG 按模块分布（各等级堆叠） |

#### F5. 报告生成

**Word 报告（10 章节）**：
1. 报告基本信息（项目名称、日期、版本、测试人员等）
2. 测试执行摘要（通过率/执行率/BUG总数等关键指标）
3. 测试范围（测试模块列表、功能点）
4. 测试用例执行详情（用例执行结果表格）
5. BUG 详细列表（BUG 分类汇总表格）
6. 图表分析（插入 4 张图表图片）
7. 测试执行记录（执行时间、环境等信息）
8. 测试附件（截图、日志等）
9. 风险评估与建议（风险项及应对建议）
10. 附录（补充数据）

**Markdown 报告**：与 Word 报告内容一致，Markdown 格式渲染。

#### F6. 报告预览/下载

- 生成完成后返回报告文件路径
- 提供下载链接（`GET /api/functional-report/download/{report_id}`）
- Markdown 报告可在线预览（`GET /api/functional-report/preview/{report_id}`）

#### F7. ERP 上传

支持三种上传方式：

| 上传类型 | 目标接口 | 说明 |
|---------|---------|------|
| 测试单报告 | `/openclaw/report` | Word→HTML→图片上传→创建测试报告 |
| 项目资料 | `/openclaw/upload/project` | 报告文件上传至项目资料 |
| 协作文档 | `/openclaw/upload/cooperation` | 报告文件上传至协作文档 |

**ERP 上传流程**：
1. Word 文档 → mammoth 转为 HTML
2. HTML 中的图片提取并上传至 ERP（`/openclaw/upload/richtext`）
3. 替换图片 URL 为 ERP 地址
4. 调用 `/openclaw/report` 创建测试报告

**重试机制**：最多重试 3 次，间隔 5 秒；4xx 错误不重试。

#### F8. ERP 配置管理

| 配置项 | 环境变量 | 默认值 | 说明 |
|-------|---------|--------|------|
| ERP API Key | `ERP_API_KEY` | `9adc1ce611544fae9bbbc5f6b1d6ce87` | ERP 接口认证 |
| ERP 基础 URL | `ERP_BASE_URL` | `https://office.ubainsyun.com:5082/api/uerp` | ERP 服务地址 |
| 默认测试单 ID | `ERP_DEVELOPTESTING_ID` | `397` | 测试单编号 |
| 报告类型 ID | `ERP_TYPE_ID` | `2` | 报告类型编号 |
| 图片 URL 前缀 | `ERP_IMAGE_URL_PREFIX` | `https://office.ubainsyun.com:5015/` | 图片访问前缀 |

---

## 3. 数据格式规范

### 3.1 测试用例 Excel 格式

- **表头行**：第 3 行（前两行为空或标题）
- **数据起始行**：第 4 行
- **列定义**（17 列）：

| 列号 | 字段名 | 说明 |
|------|--------|------|
| A | 序列号 | 数字序号，为 0 时跳过该行 |
| B | 功能模块 | 所属模块名称 |
| C | 功能类别 | 功能分类 |
| D | 用例编号 | 唯一编号，如 `LOGIN-001` |
| E | 功能描述 | 功能点描述 |
| F | 用例等级 | P0/P1/P2/P3 |
| G | 功能编号 | 功能编号 |
| H | 用例名称 | 用例标题 |
| I | 预置条件 | 前置条件，可能含 IP 信息 |
| J | STEP | 测试步骤 |
| K | JSON配置 | JSON 格式配置 |
| L | 预期结果 | 期望输出 |
| M | 测试结果 | 通过/失败/未验证/未开发 |
| N | 测试频次 | 执行频次 |
| O | 日志/截图/照片 | 附件路径 |
| P | 截图二 | 附件路径 |
| Q | 备注 | 备注信息 |

### 3.2 BUG 列表 Excel 格式

- **表头行**：第 1 行
- **数据起始行**：第 2 行
- **列定义**（9 列）：

| 列号 | 字段名 | 说明 |
|------|--------|------|
| A | 项目名称 | 项目名，为空时跳过该行 |
| B | BUG类型 | 功能/界面/性能/安全等 |
| C | BUG等级 | 1级(致命)/2级(严重)/3级(一般)/4级(轻微) |
| D | BUG状态 | 激活/已解决/已关闭 |
| E | BUG名称 | BUG 标题，可能含 `【模块名】` 标记 |
| F | 提单人员 | 报告人 |
| G | 主负责人员 | 负责人 |
| H | 截止日期 | 修复期限 |
| I | 复现步骤 | 含用例编号引用 `[A-Z]+-\d{3,}` |

---

## 4. 非功能需求

| 需求 | 说明 |
|------|------|
| 验证码 | 固定 `csba`（与被测系统一致） |
| 文件大小 | Excel 上传上限 10MB |
| 存储路径 | `data/reports/functional/` 及 `data/functional_report/` |
| ERP 超时 | 请求超时 30s |
| ERP 重试 | 最多 3 次，4xx 不重试 |
| 安全 | ERP API Key 通过环境变量配置，不硬编码在代码中 |

---

## 5. 技术方案

### 5.1 架构

```
前端 FunctionalReport.vue
  ↓ POST /api/functional-report/upload (multipart/form-data)
后端 functional_report.py (router)
  ↓ 保存 Excel
后端 functional_report_service.py (核心服务)
  ↓ openpyxl 读取 Excel
  ↓ 数据分析（复用参考工具代码）
  ↓ matplotlib 生成图表
  ↓ python-docx 生成 Word / 生成 Markdown
  ↓ 返回报告文件路径
后端 erp_service.py
  ↓ mammoth Word→HTML
  ↓ 上传图片到 ERP
  ↓ 创建 ERP 测试报告
```

### 5.2 复用策略

参考工具代码直接复制到平台后端，适配 FastAPI 异步服务：

| 参考文件 | 目标位置 | 修改方式 |
|---------|---------|---------|
| `excel_reader.py` | `backend/app/services/functional/` | 直接复制，去除 CLI 依赖 |
| `data_analyzer.py` | `backend/app/services/functional/` | 直接复制 |
| `data_extractor.py` | `backend/app/services/functional/` | 直接复制 |
| `chart_generator.py` | `backend/app/services/functional/` | 直接复制，matplotlib 配置调整 |
| `word_generator.py` | `backend/app/services/functional/` | 直接复制，去除模板路径依赖 |
| `markdown_generator.py` | `backend/app/services/functional/` | 直接复制 |
| `erp_uploader.py` | `backend/app/services/erp_service.py` | 重构为类，支持异步 |
| `config.py` | `backend/app/config.py` | 合并到 Settings 类 |
| `cli.py` | `backend/app/services/functional_report_service.py` | 核心流程编排 |

---

## 6. 接口设计

### 6.1 API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/functional-report/upload` | 上传测试用例和 BUG 列表 Excel |
| POST | `/api/functional-report/generate` | 基于已上传文件生成报告 |
| GET | `/api/functional-report/download/{report_id}` | 下载报告文件 |
| GET | `/api/functional-report/preview/{report_id}` | 预览 Markdown 报告 |
| POST | `/api/functional-report/upload-to-erp` | 上传报告到 ERP |
| GET | `/api/functional-report/config` | 获取 ERP 配置 |
| PUT | `/api/functional-report/config` | 更新 ERP 配置 |

### 6.2 前端路由

| 路径 | 组件 | 说明 |
|------|------|------|
| `/reports/functional` | `FunctionalReport.vue` | 功能测试报告页面 |

---

## 7. 依赖清单

| 依赖 | 版本 | 用途 |
|------|------|------|
| `python-docx` | >=1.0.0 | 生成 Word 报告 |
| `mammoth` | >=1.8.0 | Word 转 HTML（ERP 上传） |
| `Pillow` | >=10.0.0 | 图片处理 |
| `matplotlib` | >=3.7.0 | 生成统计图表 |

---

## 8. 风险与应对

| 风险 | 影响 | 应对 |
|------|------|------|
| Excel 格式不匹配 | 数据解析失败 | 上传时做格式校验，给出明确错误提示 |
| ERP 接口不可用 | 无法上传报告 | 支持离线下载，ERP 上传失败不阻塞主流程 |
| 中文字体缺失 | 图表中文乱码 | 配置多字体回退链 |
| 大文件上传超时 | 上传失败 | 10MB 限制 + 前端上传进度提示 |