209 lines
8.9 KiB
Markdown
209 lines
8.9 KiB
Markdown
# 台桌主数据 — 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/ 确认字段覆盖完整
|
||
-->
|