# XS454 管理后台导出 & 流水展示 — 前端对接

> 分支：`test-old`　｜　对接方：管理后台（主）、C 端 App / H5（辅）
> 范围：硬币明细「来源 / 产品」展示；用户 / 硬币明细 / 订单 / 提现 / 支持团队五个列表导出。

通用约定：

- 管理端接口均为 `POST`，JSON body
- 时间字段为 Unix 秒（`int64`）
- 金额为十进制 **string**
- 失败看响应里的业务 `code`
- 导出超限（筛选结果 **> 100000** 行）返回参数错误，前端提示「导出条数超限，请缩小筛选范围」

---

## 一、管理后台 · 硬币明细列表（字段扩展）

### 接口

| 项 | 值 |
|----|----|
| Path | `POST /v1/man/users/point_ledger/list` |
| 请求体 | 与现网 `ListUserPointLedgerRequest` 相同（无新增筛选项） |

### 响应新增字段

`ledgers[]` 每条流水新增：

| 字段 | JSON | 类型 | 说明 |
|------|------|------|------|
| 来源文案 | `sourceText` | string | 后端已拼好，**直接展示**，勿再拼 UID / 层级 |
| 产品名称 | `productName` | string | 后端已解析；无值时为 `"-"` |

```json
{
  "total": 100,
  "totalPoint": "1234.5",
  "ledgers": [
    {
      "id": 1,
      "userId": 10001,
      "point": "10",
      "after": "100",
      "type": 21,
      "refType": 2,
      "refId": 20002,
      "pointType": 1,
      "comment": "",
      "createdAt": 1732000000,
      "sourceText": "直推：+20002",
      "productName": "某某短剧"
    }
  ]
}
```

### 列表列建议

| 列 | 取值 |
|----|------|
| 来源 | `sourceText` |
| 产品 | `productName` |
| 其它列 | 保持现网（UID、时间、硬币类型、项目类型、金额、备注等） |

### `sourceText` 规则（只读了解，前端无需重算）

| 场景 | 展示示例 |
|------|----------|
| 本人短剧 / 机器人支持相关 | `用户+{uid}` |
| 支持返佣（1 起始层级） | `直推：+{下级uid}` / `二级：+…` … `五级：+…` |
| 解锁剧集 / VIP 返佣（0 起始层级） | 同上文案，层级从 extras `fan_level` 换算 |
| 管理员操作 | `管理员` |
| 其它用户关联 | `用户` |
| 无法判断 | `-` |

### `productName` 规则（只读了解）

| 流水类型 | 产品名 |
|----------|--------|
| 机器人支持支付 / 收益 / 结束返还 | 机器人标题；历史无标题则回查，仍无则 `-` |
| 短剧支持 / 收益 / 活跃值结束返还 | 短剧标题；历史无标题则回查，仍无则 `-` |
| 购买 / 消费剧集 | 订单商品名 |
| 购买 VIP | `月卡` / `年卡`（或订单商品名） |
| 其它类型 | `-` |

> 历史短剧流水**不会猜测**剧名；无 extras 且回查不到时展示 `-`。

---

## 二、管理后台 · 五个导出接口

### 通用行为

1. **请求体 = 对应列表接口的筛选条件**（与列表同源 Request）。
2. **不要传分页导出**也行：服务端忽略列表页的 `offset/limit` 语义，按筛选条件全量导出，上限 **10 万行**。
3. 成功响应：

```json
{ "url": "export/users/2026-03-19/1710820000123456.xlsx" }
```

4. 下载地址：在静态资源域名后拼接 `/static/` + `url`  
   例：`https://{cdn-or-api-host}/static/export/users/2026-03-19/xxx.xlsx`  
   （与现网抽奖导出 `ExportLottery` 的 `url` 用法一致。）
5. 文件为 `.xlsx`，表头中文见下表。
6. 空值统一导出为 `-`。

### 1. 导出用户列表

| 项 | 值 |
|----|----|
| Path | `POST /v1/man/users/export` |
| Body | 与 `POST /v1/man/users/list` 相同（`ListUserRequest`） |
| 入口 | 用户列表页「导出」按钮，带上当前筛选 |

**Excel 列**

| 列名 | 说明 |
|------|------|
| UID/邀请码 | 用户 ID |
| 粉丝邀请权限 | `允许` / `禁止`（见下方字段语义） |
| 业务员类型 / ID / 昵称 | 如 `业务员 / 100 / 张三`，无则 `-` |
| VIP状态 | 周卡 / 月卡 / 年卡 / 普通用户 / … |
| VIP到期日 | `yyyy-MM-dd HH:mm:ss`（业务时区） |
| 实名状态 | |
| 用户支持等级 | |
| 硬币余额 | 可用通用硬币 |
| 邮箱 / 手机 / 注册邀请码 | |
| 账号状态 / IP状态 | |
| 注册时间 | |

**粉丝邀请权限字段语义（重要）**

列表字段仍是 `isInviterFansDisabled`，**历史命名与字面相反**：

| `isInviterFansDisabled` | 展示 |
|-------------------------|------|
| `true` | **允许**邀请 |
| `false` | **禁止**邀请 |

导出与列表展示请统一用上表，不要按字段名字面理解。

---

### 2. 导出硬币明细

| 项 | 值 |
|----|----|
| Path | `POST /v1/man/users/point_ledger/export` |
| Body | 与 `POST /v1/man/users/point_ledger/list` 相同 |

**Excel 列**

