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

面向 **管理后台**（主）与 **C 端展示字段**（辅）。分支：`test-old`。

> 支持等级枚举请统一按 `LV1…LV7`（wire `1…7`）解析，详见 [tips_level_frontend.md](./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` |

### 请求

```json
{
  "user_id": 123,
  "offset": 0,
  "limit": 20,
  "sort": "created_at",
  "order": "DESC",
  "started_at": 0,
  "ended_at": 0
}
```

- `started_at` / `ended_at`：可选，Unix 秒；`0` 表示不限。

### 响应

```json
{
  "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 新增

```json
{
  "category": 3,
  "carousel_only": false
}
```

#### 列表筛选

```json
{
  "language": "ind",
  "category": 2,
  "offset": 0,
  "limit": 20
}
```

- `category = 0`（或不传）：**不按类别过滤**（全部）。

#### 更新注意

- 更新时若不传 / 传 `category=0`，后端**保留原类别**，不会被清零。
- 需要改类别时必须显式传 `1/2/3`。

#### 列表项新增回显

```json
{
  "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`） |
| 更新清空 | 传 `""` 可清空为未填 |

创建 / 更新示例：

```json
{ "score": "8.5" }
```

列表回显：

```json
{ "score": "8.5" }
```

未填时回显 `""`。

### `latest_home_group_id`（只读回显）

| 项 | 说明 |
|----|------|
| 谁写入 | **仅后端**：当本次更新**新勾选**了「首页板块」类分组时，取请求顺序中最后一个首页板块 ID |
| 前端 | 列表/详情展示即可；**不要**在 update body 里手写覆盖 |
| 无新增首页板块 | 保留库中原值，不会被清零 |

回显示例：

```json
{ "latest_home_group_id": 12 }
```

`0` 表示尚无。

### `resource_link`

- 创建/更新请求里字段仍可能存在，但 **更新接口已不再写入** `resource_link`。
- 前端可隐藏或只读展示历史值，勿再当作可编辑必需项。

---

## 5. 升级补贴奖励明细（用户 / 活动）

### 接口

| 项 | 值 |
|----|----|
| Path | `/v1/man/upgrade_subsidies/detail` |

### 请求

```json
{
  "user_id": 123,
  "offset": 0,
  "limit": 20,
  "sort": "triggered_at",
  "order": "DESC"
}
```

### 响应结构

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

**行为收紧**（与后台明细一致）：

- 用户等级 **&lt; 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` 判断。
