# 用户反馈系统 - 测试场景文档

> **版本**: v1.0.3  
> **最后更新**: 2026-01-07  
> **维护者**: 测试团队

---

## 📋 测试概述

### 测试范围

覆盖反馈提交、我的反馈、管理员管理、状态流转、区域权限与附件校验。

### 测试类型

- ✅ 单元测试（Unit Test）
- ✅ 集成测试（Integration Test）
- ✅ E2E 测试（End-to-End Test）

**说明**：E2E 用例由 Agent + Playwright MCP 执行，详见 `10-e2e-test-spec.md`。

### 覆盖率目标

| 测试类型 | 目标覆盖率 | 当前覆盖率 |
|---------|-----------|-----------|
| 单元测试 | 80%+ | 待补充 |
| 集成测试 | 60%+ | 待补充 |
| E2E 测试 | 关键流程 | 待补充 |

---

## ✅ 功能测试场景

### 场景 1: 用户提交反馈（正常流程）

**优先级**: P0  
**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录（使用 `storageState`）
- [ ] 进入任意页面

**测试步骤**:
1. 点击悬浮反馈按钮
2. 选择类型、填写标题与内容
3. 点击提交

**预期结果**:
- [ ] 到达断言：反馈弹窗可见
- [ ] 成功断言：出现“反馈提交成功”提示
- [ ] 弹窗关闭且无表单错误

---

### 场景 2: 用户查看我的反馈列表

**优先级**: P0  
**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录
- [ ] 已存在该用户反馈

**测试步骤**:
1. 访问 `/feedback`
2. 等待列表加载

**预期结果**:
- [ ] 到达断言：`/feedback` 页面加载完成
- [ ] 稳定断言：列表渲染完成（表格或空状态）

---

### 场景 2.1: 我的反馈列表为空

**优先级**: P1  
**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录
- [ ] 用户未提交过反馈

**测试步骤**:
1. 访问 `/feedback`
2. 等待列表加载

**预期结果**:
- [ ] 到达断言：页面标题可见
- [ ] 稳定断言：显示空状态提示

---

### 场景 2.2: 我的反馈筛选（状态）

**优先级**: P1  
**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录
- [ ] 存在多状态反馈

**测试步骤**:
1. 访问 `/feedback`
2. 选择 `select[name="status"]` 为 `PENDING`

**预期结果**:
- [ ] 到达断言：页面仍在 `/feedback`
- [ ] 稳定断言：列表状态仅为 `PENDING`

---

### 场景 2.3: 我的反馈筛选（类型）

**优先级**: P1  
**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录
- [ ] 存在多类型反馈

**测试步骤**:
1. 访问 `/feedback`
2. 选择 `select[name="type"]` 为 `BUG`

**预期结果**:
- [ ] 到达断言：页面仍在 `/feedback`
- [ ] 稳定断言：列表类型仅为 `BUG`

---

### 场景 2.4: 查看我的反馈详情

**优先级**: P0  
**测试类型**: E2E

**前置条件**:
- [ ] 用户已登录
- [ ] 存在反馈记录

**测试步骤**:
1. 进入 `/feedback`
2. 点击“查看详情”

**预期结果**:
- [ ] 到达断言：详情页或弹窗可见
- [ ] 成功/稳定断言：不展示管理员内部备注

---

### 场景 3: 管理员更新反馈状态

**优先级**: P0  
**测试类型**: Integration

**前置条件**:
- [ ] 反馈状态为 `PENDING`
- [ ] 管理员具备 `feedback:update`

**测试步骤**:
1. `PATCH /feedbacks/:id/status`，传入 `IN_PROGRESS`

**预期结果**:
- [ ] 状态更新为 `IN_PROGRESS`
- [ ] 返回 200

---

### 场景 3.1: 管理端列表加载

**优先级**: P0  
**测试类型**: E2E

**前置条件**:
- [ ] 管理员已登录
- [ ] 具备 `feedback:read` 权限

**测试步骤**:
1. 访问 `/settings/feedback`
2. 等待列表加载

**预期结果**:
- [ ] 到达断言：页面标题可见
- [ ] 稳定断言：表格或空状态渲染完成

---

### 场景 3.2: 管理端详情加载

**优先级**: P1  
**测试类型**: E2E

**前置条件**:
- [ ] 管理员已登录
- [ ] 存在反馈记录

