From efe8af6c9bf18ba18d9dfc71d89473c3d2205a0f Mon Sep 17 00:00:00 2001
From: Zhou Weidong <502333560@qq.com>
Date: Fri, 16 Oct 2026 10:23:25 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=A8=E6=8E=A5=E5=8F=A3?=
 =?UTF-8?q?=E5=A5=91=E7=BA=A6=E9=81=97=E6=BC=8F=EF=BC=8C=E9=80=90=E6=9D=A1?=
 =?UTF-8?q?=E5=B1=95=E5=BC=80=E7=B3=BB=E7=BB=9F=E7=AE=A1=E7=90=86=E4=B8=8E?=
 =?UTF-8?q?=E5=86=85=E5=AE=B9=E6=8E=A5=E5=8F=A3=E5=B9=B6=E8=A1=A5=E5=85=85?=
 =?UTF-8?q?=20watch-history/creators=20=E8=B4=A6=E5=8F=B7/media=20?=
 =?UTF-8?q?=E8=AF=A6=E6=83=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/api-phase1.md | 91 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 84 insertions(+), 7 deletions(-)

diff --git a/docs/api-phase1.md b/docs/api-phase1.md
index 782d05a..b95de8e 100644
--- a/docs/api-phase1.md
+++ b/docs/api-phase1.md
@@ -219,24 +219,98 @@ POST /app/auth/register
 
 ### 2.1 认证与系统（已实现）
 
-`POST /admin/auth/login`、`GET /admin/auth/menus`、`GET /admin/auth/profile`、
-`POST /admin/auth/logout`、`POST /admin/auth/password`；
-管理员、角色、权限、菜单、角色分类、系统配置、操作日志各自一套增删改查。
+**认证**
+
+| 方法 | 路径 | 鉴权 | 说明 |
+| --- | --- | --- | --- |
+| POST | `/admin/auth/login` | 匿名 | 登录，返回 token |
+| GET | `/admin/auth/menus` | 登录 | 当前用户菜单树 |
+| GET | `/admin/auth/profile` | 登录 | 当前用户资料 |
+| POST | `/admin/auth/logout` | 登录 | 登出 |
+| POST | `/admin/auth/password` | 登录 | 修改密码 |
+
+**系统管理（RBAC）**
+
+| 资源 | 方法 | 路径 | 权限点 |
+| --- | --- | --- | --- |
+| 管理员 | GET | `/admin/admin-users/page` · `/{id}` | `system:admin-user` |
+| 管理员 | POST | `/admin/admin-users` | `system:admin-user` |
+| 管理员 | PUT | `/admin/admin-users/{id}` · `/{id}/status` · `/{id}/password` | `system:admin-user` |
+| 管理员 | DELETE | `/admin/admin-users/{id}` | `system:admin-user` |
+| 角色 | GET | `/admin/roles/page` · `/list` · `/{id}` · `/{id}/permissions` | `system:role`（`/list` 登录即可） |
+| 角色 | POST | `/admin/roles` | `system:role` |
+| 角色 | PUT | `/admin/roles/{id}` · `/{id}/permissions` | `system:role` |
+| 角色 | DELETE | `/admin/roles/{id}` | `system:role` |
+| 权限 | GET | `/admin/permissions` | `system:role` |
+| 菜单 | GET | `/admin/menus/tree` | `system:menu` |
+| 菜单 | POST · PUT · DELETE | `/admin/menus` · `/admin/menus/{id}` | `system:menu` |
+| 角色分类 | GET · POST | `/admin/role-categories` | `system:role-category` |
+| 角色分类 | PUT · DELETE | `/admin/role-categories/{id}` | `system:role-category` |
+| 系统配置 | GET | `/admin/configs` | `system:role` / `system:menu` |
+| 系统配置 | PUT | `/admin/configs` | `system:role` |
+| 操作日志 | GET | `/admin/operation-logs/page` · `/{id}` | `log:list` |
+| 字典 | GET | `/admin/dicts/drama-category` · `/content-status` | `drama:list` |
 
 ### 2.2 内容与媒资（已实现）
 
-短剧（含是否热门、审核发布状态机）、剧集、分类、轮播图；媒资分片上传（init/chunk/complete）。
 新增字段：短剧 `rating`（内容分级）、`regionCodes`（可播区域）、版权窗口、
 `creatorId`、`tags`、`trailerUrl`；剧集 `transcodeStatus`、`hlsUrl`、`previewSeconds`、字幕。
 
