Merge branch 'dev'

.gitignore

@@ -6,7 +6,6 @@ __pycache__/
 .Python
 build/
 develop-eggs/
-dist/
 downloads/
 eggs/
 .eggs/
@@ -39,8 +38,6 @@ export/
 logs/
 
 # 环境变量
-.env
-.env.local
 
 # 测试
 .pytest_cache/

README.md

@@ -110,9 +110,6 @@ python -m cli.main \
 - `run_etl.sh`：Linux/macOS 启动脚本（需先 `cd etl_billiards`；会加载当前目录 `.env`）。
 
 ### app/
-- `app/etl_busy.py`：忙时 ETL 示例函数（TODO，占位）。
-- `app/etl_idle.py`：闲时 ETL 示例函数（TODO，占位）。
-- `app/runner.py`：简易 Runner：按 `--mode busy/idle` 调用 `app/etl_busy.py` 或 `app/etl_idle.py`（示例/未接入主 ETL）。
 
 ### etl_billiards/
 - `etl_billiards/.env`：本地运行环境变量（含敏感信息，勿提交/勿外传）。
@@ -220,13 +217,12 @@ python -m cli.main \
 - `etl_billiards/scripts/bootstrap_schema.py`：Apply the PRD-aligned warehouse schema (ODS/DWD/DWS) to PostgreSQL.
 - `etl_billiards/scripts/build_dwd_from_ods.py`：Populate PRD DWD tables from ODS payload snapshots.
 - `etl_billiards/scripts/build_dws_order_summary.py`：Recompute billiards_dws.dws_order_summary from DWD fact tables.
-- `etl_billiards/scripts/check_ods_json_vs_table.py`：ODS JSON 字段核对脚本：对照当前数据库中的 ODS 表字段，检查示例 JSON（默认目录 C:\dev\LLTQ\export\test-json-doc）
+- `etl_billiards/scripts/check_ods_json_vs_table.py`：ODS JSON 字段核对脚本：对照当前数据库中的 ODS 表字段，检查示例 JSON（默认目录 export/test-json-doc）
 - `etl_billiards/scripts/check_ods_gaps.py`：ODS 缺失校验脚本：API 主键 vs ODS 主键逐条比对，输出缺失明细样例。
 - `etl_billiards/scripts/reload_ods_windowed.py`：ODS 窗口化补跑脚本：按时间切片重跑 ODS 任务，并可配置窗口粒度与延时。
 - `etl_billiards/scripts/rebuild_db_and_run_ods_to_dwd.py`：一键重建 ETL 相关 Schema，并执行 ODS → DWD。
 - `etl_billiards/scripts/rebuild_ods_from_json.py`：从本地 JSON 示例目录重建 billiards_ods.* 表，并导入样例数据。
 - `etl_billiards/scripts/run_tests.py`：灵活的测试执行脚本，可像搭积木一样组合不同参数或预置命令（模式/数据库/归档路径等），
-- `etl_billiards/scripts/Temp1.py`：空 Python 文件（占位/临时）。
 - `etl_billiards/scripts/test_db_connection.py`：Quick utility for validating PostgreSQL connectivity (ASCII-only output).
 - `etl_billiards/scripts/test_presets.py`：测试命令仓库：集中维护 run_tests.py 的常用组合，支持一键执行。
 
@@ -388,6 +384,33 @@ python -m cli.main --pg-dsn "postgresql://user:pwd@host:5432/db" --store-id 123
 python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
 ```
 
+## 窗口切分与补偿
+用于 ETL 任务、ODS 缺失校验、数据一致性检查等“带时间窗口”的执行场景。逻辑如下：
+- 仅当传入窗口参数（如 CLI `--window-start/--window-end` 或脚本 `--start/--end`）时启用切分。
+- 先对整体窗口前后补偿 N 小时，再按月切分（`month` 为最大单位）。不需要切分时设为 `none`。
+- 分段窗口将依次执行并汇总结果。
+
+配置项（默认值见 `config/defaults.py`）：
+- `run.window_split.unit`：`month` / `none`（默认 `month`）
+- `run.window_split.compensation_hours`：整数小时（默认 2）
+
+环境变量：
+- `WINDOW_SPLIT_UNIT`
+- `WINDOW_COMPENSATION_HOURS`
+
+CLI 参数（覆盖配置）：
+- `python -m cli.main`：`--window-split-unit`，`--window-compensation-hours`
+- `scripts/check_ods_gaps.py`：`--window-split-unit`，`--window-compensation-hours`
+- `scripts/check_data_integrity.py`：`--window-split-unit`，`--window-compensation-hours`
+- `scripts/reload_ods_windowed.py`：`--window-split-unit`，`--window-compensation-hours`
+
+示例（`unit=month`，`compensation_hours=2`）：
+- 传入窗口：`2025/11/10 10:00` - `2026/1/19 10:15`
+- 实际处理窗口切分：
+  - `2025/11/10 08:00` - `2025/12/01 00:00`
+  - `2025/12/01 00:00` - `2026/01/01 00:00`
+  - `2026/01/01 00:00` - `2026/01/19 12:15`
+
 ## 测试
 说明：仓库未固定 pytest 版本（运行测试需自行安装 `pytest`）。
 
@@ -419,7 +442,7 @@ python scripts/test_db_connection.py --dsn "postgresql://user:pwd@host:5432/db"
 - 离线回放/重建 ODS（开发/运维）：  
   ```bash
   cd etl_billiards
-  python scripts/rebuild_ods_from_json.py --dsn "$PG_DSN" --json-dir "C:\\path\\to\\json-doc"
+  python scripts/rebuild_ods_from_json.py --dsn "$PG_DSN" --json-dir "export/test-json-doc"
   ```
 
 ## ODS 表概览（数据路径）
@@ -584,10 +607,10 @@ python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_BUILD_ORDER_SUMMARY
 - `--log-level` 日志级别（`INFO`/`DEBUG`）。
 - `--no-log-console` 禁用控制台日志记录（仅写入文件）。
 
-示例（按桌、按天设置窗口）：
+示例（按月切分 + 前后补偿 2h）：
 ```bash
 cd etl_billiards
-python scripts/check_ods_gaps.py --start 2025-07-01 --window-days 1 --task-codes ODS_PAYMENT --sleep-per-window-seconds 0.5
+python scripts/check_ods_gaps.py --start 2025-07-01 --end 2025-09-30 --window-split-unit month --window-compensation-hours 2 --task-codes ODS_PAYMENT --sleep-per-window-seconds 0.5
-python scripts/reload_ods_windowed.py --tasks ODS_PAYMENT,ODS_TABLE_USE --start 2025-07-01 --window-days 1 --sleep-seconds 1
+python scripts/reload_ods_windowed.py --tasks ODS_PAYMENT,ODS_TABLE_USE --start 2025-07-01 --end 2025-09-30 --window-split-unit month --window-compensation-hours 2 --sleep-seconds 1
 python run_update.py --check-ods-gaps --check-ods-window-days 1 --check-ods-sleep-per-window-seconds 0.5
-```
+```

app/etl_busy.py

@@ -1,9 +0,0 @@
-# app/etl_busy.py
-def run():
-    """
-    忙时抓取逻辑。
-    TODO: 这里写具体抓取流程（API 调用 / 网页解析 / 写入 PostgreSQL 等）
-    """
-    print("Running busy-period ETL...")
-    # 示例：后续在这里接 PostgreSQL 或 HTTP 抓取
-    # ...

app/etl_idle.py

@@ -1,8 +0,0 @@
-# app/etl_idle.py
-def run():
-    """
-    闲时抓取逻辑。
-    可以做全量同步、大批量历史修正等。
-    """
-    print("Running idle-period ETL...")
-    # ...

app/runner.py

@@ -1,31 +0,0 @@
-# app/runner.py
-import argparse
-from datetime import datetime
-
-from . import etl_busy, etl_idle
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Feiqiu ETL Runner")
-    parser.add_argument(
-        "--mode",
-        choices=["busy", "idle"],
-        required=True,
-        help="ETL mode: busy or idle",
-    )
-
-    args = parser.parse_args()
-    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
-    print(f"[{now}] Start ETL mode={args.mode}")
-
-    if args.mode == "busy":
-        etl_busy.run()
-    else:
-        etl_idle.run()
-
-    print(f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] ETL finished.")
-
-
-if __name__ == "__main__":
-    main()

etl_billiards/.env

@@ -1,53 +1,132 @@
-# -*- coding: utf-8 -*-
+# ==============================================================================
-# 文件说明：ETL 环境变量（config/env_parser.py 读取），用于数据库连接、目录与运行参数。
+# ETL 系统配置文件
+# ==============================================================================
+# 配置优先级：DEFAULTS < .env < CLI 参数
 
-# 数据库连接字符串，config/env_parser.py -> db.dsn，所有任务必需
+# ------------------------------------------------------------------------------
+# 数据库配置
+# ------------------------------------------------------------------------------
+# 完整 DSN（优先使用，如果设置了则忽略下面的 host/port/name/user/password）
 PG_DSN=postgresql://local-Python:Neo-local-1991125@100.64.0.4:5432/LLZQ-test
-# 数据库连接超时秒，config/env_parser.py -> db.connect_timeout_sec
+
+# 分离式配置（如果不使用 DSN，可以单独配置以下参数）
+# PG_HOST=localhost
+# PG_PORT=5432
+# PG_NAME=your_database
+# PG_USER=your_user
+# PG_PASSWORD=your_password
+
+# 连接超时（秒，范围 1-20）
 PG_CONNECT_TIMEOUT=10
 
-# 门店/租户ID，config/env_parser.py -> app.store_id，任务调度记录使用
+# ------------------------------------------------------------------------------
-STORE_ID=2790685415443269
+# 数据库 Schema 配置
-# 时区标识，config/env_parser.py -> app.timezone
+# ------------------------------------------------------------------------------
-TIMEZONE=Asia/Taipei
+# OLTP 业务数据 schema（默认 billiards）
+SCHEMA_OLTP=billiards
 
-# API 基础地址，config/env_parser.py -> api.base_url，FETCH 类任务调用
+# ETL 管理数据 schema（默认 etl_admin）
+SCHEMA_ETL=etl_admin
+
+# ------------------------------------------------------------------------------
+# API 配置
+# ------------------------------------------------------------------------------
 API_BASE=https://pc.ficoo.vip/apiprod/admin/v1/
