管理后台新增能力 — 前端对接
面向 管理后台(主)与 C 端展示字段(辅)。分支:test-old。
支持等级枚举请统一按 LV1…LV7(wire 1…7)解析,详见 tips_level_frontend.md。
通用约定:
- 管理端接口均为
POST,JSON body。
- 时间字段为 Unix 秒(
int64)。
- 金额 / 评分为十进制 string(空字符串表示未填)。
- HTTP 失败时看响应里的业务
code(见各节错误码)。
1. OTP 解绑(用户详情)
接口
| 项 |
值 |
| Path |
/v1/man/users/clear/otp |
| Body |
{ "user_id": 123 } |
行为
| 场景 |
结果 |
| 用户仍绑定 OTP |
成功清空,返回空 data |
用户已自行解绑(otp 已空) |
失败,业务码 14036 |
错误码
| code |
含义 |
前端建议 |
14036 CODE_OTP_ALREADY_UNBOUND |
用户已自行解绑 |
Toast:「用户已自行解绑」,勿当成功 |
2. 支持等级变化明细(用户详情)
接口
| 项 |
值 |
| Path |
/v1/man/users/tips_level/logs |
请求
{
"user_id": 123,
"offset": 0,
"limit": 20,
"sort": "created_at",
"order": "DESC",
"started_at": 0,
"ended_at": 0
}
started_at / ended_at:可选,Unix 秒;0 表示不限。
响应
{
"total": 100,
"logs": [
{
"id": 1,
"user_id": 123,
"created_at": 1728700000,
"tips_level": 3,
"change_type": 1,
"trigger_condition": "支持短剧/机器人:某某剧10硬币,活跃值为50",
"remark": ""
}
]
}
字段说明
| 字段 |
类型 |
说明 |
tips_level |
TipsLevel |
变更后等级:1=LV1 … 7=LV7 |
change_type |
enum |
1 升级 / 2 降级 |
trigger_condition |
string |
后端已拼好的中文触发条件,直接展示即可 |
remark |
string |
备注,可为空 |
change_type 文案建议
| 值 |
展示 |
1 TYPE_UPGRADE |
升级 |
2 TYPE_DOWNGRADE |
降级 |
列表列建议
| 列 |
数据 |
| 时间 |
created_at |
| 变更后等级 |
Lv{tips_level}(数值即档位) |
| 变化类型 |
change_type |
| 触发条件 |
trigger_condition |
3. 短剧分组:类别 / 仅轮播
与原有 type(系统/自定义/无分组)独立,新增 category。
枚举 Playlet.GroupCategory
| 值 |
名 |
含义 |
UI 建议 |
0 |
UNKNOWN |
未指定 |
列表筛选=全部;创建时后端默认改成标签 |
1 |
CAROUSEL |
轮播 |
「轮播」 |
2 |
HOME_SECTION |
首页板块 |
「首页板块」 |
3 |
TAG |
标签 |
「标签」(默认) |
另:carousel_only(bool)— 仅在轮播区域显示。
接口(既有 path,字段扩展)
| 动作 |
Path |
| 创建 |
/v1/man/playlet/group/create |
| 列表 |
/v1/man/playlet/group/list |
| 更新 |
/v1/man/playlet/group/update |
创建 / 更新 body 新增
{
"category": 3,
"carousel_only": false
}
列表筛选
{
"language": "ind",
"category": 2,
"offset": 0,
"limit": 20
}
category = 0(或不传):不按类别过滤(全部)。
更新注意
- 更新时若不传 / 传
category=0,后端保留原类别,不会被清零。
- 需要改类别时必须显式传
1/2/3。
列表项新增回显
{
"id": 10,
"name": "...",
"category": 2,
"carousel_only": false
}
4. 短剧:评分 / 最新首页板块 / 资源包
接口(既有 path,字段扩展)
| 动作 |
Path |
| 创建 |
/v1/man/playlet/create |
| 列表 / 详情同列表 |
/v1/man/playlet/list |
| 更新 |
/v1/man/playlet/update |
评分 score
| 规则 |
说明 |
| 类型 |
string |
| 未填 |
"" |
| 合法 |
> 0,最多 1 位小数,如 "8"、"8.5" |
| 非法 |
后端拒参(业务 CODE_ARGUMENT) |
| 更新清空 |
传 "" 可清空为未填 |
创建 / 更新示例:
{ "score": "8.5" }
列表回显:
{ "score": "8.5" }
未填时回显 ""。
latest_home_group_id(只读回显)
| 项 |
说明 |
| 谁写入 |
仅后端:当本次更新新勾选了「首页板块」类分组时,取请求顺序中最后一个首页板块 ID |
| 前端 |
列表/详情展示即可;不要在 update body 里手写覆盖 |
| 无新增首页板块 |
保留库中原值,不会被清零 |
回显示例:
{ "latest_home_group_id": 12 }
0 表示尚无。
resource_link
- 创建/更新请求里字段仍可能存在,但 更新接口已不再写入
resource_link。
- 前端可隐藏或只读展示历史值,勿再当作可编辑必需项。
5. 升级补贴奖励明细(用户 / 活动)
接口
| 项 |
值 |
| Path |
/v1/man/upgrade_subsidies/detail |
请求
{
"user_id": 123,
"offset": 0,
"limit": 20,
"sort": "triggered_at",
"order": "DESC"
}
响应结构
{
"assessing": {
"assess_until": 1728800000,
"current_level": 4,
"task_target": "130",
"current_progress": "100"
},
"total": 10,
"records": [
{
"id": 1,
"triggered_at": 1728700000,
"trigger_level": 4,
"task_target": "130",
"current_progress": "140",
"granted_amount": "50",
"status": 1
}
]
}
assessing(考核中)
| 条件 |
行为 |
用户 ≥ LV3,且存在未到期考核窗(next_subsidy_at 未到) |
返回 assessing |
| 否则 |
assessing 为空 / 省略 |
| 字段 |
说明 |
assess_until |
考核截止时间(Unix 秒) |
current_level |
当前支持等级 |
task_target |
任务目标(粉丝数或团队活跃值,与后台考核模式一致,string) |
current_progress |
当前进度(同单位 string) |
考核模式由运营配置决定(粉丝人数 / 团队活跃值);前端原样展示目标与进度即可,不必自行算 30%。
records[].status(Subsidies.RecordStatus)
| 值 |
名 |
展示建议 |
1 |
UPGRADE_GRANT |
升级发放 |
2 |
ASSESS_PASS |
考核通过 |
3 |
ASSESS_FAIL |
考核未通过 |
4 |
NOT_FIRST_UPGRADE |
非首次升级 |
5 |
DOWNGRADE_TO_LV2 |
降级到 Lv2 及以下 |
明细字段
| 字段 |
说明 |
triggered_at |
升级或考核时间 |
trigger_level |
触发时等级 |
task_target / current_progress |
非首次升级等场景可能为空 |
granted_amount |
实际进入待领取的金额(string);失败/非首次等可能为 "0" |
列表列建议
| 列 |
数据 |
| 时间 |
triggered_at |
| 等级 |
Lv{trigger_level} |
| 状态 |
status |
| 任务目标 |
task_target |
| 当时进度 |
current_progress |
| 发放金额 |
granted_amount |
顶部可单独一块展示「考核中」:assessing 有值时显示倒计时 / 截止时间与进度。
6. C 端相关(顺带)
6.1 首页分组 / 剧卡片字段
C 端首页相关响应新增(无需新接口):
| 位置 |
字段 |
分组 PlayletGroup / PlayletServiceResponse |
category、carousel_only |
剧 Playlet |
score、latest_home_group_id |
用途建议:
category + carousel_only:区分轮播区 / 首页板块 / 标签展示逻辑。
score:有值则展示评分。
latest_home_group_id:标记「最新勾选的首页板块」归属(0=无)。
6.2 升级补贴考核信息(C 端既有)
| Path |
/v1/upgrade_subsidy_check_info/get |
|
|
行为收紧(与后台明细一致):
- 用户等级 < LV3、考核窗已清空(无
next_subsidy_at)、或考核窗已过期:返回空进度(各字段为 0 / 空),不要展示考核中 UI。
- ≥ LV3 且考核窗未过期:照常返回粉丝/活跃目标与完成率。
字段形态不变:fans_count、target_fans_count、growth_rate、active_value、target_active_value、growth_rate_active_value。
7. 联调检查清单
管理后台
- [ ] OTP 已解绑用户点「解绑」→ 提示
14036,非成功
- [ ] 用户详情「等级变化」分页列表,升级/降级与触发条件可读
- [ ] 分组创建可选类别 + 仅轮播;列表可按类别筛;更新不传类别不丢原值
- [ ] 短剧创建/编辑评分:合法小数通过,非法拒参;空可清空
- [ ] 短剧勾选首页板块后列表出现
latest_home_group_id;仅改其它字段不丢该值
- [ ] 升级补贴明细:有考核窗显示
assessing;历史 records 状态文案齐全
C 端
- [ ] 首页能读到
category / carousel_only / score
- [ ] LV2 及以下用户考核页不展示「考核中」假进度
8. 附录:TipsLevel 速查(本环境)
| 展示 |
wire |
| Lv1 普通会员 |
1 |
| Lv2 个人推广 |
2 |
| Lv3 短剧体验官 |
3 |
| Lv4 人气推荐官 |
4 |
| Lv5 爆款风向官 |
5 |
| Lv6 |
6 |
| Lv7 |
7 |
升级补贴相关页面的「≥ Lv3」一律按 wire ≥ 3 判断。