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

> **版本**: v1.0.2  
> **最后更新**: 2026-01-06  
> **编写者**: 产品团队

---

## 📋 文档说明

本文档描述用户反馈系统的典型使用场景，覆盖普通用户、区域管理员与全局管理员的核心流程与异常处理。

---

## 👥 用户角色

| 角色 | 描述 | 权限级别 |
|------|------|---------|
| 普通用户 | 提交反馈与查看自己的反馈 | 普通用户 |
| 区域管理员 | 仅管理本区域反馈 | 管理员 |
| 全局管理员 | 管理所有区域反馈 | 管理员 |

---

## 🎯 场景 1: 普通用户提交反馈

### 场景描述

**用户角色**: 普通用户  
**使用时机**: 用户遇到问题或有功能建议  
**目标**: 提交可追踪的反馈

### 前置条件

- [ ] 用户已登录
- [ ] 反馈入口可见（全局悬浮按钮）

### 正常路径

| 步骤 | 用户操作 | 系统响应 | 页面/状态 |
|------|---------|---------|----------|
| 1 | 点击悬浮反馈按钮 | 打开反馈表单弹窗 | 当前页面
| 2 | 选择类型、填写标题和内容 | 表单校验通过 | 弹窗内
| 3 |（可选）填写附件 URL | 显示填写完成 | 弹窗内
| 4 | 点击提交 | 创建反馈，状态为 PENDING | 弹窗关闭，提示成功 |

**详细说明**：

**步骤1**
- 用户点击页面右下角反馈按钮
- 系统打开提交反馈弹窗

**步骤2**
- 用户填写字段：类型、标题、内容
- 系统完成前端校验与必填提示

**步骤3**
- 用户填写附件 URL（最多 5 个）
- 系统显示填写结果

**步骤4**
- 系统调用 `POST /feedbacks`
- 成功后弹出“反馈提交成功”提示

### 异常路径

#### 异常 1.1: 必填字段为空

**触发条件**: 未填写类型/标题/内容

| 步骤 | 用户操作 | 系统响应 | 错误处理 |
|------|---------|---------|---------|
| 2 | 点击提交 | 表单验证失败 | 高亮错误字段并提示 |

**恢复步骤**: 用户补齐字段后重新提交

---

#### 异常 1.2: 附件数量超限

**触发条件**: 提交超过 5 个附件 URL

**系统行为**: 拒绝提交并提示错误

**用户反馈**: 显示“附件数量超限”

### 后置条件

- ✅ 反馈记录已创建
- ✅ 状态为 `PENDING`
- ✅ 反馈 region 继承用户 metadata.region

### 业务规则

1. 反馈标题 1-200 字符，内容 1-5000 字符
2. 附件仅校验 URL 格式与数量
3. 创建时默认状态为 `PENDING`

---

## 🎯 场景 2: 普通用户查看“我的反馈”

### 场景描述

**用户角色**: 普通用户  
**使用时机**: 用户想查看自己反馈的处理进度  
**目标**: 查看列表与详情

### 前置条件

- [ ] 用户已登录
- [ ] 用户有提交过的反馈

### 正常路径

| 步骤 | 用户操作 | 系统响应 | 页面/状态 |
|------|---------|---------|----------|
| 1 | 进入“我的反馈”页面 | 加载反馈列表 | /feedback
| 2 | 点击某条反馈 | 展示反馈详情 | /feedback/:id（或弹窗） |

### 异常路径

#### 异常 2.1: 列表为空

**触发条件**: 用户未提交过反馈

**系统行为**: 返回空列表

**用户反馈**: 显示空状态提示

### 后置条件

- ✅ 列表仅包含当前用户反馈
- ✅ 详情不展示管理员内部备注

### 业务规则

1. 普通用户只可访问自己的反馈
2. 详情可见管理员回复（若有）

---

## 🎯 场景 3: 管理员处理反馈

### 场景描述

**用户角色**: 区域管理员 / 全局管理员  
**使用时机**: 管理员进入反馈管理处理问题  
**目标**: 更新状态并添加备注/回复

### 前置条件

- [ ] 管理员已登录
- [ ] 具备 `feedback:read` 与 `feedback:update` 权限

### 正常路径

| 步骤 | 用户操作 | 系统响应 | 页面/状态 |
|------|---------|---------|----------|
| 1 | 打开反馈管理列表 | 列表加载完成 | /settings/feedback
| 2 | 进入反馈详情 | 展示完整内容与上下文 | /settings/feedback/:id
| 3 | 修改状态或添加备注/回复 | 更新成功 | 状态刷新 |

### 异常路径

#### 异常 3.1: 非法状态流转

**触发条件**: 试图执行不允许的状态变更（如 PENDING → RESOLVED）

**系统行为**: 返回 `FEEDBACK_INVALID_STATUS_TRANSITION`

**用户反馈**: 显示“无效的状态变更”

---

#### 异常 3.2: 区域越权

**触发条件**: 区域管理员尝试查看其他区域反馈

**系统行为**: 返回 `FEEDBACK_ACCESS_DENIED`

**用户反馈**: 显示权限不足提示

### 后置条件

- ✅ 反馈状态按状态机规则更新
- ✅ 变更记录写入审计日志（如启用）

### 业务规则

1. 区域管理员仅可处理本区域反馈
2. 全局管理员可跨区域处理
3. 更新为 `RESOLVED` 时设置 `resolvedAt`

---

## 🎯 场景 4: 管理员批量关闭反馈

### 场景描述

**用户角色**: 管理员  
**使用时机**: 批量关闭重复或无效反馈  
**目标**: 批量更新状态

