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

docs/api-reference/site_tables_master.md

@@ -0,0 +1,208 @@
+# 台桌主数据 — GetSiteTables
+
+> 模块：`Table` · ODS 表：`site_tables_master` · 维度表（快照）
+
+---
+
+## 一、接口概述
+
+查询门店下所有台桌的配置信息，包括台号、区域、状态、灯控、线上预约、台呢使用等。每条记录对应一张台桌，是典型的维度表，与台费流水、助教流水、台费打折等事实表通过 `id`（即 `site_table_id`）关联。本表是整个门店模型中的核心基础维表之一。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /Table/GetSiteTables` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | `page` + `limit`（最大 100） |
+| 时间范围 | 不需要（全量快照） |
+
+---
+
+## 二、请求
+
+### 请求体（JSON）
+
+```json
+{
+  "showStatus": 0,
+  "virtualTableType": -1,
+  "page": 1,
+  "limit": 100
+}
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `showStatus` | int | 是 | 展示状态筛选。`0` = 全部，`1` = 展示中，`2` = 隐藏 |
+| `virtualTableType` | int | 是 | 虚拟桌类型筛选。`-1` = 全部，`0` = 物理台，`1` = 虚拟台 |
+| `page` | int | 是 | 页码，从 1 开始 |
+| `limit` | int | 是 | 每页条数，最大 100 |
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "list": [ { ... }, { ... } ],
+    "total": 71
+  }
+}
+```
+
+`data.list` 中每个对象即为一条台桌记录，共 25 个字段，按逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（25 个字段）
+
+### 4.1 主键与门店标识
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `id` | int | `2791964216463493` | 台桌主键 ID。全系统唯一标识，各类流水表（台费、助教、台费打折等）通过 `site_table_id` 引用此值 |
+| `site_id` | int | `2790685415443269` | 门店 ID，所有记录相同。与其他业务表的 `site_id` 一致 |
+| `siteName` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
+
+### 4.2 区域与台桌属性
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `site_table_area_id` | int | `2791963794329671` | 台桌区域 ID，与 `areaName` 一一对应。在台费流水中对应 `tableProfile.site_table_area_id` |
+| `areaName` | string | `"A区"` | 区域名称。已知值：`A区`（18台）、`B区`（15台）、`补时长`（7台）、`C区`（6台）、`麻将房`（5台）、`VIP包厢`（4台）、`斯诺克区`（4台）、`K包`（3台）、`666`/`M7`/`k包活动区`（各2台）、`TV台`/`M8`/`发财`（各1台） |
+| `table_name` | string | `"A1"` | 台号/台名称，71 条记录各不相同。用于前台展示，也出现在流水中的 `ledger_name` 或 `tableName` 字段 |
+| `table_price` | float | `0.0` | 台的基础单价（元）。当前门店未在台列表中配置单价（全部为 0），实际计费规则在独立计费策略表中 |
+| `virtual_table` | int | `0` | 虚拟台标记：`0` = 物理台，`1` = 虚拟台（组合计费/逻辑台）。当前门店全部为 0 |
+| `self_table` | int | `1` | 自有台标记：`1` = 本门店自有台，`0` = 联营/外部台（预留）。当前全部为 1 |
+| `is_rest_area` | int | `0` | 休息区标记：`0` = 正常计费区域，`1` = 休息区（不参与计费）。当前全部为 0 |
+
+### 4.3 状态与展示控制
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `table_status` | int | `1` | 台桌运行状态：`1` = 空闲中，`2` = 使用中，`3` = 暂停中 |
+| `tableStatusName` | string | `"空闲中"` | `table_status` 的中文名称，仅展示用途 |
+| `show_status` | int | `1` | 前台展示状态：`1` = 在开台列表中展示（68台），`2` = 不在常规列表展示（3台：大包/大包麻将房/小包，主要通过线上预约使用） |
+| `audit_status` | int | `2` | 审核状态：`2` = 已审核/已启用。其他值可能表示待审核/驳回，当前全部为 2 |
+| `charge_free` | int | `0` | 免单标记：`0` = 正常计费，`1` = 免单台。当前全部为 0 |
+
+### 4.4 灯控与延时
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `light_status` | int | `2` | 台灯状态：`1` = 开灯/可控，`2` = 关灯/关闭。与智能硬件联动 |
+| `delay_lights_time` | int | `0` | 台灯熄灭延迟时间（秒或分钟），结账后延时关灯。当前全部为 0（未启用） |
+| `temporary_light_second` | int | `0` | 临时点灯时长（秒），手动临时开灯场景。当前全部为 0（未启用） |
+| `order_delay_time` | int | `0` | 订单自动延时时长，到点后自动延长计费。当前全部为 0（未启用） |
+
+### 4.5 线上预约与团购
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `is_online_reservation` | int | `2` | 线上预约开关：`1` = 允许线上预约（仅大包/小包），`2` = 不允许。与 `show_status` 配合使用：普通台 `show_status=1` + `is_online_reservation=2`；包厢 `show_status=2` + `is_online_reservation=1` |
+| `only_allow_groupon` | int | `2` | 团购限制：`1` = 仅允许团购使用（团购专用台），`2` = 不限制。当前全部为 2 |
+| `appletQrCodeUrl` | string | `"https://pc-we.ficoo.vip/..."` | 小程序二维码 URL，每张台独立。URL 中包含 `id`（台桌 ID）和 `siteId`（门店 ID）参数。用于扫码开台、呼叫服务等 |
+
+### 4.6 台呢使用
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `table_cloth_use_time` | int | `1863727` | 台呢累计使用时长（秒）。例如 1863727 秒 ≈ 517 小时。每次开台会累加对应秒数，用于提醒更换/保养 |
+| `table_cloth_use_Cycle` | int | `0` | 台呢使用周期阈值（秒），达到后提醒更换。`0` = 未配置。当前全部为 0 |
+
+### 4.7 时间元数据
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `create_time` | string | `"2025-07-15 17:52:54"` | 台桌配置创建时间。多数台在 2025-07-16 集中创建 |
+
+---
+
+## 五、响应样例（单条记录）
+
+```json
+{
+  "id": 2791964216463493,
+  "audit_status": 2,
+  "charge_free": 0,
+  "self_table": 1,
+  "create_time": "2025-07-15 17:52:54",
+  "is_rest_area": 0,
+  "light_status": 2,
+  "show_status": 1,
+  "site_id": 2790685415443269,
+  "site_table_area_id": 2791963794329671,
+  "table_cloth_use_time": 1863727,
+  "table_cloth_use_Cycle": 0,
+  "virtual_table": 0,
+  "table_name": "A1",
+  "table_price": 0.0,
+  "table_status": 1,
+  "areaName": "A区",
+  "siteName": "朗朗桌球",
+  "tableStatusName": "空闲中",
+  "appletQrCodeUrl": "https://pc-we.ficoo.vip/rootwww/prodwx38a48dd2bc3c1642?env=prod&type=1&id=2791964216463493&siteId=2790685415443269",
+  "only_allow_groupon": 2,
+  "delay_lights_time": 0,
+  "order_delay_time": 0,
+  "temporary_light_second": 0,
+  "is_online_reservation": 2
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与台费流水（`table_fee_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `site_table_id` | 台桌主键 → 流水中的台桌 ID |
+| `table_name` | `ledger_name` / `tableName` | 台号名称 |
+| `site_table_area_id` | `tableProfile.site_table_area_id` | 区域 ID |
+| `areaName` | `tableProfile.site_table_area_name` | 区域名称 |
+
+> 台费流水是事实表，本表是对应的台桌维表。两者通过 `site_table_id` 构成事实表–维度表关系。
+
+### 与台费打折（`table_fee_discounts`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `site_table_id` / `tableProfile.id` | 台桌主键 |
+| `table_name` | `tableProfile.table_name` | 台号名称 |
+| `site_table_area_id` | `tableProfile.site_table_area_id` | 区域 ID |
+
+> 台费打折记录中的 `tableProfile` 是对本表某一行台的快照。
+
+### 与助教流水（`assistant_service_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `site_table_id` | 台桌主键 → 助教服务所在台桌 |
+| `table_name` | `tableName` | 台号名称 |
+
+> 助教服务附着在具体台桌上，可按台/按区域统计助教服务情况。
+
+### 与门店维度
+
+所有业务表的 `site_id`、`siteName` 一致，共享门店维度。台桌列表是门店维度下的子实体表，与门店档案存在 1:N 关系（一个门店多张台）。
+
+### 业务角色组合规则
+
+- 普通台：`show_status=1` + `is_online_reservation=2`（现场前台开台）
+- 线上预约包厢：`show_status=2` + `is_online_reservation=1`（线上预约入口）
+- 补时长台：通过"特殊命名 + 区域"实现，`virtual_table` 仍为 0
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/site_tables_master.md，按逻辑分组详解所有 25 个字段，含跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->