admin_new_features_frontend.md
XS451-墨西哥1.0(管理后台)/admin_new_features_frontend.md · 9.3 KB · 2026-11-19 15:09:42
原始文件 下载

管理后台新增能力 — 前端对接

面向 管理后台(主)与 C 端展示字段(辅)。分支:test-old。

支持等级枚举请统一按 LV1…LV7(wire 1…7)解析,详见 tips_level_frontend.md。

通用约定:


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
}

响应

{
  "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
}

更新注意

列表项新增回显

{
  "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


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

用途建议:

6.2 升级补贴考核信息(C 端既有)

Path /v1/upgrade_subsidy_check_info/get

行为收紧(与后台明细一致):

字段形态不变:fans_count、target_fans_count、growth_rate、active_value、target_active_value、growth_rate_active_value。


7. 联调检查清单

管理后台

C 端


8. 附录:TipsLevel 速查(本环境)

展示 wire
Lv1 普通会员 1
Lv2 个人推广 2
Lv3 短剧体验官 3
Lv4 人气推荐官 4
Lv5 爆款风向官 5
Lv6 6
Lv7 7

升级补贴相关页面的「≥ Lv3」一律按 wire ≥ 3 判断。