# 用户反馈系统 - 错误码文档

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

---

## 📋 概述

本文档定义用户反馈模块的业务错误码及前端处理建议。错误码与 API 文档保持一致。

### 错误码规范

- **命名空间**: `FEEDBACK_` 前缀
- **格式**: `FEEDBACK_{RESOURCE}_{ERROR_TYPE}`
- **HTTP 状态码**: 遵循 RESTful 标准

---

## 🎯 错误码分类

| 分类 | HTTP 状态码 | 说明 |
|------|-----------|------|
| **验证错误** | 400 | 请求参数校验失败 |
| **权限错误** | 403 | 无权限或区域不匹配 |
| **资源错误** | 404 | 反馈或关联资源不存在 |
| **业务错误** | 400 | 业务规则不满足 |

---

## ❌ 错误码清单

### 验证错误（400）

| 错误码 | 错误信息 | 场景 | 前端处理 |
|--------|---------|------|---------|
| `VALIDATION_ERROR` | 请求参数验证失败 | 通用字段校验 | 高亮错误字段并提示 |
| `FEEDBACK_ATTACHMENTS_EXCEED_LIMIT` | 附件数量超限 | 超过 5 个 | 提示数量限制 |
| `FEEDBACK_BATCH_LIMIT_EXCEEDED` | 批量数量超限 | 批量超过 100 条 | 限制勾选数量 |

---

### 权限错误（403）

| 错误码 | 错误信息 | 场景 | 前端处理 |
|--------|---------|------|---------|
| `FEEDBACK_ACCESS_DENIED` | 无权操作该反馈 | 区域不匹配或非本人 | 提示权限不足，隐藏操作 |

---

### 资源错误（404）

| 错误码 | 错误信息 | 场景 | 前端处理 |
|--------|---------|------|---------|
| `FEEDBACK_NOT_FOUND` | 反馈不存在 | 反馈被删除或不存在 | 提示“反馈不存在”并返回列表 |
| `USER_NOT_FOUND` | 用户不存在 | 指派处理人不存在 | 提示“用户不存在” |

---

### 业务错误（400）

| 错误码 | 错误信息 | 场景 | 前端处理 |
|--------|---------|------|---------|
| `FEEDBACK_INVALID_STATUS_TRANSITION` | 无效的状态变更 | 状态流转不合法 | 显示允许的状态变更 |

---

## 🎨 前端错误处理建议

```typescript
function handleFeedbackError(error: ApiClientError) {
  const { code } = error;

  if (code === 'FEEDBACK_NOT_FOUND') {
    showToast('error', '反馈不存在');
    router.push('/settings/feedback');
    return;
  }

  if (code === 'FEEDBACK_ACCESS_DENIED') {
    showToast('error', '您无权操作该反馈');
    return;
  }

  if (code === 'FEEDBACK_INVALID_STATUS_TRANSITION') {
    showToast('error', '无效的状态变更');
    return;
  }

  showToast('error', error.message || '请求失败');
}
```

---

## 🔗 相关文档

- [API 文档](./07-api.md)
- [状态机](./04-state-machine.md)
- [测试场景](./09-test-scenarios.md)

---

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