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

docs/api-reference/endpoints/payment_transactions.md

@@ -0,0 +1,459 @@
+# 支付流水（GetPayLogListPage）
+
+> 自动生成于 2026-02-13 | 数据来源：实时 API
+
+## 基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `PayLog/GetPayLogListPage` |
+| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/PayLog/GetPayLogListPage` |
+| 请求方法 | `POST` |
+| Content-Type | `application/json` |
+| 鉴权方式 | Bearer Token（`Authorization` 头） |
+| ODS 对应表 | `payment_transactions` |
+| 分页方式 | `page` + `limit`（最大 100） |
+| 时间范围 | 需要（StartPayTime / EndPayTime） |
+
+## 请求参数
+
+| 参数名 | 类型 | 示例值 | 说明 |
+|--------|------|--------|------|
+| `StartPayTime` | string | `"2026-02-01 08:00:00"` | 支付起始时间 |
+| `EndPayTime` | string | `"2026-02-13 08:00:00"` | 支付结束时间 |
+| `siteId` | int | `2790685415443269` | 门店 ID |
+| `OnlinePayChannel` | int | `0` | 在线支付渠道（0=全部） |
+| `paymentMethod` | int | `0` | 支付方式（0=全部） |
+| `relateType` | int | `0` | 关联类型（0=全部） |
+| `page` | int | `1` | 页码（从 1 开始） |
+| `limit` | int | `100` | 每页条数（最大 100） |
+
+## 响应字段（共 11 个）
+
+| # | 字段名 | 类型 | 示例值 |
+|---|--------|------|--------|
+| 1 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
+| 2 | `create_time` | string | '2026-02-13 04:49:48' |
+| 3 | `pay_amount` | float | 0.0 |
+| 4 | `pay_status` | int | 2 |
+| 5 | `pay_time` | string | '2026-02-13 04:49:48' |
+| 6 | `online_pay_channel` | int | 0 |
+| 7 | `relate_type` | int | 2 |
+| 8 | `relate_id` | int | 3092711340902597 |
+| 9 | `site_id` | int | 2790685415443269 |
+| 10 | `id` | int | 3092712422508741 |
+| 11 | `payment_method` | int | 4 |
+
+## 详细字段分析
+
+> 以下内容迁移自旧版 `payment_transactions-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
+
+二、字段逐一说明（含类型、枚举、可能含义）
+1. 门店维度字段
+1.1 siteProfile
+
+类型：对象（Object）
+
+含义：门店信息快照，与其他 JSON 中的 siteProfile 结构一致。
+
+关键子字段（只列最重要的，结构与前面文件相同）：
+
+id：门店 ID（本数据中固定为 2790685415443269）。
+
+org_id：组织 ID。
+
+shop_name：店名（例如“朗朗桌球”）。
+
+full_address / address：详细地址 / 简要地址。
+
+business_tel：门店电话。
+
+longitude / latitude：经纬度。
+
+tenant_id：租户 ID。
+
+site_label：门店标签（如 “A”）。
+
+shop_status：门店状态枚举（本数据中为 1，表示正常营业）。
+
+以及 WIFI、灯控、客服二维码等配置字段。
+
+说明：
+
+siteProfile.id 与本记录的 site_id 完全一致。
+
+在整个系统中，这是一份门店维度的冗余快照，方便前端和报表使用。
+
+1.2 site_id
+
+类型：整数（long）
+
+观测：所有记录均为 2790685415443269。
+
+含义：支付记录所属的门店 ID。
+
+关联关系：
+
+与其他所有 JSON 中的 site_id / siteId 对应，是全局的门店外键。
+
+与 siteProfile.id 相同，保证“门店维度”一致。
+
+2. 支付流水主键与业务关联
+2.1 id
+
+类型：整数（long）
+
+特征：200 条记录中的 id 全部唯一。
+
+含义：支付流水记录的主键 ID。
+
+作用：
+
+在“支付记录”这个表内部，唯一标识一条支付流水（包括金额为 0 的记录）。
+
+2.2 relate_type
+
+类型：整数（int），明显是 枚举字段。
+
+观测到的枚举值及数量：
+
+2：出现 196 次。
+
+5：出现 3 次。
+
+1：出现 1 次。
+
+含义（从结构与其他表关联推断）：
+
+表示“这条支付记录关联的业务类型”。
+
+不同的 relate_type，relate_id 指向不同业务表：
+
+relate_type = 2：
+通过数据实际比对，可以确认：
+
+relate_id 对应 结账记录.json 中的 settleList.id（即结账单 ID / order_settle_id）。
+
+本类型是“结账单支付流水”。
+
+relate_type = 5：
+通过与 会员卡流水（tenantMemberCardLogs） 的比对：
+
+在 tenantMemberCardLogs 中，存在字段 relate_id = 本表.relate_id，from_type = 3，且有充值金额 account_data。
+
+因此可以判断：relate_type = 5 对应“会员卡余额/充值类业务”的支付流水。
+
+relate_type = 1：
+当前样本中只有 1 条，且在其他 JSON 中没有找到同 ID 的记录，具体业务类型不明，结构上可先视作“其他业务类型（预留枚举值）”。
+
+总结：relate_type 是“支付关联业务类型”的枚举，至少包括：
+
+2：结账单支付；
+
+5：会员卡充值/账户操作支付；
+
+1：其他少见业务类型（暂不确定）。
+
+2.3 relate_id
+
+类型：整数（long）
+
+特征：
+
+200 条记录中，relate_id 全部互不重复（n_unique=200）。
+
+含义：关联业务记录的主键 ID（按 relate_type 不同指向不同表）。
+
+具体关联关系：
+
+当 relate_type = 2：
+
+relate_id = 结账记录表（结账记录.json）中 settleList.id。
+
+即：一条结账单，会在本表中对应一条支付记录（当前样本里是一对一，结构上允许扩展为一对多）。
+
+当 relate_type = 5：
+
+relate_id = 会员卡流水（tenantMemberCardLogs）中的 relate_id 字段，而非该表的主键 id。
+
+说明：充值/余额变更有自己的“业务单号”，该单号在支付记录和会员卡流水中共享。
+
+当 relate_type = 1：
+
+未在其他已解析表中找到对应 ID，只能确认它是一种保留业务类型。
+
+3. 支付金额与时间字段
+3.1 pay_amount
+
+类型：浮点数（float）
+
+观测数据：
+
+不同取值共 36 个。
+
+最小值：0.0，最大值：3000.0。
+
+分布特征（只看结构）：
+
+0.0：出现 140 次。
+
+其他典型值：4.0, 5.0, 6.0, 10.0, 14.0, 15.0, 20.0, 48.0, 96.0, 1000.0, 3000.0 等。
+
+含义（结构层面）：
+
+本条支付流水的“支付金额”，单位为元。
+
+特别情况：
+
+140 条 pay_amount = 0 的记录，其 (relate_type, payment_method) 组合全部为 (2, 2)。
+从结构角度看，可以解读为：
+
+这部分支付流水记录通过 payment_method=2 标记了某种支付渠道，但金额为 0；
+
+金额实际可能由其他渠道/卡券抵扣（具体业务逻辑不在本次分析范围）。
+这里仅说明“0 元支付记录在结构上是合法且被大量使用的”。
+
+3.2 create_time
+
+类型：字符串（string），格式 "YYYY-MM-DD HH:MM:SS"
+
+特征：
+
+200 条记录中，create_time 全部唯一。
+
+含义：
+
+支付记录创建时间，通常与发起支付请求的时间一致（创建支付流水的时间戳）。
+
+3.3 pay_time
+
+类型：字符串（string），格式同上。
+
+特征：
+
+200 条记录中，pay_time 也全部唯一。
+
+在数据中 create_time 与 pay_time 多数完全一致，说明支付完成较快。
+
+含义：
+
+实际支付完成时间（支付状态变为成功的时间戳）。
+
+从结构角度：
+
+create_time 可以用来追踪“付费动作发起时间”。
+
+pay_time 记录“支付成功时间”。
+在异步支付场景，二者有可能不一致（当前样本中大多相同）。
+
+4. 支付状态与渠道、方式字段
+4.1 pay_status
+
+类型：整数（int），枚举。
+
+样本情况：所有记录 pay_status = 2。
+
+含义（结合命名和导出结果推断）：
+
+支付状态枚举字段。
+
+当前导出只包含状态为 2 的记录，很明显是“支付成功”的状态。
+
+其他可能存在的枚举值（未出现在本数据中）：
+
+例如 0=未支付，1=支付中，3=支付失败，4=已退款等（仅示例，具体需参考系统配置）。
+
+结论（结构）：
+导出的 支付记录.json 是“成功支付流水”的子集，其他状态被过滤掉。
+
+4.2 payment_method
+
+类型：整数（int），枚举。
+
+样本分布：
+
+2：140 条记录。
+
+4：60 条记录。
+
+含义：
+
+支付方式枚举，例如微信、支付宝、现金、银行卡、储值卡等某一种。
+
+当前数据中只出现了 2 种枚举值，但没有文字说明映射关系。
+
+从结构角度的判断：
+
+这是区分不同支付“方式/通道”的关键字段；
+
+应与系统中的“支付方式配置表”存在映射关系（本次导出未包含该配置表）。
+
+需要注意：
+虽然可以猜测 2 和 4 可能对应常见通道（如微信/支付宝等），但在缺乏配置表的情况下不宜直接下结论，这里只确认它是“支付方式枚举”的字段。
+
+4.3 online_pay_channel
+
+类型：整数（int），枚举。
+
+样本情况：所有记录 online_pay_channel = 0。
+
+含义（命名层面）：
+
+线上支付渠道枚举，例如：
+
+0：无 / 线下；
+
+1：微信；
+
+2：支付宝；
+
+……
+
+但当前时间范围内，所有记录均为 0，没有其他枚举值出现。
+
+结构特点：
+
+这个字段是为细分“在线支付通道”准备的；
+
+当前门店在本次导出时间段内，可能没有使用该字段（或所有支付统一走某种方式未拆分）。
+
+5. 其他结构性字段
+
+这里主要就是前面已经涉及的：
+
+siteProfile：门店快照（对象）。
+
+site_id：门店 ID，所有记录相同。
+
+id：支付流水主键。
+
+relate_type & relate_id：业务关联键。
+
+没有额外隐藏字段，本表结构很精简、单一职责较强。
+
+三、与其他 JSON 的关联关系（从字段角度）
+
+本表核心作用：承载“支付结果”层面的信息，通过 relate_type + relate_id 把不同业务域的流水（结账单、会员卡流水等）统一串到“支付系统”上。
+
+1. 与结账记录（结账记录.json）的关系
+
+关联字段：
+
+当 relate_type = 2 时：
+
+支付记录.relate_id = 结账记录.settleList.id
+
+结构含义：
+
+每一笔结账单（settleList.id）对应一条支付记录（当前样本中是一条记录，relate_id 唯一）。
+
+通过这个关系，可以：
+
+从结账记录跳转到对应的支付记录；
+
+从支付记录反查对应的结账单。
+
+补充：
+
+在整个系统中，结账记录.id 也对应各类明细表的 order_settle_id（台费、助教等），因此：
+
+支付记录 间接成为连接“支付系统”与“台费/助教/商品明细”的桥梁。
+
+2. 与会员卡流水（tenantMemberCardLogs）/ 余额变更记录的关系
+
+对于 relate_type = 5 的记录：
+
+在 tenantMemberCardLogs 中存在：
+
+tenantMemberCardLogs.relate_id = 支付记录.relate_id
+
+tenantMemberCardLogs.payment_method = 支付记录.payment_method
+
+tenantMemberCardLogs.account_data = 充值金额（例如 1000.0）。
+
+结构含义：
+
+这些支付记录对应的业务类型是“会员卡余额充值/账户变动”。
+
+relate_id 在这里扮演“充值业务单号”的角色，在支付表和会员卡流水中共享。
+
+3. 与门店维度的关系
+
+site_id 与各个表（结账记录、台费流水、助教流水等）的 site_id 一致。
+
+siteProfile 作为冗余的门店信息快照，与其他文件中的门店快照结构一致。
+
+4. 与结算/小票维度的间接关系
+
+支付记录 →（通过 relate_id）→ 结账记录 →（通过 id/orderSettleId）→ 小票详情/台费/助教明细。
+
+结构上，这构成一条完整的链路：
+
+业务明细表（台费/助教等）只记录“消费内容”；
+
+结账记录汇总明细，形成一条“结算单”；
+
+支付记录在“结算单”基础上记录“实际支付行为”。
+
+四、本表暴露出的结构性设计特点和线索
+
+从纯结构、字段设计角度，本表有几个明显的设计意图和特点：
+
+强烈的“统一支付网关”设计
+通过 (relate_type, relate_id) 组合，支付系统不直接关心支付的是“台费单、结账单还是会员卡充值单”，而是：
+
+不同业务系统约定一个 relate_type；
+
+将各自的业务主键（或业务单号）写入 relate_id。
+这样整个支付层可以统一处理资金动作，而上层业务只需按约定填字段。
+
+支付成功流水视角，非全量支付事件日志
+
+pay_status 全部为 2；
+
+没有看到待支付、失败、关闭等状态。
+说明当前导出的 支付记录.json 实际上是“支付成功流水卡片”，而不是“完整交易生命周期日志”。
+对数据建模时，应该把“支付记录”视为 成功资金落地的事实表。
+
+支付方式与线上渠道双层枚举结构
+
+payment_method：高层次区分支付方式（现金/卡/微信/支付宝/储值卡等）；
+
+online_pay_channel：更细粒度区分“线上支付通道”（按实际配置可能划分微信/支付宝等）。
+当前样本中 online_pay_channel 全为 0，说明这个维度还没被实际利用，但结构已经预留，用于以后精细化拆分。
+
+允许一单多笔支付的设计空间
+
+结构上，relate_id 并没有强制唯一，可以允许：
+
+同一个 relate_id + 不同 payment_method；
+
+同一结账单部分现金、部分在线等组合支付。
+
+虽然本时间段样本中每个 relate_id 只出现一次（对 relate_type=2 来说），但从设计上看，完全可以扩展为一对多。
+在后续建模时不要假定“一个 relate_id 一定只对应一条支付记录”，这只是当前时间段的实际情况。
+
+0 元支付流水的大量存在
+
+规模：200 条记录中，有 140 条 pay_amount = 0，且全部 (relate_type=2, payment_method=2)。
+
+结构意义：
+
+系统会对“金额为 0 的支付动作”也产生支付流水记录，这可能是为了：
+
+记录“某个支付方式参与了本单，但实际金额由其他方式/卡券承担”；
+
+或记录内部结算/记账动作。
+
+对后续分析和建模来说，不能简单按“pay_amount > 0”过滤数据，否则会丢失一大批结构上真实存在的支付行为。
+
+门店维度冗余一致性
+
+site_id 与 siteProfile.id 始终一致；
+
+该模式与台费流水、助教流水、结账记录中的门店设计完全统一。
+这种“一份数字外键 + 一份冗余快照”的模式，对于你后面做数据中台/数仓建模有直接影响：
+
+在数仓中一般会把 site_id 建成维度外键；
+
+siteProfile 只在上游 ODS 层保留快照，DW 层不一定全量展开。