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

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/member_balance_changes.md
+++ b/docs/api-reference/member_balance_changes.md
@@ -0,0 +1,205 @@
+# 会员余额变动 — GetMemberCardBalanceChange
+
+> 模块：`MemberProfile` · ODS 表：`member_balance_changes` · 事实表（增量）
+
+---
+
+## 一、接口概述
+
+查询会员卡余额变动明细，记录每一次充值、消费扣款、赠送、退款等导致卡内余额发生变化的事件。每条记录包含变动前后余额、变动金额、来源类型、支付方式、操作员等信息。本表是会员卡层面的"总账/明细账表"，严格满足 `after = before + account_data` 的余额恒等关系。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /MemberProfile/GetMemberCardBalanceChange` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | `page` + `limit`（最大 100） |
+| 时间范围 | 需要（`startTime` / `endTime`） |
+
+---
+
+## 二、请求
+
+### 请求体（JSON）
+
+```json
+{
+  "startTime": "2026-02-01 08:00:00",
+  "endTime": "2026-02-13 08:00:00",
+  "fromType": 0,
+  "page": 1,
+  "limit": 100
+}
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `startTime` | string | 是 | 查询起始时间 |
+| `endTime` | string | 是 | 查询结束时间 |
+| `fromType` | int | 是 | 来源类型筛选。`0` = 全部 |
+| `page` | int | 是 | 页码，从 1 开始 |
+| `limit` | int | 是 | 每页条数，最大 100 |
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "list": [ { ... }, { ... } ],
+    "total": 200
+  }
+}
+```
+
+`data.list` 中每个对象即为一条余额变更记录，共 25 个字段，按逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（25 个字段）
+
+### 4.1 主键与关联 ID
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `id` | int | `2957881605869253` | 余额变更记录主键 ID，唯一标识一条余额变化事件 |
+| `relate_id` | int | `2957881518788421` | 关联业务记录 ID。视 `from_type` 而定，可能对应充值记录 ID、订单结算单 ID、活动核销记录 ID 等。`0` = 无挂接业务单（如纯后台调整） |
+| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
+| `site_id` | int | `2790685415443269` | 余额变动发生的门店 ID。`0` = 跨门店/平台级操作（如活动抵用券退款） |
+| `register_site_id` | int | `2790685415443269` | 会员卡注册门店 ID（办卡所在门店），与 `site_id` 区分"办卡地"和"交易发生地" |
+
+### 4.2 会员与会员卡维度
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `tenant_member_id` | int | `2799212845565701` | 租户内会员主键 ID。对应会员档案表的 `id` |
+| `system_member_id` | int | `2799212844549893` | 系统级会员 ID（全局唯一） |
+| `tenant_member_card_id` | int | `2799219999295237` | 会员卡账户 ID，指明本次变更针对哪一张卡。对应储值卡列表的 `id` |
+| `card_type_id` | int | `2793249295533893` | 卡种类型 ID。枚举：`2793249295533893` = 储值卡，`2793266846533445` = 活动抵用券，`2794699703437125` = 酒水卡，`2791990152417157` = 台费卡 |
+| `memberCardTypeName` | string | `"储值卡"` | 卡种名称，与 `card_type_id` 一一对应。枚举值：`"储值卡"`、`"活动抵用券"`、`"酒水卡"`、`"台费卡"` |
+| `memberName` | string | `"曾丹烨"` | 会员姓名/称呼 |
+| `memberMobile` | string | `"13922213242"` | 会员手机号 |
+
+### 4.3 门店名称
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `paySiteName` | string | `"朗朗桌球"` | 余额变更发生的门店名称。当 `site_id=0` 时为空字符串 |
+| `registerSiteName` | string | `"朗朗桌球"` | 卡片注册门店名称（办卡地点） |
+
+### 4.4 金额与余额（核心）
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `before` | float | `816.3` | 变动前卡账户余额（元） |
+| `account_data` | float | `-120.0` | 本次变动金额（元）。正数 = 增加（充值/赠送），负数 = 减少（消费/退款） |
+| `after` | float | `696.3` | 变动后卡账户余额（元）。恒等关系：`after = before + account_data` |
+| `refund_amount` | float | `0.0` | 退款相关金额（元）。当前未使用，全部为 `0.0` |
+
+### 4.5 变动来源与支付方式
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `from_type` | int | `1` | 变动来源类型（核心枚举）。`1` = 日常消费扣款（负数），`2` = 其他增加，`3` = 充值增加（正数，有外部支付），`4` = 调整/赠送增加（正数，后台发放），`7` = 充值退款（负数，remark 为"充值退款"），`9` = 活动抵用券余额冲减（负数，site_id=0） |
+| `payment_method` | int | `0` | 支付方式。`0` = 内部结算/非外部支付（from_type=1/2/7/9），`3` = 赠送/后台调账渠道（from_type=4），`4` = 外部支付渠道（from_type=3，如扫码充值） |
+
+### 4.6 操作员信息
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `operator_id` | int | `2790687322443013` | 执行本次余额变更操作的员工 ID |
+| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀），如 `"收银员:郑丽珊"`、`"店长:谢晓洪"` |
+
+### 4.7 状态与备注
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已逻辑删除。系统倾向"不可逆记账"，冲销通过反向变动实现 |
+| `remark` | string | `""` | 备注。多数为空，`"充值退款"` 仅出现在 `from_type=7` 的记录上 |
+
+### 4.8 时间
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `create_time` | string | `"2025-11-09 22:52:48"` | 余额变更记录创建时间，通常接近交易发生时间 |
+
+---
+
+## 五、响应样例（单条记录）
+
+```json
+{
+  "memberCardTypeName": "储值卡",
+  "paySiteName": "朗朗桌球",
+  "registerSiteName": "朗朗桌球",
+  "memberName": "曾丹烨",
+  "memberMobile": "13922213242",
+  "id": 2957881605869253,
+  "account_data": -120.0,
+  "after": 696.3,
+  "before": 816.3,
+  "card_type_id": 2793249295533893,
+  "create_time": "2025-11-09 22:52:48",
+  "from_type": 1,
+  "is_delete": 0,
+  "operator_id": 2790687322443013,
+  "operator_name": "收银员:郑丽珊",
+  "payment_method": 0,
+  "refund_amount": 0.0,
+  "register_site_id": 2790685415443269,
+  "relate_id": 2957881518788421,
+  "remark": "",
+  "site_id": 2790685415443269,
+  "system_member_id": 2799212844549893,
+  "tenant_id": 2790683160709957,
+  "tenant_member_card_id": 2799219999295237,
+  "tenant_member_id": 2799212845565701
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与会员档案（`member_profiles`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `tenant_member_id` | `id` | 租户内会员主键 |
+| `system_member_id` | `system_member_id` | 系统级会员 ID |
+
+### 与储值卡列表（`member_stored_value_cards`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `tenant_member_card_id` | `id` | 卡账户 ID → 具体哪张卡 |
+| `card_type_id` | `card_type_id` | 卡种类型 ID |
+
+> 余额变更流水通过 `tenant_member_card_id` 指向具体卡账户，再通过 `card_type_id` 确定卡种。
+
+### 与支付记录
+
+充值类记录（`from_type=3`）的 `relate_id` 对应充值记录 ID，`payment_method` 与支付记录中的支付渠道枚举保持一致。
+
+### 与订单/消费流水
+
+消费扣款（`from_type=1`）和活动冲减（`from_type=9`）的 `relate_id` 对应订单/结算单/活动扣款单的主键，可与台费流水、助教流水、门店销售记录中的 `order_settle_id` 建立关系。
+
+### 与门店维度
+
+- `site_id` / `paySiteName`：交易发生门店
+- `register_site_id` / `registerSiteName`：办卡门店
+- 少数 `site_id=0` 的记录为平台级/活动结算场景
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/member_balance_changes.md，按逻辑分组详解所有字段，含跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->