| 列名 | 说明 |
|------|------|
| UID | |
| 时间 | |
| 硬币类型 | 通用 / 消费等 |
| 产品 | 同列表 `productName` |
| 项目类型 | 流水 type 中文 |
| 来源 | 同列表 `sourceText` |
| 硬币金额 | |
| 备注 | |

---

### 3. 导出订单列表

| 项 | 值 |
|----|----|
| Path | `POST /v1/man/order/export` |
| Body | 与 `POST /v1/man/order/list` 相同 |

**Excel 列**

| 列名 | 说明 |
|------|------|
| UID | |
| 创建时间 | |
| 商品类型 | VIP / 硬币包 / 剧集等 |
| 支付方式 | |
| 商品 | 商品名 |
| 数量 | |
| 单价 | |
| 合计 | 单价 × 数量 |
| 实付金额 | 订单 `totalAmount`（已含优惠后的实付，**不要再减券**） |
| 支付状态 | |

---

### 4. 导出提现列表

| 项 | 值 |
|----|----|
| Path | `POST /v1/man/withdrawal/export` |
| Body | 与 `POST /v1/man/withdrawal/list` 相同 |

> 注意：这是**列表筛选导出**，与现有渠道批量导出  
> `POST /v1/man/withdrawal/batch/export`（`BatchExportWithdrawal`）**不是同一个接口**，勿混用。

**Excel 列**

| 列名 | 说明 |
|------|------|
| UID | |
| 提交时间 | |
| 提币金额 | |
| 状态 | |
| 审核时间 | |
| 支持平台 | 提现渠道文案 |
| 到账时间 | |
| 银行名称 | |

---

### 5. 导出支持团队列表

| 项 | 值 |
|----|----|
| Path | `POST /v1/man/tips/team/export` |
| Body | 与 `POST /v1/man/tips/team/list` 相同 |

**Excel 列**

| 列名 | 说明 |
|------|------|
| UID/邀请码 | |
| 等级 | 支持等级 |
| 上级UID / 上级昵称 | |
| 个人业绩 | 当前固定 `-`（与现网列表未填一致） |
| 个人分红 | |
| 个人活跃值 | |
| 个人经验值 | 当前固定 `-`（与现网列表未填一致） |
| 铁粉活跃值 / 团队活跃值 | |
| 裂变层级 / 团队人数 | |
| 团队业绩 / 团队分红 | |
| 状态 | 正常 / 关闭邀请 / 团队封号 等 |

---

### 导出交互建议

| 项 | 建议 |
|----|------|
| 按钮位置 | 各列表筛选栏旁「导出」 |
| 加载 | 数据量大时可能较慢，按钮 loading，超时建议 ≥ 60s |
| 成功 | 用返回 `url` 打开 / 下载；或 `window.open(staticBase + '/static/' + url)` |
| 超限 | Toast：缩小筛选后再导出 |
| 权限 | 与对应列表接口同一套后台权限 |

---

## 三、C 端 · 硬币流水（字段扩展）

仅增加 **产品名称**，无 `sourceText`（C 端不展示后台「来源」列）。

| 接口 | Path |
|------|------|
| 流水列表 | `POST /v1/point/ledger/list` |
| 账单流水 V2 | `POST /v1/point/ledger/list/v2` |

### 响应新增

| 字段 | JSON | 类型 | 说明 |
|------|------|------|------|
| 产品名称 | `productName` | string | 机器人名 / 短剧名 / 月卡或年卡；无则 `"-"` |

```json
{
  "total": 20,
  "ledgers": [
    {
      "point": "10",
      "after": "100",
      "type": 21,
      "pointType": 1,
      "createdAt": 1732000000,
      "productName": "某某机器人",
      "label": 0,
      "typeGroup": 0
    }
  ]
}
```

展示建议：在流水副标题或详情行增加「产品：{productName}」；值为 `-` 时可隐藏该行。

---

## 四、联调检查清单

### 管理后台

- [ ] 硬币明细列表展示 `sourceText`、`productName`，不再前端拼来源
- [ ] 用户 / 硬币明细 / 订单 / 提现 / 支持团队五个列表均有导出按钮
- [ ] 导出带上当前筛选条件
- [ ] 导出成功能下载 xlsx，表头与上文一致
- [ ] 筛选结果 > 10 万有友好提示
- [ ] 粉丝邀请权限按「true=允许 / false=禁止」展示（列表与导出一致）
- [ ] 提现「列表导出」与「渠道批量导出」入口区分清楚

### C 端

- [ ] `ledger/list` 与 `ledger/list/v2` 能读到 `productName`
- [ ] 无产品名（`-`）时 UI 不突兀

---

## 五、接口速查

| 能力 | Method + Path | 请求体 |
|------|---------------|--------|
| 硬币明细列表 | `POST /v1/man/users/point_ledger/list` | 现网 |
| 导出用户 | `POST /v1/man/users/export` | `ListUserRequest` |
| 导出硬币明细 | `POST /v1/man/users/point_ledger/export` | `ListUserPointLedgerRequest` |
| 导出订单 | `POST /v1/man/order/export` | `ListOrderRequest` |
| 导出提现 | `POST /v1/man/withdrawal/export` | `ListWithdrawalRequest` |
| 导出支持团队 | `POST /v1/man/tips/team/export` | `ListTipsTeamRequest` |
| C 端流水 | `POST /v1/point/ledger/list` | 现网 |
| C 端账单 V2 | `POST /v1/point/ledger/list/v2` | 现网 |

导出统一响应：`{ "url": "<相对路径>" }` → 下载 `/static/<url>`。