**测试步骤**:
1. 访问 `/settings/feedback/:id`
2. 等待详情加载

**预期结果**:
- [ ] 到达断言：URL 正确
- [ ] 稳定断言：详情字段渲染完成

---

### 场景 3.3: 管理端批量关闭（<=100）

**优先级**: P1  
**测试类型**: E2E / Integration

**前置条件**:
- [ ] 管理员已登录
- [ ] 可选中多条反馈

**测试步骤**:
1. 在列表中选择多条记录
2. 点击批量关闭

**预期结果**:
- [ ] 成功提示展示
- [ ] 状态变更为 `CLOSED`

---

### 场景 3.4: 管理端批量关闭超限（>100）

**优先级**: P1  
**测试类型**: E2E / Integration

**前置条件**:
- [ ] 管理员已登录
- [ ] 可选择 101 条记录

**测试步骤**:
1. 选择 101 条记录
2. 触发批量关闭

**预期结果**:
- [ ] 前端阻止提交并提示数量超限
- [ ] 返回 `FEEDBACK_BATCH_LIMIT_EXCEEDED`（集成层验证）

---

### 场景 4: 管理员更新反馈信息

**优先级**: P1  
**测试类型**: Integration

**前置条件**:
- [ ] 反馈存在
- [ ] 管理员具备 `feedback:update`

**测试步骤**:
1. `PATCH /feedbacks/:id` 更新 `adminNote`、`adminReply`

**预期结果**:
- [ ] 返回 200
- [ ] 字段更新成功

---

## ❌ 异常测试场景

### 场景 E1: 非法状态流转

**优先级**: P0  
**测试类型**: Unit / Integration

**前置条件**:
- [ ] 反馈状态为 `PENDING`

**测试步骤**:
1. `PATCH /feedbacks/:id/status`，传入 `RESOLVED`

**预期结果**:
- [ ] 返回 400
- [ ] 错误码 `FEEDBACK_INVALID_STATUS_TRANSITION`

---

### 场景 E2: 附件数量超限（URL）

**优先级**: P0  
**测试类型**: Unit / Integration

**测试步骤**:
1. 创建反馈时传入超过 5 个附件 URL

**预期结果**:
- [ ] 返回 400
- [ ] 错误码 `FEEDBACK_ATTACHMENTS_EXCEED_LIMIT`

---

### 场景 E3: 无权限访问

**优先级**: P0  
**测试类型**: Integration / E2E

**前置条件**:
- [ ] 普通用户登录

**测试步骤**:
1. 访问 `GET /feedbacks`

**预期结果**:
- [ ] 返回 403
- [ ] 错误码 `FEEDBACK_ACCESS_DENIED`

---

### 场景 E4: 反馈不存在

**优先级**: P1  
**测试类型**: Integration / E2E

**前置条件**:
- [ ] 使用不存在的反馈 ID

**测试步骤**:
1. 访问 `GET /feedbacks/:id`

**预期结果**:
- [ ] 返回 404
- [ ] 错误码 `FEEDBACK_NOT_FOUND`

---

## 🔐 权限测试场景

### 场景 P1: 区域管理员数据范围

**优先级**: P0  
**测试类型**: Integration

**前置条件**:
- [ ] 用户角色为 `FEEDBACK_ADMIN_CN`

**测试步骤**:
1. 访问 `GET /feedbacks`

**预期结果**:
- [ ] 返回数据全部为 `region = CN`

---

## 🔄 状态流转测试场景

### 场景 S1: 正常状态流转

**优先级**: P0  
**测试类型**: Integration

**前置条件**:
- [ ] 反馈状态为 `PENDING`

**测试步骤**:
1. `PENDING -> IN_PROGRESS`
2. `IN_PROGRESS -> RESOLVED`

**预期结果**:
- [ ] 状态按顺序更新
- [ ] `resolvedAt` 在 RESOLVED 时被设置

---

### 场景 S2: 关闭后重新激活

**优先级**: P1  
**测试类型**: Integration

**前置条件**:
- [ ] 反馈状态为 `CLOSED`

**测试步骤**:
1. `CLOSED -> PENDING`

**预期结果**:
- [ ] 状态更新为 `PENDING`
- [ ] `resolvedAt` 为空

---

## 🎨 前端交互测试场景

### 场景 UI1: 反馈弹窗校验

