# 台桌主数据 — 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） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.siteTables` |

---

## 二、请求

### 请求体（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 个字段，按 8 个逻辑分组说明如下。

---

## 四、响应字段详解（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 当前订单

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `order_id` | integer | `0` | 当前使用中的台桌关联订单 ID。`0` = 空闲无订单；非零时对应正在进行的台费订单主键 |

### 4.8 时间元数据

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `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/ 确认字段覆盖完整

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 1 个缺失字段（tableprofile）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过

- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.7"时间元数据"组混入 order_id（当前订单 ID），与时间无关
- 变更摘要: 新增 4.7"当前订单"组（1 字段）；原 4.7 时间组重编号为 4.8
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 25
-->
