# 用户反馈系统 - 状态机文档

> **版本**: v1.0.2  
> **最后更新**: 2026-01-06  
> **维护者**: 后端团队

---

## 📋 概述

### 状态机用途

用于管理反馈记录的生命周期状态，确保状态流转符合业务规则。

### 核心对象

- **对象类型**: 用户反馈（Feedback）
- **状态字段**: `status`
- **数据库表**: `platform_feedback.feedbacks`

---

## 🎯 状态定义

### 所有状态列表

| 状态代码 | 状态名称 | 中文名 | 说明 | 终态 |
|---------|---------|--------|------|-----|
| `PENDING` | Pending | 待处理 | 新提交，等待处理 | ❌ |
| `IN_PROGRESS` | In Progress | 处理中 | 已开始处理 | ❌ |
| `RESOLVED` | Resolved | 已解决 | 问题已解决/建议采纳 | ❌ |
| `CLOSED` | Closed | 已关闭 | 不处理/无效/重复 | ❌ |

**说明**：
- 反馈可被重新激活，因此不设置终态。

---

## 🔄 状态流转图

### Mermaid 图表

```mermaid
stateDiagram-v2
    [*] --> PENDING: 创建

    PENDING --> IN_PROGRESS: 开始处理
    PENDING --> CLOSED: 关闭

    IN_PROGRESS --> RESOLVED: 解决
    IN_PROGRESS --> CLOSED: 关闭
    IN_PROGRESS --> PENDING: 退回待处理

    RESOLVED --> IN_PROGRESS: 重新打开
    RESOLVED --> CLOSED: 关闭

    CLOSED --> PENDING: 重新激活
```

---

## ✅ 合法状态流转

### 流转规则表

| 当前状态 | 可流转到 | 触发动作 | 执行者 | 前置条件 |
|---------|---------|---------|--------|---------|
| `PENDING` | `IN_PROGRESS` | 开始处理 | 管理员 | 具备 `feedback:update` 权限 |
| `PENDING` | `CLOSED` | 关闭 | 管理员 | 具备 `feedback:update` 权限 |
| `IN_PROGRESS` | `RESOLVED` | 标记已解决 | 管理员 | 具备 `feedback:update` 权限 |
| `IN_PROGRESS` | `CLOSED` | 关闭 | 管理员 | 具备 `feedback:update` 权限 |
| `IN_PROGRESS` | `PENDING` | 退回待处理 | 管理员 | 具备 `feedback:update` 权限 |
| `RESOLVED` | `IN_PROGRESS` | 重新打开 | 管理员 | 具备 `feedback:update` 权限 |
| `RESOLVED` | `CLOSED` | 关闭 | 管理员 | 具备 `feedback:update` 权限 |
| `CLOSED` | `PENDING` | 重新激活 | 管理员 | 具备 `feedback:update` 权限 |

### 详细流转逻辑

#### PENDING → IN_PROGRESS（开始处理）

**前置条件**：
- [ ] 管理员权限校验通过

**触发者**: 管理员

**后置动作**：
1. 更新 `status = IN_PROGRESS`
2. 记录审计日志（如启用）

**API**: `PATCH /feedbacks/:id/status`

---

#### IN_PROGRESS → RESOLVED（标记已解决）

**前置条件**：
- [ ] 管理员权限校验通过

**触发者**: 管理员

**后置动作**：
1. 更新 `status = RESOLVED`
2. 设置 `resolvedAt = now()`

**API**: `PATCH /feedbacks/:id/status`

---

#### CLOSED → PENDING（重新激活）

**前置条件**：
- [ ] 管理员权限校验通过

**触发者**: 管理员

**后置动作**：
1. 更新 `status = PENDING`
2. 清空 `resolvedAt`

**API**: `PATCH /feedbacks/:id/status`

---

## ❌ 非法状态流转

### 禁止的流转

除合法流转表以外的任意状态变更均视为非法。

### 错误处理

**HTTP 状态码**: 400 Bad Request

**错误响应**:
```json
{
  "success": false,
  "error": {
    "code": "FEEDBACK_INVALID_STATUS_TRANSITION",
    "message": "无效的状态变更",
    "details": {
      "currentStatus": "PENDING",
      "targetStatus": "RESOLVED",
      "allowedTransitions": ["IN_PROGRESS", "CLOSED"]
    }
  }
}
```

---

## 👥 角色与状态的关系

### 角色权限矩阵

| 状态 | 普通用户 | 区域管理员 | 全局管理员 | 说明 |
|------|---------|-----------|-----------|------|
| `PENDING` | 仅查看自己 | ✅ | ✅ | 可处理 |
| `IN_PROGRESS` | 仅查看自己 | ✅ | ✅ | 可处理 |
| `RESOLVED` | 仅查看自己 | ✅ | ✅ | 可处理 |
| `CLOSED` | 仅查看自己 | ✅ | ✅ | 可处理 |

---

## 🎨 前端展示规则

### 状态徽章样式

| 状态 | 颜色 | 说明 |
|------|------|------|
| `PENDING` | `#f59e0b` | 待处理提示 |
| `IN_PROGRESS` | `#3b82f6` | 处理中 |
| `RESOLVED` | `#10b981` | 已解决 |
| `CLOSED` | `#ef4444` | 已关闭 |

### 按钮显示规则（管理端）

| 当前状态 | 允许操作 |
|---------|---------|
| `PENDING` | 开始处理、关闭 |
| `IN_PROGRESS` | 标记已解决、关闭、退回待处理 |
| `RESOLVED` | 重新打开、关闭 |
| `CLOSED` | 重新激活 |

---

## 🔌 API 影响

### 状态相关 API

| API | 方法 | 说明 | 状态变更 |
|-----|------|------|---------|
| `/feedbacks/:id/status` | PATCH | 更新状态 | 按状态机流转 |

---

## 🧪 测试要点

- [ ] 覆盖所有合法流转
- [ ] 覆盖所有非法流转（返回 `FEEDBACK_INVALID_STATUS_TRANSITION`）
- [ ] 校验 `resolvedAt` 自动设置与清空逻辑
- [ ] 校验区域权限限制

---

## 🔗 相关文档

- [产品需求文档](./01-prd.md) - 业务背景
- [API 文档](./07-api.md) - 状态相关 API
- [UI 交互规范](./05-ui-interaction-spec.md) - 前端展示规则
- [测试场景](./09-test-scenarios.md) - 状态流转测试

---

**最后更新**: 2026-01-06  
**版本**: v1.0.2  
**维护者**: 后端团队