19 KiB
退款流水（GetRefundPayLogList）
自动生成于 2026-02-13 | 数据来源：实时 API
基本信息
| 属性 | 值 |
|---|---|
| 接口路径 | Order/GetRefundPayLogList |
| 完整 URL | https://pc.ficoo.vip/apiprod/admin/v1/Order/GetRefundPayLogList |
| 请求方法 | POST |
| Content-Type | application/json |
| 鉴权方式 | Bearer Token（Authorization 头） |
| ODS 对应表 | refund_transactions |
| 分页方式 | page + limit（最大 100） |
| 时间范围 | 需要（startTime / endTime） |
请求参数
| 参数名 | 类型 | 示例值 | 说明 |
|---|---|---|---|
startTime |
string | "2026-02-01 08:00:00" |
查询起始时间 |
endTime |
string | "2026-02-13 08:00:00" |
查询结束时间 |
siteId |
int | 2790685415443269 |
门店 ID |
page |
int | 1 |
页码（从 1 开始） |
limit |
int | 100 |
每页条数（最大 100） |
响应字段（共 32 个）
| # | 字段名 | 类型 | 示例值 |
|---|---|---|---|
| 1 | tenantName |
string | '朗朗桌球' |
| 2 | siteProfile |
object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 3 | id |
int | 3089577798995141 |
| 4 | site_id |
int | 2790685415443269 |
| 5 | tenant_id |
int | 2790683160709957 |
| 6 | pay_sn |
int | 0 |
| 7 | pay_amount |
float | -8.0 |
| 8 | pay_status |
int | 2 |
| 9 | pay_time |
string | '2026-02-10 23:41:06' |
| 10 | create_time |
string | '2026-02-10 23:41:06' |
| 11 | relate_type |
int | 1 |
| 12 | relate_id |
int | 3089548319804869 |
| 13 | is_revoke |
int | 0 |
| 14 | is_delete |
int | 0 |
| 15 | online_pay_channel |
int | 0 |
| 16 | payment_method |
int | 4 |
| 17 | balance_frozen_amount |
float | 0.0 |
| 18 | card_frozen_amount |
float | 0.0 |
| 19 | member_id |
int | 0 |
| 20 | member_card_id |
int | 0 |
| 21 | round_amount |
float | 0.0 |
| 22 | online_pay_type |
int | 0 |
| 23 | action_type |
int | 2 |
| 24 | refund_amount |
float | 0.0 |
| 25 | cashier_point_id |
int | 0 |
| 26 | operator_id |
int | 0 |
| 27 | pay_terminal |
int | 1 |
| 28 | pay_config_id |
int | 0 |
| 29 | channel_payer_id |
string | '' |
| 30 | channel_pay_no |
string | '' |
| 31 | check_status |
int | 1 |
| 32 | channel_fee |
float | 0.0 |
详细字段分析
以下内容迁移自旧版
refund_transactions-Analysis.md，包含字段的业务含义、枚举值、跨表关联等详细说明。
- 记录内容类型（这份 JSON 实际记录的是什么）
从字段组合和数值特征看，每条记录代表：
“一笔已发生的退款支付流水（资金层面的退款交易）”
特点：
pay_amount 全为负数（例如 -12.0, -44000.0, -3000.0），很明显是“钱从店里流出”的方向。
pay_status 全为 2，结合支付记录推测是“退款/完成状态”（至少表示“已处理完成”）。
action_type 全为 2，极大概率是“退款动作类型”的枚举。
relate_type 只出现 2 与 5，对应两类不同业务：一种是“消费类”，一种是“充值/储值类”（具体含义依赖系统配置，但肯定是区分不同业务来源）。
这份“退款记录”是 资金维度 的退款流水，不是“业务维度”的退款单（比如没记录退款原因、操作备注等）。业务上的退款原因应从对应的订单、充值记录或其他业务表中去追踪。
二、字段逐一说明（含数据类型 & 枚举推断）
下面按功能分组，对每个字段说明其含义、类型，是否枚举，以及这些记录中实际出现的取值。
- 门店 / 租户维度字段 tenantName
类型：string
示例："朗朗桌球"
含义：租户（商户）名称。
特点：本文件中固定为“朗朗桌球”，完全冗余于 siteProfile.shop_name。
作用：方便直接在流水中看到店名，无需再查门店档案。
tenant_id
类型：int
示例：2790683160709957
含义：租户/品牌 ID，全系统维度标识该商户。
特点：本文件中所有记录相同。
作用：
作为所有门店数据的“租户分区键”；
与其他 JSON 中同名字段一致，用来确认“同一商户”。
site_id
类型：int
示例：2790685415443269
含义：门店 ID。
特点：本文件中所有记录相同（单门店）。
作用：
关联其他数据表中同一门店的数据；
与 siteProfile.id 一致，是 siteProfile 的主键。
siteProfile
类型：object
含义：门店信息快照，结构与其他 JSON 中的 siteProfile 完全一致。包含字段包括但不限于：
id：门店 ID（= site_id）；
shop_name：店名；
full_address / address：地址；
longitude / latitude：经纬度；
business_tel：电话；
一系列门店配置项（灯控、考勤、营业状态等）。
作用：
为每条退款记录附带一份当时的门店元信息；
提供冗余信息，避免联表查询门店档案。
- 退款流水主键与关联业务字段 id
类型：int
示例：2955202296416389
含义：本条 退款流水 的唯一 ID。
特点：
每条记录一个不同的长整型 ID，疑似雪花 ID 或类似分布式 ID。
作用：作为退款记录表主键，内部检索用。
relate_type
类型：int（枚举）
当前取值：{2, 5}
含义：本退款对应的“业务类型”。
结合支付记录的 relate_type 推测：
1（在支付记录中存在）：某类订单支付（可能是结账单支付）。
2：另一类业务，比如“台费/商品类消费单”或“综合订单”；在退款记录中有多条。
5：通常用来标记“储值/充值类业务”，这里的几条金额很大，形态上很像“退充值款”。
结构作用：
不直接指向某张表，而是先告知“这是哪种业务”，再配合 relate_id 确定具体业务记录。
relate_id
类型：int
示例：2948246513454661
含义：本次退款关联的业务 ID。
对于 relate_type = 2：应该对应某个订单/结算的主键；
对于 relate_type = 5：应该对应某条充值记录或储值业务记录的主键。
特点：
同一个 relate_id 可能对应多条退款流水（例如先退 88.33，又退 0.67，对应两个不同撤销动作，都关联到同一 relate_id）。
与其他 JSON 的关系：
在“支付记录”中也有 relate_type + relate_id 组合，含义一致：指向业务实体；
本文件里的退款流水和“支付记录”是通过“共同指向同一业务实体”来间接关联，而不是直接指向支付记录。
- 时间字段 create_time
类型：string，格式为 "YYYY-MM-DD HH:MM:SS"
示例："2025-11-03 15:36:19"
含义：本条退款流水在系统内创建时间。
特点：
当前数据中，create_time 与 pay_time 完全相同，说明系统在退款发生时立刻生成流水记录。
如果未来有“申请退款-审核-执行”流程，create_time 有可能偏早。
pay_time
类型：string，格式同上
示例："2025-11-03 15:36:19"
含义：退款在支付渠道层面实际发生的时间。
特点：
当前数据中与 create_time 一致，可以视为“退款完成时间”。
结构提示：
保留 create_time 和 pay_time 两个字段，说明系统设计上区分“记录生成时间”与“渠道交易时间”。如果引入异步处理，二者可能就会出现差异。
- 金额相关字段 pay_amount
类型：float
示例：-12.0, -44000.0, -3000.0, -0.67 等
含义：本次退款的 资金变动金额。
特征很重要：
全部为负数，绝对值就是退款金额。
表示“从门店账户流出的金额”（相对于支付记录中的正数进账）。
结构意义：
这份“退款记录.json”在设计上没有专门用 refund_amount 存实际退款额，而是直接用 pay_amount < 0 表示退款金额大小。
这点对之后做数据抽取/ETL 很重要：判断退款金额只看 pay_amount 的负数；refund_amount 字段在当前实现中并未使用。
refund_amount
类型：float
当前全部为：0.0
含义（推测）：
设计上本应显示“实际退款金额”（正数），与 pay_amount 配合使用；
但在目前实现里，系统只用了 pay_amount 表示金额，并没有填充这个字段。
在当前数据中的状态：
可以视为“保留字段/未启用”。
balance_frozen_amount
类型：float
当前：全部 0.0
含义（推测）：
涉及会员储值卡退款时，暂时冻结的余额金额；
用于一些“先冻结后解冻/退款”的逻辑。
当前数据状态：
所有退款记录的 member_id / member_card_id 都是 0，对应的冻结金额自然也是 0；
说明这 11 笔退款都不是“退到会员卡余额”，而是对普通支付渠道（例如刷卡）的退款。
card_frozen_amount
类型：float
当前：全部 0.0
含义：与上一个类似，偏向“某张卡的被冻结金额”，也与会员卡/储值账户相关。
状态同上：本数据中未发生“卡冻结退款”。
round_amount
类型：float
当前：全部 0.0
含义（推测）：
舍入金额/抹零金额；
在某些场景下，如果退款金额存在四舍五入等调整，会单独记录到这个字段。
当前未使用。
channel_fee
类型：float
当前：全部 0.0
含义（推测）：
第三方支付渠道对本次退款收取的手续费；
正常应该在“通道成本核算”里用到。
当前数据中没有任何通道手续费记录（可能通道不收手续费，或者手续费隐藏在其他费用内）。
- 支付方式 / 渠道相关字段
结合“支付记录.json”一起看，更容易理解这些字段的结构设计。
payment_method
类型：int（枚举）
当前取值：仅 4
在“支付记录.json”中出现的取值有：2、4。
含义（推测）：
支付/退款的 方式类型：
2：某种线上支付渠道（很可能是微信）；
4：另一种支付方式（很可能是银行卡 POS 或现金），当前这批退款全是 4，说明都是同一支付方式的退款。
具体枚举值定义要以“非球科技”系统文档为准，但可以确定是“支付方式枚举”。
online_pay_channel
类型：int（枚举）
当前：全部 0
在“支付记录.json”里同样全部为 0。
含义（推测）：
线上支付的 渠道编号，例如：
0：线下/默认渠道；
其他值（如 1,2）可能分别代表微信、支付宝等。
当前门店的退款记录全部为 0，说明这 11 笔退款要么是线下渠道，要么系统没有区分线上子渠道。
online_pay_type
类型：int（枚举）
当前：全部 0
含义（推测）：
在线退款的类型：
0：原路退回；
其他值（如果存在）可能代表“退到余额”、“退到其他银行卡”等。
当前数据中未出现其他值，说明门店的退款都是默认策略（很可能就是原路退回）。
pay_terminal
类型：int（枚举）
当前：全部 1
含义（推测）：
退款所使用的 终端类型：
1：前台收银端；
其他值可能为：小程序、自助机、后台管理系统等。
本文件中所有退款都来自同一种终端类型。
pay_config_id
类型：int
当前：全部 0
含义（推测）：
支付配置 ID，例如商户在“非球科技”内配置的某一条支付通道（某个微信商户号、银联通道）的主键。
当前数据未填（可能全部走默认配置），因此都是 0。
channel_payer_id
类型：string
当前：全部为空字符串 ""
含义（推测）：
支付渠道侧的 payer ID，例如微信 openid、银行卡号掩码等。
当前数据未使用（可能系统没回写或导出时屏蔽了）。
channel_pay_no
类型：string
当前：全部为空字符串 ""
含义（推测）：
第三方支付平台的交易号（如微信支付单号、支付宝交易号等）。
当前为空：要么是通道未返回，要么导出接口没带出这部分数据。
- 会员关联字段 member_id
类型：int
当前：全部 0
含义：
租户内部的会员 ID（对应会员档案中的某个主键）。
当前状态：
这 11 笔退款中没有任何一笔标记了会员 ID，说明是“非会员退款”或退款没绑定到会员档案。
member_card_id
类型：int
当前：全部 0
含义：
关联的会员卡账户 ID（对应“储值卡列表”或“会员档案”中的某一张卡）。
当前状态：
没有记录任何“退到某张会员卡”的情况；
结合 balance_frozen_amount = 0、card_frozen_amount = 0，可以确定当前导出时间范围的退款全部是对外部支付渠道的退款，没有会员卡内部余额的退款。
- 状态标志字段 pay_status
类型：int（枚举）
当前：全部 2
在“支付记录.json”中同样只有值 2。
含义（推测）：
支付/退款状态枚举：
1 可能为“待支付/处理中”；
2 为“已完成”（支付成功 / 退款完成）。
鉴于所有支付、退款记录导出时都已经完成，因此本文件中只有 2。
is_revoke
类型：int（枚举）
当前：全部 0
含义（推测）：
是否撤销型退款/撤销原支付：
0：正常退款；
1：撤销类型操作。
当前为 0，说明所有记录按“正常退款”处理，而不是“支付撤销”这类特殊类型。
is_delete
类型：int（枚举）
当前：全部 0
含义：逻辑删除标志。
0：未删除；
1：已删除（逻辑上标记删除，但记录仍存在）。
当前数据中所有退款记录都处于“未删除”状态。
check_status
类型：int（枚举）
当前：全部 1
含义（推测）：
审核状态：
1：已审核/通过；
其他值可能表示“待审核/审核拒绝”等。
结构意义：
说明系统设计上支持“退款需审核”的流程，但当前导出时这些记录已经审过。
action_type
类型：int（枚举）
当前：全部 2
含义（推测）：
行为类型：
1：支付；
2：退款；
或类似的“资金动作类型”。
结合：
支付记录并没有此字段，退款记录有 action_type=2；
再加上 pay_amount<0，基本可以确定这是“退款动作”的枚举标识。
- 其他操作相关字段 cashier_point_id
类型：int
当前：全部 0
含义（推测）：
收银点 ID，例如前台 1、前台 2、自助机等。
当前数据中未区分具体收银点，统一为 0。
operator_id
类型：int
当前：全部 0
含义：
执行该退款操作的操作员 ID。
当前全部为 0，说明：
要么系统没有记录具体操作员；
要么导出接口未把这个信息带出（但字段已预留）。
三、与其它 JSON 文件的关联关系（结构层面）
从字段角度，退款记录.json 与其它数据之间主要有以下关联：
与门店/租户：
tenant_id ↔ 所有 JSON 中的 tenant_id；
site_id ↔ 所有 JSON 中的 site_id；
siteProfile 内部的 id、tenant_id 与上述字段一致。 → 说明：退款记录明确挂在“朗朗桌球”这个门店下，与其它消费、库存、助教等记录在同一数据域。
与支付记录（支付记录.json）：
两者都拥有：
relate_type + relate_id：指向同一个业务实体（订单、充值等）；
payment_method、online_pay_channel：同一套支付方式枚举；
pay_amount、pay_status、pay_time：结构一致。
差异：
支付记录的 pay_amount 为正数（进账），退款记录的 pay_amount 为负数（出账）；
退款记录多了一些退款专用字段：refund_amount、balance_frozen_amount、card_frozen_amount、is_revoke、online_pay_type、channel_fee 等。
结构性结论：
支付记录 = 资金正向流入流水；
退款记录 = 资金反向流出流水；
通过 同一个 relate_type + relate_id 指向同一业务主单，从而把“支付”和“退款”绑定在同一个订单/充值实体之上。
与订单/充值等业务表：
relate_type 通知你“这是哪种业务”，relate_id 是那种业务表里的主键。
在已导出的 JSON 中，对应的业务表大致为：
relate_type = 2 → 多数对应“订单类业务”（例如结账记录、小票详情、消费明细）；
relate_type = 5 → 多数对应“充值类业务”（对照余额变更记录、充值记录）。
虽然我们在当前导出中没拿到完整的充值记录明细，但这两字段的存在，已经把退款挂在“业务主单”的坐标上了。
与会员体系：
通过 member_id、member_card_id 理论上可以关联到：
会员档案（会员档案.json）；
储值卡列表（储值卡列表.json）；
余额变更记录（余额变更记录.json）。
当前这批数据里二者均为 0，说明这 11 笔退款完全与会员卡无关，是纯支付渠道层面的退款。
结构意义：
一旦未来有“退到储值卡”的场景，member_id/member_card_id 会出现非 0 值，进而通过上述表串联起“资金退款 → 会员余额变更 → 卡账户状态”。
四、结构层面的额外重要线索（不涉及金额分析）
正/负号决定资金方向：
退款记录并没有用一个单独的“类型字段 + 正数金额”来描述退款，而是直接用 pay_amount 为负，配合 action_type=2 表示“退款”。
对后续数据对接/迁移很关键：判断“是支付还是退款”，不能只看 pay_status，而是要同时看 action_type + pay_amount 的符号。
业务实体与资金流水是一对多关系：
两条记录中 relate_id 相同但 id 不同的情况，意味着同一业务单可以产生多笔退款（例如分批退）。
这也解释了为什么系统用 relate_type + relate_id 来指业务，而“支付 record ID / 退款 record ID”本身只是在资金流水表内唯一。
退款文件是资金维，不含任何“原因类字段”：
没有“退款原因”、“备注”、“操作人姓名”等文本字段；
“是否审核通过”、“是否撤销”等只通过状态位表示；
说明系统将“业务解释”留给业务表（订单/充值），这里只关心钱动了多少、从哪儿来、到哪儿去。
会员退款与普通退款在结构上是统一模型：
即使当前数据里没有会员退款记录，字段已经预留了：
member_id / member_card_id；
balance_frozen_amount / card_frozen_amount；
online_pay_type 等。
一旦发生“退到余额/退到会员卡”的场景，这份结构可以无缝承载，不需要变更表结构。
审核流程是结构预留但未复杂使用：
有 check_status 字段，也有 is_revoke，表明系统支持“审核 + 撤销”这类管理流程。
当前导出数据中全部为 check_status=1、is_revoke=0，说明：
要么店内流程简单，退款都直接通过；
要么导出只包含“已审核通过的记录”。
与支付记录共用枚举体系：
payment_method、online_pay_channel、pay_terminal、relate_type 等枚举字段，与支付记录完全共用。
这一点对于你后续构建统一的资金流水视图很关键：可以把支付记录和退款记录 union 在一起，通过这些枚举和正负金额，就能得到一张统一的资金流水大表。