### 前置条件

- [ ] 管理员已登录
- [ ] 拥有 `feedback:update` 权限
- [ ] 已选择多条反馈

### 正常路径

| 步骤 | 用户操作 | 系统响应 | 页面/状态 |
|------|---------|---------|----------|
| 1 | 勾选多条反馈 | 记录勾选状态 | 列表页
| 2 | 选择批量关闭 | 调用批量状态接口 | 列表页
| 3 | 确认操作 | 批量更新结果返回 | 列表刷新 |

### 异常路径

#### 异常 4.1: 批量数量超限

**触发条件**: 选择超过 100 条记录

**系统行为**: 返回 `FEEDBACK_BATCH_LIMIT_EXCEEDED`

**用户反馈**: 提示“批量操作数量超过限制”

### 后置条件

- ✅ 合法记录状态更新为 `CLOSED`
- ✅ 返回失败记录与原因

---

## 📊 场景关系图

### 场景流程图

```mermaid
graph TD
    A[用户提交反馈] --> B[我的反馈列表]
    B --> C[查看反馈详情]
    A --> D[管理员列表]
    D --> E[管理员详情]
    E --> F{处理动作}
    F -->|更新状态| G[状态变更]
    F -->|添加回复| H[用户可见回复]
    D --> I[批量关闭]
```

### 场景依赖关系

| 场景 | 依赖场景 | 说明 |
|------|---------|------|
| 场景2 | 场景1 | 必须先提交才有“我的反馈”记录 |
| 场景3 | 场景1 | 管理员需要有用户提交的反馈 |
| 场景4 | 场景3 | 批量操作基于管理列表 |

---

## 🔗 与功能的对应关系

### 场景 → 功能映射

| 场景 | 涉及功能 | 相关页面 | API 接口 |
|------|---------|---------|---------|
| 场景1: 提交反馈 | 反馈创建、附件 URL | 任意页面（弹窗） | `POST /feedbacks` |
| 场景2: 我的反馈 | 列表与详情 | `/feedback` | `GET /feedbacks/my`、`GET /feedbacks/my/:id` |
| 场景3: 管理处理 | 列表、详情、状态管理 | `/settings/feedback` | `GET /feedbacks`、`PATCH /feedbacks/:id`、`PATCH /feedbacks/:id/status` |
| 场景4: 批量关闭 | 批量状态变更 | `/settings/feedback` | `POST /feedbacks/batch-status` |

### 功能 → 场景映射

| 功能点 | 使用场景 | 优先级 |
|--------|---------|--------|
| 反馈提交 | 场景1 | P0 |
| 我的反馈 | 场景2 | P0 |
| 反馈管理 | 场景3 | P0 |
| 批量操作 | 场景4 | P2 |

---

## 🎭 角色 × 场景矩阵

| 场景 | 普通用户 | 区域管理员 | 全局管理员 | 说明 |
|------|---------|-----------|-----------|------|
| 场景1: 提交反馈 | ✅ | ✅ | ✅ | 所有人可提交 |
| 场景2: 我的反馈 | ✅ 仅自己 | ✅ 仅自己 | ✅ 仅自己 | 仅个人反馈 |
| 场景3: 管理处理 | ❌ | ✅ 仅本区域 | ✅ 全部 | 权限区分 |
| 场景4: 批量关闭 | ❌ | ✅ 仅本区域 | ✅ 全部 | 权限区分 |

---

## 📊 使用频率预估

| 场景 | 使用频率 | 用户数量 | 备注 |
|------|---------|---------|------|
| 场景1 | 每天 50-200 次 | 所有员工 | 高峰期集中提交 |
| 场景2 | 每天 30-100 次 | 提交用户 | 查询进度 |
| 场景3 | 每天 10-50 次 | 管理员 | 集中处理 |
| 场景4 | 每周 1-5 次 | 管理员 | 批量关闭 |

---

## ⚠️ 边界情况

### 边界情况 1: 用户没有 metadata.region

**场景**: 新用户未配置 metadata.region

**用户行为**: 提交反馈

**系统处理**: 默认 region = `CN`

**预期结果**: 反馈可正常创建

---

### 边界情况 2: 已关闭反馈被重新打开

**场景**: 管理员重新激活 CLOSED 反馈

**用户行为**: 状态修改为 PENDING

**系统处理**: 允许流转并清空 `resolvedAt`

**预期结果**: 反馈重新进入待处理

---

## 💡 用户体验优化建议

### 优化点 1: 自动补全上下文

**当前问题**: 用户手工描述上下文成本高

**改进方案**: 自动附带 `pageUrl` 和 `userAgent`

**预期效果**: 提高问题定位效率

---

### 优化点 2: 我的反馈入口更明显

**当前问题**: 用户可能不知道在哪里查看处理进度

**改进方案**: 在反馈弹窗中增加“查看我的反馈”链接

**预期效果**: 降低用户查找成本

---

## 🔗 相关文档

- [产品需求文档](./01-prd.md) - 业务背景和功能需求
- [UI 交互规范](./05-ui-interaction-spec.md) - 界面交互细节
- [API 文档](./07-api.md) - 接口定义
- [测试场景](./09-test-scenarios.md) - 测试用例

---

## 📝 变更记录

| 版本 | 日期 | 修改人 | 修改内容 |
|------|------|--------|---------|
| v1.0.2 | 2026-01-06 | 产品团队 | 文档统一与完善 |
| v1.0 | 2025-12-08 | 产品团队 | 初始版本 |

---

**最后更新**: 2026-01-06  
**编写者**: 产品团队