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 |
后端已解析;无值时为 "-" |
{
"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 且回查不到时展示 -。
二、管理后台 · 五个导出接口
通用行为
- 请求体 = 对应列表接口的筛选条件(与列表同源 Request)。
- 不要传分页导出也行:服务端忽略列表页的
offset/limit 语义,按筛选条件全量导出,上限 10 万行。
- 成功响应:
{ "url": "export/users/2026-03-19/1710820000123456.xlsx" }
- 下载地址:在静态资源域名后拼接
/static/ + url
例:https://{cdn-or-api-host}/static/export/users/2026-03-19/xxx.xlsx
(与现网抽奖导出 ExportLottery 的 url 用法一致。)
- 文件为
.xlsx,表头中文见下表。
- 空值统一导出为
-。
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 |
机器人名 / 短剧名 / 月卡或年卡;无则 "-" |
{
"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>。