# 升级补贴改为后台发放 — 前端对接文档

> 分支：`mx-prod`　｜　对接方：管理后台（主）、C 端 App / H5（辅）
> 变更点：用户「手动领取」改为「管理员发放」，支持**单个**、**批量勾选**、**一键全量**。

通用约定（与管理后台其它接口一致）：

- 管理端接口均为 `POST`，JSON body
- 时间字段为 Unix 秒（`int64`）
- 金额为十进制 **string**（如 `"100"`、`"1560.5"`）
- 失败看响应里的业务 `code`

---

## 一、管理后台

### 1. 升级补贴列表（字段扩展）

`POST /v1/man/upgrade_subsidies/list`

#### 请求

```json
{
  "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 |

#### 响应

```json
{
  "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 单个用户发放

```json
{ "user_id": 100234 }
```

或按补贴记录 ID（列表行的 `id`）：

```json
{ "id": 9001 }
```

#### 2.2 批量发放（勾选）

```json
{ "user_ids": [100234, 100235, 100236] }
```

- 单次最多 **500** 个，超出报 `11011`
- 后端自动去重、忽略 `<0` 的非法 ID

#### 2.3 一键全量发放

```json
{ "max_count": 500 }
```

- 不传任何目标字段即「全量发放所有待发放」
- `max_count` 可选：单次处理条数，默认 `500`，上限 `2000`
- 返回 `has_more = true` 时表示还有剩余，前端提示「继续发放」再调一次即可

#### 响应

```json
{
  "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/手机号/昵称）、待发放金额下限。

#### 发放交互

1. **单个发放**：行内按钮 → 二次确认弹窗（展示昵称、等级、待发放金额）→ 调 `{user_id}`。
2. **批量发放**：表格多选 → 底部「批量发放（N 人，合计 ¥X）」→ 确认 → 调 `{user_ids}`。
3. **一键全量**：页面右上「发放全部待发放」→ 确认弹窗展示全站待发放总额 → 调 `{}` 或 `{max_count:500}`。
4. **结果提示**：
   - 成功：`成功发放 {issued_count} 人，共 {issued_amount} 硬币`（如有跳过/失败，追加「跳过 K，失败 J」）
   - `has_more = true`：按钮变为「继续发放下一批（还有剩余）」。
5. 成功后刷新列表与顶部汇总。

#### 文案建议

- 待发放为空时：`暂无待发放的升级补贴`
- 已发放行：`已发放 · {时间}`
- 全量确认：`将为 {N} 位用户发放共 {amount} 硬币，发放后立即到账且不可撤销，确认继续？`

---

## 二、C 端（用户端）

### 1. 领取接口已废弃

`POST /v1/upgrade_subsidy/receive`

- 仍保留路由（老版本 App 不会 404），但**不再发放硬币**
- 固定返回业务码 **`24027`**：`升级补贴由平台统一发放，请留意到账`

前端处理：新版本应**隐藏「领取」按钮/入口**；老版本点击后按 `24027` 的文案提示即可。

### 2. 补贴信息接口新增字段

`POST /v1/upgrade_subsidies/get`

```json
{
  "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`）。

---

## 三、联调检查清单

**管理后台**

- [ ] 列表能按 `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 与发放并发 | 结算改为原子累加，不会把已发放金额写回 |