-# API 鉴权 Token，config/env_parser.py -> api.token，FETCH 类任务调用
+API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQtdHlwZSI6IjQiLCJ1c2VyLXR5cGUiOiIxIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiMTIiLCJyb2xlLWlkIjoiMTIiLCJ0ZW5hbnQtaWQiOiIyNzkwNjgzMTYwNzA5OTU3Iiwibmlja25hbWUiOiLnp5_miLfnrqHnkIblkZjvvJrmganmgakxIiwic2l0ZS1pZCI6IjAiLCJtb2JpbGUiOiIxMzgxMDUwMjMwNCIsInNpZCI6IjI5NTA0ODk2NTgzOTU4NDUiLCJzdGFmZi1pZCI6IjMwMDk5MTg2OTE1NTkwNDUiLCJvcmctaWQiOiIwIiwicm9sZS10eXBlIjoiMyIsInJlZnJlc2hUb2tlbiI6Iks1ZnBhYlRTNkFsR0FpMmN4WGYrMHdJVkk0L2UvTVQrSVBHM3V5VWRrSjg9IiwicmVmcmVzaEV4cGlyeVRpbWUiOiIyMDI2LzEvMzEg5LiL5Y2IMTA6MTQ6NTEiLCJuZWVkQ2hlY2tUb2tlbiI6ImZhbHNlIiwiZXhwIjoxNzY5ODY4ODkxLCJpc3MiOiJ0ZXN0IiwiYXVkIjoiVXNlciJ9.BH3-iwwrBczb8aFfI__6kwe3AIsEPacN9TruaTrQ3nY
-API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQtdHlwZSI6IjQiLCJ1c2VyLXR5cGUiOiIxIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiMTIiLCJyb2xlLWlkIjoiMTIiLCJ0ZW5hbnQtaWQiOiIyNzkwNjgzMTYwNzA5OTU3Iiwibmlja25hbWUiOiLnp5_miLfnrqHnkIblkZjvvJrmganmgakxIiwic2l0ZS1pZCI6IjAiLCJtb2JpbGUiOiIxMzgxMDUwMjMwNCIsInNpZCI6IjI5NTA0ODk2NTgzOTU4NDUiLCJzdGFmZi1pZCI6IjMwMDk5MTg2OTE1NTkwNDUiLCJvcmctaWQiOiIwIiwicm9sZS10eXBlIjoiMyIsInJlZnJlc2hUb2tlbiI6IlpWV3grVThBc2FYekFJeTRiaXF6MktwNjMxbTFNRlozV3pLaXNjOHREY289IiwicmVmcmVzaEV4cGlyeVRpbWUiOiIyMDI2LzEvMTcg5LiL5Y2INDoyMjo1OSIsIm5lZWRDaGVja1Rva2VuIjoiZmFsc2UiLCJleHAiOjE3Njg2MzgxNzksImlzcyI6InRlc3QiLCJhdWQiOiJVc2VyIn0.PVeAIx1iHqmHRNaQ4OMFPuOlHBoE47bR5TGJjZP-eOE
+
-# API 请求超时秒，config/env_parser.py -> api.timeout_sec
+# API 请求超时（秒）
 API_TIMEOUT=20
-# API 分页大小，config/env_parser.py -> api.page_size
+
+# 分页大小
 API_PAGE_SIZE=200
-# API 最大重试次数，config/env_parser.py -> api.retries.max_attempts
+
+# 最大重试次数
 API_RETRY_MAX=3
 
-# 日志根目录，config/env_parser.py -> io.log_root，Init/任务运行写日志
+# 重试退避时间（JSON 数组格式，单位秒）
-LOG_ROOT=C:\dev\LLTQ\export\LOG
+# API_RETRY_BACKOFF=[1, 2, 4]
-# JSON 导出根目录，config/env_parser.py -> io.export_root，FETCH 产出及 INIT 准备
-EXPORT_ROOT=C:\dev\LLTQ\export\JSON
 
-# FETCH 模式本地输出目录，config/env_parser.py -> pipeline.fetch_root
+# ------------------------------------------------------------------------------
-FETCH_ROOT=C:\dev\LLTQ\export\JSON
+# 门店配置
-# 本地入库 JSON 目录，config/env_parser.py -> pipeline.ingest_source_dir，MANUAL_INGEST/INGEST_ONLY 使用
+# ------------------------------------------------------------------------------
-INGEST_SOURCE_DIR=C:\dev\LLTQ\export\test-json-doc
+STORE_ID=2790685415443269
+TIMEZONE=Asia/Taipei
 
-# JSON 漂亮格式输出开关，config/env_parser.py -> io.write_pretty_json
+# ------------------------------------------------------------------------------
+# 路径配置
+# ------------------------------------------------------------------------------
+# 导出根目录
+EXPORT_ROOT=export/JSON
+
+# 日志根目录
+LOG_ROOT=export/LOG
+
+# 在线抓取 JSON 输出目录
+FETCH_ROOT=export/JSON
+
+# 本地入库数据源目录（INGEST_ONLY 模式使用）
+INGEST_SOURCE_DIR=export/test-json-doc
+
+# ------------------------------------------------------------------------------
+# 流水线配置
+# ------------------------------------------------------------------------------
+# 运行模式：FULL（抓取+入库）、FETCH_ONLY（仅抓取）、INGEST_ONLY（仅入库）
+PIPELINE_FLOW=FULL
+
+# JSON 美化输出（调试用，会增加文件大小）
 WRITE_PRETTY_JSON=false
 
-# 运行流程：FULL / FETCH_ONLY / INGEST_ONLY，config/env_parser.py -> pipeline.flow
+# ------------------------------------------------------------------------------
-PIPELINE_FLOW=FULL
+# 时间窗口配置
-# 指定任务列表（逗号分隔，覆盖默认），config/env_parser.py -> run.tasks
+# ------------------------------------------------------------------------------
-# RUN_TASKS=INIT_ODS_SCHEMA,MANUAL_INGEST
+# 冗余窗口（秒），向前多抓取的时间避免边界数据丢失
-
-# 固定回溯窗口（可选）：同时设置 WINDOW_START + WINDOW_END，将覆盖游标/当前时间窗口
-# WINDOW_START=2025-07-01 00:00:00
-# WINDOW_END=2025-08-01 00:00:00
-
-# 窗口/补偿参数，config/env_parser.py -> run.*
 OVERLAP_SECONDS=120
+
+# 忙时窗口大小（分钟）
 WINDOW_BUSY_MIN=30
+
+# 闲时窗口大小（分钟）
 WINDOW_IDLE_MIN=180
+
+# 闲时窗口定义（HH:MM 格式）
 IDLE_START=04:00
 IDLE_END=16:00
+
+# 窗口切分单位（month/none），用于长时间回溯任务按月切分
+WINDOW_SPLIT_UNIT=month
+
+# 窗口前后补偿小时数，用于捕获边界数据
+WINDOW_COMPENSATION_HOURS=2
+
+# 允许空结果推进窗口
 ALLOW_EMPTY_RESULT_ADVANCE=true
+
+# ------------------------------------------------------------------------------
+# 数据完整性检查配置
+# ------------------------------------------------------------------------------
+# 检查模式：history（历史全量）、recent（最近增量）
+INTEGRITY_MODE=history
+
+# 历史检查起始日期（history 模式使用）
+INTEGRITY_HISTORY_START=2025-07-01
+
+# 历史检查结束日期（留空表示到当前）
+INTEGRITY_HISTORY_END=
+
+# 是否包含维度表校验
+INTEGRITY_INCLUDE_DIMENSIONS=true
+
+# 发现丢失数据时是否自动补全
+INTEGRITY_AUTO_BACKFILL=true
+
+# 自动执行完整性检查（ETL 完成后自动触发）
+INTEGRITY_AUTO_CHECK=false
+
+# 指定要校验的 ODS 任务代码（逗号分隔，留空表示全部）
+# INTEGRITY_ODS_TASK_CODES=ODS_PAYMENT,ODS_MEMBER
+
+# ------------------------------------------------------------------------------
+# 默认任务列表（逗号分隔，可被 CLI --tasks 参数覆盖）
+# ------------------------------------------------------------------------------
+# RUN_TASKS=ODS_PAYMENT,ODS_MEMBER,ODS_SETTLEMENT_RECORDS,DWD_LOAD_FROM_ODS
+

etl_billiards/ETL_Manager.spec

@@ -0,0 +1,44 @@
+# -*- mode: python ; coding: utf-8 -*-
+
+
+a = Analysis(
+    ['C:\\dev\\LLTQ\\ETL\\feiqiu-ETL\\etl_billiards\\gui\\main.py'],
+    pathex=[],
+    binaries=[],
+    datas=[('C:\\dev\\LLTQ\\ETL\\feiqiu-ETL\\etl_billiards\\gui\\resources', 'gui/resources'), ('C:\\dev\\LLTQ\\ETL\\feiqiu-ETL\\etl_billiards\\database\\schema_dwd_doc.sql', 'database'), ('C:\\dev\\LLTQ\\ETL\\feiqiu-ETL\\etl_billiards\\database\\schema_dws.sql', 'database'), ('C:\\dev\\LLTQ\\ETL\\feiqiu-ETL\\etl_billiards\\database\\schema_etl_admin.sql', 'database'), ('C:\\dev\\LLTQ\\ETL\\feiqiu-ETL\\etl_billiards\\database\\schema_ODS_doc.sql', 'database'), ('C:\\dev\\LLTQ\\ETL\\feiqiu-ETL\\etl_billiards\\database\\seed_ods_tasks.sql', 'database'), ('C:\\dev\\LLTQ\\ETL\\feiqiu-ETL\\etl_billiards\\database\\seed_scheduler_tasks.sql', 'database')],
+    hiddenimports=['PySide6.QtCore', 'PySide6.QtGui', 'PySide6.QtWidgets', 'psycopg2', 'psycopg2.extras', 'psycopg2.extensions', 'gui.models.task_model', 'gui.models.schedule_model', 'gui.utils.cli_builder', 'gui.utils.config_helper', 'gui.utils.app_settings', 'gui.workers.task_worker', 'gui.workers.db_worker', 'gui.widgets.settings_dialog'],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=['matplotlib', 'numpy', 'pandas', 'scipy', 'PIL', 'cv2', 'tkinter'],
+    noarchive=False,
+    optimize=0,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name='ETL_Manager',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    console=False,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.datas,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    name='ETL_Manager',
+)

etl_billiards/build_exe.py

