初始提交：飞球 ETL 系统全量代码

docs/api-reference/endpoints/refund_transactions.md

@@ -0,0 +1,711 @@
+# 退款流水（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`，包含字段的业务含义、枚举值、跨表关联等详细说明。
+
+2. 记录内容类型（这份 JSON 实际记录的是什么）
+
+从字段组合和数值特征看，每条记录代表：
+
+“一笔已发生的退款支付流水（资金层面的退款交易）”
+
+特点：
+
+pay_amount 全为负数（例如 -12.0, -44000.0, -3000.0），很明显是“钱从店里流出”的方向。
+
+pay_status 全为 2，结合支付记录推测是“退款/完成状态”（至少表示“已处理完成”）。
+
+action_type 全为 2，极大概率是“退款动作类型”的枚举。
+
+relate_type 只出现 2 与 5，对应两类不同业务：一种是“消费类”，一种是“充值/储值类”（具体含义依赖系统配置，但肯定是区分不同业务来源）。
+
+这份“退款记录”是 资金维度 的退款流水，不是“业务维度”的退款单（比如没记录退款原因、操作备注等）。业务上的退款原因应从对应的订单、充值记录或其他业务表中去追踪。
+
+二、字段逐一说明（含数据类型 & 枚举推断）
+
+下面按功能分组，对每个字段说明其含义、类型，是否枚举，以及这些记录中实际出现的取值。
+
+1. 门店 / 租户维度字段
+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：电话；
+
+一系列门店配置项（灯控、考勤、营业状态等）。
+
+作用：
+
+为每条退款记录附带一份当时的门店元信息；
+
+提供冗余信息，避免联表查询门店档案。
+
+2. 退款流水主键与关联业务字段
+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 组合，含义一致：指向业务实体；
+
+本文件里的退款流水和“支付记录”是通过“共同指向同一业务实体”来间接关联，而不是直接指向支付记录。
+
+3. 时间字段
+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 两个字段，说明系统设计上区分“记录生成时间”与“渠道交易时间”。如果引入异步处理，二者可能就会出现差异。
+
+4. 金额相关字段
+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
+
+含义（推测）：
+
+第三方支付渠道对本次退款收取的手续费；
+
+正常应该在“通道成本核算”里用到。
+
+当前数据中没有任何通道手续费记录（可能通道不收手续费，或者手续费隐藏在其他费用内）。
+
+5. 支付方式 / 渠道相关字段
+
+结合“支付记录.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
+
+当前：全部为空字符串 ""
+
+含义（推测）：
+
+第三方支付平台的交易号（如微信支付单号、支付宝交易号等）。
+
+当前为空：要么是通道未返回，要么导出接口没带出这部分数据。
+
+6. 会员关联字段
+member_id
+
+类型：int
+
+当前：全部 0
+
+含义：
+
+租户内部的会员 ID（对应会员档案中的某个主键）。
+
+当前状态：
+
+这 11 笔退款中没有任何一笔标记了会员 ID，说明是“非会员退款”或退款没绑定到会员档案。
+
+member_card_id
+
+类型：int
+
+当前：全部 0
+
+含义：
+
+关联的会员卡账户 ID（对应“储值卡列表”或“会员档案”中的某一张卡）。
+
+当前状态：
+
+没有记录任何“退到某张会员卡”的情况；
+
+结合 balance_frozen_amount = 0、card_frozen_amount = 0，可以确定当前导出时间范围的退款全部是对外部支付渠道的退款，没有会员卡内部余额的退款。
+
+7. 状态标志字段
+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，基本可以确定这是“退款动作”的枚举标识。
+
+8. 其他操作相关字段
+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 在一起，通过这些枚举和正负金额，就能得到一张统一的资金流水大表。