在前后端开发联调前 的提交20260223

docs/database/BD_Manual_site_tables_master.md

@@ -0,0 +1,61 @@
+# BD_Manual：site_tables_master（台桌维表）
+
+> ODS 表：`ods.site_tables_master`
+> DWD 表：`dwd.dim_table`（主表）、`dwd.dim_table_ex`（扩展表）
+> API 接口：门店台桌列表
+> JSON 路径：`site_tables_master.json → data.siteTables`
+> 装载方式：SCD2 维度合并（`DwdLoadTask`）
+> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
+
+---
+
+## 1. dim_table（主表）
+
+| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
+|----------|------|---------|---------|---------|-------------|
+| `table_id` | BIGINT | `id` | FACT_MAPPINGS | 台桌唯一标识（PK 之一） | 飞球雪花 ID |
+| `site_id` | BIGINT | `site_id` | 自动映射 | 门店 ID | 飞球门店 ID |
+| `table_name` | TEXT | `table_name` | 自动映射 | 台桌名称 | 如 `1号台`、`VIP1` |
+| `site_table_area_id` | BIGINT | `site_table_area_id` | 自动映射 | 门店台桌区域 ID | 飞球区域 ID |
+| `site_table_area_name` | TEXT | `areaname` | FACT_MAPPINGS | 台桌区域名称 | 如 `大厅`、`VIP区` |
+| `tenant_table_area_id` | BIGINT | `site_table_area_id` | FACT_MAPPINGS | 租户级台桌区域 ID | 飞球区域 ID |
+| `table_price` | NUMERIC | `table_price` | 自动映射 | 台费单价（元/小时） | 金额值 |
+| `order_id` | BIGINT | `order_id` | FACT_MAPPINGS | 当前关联的订单 ID，0 表示空闲 | `0` 或订单 ID |
+| `scd2_*` | — | — | DWD 元数据 | SCD2 慢变维度追踪字段 | — |
+
+---
+
+## 2. dim_table_ex（扩展表）
+
+| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
+|----------|------|---------|---------|---------|-------------|
+| `table_id` | BIGINT | `id` | FACT_MAPPINGS | 台桌唯一标识（PK 之一） | 同主表 |
+| `show_status` | INTEGER | `show_status` | 自动映射 | 展示状态 | 枚举值 |
+| `is_online_reservation` | INTEGER | `is_online_reservation` | 自动映射 | 是否支持在线预约：0=否，1=是 | `0` / `1` |
+| `table_cloth_use_time` | INTEGER | `table_cloth_use_time` | FACT_MAPPINGS | 台布使用时间（累计使用次数或时长） | 整数 |
+| `table_cloth_use_cycle` | INTEGER | `table_cloth_use_cycle` | 自动映射 | 台布更换周期 | 整数 |
+| `table_status` | INTEGER | `table_status` | 自动映射 | 台桌状态枚举 | 枚举值 |
+| `create_time` | TIMESTAMPTZ | `create_time` | FACT_MAPPINGS | 台桌配置的创建时间或最近一次创建/复制时间 | ISO 时间戳 |
+| `light_status` | INTEGER | `light_status` | FACT_MAPPINGS | 台灯状态：1=已关灯，2=已开灯 | `1` / `2` |
+| `tablestatusname` | TEXT | `tablestatusname` | FACT_MAPPINGS | 台桌状态中文名称（如"空闲中""使用中"），仅展示用途。ODS 列 `tableStatusName` 在 PG 中小写化 | 如 `空闲中`、`使用中` |
+| `sitename` | TEXT | `sitename` | FACT_MAPPINGS | 门店名称快照，冗余字段。ODS 列 `siteName` 在 PG 中小写化 | 如 `朗朗桌球` |
+| `applet_qr_code_url` | TEXT | `"appletQrCodeUrl"` | FACT_MAPPINGS | 小程序二维码 URL，用于扫码开台等场景。ODS 列用双引号保留驼峰大小写 | HTTPS 链接或 NULL |
+| `audit_status` | INTEGER | `audit_status` | FACT_MAPPINGS | 审核状态：2=已审核通过（当前全部为 2） | `2` |
+| `charge_free` | INTEGER | `charge_free` | FACT_MAPPINGS | 是否免费台：0=收费，1=免费（当前全部为 0） | `0` / `1` |
+| `delay_lights_time` | INTEGER | `delay_lights_time` | FACT_MAPPINGS | 台灯熄灭延迟时间（秒），结账后延时关灯的秒数 | 正整数 |
+| `is_rest_area` | INTEGER | `is_rest_area` | FACT_MAPPINGS | 是否休息区台桌：0=否，1=是（当前全部为 0） | `0` / `1` |
+| `only_allow_groupon` | INTEGER | `only_allow_groupon` | FACT_MAPPINGS | 是否仅允许团购开台：0=不限制，1=仅团购，2=不限制（当前全部为 2） | `0` / `1` / `2` |
+| `order_delay_time` | INTEGER | `order_delay_time` | FACT_MAPPINGS | 订单自动延时时长（秒），超时未结账自动延长的时间 | 正整数 |
+| `self_table` | INTEGER | `self_table` | FACT_MAPPINGS | 是否自有台桌：1=自有（当前全部为 1） | `1` |
+| `temporary_light_second` | INTEGER | `temporary_light_second` | FACT_MAPPINGS | 临时开灯秒数，临时开灯持续的时间 | 正整数 |
+| `virtual_table` | INTEGER | `virtual_table` | FACT_MAPPINGS | 是否虚拟台桌：0=实体台，1=虚拟台（当前全部为 0） | `0` / `1` |
+| `scd2_*` | — | — | DWD 元数据 | SCD2 慢变维度追踪字段 | — |
+
+---
+
+## 3. 代码引用
+
+- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dim_table"]` / `FACT_MAPPINGS["dwd.dim_table_ex"]`
+- TABLE_MAP：`"dwd.dim_table" → "ods.site_tables_master"`
+- DWS 下游：`dws_finance_daily_task.py`（财务日报，台费汇总按区域分组）
+- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__add_dim_table_ex_fields.sql`（已归档）