-媒资上传补充（批 3 加固，后台与创作者共用同一套接口，未重写）：
+**短剧（含审核发布状态机）**
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/dramas/page` | `drama:list` | 检索（含热门、状态筛选） |
+| GET | `/admin/dramas/{id}` | `drama:list` | 详情 |
+| POST | `/admin/dramas` | `drama:create` | 新建短剧 |
+| PUT | `/admin/dramas/{id}` | `drama:update` | 编辑短剧 |
+| DELETE | `/admin/dramas/{id}` | `drama:delete` | 删除短剧 |
+| POST | `/admin/dramas/{id}/submit` | `drama:review` / `drama:update` | 提交审核 |
+| POST | `/admin/dramas/{id}/approve` | `drama:review` | 审核通过 |
+| POST | `/admin/dramas/{id}/reject` | `drama:review` | 驳回 |
+| POST | `/admin/dramas/{id}/publish` | `drama:review` | 上线 |
+| POST | `/admin/dramas/{id}/offline` | `drama:review` | 下线 |
+| GET | `/admin/dramas/{id}/review-records` | `drama:list` | 审核记录 |
+
+**剧集**
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/episodes?dramaId=` | `episode:list` | 某剧分集列表 |
+| POST | `/admin/episodes` | `episode:upload` | 新增分集 |
+| PUT | `/admin/episodes/{id}` | `episode:upload` | 编辑分集 |
+| DELETE | `/admin/episodes/{id}` | `episode:upload` | 删除分集 |
+| PUT | `/admin/episodes/sort` | `episode:sort` | 批量排序 |
+
+**短剧类型**
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/drama-categories` | `drama:list` | 类型列表 |
+| POST | `/admin/drama-categories` | `drama:create` | 新增类型 |
+| PUT | `/admin/drama-categories/{id}` | `drama:update` | 编辑类型 |
+| DELETE | `/admin/drama-categories/{id}` | `drama:delete` | 删除类型 |
+
+**轮播图**
+
+| 方法 | 路径 | 权限点 | 说明 |
+| --- | --- | --- | --- |
+| GET | `/admin/banners/page` · `/admin/banners/{id}` | `banner:list` | 检索 / 详情 |
+| POST | `/admin/banners` | `banner:create` | 新增 |
+| PUT | `/admin/banners/{id}` · `/{id}/status` · `/sort` | `banner:update` | 编辑 / 改状态 / 排序 |
+| DELETE | `/admin/banners/{id}` | `banner:delete` | 删除 |
+
+**媒资分片上传（后台与创作者共用）**
 
 | 方法 | 路径 | 说明 |
 | --- | --- | --- |
 | POST | `/admin/media/upload/init` | 建上传会话（返回 `uploadId` / `chunkSize` / `totalChunks` / `objectKey`） |
 | POST | `/admin/media/upload/chunk` | 传分片（`uploadId` + `index` + `file`），可重复传同一片 |
-| GET | `/admin/media/upload/{uploadId}` | **新增**：断点续传回显（`receivedChunks` / `totalChunks` / `percent` / `status` / 完成后带 `url`） |
+| GET | `/admin/media/upload/{uploadId}` | 断点续传回显（`receivedChunks` / `totalChunks` / `percent` / `status` / 完成后带 `url`） |
 | POST | `/admin/media/upload/complete` | 合并分片出媒资（幂等：同一 uploadId 重复调用返回同一产物） |
+| GET | `/admin/media/{id}` | 媒资详情 |
+
+> 媒资上传与详情权限点均为 `cover:upload` 或 `episode:upload`（`@ss.hasAnyPermission`）。
 
 **上传会话归属**：`uploadId` 相当于上传凭证，`chunk` / `complete` / 进度查询都校验会话发起人，
 别人拿到 `uploadId` 也塞不进分片（`{"code":403,"message":"无权操作该上传会话"}`）。
@@ -248,6 +322,7 @@ POST /app/auth/register
 | GET | `/admin/app-users/page` | `app-user:list` | 检索：keyword（uid/昵称/手机号/邮箱）、status、countryCode、registerSource |
 | GET | `/admin/app-users/{id}` | `app-user:list` | 详情 |
 | GET | `/admin/app-users/{id}/ban-records` | `app-user:list` | 封禁与申诉记录 |
+| GET | `/admin/app-users/{id}/watch-history` | `app-user:list` | 观看流水明细（带剧名/集号，客服核对用） |
 | PUT | `/admin/app-users/{id}/status` | `app-user:update` | 改状态：normal/limited/banned |
 
 状态处置会**立即吊销该用户全部会话**并写入封禁记录，避免"封了还能用"。
@@ -294,6 +369,9 @@ POST /app/auth/register
 | --- | --- | --- | --- |
 | GET | `/admin/creators/page` `/admin/creators/{id}` `/{id}/documents` | `creator:list` | 创作者检索、详情、资质文件 |
 | PUT | `/admin/creators/{id}/audit` | `creator:audit` | 入驻审核：`APPROVE` / `REJECT`（必填原因+原因码）/ `FREEZE` |
+| POST | `/admin/creators` | `creator:audit` | 手工录入创作者主体（C 端申请入驻未实现前的打通用口） |
+| POST | `/admin/creators/{id}/account` | `creator:account` | 开通创作者账号（幂等） |
+| POST | `/admin/creators/{id}/account/reset-password` | `creator:account` | 重置创作者账号密码（一次性明文返回） |
 | GET | `/admin/submissions/page` `/admin/submissions/{id}` | `submission:list` | 内容提交检索与详情 |
 | PUT | `/admin/submissions/{id}/audit` | `submission:audit` | 审核通过后按 `type` 落到短剧状态机（CREATE/UPDATE 留档、PUBLISH 上线、OFFLINE 下线） |
 | GET · PUT | `/admin/prices` | `price:update` | 分集价格：整剧 `freeEpisodes`/`unlockCoin` + 逐集覆盖；改价立即影响播放与下载判定 |
@@ -348,7 +426,6 @@ POST /app/auth/register
 | PUT | `/admin/prices` | 分集价格与免费集配置 |
 | GET | `/admin/dashboard/overview` | 经营大盘（用户/播放/收入/成本） |
 | GET | `/admin/dashboard/transcode` | 转码队列与失败任务 |
-| POST | `/admin/notices` | 发布系统公告 |
 
 ### 2.9 后台前端页面（已实现）