---
url: /docs/api-docs/v1/admin/content.md
---
# content — 内容管理（8 action）

> 前缀：`/api/v1/admin/content/`
> 权限：`CONTENT_READ`（list/detail）· `CONTENT_WRITE`（publish/unpublish/feature/tag/categorize）· `CONTENT_REVIEW`（moderate-comment）— 仅 **super + operator**，it 一律 403
> 代码：`src/app/admin/interface/api/content_mgmt.py` + `application/usecase/content_mgmt.py`

## 3.4.1 list —— 内容列表

`GET /api/v1/admin/content/list` · 权限 `CONTENT_READ`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | ⬜ | 1 | ≥1 |
| `page_size` | int | ⬜ | 20 | 1~100 |
| `type` | string | ⬜ | — | 内容类型过滤 |
| `status` | string | ⬜ | — | 状态过滤 |
| `keyword` | string | ⬜ | — | 标题子串 |

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

`ContentSummary` 字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 内容 id |
| `title` | string | 标题 |
| `type` | string | 类型 |
| `status` | string | `draft` | `published` | `unpublished` | `featured` |
| `category_id` | string | null | 分类 |
| `tags` | string\[] | 标签 |
| `featured_position` | string | null | 推荐位 |
| `view_count` / `comment_count` | int | 计数 |
| `published_at` | string | null | ISO |
| `created_at` | string | ISO |

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

## 3.4.2 detail —— 内容详情

`GET /api/v1/admin/content/detail/{content_id}` · 权限 `CONTENT_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `content` | object | 全字段（正文 + `author_id` / `featured_expires_at` / `scheduled_at` / `unpublished_reason` / `like_count` / `updated_at`） |
| `stats` | object | `{view_count, like_count, comment_count}` |
| `comments_summary` | object | `{total, by_status: {pending, approved, rejected, hidden}}` |

**错误码**：`40201201`（404）内容不存在。

## 3.4.3 publish —— 上架

`POST /api/v1/admin/content/publish` · 权限 `CONTENT_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `content_id` | string | ✅ | 目标内容 |
| `scheduled_at` | string | null | ⬜ | 定时上架时间（ISO；缺省立即） |

**响应 data**：`{ "success": true, "published_at": "<ISO>" }`

**错误码**：`40201201`（404）· `40201202` 重复上架 · `40201001` 参数非法。

## 3.4.4 unpublish —— 下架

`POST /api/v1/admin/content/unpublish` · 权限 `CONTENT_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `content_id` | string | ✅ | — | 目标内容 |
| `reason` | string | ✅ | — | 下架原因 |
| `force` | bool | ⬜ | false | 有关联评论（`40201204`）时强制下架 |

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

**错误码**：

| code | 场景 |
|---|---|
| `40201201` | 内容不存在（404） |
| `40201203` | 未上架（下架前未 published） |
| `40201204` | 有关联评论（级联提示；`force=true` 可越） |
| `40201001` | reason 缺失 |

## 3.4.5 feature —— 推荐位

`POST /api/v1/admin/content/feature` · 权限 `CONTENT_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `content_id` | string | ✅ | 目标内容 |
| `position` | string | ✅ | 推荐位标识 |
| `expires_at` | string | ✅ | 推荐过期时间（ISO） |

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

**错误码**：`40201201`（404）· `40201203` 未上架 · `40201205` 重复置顶（推荐位未过期）· `40201001` 参数非法。

## 3.4.6 tag —— 标签增删

`POST /api/v1/admin/content/tag` · 权限 `CONTENT_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `content_id` | string | ✅ | 目标内容 |
| `add_tags` | string\[] | ⬜ | 新增标签（缺省 `[]`） |
| `remove_tags` | string\[] | ⬜ | 移除标签（缺省 `[]`） |

**响应 data**：`{ "success": true, "tags": [ ...最终标签 ] }`

**错误码**：`40201201`（404）· `40201206` 标签冲突（add 与现有冲突）· `40201001` 参数非法。

## 3.4.7 categorize —— 设置分类

`POST /api/v1/admin/content/categorize` · 权限 `CONTENT_WRITE`

**请求 body**：`{ content_id✅, category_id✅ }`

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

**错误码**：`40201201`（404）· `40201207` 分类层级超限（MAX\_CATEGORY\_DEPTH）· `40201001` 参数非法。

## 3.4.8 moderate-comment —— 评论审核

`POST /api/v1/admin/content/moderate-comment` · 权限 `CONTENT_REVIEW`

> 内容评论区审核（与 [reviews](/api-docs/v1/admin/reviews) 模块的**评价**审核区分）。

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `comment_id` | string | ✅ | 目标评论 |
| `action` | string | ✅ | 审核动作（approve / reject / hide 等） |
| `reason` | string | null | ⬜ | 原因（audit） |

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

**错误码**：`40201208`（404）评论不存在 · `40201001` action 非法。

***

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