upgrade_subsidy_admin_issue_frontend.md
XS452-墨西哥的升级补贴改为用户找客服发放/upgrade_subsidy_admin_issue_frontend.md · 10.0 KB · 2026-11-19 15:09:42
原始文件 下载

升级补贴改为后台发放 — 前端对接文档

分支:mx-prod | 对接方:管理后台(主)、C 端 App / H5(辅) 变更点:用户「手动领取」改为「管理员发放」,支持单个、批量勾选、一键全量。

通用约定(与管理后台其它接口一致):


一、管理后台

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] }

2.3 一键全量发放

{ "max_count": 500 }

响应

{
  "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 可能为空数组。

幂等与并发(前端需要知道的)


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/手机号/昵称)、待发放金额下限。

发放交互

  1. 单个发放:行内按钮 → 二次确认弹窗(展示昵称、等级、待发放金额)→ 调 {user_id}。
  2. 批量发放:表格多选 → 底部「批量发放(N 人,合计 ¥X)」→ 确认 → 调 {user_ids}。
  3. 一键全量:页面右上「发放全部待发放」→ 确认弹窗展示全站待发放总额 → 调 {} 或 {max_count:500}。
  4. 结果提示: - 成功:成功发放 {issued_count} 人,共 {issued_amount} 硬币(如有跳过/失败,追加「跳过 K,失败 J」) - has_more = true:按钮变为「继续发放下一批(还有剩余)」。
  5. 成功后刷新列表与顶部汇总。

文案建议


二、C 端(用户端)

1. 领取接口已废弃

POST /v1/upgrade_subsidy/receive

前端处理:新版本应隐藏「领取」按钮/入口;老版本点击后按 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 调整建议

  1. 移除领取按钮,改为说明文案: - 升级补贴由平台统一发放,发放后自动到账,可在明细中查看
  2. 考核页保留「待发放 / 已发放累计」两块数值(只读)。
  3. 老版本兼容:仅当 can_receive === true 才展示按钮(当前不会为 true)。
  4. 若产品需要,可在补贴页加「到账记录」入口(数据来源仍为硬币流水,类型 TYPE_UPGRADE_SUBSIDY)。

三、联调检查清单

管理后台

C 端

资金核对


四、兼容性说明

场景 行为
老版 App 点领取 返回 24027,不重复到账
老版后台(若仍传 {id}) 兼容,按单条发放处理;但返回体是汇总结构,老前端若按空对象解析不会报错(多出字段被忽略)
并发领取 + 后台发放 同一用户咨询锁串行,只会发放一次
结算 cron 与发放并发 结算改为原子累加,不会把已发放金额写回