升级补贴改为后台发放 — 前端对接文档
分支:
mx-prod| 对接方:管理后台(主)、C 端 App / H5(辅) 变更点:用户「手动领取」改为「管理员发放」,支持单个、批量勾选、一键全量。
通用约定(与管理后台其它接口一致):
- 管理端接口均为
POST,JSON body - 时间字段为 Unix 秒(
int64) - 金额为十进制 string(如
"100"、"1560.5") - 失败看响应里的业务
code
一、管理后台
1. 升级补贴列表(字段扩展)
POST /v1/man/upgrade_subsidies/list
请求
{
"offset": 0,
"limit": 20,
"sort": "id",
"order": "DESC",
"user_id": 0,
"status": 2,
"keyword": "1380013",
"min_total_amount": "10"
}
| 字段 | 类型 | 说明 |
|---|---|---|
user_id |
int64 | 可选,精确匹配用户 |
status |
enum | 可选,1=已发放、2=待发放、0/不传=全部 |
keyword |
string | 新增。用户ID / 手机号 / 昵称 模糊搜索 |
min_total_amount |
string | 新增。待发放金额下限,如 "10" 表示 ≥10 |
响应
{
"total": 128,
"all_wait_amount": "12860",
"all_issued_amount": "45200",
"upgrade_subsidies": [
{
"id": 9001,
"user_id": 100234,
"current_level": 4,
"max_level": 5,
"next_subsidy_at": 1733000000,
"total_subsidy_amount": "180",
"received_subsidy_amount": "360",
"last_subsidy_at": 1730000000,
"status": 2,
"subsidy_type": 1,
"user": {
"user_id": 100234,
"nickname": "张三",
"mobile": "13800138000",
"tips_level": 4,
"avatar": "https://..."
}
}
]
}
| 新增字段 | 说明 |
|---|---|
all_wait_amount |
全站待发放总额(不随筛选变化),用于页面头部 |
all_issued_amount |
全站已发放总额 |
upgrade_subsidies[].user |
用户精简信息(user_id / nickname / mobile / tips_level / avatar) |
upgrade_subsidies[].received_subsidy_amount |
已发放累计(原有字段,列表可直接展示) |
status:2待发放(可操作「发放」)、1已发放(只读)。total_subsidy_amount:待发放金额;为"0"时不可发放(后端会跳过)。
2. 发放升级补贴
POST /v1/man/upgrade_subsidies/issue
三种用法三选一,同时传多个目标会返回参数错误(11011)。
2.1 单个用户发放
{ "user_id": 100234 }
或按补贴记录 ID(列表行的 id):
{ "id": 9001 }
2.2 批量发放(勾选)
{ "user_ids": [100234, 100235, 100236] }
- 单次最多 500 个,超出报
11011 - 后端自动去重、忽略
<0的非法 ID
2.3 一键全量发放
{ "max_count": 500 }
- 不传任何目标字段即「全量发放所有待发放」
max_count可选:单次处理条数,默认500,上限2000- 返回
has_more = true时表示还有剩余,前端提示「继续发放」再调一次即可
响应
{
"issued_count": 12,
"issued_amount": "1560",
"skipped_count": 3,
"failed_count": 1,
"failures": [
{ "user_id": 100999, "reason": "无升级补贴记录" }
],
"has_more": true
}
| 字段 | 说明 |
|---|---|
issued_count |
本次成功发放人数 |
issued_amount |
本次发放总金额(string) |
skipped_count |
跳过数(已发放 / 待发放为 0 / 状态非待发放) |
failed_count |
失败数(单条失败不影响整批) |
failures[] |
失败明细:user_id + reason。reason 为通用文案(如「发放失败,请重试」「无升级补贴记录」),不要依赖其内容做分支判断 |
has_more |
全量模式下是否还有剩余待发放 |
错误码
| code | 含义 | 前端处理 |
|---|---|---|
11011 |
参数错误(目标冲突 / user_ids 超 500 / 金额格式非法) | 提示检查选择 |
14023 |
无管理权限(非管理员) | 隐藏入口 / 提示无权限 |
11007 |
操作过于频繁(有其它发放任务在执行,30s 内重复提交) | 提示稍后重试 |
24028 |
没有待发放的升级补贴(按 id/user_id/user_ids 指定的目标查不到补贴记录) |
提示「该用户暂无升级补贴记录」 |
11003 / 11009 |
服务 / 数据库异常 | 通用错误提示,可重试 |
成功时一定返回上面结构(不再是空对象),请按字段取值;
failures可能为空数组。
幂等与并发(前端需要知道的)
- 同一个用户重复点「发放」不会重复到账:第二次会返回
skipped_count +1。 - 全量发放有 30 秒全局去重锁:两个管理员同时点,后一个会收到
11007。 - 单条失败不会回滚其它用户,请以
issued_count/failures为准提示结果。
3. 管理后台 UI 建议
列表页
| 列 | 数据 |
|---|---|
| 用户 | user.nickname + user.user_id + Lv{user.tips_level} |
| 等级 | current_level / max_level |
| 待发放 | total_subsidy_amount |
| 已发放 | received_subsidy_amount |
| 下次考核 | next_subsidy_at |
| 状态 | status:2 → 「待发放」;1 → 「已发放(last_subsidy_at)」 |
| 操作 | status=2 且金额 >0 显示「发放」;否则置灰 |
顶部卡片:全站待发放 all_wait_amount、已发放 all_issued_amount。
筛选区:状态(待发放/已发放/全部)、关键字(用户ID/手机号/昵称)、待发放金额下限。
发放交互
- 单个发放:行内按钮 → 二次确认弹窗(展示昵称、等级、待发放金额)→ 调
{user_id}。 - 批量发放:表格多选 → 底部「批量发放(N 人,合计 ¥X)」→ 确认 → 调
{user_ids}。 - 一键全量:页面右上「发放全部待发放」→ 确认弹窗展示全站待发放总额 → 调
{}或{max_count:500}。 - 结果提示:
- 成功:
成功发放 {issued_count} 人,共 {issued_amount} 硬币(如有跳过/失败,追加「跳过 K,失败 J」) -has_more = true:按钮变为「继续发放下一批(还有剩余)」。 - 成功后刷新列表与顶部汇总。
文案建议
- 待发放为空时:
暂无待发放的升级补贴 - 已发放行:
已发放 · {时间} - 全量确认:
将为 {N} 位用户发放共 {amount} 硬币,发放后立即到账且不可撤销,确认继续?
二、C 端(用户端)
1. 领取接口已废弃
POST /v1/upgrade_subsidy/receive
- 仍保留路由(老版本 App 不会 404),但不再发放硬币
- 固定返回业务码
24027:升级补贴由平台统一发放,请留意到账
前端处理:新版本应隐藏「领取」按钮/入口;老版本点击后按 24027 的文案提示即可。
2. 补贴信息接口新增字段
POST /v1/upgrade_subsidies/get
{
"lv3_amount": "20",
"lv4_amount": "50",
"lv5_amount": "100",
"lv6_amount": "200",
"lv7_amount": "500",
"total_subsidy_amount": "180",
"received_subsidy_amount": "360",
"can_receive": false,
"next_subsidy_at": 1733000000,
"next_subsidy_amount": "100",
"max_level_upgrade_at": 1729000000
}
| 字段 | 说明 | 展示建议 |
|---|---|---|
can_receive |
新增,恒为 false |
用它决定是否展示「领取」按钮;false 时必须隐藏 |
received_subsidy_amount |
新增,已发放累计 | 「已发放累计」 |
total_subsidy_amount |
语义变为「待发放金额(只读)」 | 「待发放」 |
next_subsidy_at / next_subsidy_amount |
下次考核时间 / 预计金额 | 保留原展示 |
3. C 端 UI 调整建议
- 移除领取按钮,改为说明文案:
-
升级补贴由平台统一发放,发放后自动到账,可在明细中查看 - 考核页保留「待发放 / 已发放累计」两块数值(只读)。
- 老版本兼容:仅当
can_receive === true才展示按钮(当前不会为 true)。 - 若产品需要,可在补贴页加「到账记录」入口(数据来源仍为硬币流水,类型
TYPE_UPGRADE_SUBSIDY)。
三、联调检查清单
管理后台
- [ ] 列表能按
status=2筛出待发放,all_wait_amount与各行合计一致 - [ ]
keyword用用户ID / 手机号 / 昵称都能搜到同一用户 - [ ] 单个发放后:状态变「已发放」、
received_subsidy_amount增加、顶部汇总变化 - [ ] 批量勾选 20 人(含 1 个已发放用户)→ 返回
issued_count=19, skipped_count=1 - [ ] 全量发放
has_more=true→ 点「继续发放」能处理剩余 - [ ] 两个标签页同时点全量 → 其中一个收到
11007 - [ ] 对已发放用户再点发放 → 返回成功且
skipped_count=1、余额不变 - [ ] 对没有任何补贴记录的用户发放 →
24028 - [ ] 非管理员账号看不到入口 / 调用返回
14023
C 端
- [ ] 补贴页不再显示「领取」按钮
- [ ] 「待发放」「已发放累计」数值正确
- [ ] 老版本点领取 → 提示
24027,余额不变 - [ ] 后台发放后重新进入页面,已发放累计增加、待发放减少
资金核对
- [ ] 每笔发放对应一条硬币流水:类型「升级补贴」,来源「管理员」
- [ ] 发放前后用户可用余额差额 =
issued_amount
四、兼容性说明
| 场景 | 行为 |
|---|---|
| 老版 App 点领取 | 返回 24027,不重复到账 |
老版后台(若仍传 {id}) |
兼容,按单条发放处理;但返回体是汇总结构,老前端若按空对象解析不会报错(多出字段被忽略) |
| 并发领取 + 后台发放 | 同一用户咨询锁串行,只会发放一次 |
| 结算 cron 与发放并发 | 结算改为原子累加,不会把已发放金额写回 |