Drama Server API Reference

鉴权规则

场景	Header	说明
用户接口	`Authorization: Bearer <user_token>`	登录后访问用户资料、观看进度、支付接口。
后台接口	`Authorization: Bearer <admin_token>`	管理员登录后访问后台统计、分类、短剧、剧集、订单、用户接口。

Public APIs

GET/health

服务健康检查。

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

POST/api/v1/auth/login/mobile

手机号登录，返回用户 token 与 refreshToken。

{
  "mobile": "13800138000",
  "code": "1234"
}

GET/api/v1/home

首页聚合接口，当前主要字段包括 banners、continueWatching、sections。

GET/api/v1/categories

分类列表。

GET/api/v1/dramas?page=1&pageSize=20

短剧列表，支持分页参数 page 和 pageSize。

GET/api/v1/dramas/:id

短剧详情，包含短剧基础信息、分类信息、标签信息。

GET/api/v1/dramas/:id/episodes

剧集列表，返回 { dramaId, episodes }。

GET/api/v1/episodes/:id/play

播放地址与权限判断。未登录也可访问，但如果带用户 token，会按用户身份判断是否已解锁。

{
  "code": 4003,
  "message": "episode_locked",
  "data": {
    "episodeId": 1012,
    "playable": false,
    "trialEnded": true,
    "unlockMode": "episode",
    "price": 30,
    "vipFree": true
  }
}

User APIs

GET/api/v1/user/profile

当前用户资料，需要用户 token。

POST/api/v1/history/progress

保存观看进度。

{
  "dramaId": 101,
  "episodeId": 1001,
  "progressSeconds": 35,
  "duration": 95,
  "finished": false
}

POST/api/v1/payment/create

创建支付订单。支持 orderType=episode 和 orderType=drama。

{
  "orderType": "episode",
  "targetId": 1012
}

POST/api/v1/payment/mock-pay

模拟支付，用于联调解锁流程。

{
  "orderNo": "PO1775780000000"
}

Admin APIs

POST/admin/v1/auth/login

管理员登录。

{
  "username": "admin",
  "password": "admin123"
}

GET/admin/v1/dashboard/overview

后台概览统计。

GET/admin/v1/categories?page=1&pageSize=20&status=1

POST/admin/v1/categories

PUT/admin/v1/categories/:id

DELETE/admin/v1/categories/:id

后台分类列表、新增、更新、删除。列表接口支持分页，也支持按 status 筛选，返回 { list, pagination, filters }。

GET/admin/v1/dramas?page=1&pageSize=20&title=闪婚&categoryId=1&status=1

POST/admin/v1/dramas

PUT/admin/v1/dramas/:id

DELETE/admin/v1/dramas/:id

后台短剧列表、新增、更新、删除。列表支持按 title 模糊筛选，也支持按 categoryId、status 精筛，并返回分页信息与当前 filters。

GET/admin/v1/dramas/:id/episodes?page=1&pageSize=20&status=1

POST/admin/v1/episodes

PUT/admin/v1/episodes/:id

DELETE/admin/v1/episodes/:id

后台查看某剧剧集列表、新增剧集、更新剧集、删除剧集。剧集列表现在支持分页，也支持按 status 筛选，返回 { dramaId, list, pagination, filters }。

GET/admin/v1/orders?page=1&pageSize=20&status=paid&orderType=episode&userId=1&orderNo=PO177578

GET/admin/v1/orders/:id

后台订单列表与订单详情。列表支持按 status、orderType、userId、orderNo 检索，详情接口适合运营排单时查看单条订单信息。

GET/admin/v1/users?page=1&pageSize=20&mobile=138&nickname=测试&status=1

GET/admin/v1/users/:id

后台用户列表与用户详情。列表支持按 mobile、nickname 模糊筛选，也支持按 status 精筛；详情接口适合运营查看单个用户信息。

业务码