**优先级**: P0  
**测试类型**: E2E

**测试步骤**:
1. 打开反馈弹窗
2. 不填写必填项直接提交

**预期结果**:
- [ ] 到达断言：弹窗仍然可见
- [ ] 成功/稳定断言：出现字段校验提示

---

### 场景 UI2: 管理员详情页加载

**优先级**: P1  
**测试类型**: E2E

**测试步骤**:
1. 访问 `/settings/feedback/:id`
2. 等待页面加载

**预期结果**:
- [ ] 到达断言：URL 正确
- [ ] 稳定断言：详情字段渲染完成

---

### 场景 UI3: 反馈弹窗附件上限提示

**优先级**: P1  
**测试类型**: E2E

**测试步骤**:
1. 打开反馈弹窗
2. 输入 6 个附件 URL
3. 点击提交

**预期结果**:
- [ ] 到达断言：弹窗仍然可见
- [ ] 成功/稳定断言：提示“附件数量超限”

---

### 场景 UI4: 管理端筛选（状态/类型/区域）

**优先级**: P1  
**测试类型**: E2E

**前置条件**:
- [ ] 管理员已登录
- [ ] 存在多状态、多类型、多区域数据

**测试步骤**:
1. 在 `/settings/feedback` 分别选择状态/类型/区域筛选

**预期结果**:
- [ ] 到达断言：页面仍在管理端列表
- [ ] 稳定断言：列表结果与筛选条件一致

---

## 🌐 集成测试场景

### 场景 I1: API 全链路

**优先级**: P0  
**测试类型**: Integration

**测试步骤**:
1. 创建：`POST /feedbacks`
2. 查询：`GET /feedbacks/my`
3. 管理查询：`GET /feedbacks`
4. 更新：`PATCH /feedbacks/:id`
5. 状态更新：`PATCH /feedbacks/:id/status`
6. 删除：`DELETE /feedbacks/:id`

**预期结果**:
- [ ] 接口返回符合 API 文档
- [ ] 软删除后列表不可见

---

### 场景 I2: 批量状态更新（<=100）

**优先级**: P1  
**测试类型**: Integration

**测试步骤**:
1. `POST /feedbacks/batch-status`，传入 <=100 条

**预期结果**:
- [ ] 返回成功统计
- [ ] 状态更新正确

---

### 场景 I3: 批量状态更新超限

**优先级**: P1  
**测试类型**: Integration

**测试步骤**:
1. `POST /feedbacks/batch-status`，传入 >100 条

**预期结果**:
- [ ] 返回 400
- [ ] 错误码 `FEEDBACK_BATCH_LIMIT_EXCEEDED`

---

### 场景 I4: 区域管理员数据范围

**优先级**: P0  
**测试类型**: Integration

**测试步骤**:
1. 使用 `FEEDBACK_ADMIN_CN` 访问 `GET /feedbacks`

**预期结果**:
- [ ] 返回数据 `region = CN`

---

### 场景 I5: 普通用户访问管理端列表

**优先级**: P0  
**测试类型**: Integration

**测试步骤**:
1. 普通用户访问 `GET /feedbacks`

**预期结果**:
- [ ] 返回 403
- [ ] 错误码 `FEEDBACK_ACCESS_DENIED`

---

## 📊 测试覆盖矩阵

| 功能 | 单元测试 | 集成测试 | E2E测试 | 状态 |
|------|---------|---------|---------|------|
| 创建反馈 | ✅ | ✅ | ✅ | 待实施 |
| 我的反馈 | ✅ | ✅ | ✅ | 待实施 |
| 管理列表 | ✅ | ✅ | ✅ | 待实施 |
| 状态流转 | ✅ | ✅ | 🚧 | 待实施 |
| 附件校验 | ✅ | ✅ | ✅ | 待实施 |
| 区域权限 | ✅ | ✅ | ✅ | 待实施 |

---

## 🔗 相关文档

- [产品需求](./01-prd.md)
- [UI 交互规范](./05-ui-interaction-spec.md)
- [API 文档](./07-api.md)
- [状态机](./04-state-machine.md)
- [错误码](./08-error-codes.md)
- [E2E 测试规范](./10-e2e-test-spec.md)

---

**最后更新**: 2026-01-07  
**版本**: v1.0.3  
**维护者**: 测试团队