FruitServer/docs/api-phase1.md

第一阶段接口清单（后台管理 + 客户端）

版本 v1.0 · 配套 PRD 与 后端设计 状态说明：已实现 = 代码已落地可联调；下一批 = 表结构与契约已冻结，代码待补。

0. 通用约定

服务入口：后台管理 fruitshorts-admin-api 只暴露 /admin/**（8080）； 客户端 fruitshorts-app-api 只暴露 /app/** 与媒资 /files/**（8081）。

统一响应体

{ "code": 0, "message": "ok", "data": {} }

code = 0 成功；非 0 时 message 可直接展示给用户。分页统一为 { total, list }。

鉴权：Authorization: Bearer <token>。 管理端与客户端用两套独立密钥签发，管理端 token 打到客户端接口会直接被拒。 客户端 access token 默认 2 小时，refresh token 30 天且每次刷新轮换。

设备标识：客户端建议所有请求都带 X-Device-Id，用于下载授权、并发播放限制与风控。

主要错误码

code	含义	客户端处理
0	成功	—
400	参数校验失败	提示 message
401	未登录或登录过期	用 refresh token 换新 token，失败则跳登录
403	无权限	提示无权限
429	请求过于频繁	提示稍后再试（验证码频控走这里）
100000	账号或密码错误	提示
100001	账号已停用	展示封禁申诉入口
100002	金币余额不足	拉起充值
100003	剧集未发布或不存在	返回上一页
100005	订单已支付或已关闭	刷新订单状态
200002	数据不存在	提示
200003	当前状态不允许该操作	提示

1. 客户端接口（/app/**）

1.1 账号（已实现）

方法	路径	鉴权	说明
POST	/app/auth/otp	匿名	发送验证码。scene = REGISTER/LOGIN/RESET_PWD/BIND
POST	/app/auth/register	匿名	手机号/邮箱注册，返回令牌
POST	/app/auth/login	匿名	验证码或密码登录
POST	/app/auth/refresh	匿名	用 refresh token 换新令牌并轮换
POST	/app/auth/logout	可选	登出；allDevices=true 吊销全部会话

发送验证码：

POST /app/auth/otp
{ "scene": "REGISTER", "targetType": "PHONE", "target": "08123456789", "deviceId": "d-1" }

手机号会自动规范化成 E.164（印尼本地 08xx → +62xxx）。频控：同号 60 秒一次、每日 10 次， 同 IP 每小时 20 次；连续输错 5 次该验证码作废。

注册：

POST /app/auth/register
{
  "targetType": "PHONE", "target": "08123456789", "code": "123456",
  "password": "可选，设置后可用密码登录",
  "nickname": "可选",
  "deviceId": "d-1", "platform": "IOS", "appVersion": "1.0.0",
  "agreementVersion": "2026-10-01", "marketingConsent": false
}

响应（登录、刷新同结构）：

{
  "code": 0, "message": "ok",
  "data": {
    "accessToken": "...", "refreshToken": "...", "expiresIn": 7200, "tokenType": "Bearer",
    "newUser": true,
    "user": { "uid": "U8KQ2ZP1", "nickname": "User8KQ2ZP", "status": "normal",
              "countryCode": "ID", "language": "id-ID", "currency": "IDR",
              "maskedTarget": "+628****789", "vipLevel": 0, "vipExpireAt": null }
  }
}

1.2 个人中心（已实现）

方法	路径	说明
GET	/app/me	当前用户资料
PUT	/app/me	修改昵称/头像/性别/生日/语言/时区/区域
GET	/app/me/devices	登录设备列表
GET	/app/me/export	数据导出（商店与隐私法规要求）
POST	/app/me/deactivate	申请注销，进入 15 天冷静期并立即登出全部设备
POST	/app/me/deactivate/cancel	冷静期内撤销注销

1.3 内容浏览（已实现）

方法	路径	说明
GET	/app/home/feed	首页：轮播 + 分区，卡片带 preview 可播预览集
GET	/app/discover/feed	发现页分区
GET	/app/categories	分类列表
GET	/app/dramas/{id}	详情（含剧集列表，免费集带已签名播放地址）

1.4 播放（已实现，链路已重做）

方法	路径	鉴权	说明
GET	/app/episodes/{id}/play	可选	签发播放票据与签名地址

{
  "code": 0, "message": "ok",
  "data": {
    "episodeId": 12, "dramaId": 5, "number": 1, "title": "第 1 集", "durationSec": 180,
    "accessible": true,
    "accessType": "FREE",
    "playUrl": "/files/episode/202610/xxx.mp4?e=1760000000&s=9f2c...",
    "qualities": ["AUTO"],
    "unlockCoin": 0,
    "previewSeconds": 0
  }
}

accessType 取值：FREE（免费集）、ENTITLED（已购权益）、COIN_REQUIRED（需解锁， 此时 playUrl 为空、unlockCoin 有值）、NO_MEDIA（还没上传片源或未转码完成）。

判定顺序由服务端决定，客户端不得自行推断可否播放。 签名默认 15 分钟有效； 开启 fruitshorts.media.signature-required 后，/files/episode/** 没带有效签名会返回 403。

1.5 观看记录与收藏（已实现）

方法	路径	说明
POST	/app/watch/progress	上报进度（建议每 10s 一次，切集时补一次）
GET	/app/watch/progress?dramaId=	某剧续看位置
GET	/app/watch/recent?limit=20	最近观看
DELETE	/app/watch/progress/{dramaId}	删除某剧记录
DELETE	/app/watch/progress	清空记录
POST	/app/favorites/toggle	收藏/取消收藏，返回切换后状态
GET	/app/favorites	收藏列表（卡片结构与首页一致）
DELETE	/app/favorites/{dramaId}	取消收藏

进度合并规则：同一集内只前进不后退；换集直接采纳新集；finished 只在接近片尾或客户端显式上报时置位。 这样用户换设备不会看到进度倒退。

1.6 离线下载（已实现）

服务端只发授权与短时效地址，分片由客户端直接向 CDN 拉取 —— 这样并发下载不会打到应用服务器，服务端只记账（进度、配额、有效期）。

方法	路径	说明
GET	/app/downloads/policy	策略与配额：单设备上限、授权天数、仅 Wi-Fi、清晰度上限、已用/剩余
PUT	/app/downloads/settings	偏好设置：仅 Wi-Fi 下载、最高清晰度
POST	/app/downloads	申请下载授权（同剧集重复申请幂等，只刷新有效期）
GET	/app/downloads	下载列表（授权 + 任务进度，可直接渲染）
GET	/app/downloads/{episodeId}/url	断点续传前重新取地址（授权不变，地址是短时效的）
POST	/app/downloads/{episodeId}/progress	上报下载进度，用于断点续传与跨端展示
DELETE	/app/downloads/{episodeId}	删除单条下载（吊销授权）
DELETE	/app/downloads	清空当前设备全部下载，返回清除条数

设备标识优先取请求体 deviceId，其次取请求头 X-Device-Id。 授权默认 30 天有效，过期由每日定时任务置为 EXPIRED；被吊销或过期的授权客户端下次联网即失效。 需要解锁的剧集走权益判定，未解锁不允许下载（当前内容均为免费集，付费链路见 09）。 配额与有效期由 fruitshorts.download.* 配置，通过 policy 下发，客户端不要写死。

1.7 互动与内容治理（已实现）

方法	路径	鉴权	说明
POST	/app/comments	登录	发表评论/回复：过敏感词后按策略发布或转待审
GET	/app/comments?dramaId=&cursor=&size=	匿名	游标翻页；不传 rootId 返回顶层评论，传了返回该楼层回复
DELETE	/app/comments/{id}	登录	删除自己的评论（逻辑置为 deleted）
POST	/app/likes/toggle	登录	点赞/取消点赞，targetType 支持 DRAMA / COMMENT
POST	/app/reports	登录	举报评论/用户/短剧；同一目标只保留一条待处理工单

敏感词三档处置：BLOCK 直接拒绝并返回原因、REPLACE 替换后放行、REVIEW 转人工待审。 审核策略由 fruitshorts.interaction.comment-audit-mode 控制： MACHINE_FIRST（机审通过即发布，当前默认）或 PRE_REVIEW（全部先审后发，生产建议）。

可见性：匿名与其他人只看得到 published；自己待审的评论也会返回，便于展示"审核中"。 评论列表禁止重复提交（同一剧集每分钟 5 条，可配）。

1.8 金币与权益（已实现）

方法	路径	说明
GET	/app/wallet	金币余额 + 最近流水
POST	/app/episodes/{id}/unlock	金币解锁分集；幂等键 unlock:{userId}:{episodeId}，重复调用不重复扣币
GET	/app/orders	我的订单
POST	/app/orders/verify	提交 IAP / Google Play 票据。本轮只留端口不接商店，会返回 200003 尚未配置

解锁后播放入口与下载入口会同时放行 —— 权益判定由交易模块的 EntitlementPort 实现提供， 播放域与下载域都不需要改代码。金币变动一律带幂等键并写 coin_ledger，钱包余额与流水同事务。

1.9 创作者（下一批）

方法	路径	说明
GET	/app/orders	我的订单
GET	/app/wallet	金币余额与流水
POST	/app/episodes/{id}/unlock	金币解锁分集
POST	/app/creator/apply	创作者入驻
GET	/app/creator/works	我的作品与审核状态
GET	/app/creator/stats	创作者数据看板
GET	/app/config	启动配置（协议版本、开关、最低版本）
GET	/app/notices	系统公告

2. 后台管理接口（/admin/**）

2.1 认证与系统（已实现）

POST /admin/auth/login、GET /admin/auth/menus、GET /admin/auth/profile、 POST /admin/auth/logout、POST /admin/auth/password； 管理员、角色、权限、菜单、角色分类、系统配置、操作日志各自一套增删改查。

2.2 内容与媒资（已实现）

短剧（含是否热门、审核发布状态机）、剧集、分类、轮播图；媒资分片上传（init/chunk/complete）。 新增字段：短剧 rating（内容分级）、regionCodes（可播区域）、版权窗口、 creatorId、tags、trailerUrl；剧集 transcodeStatus、hlsUrl、previewSeconds、字幕。

2.3 App 用户管理（已实现）

方法	路径	权限点	说明
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	封禁与申诉记录
PUT	/admin/app-users/{id}/status	app-user:update	改状态：normal/limited/banned

状态处置会立即吊销该用户全部会话并写入封禁记录，避免"封了还能用"。

2.4 下载管理（已实现）

方法	路径	权限点	说明
GET	/admin/downloads/page	download:list	按用户 / 设备 / 状态检索下载授权，含剧名与集号
GET	/admin/downloads/stats	download:list	授权与任务的分布统计
PUT	/admin/downloads/{id}/revoke	download:revoke	吊销授权，用户侧下次联网即失效
POST	/admin/downloads/cleanup	download:revoke	手动清理过期授权（默认每天凌晨自动执行）

2.5 内容治理（已实现）

方法	路径	权限点	说明
GET	/admin/comments/page	comment:list	检索评论，status=pending 即审核队列
GET	/admin/comments/{id}/audit-records	comment:list	审核留证：机审与人审的完整链路
PUT	/admin/comments/{id}/audit	comment:audit	通过 / 驳回（带原因码与说明）
DELETE	/admin/comments/{id}	comment:audit	删除评论
GET	/admin/reports/page	report:list	举报工单检索（状态 / 类型 / 原因）
PUT	/admin/reports/{id}/handle	report:handle	处理工单；结论成立会联动驳回被举报评论，可选择同时封禁被举报用户
GET	/admin/sensitive-words/page	sensitive-word:list	敏感词检索
POST/PUT/DELETE	/admin/sensitive-words[/{id}]	sensitive-word:update	维护词库，改动即时生效（服务端缓存失效重建）

2.6 订单与权益（已实现）

方法	路径	权限点	说明
GET	/admin/orders/page /admin/orders/{orderNo} /{orderNo}/events	order:list	订单检索、详情、状态流转流水
POST	/admin/orders/{orderNo}/compensate	order:update	补发：已支付未交付的订单重新交付，已交付幂等返回
POST	/admin/orders/{orderNo}/refund	order:update	退款/撤销：回收权益 + 扣回金币（余额不足时留人工跟进备注）
GET	/admin/entitlements/page	entitlement:list	权益检索
POST	/admin/entitlements	entitlement:update	人工补发权益（客服补偿）
PUT	/admin/entitlements/{id}/revoke	entitlement:update	回收权益，播放判定实时生效
GET	/admin/wallets/{userId}/ledger	order:list	金币流水
POST	/admin/wallets/coins	wallet:update	人工补币/扣回，必须带幂等键，先校验用户存在
POST	/admin/reconcile/run · GET /admin/reconcile/page	reconcile:run / order:list	手动对账与历史（默认每天 04:20 自动跑前一天）

2.7 创作者与内容审核（已实现）

方法	路径	权限点	说明
GET	/admin/creators/page /admin/creators/{id} /{id}/documents	creator:list	创作者检索、详情、资质文件
PUT	/admin/creators/{id}/audit	creator:audit	入驻审核：APPROVE / REJECT（必填原因+原因码）/ FREEZE
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 + 逐集覆盖；改价立即影响播放与下载判定

定时发布：DramaPublishJob 每分钟扫一次，把 publish_at 到点的 approved 短剧推上线， 走的是短剧状态机（不直接改状态字段）。上下架也可通过内容提交的 OFFLINE 审核触发。

2.8 数据看板（下一批）

方法	路径	说明
GET	/admin/comments/page	评论审核队列
PUT	/admin/comments/{id}/audit	通过/驳回（带原因码）
GET	/admin/reports/page	举报工单
PUT	/admin/reports/{id}/handle	处理举报（可联动封禁）
GET/POST/PUT	/admin/sensitive-words	敏感词库
GET	/admin/orders/page	订单检索（可按用户、状态、平台）
POST	/admin/orders/{orderNo}/compensate	票据丢失的补发
PUT	/admin/entitlements/{id}/revoke	权益回收
POST	/admin/reconcile/run	手动触发对账
GET	/admin/creators/page	创作者审核队列
PUT	/admin/creators/{id}/audit	入驻审核
GET	/admin/submissions/page	内容提交审核
PUT	/admin/submissions/{id}/audit	内容审核（通过/驳回/驳回原因码）
PUT	/admin/prices	分集价格与免费集配置
GET	/admin/dashboard/overview	经营大盘（用户/播放/收入/成本）
GET	/admin/dashboard/transcode	转码队列与失败任务
POST	/admin/notices	发布系统公告

3. 契约与实现状态对照

模块	表结构	接口	代码
01 基础与交付准备	已就绪	约定已冻结	脚手架 / 契约 / 签名 / 转码骨架 已实现
02 用户账号与登录	已建	已冻结	已实现（手机号/邮箱，第三方登录走同一凭证表）
03 内容发现与详情	已建	已冻结	已实现（补了分级、区域、版权、标签字段）
04 播放器与播放控制	已建	已冻结	票据 + 签名 + 进度 已实现；多码率依赖转码 worker
05 记录、收藏与下载	已建	已冻结	已实现：进度、观看流水、收藏、离线下载授权与任务
06 评论、点赞与分享	已建	已冻结	已实现：评论（游标翻页/审核/删除）、点赞、举报、敏感词；分享埋点在下一批
07 创作者中心	已建	已冻结	下一批（转码任务与产物记账已实现）
08 平台运营后台	已建	已冻结	用户管理、内容治理、订单与权益、创作者与内容审核已实现；数据看板下一批
09 分集收费与支付	已建	已冻结	下一批（权益判定端口已预留，接上即生效）
10 质量、数据与上线	已建	已冻结	压测与埋点 下一批