---
url: /docs/api-docs/v1/admin/reviews.md
---
# review — 评价审核（5 action）

> 前缀：`/api/v1/admin/review/`
> 权限：`REVIEW_READ`（list/detail）· `REVIEW_APPROVE`（approve/reject/handle-appeal）— 仅 **super + operator**，it 一律 403
> 代码：`src/app/admin/interface/api/review_mgmt.py` + `application/usecase/review_mgmt.py`
> ⚠️ 与 [content](/api-docs/v1/admin/content) 的 `moderate-comment`（CONTENT\_REVIEW — 评论区）区分：本模块审的是**评价**（rating + body）

## 3.7.1 list —— 评价列表

`GET /api/v1/admin/review/list` · 权限 `REVIEW_READ`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | ⬜ | 1 | ≥1 |
| `page_size` | int | ⬜ | 20 | 1~100 |
| `status` | string | ⬜ | — | `pending` | `approved` | `rejected` | `appealed` |
| `rating` | int | ⬜ | — | 1~5 星级过滤 |
| `keyword` | string | ⬜ | — | 内容子串 |

**响应 data**：`{ total, page, page_size, items: [ReviewSummary] }`

`ReviewSummary` 字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` / `user_id` / `target_content_id` | string | 评价 / 用户 / 目标内容 |
| `rating` | int | 1~5 |
| `body` | string | 评价正文 |
| `status` | string | 状态 |
| `reject_reason` | string | null | 拒绝原因 |
| `created_at` / `updated_at` | string | ISO |

**错误码**：`40201001` page/page\_size < 1 / rating 越界。

## 3.7.2 detail —— 评价详情

`GET /api/v1/admin/review/detail/{review_id}` · 权限 `REVIEW_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `review` | object | 全字段（+ `appeal_requested_at` / `appeal_decided_at`） |
| `target_content` | object | `{content_id, title, type, status}` |
| `replies` | array | 回复/追评 |

**错误码**：`40201501`（404）评价不存在（与 LOGIN\_FAILED 同码 Enum 别名 — 本路径下语义为 NOT\_FOUND）。

## 3.7.3 approve —— 通过

`POST /api/v1/admin/review/approve` · 权限 `REVIEW_APPROVE`

**请求 body**：`{ review_id✅, note? }`

**响应 data**：`{ "success": true }`

**错误码**：`40201501`（404）· `40201502` 已审核（重复操作）。

## 3.7.4 reject —— 拒绝

`POST /api/v1/admin/review/reject` · 权限 `REVIEW_APPROVE`

**请求 body**：`{ review_id✅, reason✅, note? }`

**响应 data**：`{ "success": true }`

**错误码**：`40201501`（404）· `40201502` 已审核 · `40201001` reason 缺失。

## 3.7.5 handle-appeal —— 处理申诉

`POST /api/v1/admin/review/handle-appeal` · 权限 `REVIEW_APPROVE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `review_id` | string | ✅ | 目标评价（已被 reject 且用户申诉） |
| `decision` | string | ✅ | 申诉裁定（如 uphold 维持 / overturn 推翻） |
| `reason` | string | ✅ | 裁定说明 |

**响应 data**：`{ "success": true }`

**错误码**：

| code | 场景 |
|---|---|
| `40201501` | 评价不存在（404） |
| `40201503` | 申诉已处理（重复） |
| `40201504` | 申诉处理超时（需重新提交） |
| `40201001` | decision 非法 |

***

**本域错误码汇总**：`40201501`-`40201504`（§6.7）。通用失败见 [admin 总览](/api-docs/v1/admin/)。