@@ -0,0 +1,181 @@
+# -*- coding: utf-8 -*-
+"""
+ETL GUI 打包脚本
+
+使用 PyInstaller 将 GUI 应用打包为 Windows EXE
+
+用法:
+    python build_exe.py [--onefile] [--console] [--clean]
+
+参数:
+    --onefile   打包为单个 EXE 文件（默认为目录模式）
+    --console   显示控制台窗口（调试用）
+    --clean     打包前清理旧的构建文件
+"""
+
+import os
+import sys
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def get_project_root() -> Path:
+    """获取项目根目录"""
+    return Path(__file__).resolve().parent
+
+
+def clean_build():
+    """清理旧的构建文件"""
+    project_root = get_project_root()
+    
+    dirs_to_clean = [
+        project_root / "build",
+        project_root / "dist",
+    ]
+    
+    files_to_clean = [
+        project_root / "etl_gui.spec",
+    ]
+    
+    for d in dirs_to_clean:
+        if d.exists():
+            print(f"清理目录: {d}")
+            shutil.rmtree(d)
+    
+    for f in files_to_clean:
+        if f.exists():
+            print(f"清理文件: {f}")
+            f.unlink()
+
+
+def build_exe(onefile: bool = False, console: bool = False):
+    """构建 EXE"""
+    project_root = get_project_root()
+    
+    # 主入口
+    main_script = project_root / "gui" / "main.py"
+    
+    # 资源文件
+    resources_dir = project_root / "gui" / "resources"
+    database_dir = project_root / "database"
+    
+    # 构建 PyInstaller 命令
+    # 使用 ASCII 名称避免 Windows 控制台编码问题
+    cmd = [
+        sys.executable, "-m", "PyInstaller",
+        "--name", "ETL_Manager",
+        "--noconfirm",
+    ]
+    
+    # 单文件或目录模式
+    if onefile:
+        cmd.append("--onefile")
+    else:
+        cmd.append("--onedir")
+    
+    # 窗口模式
+    if not console:
+        cmd.append("--windowed")
+    
+    # 添加数据文件
+    # 样式表
+    if resources_dir.exists():
+        cmd.extend(["--add-data", f"{resources_dir};gui/resources"])
+    
+    # 数据库 SQL 文件
+    if database_dir.exists():
+        for sql_file in database_dir.glob("*.sql"):
+            cmd.extend(["--add-data", f"{sql_file};database"])
+    
+    # 隐式导入
+    hidden_imports = [
+        "PySide6.QtCore",
+        "PySide6.QtGui",
+        "PySide6.QtWidgets",
+        "psycopg2",
+        "psycopg2.extras",
+        "psycopg2.extensions",
+        # GUI 模块
+        "gui.models.task_model",
+        "gui.models.schedule_model",
+        "gui.utils.cli_builder",
+        "gui.utils.config_helper",
+        "gui.utils.app_settings",
+        "gui.workers.task_worker",
+        "gui.workers.db_worker",
+        "gui.widgets.settings_dialog",
+    ]
+    for imp in hidden_imports:
+        cmd.extend(["--hidden-import", imp])
+    
+    # 排除不需要的模块（减小体积）
+    excludes = [
+        "matplotlib",
+        "numpy",
+        "pandas",
+        "scipy",
+        "PIL",
+        "cv2",
+        "tkinter",
+    ]
+    for exc in excludes:
+        cmd.extend(["--exclude-module", exc])
+    
+    # 工作目录
+    cmd.extend(["--workpath", str(project_root / "build")])
+    cmd.extend(["--distpath", str(project_root / "dist")])
+    cmd.extend(["--specpath", str(project_root)])
+    
+    # 主脚本
+    cmd.append(str(main_script))
+    
+    print("执行命令:")
+    print(" ".join(cmd))
+    print()
+    
+    # 执行打包
+    result = subprocess.run(cmd, cwd=str(project_root))
+    
+    if result.returncode == 0:
+        print()
+        print("=" * 50)
+        print("打包成功!")
+        print(f"输出目录: {project_root / 'dist'}")
+        print("=" * 50)
+    else:
+        print()
+        print("打包失败，请检查错误信息")
+        sys.exit(1)
+
+
+def main():
+    """主函数"""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="ETL GUI 打包工具")
+    parser.add_argument("--onefile", action="store_true", help="打包为单个 EXE")
+    parser.add_argument("--console", action="store_true", help="显示控制台窗口")
+    parser.add_argument("--clean", action="store_true", help="打包前清理")
+    
+    args = parser.parse_args()
+    
+    # 检查 PyInstaller
+    try:
+        import PyInstaller
+        print(f"PyInstaller 版本: {PyInstaller.__version__}")
+    except ImportError:
+        print("错误: 未安装 PyInstaller")
+        print("请运行: pip install pyinstaller")
+        sys.exit(1)
+    
+    # 清理
+    if args.clean:
+        clean_build()
+    
+    # 构建
+    build_exe(onefile=args.onefile, console=args.console)
+
+
+if __name__ == "__main__":
+    main()

etl_billiards/cli/main.py

@@ -57,6 +57,17 @@ def parse_args():
         action="store_true",
         help="强制使用 window_start/window_end，不走 MAX(fetched_at) 兜底",
     )
+    parser.add_argument(
+        "--window-split-unit",
+        dest="window_split_unit",
+        help="窗口切分单位（month/none），默认来自配置 run.window_split.unit",
+    )
+    parser.add_argument(
+        "--window-compensation-hours",
+        dest="window_compensation_hours",
+        type=int,
+        help="窗口前后补偿小时数，默认来自配置 run.window_split.compensation_hours",
+    )
     
     # 目录参数
     parser.add_argument("--export-root", help="导出根目录")
@@ -134,6 +145,12 @@ def build_cli_overrides(args) -> dict:
             overrides["run"]["window_override"]["end"] = args.window_end
     if args.force_window_override:
         overrides.setdefault("run", {})["force_window_override"] = True
+    if args.window_split_unit:
+        overrides.setdefault("run", {}).setdefault("window_split", {})["unit"] = args.window_split_unit
+    if args.window_compensation_hours is not None:
+        overrides.setdefault("run", {}).setdefault("window_split", {})[
+            "compensation_hours"
+        ] = args.window_compensation_hours
 
     # 运行窗口
     if args.idle_start:

etl_billiards/config/defaults.py

@@ -58,6 +58,10 @@ DEFAULTS = {
             "default_idle": 180,
         },
         "overlap_seconds": 120,
