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

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/table_fee_discount_records.md
+++ b/docs/api-reference/table_fee_discount_records.md
@@ -0,0 +1,195 @@
+# 台费优惠记录 — GetTaiFeeAdjustList
+
+> 模块：`Site` · ODS 表：`table_fee_discount_records` · 事实表（增量）
+
+---
+
+## 一、接口概述
+
+查询门店下台费打折/调账的流水记录。每条记录不是台桌使用记录，而是在台费基础上追加的一条"金额调整记录"，用于记录某个订单、某张台在台费上的手工打折/减免金额。与台费流水表形成"主表 + 子操作表"的关系，通过 `adjust_amount ↔ ledger_amount` 闭合金额链路。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /Site/GetTaiFeeAdjustList` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | `page` + `limit`（最大 100） |
+| 时间范围 | `startTime` / `endTime`（必填） |
+
+---
+
+## 二、请求
+
+### 请求体（JSON）
+
+```json
+{
+  "startTime": "2025-11-01 08:00:00",
+  "endTime": "2025-11-10 08:00:00",
+  "siteId": 2790685415443269,
+  "page": 1,
+  "limit": 100
+}
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `startTime` | string | 是 | 查询起始时间 |
+| `endTime` | string | 是 | 查询结束时间 |
+| `siteId` | int | 是 | 门店 ID |
+| `page` | int | 是 | 页码，从 1 开始 |
+| `limit` | int | 是 | 每页条数，最大 100 |
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "taiFeeAdjustInfos": [ { ... }, { ... } ],
+    "total": 200
+  }
+}
+```
+
+`data.taiFeeAdjustInfos` 中每个对象即为一条台费优惠记录，共 20 个字段，按逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（20 个字段）
+
+### 4.1 主键与订单关联
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `id` | int | `2957913441881989` | 台费打折/调整流水主键 ID |
+| `order_trade_no` | int | `2957784612605829` | 订单交易号。与台费流水、助教流水、小票详情的同名字段一致。少数订单有多条调整记录 |
+| `order_settle_id` | int | `2957913171693253` | 结算单/小票 ID。与小票详情的 `orderSettleId` 对应 |
+| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
+| `site_id` | int | `2790685415443269` | 门店 ID |
+
+### 4.2 台桌维度
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `site_table_id` | int | `2793020259897413` | 台桌 ID，对应台桌配置表主键 |
+| `tenant_table_area_id` | int | `2791961347968901` | 租户维度台桌区域 ID |
+| `tableProfile` | object | `{...}` | 台桌配置信息快照，包含 `id`（台桌 ID）、`table_name`（台号如 `"S1"`）、`site_table_area_id`（门店区域 ID）、`site_table_area_name`（区域名如 `"斯诺克区"`）、`table_price`（基础单价，当前为 0.0）、`ewelink_client_id`（智能硬件 ID）、`charge_free`（免单标识）等字段 |
+
+### 4.3 金额与数量
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `ledger_amount` | float | `148.15` | 台费调账/减免金额（元/人民币）。**注意**：在本表中 `ledger_amount` 表示"被调整掉的金额"，对应台费流水中同一订单的 `adjust_amount`。与台费流水中的 `ledger_amount`（原始应收）含义不同 |
+| `ledger_count` | int | `1` | 调整次数，当前固定为 `1`（一次调账事件）。与台费流水中的 `ledger_count`（计费秒数）含义完全不同 |
+| `ledger_name` | string | `""` | 调账项目名称/打折原因描述。当前门店未使用，全部为空字符串。预留字段 |
+
+### 4.4 申请与操作信息
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `adjust_type` | int | `1` | 调整类型枚举。`1` = 台费打折/减免。其他值（如台费转移、误操作恢复）当前未出现 |
+| `applicant_id` | int | `2790687322443013` | 打折/调账申请人 ID |
+| `applicant_name` | string | `"收银员:郑丽珊"` | 申请人姓名（带角色描述），冗余展示字段 |
+| `operator_id` | int | `2790687322443013` | 实际执行调账操作的操作员 ID。当前数据中与 `applicant_id` 相同 |
+| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名 |
+| `create_time` | string | `"2025-11-09 23:25:11"` | 调整记录创建时间，即打折操作执行的时间戳 |
+
+### 4.5 状态与标记
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `ledger_status` | int | `1` | 调整记录状态。`1` = 生效（当前有效的调账记录）；`0` = 已失效/被覆盖（历史记录、已撤销或被后续调账覆盖）。同一 `order_trade_no` 下可能有多条记录，仅 `ledger_status = 1` 的为当前有效 |
+| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |
+
+### 4.6 门店信息快照
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `siteProfile` | object | `{...}` | 门店信息快照（冗余），结构与其他接口一致，不再逐字段展开 |
+
+---
+
+## 五、响应样例（单条记录）
+
+```json
+{
+  "tableProfile": {
+    "id": 2793020259897413,
+    "tenant_id": 2790683160709957,
+    "tenant_name": "",
+    "siteName": "",
+    "table_name": "S1",
+    "site_table_area_id": 2791963836207173,
+    "area_type_id": 0,
+    "table_price": 0.0,
+    "ewelink_client_id": "",
+    "site_table_area_name": "斯诺克区",
+    "charge_free": 0
+  },
+  "siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
+  "id": 2957913441881989,
+  "adjust_type": 1,
+  "applicant_id": 2790687322443013,
+  "applicant_name": "收银员:郑丽珊",
+  "create_time": "2025-11-09 23:25:11",
+  "is_delete": 0,
+  "ledger_amount": 148.15,
+  "ledger_count": 1,
+  "ledger_name": "",
+  "ledger_status": 1,
+  "operator_id": 2790687322443013,
+  "operator_name": "收银员:郑丽珊",
+  "order_settle_id": 2957913171693253,
+  "order_trade_no": 2957784612605829,
+  "site_id": 2790685415443269,
+  "site_table_id": 2793020259897413,
+  "tenant_id": 2790683160709957,
+  "tenant_table_area_id": 2791961347968901
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与台费流水（`table_fee_transactions`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `order_trade_no` | `order_trade_no` | 同一订单 |
+| `order_settle_id` | `order_settle_id` | 同一结算单 |
+| `site_table_id` | `site_table_id` | 同一台桌 |
+| `ledger_amount`（本表，生效记录） | `adjust_amount`（台费流水） | 本表的减免金额 = 台费流水中的调账金额 |
+
+> 台费流水给出时长 + 原始台费 + 各种金额拆分（含 `adjust_amount`）；台费优惠记录给出是谁、何时、以哪种类型发起了调账，调了多少金额。两表通过 `order_trade_no` 做一对一/一对多关系。
+
+### 与台桌配置 / 区域配置
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `site_table_id` | 台桌配置表 `id` | 台桌主键 |
+| `tableProfile.table_name` | 台桌配置表 `table_name` | 台号名称 |
+| `tableProfile.site_table_area_id` | 门店台桌区域维表 | 门店级区域 |
+| `tenant_table_area_id` | 租户台桌区域维表 | 租户级区域 |
+
+### 与员工/账号体系
+
+`applicant_id` / `operator_id` 与账号体系中的用户 ID 对应（与助教账号 `user_id` 属于同一 ID 空间）。可按员工维度统计台费打折频次和金额。
+
+### 与门店维度
+
+`site_id` 与所有业务表的 `site_id` 一致。`siteProfile` 为冗余快照。
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/table_fee_discount_records.md，按逻辑分组详解所有字段，含跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->