Code	含义
`0`	成功
`4000`	bad_request
`4001`	already_unlocked
`4002`	insufficient_balance
`4003`	episode_locked
`4004`	order_status_invalid
`4010`	unauthorized
`4040`	资源不存在
`5000`	服务端错误

Quick Start

curl -s https://m.iaoo.de/health
curl -s https://m.iaoo.de/api/v1/home
curl -s "https://m.iaoo.de/api/v1/dramas?page=1&pageSize=20"

curl -s https://m.iaoo.de/api/v1/auth/login/mobile \
  -H 'Content-Type: application/json' \
  -d '{"mobile":"13800138000","code":"1234"}'

curl -s https://m.iaoo.de/admin/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123"}'

User Curl Examples

下面这组命令适合前端、测试或验收同学直接跑用户侧流程。涉及鉴权的接口，把 <user_token> 换成登录接口返回的 token。

推荐验收顺序：先登录拿 token，再依次验证首页、短剧列表、短剧详情、剧集列表、播放接口，最后再跑支付创建与 mock-pay，这样最接近真实用户链路。

# 1) 用户手机号登录，获取 token
curl -s https://m.iaoo.de/api/v1/auth/login/mobile \
  -H 'Content-Type: application/json' \
  -d '{"mobile":"13800138000","code":"1234"}'

# 2) 查看首页聚合内容
curl -s https://m.iaoo.de/api/v1/home

# 3) 查看公开短剧列表
curl -s "https://m.iaoo.de/api/v1/dramas?page=1&pageSize=20"

# 4) 查看短剧详情
curl -s https://m.iaoo.de/api/v1/dramas/101

# 5) 查看某剧剧集列表
curl -s https://m.iaoo.de/api/v1/dramas/101/episodes

# 6) 查询播放地址与解锁状态（可带用户 token）
curl -s https://m.iaoo.de/api/v1/episodes/1001/play \
  -H 'Authorization: Bearer '

# 7) 创建支付订单
curl -s https://m.iaoo.de/api/v1/payment/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ' \
  -d '{"orderType":"episode","targetId":1012}'

# 8) 模拟支付，用于联调解锁流程
curl -s https://m.iaoo.de/api/v1/payment/mock-pay \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ' \
  -d '{"orderNo":"PO1775780000000"}'

Admin Curl Examples

下面这组命令适合直接拿去做后台联调和验收。真实使用时，把 <admin_token> 换成登录接口返回的 token。

推荐验收顺序：先登录后台，再依次验证短剧列表、剧集列表、订单检索，最后再执行删除动作。删除接口建议放到最后，避免影响前面的列表与详情联调。

# 1) 管理员登录，获取 token
curl -s https://m.iaoo.de/admin/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123"}'

# 2) 查短剧列表，带分页和筛选
curl -s "https://m.iaoo.de/admin/v1/dramas?page=1&pageSize=20&title=闪婚&categoryId=1&status=1" \
  -H 'Authorization: Bearer '

# 3) 查某个短剧的剧集列表，带分页和状态筛选
curl -s "https://m.iaoo.de/admin/v1/dramas/101/episodes?page=1&pageSize=20&status=1" \
  -H 'Authorization: Bearer '

# 4) 查订单列表，按状态 / 类型 / 用户 / 订单号组合检索
curl -s "https://m.iaoo.de/admin/v1/orders?page=1&pageSize=20&status=paid&orderType=episode&userId=1&orderNo=PO177578" \
  -H 'Authorization: Bearer '

# 5) 查单条订单详情
curl -s https://m.iaoo.de/admin/v1/orders/1 \
  -H 'Authorization: Bearer '

# 6) 查单个用户详情
curl -s https://m.iaoo.de/admin/v1/users/1 \
  -H 'Authorization: Bearer '

# 7) 删除一个剧集
curl -s -X DELETE https://m.iaoo.de/admin/v1/episodes/1001 \
  -H 'Authorization: Bearer '

# 8) 删除一个短剧
curl -s -X DELETE https://m.iaoo.de/admin/v1/dramas/101 \
  -H 'Authorization: Bearer '