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

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/tenant_member_balance_overview.md
+++ b/docs/api-reference/tenant_member_balance_overview.md
@@ -0,0 +1,185 @@
+# 会员余额总览 — TenantMemberBalanceOverview
+
+> 模块：`MemberProfile` · ODS 表：无（新发现 API，尚未建表） · 统计快照
+
+---
+
+## 一、接口概述
+
+查询当前租户下所有会员卡的余额统计一览，按卡介质（电子卡/实体卡）和卡来源（充值卡/赠送卡）两个维度汇总，并提供各卡类型的明细分拆。该接口为新发现的 API，当前尚未建立 ODS 表，主要用于财务对账和会员资产概览。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /MemberProfile/TenantMemberBalanceOverview` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | 无分页 |
+| 时间范围 | 不需要（实时快照） |
+
+---
+
+## 二、请求
+
+### 请求体
+
+```json
+null
+```
+
+该接口无需请求参数，直接返回当前租户的会员余额汇总。
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "totalPointBalance": 0.0,
+    "totalCardBalance": 356619.51,
+    "totalCardPrincipalBalance": 346917.34,
+    "electronicCardBalance": 356619.51,
+    "physicsCardBalance": 0,
+    "rechargeCardBalance": 90055.67,
+    "rechargeCardList": [ { ... } ],
+    "giveCardBalance": 266563.84,
+    "giveCardList": [ { ... } ]
+  }
+}
+```
+
+`data` 对象包含 9 个顶层字段，其中 `rechargeCardList` 和 `giveCardList` 为卡类型明细数组。
+
+---
+
+## 四、响应字段详解（9 个字段）
+
+### 4.1 总额汇总
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `totalPointBalance` | float | `0.0` | 全部会员积分余额合计（元）。当前门店未启用积分功能 |
+| `totalCardBalance` | float | `356619.51` | 全部会员卡余额合计（元），含本金和赠送金额。等于 `electronicCardBalance` + `physicsCardBalance` |
+| `totalCardPrincipalBalance` | float | `346917.34` | 全部会员卡本金余额合计（元），不含赠送部分 |
+
+### 4.2 按卡介质分类
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `electronicCardBalance` | float | `356619.51` | 电子卡余额合计（元）。当前门店全部为电子卡 |
+| `physicsCardBalance` | int | `0` | 实体卡余额合计（元）。当前门店未使用实体卡 |
+
+### 4.3 按卡来源分类 — 充值卡
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `rechargeCardBalance` | float | `90055.67` | 充值卡余额合计（元），即会员主动充值获得的卡 |
+| `rechargeCardList` | array | 见下表 | 充值卡按类型的明细列表 |
+
+`rechargeCardList` 数组中每个元素：
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `cardTypeName` | string | `"储值卡"` | 卡类型名称。已知值：`储值卡`、`月卡` |
+| `balance` | float | `86115.67` | 该类型卡的余额合计（元），含赠送部分 |
+| `principalBalance` | float | `86115.67` | 该类型卡的本金余额合计（元） |
+
+### 4.4 按卡来源分类 — 赠送卡
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `giveCardBalance` | float | `266563.84` | 赠送卡余额合计（元），即系统赠送/活动发放的卡 |
+| `giveCardList` | array | 见下表 | 赠送卡按类型的明细列表 |
+
+`giveCardList` 数组中每个元素：
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `cardTypeName` | string | `"台费卡"` | 卡类型名称。已知值：`消费卡`、`年卡`、`台费卡`、`活动抵用券`、`酒水卡` |
+| `balance` | float | `247875.46` | 该类型卡的余额合计（元），含赠送部分 |
+| `principalBalance` | float | `247875.46` | 该类型卡的本金余额合计（元） |
+
+---
+
+## 五、响应样例
+
+```json
+{
+  "totalPointBalance": 0.0,
+  "totalCardBalance": 356619.51,
+  "totalCardPrincipalBalance": 346917.34,
+  "electronicCardBalance": 356619.51,
+  "physicsCardBalance": 0,
+  "rechargeCardBalance": 90055.67,
+  "rechargeCardList": [
+    {
+      "cardTypeName": "储值卡",
+      "balance": 86115.67,
+      "principalBalance": 86115.67
+    },
+    {
+      "cardTypeName": "月卡",
+      "balance": 3940.0,
+      "principalBalance": 3940.0
+    }
+  ],
+  "giveCardBalance": 266563.84,
+  "giveCardList": [
+    {
+      "cardTypeName": "消费卡",
+      "balance": 0,
+      "principalBalance": 0
+    },
+    {
+      "cardTypeName": "年卡",
+      "balance": 7.0,
+      "principalBalance": 7.0
+    },
+    {
+      "cardTypeName": "台费卡",
+      "balance": 247875.46,
+      "principalBalance": 247875.46
+    },
+    {
+      "cardTypeName": "活动抵用券",
+      "balance": 14972.43,
+      "principalBalance": 5270.26
+    },
+    {
+      "cardTypeName": "酒水卡",
+      "balance": 3708.95,
+      "principalBalance": 3708.95
+    }
+  ]
+}
+```
+
+---
+
+## 六、跨表关联
+
+该接口返回的是租户级汇总统计，不包含会员个体信息，与业务表的关联为间接关系。
+
+| 潜在关联 | 说明 |
+|----------|------|
+| `totalCardBalance` | 应等于会员卡列表中所有卡的余额之和 |
+| `rechargeCardList` / `giveCardList` 中的 `cardTypeName` | 对应会员卡类型配置中的卡类型名称 |
+| `balance` vs `principalBalance` 差额 | 反映赠送金额部分，与充值记录中的赠送金额对应 |
+
+> 当前该接口尚未建立 ODS 表，暂无 ETL 入库流程。该接口适合用于 DWS 层的会员资产快照统计，如后续需要持久化，建议在 `billiards_dws` schema 下新建汇总表。
+
+### 金额校验关系
+
+- `totalCardBalance` = `electronicCardBalance` + `physicsCardBalance`
+- `totalCardBalance` = `rechargeCardBalance` + `giveCardBalance`
+- 各 `*CardList` 中 `balance` 之和应等于对应的 `*CardBalance`
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/tenant_member_balance_overview.md，按逻辑分组详解 9 个字段及嵌套结构，含金额校验关系
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->