xs454_admin_export_frontend.md
XS454-管理后台,硬币明细的来源改为具体的UID和部分数据增加导出功能/xs454_admin_export_frontend.md · 9.3 KB · 2026-11-19 15:09:42
原始文件 下载

XS454 管理后台导出 & 流水展示 — 前端对接

分支:test-old | 对接方:管理后台(主)、C 端 App / H5(辅) 范围:硬币明细「来源 / 产品」展示;用户 / 硬币明细 / 订单 / 提现 / 支持团队五个列表导出。

通用约定:


一、管理后台 · 硬币明细列表(字段扩展)

接口

项 值
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 且回查不到时展示 -。


二、管理后台 · 五个导出接口

通用行为

  1. 请求体 = 对应列表接口的筛选条件(与列表同源 Request)。
  2. 不要传分页导出也行:服务端忽略列表页的 offset/limit 语义,按筛选条件全量导出,上限 10 万行。
  3. 成功响应:
{ "url": "export/users/2026-03-19/1710820000123456.xlsx" }
  1. 下载地址:在静态资源域名后拼接 /static/ + url
    例:https://{cdn-or-api-host}/static/export/users/2026-03-19/xxx.xlsx
    (与现网抽奖导出 ExportLottery 的 url 用法一致。)
  2. 文件为 .xlsx,表头中文见下表。
  3. 空值统一导出为 -。

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}」;值为 - 时可隐藏该行。


四、联调检查清单

管理后台

C 端


五、接口速查

能力 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>。