+        "window_split": {
+            "unit": "month",
+            "compensation_hours": 2,
+        },
         "idle_window": {
             "start": "04:00",
             "end": "16:00",
@@ -65,8 +69,8 @@ DEFAULTS = {
         "allow_empty_result_advance": True,
     },
     "io": {
-        "export_root": r"C:\dev\LLTQ\export\JSON",
+        "export_root": "export/JSON",
-        "log_root": r"C:\dev\LLTQ\export\LOG",
+        "log_root": "export/LOG",
         "manifest_name": "manifest.json",
         "ingest_report_name": "ingest_report.json",
         "write_pretty_json": True,
@@ -76,7 +80,7 @@ DEFAULTS = {
         # 运行流程：FETCH_ONLY（仅在线抓取落盘）、INGEST_ONLY（本地清洗入库）、FULL（抓取 + 清洗入库）
         "flow": "FULL",
         # 在线抓取 JSON 输出根目录（按任务、run_id 与时间自动创建子目录）
-        "fetch_root": r"C:\dev\LLTQ\export\JSON",
+        "fetch_root": "export/JSON",
         # 本地清洗入库时的 JSON 输入目录（为空则默认使用本次抓取目录）
         "ingest_source_dir": "",
     },
@@ -97,10 +101,19 @@ DEFAULTS = {
     },
     "ods": {
         # ODS 离线重建/回放相关（仅开发/运维使用）
-        "json_doc_dir": r"C:\dev\LLTQ\export\test-json-doc",
+        "json_doc_dir": "export/test-json-doc",
         "include_files": "",
         "drop_schema_first": True,
     },
+    "integrity": {
+        "mode": "history",
+        "history_start": "2025-07-01",
+        "history_end": "",
+        "include_dimensions": False,
+        "auto_check": False,
+        "ods_task_codes": "",
+    },
+
 }
 
 # 任务代码常量

etl_billiards/config/env_parser.py

@@ -42,11 +42,20 @@ ENV_MAP = {
     "ALLOW_EMPTY_ADVANCE": ("run.allow_empty_result_advance",),
     "WINDOW_START": ("run.window_override.start",),
     "WINDOW_END": ("run.window_override.end",),
+    "WINDOW_SPLIT_UNIT": ("run.window_split.unit",),
+    "WINDOW_COMPENSATION_HOURS": ("run.window_split.compensation_hours",),
     "PIPELINE_FLOW": ("pipeline.flow",),
     "JSON_FETCH_ROOT": ("pipeline.fetch_root",),
     "JSON_SOURCE_DIR": ("pipeline.ingest_source_dir",),
     "FETCH_ROOT": ("pipeline.fetch_root",),
     "INGEST_SOURCE_DIR": ("pipeline.ingest_source_dir",),
+    "INTEGRITY_MODE": ("integrity.mode",),
+    "INTEGRITY_HISTORY_START": ("integrity.history_start",),
+    "INTEGRITY_HISTORY_END": ("integrity.history_end",),
+    "INTEGRITY_INCLUDE_DIMENSIONS": ("integrity.include_dimensions",),
+    "INTEGRITY_AUTO_CHECK": ("integrity.auto_check",),
+    "INTEGRITY_AUTO_BACKFILL": ("integrity.auto_backfill",),
+    "INTEGRITY_ODS_TASK_CODES": ("integrity.ods_task_codes",),
 }
 
 

etl_billiards/database/schema_ODS_doc.sql

@@ -25,7 +25,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.member_profiles (
     payload                  JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.member_profiles IS 'ODS 原始明细表：会员档案/会员账户信息。来源：C:/dev/LLTQ/export/test-json-doc/member_profiles.json；分析：member_profiles-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.member_profiles IS 'ODS 原始明细表：会员档案/会员账户信息。来源：export/test-json-doc/member_profiles.json；分析：member_profiles-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.member_profiles.tenant_id IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】member_profiles.json - data.tenantMemberInfos - tenant_id。';
 COMMENT ON COLUMN billiards_ods.member_profiles.register_site_id IS '【说明】会员的注册门店 ID。     【示例】2790685415443269（用于会员的注册门店 ID）。          【JSON字段】member_profiles.json - data.tenantMemberInfos - register_site_id。';
 COMMENT ON COLUMN billiards_ods.member_profiles.site_name IS '【说明】注册门店名称，属于冗余字段，用于直接展示。     【示例】朗朗桌球（注册门店名称，属于冗余字段，用于直接展示）。          【JSON字段】member_profiles.json - data.tenantMemberInfos - site_name。';
@@ -42,7 +42,7 @@ COMMENT ON COLUMN billiards_ods.member_profiles.status IS '【说明】帐户状
 COMMENT ON COLUMN billiards_ods.member_profiles.user_status IS '【说明】用户账号状态（偏“用户逻辑”层面的状态）。     【示例】1（用于用户账号状态（偏“用户逻辑”层面的状态））。          【JSON字段】member_profiles.json - data.tenantMemberInfos - user_status。';
 COMMENT ON COLUMN billiards_ods.member_profiles.create_time IS '【说明】会员账户的创建时间（即这条档案/这张卡在系统中被创建的时间）。     【示例】2025-11-08 01:29:33（用于会员账户的创建时间（即这条档案/这张卡在系统中被创建的时间））。          【JSON字段】member_profiles.json - data.tenantMemberInfos - create_time。';
 COMMENT ON COLUMN billiards_ods.member_profiles.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】member_profiles.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】member_profiles.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.member_profiles.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/member_profiles.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】member_profiles.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.member_profiles.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/member_profiles.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】member_profiles.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.member_profiles.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】member_profiles.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.member_profiles.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】member_profiles.json - data.tenantMemberInfos - $。';
 
@@ -79,7 +79,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.member_balance_changes (
     payload               JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.member_balance_changes IS 'ODS 原始明细表：会员余额变更流水。来源：C:/dev/LLTQ/export/test-json-doc/member_balance_changes.json；分析：member_balance_changes-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.member_balance_changes IS 'ODS 原始明细表：会员余额变更流水。来源：export/test-json-doc/member_balance_changes.json；分析：member_balance_changes-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.member_balance_changes.tenant_id IS '【说明】租户/商户 ID，本数据中是固定值（同一品牌/商户）。     【示例】2790683160709957（用于租户/商户 ID，本数据中是固定值（同一品牌/商户））。          【JSON字段】member_balance_changes.json - data.tenantMemberCardLogs - tenant_id。';
 COMMENT ON COLUMN billiards_ods.member_balance_changes.site_id IS '【说明】非 0：记录所属的具体门店 ID（与其他 JSON 内的 site_id 一致）。     【示例】2790685415443269（用于非 0：记录所属的具体门店 ID（与其他 JSON 内的 site_id 一致））。          【JSON字段】member_balance_changes.json - data.tenantMemberCardLogs - site_id。';
 COMMENT ON COLUMN billiards_ods.member_balance_changes.register_site_id IS '【说明】会员卡的“注册门店 ID”，即办卡所在门店。     【示例】2790685415443269（用于会员卡的“注册门店 ID”，即办卡所在门店）。          【JSON字段】member_balance_changes.json - data.tenantMemberCardLogs - register_site_id。';
@@ -106,7 +106,7 @@ COMMENT ON COLUMN billiards_ods.member_balance_changes.operator_name IS '【说
 COMMENT ON COLUMN billiards_ods.member_balance_changes.is_delete IS '【说明】逻辑删除标记（0=否，1=是）。     【示例】0（用于逻辑删除标记（0=否，1=是））。          【JSON字段】member_balance_changes.json - data.tenantMemberCardLogs - is_delete。';
 COMMENT ON COLUMN billiards_ods.member_balance_changes.create_time IS '【说明】本条余额变更记录的创建时间，通常接近交易发生时间。     【示例】2025-11-09 22:52:48（用于本条余额变更记录的创建时间，通常接近交易发生时间）。          【JSON字段】member_balance_changes.json - data.tenantMemberCardLogs - create_time。';
 COMMENT ON COLUMN billiards_ods.member_balance_changes.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】member_balance_changes.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】member_balance_changes.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.member_balance_changes.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/member_balance_changes.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】member_balance_changes.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.member_balance_changes.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/member_balance_changes.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】member_balance_changes.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.member_balance_changes.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】member_balance_changes.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.member_balance_changes.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】member_balance_changes.json - data.tenantMemberCardLogs - $。';
 
@@ -187,7 +187,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.member_stored_value_cards (
     payload                           JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.member_stored_value_cards IS 'ODS 原始明细表：会员储值/卡券账户列表。来源：C:/dev/LLTQ/export/test-json-doc/member_stored_value_cards.json；分析：member_stored_value_cards-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.member_stored_value_cards IS 'ODS 原始明细表：会员储值/卡券账户列表。来源：export/test-json-doc/member_stored_value_cards.json；分析：member_stored_value_cards-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.member_stored_value_cards.tenant_id IS '【说明】租户/品牌 ID，与其他 JSON 中 tenant_id 一致。     【示例】2790683160709957（用于租户/品牌 ID，与其他 JSON 中 tenant_id 一致）。          【JSON字段】member_stored_value_cards.json - data.tenantMemberCards - tenant_id。';
 COMMENT ON COLUMN billiards_ods.member_stored_value_cards.tenant_member_id IS '【说明】当前商户（品牌/租户）中会员的主键 ID。     【示例】2955204541320325（用于当前商户（品牌/租户）中会员的主键 ID）。          【JSON字段】member_stored_value_cards.json - data.tenantMemberCards - tenant_member_id。';
 COMMENT ON COLUMN billiards_ods.member_stored_value_cards.system_member_id IS '【说明】系统级会员 ID（跨门店统一主键）。     【示例】2955204540009605（用于系统级会员 ID（跨门店统一主键））。          【JSON字段】member_stored_value_cards.json - data.tenantMemberCards - system_member_id。';
@@ -258,7 +258,7 @@ COMMENT ON COLUMN billiards_ods.member_stored_value_cards.tenantName IS '【说
 COMMENT ON COLUMN billiards_ods.member_stored_value_cards.pdAssisnatLevel IS '【说明】允许使用的“陪打/助教等级”列表。     【示例】[]（用于允许使用的“陪打/助教等级”列表）。          【JSON字段】member_stored_value_cards.json - data.tenantMemberCards - pdAssisnatLevel。';
 COMMENT ON COLUMN billiards_ods.member_stored_value_cards.cxAssisnatLevel IS '【说明】可能是“促销活动中的助教等级限制”（命名中 cx 多为“促销”缩写）。     【示例】[]（用于可能是“促销活动中的助教等级限制”（命名中 cx 多为“促销”缩写））。          【JSON字段】member_stored_value_cards.json - data.tenantMemberCards - cxAssisnatLevel。';
 COMMENT ON COLUMN billiards_ods.member_stored_value_cards.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】member_stored_value_cards.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】member_stored_value_cards.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.member_stored_value_cards.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/member_stored_value_cards.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】member_stored_value_cards.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.member_stored_value_cards.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/member_stored_value_cards.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】member_stored_value_cards.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.member_stored_value_cards.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】member_stored_value_cards.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.member_stored_value_cards.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】member_stored_value_cards.json - data.tenantMemberCards - $。';
 
@@ -331,7 +331,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.recharge_settlements (
     payload               JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.recharge_settlements IS 'ODS 原始明细表：充值结算记录。来源：C:/dev/LLTQ/export/test-json-doc/recharge_settlements.json；分析：recharge_settlements-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.recharge_settlements IS 'ODS 原始明细表：充值结算记录。来源：export/test-json-doc/recharge_settlements.json；分析：recharge_settlements-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.recharge_settlements.id IS '【说明】门店 ID。     【示例】NULL（用于门店 ID）。          【JSON字段】recharge_settlements.json - $ - id。';
 COMMENT ON COLUMN billiards_ods.recharge_settlements.tenantid IS '【说明】来自 JSON 导出的原始字段，用于保留业务取值。     【示例】NULL（来自 JSON 导出的原始字段，用于保留业务取值）。          【JSON字段】recharge_settlements.json - $ - tenantid。';
 COMMENT ON COLUMN billiards_ods.recharge_settlements.siteid IS '【说明】来自 JSON 导出的原始字段，用于保留业务取值。     【示例】NULL（来自 JSON 导出的原始字段，用于保留业务取值）。          【JSON字段】recharge_settlements.json - $ - siteid。';
@@ -394,7 +394,7 @@ COMMENT ON COLUMN billiards_ods.recharge_settlements.isfirst IS '【说明】来
 COMMENT ON COLUMN billiards_ods.recharge_settlements.rechargecardamount IS '【说明】金额字段，用于计费/结算/分摊等金额计算。     【示例】NULL（金额字段，用于计费/结算/分摊等金额计算）。          【JSON字段】recharge_settlements.json - $ - rechargecardamount。';
 COMMENT ON COLUMN billiards_ods.recharge_settlements.giftcardamount IS '【说明】金额字段，用于计费/结算/分摊等金额计算。     【示例】NULL（金额字段，用于计费/结算/分摊等金额计算）。          【JSON字段】recharge_settlements.json - $ - giftcardamount。';
 COMMENT ON COLUMN billiards_ods.recharge_settlements.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】recharge_settlements.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】recharge_settlements.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.recharge_settlements.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/recharge_settlements.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】recharge_settlements.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.recharge_settlements.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/recharge_settlements.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】recharge_settlements.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.recharge_settlements.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】recharge_settlements.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.recharge_settlements.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】recharge_settlements.json - $ - $。';
 
@@ -467,7 +467,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.settlement_records (
     payload               JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.settlement_records IS 'ODS 原始明细表：结账/结算记录。来源：C:/dev/LLTQ/export/test-json-doc/settlement_records.json；分析：settlement_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.settlement_records IS 'ODS 原始明细表：结账/结算记录。来源：export/test-json-doc/settlement_records.json；分析：settlement_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.settlement_records.id IS '【说明】结账记录主键 ID（订单结算 ID）。     【示例】NULL（用于结账记录主键 ID（订单结算 ID））。          【JSON字段】settlement_records.json - $ - id。';
 COMMENT ON COLUMN billiards_ods.settlement_records.tenantid IS '【说明】来自 JSON 导出的原始字段，用于保留业务取值。     【示例】NULL（来自 JSON 导出的原始字段，用于保留业务取值）。          【JSON字段】settlement_records.json - $ - tenantid。';
 COMMENT ON COLUMN billiards_ods.settlement_records.siteid IS '【说明】来自 JSON 导出的原始字段，用于保留业务取值。     【示例】NULL（来自 JSON 导出的原始字段，用于保留业务取值）。          【JSON字段】settlement_records.json - $ - siteid。';
@@ -530,7 +530,7 @@ COMMENT ON COLUMN billiards_ods.settlement_records.isfirst IS '【说明】来
 COMMENT ON COLUMN billiards_ods.settlement_records.rechargecardamount IS '【说明】金额字段，用于计费/结算/分摊等金额计算。     【示例】NULL（金额字段，用于计费/结算/分摊等金额计算）。          【JSON字段】settlement_records.json - $ - rechargecardamount。';
 COMMENT ON COLUMN billiards_ods.settlement_records.giftcardamount IS '【说明】金额字段，用于计费/结算/分摊等金额计算。     【示例】NULL（金额字段，用于计费/结算/分摊等金额计算）。          【JSON字段】settlement_records.json - $ - giftcardamount。';
 COMMENT ON COLUMN billiards_ods.settlement_records.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】settlement_records.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】settlement_records.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.settlement_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/settlement_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】settlement_records.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.settlement_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/settlement_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】settlement_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.settlement_records.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】settlement_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.settlement_records.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】settlement_records.json - $ - $。';
 
@@ -555,7 +555,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.assistant_cancellation_records (
     payload                JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.assistant_cancellation_records IS 'ODS 原始明细表：助教作废/取消记录。来源：C:/dev/LLTQ/export/test-json-doc/assistant_cancellation_records.json；分析：assistant_cancellation_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.assistant_cancellation_records IS 'ODS 原始明细表：助教作废/取消记录。来源：export/test-json-doc/assistant_cancellation_records.json；分析：assistant_cancellation_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.id IS '【说明】本表主键 ID，用于唯一标识一条记录。     【示例】2957675849518789（本表主键 ID，用于唯一标识一条记录）。          【JSON字段】assistant_cancellation_records.json - data.abolitionAssistants - id。';
 COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.siteId IS '【说明】门店 ID，即该废除记录所在门店。     【示例】2790685415443269（用于门店 ID，即该废除记录所在门店）。          【JSON字段】assistant_cancellation_records.json - data.abolitionAssistants - siteId。';
 COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.siteProfile IS '【说明】门店信息快照。     【示例】{"id": 2790685415443269, "org_id": 2790684179467077, "shop_name": "朗朗桌球", "avatar": "https://oss.ficoo.vip/admin/hXcE4E…（用于门店信息快照）。          【JSON字段】assistant_cancellation_records.json - data.abolitionAssistants - siteProfile。';
@@ -570,7 +570,7 @@ COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.tableName IS '【
 COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.trashReason IS '【说明】用于记录“废除原因”的文本描述，例如“顾客临时有事取消”“录入错误”“更换助教”等。     【示例】NULL（用于记录“废除原因”的文本描述，例如“顾客临时有事取消”“录入错误”“更换助教”等）。          【JSON字段】assistant_cancellation_records.json - data.abolitionAssistants - trashReason。';
 COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.createTime IS '【说明】这条“助教废除记录”被创建的时间，即系统正式记录“废除”操作的时刻。     【示例】2025-11-09 19:23:29（用于这条“助教废除记录”被创建的时间，即系统正式记录“废除”操作的时刻）。          【JSON字段】assistant_cancellation_records.json - data.abolitionAssistants - createTime。';
 COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】assistant_cancellation_records.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】assistant_cancellation_records.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/assistant_cancellation_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】assistant_cancellation_records.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/assistant_cancellation_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】assistant_cancellation_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】assistant_cancellation_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.assistant_cancellation_records.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】assistant_cancellation_records.json - data.abolitionAssistants - $。';
 
@@ -644,7 +644,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.assistant_accounts_master (
     payload                JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.assistant_accounts_master IS 'ODS 原始明细表：助教档案主数据。来源：C:/dev/LLTQ/export/test-json-doc/assistant_accounts_master.json；分析：assistant_accounts_master-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.assistant_accounts_master IS 'ODS 原始明细表：助教档案主数据。来源：export/test-json-doc/assistant_accounts_master.json；分析：assistant_accounts_master-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.assistant_accounts_master.id IS '【说明】助教账号主键 ID，在“助教流水.json”中对应 site_assistant_id。     【示例】2947562271297029（用于助教账号主键 ID，在“助教流水.json”中对应 site_assistant_id）。          【JSON字段】assistant_accounts_master.json - data.assistantInfos - id。';
 COMMENT ON COLUMN billiards_ods.assistant_accounts_master.tenant_id IS '【说明】品牌/租户 ID，对应“非球科技”系统中该商户的唯一标识。     【示例】2790683160709957（用于品牌/租户 ID，对应“非球科技”系统中该商户的唯一标识）。          【JSON字段】assistant_accounts_master.json - data.assistantInfos - tenant_id。';
 COMMENT ON COLUMN billiards_ods.assistant_accounts_master.site_id IS '【说明】门店 ID，对应本次数据的这家球房（朗朗桌球）。     【示例】2790685415443269（用于门店 ID，对应本次数据的这家球房（朗朗桌球））。          【JSON字段】assistant_accounts_master.json - data.assistantInfos - site_id。';
@@ -708,7 +708,7 @@ COMMENT ON COLUMN billiards_ods.assistant_accounts_master.light_equipment_id IS
 COMMENT ON COLUMN billiards_ods.assistant_accounts_master.entry_sign_status IS '【说明】来自 JSON 导出的原始字段，用于保留业务取值。     【示例】0（来自 JSON 导出的原始字段，用于保留业务取值。）。          【JSON字段】assistant_accounts_master.json - data.assistantInfos - entry_sign_status。';
 COMMENT ON COLUMN billiards_ods.assistant_accounts_master.resign_sign_status IS '【说明】离职协议签署状态，类似上面。     【示例】0（用于离职协议签署状态，类似上面）。          【JSON字段】assistant_accounts_master.json - data.assistantInfos - resign_sign_status。';
 COMMENT ON COLUMN billiards_ods.assistant_accounts_master.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】assistant_accounts_master.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】assistant_accounts_master.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.assistant_accounts_master.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/assistant_accounts_master.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】assistant_accounts_master.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.assistant_accounts_master.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/assistant_accounts_master.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】assistant_accounts_master.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.assistant_accounts_master.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】assistant_accounts_master.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.assistant_accounts_master.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】assistant_accounts_master.json - data.assistantInfos - $。';
 
@@ -784,7 +784,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.assistant_service_records (
     fetched_at               TIMESTAMPTZ DEFAULT now()
 );
 
-COMMENT ON TABLE billiards_ods.assistant_service_records IS 'ODS 原始明细表：助教服务流水。来源：C:/dev/LLTQ/export/test-json-doc/assistant_service_records.json；分析：assistant_service_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.assistant_service_records IS 'ODS 原始明细表：助教服务流水。来源：export/test-json-doc/assistant_service_records.json；分析：assistant_service_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.assistant_service_records.id IS '【说明】本条助教流水记录的主键 ID（流水唯一标识）。     【示例】2957913441292165（用于本条助教流水记录的主键 ID（流水唯一标识））。          【JSON字段】assistant_service_records.json - data.orderAssistantDetails - id。';
 COMMENT ON COLUMN billiards_ods.assistant_service_records.tenant_id IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】assistant_service_records.json - data.orderAssistantDetails - tenant_id。';
 COMMENT ON COLUMN billiards_ods.assistant_service_records.site_id IS '【说明】门店 ID，本数据中指“朗朗桌球”这一家门店。     【示例】2790685415443269（用于门店 ID，本数据中指“朗朗桌球”这一家门店）。          【JSON字段】assistant_service_records.json - data.orderAssistantDetails - site_id。';
@@ -851,7 +851,7 @@ COMMENT ON COLUMN billiards_ods.assistant_service_records.is_not_responding IS '
 COMMENT ON COLUMN billiards_ods.assistant_service_records.is_confirm IS '【说明】布尔/开关字段，用于表示权限、可用性或状态开关。     【示例】2（布尔/开关字段，用于表示权限、可用性或状态开关。）。          【JSON字段】assistant_service_records.json - data.orderAssistantDetails - is_confirm。';
 COMMENT ON COLUMN billiards_ods.assistant_service_records.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】assistant_service_records.json - data.orderAssistantDetails - $。';
 COMMENT ON COLUMN billiards_ods.assistant_service_records.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】assistant_service_records.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】assistant_service_records.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.assistant_service_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/assistant_service_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】assistant_service_records.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.assistant_service_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/assistant_service_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】assistant_service_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.assistant_service_records.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】assistant_service_records.json - ETL元数据 - 无。';
 
 
@@ -887,7 +887,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.site_tables_master (
     payload                  JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.site_tables_master IS 'ODS 原始明细表：门店桌台主数据。来源：C:/dev/LLTQ/export/test-json-doc/site_tables_master.json；分析：site_tables_master-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.site_tables_master IS 'ODS 原始明细表：门店桌台主数据。来源：export/test-json-doc/site_tables_master.json；分析：site_tables_master-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.site_tables_master.id IS '【说明】台桌主键 ID。     【示例】2791964216463493（用于台桌主键 ID）。          【JSON字段】site_tables_master.json - data.siteTables - id。';
 COMMENT ON COLUMN billiards_ods.site_tables_master.site_id IS '【说明】门店 ID。     【示例】2790685415443269（用于门店 ID）。          【JSON字段】site_tables_master.json - data.siteTables - site_id。';
 COMMENT ON COLUMN billiards_ods.site_tables_master.siteName IS '【说明】门店名称快照，冗余字段，配合 site_id 使用。     【示例】朗朗桌球（用于门店名称快照，冗余字段，配合 site_id 使用）。          【JSON字段】site_tables_master.json - data.siteTables - siteName。';
@@ -913,7 +913,7 @@ COMMENT ON COLUMN billiards_ods.site_tables_master.table_status IS '【说明】
 COMMENT ON COLUMN billiards_ods.site_tables_master.temporary_light_second IS '【说明】临时点灯时长（秒），例如手动临时开灯一段时间。     【示例】0（用于临时点灯时长（秒），例如手动临时开灯一段时间）。          【JSON字段】site_tables_master.json - data.siteTables - temporary_light_second。';
 COMMENT ON COLUMN billiards_ods.site_tables_master.virtual_table IS '【说明】当前值：全部为 0。     【示例】0（用于当前值：全部为 0）。          【JSON字段】site_tables_master.json - data.siteTables - virtual_table。';
 COMMENT ON COLUMN billiards_ods.site_tables_master.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】site_tables_master.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】site_tables_master.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.site_tables_master.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/site_tables_master.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】site_tables_master.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.site_tables_master.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/site_tables_master.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】site_tables_master.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.site_tables_master.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】site_tables_master.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.site_tables_master.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】site_tables_master.json - data.siteTables - $。';
 
@@ -945,7 +945,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.table_fee_discount_records (
     payload             JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.table_fee_discount_records IS 'ODS 原始明细表：台费折扣记录。来源：C:/dev/LLTQ/export/test-json-doc/table_fee_discount_records.json；分析：table_fee_discount_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.table_fee_discount_records IS 'ODS 原始明细表：台费折扣记录。来源：export/test-json-doc/table_fee_discount_records.json；分析：table_fee_discount_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.table_fee_discount_records.id IS '【说明】台费打折 / 调整流水主键 ID。     【示例】2957913441881989（用于台费打折 / 调整流水主键 ID）。          【JSON字段】table_fee_discount_records.json - data.taiFeeAdjustInfos - id。';
 COMMENT ON COLUMN billiards_ods.table_fee_discount_records.tenant_id IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】table_fee_discount_records.json - data.taiFeeAdjustInfos - tenant_id。';
 COMMENT ON COLUMN billiards_ods.table_fee_discount_records.site_id IS '【说明】门店 ID，本批数据全部为同一家门店（朗朗桌球）。     【示例】2790685415443269（用于门店 ID，本批数据全部为同一家门店（朗朗桌球））。          【JSON字段】table_fee_discount_records.json - data.taiFeeAdjustInfos - site_id。';
@@ -967,7 +967,7 @@ COMMENT ON COLUMN billiards_ods.table_fee_discount_records.order_trade_no IS '
 COMMENT ON COLUMN billiards_ods.table_fee_discount_records.is_delete IS '【说明】逻辑删除标记（0=否，1=是）。     【示例】0（用于逻辑删除标记（0=否，1=是））。          【JSON字段】table_fee_discount_records.json - data.taiFeeAdjustInfos - is_delete。';
 COMMENT ON COLUMN billiards_ods.table_fee_discount_records.create_time IS '【说明】台费调整记录的创建时间，即打折操作被执行的时间戳。     【示例】2025-11-09 23:25:11（用于台费调整记录的创建时间，即打折操作被执行的时间戳）。          【JSON字段】table_fee_discount_records.json - data.taiFeeAdjustInfos - create_time。';
 COMMENT ON COLUMN billiards_ods.table_fee_discount_records.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】table_fee_discount_records.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】table_fee_discount_records.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.table_fee_discount_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/table_fee_discount_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】table_fee_discount_records.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.table_fee_discount_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/table_fee_discount_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】table_fee_discount_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.table_fee_discount_records.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】table_fee_discount_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.table_fee_discount_records.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】table_fee_discount_records.json - data.taiFeeAdjustInfos - $。';
 
@@ -1018,7 +1018,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.table_fee_transactions (
     fetched_at               TIMESTAMPTZ DEFAULT now()
 );
 
-COMMENT ON TABLE billiards_ods.table_fee_transactions IS 'ODS 原始明细表：台费流水。来源：C:/dev/LLTQ/export/test-json-doc/table_fee_transactions.json；分析：table_fee_transactions-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.table_fee_transactions IS 'ODS 原始明细表：台费流水。来源：export/test-json-doc/table_fee_transactions.json；分析：table_fee_transactions-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.table_fee_transactions.id IS '【说明】台费流水记录主键（事实表主键）。     【示例】2957924029058885（用于台费流水记录主键（事实表主键））。          【JSON字段】table_fee_transactions.json - data.siteTableUseDetailsList - id。';
 COMMENT ON COLUMN billiards_ods.table_fee_transactions.tenant_id IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】table_fee_transactions.json - data.siteTableUseDetailsList - tenant_id。';
 COMMENT ON COLUMN billiards_ods.table_fee_transactions.site_id IS '【说明】门店 ID，本次数据全部来自同一门店（朗朗桌球）。     【示例】2790685415443269（用于门店 ID，本次数据全部来自同一门店（朗朗桌球））。          【JSON字段】table_fee_transactions.json - data.siteTableUseDetailsList - site_id。';
@@ -1060,7 +1060,7 @@ COMMENT ON COLUMN billiards_ods.table_fee_transactions.salesman_user_id IS '【
 COMMENT ON COLUMN billiards_ods.table_fee_transactions.create_time IS '【说明】这条台费流水记录的创建时间，通常接近结账时间。     【示例】2025-11-09 23:35:57（用于这条台费流水记录的创建时间，通常接近结账时间）。          【JSON字段】table_fee_transactions.json - data.siteTableUseDetailsList - create_time。';
 COMMENT ON COLUMN billiards_ods.table_fee_transactions.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】table_fee_transactions.json - data.siteTableUseDetailsList - $。';
 COMMENT ON COLUMN billiards_ods.table_fee_transactions.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】table_fee_transactions.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】table_fee_transactions.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.table_fee_transactions.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/table_fee_transactions.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】table_fee_transactions.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.table_fee_transactions.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/table_fee_transactions.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】table_fee_transactions.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.table_fee_transactions.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】table_fee_transactions.json - ETL元数据 - 无。';
 
 
@@ -1090,7 +1090,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.goods_stock_movements (
     payload              JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.goods_stock_movements IS 'ODS 原始明细表：商品库存变动流水。来源：C:/dev/LLTQ/export/test-json-doc/goods_stock_movements.json；分析：goods_stock_movements-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.goods_stock_movements IS 'ODS 原始明细表：商品库存变动流水。来源：export/test-json-doc/goods_stock_movements.json；分析：goods_stock_movements-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.goods_stock_movements.siteGoodsStockId IS '【说明】门店某个“商品库存记录”的主键 ID。     【示例】2957911857581957（用于门店某个“商品库存记录”的主键 ID）。          【JSON字段】goods_stock_movements.json - data.queryDeliveryRecordsList - siteGoodsStockId。';
 COMMENT ON COLUMN billiards_ods.goods_stock_movements.tenantId IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】goods_stock_movements.json - data.queryDeliveryRecordsList - tenantId。';
 COMMENT ON COLUMN billiards_ods.goods_stock_movements.siteId IS '【说明】门店 ID。     【示例】2790685415443269（用于门店 ID）。          【JSON字段】goods_stock_movements.json - data.queryDeliveryRecordsList - siteId。';
@@ -1111,7 +1111,7 @@ COMMENT ON COLUMN billiards_ods.goods_stock_movements.remark IS '【说明】备
 COMMENT ON COLUMN billiards_ods.goods_stock_movements.operatorName IS '【说明】执行此次库存变动的操作人。     【示例】收银员:郑丽珊（用于执行此次库存变动的操作人）。          【JSON字段】goods_stock_movements.json - data.queryDeliveryRecordsList - operatorName。';
 COMMENT ON COLUMN billiards_ods.goods_stock_movements.createTime IS '【说明】这条库存变动记录的创建时间，即发生库存变更的时间点。     【示例】2025-11-09 23:23:34（用于这条库存变动记录的创建时间，即发生库存变更的时间点）。          【JSON字段】goods_stock_movements.json - data.queryDeliveryRecordsList - createTime。';
 COMMENT ON COLUMN billiards_ods.goods_stock_movements.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】goods_stock_movements.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】goods_stock_movements.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.goods_stock_movements.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/goods_stock_movements.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】goods_stock_movements.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.goods_stock_movements.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/goods_stock_movements.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】goods_stock_movements.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.goods_stock_movements.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】goods_stock_movements.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.goods_stock_movements.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】goods_stock_movements.json - data.queryDeliveryRecordsList - $。';
 
@@ -1134,7 +1134,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.stock_goods_category_tree (
     payload                  JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.stock_goods_category_tree IS 'ODS 原始明细表：商品分类树。来源：C:/dev/LLTQ/export/test-json-doc/stock_goods_category_tree.json；分析：stock_goods_category_tree-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.stock_goods_category_tree IS 'ODS 原始明细表：商品分类树。来源：export/test-json-doc/stock_goods_category_tree.json；分析：stock_goods_category_tree-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.id IS '【说明】分类节点主键 ID（在商品分类维度中的唯一标识）。     【示例】2790683528350533（用于分类节点主键 ID（在商品分类维度中的唯一标识））。          【JSON字段】stock_goods_category_tree.json - data.goodsCategoryList - id。';
 COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.tenant_id IS '【说明】租户 ID（品牌/商户 ID）。     【示例】2790683160709957（用于租户 ID（品牌/商户 ID））。          【JSON字段】stock_goods_category_tree.json - data.goodsCategoryList - tenant_id。';
 COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.category_name IS '【说明】分类名称（实际业务分类名称）。     【示例】槟榔（用于分类名称（实际业务分类名称））。          【JSON字段】stock_goods_category_tree.json - data.goodsCategoryList - category_name。';
@@ -1147,7 +1147,7 @@ COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.categoryBoxes IS '【
 COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.sort IS '【说明】分类的排序序号，用于前端展示顺序的控制。     【示例】1（分类的排序序号，用于前端展示顺序的控制）。          【JSON字段】stock_goods_category_tree.json - data.goodsCategoryList - sort。';
 COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.is_warehousing IS '【说明】本文件可视为“所有参与库存管理的商品分类清单”，因此均为 1。     【示例】1（用于本文件可视为“所有参与库存管理的商品分类清单”，因此均为 1）。          【JSON字段】stock_goods_category_tree.json - data.goodsCategoryList - is_warehousing。';
 COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】stock_goods_category_tree.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】stock_goods_category_tree.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/stock_goods_category_tree.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】stock_goods_category_tree.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/stock_goods_category_tree.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】stock_goods_category_tree.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】stock_goods_category_tree.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.stock_goods_category_tree.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】stock_goods_category_tree.json - data.goodsCategoryList - $。';
 
@@ -1173,7 +1173,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.goods_stock_summary (
     payload               JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.goods_stock_summary IS 'ODS 原始明细表：商品库存汇总。来源：C:/dev/LLTQ/export/test-json-doc/goods_stock_summary.json；分析：goods_stock_summary-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.goods_stock_summary IS 'ODS 原始明细表：商品库存汇总。来源：export/test-json-doc/goods_stock_summary.json；分析：goods_stock_summary-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.goods_stock_summary.siteGoodsId IS '【说明】门店商品 ID，本库存汇总表的主键，对应某个具体商品在本店的唯一标识。     【示例】2791953867886725（用于门店商品 ID，本库存汇总表的主键，对应某个具体商品在本店的唯一标识）。          【JSON字段】goods_stock_summary.json - $ - siteGoodsId。';
 COMMENT ON COLUMN billiards_ods.goods_stock_summary.goodsName IS '【说明】商品名称，冗余于门店商品档案的 goods_name。     【示例】东方树叶（用于商品名称，冗余于门店商品档案的 goods_name）。          【JSON字段】goods_stock_summary.json - $ - goodsName。';
 COMMENT ON COLUMN billiards_ods.goods_stock_summary.goodsUnit IS '【说明】商品的计量单位（售卖单位）。     【示例】瓶（用于商品的计量单位（售卖单位））。          【JSON字段】goods_stock_summary.json - $ - goodsUnit。';
@@ -1189,7 +1189,7 @@ COMMENT ON COLUMN billiards_ods.goods_stock_summary.rangeSaleMoney IS '【说明
 COMMENT ON COLUMN billiards_ods.goods_stock_summary.rangeInventory IS '【说明】查询区间内的 盘点调整净变动量（盘盈–盘亏）。     【示例】0（用于查询区间内的 盘点调整净变动量（盘盈–盘亏））。          【JSON字段】goods_stock_summary.json - $ - rangeInventory。';
 COMMENT ON COLUMN billiards_ods.goods_stock_summary.currentStock IS '【说明】导出时刻的实时库存数量。     【示例】118（用于导出时刻的实时库存数量）。          【JSON字段】goods_stock_summary.json - $ - currentStock。';
 COMMENT ON COLUMN billiards_ods.goods_stock_summary.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】goods_stock_summary.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】goods_stock_summary.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.goods_stock_summary.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/goods_stock_summary.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】goods_stock_summary.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.goods_stock_summary.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/goods_stock_summary.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】goods_stock_summary.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.goods_stock_summary.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】goods_stock_summary.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.goods_stock_summary.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】goods_stock_summary.json - $ - $。';
 
@@ -1212,7 +1212,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.payment_transactions (
     payload            JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.payment_transactions IS 'ODS 原始明细表：支付流水。来源：C:/dev/LLTQ/export/test-json-doc/payment_transactions.json；分析：payment_transactions-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.payment_transactions IS 'ODS 原始明细表：支付流水。来源：export/test-json-doc/payment_transactions.json；分析：payment_transactions-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.payment_transactions.id IS '【说明】支付流水记录的主键 ID。     【示例】2957924026486597（用于支付流水记录的主键 ID）。          【JSON字段】payment_transactions.json - $ - id。';
 COMMENT ON COLUMN billiards_ods.payment_transactions.site_id IS '【说明】支付记录所属的门店 ID。     【示例】2790685415443269（用于支付记录所属的门店 ID）。          【JSON字段】payment_transactions.json - $ - site_id。';
 COMMENT ON COLUMN billiards_ods.payment_transactions.siteProfile IS '【说明】门店信息快照，与其他 JSON 中的 siteProfile 结构一致。     【示例】{"id": 2790685415443269, "org_id": 2790684179467077, "shop_name": "朗朗桌球", "avatar": "https://oss.ficoo.vip/admin/hXcE4E…（用于门店信息快照，与其他 JSON 中的 siteProfile 结构一致）。          【JSON字段】payment_transactions.json - $ - siteProfile。';
@@ -1225,7 +1225,7 @@ COMMENT ON COLUMN billiards_ods.payment_transactions.create_time IS '【说明
 COMMENT ON COLUMN billiards_ods.payment_transactions.payment_method IS '【说明】支付方式枚举，例如微信、支付宝、现金、银行卡、储值卡等某一种。     【示例】4（用于支付方式枚举，例如微信、支付宝、现金、银行卡、储值卡等某一种）。          【JSON字段】payment_transactions.json - $ - payment_method。';
 COMMENT ON COLUMN billiards_ods.payment_transactions.online_pay_channel IS '【说明】每一笔结账单（settleList.id）对应一条支付记录（当前样本中是一条记录，relate_id 唯一）。     【示例】0（用于每一笔结账单（settleList.id）对应一条支付记录（当前样本中是一条记录，relate_id 唯一））。          【JSON字段】payment_transactions.json - $ - online_pay_channel。';
 COMMENT ON COLUMN billiards_ods.payment_transactions.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】payment_transactions.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】payment_transactions.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.payment_transactions.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/payment_transactions.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】payment_transactions.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.payment_transactions.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/payment_transactions.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】payment_transactions.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.payment_transactions.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】payment_transactions.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.payment_transactions.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】payment_transactions.json - $ - $。';
 
@@ -1269,7 +1269,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.refund_transactions (
     payload              JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.refund_transactions IS 'ODS 原始明细表：退款流水。来源：C:/dev/LLTQ/export/test-json-doc/refund_transactions.json；分析：refund_transactions-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.refund_transactions IS 'ODS 原始明细表：退款流水。来源：export/test-json-doc/refund_transactions.json；分析：refund_transactions-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.refund_transactions.id IS '【说明】本条 退款流水 的唯一 ID。     【示例】2955202296416389（用于本条 退款流水 的唯一 ID）。          【JSON字段】refund_transactions.json - $ - id。';
 COMMENT ON COLUMN billiards_ods.refund_transactions.tenant_id IS '【说明】租户/品牌 ID，全系统维度标识该商户。     【示例】2790683160709957（用于租户/品牌 ID，全系统维度标识该商户）。          【JSON字段】refund_transactions.json - $ - tenant_id。';
 COMMENT ON COLUMN billiards_ods.refund_transactions.tenantName IS '【说明】租户（商户）名称。     【示例】朗朗桌球（用于租户（商户）名称）。          【JSON字段】refund_transactions.json - $ - tenantName。';
@@ -1303,7 +1303,7 @@ COMMENT ON COLUMN billiards_ods.refund_transactions.is_delete IS '【说明】
 COMMENT ON COLUMN billiards_ods.refund_transactions.balance_frozen_amount IS '【说明】涉及会员储值卡退款时，暂时冻结的余额金额。     【示例】0.0（用于涉及会员储值卡退款时，暂时冻结的余额金额）。          【JSON字段】refund_transactions.json - $ - balance_frozen_amount。';
 COMMENT ON COLUMN billiards_ods.refund_transactions.card_frozen_amount IS '【说明】与上一个类似，偏向“某张卡的被冻结金额”，也与会员卡/储值账户相关。     【示例】0.0（用于与上一个类似，偏向“某张卡的被冻结金额”，也与会员卡/储值账户相关）。          【JSON字段】refund_transactions.json - $ - card_frozen_amount。';
 COMMENT ON COLUMN billiards_ods.refund_transactions.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】refund_transactions.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】refund_transactions.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.refund_transactions.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/refund_transactions.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】refund_transactions.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.refund_transactions.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/refund_transactions.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】refund_transactions.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.refund_transactions.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】refund_transactions.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.refund_transactions.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】refund_transactions.json - $ - $。';
 
@@ -1341,7 +1341,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.platform_coupon_redemption_records (
     payload           JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.platform_coupon_redemption_records IS 'ODS 原始明细表：平台券核销/使用记录。来源：C:/dev/LLTQ/export/test-json-doc/platform_coupon_redemption_records.json；分析：platform_coupon_redemption_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.platform_coupon_redemption_records IS 'ODS 原始明细表：平台券核销/使用记录。来源：export/test-json-doc/platform_coupon_redemption_records.json；分析：platform_coupon_redemption_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.id IS '【说明】本条平台验券记录在本系统内的主键 ID。     【示例】2957929042218501（用于本条平台验券记录在本系统内的主键 ID）。          【JSON字段】platform_coupon_redemption_records.json - $ - id。';
 COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.verify_id IS '【说明】平台核销记录 ID（某些平台会为每一次核销生成一个唯一 ID）。     【示例】7570689090418149418（用于平台核销记录 ID（某些平台会为每一次核销生成一个唯一 ID））。          【JSON字段】platform_coupon_redemption_records.json - $ - verify_id。';
 COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.certificate_id IS '【说明】平台侧的凭证 ID（通常由第三方团购平台生成的券实例 ID）。     【示例】5008024789379597447（用于平台侧的凭证 ID（通常由第三方团购平台生成的券实例 ID））。          【JSON字段】platform_coupon_redemption_records.json - $ - certificate_id。';
@@ -1369,7 +1369,7 @@ COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.operator_name
 COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.is_delete IS '【说明】把平台验券记录挂到本门店的一条订单上。     【示例】0（用于把平台验券记录挂到本门店的一条订单上）。          【JSON字段】platform_coupon_redemption_records.json - $ - is_delete。';
 COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.siteProfile IS '【说明】门店信息快照。     【示例】{"id": 2790685415443269, "org_id": 2790684179467077, "shop_name": "朗朗桌球", "avatar": "https://oss.ficoo.vip/admin/hXcE4E…（用于门店信息快照）。          【JSON字段】platform_coupon_redemption_records.json - $ - siteProfile。';
 COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】platform_coupon_redemption_records.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】platform_coupon_redemption_records.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/platform_coupon_redemption_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】platform_coupon_redemption_records.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/platform_coupon_redemption_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】platform_coupon_redemption_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】platform_coupon_redemption_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.platform_coupon_redemption_records.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】platform_coupon_redemption_records.json - $ - $。';
 
@@ -1412,7 +1412,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.tenant_goods_master (
     fetched_at              TIMESTAMPTZ DEFAULT now()
 );
 
-COMMENT ON TABLE billiards_ods.tenant_goods_master IS 'ODS 原始明细表：租户商品主数据。来源：C:/dev/LLTQ/export/test-json-doc/tenant_goods_master.json；分析：tenant_goods_master-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.tenant_goods_master IS 'ODS 原始明细表：租户商品主数据。来源：export/test-json-doc/tenant_goods_master.json；分析：tenant_goods_master-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.tenant_goods_master.id IS '【说明】商品档案主键 ID，唯一标识一条商品。     【示例】2791925230096261（用于商品档案主键 ID，唯一标识一条商品）。          【JSON字段】tenant_goods_master.json - data.tenantGoodsList - id。';
 COMMENT ON COLUMN billiards_ods.tenant_goods_master.tenant_id IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】tenant_goods_master.json - data.tenantGoodsList - tenant_id。';
 COMMENT ON COLUMN billiards_ods.tenant_goods_master.goods_name IS '【说明】商品名称（前台展示名称）。     【示例】东方树叶（用于商品名称（前台展示名称））。          【JSON字段】tenant_goods_master.json - data.tenantGoodsList - goods_name。';
@@ -1446,7 +1446,7 @@ COMMENT ON COLUMN billiards_ods.tenant_goods_master.create_time IS '【说明】
 COMMENT ON COLUMN billiards_ods.tenant_goods_master.update_time IS '【说明】商品档案最近一次修改时间。     【示例】2025-10-29 23:51:38（用于商品档案最近一次修改时间）。          【JSON字段】tenant_goods_master.json - data.tenantGoodsList - update_time。';
 COMMENT ON COLUMN billiards_ods.tenant_goods_master.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】tenant_goods_master.json - data.tenantGoodsList - $。';
 COMMENT ON COLUMN billiards_ods.tenant_goods_master.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】tenant_goods_master.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】tenant_goods_master.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.tenant_goods_master.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/tenant_goods_master.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】tenant_goods_master.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.tenant_goods_master.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/tenant_goods_master.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】tenant_goods_master.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.tenant_goods_master.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】tenant_goods_master.json - ETL元数据 - 无。';
 
 
@@ -1492,7 +1492,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.group_buy_packages (
     payload                     JSONB NOT NULL
 );
 
-COMMENT ON TABLE billiards_ods.group_buy_packages IS 'ODS 原始明细表：团购套餐主数据。来源：C:/dev/LLTQ/export/test-json-doc/group_buy_packages.json；分析：group_buy_packages-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.group_buy_packages IS 'ODS 原始明细表：团购套餐主数据。来源：export/test-json-doc/group_buy_packages.json；分析：group_buy_packages-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.group_buy_packages.id IS '【说明】门店侧套餐 ID，本文件内部的主键。     【示例】2939215004469573（用于门店侧套餐 ID，本文件内部的主键）。          【JSON字段】group_buy_packages.json - data.packageCouponList - id。';
 COMMENT ON COLUMN billiards_ods.group_buy_packages.package_id IS '【说明】“上层套餐 ID” 或“总部/系统级套餐 ID”。     【示例】1814707240811572（用于“上层套餐 ID” 或“总部/系统级套餐 ID”）。          【JSON字段】group_buy_packages.json - data.packageCouponList - package_id。';
 COMMENT ON COLUMN billiards_ods.group_buy_packages.package_name IS '【说明】团购套餐名称，用于前台展示和核销界面。     【示例】早场特惠一小时（团购套餐名称，用于前台展示和核销界面）。          【JSON字段】group_buy_packages.json - data.packageCouponList - package_name。';
@@ -1529,7 +1529,7 @@ COMMENT ON COLUMN billiards_ods.group_buy_packages.area_tag_type IS '【说明
 COMMENT ON COLUMN billiards_ods.group_buy_packages.creator_name IS '【说明】创建人信息，一般包含“角色：姓名”。     【示例】店长:郑丽珊（用于创建人信息，一般包含“角色：姓名”）。          【JSON字段】group_buy_packages.json - data.packageCouponList - creator_name。';
 COMMENT ON COLUMN billiards_ods.group_buy_packages.create_time IS '【说明】该套餐在系统中创建的时间。     【示例】2025-10-27 18:24:09（用于该套餐在系统中创建的时间）。          【JSON字段】group_buy_packages.json - data.packageCouponList - create_time。';
 COMMENT ON COLUMN billiards_ods.group_buy_packages.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】group_buy_packages.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】group_buy_packages.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.group_buy_packages.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/group_buy_packages.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】group_buy_packages.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.group_buy_packages.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/group_buy_packages.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】group_buy_packages.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.group_buy_packages.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】group_buy_packages.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.group_buy_packages.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】group_buy_packages.json - data.packageCouponList - $。';
 
@@ -1584,7 +1584,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.group_buy_redemption_records (
     fetched_at                      TIMESTAMPTZ DEFAULT now()
 );
 
-COMMENT ON TABLE billiards_ods.group_buy_redemption_records IS 'ODS 原始明细表：团购核销记录。来源：C:/dev/LLTQ/export/test-json-doc/group_buy_redemption_records.json；分析：group_buy_redemption_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.group_buy_redemption_records IS 'ODS 原始明细表：团购核销记录。来源：export/test-json-doc/group_buy_redemption_records.json；分析：group_buy_redemption_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.id IS '【说明】本条“团购套餐流水”记录的 主键 ID。     【示例】2957924029615941（用于本条“团购套餐流水”记录的 主键 ID）。          【JSON字段】group_buy_redemption_records.json - data.siteTableUseDetailsList - id。';
 COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.tenant_id IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】group_buy_redemption_records.json - data.siteTableUseDetailsList - tenant_id。';
 COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.site_id IS '【说明】门店 ID，与其它 JSON 中一致。     【示例】2790685415443269（用于门店 ID，与其它 JSON 中一致）。          【JSON字段】group_buy_redemption_records.json - data.siteTableUseDetailsList - site_id。';
@@ -1630,7 +1630,7 @@ COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.is_delete IS '【
 COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.create_time IS '【说明】本条团购套餐使用流水创建时间（即券核销时间，或与结账时间接近）。     【示例】2025-11-09 23:35:57（用于本条团购套餐使用流水创建时间（即券核销时间，或与结账时间接近））。          【JSON字段】group_buy_redemption_records.json - data.siteTableUseDetailsList - create_time。';
 COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】group_buy_redemption_records.json - data.siteTableUseDetailsList - $。';
 COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】group_buy_redemption_records.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】group_buy_redemption_records.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/group_buy_redemption_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】group_buy_redemption_records.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/group_buy_redemption_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】group_buy_redemption_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.group_buy_redemption_records.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】group_buy_redemption_records.json - ETL元数据 - 无。';
 
 
@@ -1679,7 +1679,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.settlement_ticket_details (
     fetched_at            TIMESTAMPTZ DEFAULT now()
 );
 
-COMMENT ON TABLE billiards_ods.settlement_ticket_details IS 'ODS 原始明细表：结算小票明细。来源：C:/dev/LLTQ/export/test-json-doc/settlement_ticket_details.json；分析：settlement_ticket_details-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.settlement_ticket_details IS 'ODS 原始明细表：结算小票明细。来源：export/test-json-doc/settlement_ticket_details.json；分析：settlement_ticket_details-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.settlement_ticket_details.orderSettleId IS '【说明】结算单 ID（和顶层字段相同，再次冗余）。     【示例】2957922914357125（用于结算单 ID（和顶层字段相同，再次冗余））。          【JSON字段】settlement_ticket_details.json - $ - orderSettleId。';
 COMMENT ON COLUMN billiards_ods.settlement_ticket_details.actualPayment IS '【说明】本单实际支付金额总和（顾客本次实际付出：现金 + 线上 + 会员余额等）。     【示例】NULL（用于本单实际支付金额总和（顾客本次实际付出：现金 + 线上 + 会员余额等））。          【JSON字段】settlement_ticket_details.json - $ - actualPayment。';
 COMMENT ON COLUMN billiards_ods.settlement_ticket_details.adjustAmount IS '【说明】人工调价/整单调整金额（例如手工改价、折扣调整），是所有类型的手工调整合计。     【示例】NULL（用于人工调价/整单调整金额（例如手工改价、折扣调整），是所有类型的手工调整合计）。          【JSON字段】settlement_ticket_details.json - $ - adjustAmount。';
@@ -1720,7 +1720,7 @@ COMMENT ON COLUMN billiards_ods.settlement_ticket_details.orderItem IS '【说
 COMMENT ON COLUMN billiards_ods.settlement_ticket_details.tenantMemberCardLogs IS '【说明】来自 JSON 导出的原始字段，用于保留业务取值。     【示例】NULL（来自 JSON 导出的原始字段，用于保留业务取值）。          【JSON字段】settlement_ticket_details.json - $ - tenantMemberCardLogs。';
 COMMENT ON COLUMN billiards_ods.settlement_ticket_details.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】settlement_ticket_details.json - $ - $。';
 COMMENT ON COLUMN billiards_ods.settlement_ticket_details.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】settlement_ticket_details.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】settlement_ticket_details.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.settlement_ticket_details.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/settlement_ticket_details.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】settlement_ticket_details.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.settlement_ticket_details.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/settlement_ticket_details.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】settlement_ticket_details.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.settlement_ticket_details.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】settlement_ticket_details.json - ETL元数据 - 无。';
 
 
@@ -1776,7 +1776,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.store_goods_master (
     fetched_at          TIMESTAMPTZ DEFAULT now()
 );
 
-COMMENT ON TABLE billiards_ods.store_goods_master IS 'ODS 原始明细表：门店商品主数据。来源：C:/dev/LLTQ/export/test-json-doc/store_goods_master.json；分析：store_goods_master-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.store_goods_master IS 'ODS 原始明细表：门店商品主数据。来源：export/test-json-doc/store_goods_master.json；分析：store_goods_master-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.store_goods_master.id IS '【说明】门店商品 ID，门店维度的商品主键。     【示例】2793025851560005（用于门店商品 ID，门店维度的商品主键）。          【JSON字段】store_goods_master.json - data.orderGoodsList - id。';
 COMMENT ON COLUMN billiards_ods.store_goods_master.tenant_id IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】store_goods_master.json - data.orderGoodsList - tenant_id。';
 COMMENT ON COLUMN billiards_ods.store_goods_master.site_id IS '【说明】门店 ID。     【示例】2790685415443269（用于门店 ID）。          【JSON字段】store_goods_master.json - data.orderGoodsList - site_id。';
@@ -1823,7 +1823,7 @@ COMMENT ON COLUMN billiards_ods.store_goods_master.create_time IS '【说明】
 COMMENT ON COLUMN billiards_ods.store_goods_master.update_time IS '【说明】最后一次修改该商品档案的时间（包括价格调整、状态变更等）。     【示例】2025-11-09 07:23:47（用于最后一次修改该商品档案的时间（包括价格调整、状态变更等））。          【JSON字段】store_goods_master.json - data.orderGoodsList - update_time。';
 COMMENT ON COLUMN billiards_ods.store_goods_master.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】store_goods_master.json - data.orderGoodsList - $。';
 COMMENT ON COLUMN billiards_ods.store_goods_master.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】store_goods_master.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】store_goods_master.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.store_goods_master.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/store_goods_master.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】store_goods_master.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.store_goods_master.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/store_goods_master.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】store_goods_master.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.store_goods_master.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】store_goods_master.json - ETL元数据 - 无。';
 
 
@@ -1885,7 +1885,7 @@ CREATE TABLE IF NOT EXISTS billiards_ods.store_goods_sales_records (
     fetched_at                 TIMESTAMPTZ DEFAULT now()
 );
 
-COMMENT ON TABLE billiards_ods.store_goods_sales_records IS 'ODS 原始明细表：门店商品销售流水。来源：C:/dev/LLTQ/export/test-json-doc/store_goods_sales_records.json；分析：store_goods_sales_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
+COMMENT ON TABLE billiards_ods.store_goods_sales_records IS 'ODS 原始明细表：门店商品销售流水。来源：export/test-json-doc/store_goods_sales_records.json；分析：store_goods_sales_records-Analysis.md。字段以导出原样为主；ETL 补充 source_file/source_endpoint/fetched_at，并保留 payload 为原始记录快照。';
 COMMENT ON COLUMN billiards_ods.store_goods_sales_records.id IS '【说明】本条「门店销售流水」记录的主键 ID。     【示例】2957924029550406（用于本条「门店销售流水」记录的主键 ID）。          【JSON字段】store_goods_sales_records.json - data.orderGoodsLedgers - id。';
 COMMENT ON COLUMN billiards_ods.store_goods_sales_records.tenant_id IS '【说明】租户/品牌 ID。     【示例】2790683160709957（用于租户/品牌 ID）。          【JSON字段】store_goods_sales_records.json - data.orderGoodsLedgers - tenant_id。';
 COMMENT ON COLUMN billiards_ods.store_goods_sales_records.site_id IS '【说明】门店 ID（系统主键）。     【示例】2790685415443269（用于门店 ID（系统主键））。          【JSON字段】store_goods_sales_records.json - data.orderGoodsLedgers - site_id。';
@@ -1939,7 +1939,7 @@ COMMENT ON COLUMN billiards_ods.store_goods_sales_records.tenant_goods_category_
 COMMENT ON COLUMN billiards_ods.store_goods_sales_records.create_time IS '【说明】销售记录创建时间，通常就是结账时间或录入时间。     【示例】2025-11-09 23:35:57（用于销售记录创建时间，通常就是结账时间或录入时间）。          【JSON字段】store_goods_sales_records.json - data.orderGoodsLedgers - create_time。';
 COMMENT ON COLUMN billiards_ods.store_goods_sales_records.payload IS '【说明】完整原始 JSON 记录快照，用于回溯与二次解析。     【示例】{...}（完整原始 JSON 记录快照，用于回溯与二次解析）。          【JSON字段】store_goods_sales_records.json - data.orderGoodsLedgers - $。';
 COMMENT ON COLUMN billiards_ods.store_goods_sales_records.source_file IS '【说明】ETL 元数据：原始导出文件名，用于数据追溯。     【示例】store_goods_sales_records.json（ETL 元数据：原始导出文件名，用于数据追溯）。          【JSON字段】store_goods_sales_records.json - ETL元数据 - 无。';
-COMMENT ON COLUMN billiards_ods.store_goods_sales_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】C:/dev/LLTQ/export/test-json-doc/store_goods_sales_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】store_goods_sales_records.json - ETL元数据 - 无。';
+COMMENT ON COLUMN billiards_ods.store_goods_sales_records.source_endpoint IS '【说明】ETL 元数据：采集来源（接口/文件路径），用于数据追溯。     【示例】export/test-json-doc/store_goods_sales_records.json（ETL 元数据：采集来源（接口/文件路径），用于数据追溯）。          【JSON字段】store_goods_sales_records.json - ETL元数据 - 无。';
 COMMENT ON COLUMN billiards_ods.store_goods_sales_records.fetched_at IS '【说明】ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理。     【示例】2025-11-10T00:00:00+08:00（ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理）。          【JSON字段】store_goods_sales_records.json - ETL元数据 - 无。';
 
 

etl_billiards/database/schema_dwd_doc.sql

@@ -1324,7 +1324,8 @@ CREATE TABLE IF NOT EXISTS dwd_store_goods_sale_Ex (
     push_money NUMERIC(18,2),
     is_single_order INTEGER,
     sales_type INTEGER,
-    operator_id BIGINT
+    operator_id BIGINT,
+    PRIMARY KEY (store_goods_sale_id)
 );
 
 COMMENT ON TABLE billiards_dwd.dwd_store_goods_sale_ex IS 'DWD 明细事实表（扩展字段表）：dwd_store_goods_sale_ex。ODS 来源表：billiards_ods.store_goods_sales_records（对应 JSON：store_goods_sales_records.json；分析：store_goods_sales_records-Analysis.md）。装载/清洗逻辑参考：etl_billiards/tasks/dwd_load_task.py（DwdLoadTask）。';

etl_billiards/database/seed_scheduler_tasks.sql

@@ -17,6 +17,7 @@ task_codes AS (
         'ASSISTANTS',
         'COUPON_USAGE',
         'CHECK_CUTOFF',
+        'DATA_INTEGRITY_CHECK',
         'DWD_LOAD_FROM_ODS',
         'DWD_QUALITY_CHECK',
         'INIT_DWD_SCHEMA',