在准备环境前提交次全部更改。

apps/etl/connectors/feiqiu/docs/database/ODS/changes/2026-02-13_ddl_sync_ods.md

@@ -0,0 +1,96 @@
+# ODS 层 DDL 同步修正 — 变更记录
+
+> 结构性变更：修正 4 项差异（删除 2 个冗余字段、修正 1 个字段类型、补充 1 个缺失字段）
+
+## 溯源
+
+- 日期：2026-02-13（Asia/Shanghai）
+- 工具：`scripts/compare_ddl_db.py --schema ods --ddl-path database/schema_ODS_doc.sql`
+- Direct cause：DDL 对比脚本发现 `database/schema_ODS_doc.sql` 与数据库 `ods` schema 实际状态存在 4 项差异，以数据库为准修正 DDL 文件。
+
+## 变更内容
+
+| Schema | 表名 | 操作 | 字段 | DDL 原定义 | 数据库实际 | 说明 |
+|--------|------|------|------|-----------|-----------|------|
+| `ods` | `recharge_settlements` | DDL 删除字段 | `settlelist` | `jsonb` | — | DDL 中有但数据库中不存在，属冗余定义 |
+| `ods` | `settlement_records` | DDL 删除字段 | `settlelist` | `jsonb` | — | DDL 中有但数据库中不存在，属冗余定义 |
+| `ods` | `tenant_goods_master` | DDL 修正类型 | `not_sale` | `BOOLEAN` | `INTEGER` | 字段类型不匹配，以数据库为准 |
+| `ods` | `refund_transactions` | DDL 补充字段 | `check_status` | — | `INTEGER` | 数据库中有但 DDL 中未定义 |
+
+## 变更原因
+
+1. `recharge_settlements.settlelist` 和 `settlement_records.settlelist`：DDL 文件中残留的字段定义，数据库中已在先前迁移（`20260214_drop_ods_settlelist.sql`）中删除，DDL 未同步清理
+2. `tenant_goods_master.not_sale`：DDL 定义为 `BOOLEAN`，但数据库实际为 `INTEGER`（0/1 表示是否停售），以数据库为准修正
+3. `refund_transactions.check_status`：数据库中存在的审核状态字段，DDL 文件中遗漏未定义
+
+## 影响范围
+
+| 影响对象 | 影响程度 | 说明 |
+|----------|----------|------|
+| ETL 加载任务 | 无影响 | 本次仅修正 DDL 文档，不涉及数据库结构变更 |
+| 后端 API | 无影响 | DDL 文件为文档性质，不影响运行时 |
+| 小程序字段映射 | 无影响 | 小程序不直接读 ODS 层 |
+| ODS 表级文档 | ⚠️ 需同步 | 后续生成 ODS 表级文档时应以修正后的 DDL 为准 |
+| DWD 加载映射 | 无影响 | `refund_transactions.check_status` 已在 DWD 层有对应映射 |
+
+**注意**：本次变更仅修正 DDL 文件（文档同步），数据库结构未发生任何变更。数据库是"源头"，DDL 文件是"文档"。
+
+## 回滚策略
+
+本次为 DDL 文件修正（文档同步），无需数据库回滚。若需恢复 DDL 文件，使用 Git 回退即可：
+
+```bash
+git checkout HEAD~1 -- database/schema_ODS_doc.sql
+```
+
+若未来需要将数据库结构回退到 DDL 修正前的状态（不推荐）：
+
+```sql
+-- 1) 恢复 settlelist 列（数据不可恢复）
+ALTER TABLE ods.recharge_settlements ADD COLUMN settlelist JSONB;
+ALTER TABLE ods.settlement_records ADD COLUMN settlelist JSONB;
+
+-- 2) 将 not_sale 改回 BOOLEAN（需数据转换）
+ALTER TABLE ods.tenant_goods_master
+  ALTER COLUMN not_sale TYPE BOOLEAN USING (not_sale::INTEGER != 0);
+
+-- 3) 删除 check_status 列
+ALTER TABLE ods.refund_transactions DROP COLUMN check_status;
+```
+
+## 验证 SQL
+
+```sql
+-- 1) 确认 settlelist 列在数据库中确实不存在
+SELECT column_name
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+  AND table_name IN ('recharge_settlements', 'settlement_records')
+  AND column_name = 'settlelist';
+-- 预期：0 行
+
+-- 2) 确认 tenant_goods_master.not_sale 实际类型为 integer
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+  AND table_name = 'tenant_goods_master'
+  AND column_name = 'not_sale';
+-- 预期：data_type = 'integer'
+
+-- 3) 确认 refund_transactions.check_status 存在且类型为 integer
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+  AND table_name = 'refund_transactions'
+  AND column_name = 'check_status';
+-- 预期：1 行，data_type = 'integer'
+
+-- 4) 确认修正后 DDL 与数据库零差异（通过对比脚本验证）
+-- python scripts/compare_ddl_db.py --schema ods --ddl-path database/schema_ODS_doc.sql
+-- 预期：0 项差异
+```
+
+## 关联文件
+
+- DDL 文件：`database/schema_ODS_doc.sql`
+- 对比结果：`docs/database/ddl_compare_results.md`

apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260213_align_ods_with_api.md

@@ -0,0 +1,39 @@
+# ODS 表与 API JSON 字段对齐 — 变更记录
+
+> 无结构性变更
+
+## 溯源
+
+- 日期：2026-02-13（Asia/Shanghai）
+- Prompt：P20260213-210000 — 用新梳理的 API 返回 JSON 文档比对数据库 ODS 层
+- Direct cause：`scripts/compare_api_ods.py` 自动比对 22 张 ODS 表与 `docs/api-reference/` 文档中的 JSON 字段，结论为全部对齐，无需 ALTER
+
+## 说明
+
+迁移文件 `database/migrations/20260213_align_ods_with_api.sql` 为比对结论记录，不包含任何 DDL 语句。
+
+- 比对范围：`ods` schema 下 22 张表
+- 比对逻辑：camelCase → snake_case 归一化匹配 + 去下划线纯小写兜底
+- 结论：所有 ODS 表列已与 API JSON 响应字段完全对齐
+- `stock_goods_category_tree` 的 `goodsCategoryList`/`total` 为响应包装层字段，ODS 表已正确展开存储数组内的记录级字段，无需额外列
+
+## 验证 SQL
+
+```sql
+-- 1) 确认 ods schema 下表数量
+SELECT count(*) FROM information_schema.tables
+WHERE table_schema = 'ods' AND table_type = 'BASE TABLE';
+
+-- 2) 确认迁移文件未引入新列（对比前后列数应一致）
+SELECT table_name, count(*) AS col_count
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+GROUP BY table_name
+ORDER BY table_name;
+
+-- 3) 确认无待执行的 pending migration（迁移文件为纯注释，不应产生任何变更）
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_schema = 'ods' AND table_name = 'assistant_accounts_master'
+ORDER BY ordinal_position;
+```

apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260214_drop_ods_option_name_able_site_transfer.md

@@ -0,0 +1,111 @@
+# ODS 层删除 option_name / able_site_transfer 冗余列 — 变更记录
+
+> 结构性变更：删除 2 张表各 1 个冗余列（API JSON 中不存在，ODS 全 NULL）
+
+## 溯源
+
+- 日期：2026-02-14（Asia/Shanghai）
+- Prompt：P20260214-070000 — 删除 ODS 层 store_goods_sales_records.option_name 和 member_stored_value_cards.able_site_transfer
+- Direct cause：API vs ODS 比对报告（v3-fixed）中这两列被标注为"ODS 独有"，经查证 API JSON 响应中从未返回这两个字段，ODS 中全部为 NULL（0 条非空数据），属于冗余列，应清理。
+
+## 变更内容
+
+| Schema | 表名 | 操作 | 列名 | 原类型 | 说明 |
+|--------|------|------|------|--------|------|
+| `ods` | `store_goods_sales_records` | DROP COLUMN | `option_name` | `text` | API 后续版本新增字段，实际从未返回数据，全 NULL |
+| `ods` | `member_stored_value_cards` | DROP COLUMN | `able_site_transfer` | `integer` | API 后续版本新增字段，实际从未返回数据，全 NULL |
+
+### Before / After
+
+**store_goods_sales_records**：
+- Before：52 个业务列 + 5 个 meta 列（含 `option_name text`）
+- After：51 个业务列 + 5 个 meta 列（`option_name` 已移除）
+
+**member_stored_value_cards**：
+- Before：76 个业务列 + 5 个 meta 列（含 `able_site_transfer integer`）
+- After：75 个业务列 + 5 个 meta 列（`able_site_transfer` 已移除）
+
+## 变更原因
+
+1. v3-fixed 比对报告显示 `option_name` 和 `able_site_transfer` 为"ODS 独有"字段
+2. 全量 JSON 刷新审计（100 条/接口）确认 API 响应中从未包含这两个字段
+3. 数据库查询确认两列全部为 NULL，无实际业务数据
+4. 保留全 NULL 的冗余列会误导后续开发和数据分析
+
+## 影响范围
+
+| 影响对象 | 影响程度 | 说明 |
+|----------|----------|------|
+| ODS 抓取任务 | ⚠️ 需确认 | ODS 入库 INSERT/UPSERT 语句中若包含这两列需移除 |
+| DWD 加载任务 | 无影响 | DWD 层未映射这两个字段（全 NULL 无法产生有意义的 DWD 数据） |
+| API 契约 | 无影响 | API 响应结构不变，这两个字段本就不在 API 返回中 |
+| 小程序 | 无影响 | 小程序不直接读 ODS 层 |
+| 比对报告 | 需更新 | `docs/reports/api_ods_comparison_v3_fixed.md` 中两表的 ODS 独有字段需移除 |
+
+## 回滚策略
+
+```sql
+-- 恢复列结构（数据不可恢复，因原始数据全为 NULL）
+ALTER TABLE ods.store_goods_sales_records ADD COLUMN option_name TEXT;
+ALTER TABLE ods.member_stored_value_cards ADD COLUMN able_site_transfer INTEGER;
+```
+
+**注意事项**：
+- 回滚后两列数据均为 NULL（与删除前一致），无数据丢失风险
+- 若未来 API 版本开始返回这两个字段，需重新 ADD COLUMN 并更新 ODS 入库逻辑
+
+## 验证 SQL
+
+```sql
+-- 1) 确认 option_name 列已不存在
+SELECT column_name
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+  AND table_name = 'store_goods_sales_records'
+  AND column_name = 'option_name';
+-- 预期：0 行
+
+-- 2) 确认 able_site_transfer 列已不存在
+SELECT column_name
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+  AND table_name = 'member_stored_value_cards'
+  AND column_name = 'able_site_transfer';
+-- 预期：0 行
+
+-- 3) 确认两表当前列数
+SELECT table_name, count(*) AS total_columns
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+  AND table_name IN ('store_goods_sales_records', 'member_stored_value_cards')
+GROUP BY table_name;
+-- 预期：store_goods_sales_records = 56（51 业务 + 5 meta），member_stored_value_cards = 80（75 业务 + 5 meta）
+
+-- 4) 确认删除前数据确实全 NULL（回溯验证，迁移执行前运行）
+-- SELECT count(*) FROM ods.store_goods_sales_records WHERE option_name IS NOT NULL;
+-- SELECT count(*) FROM ods.member_stored_value_cards WHERE able_site_transfer IS NOT NULL;
+-- 预期：均为 0
+```
+
+## 迁移文件
+
+`database/migrations/20260214_drop_ods_option_name_able_site_transfer.sql`
+
+
+---
+
+## 补充记录：schema_ODS_doc.sql AI_CHANGELOG 标注
+
+- 日期：2026-02-14（Asia/Shanghai）
+- Prompt：P20260214-070000（同上）
+- 变更内容：在 `database/schema_ODS_doc.sql` 末尾追加 AI_CHANGELOG 注释块，记录 option_name / able_site_transfer 两列在 DDL 文档中的注释化处理
+- 结论：**无结构性变更**（仅追加 SQL 注释，不涉及 DDL 操作）
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-14
+- Prompt: P20260214-070000 — ODS 清理与文档标注（5 项任务）
+- 直接原因: DB schema 变更（删除 2 列）必须同步 BD Manual
+- 变更摘要: 新建 ODS 层变更记录文档，记录 option_name 和 able_site_transfer 的删除原因、影响、回滚策略和验证 SQL
+- 风险与验证: 纯文档；验证：验证 SQL 执行结果与预期一致
+-->

apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260214_drop_ods_settlelist.md

@@ -0,0 +1,102 @@
+# ODS 层删除 settlelist 冗余列 — 变更记录
+
+> 结构性变更：删除 2 张表的 1 个 jsonb 列
+
+## 溯源
+
+- 日期：2026-02-14（Asia/Shanghai）
+- Prompt：P20260214-023000 — 删除 ODS 层 settlement_records / recharge_settlements 的 settlelist jsonb 列
+- Direct cause：`settlelist` 列与 `payload` 列数据完全重复（`payload` 存储完整 API 响应 JSON，已包含 `settleList` 对象），属于冗余存储。DWD 加载逻辑已改为从 `payload` 提取 `settleList`，该列不再被任何下游消费。
+
+## 变更内容
+
+| Schema | 表名 | 操作 | 列名 | 原类型 | 说明 |
+|--------|------|------|------|--------|------|
+| `ods` | `settlement_records` | DROP COLUMN | `settlelist` | `jsonb` | 存储原始 settleList 对象，与 payload 重复 |
+| `ods` | `recharge_settlements` | DROP COLUMN | `settlelist` | `jsonb` | 存储原始 settleList 对象，与 payload 重复 |
+
+### Before / After
+
+**settlement_records**：
+- Before：67 个业务列 + 5 个 meta 列（含 `settlelist jsonb`）
+- After：66 个业务列 + 5 个 meta 列（`settlelist` 已移除）
+
+**recharge_settlements**：
+- Before：67 个业务列 + 5 个 meta 列（含 `settlelist jsonb`）
+- After：66 个业务列 + 5 个 meta 列（`settlelist` 已移除）
+
+## 变更原因
+
+1. `payload` 列（jsonb）已存储完整的 API 响应 JSON，其中包含 `settleList` 对象
+2. `settlelist` 列是 ETL 入库时从 `payload` 中额外提取并单独存储的副本，属于冗余
+3. API vs ODS 比对报告（v3-fixed）中已标注 `settlelist` 为"ODS jsonb 列（存储原始 settleList 对象）"
+4. DWD 加载逻辑已修改为直接从 `payload->'settleList'` 提取数据
+
+## 影响范围
+
+| 影响对象 | 影响程度 | 说明 |
+|----------|----------|------|
+| DWD 加载任务 | ⚠️ 需确认 | DWD 加载必须已改为从 `payload` 提取 settleList，不再读 `settlelist` 列 |
+| ODS 抓取任务 | ⚠️ 需确认 | ODS 入库逻辑需移除对 `settlelist` 列的写入（INSERT/UPSERT 语句） |
+| API 契约 | 无影响 | API 响应结构不变，仅 ODS 存储方式调整 |
+| 小程序 | 无影响 | 小程序不直接读 ODS 层 |
+| 比对报告 | 需更新 | `docs/reports/api_ods_comparison_v3.md` 和 `scripts/ods_columns.json` 中 settlement_records / recharge_settlements 的列清单需移除 `settlelist` |
+| 比对脚本 | 需更新 | `scripts/run_compare_v3_fixed.py` 中 `classify_ods_only()` 对 `settlelist` 的特殊处理可移除 |
+
+## 回滚策略
+
+```sql
+-- 1) 恢复列结构
+ALTER TABLE ods.settlement_records ADD COLUMN settlelist jsonb;
+ALTER TABLE ods.recharge_settlements ADD COLUMN settlelist jsonb;
+
+-- 2) 从 payload 回填数据（回滚后列为 NULL，需重新提取）
+UPDATE ods.settlement_records
+SET settlelist = payload->'settleList'
+WHERE payload IS NOT NULL;
+
+UPDATE ods.recharge_settlements
+SET settlelist = payload->'settleList'
+WHERE payload IS NOT NULL;
+```
+
+**注意事项**：
+- 回滚后 `settlelist` 列数据为 NULL，必须执行回填 UPDATE
+- 若历史数据中存在 `payload IS NULL` 的行，这些行的 `settlelist` 将永久丢失（无法恢复）
+- 回填前建议先统计 `payload IS NULL` 的行数，评估数据损失范围
+
+## 验证 SQL
+
+```sql
+-- 1) 确认 settlelist 列已不存在
+SELECT column_name
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+  AND table_name IN ('settlement_records', 'recharge_settlements')
+  AND column_name = 'settlelist';
+-- 预期：0 行
+
+-- 2) 确认 payload 列仍存在且包含 settleList 数据
+SELECT count(*)
+FROM ods.settlement_records
+WHERE payload IS NOT NULL AND payload->'settleList' IS NOT NULL;
+-- 预期：> 0（确认 payload 中有 settleList 数据可用）
+
+-- 3) 确认两表当前列数（排除 meta 列后应为 66）
+SELECT table_name, count(*) AS total_columns
+FROM information_schema.columns
+WHERE table_schema = 'ods'
+  AND table_name IN ('settlement_records', 'recharge_settlements')
+GROUP BY table_name;
+-- 预期：settlement_records = 71（66 业务 + 5 meta），recharge_settlements = 71
+
+-- 4) 确认 DWD 加载可从 payload 正常提取 settleList
+SELECT id, (payload->'settleList') IS NOT NULL AS has_settle_list
+FROM ods.settlement_records
+LIMIT 5;
+-- 预期：has_settle_list = true（至少对 payload 非空的行）
+```
+
+## 迁移文件
+
+`database/migrations/20260214_drop_ods_settlelist.sql`

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_assistant_accounts_master.md

@@ -0,0 +1,118 @@
+# assistant_accounts_master 助教账户主表
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | assistant_accounts_master |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/assistant_accounts_master.json |
+| 说明 | 助教档案主数据 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 助教账号主键 ID，在“助教流水.json”中对应 site_assistant_id |
+| 2 | tenant_id | BIGINT | YES | 品牌/租户 ID，对应“非球科技”系统中该商户的唯一标识 |
+| 3 | site_id | BIGINT | YES | 门店 ID，对应本次数据的这家球房（朗朗桌球） |
+| 4 | assistant_no | TEXT | YES | 助教工号 / 编号，便于业务侧识别 |
+| 5 | nickname | TEXT | YES | 助教在前台展示的昵称，如“佳怡”“周周”“球球”等 |
+| 6 | real_name | TEXT | YES | 助教真实姓名，如“何海婷”“梁婷婷”等 |
+| 7 | mobile | TEXT | YES | 助教手机号，用于登录绑定、通知、钉钉同步等 |
+| 8 | team_id | BIGINT | YES | 助教所属团队 ID |
+| 9 | team_name | TEXT | YES | 团队名称，展示用，和 team_id 一一对应 |
+| 10 | user_id | BIGINT | YES | 系统级“用户账号 ID”，通常对应登录账号 |
+| 11 | level | TEXT | YES | 10 × 24 |
+| 12 | assistant_status | INTEGER | YES | 1 × 48 |
+| 13 | work_status | INTEGER | YES | 当 leave_status = 0 时，work_status = 1 |
+| 14 | leave_status | INTEGER | YES | 0 × 21 |
+| 15 | entry_time | TIMESTAMP | YES | 入职时间 |
+| 16 | resign_time | TIMESTAMP | YES | 离职日期 |
+| 17 | start_time | TIMESTAMP | YES | 当前配置生效的开始日期 |
+| 18 | end_time | TIMESTAMP | YES | 当前配置生效的结束日期（例如一个周期性的排班/合同周期） |
+| 19 | create_time | TIMESTAMP | YES | 账号创建时间 |
+| 20 | update_time | TIMESTAMP | YES | 账号最近一次被修改的时间（例如修改等级、昵称等） |
+| 21 | order_trade_no | TEXT | YES | 该助教最近一次关联的订单号，用于快速跳转或回溯最近服务行为 |
+| 22 | staff_id | BIGINT | YES | 预留给“人事系统员工 ID”的字段，目前未接入或未启用 |
+| 23 | staff_profile_id | BIGINT | YES | 人事档案 ID，与第三方 HR 系统或内部员工档案集成使用，当前未启用 |
+| 24 | system_role_id | BIGINT | YES | 标识类 ID 字段，用于关联/定位相关实体 |
+| 25 | avatar | TEXT | YES | 助教头像地址 |
+| 26 | birth_date | TIMESTAMP | YES | 助教出生日期 |
+| 27 | gender | INTEGER | YES | 0 × 40 |
+| 28 | height | NUMERIC(18,2) | YES | 身高（单位：厘米） |
+| 29 | weight | NUMERIC(18,2) | YES | 体重（单位：公斤） |
+| 30 | job_num | TEXT | YES | 备用工号字段，目前未在该门店启用 |
+| 31 | show_status | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 32 | show_sort | INTEGER | YES | 前台展示排序权重，值越小/越大对应不同的排序策略（当前看起来与 assistant_no 有一定对应关系） |
+| 33 | sum_grade | NUMERIC(18,2) | YES | 评分总和，用于计算平均分（assistant_grade = sum_grade / get_grade_times），当前为 0 |
+| 34 | assistant_grade | NUMERIC(18,2) | YES | 助教综合评分（员工维度的平均分 snapshot），当前尚未启用评分 |
+| 35 | get_grade_times | INTEGER | YES | 累计被评分次数 |
+| 36 | introduce | TEXT | YES | 个人简介文案，预留给助教自我介绍使用 |
+| 37 | video_introduction_url | TEXT | YES | 助教个人视频介绍地址 |
+| 38 | group_id | BIGINT | YES | 上层“分组 ID”预留字段（例如集团/事业部），本门店未使用 |
+| 39 | group_name | TEXT | YES | group_id 对应的名称，目前为空 |
+| 40 | shop_name | TEXT | YES | 门店名称，冗余字段，用于展示 |
+| 41 | charge_way | INTEGER | YES | 2 代表当前门店为“计时收费”，其他值（1、3 等）可能对应按局、按课时等，当前未出现 |
+| 42 | entry_type | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 43 | allow_cx | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 44 | is_guaranteed | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 45 | salary_grant_enabled | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 46 | light_status | INTEGER | YES | 灯光控制状态，如 1=启用控制、2=不启用 或相反 |
+| 47 | online_status | INTEGER | YES | 在线状态 |
+| 48 | is_delete | INTEGER | YES | 逻辑删除标记（0=否，1=是） |
+| 49 | cx_unit_price | NUMERIC(18,2) | YES | 促销时段的单价，本门店未在账号表层面设置 |
+| 50 | pd_unit_price | NUMERIC(18,2) | YES | 某种标准单价（例如“普通时段单价”），这里未在账号上配置（实际单价在助教商品或套餐配置中） |
+| 51 | last_table_id | BIGINT | YES | 该助教最近一次服务的球台 ID |
+| 52 | last_table_name | TEXT | YES | 最近服务球台名称（展示用） |
+| 53 | person_org_id | BIGINT | YES | 人事组织 ID，通常表示“某某门店-助教部-某小组”等层级组织 |
+| 54 | serial_number | BIGINT | YES | 系统内部生成的序列号或排序标识，用于全局排序或迁移 |
+| 55 | is_team_leader | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 56 | criticism_status | INTEGER | YES | 1 × 49 |
+| 57 | last_update_name | TEXT | YES | 最近修改该账号配置的管理员名称 |
+| 58 | ding_talk_synced | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 59 | site_light_cfg_id | BIGINT | YES | 门店灯控配置 ID，本门店未在助教账号维度启用 |
+| 60 | light_equipment_id | TEXT | YES | 灯控设备 ID，如果开启“助教开台自动控制灯”，会通过该字段关联到灯控硬件 |
+| 61 | entry_sign_status | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 62 | resign_sign_status | INTEGER | YES | 离职协议签署状态，类似上面 |
+| 63 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 64 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 65 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 66 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 67 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.assistant_accounts_master
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.assistant_accounts_master
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/assistant_accounts_master.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_assistant_cancellation_records.md

@@ -0,0 +1,70 @@
+# assistant_cancellation_records 助教取消/作废记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | assistant_cancellation_records |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/assistant_cancellation_records.json |
+| 说明 | 助教作废/取消记录 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 本表主键 ID，用于唯一标识一条记录 |
+| 2 | siteid | BIGINT | YES | （待补充） |
+| 3 | siteprofile | JSONB | YES | （待补充） |
+| 4 | assistantname | TEXT | YES | （待补充） |
+| 5 | assistantabolishamount | NUMERIC(18,2) | YES | （待补充） |
+| 6 | assistanton | INTEGER | YES | （待补充） |
+| 7 | pdchargeminutes | INTEGER | YES | （待补充） |
+| 8 | tableareaid | BIGINT | YES | （待补充） |
+| 9 | tablearea | TEXT | YES | （待补充） |
+| 10 | tableid | BIGINT | YES | （待补充） |
+| 11 | tablename | TEXT | YES | （待补充） |
+| 12 | trashreason | TEXT | YES | （待补充） |
+| 13 | createtime | TIMESTAMP | YES | （待补充） |
+| 14 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 15 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 16 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 17 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 18 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 19 | tenant_id | BIGINT | YES | 租户ID |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.assistant_cancellation_records
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.assistant_cancellation_records
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/assistant_cancellation_records.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_assistant_service_records.md

@@ -0,0 +1,122 @@
+# assistant_service_records 助教服务记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | assistant_service_records |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/assistant_service_records.json |
+| 说明 | 助教服务流水 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 本条助教流水记录的主键 ID（流水唯一标识） |
+| 2 | tenant_id | BIGINT | YES | 租户/品牌 ID |
+| 3 | site_id | BIGINT | YES | 门店 ID，本数据中指“朗朗桌球”这一家门店 |
+| 4 | siteprofile | JSONB | YES | （待补充） |
+| 5 | site_table_id | BIGINT | YES | 球台 ID |
+| 6 | order_settle_id | BIGINT | YES | 订单结算 ID，相当于“结账单号”的内部主键 |
+| 7 | order_trade_no | TEXT | YES | 订单交易号，整个订单层面的编号 |
+| 8 | order_pay_id | BIGINT | YES | 关联到“支付记录”的主键 ID |
+| 9 | order_assistant_id | BIGINT | YES | 订单中“助教项目明细”的内部 ID |
+| 10 | order_assistant_type | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 11 | assistantname | TEXT | YES | （待补充） |
+| 12 | assistantno | TEXT | YES | （待补充） |
+| 13 | assistant_level | TEXT | YES | 助教等级名称，与 assistant_level 一一对应（初级/中级/高级/助教管理） |
+| 14 | levelname | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 15 | site_assistant_id | BIGINT | YES | 门店维度的助教 ID |
+| 16 | skill_id | BIGINT | YES | 助教服务“课程/技能”ID |
+| 17 | skillname | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 18 | system_member_id | BIGINT | YES | 系统级会员 ID（全集团统一 ID） |
+| 19 | tablename | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 20 | tenant_member_id | BIGINT | YES | 商户维度会员 ID（门店/品牌内的会员主键） |
+| 21 | user_id | BIGINT | YES | 助教对应的“用户账号 ID”（系统级用户） |
+| 22 | assistant_team_id | BIGINT | YES | 助教所属团队 ID |
+| 23 | nickname | TEXT | YES | 助教对外昵称，如“佳怡”“周周”“球球”等 |
+| 24 | ledger_name | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 25 | ledger_group_name | TEXT | YES | 助教项目所属的“计费分组/套餐分组名称”，例如某种助教套餐或业务组名称 |
+| 26 | ledger_amount | NUMERIC(18,2) | YES | 按标准单价计算出来的应收金额（近似 = ledger_unit_price × income_seconds / 3600） |
+| 27 | ledger_count | NUMERIC(18,4) | YES | 台账记录的计时总秒数 |
+| 28 | ledger_unit_price | NUMERIC(18,4) | YES | 助教服务 标准单价（通常是标价：每小时、每节课的单价） |
+| 29 | ledger_status | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 30 | ledger_start_time | TIMESTAMP | YES | 台账层面记录的开始时间 |
+| 31 | ledger_end_time | TIMESTAMP | YES | 台账层面的结束时间 |
+| 32 | manual_discount_amount | NUMERIC(18,2) | YES | 收银员手动给予的减免金额（人工改价） |
+| 33 | member_discount_amount | NUMERIC(18,2) | YES | 由会员卡折扣产生的优惠金额 |
+| 34 | coupon_deduct_money | NUMERIC(18,2) | YES | 由“优惠券/代金券/团购券”等 直接抵扣到这条助教服务上的金额 |
+| 35 | service_money | NUMERIC(18,2) | YES | 用于记录与助教结算的金额（平台预留的“成本/分成”字段） |
+| 36 | projected_income | NUMERIC(18,2) | YES | 实际结算计入门店的金额（已经考虑折扣、卡权益、券等后的结果） |
+| 37 | real_use_seconds | INTEGER | YES | 实际使用时长（秒） |
+| 38 | income_seconds | INTEGER | YES | 计费秒数 / 应计收入对应的时间 |
+| 39 | start_use_time | TIMESTAMP | YES | 助教实际开始服务时间 |
+| 40 | last_use_time | TIMESTAMP | YES | 最后一次使用（实际服务）时间 |
+| 41 | create_time | TIMESTAMP | YES | 这条助教流水记录创建时间（一般接近结算/下单时间） |
+| 42 | is_single_order | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 43 | is_delete | INTEGER | YES | 逻辑删除标志 |
+| 44 | is_trash | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 45 | trash_reason | TEXT | YES | 废除原因（文本说明），例如“顾客取消”“录入错误”等 |
+| 46 | trash_applicant_id | BIGINT | YES | 提出废除申请的员工 ID（通常是操作员/管理员） |
+| 47 | trash_applicant_name | TEXT | YES | 废除申请人姓名 |
+| 48 | operator_id | BIGINT | YES | 操作员 ID（录入/结算这条助教服务的员工） |
+| 49 | operator_name | TEXT | YES | 操作员姓名，与 operator_id 一起使用，便于直接阅读 |
+| 50 | salesman_name | TEXT | YES | 关联的“营业员/销售员姓名”，用于提成归属 |
+| 51 | salesman_org_id | BIGINT | YES | 营业员所属组织/部门 ID |
+| 52 | salesman_user_id | BIGINT | YES | 营业员用户 ID |
+| 53 | person_org_id | BIGINT | YES | 助教所属“人事组织/部门 ID” |
+| 54 | add_clock | INTEGER | YES | 加钟秒数，即在原有预约/服务基础上临时追加的时长 |
+| 55 | returns_clock | INTEGER | YES | 退钟秒数（取消加钟或提前结束退回的时间） |
+| 56 | composite_grade | NUMERIC(10,2) | YES | 综合评分（例如技能+服务加权后的平均分），当前数据没有实际评分 |
+| 57 | composite_grade_time | TIMESTAMP | YES | 助教服务所在的球台名称（如 "A17"、"S1"） |
+| 58 | skill_grade | NUMERIC(10,2) | YES | 顾客对“技能表现”的评分（整数或打分等级） |
+| 59 | service_grade | NUMERIC(10,2) | YES | 顾客对“服务态度”的评分 |
+| 60 | sum_grade | NUMERIC(10,2) | YES | 累计评分总和（可能用于计算平均分），当前为 0 |
+| 61 | grade_status | INTEGER | YES | 1 = 未评价/正常 |
+| 62 | get_grade_times | INTEGER | YES | 该条记录对应的评价次数（或该助教被评价次数快照） |
+| 63 | is_not_responding | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 64 | is_confirm | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 65 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 66 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 67 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 68 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 69 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 70 | assistantteamname | TEXT | YES | 助教团队名称 |
+| 71 | real_service_money | NUMERIC(18,2) | YES | 实际服务费金额 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.assistant_service_records
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.assistant_service_records
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/assistant_service_records.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_goods_stock_movements.md

@@ -0,0 +1,75 @@
+# goods_stock_movements 商品库存变动流水
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | goods_stock_movements |
+| 主键 | sitegoodsstockid, content_hash |
+| 数据来源 | export/test-json-doc/goods_stock_movements.json |
+| 说明 | 商品库存变动流水 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | sitegoodsstockid | BIGINT | NO | （待补充） |
+| 2 | tenantid | BIGINT | YES | （待补充） |
+| 3 | siteid | BIGINT | YES | （待补充） |
+| 4 | sitegoodsid | BIGINT | YES | （待补充） |
+| 5 | goodsname | TEXT | YES | （待补充） |
+| 6 | goodscategoryid | BIGINT | YES | （待补充） |
+| 7 | goodssecondcategoryid | BIGINT | YES | （待补充） |
+| 8 | unit | TEXT | YES | 库存计量单位 |
+| 9 | price | NUMERIC(18,4) | YES | 商品单价（单位金额） |
+| 10 | stocktype | INTEGER | YES | （待补充） |
+| 11 | changenum | NUMERIC(18,4) | YES | （待补充） |
+| 12 | startnum | NUMERIC(18,4) | YES | （待补充） |
+| 13 | endnum | NUMERIC(18,4) | YES | （待补充） |
+| 14 | changenuma | NUMERIC(18,4) | YES | （待补充） |
+| 15 | startnuma | NUMERIC(18,4) | YES | （待补充） |
+| 16 | endnuma | NUMERIC(18,4) | YES | （待补充） |
+| 17 | remark | TEXT | YES | 备注信息，用于手工记录本次变更的特殊原因说明（例如“盘点差异调整”“报损”） |
+| 18 | operatorname | TEXT | YES | （待补充） |
+| 19 | createtime | TIMESTAMP | YES | （待补充） |
+| 20 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 21 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 22 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 23 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 24 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.goods_stock_movements
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.goods_stock_movements
+WHERE sitegoodsstockid = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/goods_stock_movements.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_goods_stock_summary.md

@@ -0,0 +1,70 @@
+# goods_stock_summary 商品库存汇总
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | goods_stock_summary |
+| 主键 | sitegoodsid, content_hash |
+| 数据来源 | export/test-json-doc/goods_stock_summary.json |
+| 说明 | 商品库存汇总 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | sitegoodsid | BIGINT | NO | （待补充） |
+| 2 | goodsname | TEXT | YES | （待补充） |
+| 3 | goodsunit | TEXT | YES | （待补充） |
+| 4 | goodscategoryid | BIGINT | YES | （待补充） |
+| 5 | goodscategorysecondid | BIGINT | YES | （待补充） |
+| 6 | categoryname | TEXT | YES | （待补充） |
+| 7 | rangestartstock | NUMERIC(18,4) | YES | （待补充） |
+| 8 | rangeendstock | NUMERIC(18,4) | YES | （待补充） |
+| 9 | rangein | NUMERIC(18,4) | YES | （待补充） |
+| 10 | rangeout | NUMERIC(18,4) | YES | （待补充） |
+| 11 | rangesale | NUMERIC(18,4) | YES | （待补充） |
+| 12 | rangesalemoney | NUMERIC(18,2) | YES | （待补充） |
+| 13 | rangeinventory | NUMERIC(18,4) | YES | （待补充） |
+| 14 | currentstock | NUMERIC(18,4) | YES | （待补充） |
+| 15 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 16 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 17 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 18 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 19 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.goods_stock_summary
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.goods_stock_summary
+WHERE sitegoodsid = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/goods_stock_summary.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_group_buy_packages.md

@@ -0,0 +1,94 @@
+# group_buy_packages 团购套餐定义
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | group_buy_packages |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/group_buy_packages.json |
+| 说明 | 团购套餐主数据 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 门店侧套餐 ID，本文件内部的主键 |
+| 2 | package_id | BIGINT | YES | “上层套餐 ID” 或“总部/系统级套餐 ID” |
+| 3 | package_name | TEXT | YES | 团购套餐名称，用于前台展示和核销界面 |
+| 4 | selling_price | NUMERIC(18,2) | YES | 语义上应该是“团购售卖价”（顾客在平台购买券时的成交价格） |
+| 5 | coupon_money | NUMERIC(18,2) | YES | 券面值或内部结算面值，表示该套餐在门店侧对应的金额额度 |
+| 6 | date_type | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 7 | date_info | TEXT | YES | 预留字段，通常用来存储更细粒度的日期信息，如具体日期列表、节假日特殊规则（可能是 JSON 字符串或编码） |
+| 8 | start_time | TIMESTAMP | YES | 套餐开始生效的日期时间 |
+| 9 | end_time | TIMESTAMP | YES | 套餐失效的日期时间（到这个时间点后不可使用） |
+| 10 | start_clock | TEXT | YES | 每日可用起始时间点（第一段） |
+| 11 | end_clock | TEXT | YES | 每日可用的结束时间点（第一段） |
+| 12 | add_start_clock | TEXT | YES | 附加可用时间段的起始时间（第二段） |
+| 13 | add_end_clock | TEXT | YES | 附加时段结束时间，多数情况配合 "00:00:00" 或 "10:00:00" 使用 |
+| 14 | duration | INTEGER | YES | 套餐内包含的时长（秒） |
+| 15 | usable_count | INTEGER | YES | 可使用次数上限 |
+| 16 | usable_range | INTEGER | YES | 一般用于文字描述可用日期范围（例如“周一至周五”） |
+| 17 | table_area_id | BIGINT | YES | 原始设计应为“单一台区 ID”，当套餐只限一个区域可以用这个字段存储 |
+| 18 | table_area_name | TEXT | YES | 套餐适用的“门店台区名称”，用于显示和筛选 |
+| 19 | table_area_id_list | JSONB | YES | 用来存放具体台区 ID 列表（例如 "1,2,3"），实现更细粒度的台桌限制 |
+| 20 | tenant_table_area_id | BIGINT | YES | 与 table_area_id 类似，是租户层级的台区 ID，原本用于单区选择 |
+| 21 | tenant_table_area_id_list | JSONB | YES | 实际代表“台区集合 ID”或“租户台区配置 ID”，用来限制套餐可用的台区范围 |
+| 22 | site_id | BIGINT | YES | 门店 ID |
+| 23 | site_name | TEXT | YES | 门店名称 |
+| 24 | tenant_id | BIGINT | YES | 租户 ID（品牌/商户 ID） |
+| 25 | card_type_ids | JSONB | YES | 原意是“适用会员卡类型 ID 列表”，例如某套餐只允许某几种会员卡使用，可以在此配置 |
+| 26 | group_type | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 27 | system_group_type | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 28 | type | INTEGER | YES | 内部业务子类型，具体含义需要结合系统文档 |
+| 29 | effective_status | INTEGER | YES | 1：13 条 |
+| 30 | is_enabled | INTEGER | YES | 启用状态 |
+| 31 | is_delete | INTEGER | YES | 逻辑删除标志 |
+| 32 | max_selectable_categories | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 33 | area_tag_type | INTEGER | YES | 1 很可能代表“按台区标签限制”，例如 A区、中八区、包厢、KTV 等 |
+| 34 | creator_name | TEXT | YES | 创建人信息，一般包含“角色：姓名” |
+| 35 | create_time | TIMESTAMP | YES | 该套餐在系统中创建的时间 |
+| 36 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 37 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 38 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 39 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 40 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 41 | is_first_limit | BOOLEAN | YES | 是否首单限制 |
+| 42 | sort | INTEGER | YES | 排序 |
+| 43 | tenantcouponsaleorderitemid | BIGINT | YES | 租户券销售订单项ID |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.group_buy_packages
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.group_buy_packages
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/group_buy_packages.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_group_buy_redemption_records.md

@@ -0,0 +1,108 @@
+# group_buy_redemption_records 团购核销记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | group_buy_redemption_records |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/group_buy_redemption_records.json |
+| 说明 | 团购核销记录 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 本条“团购套餐流水”记录的 主键 ID |
+| 2 | tenant_id | BIGINT | YES | 租户/品牌 ID |
+| 3 | site_id | BIGINT | YES | 门店 ID，与其它 JSON 中一致 |
+| 4 | sitename | TEXT | YES | （待补充） |
+| 5 | table_id | BIGINT | YES | 球台 ID |
+| 6 | tablename | TEXT | YES | （待补充） |
+| 7 | tableareaname | TEXT | YES | （待补充） |
+| 8 | tenant_table_area_id | BIGINT | YES | 租户级台区分组 ID，表示当前使用券的台桌所属的区域组合 |
+| 9 | order_trade_no | TEXT | YES | 订单交易号，和其它消费明细（台费、商品、助教、团购）共用的订单主键 |
+| 10 | order_settle_id | BIGINT | YES | 结算单 ID（小票结账主键） |
+| 11 | order_pay_id | BIGINT | YES | 指向支付记录表中的支付流水 ID |
+| 12 | order_coupon_id | BIGINT | YES | 订单中“券使用记录”的 ID |
+| 13 | order_coupon_channel | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 14 | coupon_code | TEXT | YES | 团购券券码，核销时扫描/录入的字符串 |
+| 15 | coupon_money | NUMERIC(18,2) | YES | 本次核销时，这张券在门店侧对应的金额额度（“可抵扣金额”） |
+| 16 | coupon_origin_id | BIGINT | YES | 平台/上游系统中的券记录主键 ID，“券来源 ID” |
+| 17 | ledger_name | TEXT | YES | 台费侧关联的“团购项目名称”（记账名） |
+| 18 | ledger_group_name | TEXT | YES | 团购项目所属的“记账分组名称”（例如“团购台费”“团购包厢”等） |
+| 19 | ledger_amount | NUMERIC(18,2) | YES | 本次券实际冲抵台费的金额 |
+| 20 | ledger_count | NUMERIC(18,4) | YES | 按此次优惠实际计算的“核销秒数” |
+| 21 | ledger_unit_price | NUMERIC(18,4) | YES | 对应台费的标准单价，单位元/小时（从数值来看是类似29.9/小时这种定价） |
+| 22 | ledger_status | INTEGER | YES | 流水状态 |
+| 23 | table_charge_seconds | INTEGER | YES | 本次结算中该球台总计计费的秒数（整台的台费计费时间） |
+| 24 | promotion_activity_id | BIGINT | YES | 团购/促销活动 ID |
+| 25 | promotion_coupon_id | BIGINT | YES | 团购套餐定义 ID |
+| 26 | promotion_seconds | INTEGER | YES | 团购套餐定义的“标准时长”（券本身标称的可用时长） |
+| 27 | offer_type | INTEGER | YES | 优惠类型 |
+| 28 | assistant_promotion_money | NUMERIC(18,2) | YES | 分摊到“助教服务”的促销金额 |
+| 29 | assistant_service_promotion_money | NUMERIC(18,2) | YES | 进一步细分助教服务的促销金额 |
+| 30 | table_service_promotion_money | NUMERIC(18,2) | YES | 本次券使用中，分摊到“台费服务费”部分的促销金额 |
+| 31 | goods_promotion_money | NUMERIC(18,2) | YES | 本次券使用中，分摊到“商品”部分的促销金额 |
+| 32 | recharge_promotion_money | NUMERIC(18,2) | YES | 来自“充值类优惠”的分摊金额（例如储值赠送部分） |
+| 33 | reward_promotion_money | NUMERIC(18,2) | YES | 本次促销中，属于“奖励金/积分抵扣”的金额 |
+| 34 | goodsoptionprice | NUMERIC(18,2) | YES | （待补充） |
+| 35 | salesman_name | TEXT | YES | 营业员姓名 |
+| 36 | sales_man_org_id | BIGINT | YES | 营业员所属组织 ID |
+| 37 | salesman_role_id | BIGINT | YES | 营业员角色 ID |
+| 38 | salesman_user_id | BIGINT | YES | 营业员/业务员用户 ID |
+| 39 | operator_id | BIGINT | YES | 执行本次核销/结算操作的 操作员 ID |
+| 40 | operator_name | TEXT | YES | 操作员名称（包含角色说明），与 operator_id 对应的冗余展示字段 |
+| 41 | is_single_order | INTEGER | YES | 是否单独作为一条订单行 |
+| 42 | is_delete | INTEGER | YES | 逻辑删除标记（0=否，1=是） |
+| 43 | create_time | TIMESTAMP | YES | 本条团购套餐使用流水创建时间（即券核销时间，或与结账时间接近） |
+| 44 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 45 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 46 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 47 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 48 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 49 | assistant_service_share_money | NUMERIC(18,2) | YES | 助教服务分摊金额 |
+| 50 | assistant_share_money | NUMERIC(18,2) | YES | 助教分摊金额 |
+| 51 | coupon_sale_id | BIGINT | YES | 优惠券销售ID |
+| 52 | good_service_share_money | NUMERIC(18,2) | YES | 商品服务分摊金额 |
+| 53 | goods_share_money | NUMERIC(18,2) | YES | 商品分摊金额 |
+| 54 | member_discount_money | NUMERIC(18,2) | YES | 会员折扣金额 |
+| 55 | recharge_share_money | NUMERIC(18,2) | YES | 充值分摊金额 |
+| 56 | table_service_share_money | NUMERIC(18,2) | YES | 台费服务分摊金额 |
+| 57 | table_share_money | NUMERIC(18,2) | YES | 台费分摊金额 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.group_buy_redemption_records
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.group_buy_redemption_records
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/group_buy_redemption_records.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_member_balance_changes.md

@@ -0,0 +1,84 @@
+# member_balance_changes 会员余额变更流水
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | member_balance_changes |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/member_balance_changes.json |
+| 说明 | 会员余额变更流水 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | tenant_id | BIGINT | YES | 租户/商户 ID，本数据中是固定值（同一品牌/商户） |
+| 2 | site_id | BIGINT | YES | 非 0：记录所属的具体门店 ID（与其他 JSON 内的 site_id 一致） |
+| 3 | register_site_id | BIGINT | YES | 会员卡的“注册门店 ID”，即办卡所在门店 |
+| 4 | registersitename | TEXT | YES | （待补充） |
+| 5 | paysitename | TEXT | YES | （待补充） |
+| 6 | id | BIGINT | NO | 余额变更记录的主键 ID，唯一标识这一条“账户余额变化事件” |
+| 7 | tenant_member_id | BIGINT | YES | 商户维度的会员 ID（租户内会员主键） |
+| 8 | tenant_member_card_id | BIGINT | YES | 会员卡账户 ID，在租户内唯一标识某张卡 |
+| 9 | system_member_id | BIGINT | YES | 系统级（全局）会员 ID |
+| 10 | membername | TEXT | YES | （待补充） |
+| 11 | membermobile | TEXT | YES | （待补充） |
+| 12 | card_type_id | BIGINT | YES | 卡种类型 ID，用于区分不同卡种 |
+| 13 | membercardtypename | TEXT | YES | （待补充） |
+| 14 | account_data | NUMERIC(18,2) | YES | 本次变动的金额（元），正数表示增加，负数表示减少 |
+| 15 | before | NUMERIC(18,2) | YES | 本次变动前，该卡账户的余额（元） |
+| 16 | after | NUMERIC(18,2) | YES | 本次变动后，该卡账户的余额（元） |
+| 17 | refund_amount | NUMERIC(18,2) | YES | 可能用于标记“其中有多少金额是以‘退款’形式回流的”，或区分“退回余额”和“原路退回”两种模式 |
+| 18 | from_type | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 19 | payment_method | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 20 | relate_id | BIGINT | YES | 例如某次充值记录的 ID、某张订单/结算单 ID、某次活动抵用券核销记录 ID 等 |
+| 21 | remark | TEXT | YES | 当为空时，说明这条变动没有额外备注说明 |
+| 22 | operator_id | BIGINT | YES | 执行此次余额变更操作的员工 ID |
+| 23 | operator_name | TEXT | YES | 操作员姓名（带职位前缀），是对 operator_id 的可读冗余字段 |
+| 24 | is_delete | INTEGER | YES | 逻辑删除标记（0=否，1=是） |
+| 25 | create_time | TIMESTAMP | YES | 本条余额变更记录的创建时间，通常接近交易发生时间 |
+| 26 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 27 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 28 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 29 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 30 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 31 | principal_after | NUMERIC(18,2) | YES | 变动后本金 |
+| 32 | principal_before | NUMERIC(18,2) | YES | 变动前本金 |
+| 33 | principal_data | TEXT | YES | 本金变动数据 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.member_balance_changes
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.member_balance_changes
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/member_balance_changes.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_member_profiles.md

@@ -0,0 +1,76 @@
+# member_profiles 会员档案/账户信息
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | member_profiles |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/member_profiles.json |
+| 说明 | 会员档案/会员账户信息 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | tenant_id | BIGINT | YES | 租户/品牌 ID |
+| 2 | register_site_id | BIGINT | YES | 会员的注册门店 ID |
+| 3 | site_name | TEXT | YES | 注册门店名称，属于冗余字段，用于直接展示 |
+| 4 | id | BIGINT | NO | 这是“租户内会员账户”的主键 ID |
+| 5 | system_member_id | BIGINT | YES | 这是“系统级会员 ID”，在全平台唯一，用来把一个会员在不同门店/不同卡类型下的账户统一到一个“人”的维度上 |
+| 6 | member_card_grade_code | BIGINT | YES | 这两个字段是成对出现的：一个数值码，一个中文名称 |
+| 7 | member_card_grade_name | TEXT | YES | 这是“会员卡种类/等级”的定义字段 |
+| 8 | mobile | TEXT | YES | 会员绑定的手机号码 |
+| 9 | nickname | TEXT | YES | 会员在当前租户下的显示名称（可以是姓名，也可以是昵称） |
+| 10 | point | NUMERIC(18,2) | YES | 当前积分余额（这条会员账户的积分值） |
+| 11 | growth_value | NUMERIC(18,2) | YES | 成长值 / 经验值，用于会员等级晋升的累计指标 |
+| 12 | referrer_member_id | BIGINT | YES | 推荐人会员 ID，用于记录该会员是由哪位老会员推荐 |
+| 13 | status | INTEGER | YES | 帐户状态（偏“卡状态/档案状态”） |
+| 14 | user_status | INTEGER | YES | 用户账号状态（偏“用户逻辑”层面的状态） |
+| 15 | create_time | TIMESTAMP | YES | 会员账户的创建时间（即这条档案/这张卡在系统中被创建的时间） |
+| 16 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 17 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 18 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 19 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 20 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 21 | pay_money_sum | NUMERIC(18,2) | YES | 累计支付金额 |
+| 22 | person_tenant_org_id | BIGINT | YES | 人员租户组织ID |
+| 23 | person_tenant_org_name | TEXT | YES | 人员租户组织名称 |
+| 24 | recharge_money_sum | NUMERIC(18,2) | YES | 累计充值金额 |
+| 25 | register_source | TEXT | YES | 注册来源 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.member_profiles
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.member_profiles
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/member_profiles.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_member_stored_value_cards.md

@@ -0,0 +1,131 @@
+# member_stored_value_cards 会员储值/卡券账户
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | member_stored_value_cards |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/member_stored_value_cards.json |
+| 说明 | 会员储值/卡券账户列表 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | tenant_id | BIGINT | YES | 租户/品牌 ID，与其他 JSON 中 tenant_id 一致 |
+| 2 | tenant_member_id | BIGINT | YES | 当前商户（品牌/租户）中会员的主键 ID |
+| 3 | system_member_id | BIGINT | YES | 系统级会员 ID（跨门店统一主键） |
+| 4 | register_site_id | BIGINT | YES | 卡首次办理的门店 ID |
+| 5 | site_name | TEXT | YES | 卡归属门店名称（视图中的展示字段） |
+| 6 | id | BIGINT | NO | 本表主键 ID，用于唯一标识一条记录 |
+| 7 | member_card_grade_code | BIGINT | YES | 卡等级/卡类代码，和下面两个名称字段一一对应 |
+| 8 | member_card_grade_code_name | TEXT | YES | 卡等级/卡类名称 |
+| 9 | member_card_type_name | TEXT | YES | 卡类型名称，实际与 member_card_grade_code_name 一致 |
+| 10 | member_name | TEXT | YES | 持卡会员姓名快照 |
+| 11 | member_mobile | TEXT | YES | 持卡会员手机号快照 |
+| 12 | card_type_id | BIGINT | YES | 卡种 ID（定义“这是哪一种卡”） |
+| 13 | card_no | TEXT | YES | 实体卡物理卡号／条码号 |
+| 14 | card_physics_type | TEXT | YES | 物理卡类型 |
+| 15 | balance | NUMERIC(18,2) | YES | 当前卡内余额（主要针对储值卡、部分券卡） |
+| 16 | denomination | NUMERIC(18,2) | YES | 采用“几折”的记法：10=不打折，9=九折，8=八折 |
+| 17 | table_discount | NUMERIC(10,4) | YES | 数量/时长字段，用于统计与计量 |
+| 18 | goods_discount | NUMERIC(10,4) | YES | 数量/时长字段，用于统计与计量 |
+| 19 | assistant_discount | NUMERIC(10,4) | YES | 数量/时长字段，用于统计与计量 |
+| 20 | assistant_reward_discount | NUMERIC(10,4) | YES | 数量/时长字段，用于统计与计量 |
+| 21 | table_service_discount | NUMERIC(10,4) | YES | 数量/时长字段，用于统计与计量 |
+| 22 | assistant_service_discount | NUMERIC(10,4) | YES | 数量/时长字段，用于统计与计量 |
+| 23 | coupon_discount | NUMERIC(10,4) | YES | 数量/时长字段，用于统计与计量 |
+| 24 | goods_service_discount | NUMERIC(10,4) | YES | 数量/时长字段，用于统计与计量 |
+| 25 | assistant_discount_sub_switch | INTEGER | YES | 数量/时长字段，用于统计与计量 |
+| 26 | table_discount_sub_switch | INTEGER | YES | 数量/时长字段，用于统计与计量 |
+| 27 | goods_discount_sub_switch | INTEGER | YES | 数量/时长字段，用于统计与计量 |
+| 28 | assistant_reward_discount_sub_switch | INTEGER | YES | 数量/时长字段，用于统计与计量 |
+| 29 | table_service_deduct_radio | NUMERIC(10,4) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 30 | assistant_service_deduct_radio | NUMERIC(10,4) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 31 | goods_service_deduct_radio | NUMERIC(10,4) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 32 | assistant_deduct_radio | NUMERIC(10,4) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 33 | table_deduct_radio | NUMERIC(10,4) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 34 | goods_deduct_radio | NUMERIC(10,4) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 35 | coupon_deduct_radio | NUMERIC(10,4) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 36 | assistant_reward_deduct_radio | NUMERIC(10,4) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 37 | tablecarddeduct | NUMERIC(18,2) | YES | （待补充） |
+| 38 | tableservicecarddeduct | NUMERIC(18,2) | YES | （待补充） |
+| 39 | goodscardeduct | NUMERIC(18,2) | YES | （待补充） |
+| 40 | goodsservicecarddeduct | NUMERIC(18,2) | YES | （待补充） |
+| 41 | assistantcarddeduct | NUMERIC(18,2) | YES | （待补充） |
+| 42 | assistantservicecarddeduct | NUMERIC(18,2) | YES | （待补充） |
+| 43 | assistantrewardcarddeduct | NUMERIC(18,2) | YES | （待补充） |
+| 44 | cardsettlededuct | NUMERIC(18,2) | YES | （待补充） |
+| 45 | couponcarddeduct | NUMERIC(18,2) | YES | （待补充） |
+| 46 | deliveryfeededuct | NUMERIC(18,2) | YES | （待补充） |
+| 47 | use_scene | INTEGER | YES | 卡使用场景说明（比如“仅店内使用”“仅团建”等），本门店尚未使用此字段 |
+| 48 | able_cross_site | INTEGER | YES | 是否允许跨店使用 |
+| 49 | is_allow_give | INTEGER | YES | 是否允许转赠/转让给其他会员 |
+| 50 | is_allow_order_deduct | INTEGER | YES | 是否允许在“订单层面统一扣款” |
+| 51 | is_delete | INTEGER | YES | 逻辑删除标志 |
+| 52 | bind_password | TEXT | YES | 卡绑定密码，用于消费或查询验证（目前未启用） |
+| 53 | goods_discount_range_type | INTEGER | YES | 数量/时长字段，用于统计与计量 |
+| 54 | goodscategoryid | BIGINT | YES | （待补充） |
+| 55 | tableareaid | BIGINT | YES | （待补充） |
+| 56 | effect_site_id | BIGINT | YES | 卡片限定生效门店 ID |
+| 57 | start_time | TIMESTAMP | YES | 卡片生效开始时间（有效期起始） |
+| 58 | end_time | TIMESTAMP | YES | 卡片有效期结束时间 |
+| 59 | disable_start_time | TIMESTAMP | YES | 停用时间段（比如临时冻结卡的起止时间） |
+| 60 | disable_end_time | TIMESTAMP | YES | 停用时间段（比如临时冻结卡的起止时间） |
+| 61 | last_consume_time | TIMESTAMP | YES | 最近一次消费时间 |
+| 62 | create_time | TIMESTAMP | YES | 卡片创建时间（开卡时间） |
+| 63 | status | INTEGER | YES | 状态枚举，用于标识记录当前业务状态 |
+| 64 | sort | INTEGER | YES | 在前端展示或某些列表中的排序权重 |
+| 65 | tenantavatar | TEXT | YES | （待补充） |
+| 66 | tenantname | TEXT | YES | （待补充） |
+| 67 | pdassisnatlevel | TEXT | YES | （待补充） |
+| 68 | cxassisnatlevel | TEXT | YES | （待补充） |
+| 69 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 70 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 71 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 72 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 73 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 74 | able_share_member_discount | BOOLEAN | YES | 是否可共享会员折扣 |
+| 75 | electricity_deduct_radio | NUMERIC(18,4) | YES | 电费扣减比例 |
+| 76 | electricity_discount | NUMERIC(18,4) | YES | 电费折扣 |
+| 77 | electricitycarddeduct | BOOLEAN | YES | 电费卡扣 |
+| 78 | member_grade | BIGINT | YES | 会员等级 |
+| 79 | principal_balance | NUMERIC(18,2) | YES | 本金余额 |
+| 80 | rechargefreezebalance | NUMERIC(18,2) | YES | 充值冻结余额 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.member_stored_value_cards
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.member_stored_value_cards
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/member_stored_value_cards.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_payment_transactions.md

@@ -0,0 +1,68 @@
+# payment_transactions 支付交易记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | payment_transactions |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/payment_transactions.json |
+| 说明 | 支付流水 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 支付流水记录的主键 ID |
+| 2 | site_id | BIGINT | YES | 支付记录所属的门店 ID |
+| 3 | siteprofile | JSONB | YES | （待补充） |
+| 4 | relate_type | INTEGER | YES | 表示“这条支付记录关联的业务类型” |
+| 5 | relate_id | BIGINT | YES | 关联业务记录的主键 ID（按 relate_type 不同指向不同表） |
+| 6 | pay_amount | NUMERIC(18,2) | YES | 本条支付流水的“支付金额”，单位为元 |
+| 7 | pay_status | INTEGER | YES | 支付状态枚举字段 |
+| 8 | pay_time | TIMESTAMP | YES | 实际支付完成时间（支付状态变为成功的时间戳） |
+| 9 | create_time | TIMESTAMP | YES | 支付记录创建时间，通常与发起支付请求的时间一致（创建支付流水的时间戳） |
+| 10 | payment_method | INTEGER | YES | 支付方式枚举，例如微信、支付宝、现金、银行卡、储值卡等某一种 |
+| 11 | online_pay_channel | INTEGER | YES | 每一笔结账单（settleList.id）对应一条支付记录（当前样本中是一条记录，relate_id 唯一） |
+| 12 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 13 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 14 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 15 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 16 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 17 | tenant_id | BIGINT | YES | 租户ID |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.payment_transactions
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.payment_transactions
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/payment_transactions.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_platform_coupon_redemption_records.md

@@ -0,0 +1,82 @@
+# platform_coupon_redemption_records 平台券核销记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | platform_coupon_redemption_records |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/platform_coupon_redemption_records.json |
+| 说明 | 平台券核销/使用记录 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 本条平台验券记录在本系统内的主键 ID |
+| 2 | verify_id | BIGINT | YES | 平台核销记录 ID（某些平台会为每一次核销生成一个唯一 ID） |
+| 3 | certificate_id | TEXT | YES | 平台侧的凭证 ID（通常由第三方团购平台生成的券实例 ID） |
+| 4 | coupon_code | TEXT | YES | 券码，顾客出示的团购券密码/编号 |
+| 5 | coupon_name | TEXT | YES | 团购券产品名称（即第三方平台上向顾客展示的名称） |
+| 6 | coupon_channel | INTEGER | YES | 券来源渠道（第三方平台渠道编号） |
+| 7 | groupon_type | INTEGER | YES | 团购券类型 |
+| 8 | group_package_id | BIGINT | YES | 标识类 ID 字段，用于关联/定位相关实体 |
+| 9 | sale_price | NUMERIC(18,2) | YES | 顾客在第三方平台上实际支付的价格（团购售价） |
+| 10 | coupon_money | NUMERIC(18,2) | YES | 券面值 / 套餐价值（系统层面的“可抵扣金额或对应套餐价值”） |
+| 11 | coupon_free_time | NUMERIC(18,2) | YES | 券附带的“免费时长”字段（例如送多少分钟台费） |
+| 12 | coupon_cover | TEXT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 13 | coupon_remark | TEXT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 14 | use_status | INTEGER | YES | 值 1：198 条 |
+| 15 | consume_time | TIMESTAMP | YES | 券被核销/使用的业务时间 |
+| 16 | create_time | TIMESTAMP | YES | 验券记录在本系统中创建的时间（记录入库时间） |
+| 17 | deal_id | TEXT | YES | 另一个层次的团购产品 ID |
+| 18 | channel_deal_id | TEXT | YES | 渠道侧 dealId / 产品 ID，一般是第三方平台给该团购商品定义的主键 |
+| 19 | site_id | BIGINT | YES | 门店 ID |
+| 20 | site_order_id | BIGINT | YES | 门店内部的订单 ID（平台券核销时对应的店内订单） |
+| 21 | table_id | BIGINT | YES | 使用券的球台 ID |
+| 22 | tenant_id | BIGINT | YES | 商户/租户 ID（品牌级别） |
+| 23 | operator_id | BIGINT | YES | 操作员 ID（执行验券操作的收银员/员工） |
+| 24 | operator_name | TEXT | YES | 操作员姓名，例如 "收银员:郑丽珊" |
+| 25 | is_delete | INTEGER | YES | 把平台验券记录挂到本门店的一条订单上 |
+| 26 | siteprofile | JSONB | YES | （待补充） |
+| 27 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 28 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 29 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 30 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 31 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.platform_coupon_redemption_records
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.platform_coupon_redemption_records
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/platform_coupon_redemption_records.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_recharge_settlements.md

@@ -0,0 +1,122 @@
+# recharge_settlements 充值结算记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | recharge_settlements |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/recharge_settlements.json |
+| 说明 | 充值结算记录 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 门店 ID |
+| 2 | tenantid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 3 | siteid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 4 | sitename | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 5 | balanceamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 6 | cardamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 7 | cashamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 8 | couponamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 9 | createtime | TIMESTAMPTZ | YES | 时间字段，用于记录业务时间点/发生时间 |
+| 10 | memberid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 11 | membername | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 12 | tenantmembercardid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 13 | membercardtypename | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 14 | memberphone | TEXT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 15 | tableid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 16 | consumemoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 17 | onlineamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 18 | operatorid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 19 | operatorname | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 20 | revokeorderid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 21 | revokeordername | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 22 | revoketime | TIMESTAMPTZ | YES | 时间字段，用于记录业务时间点/发生时间 |
+| 23 | payamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 24 | pointamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 25 | refundamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 26 | settlename | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 27 | settlerelateid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 28 | settlestatus | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 29 | settletype | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 30 | paytime | TIMESTAMPTZ | YES | 时间字段，用于记录业务时间点/发生时间 |
+| 31 | roundingamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 32 | paymentmethod | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 33 | adjustamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 34 | assistantcxmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 35 | assistantpdmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 36 | couponsaleamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 37 | memberdiscountamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 38 | tablechargemoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 39 | goodsmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 40 | realgoodsmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 41 | servicemoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 42 | prepaymoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 43 | salesmanname | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 44 | orderremark | TEXT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 45 | salesmanuserid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 46 | canberevoked | BOOLEAN | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 47 | pointdiscountprice | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 48 | pointdiscountcost | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 49 | activitydiscount | NUMERIC(18,2) | YES | 数量/时长字段，用于统计与计量 |
+| 50 | serialnumber | BIGINT | YES | 数量/时长字段，用于统计与计量 |
+| 51 | assistantmanualdiscount | NUMERIC(18,2) | YES | 数量/时长字段，用于统计与计量 |
+| 52 | allcoupondiscount | NUMERIC(18,2) | YES | 数量/时长字段，用于统计与计量 |
+| 53 | goodspromotionmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 54 | assistantpromotionmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 55 | isusecoupon | BOOLEAN | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 56 | isusediscount | BOOLEAN | YES | 数量/时长字段，用于统计与计量 |
+| 57 | isactivity | BOOLEAN | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 58 | isbindmember | BOOLEAN | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 59 | isfirst | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 60 | rechargecardamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 61 | giftcardamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 62 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 63 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 64 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 65 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 66 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 67 | electricityadjustmoney | NUMERIC(18,2) | YES | 电费调整金额 |
+| 68 | electricitymoney | NUMERIC(18,2) | YES | 电费金额 |
+| 69 | mervousalesamount | NUMERIC(18,2) | YES | 商户券销售额 |
+| 70 | plcouponsaleamount | NUMERIC(18,2) | YES | 平台券销售额 |
+| 71 | realelectricitymoney | NUMERIC(18,2) | YES | 实际电费金额 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.recharge_settlements
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.recharge_settlements
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/recharge_settlements.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_refund_transactions.md

@@ -0,0 +1,88 @@
+# refund_transactions 退款交易记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | refund_transactions |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/refund_transactions.json |
+| 说明 | 退款流水 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 本条 退款流水 的唯一 ID |
+| 2 | tenant_id | BIGINT | YES | 租户/品牌 ID，全系统维度标识该商户 |
+| 3 | tenantname | TEXT | YES | （待补充） |
+| 4 | site_id | BIGINT | YES | 门店 ID |
+| 5 | siteprofile | JSONB | YES | （待补充） |
+| 6 | relate_type | INTEGER | YES | 本退款对应的“业务类型” |
+| 7 | relate_id | BIGINT | YES | 本次退款关联的业务 ID |
+| 8 | pay_sn | TEXT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 9 | pay_amount | NUMERIC(18,2) | YES | 本次退款的 资金变动金额 |
+| 10 | refund_amount | NUMERIC(18,2) | YES | 设计上本应显示“实际退款金额”（正数），与 pay_amount 配合使用 |
+| 11 | round_amount | NUMERIC(18,2) | YES | 舍入金额/抹零金额 |
+| 12 | pay_status | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 13 | pay_time | TIMESTAMP | YES | 退款在支付渠道层面实际发生的时间 |
+| 14 | create_time | TIMESTAMP | YES | 本条退款流水在系统内创建时间 |
+| 15 | payment_method | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 16 | pay_terminal | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 17 | pay_config_id | BIGINT | YES | 支付配置 ID，例如商户在“非球科技”内配置的某一条支付通道（某个微信商户号、银联通道）的主键 |
+| 18 | online_pay_channel | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 19 | online_pay_type | INTEGER | YES | 当前：全部 0 |
+| 20 | channel_fee | NUMERIC(18,2) | YES | 第三方支付渠道对本次退款收取的手续费 |
+| 21 | channel_payer_id | TEXT | YES | 支付渠道侧的 payer ID，例如微信 openid、银行卡号掩码等 |
+| 22 | channel_pay_no | TEXT | YES | 第三方支付平台的交易号（如微信支付单号、支付宝交易号等） |
+| 23 | member_id | BIGINT | YES | 租户内部的会员 ID（对应会员档案中的某个主键） |
+| 24 | member_card_id | BIGINT | YES | 关联的会员卡账户 ID（对应“储值卡列表”或“会员档案”中的某一张卡） |
+| 25 | cashier_point_id | BIGINT | YES | 收银点 ID，例如前台 1、前台 2、自助机等 |
+| 26 | operator_id | BIGINT | YES | 执行该退款操作的操作员 ID |
+| 27 | action_type | INTEGER | YES | 当前：全部 2 |
+| 28 | check_status | INTEGER | YES | 当前：全部 1 |
+| 29 | is_revoke | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 30 | is_delete | INTEGER | YES | 逻辑删除标志 |
+| 31 | balance_frozen_amount | NUMERIC(18,2) | YES | 涉及会员储值卡退款时，暂时冻结的余额金额 |
+| 32 | card_frozen_amount | NUMERIC(18,2) | YES | 与上一个类似，偏向“某张卡的被冻结金额”，也与会员卡/储值账户相关 |
+| 33 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 34 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 35 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 36 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 37 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.refund_transactions
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.refund_transactions
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/refund_transactions.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_settlement_records.md

@@ -0,0 +1,122 @@
+# settlement_records 结算记录（台费+商品+助教）
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | settlement_records |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/settlement_records.json |
+| 说明 | 结账/结算记录 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 结账记录主键 ID（订单结算 ID） |
+| 2 | tenantid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 3 | siteid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 4 | sitename | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 5 | balanceamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 6 | cardamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 7 | cashamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 8 | couponamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 9 | createtime | TIMESTAMPTZ | YES | 时间字段，用于记录业务时间点/发生时间 |
+| 10 | memberid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 11 | membername | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 12 | tenantmembercardid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 13 | membercardtypename | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 14 | memberphone | TEXT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 15 | tableid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 16 | consumemoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 17 | onlineamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 18 | operatorid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 19 | operatorname | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 20 | revokeorderid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 21 | revokeordername | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 22 | revoketime | TIMESTAMPTZ | YES | 时间字段，用于记录业务时间点/发生时间 |
+| 23 | payamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 24 | pointamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 25 | refundamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 26 | settlename | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 27 | settlerelateid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 28 | settlestatus | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 29 | settletype | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 30 | paytime | TIMESTAMPTZ | YES | 时间字段，用于记录业务时间点/发生时间 |
+| 31 | roundingamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 32 | paymentmethod | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 33 | adjustamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 34 | assistantcxmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 35 | assistantpdmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 36 | couponsaleamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 37 | memberdiscountamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 38 | tablechargemoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 39 | goodsmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 40 | realgoodsmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 41 | servicemoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 42 | prepaymoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 43 | salesmanname | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 44 | orderremark | TEXT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 45 | salesmanuserid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 46 | canberevoked | BOOLEAN | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 47 | pointdiscountprice | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 48 | pointdiscountcost | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 49 | activitydiscount | NUMERIC(18,2) | YES | 数量/时长字段，用于统计与计量 |
+| 50 | serialnumber | BIGINT | YES | 数量/时长字段，用于统计与计量 |
+| 51 | assistantmanualdiscount | NUMERIC(18,2) | YES | 数量/时长字段，用于统计与计量 |
+| 52 | allcoupondiscount | NUMERIC(18,2) | YES | 数量/时长字段，用于统计与计量 |
+| 53 | goodspromotionmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 54 | assistantpromotionmoney | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 55 | isusecoupon | BOOLEAN | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 56 | isusediscount | BOOLEAN | YES | 数量/时长字段，用于统计与计量 |
+| 57 | isactivity | BOOLEAN | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 58 | isbindmember | BOOLEAN | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 59 | isfirst | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 60 | rechargecardamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 61 | giftcardamount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 62 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 63 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 64 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 65 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 66 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 67 | electricityadjustmoney | NUMERIC(18,2) | YES | 电费调整金额 |
+| 68 | electricitymoney | NUMERIC(18,2) | YES | 电费金额 |
+| 69 | mervousalesamount | NUMERIC(18,2) | YES | 商户券销售额 |
+| 70 | plcouponsaleamount | NUMERIC(18,2) | YES | 平台券销售额 |
+| 71 | realelectricitymoney | NUMERIC(18,2) | YES | 实际电费金额 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.settlement_records
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.settlement_records
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/settlement_records.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_settlement_ticket_details.md

@@ -0,0 +1,94 @@
+# settlement_ticket_details 结算小票明细
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | settlement_ticket_details |
+| 主键 | ordersettleid, content_hash |
+| 数据来源 | export/test-json-doc/settlement_ticket_details.json |
+| 说明 | 结算小票明细 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | ordersettleid | BIGINT | NO | （待补充） |
+| 2 | actualpayment | NUMERIC(18,2) | YES | （待补充） |
+| 3 | adjustamount | NUMERIC(18,2) | YES | （待补充） |
+| 4 | assistantmanualdiscount | NUMERIC(18,2) | YES | （待补充） |
+| 5 | balanceamount | NUMERIC(18,2) | YES | （待补充） |
+| 6 | cashiername | TEXT | YES | （待补充） |
+| 7 | consumemoney | NUMERIC(18,2) | YES | （待补充） |
+| 8 | couponamount | NUMERIC(18,2) | YES | （待补充） |
+| 9 | deliveryaddress | TEXT | YES | （待补充） |
+| 10 | deliveryfee | NUMERIC(18,2) | YES | （待补充） |
+| 11 | ledgeramount | NUMERIC(18,2) | YES | （待补充） |
+| 12 | memberdeductamount | NUMERIC(18,2) | YES | （待补充） |
+| 13 | memberofferamount | NUMERIC(18,2) | YES | （待补充） |
+| 14 | onlinereturnamount | NUMERIC(18,2) | YES | （待补充） |
+| 15 | orderremark | TEXT | YES | （待补充） |
+| 16 | ordersettlenumber | BIGINT | YES | （待补充） |
+| 17 | paymemberbalance | NUMERIC(18,2) | YES | （待补充） |
+| 18 | paytime | TIMESTAMP | YES | （待补充） |
+| 19 | paymentmethod | INTEGER | YES | （待补充） |
+| 20 | pointdiscountcost | NUMERIC(18,2) | YES | （待补充） |
+| 21 | pointdiscountprice | NUMERIC(18,2) | YES | （待补充） |
+| 22 | prepaymoney | NUMERIC(18,2) | YES | （待补充） |
+| 23 | refundamount | NUMERIC(18,2) | YES | （待补充） |
+| 24 | returngoodsamount | NUMERIC(18,2) | YES | （待补充） |
+| 25 | rewardname | TEXT | YES | （待补充） |
+| 26 | settletype | TEXT | YES | （待补充） |
+| 27 | siteaddress | TEXT | YES | （待补充） |
+| 28 | sitebusinesstel | TEXT | YES | （待补充） |
+| 29 | siteid | BIGINT | YES | （待补充） |
+| 30 | sitename | TEXT | YES | （待补充） |
+| 31 | tenantid | BIGINT | YES | （待补充） |
+| 32 | tenantname | TEXT | YES | （待补充） |
+| 33 | ticketcustomcontent | TEXT | YES | （待补充） |
+| 34 | ticketremark | TEXT | YES | （待补充） |
+| 35 | vouchermoney | NUMERIC(18,2) | YES | （待补充） |
+| 36 | memberprofile | JSONB | YES | （待补充） |
+| 37 | orderitem | JSONB | YES | （待补充） |
+| 38 | tenantmembercardlogs | JSONB | YES | （待补充） |
+| 39 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 40 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 41 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 42 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 43 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.settlement_ticket_details
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.settlement_ticket_details
+WHERE ordersettleid = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/settlement_ticket_details.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_site_tables_master.md

@@ -0,0 +1,82 @@
+# site_tables_master 门店台桌主表
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | site_tables_master |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/site_tables_master.json |
+| 说明 | 门店桌台主数据 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 台桌主键 ID |
+| 2 | site_id | BIGINT | YES | 门店 ID |
+| 3 | sitename | TEXT | YES | （待补充） |
+| 4 | appletQrCodeUrl | TEXT | YES | （待补充） |
+| 5 | areaname | TEXT | YES | （待补充） |
+| 6 | audit_status | INTEGER | YES | 当前值：全部为 2 |
+| 7 | charge_free | INTEGER | YES | 当前值：全部为 0 |
+| 8 | create_time | TIMESTAMP | YES | 台桌配置的创建时间或最近一次创建/复制时间 |
+| 9 | delay_lights_time | INTEGER | YES | 台灯熄灭延迟时间（单位多半是秒或分钟），用于结账后延时关灯 |
+| 10 | is_online_reservation | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 11 | is_rest_area | INTEGER | YES | 当前值：全部为 0 |
+| 12 | light_status | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 13 | only_allow_groupon | INTEGER | YES | 小程序二维码 URL |
+| 14 | order_delay_time | INTEGER | YES | 订单层面允许的“自动延时时长”（例如到点后自动延长多少时间继续计费） |
+| 15 | self_table | INTEGER | YES | 当前值：全部为 1 |
+| 16 | show_status | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 17 | site_table_area_id | BIGINT | YES | 门店维度的“台桌区域 ID” |
+| 18 | tablestatusname | TEXT | YES | （待补充） |
+| 19 | table_cloth_use_cycle | INTEGER | YES | （待补充） |
+| 20 | table_cloth_use_time | TIMESTAMP | YES | 时间字段，用于记录业务时间点/发生时间 |
+| 21 | table_name | TEXT | YES | 台号/台名称，用于前台操作界面展示，也出现在小票和各种流水中的 ledger_name 或 tableName 字段 |
+| 22 | table_price | NUMERIC(18,2) | YES | 设计上应为“台的基础单价”字段（例如按小时或按局单价） |
+| 23 | table_status | INTEGER | YES | 台当前运行状态，真实反映某一时刻台的占用/暂停情况 |
+| 24 | temporary_light_second | INTEGER | YES | 临时点灯时长（秒），例如手动临时开灯一段时间 |
+| 25 | virtual_table | INTEGER | YES | 当前值：全部为 0 |
+| 26 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 27 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 28 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 29 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 30 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 31 | order_id | BIGINT | YES | 订单ID |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.site_tables_master
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.site_tables_master
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/site_tables_master.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_stock_goods_category_tree.md

@@ -0,0 +1,67 @@
+# stock_goods_category_tree 库存商品分类树
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | stock_goods_category_tree |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/stock_goods_category_tree.json |
+| 说明 | 商品分类树 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 分类节点主键 ID（在商品分类维度中的唯一标识） |
+| 2 | tenant_id | BIGINT | YES | 租户 ID（品牌/商户 ID） |
+| 3 | category_name | TEXT | YES | 分类名称（实际业务分类名称） |
+| 4 | alias_name | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 5 | pid | BIGINT | YES | 父级分类 ID |
+| 6 | business_name | TEXT | YES | 业务大类名称 |
+| 7 | tenant_goods_business_id | BIGINT | YES | 业务大类 ID |
+| 8 | open_salesman | INTEGER | YES | 是否启用“营业员”或“导购提成”相关的功能开关 |
+| 9 | categoryboxes | JSONB | YES | （待补充） |
+| 10 | sort | INTEGER | YES | 分类的排序序号，用于前端展示顺序的控制 |
+| 11 | is_warehousing | INTEGER | YES | 本文件可视为“所有参与库存管理的商品分类清单”，因此均为 1 |
+| 12 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 13 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 14 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 15 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 16 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.stock_goods_category_tree
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.stock_goods_category_tree
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/stock_goods_category_tree.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_store_goods_master.md

@@ -0,0 +1,103 @@
+# store_goods_master 门店商品主表
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | store_goods_master |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/store_goods_master.json |
+| 说明 | 门店商品主数据 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 门店商品 ID，门店维度的商品主键 |
+| 2 | tenant_id | BIGINT | YES | 租户/品牌 ID |
+| 3 | site_id | BIGINT | YES | 门店 ID |
+| 4 | sitename | TEXT | YES | （待补充） |
+| 5 | tenant_goods_id | BIGINT | YES | 租户/品牌维度的商品 ID，相当于“全局商品 ID” |
+| 6 | goods_name | TEXT | YES | 商品名称，例如“合味道泡面”“地道肠”“麻将房茶位费”等 |
+| 7 | goods_bar_code | TEXT | YES | 商品条形码（如 EAN-13 编码），用于扫码销售 |
+| 8 | goods_category_id | BIGINT | YES | 商品一级分类 ID |
+| 9 | goods_second_category_id | BIGINT | YES | 商品二级分类 ID |
+| 10 | onecategoryname | TEXT | YES | （待补充） |
+| 11 | twocategoryname | TEXT | YES | （待补充） |
+| 12 | unit | TEXT | YES | 商品计量单位（销售单位） |
+| 13 | sale_price | NUMERIC(18,4) | YES | 商品标准销售价（挂牌价），单位为元 |
+| 14 | cost_price | NUMERIC(18,4) | YES | 商品成本价（单件成本） |
+| 15 | cost_price_type | INTEGER | YES | 1 代表使用“固定成本价”（手工维护的 cost_price），provisional_total_cost 按“数量 × cost_price”算 |
+| 16 | min_discount_price | NUMERIC(18,4) | YES | 最低允许成交价（限价） |
+| 17 | safe_stock | NUMERIC(18,4) | YES | 安全库存量（阈值），低于该值时系统可以提示补货 |
+| 18 | stock | NUMERIC(18,4) | YES | 当前可用库存数量（以 unit 为单位） |
+| 19 | stock_a | NUMERIC(18,4) | YES | （待补充） |
+| 20 | sale_num | NUMERIC(18,4) | YES | 在当前统计口径下的销售数量（总销量，单位同 unit） |
+| 21 | total_purchase_cost | NUMERIC(18,4) | YES | 总采购成本，单位为元 |
+| 22 | total_sales | NUMERIC(18,4) | YES | 累计销售数量 |
+| 23 | average_monthly_sales | NUMERIC(18,4) | YES | 平均月销量（件/月），根据某个统计周期内的销售数据折算而来 |
+| 24 | batch_stock_quantity | NUMERIC(18,2) | YES | 当前“批次”的库存数量（主单位） |
+| 25 | days_available | INTEGER | YES | 商品“在架天数”或“可售天数”，大致等于当前时间减去首次上架时间 |
+| 26 | provisional_total_cost | NUMERIC(18,2) | YES | 暂估总成本，单位为元 |
+| 27 | enable_status | INTEGER | YES | 控制商品档案是否参与任何业务（库存、销售等） |
+| 28 | audit_status | INTEGER | YES | 观察值：全部为 2 |
+| 29 | goods_state | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 30 | is_delete | INTEGER | YES | 逻辑删除标志 |
+| 31 | is_warehousing | INTEGER | YES | 是否纳入库存管理 |
+| 32 | able_discount | INTEGER | YES | 是否允许参与折扣 |
+| 33 | able_site_transfer | INTEGER | YES | 表示是否允许跨门店调拨或跨站点共享库存 |
+| 34 | forbid_sell_status | INTEGER | YES | 观察值：全部为 1 |
+| 35 | freeze | INTEGER | YES | （待补充） |
+| 36 | send_state | INTEGER | YES | 观察值：全部为 1 |
+| 37 | custom_label_type | INTEGER | YES | 自定义标签类型 |
+| 38 | option_required | INTEGER | YES | 是否需要在销售时选择规格/选项 |
+| 39 | sale_channel | INTEGER | YES | 销售渠道类型 |
+| 40 | sort | INTEGER | YES | 排序权重，用于前端商品列表展示时的排版顺序，数值越小/越大哪个优先，具体规则看系统设定（一般是数值越小排序越靠前） |
+| 41 | remark | TEXT | YES | 商品备注（可以写口味说明、供应商、注意事项等） |
+| 42 | pinyin_initial | TEXT | YES | 商品名称的拼音首字母缩写，有时多个别名用逗号分隔 |
+| 43 | goods_cover | TEXT | YES | 商品图片 URL（如 OSS 对象存储地址），用于前端展示商品图片 |
+| 44 | create_time | TIMESTAMP | YES | 门店商品档案创建时间（商品在门店建立档案的时间点） |
+| 45 | update_time | TIMESTAMP | YES | 最后一次修改该商品档案的时间（包括价格调整、状态变更等） |
+| 46 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 47 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 48 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 49 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 50 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 51 | commodity_code | TEXT | YES | 商品编码 |
+| 52 | not_sale | INTEGER | YES | （待补充） |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.store_goods_master
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.store_goods_master
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/store_goods_master.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_store_goods_sales_records.md

@@ -0,0 +1,107 @@
+# store_goods_sales_records 门店商品销售记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | store_goods_sales_records |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/store_goods_sales_records.json |
+| 说明 | 门店商品销售流水 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 本条「门店销售流水」记录的主键 ID |
+| 2 | tenant_id | BIGINT | YES | 租户/品牌 ID |
+| 3 | site_id | BIGINT | YES | 门店 ID（系统主键） |
+| 4 | siteid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 5 | sitename | TEXT | YES | 名称字段，用于展示与辅助识别 |
+| 6 | site_goods_id | BIGINT | YES | 门店商品 ID |
+| 7 | tenant_goods_id | BIGINT | YES | 租户（品牌）级商品 ID（全局商品 ID） |
+| 8 | order_settle_id | BIGINT | YES | 订单结算 ID（结账单主键） |
+| 9 | order_trade_no | TEXT | YES | 订单交易号（业务单号） |
+| 10 | order_goods_id | BIGINT | YES | 订单商品明细 ID（订单内部的商品行主键） |
+| 11 | ordergoodsid | BIGINT | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 12 | order_pay_id | BIGINT | YES | 关联支付记录的 ID |
+| 13 | order_coupon_id | BIGINT | YES | 订单级优惠券 ID |
+| 14 | ledger_name | TEXT | YES | 销售项目名称（商品名称），例如 “哇哈哈矿泉水”“地道肠”“东方树叶”等 |
+| 15 | ledger_group_name | TEXT | YES | 销售项目所属的「门店内部分组名称」，类似前台菜单分组或大类标签 |
+| 16 | ledger_amount | NUMERIC(18,2) | YES | 原始应收金额，公式上接近 ledger_unit_price × ledger_count |
+| 17 | ledger_count | NUMERIC(18,4) | YES | 销售数量（以 unit 为单位，unit 字段在门店商品档案中） |
+| 18 | ledger_unit_price | NUMERIC(18,4) | YES | 商品在该次销售中的「结算单价」（元/单位） |
+| 19 | ledger_status | INTEGER | YES | 销售流水状态 |
+| 20 | discount_money | NUMERIC(18,2) | YES | 本条销售明细的「价格优惠金额」，即原价部分被减免掉的金额 |
+| 21 | discount_price | NUMERIC(18,2) | YES | 折后单价（元/单位） |
+| 22 | coupon_deduct_money | NUMERIC(18,2) | YES | 被优惠券 / 团购券直接抵扣到这条商品明细上的金额 |
+| 23 | member_discount_amount | NUMERIC(18,2) | YES | 由会员身份（会员折扣）针对这一行商品产生的优惠金额 |
+| 24 | option_coupon_deduct_money | NUMERIC(18,2) | YES | 由优惠券抵扣“选项价格”的金额 |
+| 25 | option_member_discount_money | NUMERIC(18,2) | YES | 由会员折扣作用在“选项价格”上的优惠金额 |
+| 26 | point_discount_money | NUMERIC(18,2) | YES | 由积分抵扣的金额（顾客兑换积分抵现金额） |
+| 27 | point_discount_money_cost | NUMERIC(18,2) | YES | 积分抵扣对应的“成本金额”（后台核算用），例如按积分成本来计提费用 |
+| 28 | real_goods_money | NUMERIC(18,2) | YES | 商品实际入账金额（考虑折扣、可能还会考虑其它抵扣后的实际销售金额） |
+| 29 | cost_money | NUMERIC(18,2) | YES | 本条销售对应的成本金额（以元计） |
+| 30 | push_money | NUMERIC(18,2) | YES | 本条销售对应的提成金额（给营业员/促销员的提成） |
+| 31 | sales_type | INTEGER | YES | 销售类型 |
+| 32 | is_single_order | INTEGER | YES | 是否单独订单标识 |
+| 33 | is_delete | INTEGER | YES | 逻辑删除标志 |
+| 34 | goods_remark | TEXT | YES | 商品备注/口味说明/特殊说明 |
+| 35 | option_price | NUMERIC(18,2) | YES | 商品选项（规格/加料）的附加价格 |
+| 36 | option_value_name | TEXT | YES | 商品选项名称（如规格、口味：大杯/小杯，不加冰等） |
+| 37 | member_coupon_id | BIGINT | YES | 会员券 ID（比如会员专享优惠券） |
+| 38 | package_coupon_id | BIGINT | YES | 套餐券 ID |
+| 39 | sales_man_org_id | BIGINT | YES | 营业员所属组织/部门 ID |
+| 40 | salesman_name | TEXT | YES | 营业员姓名（如果有为具体销售员记业绩，则在此填姓名） |
+| 41 | salesman_role_id | BIGINT | YES | 营业员的系统角色 ID（例如某个角色代码表示“销售员”） |
+| 42 | salesman_user_id | BIGINT | YES | 营业员用户 ID（系统账号 ID） |
+| 43 | operator_id | BIGINT | YES | 操作员 ID（录入这笔销售的员工） |
+| 44 | operator_name | TEXT | YES | 操作员姓名，文字冗余 |
+| 45 | opensalesman | TEXT | YES | （待补充） |
+| 46 | returns_number | INTEGER | YES | 退货数量（如果这条明细做了退货，会记录退货数量） |
+| 47 | site_table_id | BIGINT | YES | 球台 ID |
+| 48 | tenant_goods_business_id | BIGINT | YES | 租户级商品「业务大类」ID（例如“零食类”“酒水类”等更高维度） |
+| 49 | tenant_goods_category_id | BIGINT | YES | 租户级商品一级分类 ID |
+| 50 | create_time | TIMESTAMP | YES | 销售记录创建时间，通常就是结账时间或录入时间 |
+| 51 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 52 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 53 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 54 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 55 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 56 | coupon_share_money | NUMERIC(18,2) | YES | 优惠券分摊金额 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.store_goods_sales_records
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.store_goods_sales_records
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/store_goods_sales_records.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_table_fee_discount_records.md

@@ -0,0 +1,84 @@
+# table_fee_discount_records 台费折扣/调整记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | table_fee_discount_records |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/table_fee_discount_records.json |
+| 说明 | 台费折扣记录 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 台费打折 / 调整流水主键 ID |
+| 2 | tenant_id | BIGINT | YES | 租户/品牌 ID |
+| 3 | site_id | BIGINT | YES | 门店 ID，本批数据全部为同一家门店（朗朗桌球） |
+| 4 | siteprofile | JSONB | YES | （待补充） |
+| 5 | site_table_id | BIGINT | YES | 台桌 ID |
+| 6 | tableprofile | JSONB | YES | （待补充） |
+| 7 | tenant_table_area_id | BIGINT | YES | 租户维度的“台桌区域 ID” |
+| 8 | adjust_type | INTEGER | YES | 文件名是“台费打折”，字段名为“调整类型”，当前所有记录都是 1，即“台费打折/台费减免”这一种调整类型 |
+| 9 | ledger_amount | NUMERIC(18,2) | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 10 | ledger_count | NUMERIC(18,4) | YES | 这里不是“秒数”，而是“调整次数/条数”的量化，目前固定为 1，表示“一次调账事件” |
+| 11 | ledger_name | TEXT | YES | 设计上应该用于记录“调账项目名称”或“打折原因描述”（例如某种优惠规则名称），但当前门店并未使用该字段 |
+| 12 | ledger_status | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 13 | applicant_id | BIGINT | YES | 打折/调账申请人 ID |
+| 14 | applicant_name | TEXT | YES | 申请人姓名（带角色描述），为 applicant_id 的冗余显示字段 |
+| 15 | operator_id | BIGINT | YES | 实际执行调账操作的操作员 ID |
+| 16 | operator_name | TEXT | YES | 操作员姓名 |
+| 17 | order_settle_id | BIGINT | YES | 结算单/小票 ID |
+| 18 | order_trade_no | TEXT | YES | 订单交易号 |
+| 19 | is_delete | INTEGER | YES | 逻辑删除标记（0=否，1=是） |
+| 20 | create_time | TIMESTAMP | YES | 台费调整记录的创建时间，即打折操作被执行的时间戳 |
+| 21 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 22 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 23 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 24 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 25 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 26 | area_type_id | BIGINT | YES | 区域类型ID |
+| 27 | charge_free | BOOLEAN | YES | 是否免费 |
+| 28 | site_table_area_id | BIGINT | YES | 门店台区ID |
+| 29 | site_table_area_name | TEXT | YES | 门店台区名称 |
+| 30 | sitename | TEXT | YES | 门店名称 |
+| 31 | table_name | TEXT | YES | 台桌名称 |
+| 32 | table_price | NUMERIC(18,2) | YES | 台桌价格 |
+| 33 | tenant_name | TEXT | YES | 租户名称 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.table_fee_discount_records
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.table_fee_discount_records
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/table_fee_discount_records.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_table_fee_transactions.md

@@ -0,0 +1,98 @@
+# table_fee_transactions 台费交易记录
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | table_fee_transactions |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/table_fee_transactions.json |
+| 说明 | 台费流水 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 台费流水记录主键（事实表主键） |
+| 2 | tenant_id | BIGINT | YES | 租户/品牌 ID |
+| 3 | site_id | BIGINT | YES | 门店 ID，本次数据全部来自同一门店（朗朗桌球） |
+| 4 | siteprofile | JSONB | YES | （待补充） |
+| 5 | site_table_id | BIGINT | YES | 球台 ID |
+| 6 | site_table_area_id | BIGINT | YES | 门店内“台桌区域” ID（站在门店物理布局的角度） |
+| 7 | site_table_area_name | TEXT | YES | 台桌区域的名称，用于门店表现和区域统计 |
+| 8 | tenant_table_area_id | BIGINT | YES | 租户维度的台桌区域 ID（品牌层面的同一类区域） |
+| 9 | order_trade_no | TEXT | YES | 订单交易号，是整笔订单的主编号 |
+| 10 | order_pay_id | BIGINT | YES | 订单支付记录 ID |
+| 11 | order_settle_id | BIGINT | YES | 结算单号/结账 ID，对应一次结账操作 |
+| 12 | ledger_name | TEXT | YES | 台号名称，实际展示给员工/顾客看的桌台编号 |
+| 13 | ledger_amount | NUMERIC(18,2) | YES | 按单价与计费时长计算出的原始应收台费金额 |
+| 14 | ledger_count | NUMERIC(18,4) | YES | 台账记录的计费秒数，计费用秒数（应收时长） |
+| 15 | ledger_unit_price | NUMERIC(18,4) | YES | 台费结算时设置的 每小时单价/计费单价 |
+| 16 | ledger_status | INTEGER | YES | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| 17 | ledger_start_time | TIMESTAMP | YES | 台账上的计费起始时间 |
+| 18 | ledger_end_time | TIMESTAMP | YES | 台账上的计费结束时间 |
+| 19 | start_use_time | TIMESTAMP | YES | 台开始使用的时间（实际开台时间） |
+| 20 | last_use_time | TIMESTAMP | YES | 最后使用/操作时间 |
+| 21 | real_table_use_seconds | INTEGER | YES | 实际使用的总秒数（系统真实统计的使用时长） |
+| 22 | real_table_charge_money | NUMERIC(18,2) | YES | 台费中实际向顾客收取的金额（现金/实付维度，未含券方承担或内部调账的那一部分） |
+| 23 | add_clock_seconds | INTEGER | YES | 加钟秒数，在原有使用基础上追加的时长 |
+| 24 | adjust_amount | NUMERIC(18,2) | YES | 调整金额/调账金额，用于将台费金额转移或冲减到其它项目，或手工调整 |
+| 25 | coupon_promotion_amount | NUMERIC(18,2) | YES | 由优惠券/活动/团购（平台/门店促销）承担的优惠金额，直接抵扣在台费上 |
+| 26 | member_discount_amount | NUMERIC(18,2) | YES | 由会员权益产生的优惠金额，例如会员折扣、会员价等 |
+| 27 | used_card_amount | NUMERIC(18,2) | YES | 由储值卡、次卡等“卡内余额”抵扣的金额 |
+| 28 | mgmt_fee | NUMERIC(18,2) | YES | 管理费字段，用于未来支持“台费附加管理费/服务费”的功能 |
+| 29 | service_money | NUMERIC(18,2) | YES | 门店用于记录“服务费/成本/分成金额”的字段，类似助教流水里的 service_money |
+| 30 | fee_total | NUMERIC(18,2) | YES | 各种附加费用（如管理费、服务费）合计值 |
+| 31 | is_single_order | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 32 | is_delete | INTEGER | YES | 逻辑删除标记（0=否，1=是） |
+| 33 | member_id | BIGINT | YES | 门店/租户内的会员 ID |
+| 34 | operator_id | BIGINT | YES | 操作员 ID，负责开台/结账的员工账号 ID |
+| 35 | operator_name | TEXT | YES | 操作员姓名（冗余字段），便于直接阅读，不必再联表员工档案 |
+| 36 | salesman_name | TEXT | YES | 业务员/营业员姓名，如果台费有单独提成员工，这里记录归属人 |
+| 37 | salesman_org_id | BIGINT | YES | 营业员所属机构/部门 ID |
+| 38 | salesman_user_id | BIGINT | YES | 营业员的用户 ID（与 salesman_name 搭配） |
+| 39 | create_time | TIMESTAMP | YES | 这条台费流水记录的创建时间，通常接近结账时间 |
+| 40 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 41 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 42 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 43 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 44 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 45 | activity_discount_amount | NUMERIC(18,2) | YES | 活动折扣金额 |
+| 46 | order_consumption_type | INTEGER | YES | 订单消费类型 |
+| 47 | real_service_money | NUMERIC(18,2) | YES | 实际服务费金额 |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.table_fee_transactions
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.table_fee_transactions
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/table_fee_transactions.json |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_tenant_goods_master.md

@@ -0,0 +1,88 @@
+# tenant_goods_master 租户商品主表
+
+> 生成时间：2026-02-14
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | tenant_goods_master |
+| 主键 | id, content_hash |
+| 数据来源 | export/test-json-doc/tenant_goods_master.json |
+| 说明 | 租户商品主数据 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 商品档案主键 ID，唯一标识一条商品 |
+| 2 | tenant_id | BIGINT | YES | 租户/品牌 ID |
+| 3 | goods_name | TEXT | YES | 商品名称（前台展示名称） |
+| 4 | goods_bar_code | TEXT | YES | 商品条码（EAN 等），目前未维护 |
+| 5 | goods_category_id | BIGINT | YES | 商品一级分类 ID |
+| 6 | goods_second_category_id | BIGINT | YES | 商品二级分类 ID |
+| 7 | categoryname | TEXT | YES | （待补充） |
+| 8 | unit | TEXT | YES | 计量单位 |
+| 9 | goods_number | TEXT | YES | 商品内部编码（自定义货号/系统货号） |
+| 10 | out_goods_id | TEXT | YES | 外部系统商品 ID（对接第三方平台使用，如外卖、线上商城等） |
+| 11 | goods_state | INTEGER | YES | 商品状态（上架/下架等） |
+| 12 | sale_channel | INTEGER | YES | 销售渠道类型，如“门店堂食/线下零售/线上小程序”等的一种编码 |
+| 13 | able_discount | INTEGER | YES | 是否允许参与折扣/打折 |
+| 14 | able_site_transfer | INTEGER | YES | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| 15 | is_delete | INTEGER | YES | 逻辑删除标志 |
+| 16 | is_warehousing | INTEGER | YES | 是否启用库存管理 |
+| 17 | isinsite | INTEGER | YES | （待补充） |
+| 18 | cost_price | NUMERIC(18,4) | YES | 成本价格 |
+| 19 | cost_price_type | INTEGER | YES | 金额字段，用于计费/结算/分摊等金额计算 |
+| 20 | market_price | NUMERIC(18,4) | YES | 商品标价 / 售价（标准销售单价） |
+| 21 | min_discount_price | NUMERIC(18,4) | YES | 该商品允许售卖的最低价格（底价） |
+| 22 | common_sale_royalty | NUMERIC(18,4) | YES | 普通销售提成比例或提成金额的配置字段 |
+| 23 | point_sale_royalty | NUMERIC(18,4) | YES | 积分销售提成/积分赠送规则相关配置 |
+| 24 | pinyin_initial | TEXT | YES | 拼音首字母/助记码 |
+| 25 | commoditycode | TEXT | YES | （待补充） |
+| 26 | commodity_code | TEXT | YES | 商品编码（通常为对外商品编码或条码） |
+| 27 | goods_cover | TEXT | YES | 商品封面图片 URL 地址 |
+| 28 | supplier_id | BIGINT | YES | 供应商 ID，用于关联到供应商档案 |
+| 29 | remark_name | TEXT | YES | 商品备注名/别名，通常用来配置简写或特殊显示名称 |
+| 30 | create_time | TIMESTAMP | YES | 商品档案创建时间 |
+| 31 | update_time | TIMESTAMP | YES | 商品档案最近一次修改时间 |
+| 32 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
+| 33 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
+| 34 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
+| 35 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
+| 36 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
+| 37 | not_sale | INTEGER | YES | （待补充） |
+
+## 使用说明
+
+```sql
+-- 查询最新入库的记录
+SELECT * FROM ods.tenant_goods_master
+ORDER BY fetched_at DESC
+LIMIT 10;
+```
+
+```sql
+-- 按业务主键查询某条记录的所有版本
+SELECT * FROM ods.tenant_goods_master
+WHERE id = <value>
+ORDER BY fetched_at DESC;
+```
+
+## ETL 元数据字段
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
+| source_file | TEXT | 原始导出文件名，用于数据追溯 |
+| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
+| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
+| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | export/test-json-doc/tenant_goods_master.json |

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetAbolitionAssistant_assistant_cancellation_records.md

@@ -0,0 +1,50 @@
+# 助教撤销记录（GetAbolitionAssistant） → assistant_cancellation_records 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `AssistantPerformance/GetAbolitionAssistant` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.assistant_cancellation_records` |
+| JSON 数据路径 | `data.abolitionAssistants` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 本表主键 ID，用于唯一标识一条记录 |
+| siteId | siteId | int→BIGINT（`parse_int`） | 门店 ID，即该废除记录所在门店 |
+| siteProfile | siteProfile | object→JSONB（原样存储） | 门店信息快照 |
+| assistantName | assistantName | string→TEXT（原样） | 助教姓名/对外展示名称 |
+| assistantAbolishAmount | assistantAbolishAmount | float→NUMERIC(18,2)（`parse_decimal`） | 与“助教废除”关联的金额字段 |
+| assistantOn | assistantOn | int→INT（`parse_int`） | 助教编号（工号/序号） |
+| pdChargeMinutes | pdChargeMinutes | int→INT（`parse_int`） | “已发生的计费时长（分钟）”，即这次助教服务在被废除前已经累计了多少分钟 |
+| tableAreaId | tableAreaId | int→BIGINT（`parse_int`） | 台桌所在区域 ID |
+| tableArea | tableArea | string→TEXT（原样） | 台桌所属区域名称 |
+| tableId | tableId | int→BIGINT（`parse_int`） | 球台/桌子的 ID |
+| tableName | tableName | string→TEXT（原样） | 台桌名称/编号，供人阅读 |
+| trashReason | trashReason | string→TEXT（原样） | 用于记录“废除原因”的文本描述，例如“顾客临时有事取消”“录入错误”“更换助教”等 |
+| createTime | createTime | string→TIMESTAMP（`parse_timestamp`） | 这条“助教废除记录”被创建的时间，即系统正式记录“废除”操作的时刻 |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`assistant_cancellation_records.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `AssistantPerformance/GetAbolitionAssistant` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetAllOrderSettleList_settlement_records.md

@@ -0,0 +1,102 @@
+# 结账记录（GetAllOrderSettleList） → settlement_records 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Site/GetAllOrderSettleList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.settlement_records` |
+| JSON 数据路径 | `data.settleList（外层含 siteProfile）` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 结账记录主键 ID（订单结算 ID） |
+| tenantid | tenantid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| siteid | siteid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| sitename | sitename | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| balanceamount | balanceamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| cardamount | cardamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| cashamount | cashamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| couponamount | couponamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| createtime | createtime | string→TIMESTAMP（`parse_timestamp`） | 时间字段，用于记录业务时间点/发生时间 |
+| memberid | memberid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| membername | membername | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| tenantmembercardid | tenantmembercardid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| membercardtypename | membercardtypename | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| memberphone | memberphone | string→TEXT（原样） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| tableid | tableid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| consumemoney | consumemoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| onlineamount | onlineamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| operatorid | operatorid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| operatorname | operatorname | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| revokeorderid | revokeorderid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| revokeordername | revokeordername | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| revoketime | revoketime | string→TIMESTAMP（`parse_timestamp`） | 时间字段，用于记录业务时间点/发生时间 |
+| payamount | payamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| pointamount | pointamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| refundamount | refundamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| settlename | settlename | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| settlerelateid | settlerelateid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| settlestatus | settlestatus | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| settletype | settletype | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| paytime | paytime | string→TIMESTAMP（`parse_timestamp`） | 时间字段，用于记录业务时间点/发生时间 |
+| roundingamount | roundingamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| paymentmethod | paymentmethod | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| adjustamount | adjustamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistantcxmoney | assistantcxmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistantpdmoney | assistantpdmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| couponsaleamount | couponsaleamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| memberdiscountamount | memberdiscountamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| tablechargemoney | tablechargemoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| goodsmoney | goodsmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| realgoodsmoney | realgoodsmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| servicemoney | servicemoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| prepaymoney | prepaymoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| salesmanname | salesmanname | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| orderremark | orderremark | string→TEXT（原样） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| salesmanuserid | salesmanuserid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| canberevoked | canberevoked | bool→BOOLEAN | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| pointdiscountprice | pointdiscountprice | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| pointdiscountcost | pointdiscountcost | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| activitydiscount | activitydiscount | float→NUMERIC(18,2)（`parse_decimal`） | 数量/时长字段，用于统计与计量 |
+| serialnumber | serialnumber | int→BIGINT（`parse_int`） | 数量/时长字段，用于统计与计量 |
+| assistantmanualdiscount | assistantmanualdiscount | float→NUMERIC(18,2)（`parse_decimal`） | 数量/时长字段，用于统计与计量 |
+| allcoupondiscount | allcoupondiscount | float→NUMERIC(18,2)（`parse_decimal`） | 数量/时长字段，用于统计与计量 |
+| goodspromotionmoney | goodspromotionmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistantpromotionmoney | assistantpromotionmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| isusecoupon | isusecoupon | bool→BOOLEAN | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| isusediscount | isusediscount | bool→BOOLEAN | 数量/时长字段，用于统计与计量 |
+| isactivity | isactivity | bool→BOOLEAN | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| isbindmember | isbindmember | bool→BOOLEAN | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| isfirst | isfirst | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| rechargecardamount | rechargecardamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| giftcardamount | giftcardamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| electricityadjustmoney | electricityadjustmoney | float→NUMERIC(18,2)（`parse_decimal`） | 电费调整金额（新增字段） |
+| electricitymoney | electricitymoney | float→NUMERIC(18,2)（`parse_decimal`） | 电费金额（新增字段） |
+| mervousalesamount | mervousalesamount | float→NUMERIC(18,2)（`parse_decimal`） | 商户代金券销售金额（新增字段） |
+| plcouponsaleamount | plcouponsaleamount | float→NUMERIC(18,2)（`parse_decimal`） | 平台券销售金额（新增字段） |
+| realelectricitymoney | realelectricitymoney | float→NUMERIC(18,2)（`parse_decimal`） | 实际电费金额（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`settlement_records.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Site/GetAllOrderSettleList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetGoodsInventoryList_store_goods_master.md

@@ -0,0 +1,83 @@
+# 门店商品库存主数据（GetGoodsInventoryList） → store_goods_master 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `TenantGoods/GetGoodsInventoryList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.store_goods_master` |
+| JSON 数据路径 | `data.orderGoodsList` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 门店商品 ID，门店维度的商品主键 |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID |
+| siteName | siteName | string→TEXT（原样） | 门店名称，是对 site_id 的冗余展示，方便直接阅读，无需再去关联门店档案 |
+| tenant_goods_id | tenant_goods_id | int→BIGINT（`parse_int`） | 租户/品牌维度的商品 ID，相当于“全局商品 ID” |
+| goods_name | goods_name | string→TEXT（原样） | 商品名称，例如“合味道泡面”“地道肠”“麻将房茶位费”等 |
+| goods_bar_code | goods_bar_code | string→TEXT（原样） | 商品条形码（如 EAN-13 编码），用于扫码销售 |
+| goods_category_id | goods_category_id | int→BIGINT（`parse_int`） | 商品一级分类 ID |
+| goods_second_category_id | goods_second_category_id | int→BIGINT（`parse_int`） | 商品二级分类 ID |
+| oneCategoryName | oneCategoryName | string→TEXT（原样） | 一级分类名称，如“零食”“酒水”“服务费”等 |
+| twoCategoryName | twoCategoryName | string→TEXT（原样） | 二级分类名称，如“面”“洋酒”“纸巾”等 |
+| unit | unit | string→TEXT（原样） | 商品计量单位（销售单位） |
+| sale_price | sale_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 商品标准销售价（挂牌价），单位为元 |
+| cost_price | cost_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 商品成本价（单件成本） |
+| cost_price_type | cost_price_type | int→INT（`parse_int`） | 1 代表使用“固定成本价”（手工维护的 cost_price），provisional_total_cost 按“数量 × cost_price”算 |
+| min_discount_price | min_discount_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 最低允许成交价（限价） |
+| safe_stock | safe_stock | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 安全库存量（阈值），低于该值时系统可以提示补货 |
+| stock | stock | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 当前可用库存数量（以 unit 为单位） |
+| stock_A | stock_A | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 副单位库存数量 |
+| sale_num | sale_num | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 在当前统计口径下的销售数量（总销量，单位同 unit） |
+| total_purchase_cost | total_purchase_cost | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 总采购成本，单位为元 |
+| total_sales | total_sales | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 累计销售数量 |
+| average_monthly_sales | average_monthly_sales | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 平均月销量（件/月），根据某个统计周期内的销售数据折算而来 |
+| batch_stock_quantity | batch_stock_quantity | float→NUMERIC(18,2)（`parse_decimal`） | 当前“批次”的库存数量（主单位） |
+| days_available | days_available | int→INT（`parse_int`） | 商品“在架天数”或“可售天数”，大致等于当前时间减去首次上架时间 |
+| provisional_total_cost | provisional_total_cost | float→NUMERIC(18,2)（`parse_decimal`） | 暂估总成本，单位为元 |
+| enable_status | enable_status | int→INT（`parse_int`） | 控制商品档案是否参与任何业务（库存、销售等） |
+| audit_status | audit_status | int→INT（`parse_int`） | 观察值：全部为 2 |
+| goods_state | goods_state | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标志 |
+| is_warehousing | is_warehousing | int→INT（`parse_int`） | 是否纳入库存管理 |
+| able_discount | able_discount | int→INT（`parse_int`） | 是否允许参与折扣 |
+| able_site_transfer | able_site_transfer | int→INT（`parse_int`） | 表示是否允许跨门店调拨或跨站点共享库存 |
+| forbid_sell_status | forbid_sell_status | int→INT（`parse_int`） | 观察值：全部为 1 |
+| "freeze" | "freeze" | int→INT（`parse_int`） | 冻结状态（新增字段） |
+| send_state | send_state | int→INT（`parse_int`） | 观察值：全部为 1 |
+| custom_label_type | custom_label_type | int→INT（`parse_int`） | 自定义标签类型 |
+| option_required | option_required | int→INT（`parse_int`） | 是否需要在销售时选择规格/选项 |
+| sale_channel | sale_channel | int→INT（`parse_int`） | 销售渠道类型 |
+| sort | sort | int→INT（`parse_int`） | 排序权重，用于前端商品列表展示时的排版顺序，数值越小/越大哪个优先，具体规则看系统设定（一般是数值越小排序越靠前） |
+| remark | remark | string→TEXT（原样） | 商品备注（可以写口味说明、供应商、注意事项等） |
+| pinyin_initial | pinyin_initial | string→TEXT（原样） | 商品名称的拼音首字母缩写，有时多个别名用逗号分隔 |
+| goods_cover | goods_cover | string→TEXT（原样） | 商品图片 URL（如 OSS 对象存储地址），用于前端展示商品图片 |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 门店商品档案创建时间（商品在门店建立档案的时间点） |
+| update_time | update_time | string→TIMESTAMP（`parse_timestamp`） | 最后一次修改该商品档案的时间（包括价格调整、状态变更等） |
+| commodity_code | commodity_code | string→TEXT（原样） | 商品编码（新增字段） |
+| not_sale | not_sale | int→INT（`parse_int`） | 是否禁售（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`store_goods_master.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `TenantGoods/GetGoodsInventoryList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetGoodsSalesList_store_goods_sales_records.md

@@ -0,0 +1,87 @@
+# 门店商品销售记录（GetGoodsSalesList） → store_goods_sales_records 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `TenantGoods/GetGoodsSalesList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.store_goods_sales_records` |
+| JSON 数据路径 | `data.orderGoodsLedgers` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 本条「门店销售流水」记录的主键 ID |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID（系统主键） |
+| site_id | siteid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| siteName | sitename | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| site_goods_id | site_goods_id | int→BIGINT（`parse_int`） | 门店商品 ID |
+| tenant_goods_id | tenant_goods_id | int→BIGINT（`parse_int`） | 租户（品牌）级商品 ID（全局商品 ID） |
+| order_settle_id | order_settle_id | int→BIGINT（`parse_int`） | 订单结算 ID（结账单主键） |
+| order_trade_no | order_trade_no | string→TEXT（原样） | 订单交易号（业务单号） |
+| order_goods_id | order_goods_id | int→BIGINT（`parse_int`） | 订单商品明细 ID（订单内部的商品行主键） |
+| order_goods_id | ordergoodsid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| order_pay_id | order_pay_id | int→BIGINT（`parse_int`） | 关联支付记录的 ID |
+| order_coupon_id | order_coupon_id | int→BIGINT（`parse_int`） | 订单级优惠券 ID |
+| ledger_name | ledger_name | string→TEXT（原样） | 销售项目名称（商品名称），例如 “哇哈哈矿泉水”“地道肠”“东方树叶”等 |
+| ledger_group_name | ledger_group_name | string→TEXT（原样） | 销售项目所属的「门店内部分组名称」，类似前台菜单分组或大类标签 |
+| ledger_amount | ledger_amount | float→NUMERIC(18,2)（`parse_decimal`） | 原始应收金额，公式上接近 ledger_unit_price × ledger_count |
+| ledger_count | ledger_count | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 销售数量（以 unit 为单位，unit 字段在门店商品档案中） |
+| ledger_unit_price | ledger_unit_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 商品在该次销售中的「结算单价」（元/单位） |
+| ledger_status | ledger_status | int→INT（`parse_int`） | 销售流水状态 |
+| discount_money | discount_money | float→NUMERIC(18,2)（`parse_decimal`） | 本条销售明细的「价格优惠金额」，即原价部分被减免掉的金额 |
+| discount_price | discount_price | float→NUMERIC(18,2)（`parse_decimal`） | 折后单价（元/单位） |
+| coupon_deduct_money | coupon_deduct_money | float→NUMERIC(18,2)（`parse_decimal`） | 被优惠券 / 团购券直接抵扣到这条商品明细上的金额 |
+| member_discount_amount | member_discount_amount | float→NUMERIC(18,2)（`parse_decimal`） | 由会员身份（会员折扣）针对这一行商品产生的优惠金额 |
+| option_coupon_deduct_money | option_coupon_deduct_money | float→NUMERIC(18,2)（`parse_decimal`） | 由优惠券抵扣“选项价格”的金额 |
+| option_member_discount_money | option_member_discount_money | float→NUMERIC(18,2)（`parse_decimal`） | 由会员折扣作用在“选项价格”上的优惠金额 |
+| point_discount_money | point_discount_money | float→NUMERIC(18,2)（`parse_decimal`） | 由积分抵扣的金额（顾客兑换积分抵现金额） |
+| point_discount_money_cost | point_discount_money_cost | float→NUMERIC(18,2)（`parse_decimal`） | 积分抵扣对应的“成本金额”（后台核算用），例如按积分成本来计提费用 |
+| real_goods_money | real_goods_money | float→NUMERIC(18,2)（`parse_decimal`） | 商品实际入账金额（考虑折扣、可能还会考虑其它抵扣后的实际销售金额） |
+| cost_money | cost_money | float→NUMERIC(18,2)（`parse_decimal`） | 本条销售对应的成本金额（以元计） |
+| push_money | push_money | float→NUMERIC(18,2)（`parse_decimal`） | 本条销售对应的提成金额（给营业员/促销员的提成） |
+| sales_type | sales_type | int→INT（`parse_int`） | 销售类型 |
+| is_single_order | is_single_order | int→INT（`parse_int`） | 是否单独订单标识 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标志 |
+| goods_remark | goods_remark | string→TEXT（原样） | 商品备注/口味说明/特殊说明 |
+| option_price | option_price | float→NUMERIC(18,2)（`parse_decimal`） | 商品选项（规格/加料）的附加价格 |
+| option_value_name | option_value_name | string→TEXT（原样） | 商品选项名称（如规格、口味：大杯/小杯，不加冰等） |
+| member_coupon_id | member_coupon_id | int→BIGINT（`parse_int`） | 会员券 ID（比如会员专享优惠券） |
+| package_coupon_id | package_coupon_id | int→BIGINT（`parse_int`） | 套餐券 ID |
+| sales_man_org_id | sales_man_org_id | int→BIGINT（`parse_int`） | 营业员所属组织/部门 ID |
+| salesman_name | salesman_name | string→TEXT（原样） | 营业员姓名（如果有为具体销售员记业绩，则在此填姓名） |
+| salesman_role_id | salesman_role_id | int→BIGINT（`parse_int`） | 营业员的系统角色 ID（例如某个角色代码表示“销售员”） |
+| salesman_user_id | salesman_user_id | int→BIGINT（`parse_int`） | 营业员用户 ID（系统账号 ID） |
+| operator_id | operator_id | int→BIGINT（`parse_int`） | 操作员 ID（录入这笔销售的员工） |
+| operator_name | operator_name | string→TEXT（原样） | 操作员姓名，文字冗余 |
+| openSalesman | openSalesman | string→TEXT（原样） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| returns_number | returns_number | int→INT（`parse_int`） | 退货数量（如果这条明细做了退货，会记录退货数量） |
+| site_table_id | site_table_id | int→BIGINT（`parse_int`） | 球台 ID |
+| tenant_goods_business_id | tenant_goods_business_id | int→BIGINT（`parse_int`） | 租户级商品「业务大类」ID（例如“零食类”“酒水类”等更高维度） |
+| tenant_goods_category_id | tenant_goods_category_id | int→BIGINT（`parse_int`） | 租户级商品一级分类 ID |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 销售记录创建时间，通常就是结账时间或录入时间 |
+| coupon_share_money | coupon_share_money | float→NUMERIC(18,2)（`parse_decimal`） | 优惠券分摊金额（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`store_goods_sales_records.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `TenantGoods/GetGoodsSalesList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetGoodsStockReport_goods_stock_summary.md

@@ -0,0 +1,50 @@
+# 库存汇总报表（GetGoodsStockReport） → goods_stock_summary 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `TenantGoods/GetGoodsStockReport` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.goods_stock_summary` |
+| JSON 数据路径 | `$（平铺结构）` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| siteGoodsId | siteGoodsId | int→BIGINT（`parse_int`） | 门店商品 ID，本库存汇总表的主键，对应某个具体商品在本店的唯一标识 |
+| goodsName | goodsName | string→TEXT（原样） | 商品名称，冗余于门店商品档案的 goods_name |
+| goodsUnit | goodsUnit | string→TEXT（原样） | 商品的计量单位（售卖单位） |
+| goodsCategoryId | goodsCategoryId | int→BIGINT（`parse_int`） | 一级商品分类 ID |
+| goodsCategorySecondId | goodsCategorySecondId | int→BIGINT（`parse_int`） | 二级（次级）商品分类 ID，是 goodsCategoryId 的下级分类 |
+| categoryName | categoryName | string→TEXT（原样） | 一级分类名称，属于冗余字段，用于直接展示 |
+| rangeStartStock | rangeStartStock | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间 起始时刻 的库存数量（期初库存） |
+| rangeEndStock | rangeEndStock | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间 结束时刻 的库存数量（期末库存） |
+| rangeIn | rangeIn | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间内的 入库数量汇总（正值），包括采购入库、调拨入库等 |
+| rangeOut | rangeOut | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间内的 出库数量汇总，以 负数 表示从库存扣减（出库/销售） |
+| rangeSale | rangeSale | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间内，该商品的 销售数量汇总（售出多少“包/瓶/份”等） |
+| rangeSaleMoney | rangeSaleMoney | float→NUMERIC(18,2)（`parse_decimal`） | 查询区间内，该商品销售的 金额小计（按商品维度汇总） |
+| rangeInventory | rangeInventory | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间内的 盘点调整净变动量（盘盈–盘亏） |
+| currentStock | currentStock | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 导出时刻的实时库存数量 |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`goods_stock_summary.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `TenantGoods/GetGoodsStockReport` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetMemberCardBalanceChange_member_balance_changes.md

@@ -0,0 +1,64 @@
+# 会员余额变动（GetMemberCardBalanceChange） → member_balance_changes 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `MemberProfile/GetMemberCardBalanceChange` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.member_balance_changes` |
+| JSON 数据路径 | `data.tenantMemberCardLogs` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/商户 ID，本数据中是固定值（同一品牌/商户） |
+| site_id | site_id | int→BIGINT（`parse_int`） | 非 0：记录所属的具体门店 ID（与其他 JSON 内的 site_id 一致） |
+| register_site_id | register_site_id | int→BIGINT（`parse_int`） | 会员卡的“注册门店 ID”，即办卡所在门店 |
+| registerSiteName | registerSiteName | string→TEXT（原样） | 卡片的注册门店名称（办卡地点），和 register_site_id 配套 |
+| paySiteName | paySiteName | string→TEXT（原样） | 发生本次余额变更的门店名称（即本次消费/充值所在门店） |
+| id | id | int→BIGINT（`parse_int`） | 余额变更记录的主键 ID，唯一标识这一条“账户余额变化事件” |
+| tenant_member_id | tenant_member_id | int→BIGINT（`parse_int`） | 商户维度的会员 ID（租户内会员主键） |
+| tenant_member_card_id | tenant_member_card_id | int→BIGINT（`parse_int`） | 会员卡账户 ID，在租户内唯一标识某张卡 |
+| system_member_id | system_member_id | int→BIGINT（`parse_int`） | 系统级（全局）会员 ID |
+| memberName | memberName | string→TEXT（原样） | 会员姓名或称呼（非昵称字段） |
+| memberMobile | memberMobile | string→TEXT（原样） | 会员手机号 |
+| card_type_id | card_type_id | int→BIGINT（`parse_int`） | 卡种类型 ID，用于区分不同卡种 |
+| memberCardTypeName | memberCardTypeName | string→TEXT（原样） | 卡种名称，与 card_type_id 一一对应，是一个 卡种枚举名称 |
+| account_data | account_data | float→NUMERIC(18,2)（`parse_decimal`） | 本次变动的金额（元），正数表示增加，负数表示减少 |
+| before | before | float→NUMERIC(18,2)（`parse_decimal`） | 本次变动前，该卡账户的余额（元） |
+| after | after | float→NUMERIC(18,2)（`parse_decimal`） | 本次变动后，该卡账户的余额（元） |
+| refund_amount | refund_amount | float→NUMERIC(18,2)（`parse_decimal`） | 可能用于标记“其中有多少金额是以‘退款’形式回流的”，或区分“退回余额”和“原路退回”两种模式 |
+| from_type | from_type | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| payment_method | payment_method | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| relate_id | relate_id | int→BIGINT（`parse_int`） | 例如某次充值记录的 ID、某张订单/结算单 ID、某次活动抵用券核销记录 ID 等 |
+| remark | remark | string→TEXT（原样） | 当为空时，说明这条变动没有额外备注说明 |
+| operator_id | operator_id | int→BIGINT（`parse_int`） | 执行此次余额变更操作的员工 ID |
+| operator_name | operator_name | string→TEXT（原样） | 操作员姓名（带职位前缀），是对 operator_id 的可读冗余字段 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标记（0=否，1=是） |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 本条余额变更记录的创建时间，通常接近交易发生时间 |
+| principal_after | principal_after | float→NUMERIC(18,2)（`parse_decimal`） | 变动后本金余额（新增字段） |
+| principal_before | principal_before | float→NUMERIC(18,2)（`parse_decimal`） | 变动前本金余额（新增字段） |
+| principal_data | principal_data | string→TEXT（原样） | 本金变动金额（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`member_balance_changes.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `MemberProfile/GetMemberCardBalanceChange` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetOfflineCouponConsumePageList_platform_coupon_redemption_records.md

@@ -0,0 +1,62 @@
+# 平台券核销记录（GetOfflineCouponConsumePageList） → platform_coupon_redemption_records 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Promotion/GetOfflineCouponConsumePageList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.platform_coupon_redemption_records` |
+| JSON 数据路径 | `$（平铺结构，外层含 siteProfile）` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 本条平台验券记录在本系统内的主键 ID |
+| verify_id | verify_id | int→BIGINT（`parse_int`） | 平台核销记录 ID（某些平台会为每一次核销生成一个唯一 ID） |
+| certificate_id | certificate_id | string→TEXT（原样） | 平台侧的凭证 ID（通常由第三方团购平台生成的券实例 ID） |
+| coupon_code | coupon_code | string→TEXT（原样） | 券码，顾客出示的团购券密码/编号 |
+| coupon_name | coupon_name | string→TEXT（原样） | 团购券产品名称（即第三方平台上向顾客展示的名称） |
+| coupon_channel | coupon_channel | int→INT（`parse_int`） | 券来源渠道（第三方平台渠道编号） |
+| groupon_type | groupon_type | int→INT（`parse_int`） | 团购券类型 |
+| group_package_id | group_package_id | int→BIGINT（`parse_int`） | 标识类 ID 字段，用于关联/定位相关实体 |
+| sale_price | sale_price | float→NUMERIC(18,2)（`parse_decimal`） | 顾客在第三方平台上实际支付的价格（团购售价） |
+| coupon_money | coupon_money | float→NUMERIC(18,2)（`parse_decimal`） | 券面值 / 套餐价值（系统层面的“可抵扣金额或对应套餐价值”） |
+| coupon_free_time | coupon_free_time | float→NUMERIC(18,2)（`parse_decimal`） | 券附带的“免费时长”字段（例如送多少分钟台费） |
+| coupon_cover | coupon_cover | string→TEXT（原样） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| coupon_remark | coupon_remark | string→TEXT（原样） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| use_status | use_status | int→INT（`parse_int`） | 值 1：198 条 |
+| consume_time | consume_time | string→TIMESTAMP（`parse_timestamp`） | 券被核销/使用的业务时间 |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 验券记录在本系统中创建的时间（记录入库时间） |
+| deal_id | deal_id | string→TEXT（原样） | 另一个层次的团购产品 ID |
+| channel_deal_id | channel_deal_id | string→TEXT（原样） | 渠道侧 dealId / 产品 ID，一般是第三方平台给该团购商品定义的主键 |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID |
+| site_order_id | site_order_id | int→BIGINT（`parse_int`） | 门店内部的订单 ID（平台券核销时对应的店内订单） |
+| table_id | table_id | int→BIGINT（`parse_int`） | 使用券的球台 ID |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 商户/租户 ID（品牌级别） |
+| operator_id | operator_id | int→BIGINT（`parse_int`） | 操作员 ID（执行验券操作的收银员/员工） |
+| operator_name | operator_name | string→TEXT（原样） | 操作员姓名，例如 "收银员:郑丽珊" |
+| is_delete | is_delete | int→INT（`parse_int`） | 把平台验券记录挂到本门店的一条订单上 |
+| siteProfile | siteProfile | object→JSONB（原样存储） | 门店信息快照 |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`platform_coupon_redemption_records.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Promotion/GetOfflineCouponConsumePageList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetOrderAssistantDetails_assistant_service_records.md

@@ -0,0 +1,102 @@
+# 助教服务流水（GetOrderAssistantDetails） → assistant_service_records 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `AssistantPerformance/GetOrderAssistantDetails` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.assistant_service_records` |
+| JSON 数据路径 | `data.orderAssistantDetails` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 本条助教流水记录的主键 ID（流水唯一标识） |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID，本数据中指“朗朗桌球”这一家门店 |
+| siteProfile | siteProfile | object→JSONB（原样存储） | 门店信息快照，包括 id、shop_name、address 等，和其他 JSON 里的 siteProfile 一致 |
+| site_table_id | site_table_id | int→BIGINT（`parse_int`） | 球台 ID |
+| order_settle_id | order_settle_id | int→BIGINT（`parse_int`） | 订单结算 ID，相当于“结账单号”的内部主键 |
+| order_trade_no | order_trade_no | string→TEXT（原样） | 订单交易号，整个订单层面的编号 |
+| order_pay_id | order_pay_id | int→BIGINT（`parse_int`） | 关联到“支付记录”的主键 ID |
+| order_assistant_id | order_assistant_id | int→BIGINT（`parse_int`） | 订单中“助教项目明细”的内部 ID |
+| order_assistant_type | order_assistant_type | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| assistantName | assistantName | string→TEXT（原样） | 助教姓名，如“何海婷”“胡敏”等 |
+| assistantNo | assistantNo | string→TEXT（原样） | 助教编号，例如 "27" |
+| assistant_level | assistant_level | string→TEXT（原样） | 助教等级名称，与 assistant_level 一一对应（初级/中级/高级/助教管理） |
+| levelName | levelname | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| site_assistant_id | site_assistant_id | int→BIGINT（`parse_int`） | 门店维度的助教 ID |
+| skill_id | skill_id | int→BIGINT（`parse_int`） | 助教服务“课程/技能”ID |
+| skillName | skillname | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| system_member_id | system_member_id | int→BIGINT（`parse_int`） | 系统级会员 ID（全集团统一 ID） |
+| tableName | tablename | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| tenant_member_id | tenant_member_id | int→BIGINT（`parse_int`） | 商户维度会员 ID（门店/品牌内的会员主键） |
+| user_id | user_id | int→BIGINT（`parse_int`） | 助教对应的“用户账号 ID”（系统级用户） |
+| assistant_team_id | assistant_team_id | int→BIGINT（`parse_int`） | 助教所属团队 ID |
+| nickname | nickname | string→TEXT（原样） | 助教对外昵称，如“佳怡”“周周”“球球”等 |
+| ledger_name | ledger_name | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| ledger_group_name | ledger_group_name | string→TEXT（原样） | 助教项目所属的“计费分组/套餐分组名称”，例如某种助教套餐或业务组名称 |
+| ledger_amount | ledger_amount | float→NUMERIC(18,2)（`parse_decimal`） | 按标准单价计算出来的应收金额（近似 = ledger_unit_price × income_seconds / 3600） |
+| ledger_count | ledger_count | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 台账记录的计时总秒数 |
+| ledger_unit_price | ledger_unit_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 助教服务 标准单价（通常是标价：每小时、每节课的单价） |
+| ledger_status | ledger_status | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| ledger_start_time | ledger_start_time | string→TIMESTAMP（`parse_timestamp`） | 台账层面记录的开始时间 |
+| ledger_end_time | ledger_end_time | string→TIMESTAMP（`parse_timestamp`） | 台账层面的结束时间 |
+| manual_discount_amount | manual_discount_amount | float→NUMERIC(18,2)（`parse_decimal`） | 收银员手动给予的减免金额（人工改价） |
+| member_discount_amount | member_discount_amount | float→NUMERIC(18,2)（`parse_decimal`） | 由会员卡折扣产生的优惠金额 |
+| coupon_deduct_money | coupon_deduct_money | float→NUMERIC(18,2)（`parse_decimal`） | 由“优惠券/代金券/团购券”等 直接抵扣到这条助教服务上的金额 |
+| service_money | service_money | float→NUMERIC(18,2)（`parse_decimal`） | 用于记录与助教结算的金额（平台预留的“成本/分成”字段） |
+| projected_income | projected_income | float→NUMERIC(18,2)（`parse_decimal`） | 实际结算计入门店的金额（已经考虑折扣、卡权益、券等后的结果） |
+| real_use_seconds | real_use_seconds | int→INT（`parse_int`） | 实际使用时长（秒） |
+| income_seconds | income_seconds | int→INT（`parse_int`） | 计费秒数 / 应计收入对应的时间 |
+| start_use_time | start_use_time | string→TIMESTAMP（`parse_timestamp`） | 助教实际开始服务时间 |
+| last_use_time | last_use_time | string→TIMESTAMP（`parse_timestamp`） | 最后一次使用（实际服务）时间 |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 这条助教流水记录创建时间（一般接近结算/下单时间） |
+| is_single_order | is_single_order | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标志 |
+| is_trash | is_trash | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| trash_reason | trash_reason | string→TEXT（原样） | 废除原因（文本说明），例如“顾客取消”“录入错误”等 |
+| trash_applicant_id | trash_applicant_id | int→BIGINT（`parse_int`） | 提出废除申请的员工 ID（通常是操作员/管理员） |
+| trash_applicant_name | trash_applicant_name | string→TEXT（原样） | 废除申请人姓名 |
+| operator_id | operator_id | int→BIGINT（`parse_int`） | 操作员 ID（录入/结算这条助教服务的员工） |
+| operator_name | operator_name | string→TEXT（原样） | 操作员姓名，与 operator_id 一起使用，便于直接阅读 |
+| salesman_name | salesman_name | string→TEXT（原样） | 关联的“营业员/销售员姓名”，用于提成归属 |
+| salesman_org_id | salesman_org_id | int→BIGINT（`parse_int`） | 营业员所属组织/部门 ID |
+| salesman_user_id | salesman_user_id | int→BIGINT（`parse_int`） | 营业员用户 ID |
+| person_org_id | person_org_id | int→BIGINT（`parse_int`） | 助教所属“人事组织/部门 ID” |
+| add_clock | add_clock | int→INT（`parse_int`） | 加钟秒数，即在原有预约/服务基础上临时追加的时长 |
+| returns_clock | returns_clock | int→INT（`parse_int`） | 退钟秒数（取消加钟或提前结束退回的时间） |
+| composite_grade | composite_grade | →NUMERIC(10,2) | 综合评分（例如技能+服务加权后的平均分），当前数据没有实际评分 |
+| composite_grade_time | composite_grade_time | string→TIMESTAMP（`parse_timestamp`） | 助教服务所在的球台名称（如 "A17"、"S1"） |
+| skill_grade | skill_grade | →NUMERIC(10,2) | 顾客对“技能表现”的评分（整数或打分等级） |
+| service_grade | service_grade | →NUMERIC(10,2) | 顾客对“服务态度”的评分 |
+| sum_grade | sum_grade | →NUMERIC(10,2) | 累计评分总和（可能用于计算平均分），当前为 0 |
+| grade_status | grade_status | int→INT（`parse_int`） | 1 = 未评价/正常 |
+| get_grade_times | get_grade_times | int→INT（`parse_int`） | 该条记录对应的评价次数（或该助教被评价次数快照） |
+| is_not_responding | is_not_responding | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| is_confirm | is_confirm | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| assistantteamname | assistantteamname | string→TEXT（原样） | 助教团队名称（新增字段） |
+| real_service_money | real_service_money | float→NUMERIC(18,2)（`parse_decimal`） | 实际服务费金额（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`assistant_service_records.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `AssistantPerformance/GetOrderAssistantDetails` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetOrderSettleTicketNew_settlement_ticket_details.md

@@ -0,0 +1,74 @@
+# 结账小票明细（GetOrderSettleTicketNew） → settlement_ticket_details 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Order/GetOrderSettleTicketNew` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.settlement_ticket_details` |
+| JSON 数据路径 | `$（平铺结构）` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| orderSettleId | orderSettleId | int→BIGINT（`parse_int`） | 结算单 ID（和顶层字段相同，再次冗余） |
+| actualPayment | actualPayment | float→NUMERIC(18,2)（`parse_decimal`） | 本单实际支付金额总和（顾客本次实际付出：现金 + 线上 + 会员余额等） |
+| adjustAmount | adjustAmount | float→NUMERIC(18,2)（`parse_decimal`） | 人工调价/整单调整金额（例如手工改价、折扣调整），是所有类型的手工调整合计 |
+| assistantManualDiscount | assistantManualDiscount | float→NUMERIC(18,2)（`parse_decimal`） | 针对“助教项目”的人工减免金额汇总（整单维度） |
+| balanceAmount | balanceAmount | float→NUMERIC(18,2)（`parse_decimal`） | 本单通过“会员余额/储值卡”支付的金额（从余额中扣除的总额） |
+| cashierName | cashierName | string→TEXT（原样） | 本单结算操作员名称（带角色前缀文字） |
+| consumeMoney | consumeMoney | float→NUMERIC(18,2)（`parse_decimal`） | 本单“消费金额总计”（原价层面），即台费 + 商品 + 助教 + 服务等消费项目的金额总和（未扣除各类优惠） |
+| couponAmount | couponAmount | float→NUMERIC(18,2)（`parse_decimal`） | 本单由优惠券抵扣的金额汇总 |
+| deliveryAddress | deliveryAddress | string→TEXT（原样） | 配送地址（若存在外送业务时使用） |
+| deliveryFee | deliveryFee | float→NUMERIC(18,2)（`parse_decimal`） | 配送费金额（如果支持外送业务） |
+| ledgerAmount | ledgerAmount | float→NUMERIC(18,2)（`parse_decimal`） | 商品小计金额（通常 = 单价 × 数量，未考虑其他折扣） |
+| memberDeductAmount | memberDeductAmount | float→NUMERIC(18,2)（`parse_decimal`） | 会员抵扣的某种数量或金额（例如积分抵现金额、次卡次数抵扣等），当前数据未启用 |
+| memberOfferAmount | memberOfferAmount | float→NUMERIC(18,2)（`parse_decimal`） | 由“会员权益/折扣”产生的优惠金额总计（整单维度） |
+| onlineReturnAmount | onlineReturnAmount | float→NUMERIC(18,2)（`parse_decimal`） | 本单通过线上支付渠道退回的金额（如微信/支付宝退款） |
+| orderRemark | orderRemark | string→TEXT（原样） | 订单备注，由收银员录入，用于记录与本单相关的特殊说明 |
+| orderSettleNumber | orderSettleNumber | int→BIGINT（`parse_int`） | 结算单编号（与 ID 独立的一套编号体系，如流水号） |
+| payMemberBalance | payMemberBalance | float→NUMERIC(18,2)（`parse_decimal`） | 使用会员余额支付的金额，用于区分与 balanceAmount 的不同维度（如“本次支付使用余额部分”与“余额本身变化”等），当前未实际使用 |
+| payTime | payTime | string→TIMESTAMP（`parse_timestamp`） | 本单最终支付成功时间 |
+| paymentMethod | paymentMethod | int→INT（`parse_int`） | 结算主支付方式编码（汇总视角） |
+| pointDiscountCost | pointDiscountCost | float→NUMERIC(18,2)（`parse_decimal`） | 积分抵扣对应的成本金额（成本侧） |
+| pointDiscountPrice | pointDiscountPrice | float→NUMERIC(18,2)（`parse_decimal`） | 积分抵扣对应的金额（售价侧） |
+| prepayMoney | prepayMoney | float→NUMERIC(18,2)（`parse_decimal`） | 预付金/定金在本单中使用的金额 |
+| refundAmount | refundAmount | float→NUMERIC(18,2)（`parse_decimal`） | 本单涉及的退款金额（汇总） |
+| returnGoodsAmount | returnGoodsAmount | float→NUMERIC(18,2)（`parse_decimal`） | 本单涉及的退货金额汇总 |
+| rewardName | rewardName | string→TEXT（原样） | 用于标识本单适用的激励方案名称，可能用于内部绩效或活动名称展示 |
+| settleType | settleType | string→TEXT（原样） | 结算类型字符串标识 |
+| siteAddress | siteAddress | string→TEXT（原样） | 门店地址（详细地址） |
+| siteBusinessTel | siteBusinessTel | string→TEXT（原样） | 门店电话 |
+| siteId | siteId | int→BIGINT（`parse_int`） | 门店 ID |
+| siteName | siteName | string→TEXT（原样） | 门店名称，如“朗朗桌球” |
+| tenantId | tenantId | int→BIGINT（`parse_int`） | 租户 / 商户 ID（品牌维度） |
+| tenantName | tenantName | string→TEXT（原样） | 租户名称，如“朗朗桌球” |
+| ticketCustomContent | ticketCustomContent | string→TEXT（原样） | 自定义小票内容，如商家自定义宣传语、条款等 |
+| ticketRemark | ticketRemark | string→TEXT（原样） | 小票备注内容，可用于打印在小票底部或顶部（例如活动说明、特别提示） |
+| voucherMoney | voucherMoney | float→NUMERIC(18,2)（`parse_decimal`） | 代金券类金额字段（可能用于某类“代金券余额”或“券面值”记录） |
+| memberProfile | memberProfile | object→JSONB（原样存储） | 不是会员卡主键，而是本次结账时的会员信息快照 |
+| orderItem | orderItem | object→JSONB（原样存储） | 本次结算对应的“订单明细列表”，这部分是连接“台费流水 / 商品出库 / 券使用”等多个子领域的关键结构 |
+| tenantMemberCardLogs | tenantMemberCardLogs | object→JSONB（原样存储） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`settlement_ticket_details.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Order/GetOrderSettleTicketNew` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetPayLogListPage_payment_transactions.md

@@ -0,0 +1,48 @@
+# 支付流水（GetPayLogListPage） → payment_transactions 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `PayLog/GetPayLogListPage` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.payment_transactions` |
+| JSON 数据路径 | `$（平铺结构，外层含 siteProfile）` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 支付流水记录的主键 ID |
+| site_id | site_id | int→BIGINT（`parse_int`） | 支付记录所属的门店 ID |
+| siteProfile | siteProfile | object→JSONB（原样存储） | 门店信息快照，与其他 JSON 中的 siteProfile 结构一致 |
+| relate_type | relate_type | int→INT（`parse_int`） | 表示“这条支付记录关联的业务类型” |
+| relate_id | relate_id | int→BIGINT（`parse_int`） | 关联业务记录的主键 ID（按 relate_type 不同指向不同表） |
+| pay_amount | pay_amount | float→NUMERIC(18,2)（`parse_decimal`） | 本条支付流水的“支付金额”，单位为元 |
+| pay_status | pay_status | int→INT（`parse_int`） | 支付状态枚举字段 |
+| pay_time | pay_time | string→TIMESTAMP（`parse_timestamp`） | 实际支付完成时间（支付状态变为成功的时间戳） |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 支付记录创建时间，通常与发起支付请求的时间一致（创建支付流水的时间戳） |
+| payment_method | payment_method | int→INT（`parse_int`） | 支付方式枚举，例如微信、支付宝、现金、银行卡、储值卡等某一种 |
+| online_pay_channel | online_pay_channel | int→INT（`parse_int`） | 每一笔结账单（settleList.id）对应一条支付记录（当前样本中是一条记录，relate_id 唯一） |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`payment_transactions.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `PayLog/GetPayLogListPage` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetRechargeSettleList_recharge_settlements.md

@@ -0,0 +1,102 @@
+# 充值结算记录（GetRechargeSettleList） → recharge_settlements 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Site/GetRechargeSettleList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.recharge_settlements` |
+| JSON 数据路径 | `data.settleList（外层含 siteProfile）` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 门店 ID |
+| tenantid | tenantid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| siteid | siteid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| sitename | sitename | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| balanceamount | balanceamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| cardamount | cardamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| cashamount | cashamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| couponamount | couponamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| createtime | createtime | string→TIMESTAMP（`parse_timestamp`） | 时间字段，用于记录业务时间点/发生时间 |
+| memberid | memberid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| membername | membername | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| tenantmembercardid | tenantmembercardid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| membercardtypename | membercardtypename | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| memberphone | memberphone | string→TEXT（原样） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| tableid | tableid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| consumemoney | consumemoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| onlineamount | onlineamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| operatorid | operatorid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| operatorname | operatorname | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| revokeorderid | revokeorderid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| revokeordername | revokeordername | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| revoketime | revoketime | string→TIMESTAMP（`parse_timestamp`） | 时间字段，用于记录业务时间点/发生时间 |
+| payamount | payamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| pointamount | pointamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| refundamount | refundamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| settlename | settlename | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| settlerelateid | settlerelateid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| settlestatus | settlestatus | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| settletype | settletype | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| paytime | paytime | string→TIMESTAMP（`parse_timestamp`） | 时间字段，用于记录业务时间点/发生时间 |
+| roundingamount | roundingamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| paymentmethod | paymentmethod | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| adjustamount | adjustamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistantcxmoney | assistantcxmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistantpdmoney | assistantpdmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| couponsaleamount | couponsaleamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| memberdiscountamount | memberdiscountamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| tablechargemoney | tablechargemoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| goodsmoney | goodsmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| realgoodsmoney | realgoodsmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| servicemoney | servicemoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| prepaymoney | prepaymoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| salesmanname | salesmanname | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| orderremark | orderremark | string→TEXT（原样） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| salesmanuserid | salesmanuserid | int→BIGINT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| canberevoked | canberevoked | bool→BOOLEAN | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| pointdiscountprice | pointdiscountprice | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| pointdiscountcost | pointdiscountcost | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| activitydiscount | activitydiscount | float→NUMERIC(18,2)（`parse_decimal`） | 数量/时长字段，用于统计与计量 |
+| serialnumber | serialnumber | int→BIGINT（`parse_int`） | 数量/时长字段，用于统计与计量 |
+| assistantmanualdiscount | assistantmanualdiscount | float→NUMERIC(18,2)（`parse_decimal`） | 数量/时长字段，用于统计与计量 |
+| allcoupondiscount | allcoupondiscount | float→NUMERIC(18,2)（`parse_decimal`） | 数量/时长字段，用于统计与计量 |
+| goodspromotionmoney | goodspromotionmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistantpromotionmoney | assistantpromotionmoney | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| isusecoupon | isusecoupon | bool→BOOLEAN | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| isusediscount | isusediscount | bool→BOOLEAN | 数量/时长字段，用于统计与计量 |
+| isactivity | isactivity | bool→BOOLEAN | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| isbindmember | isbindmember | bool→BOOLEAN | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| isfirst | isfirst | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| rechargecardamount | rechargecardamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| giftcardamount | giftcardamount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| electricityadjustmoney | electricityadjustmoney | float→NUMERIC(18,2)（`parse_decimal`） | 电费调整金额（新增字段） |
+| electricitymoney | electricitymoney | float→NUMERIC(18,2)（`parse_decimal`） | 电费金额（新增字段） |
+| mervousalesamount | mervousalesamount | float→NUMERIC(18,2)（`parse_decimal`） | 商户代金券销售金额（新增字段） |
+| plcouponsaleamount | plcouponsaleamount | float→NUMERIC(18,2)（`parse_decimal`） | 平台券销售金额（新增字段） |
+| realelectricitymoney | realelectricitymoney | float→NUMERIC(18,2)（`parse_decimal`） | 实际电费金额（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`recharge_settlements.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Site/GetRechargeSettleList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetRefundPayLogList_refund_transactions.md

@@ -0,0 +1,68 @@
+# 退款流水（GetRefundPayLogList） → refund_transactions 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Order/GetRefundPayLogList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.refund_transactions` |
+| JSON 数据路径 | `$（平铺结构，外层含 siteProfile）` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 本条 退款流水 的唯一 ID |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID，全系统维度标识该商户 |
+| tenantName | tenantName | string→TEXT（原样） | 租户（商户）名称 |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID |
+| siteProfile | siteProfile | object→JSONB（原样存储） | 门店信息快照，结构与其他 JSON 中的 siteProfile 完全一致 |
+| relate_type | relate_type | int→INT（`parse_int`） | 本退款对应的“业务类型” |
+| relate_id | relate_id | int→BIGINT（`parse_int`） | 本次退款关联的业务 ID |
+| pay_sn | pay_sn | string→TEXT（原样） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| pay_amount | pay_amount | float→NUMERIC(18,2)（`parse_decimal`） | 本次退款的 资金变动金额 |
+| refund_amount | refund_amount | float→NUMERIC(18,2)（`parse_decimal`） | 设计上本应显示“实际退款金额”（正数），与 pay_amount 配合使用 |
+| round_amount | round_amount | float→NUMERIC(18,2)（`parse_decimal`） | 舍入金额/抹零金额 |
+| pay_status | pay_status | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| pay_time | pay_time | string→TIMESTAMP（`parse_timestamp`） | 退款在支付渠道层面实际发生的时间 |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 本条退款流水在系统内创建时间 |
+| payment_method | payment_method | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| pay_terminal | pay_terminal | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| pay_config_id | pay_config_id | int→BIGINT（`parse_int`） | 支付配置 ID，例如商户在“非球科技”内配置的某一条支付通道（某个微信商户号、银联通道）的主键 |
+| online_pay_channel | online_pay_channel | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| online_pay_type | online_pay_type | int→INT（`parse_int`） | 当前：全部 0 |
+| channel_fee | channel_fee | float→NUMERIC(18,2)（`parse_decimal`） | 第三方支付渠道对本次退款收取的手续费 |
+| channel_payer_id | channel_payer_id | string→TEXT（原样） | 支付渠道侧的 payer ID，例如微信 openid、银行卡号掩码等 |
+| channel_pay_no | channel_pay_no | string→TEXT（原样） | 第三方支付平台的交易号（如微信支付单号、支付宝交易号等） |
+| member_id | member_id | int→BIGINT（`parse_int`） | 租户内部的会员 ID（对应会员档案中的某个主键） |
+| member_card_id | member_card_id | int→BIGINT（`parse_int`） | 关联的会员卡账户 ID（对应“储值卡列表”或“会员档案”中的某一张卡） |
+| cashier_point_id | cashier_point_id | int→BIGINT（`parse_int`） | 收银点 ID，例如前台 1、前台 2、自助机等 |
+| operator_id | operator_id | int→BIGINT（`parse_int`） | 执行该退款操作的操作员 ID |
+| action_type | action_type | int→INT（`parse_int`） | 当前：全部 2 |
+| check_status | check_status | int→INT（`parse_int`） | 当前：全部 1 |
+| is_revoke | is_revoke | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标志 |
+| balance_frozen_amount | balance_frozen_amount | float→NUMERIC(18,2)（`parse_decimal`） | 涉及会员储值卡退款时，暂时冻结的余额金额 |
+| card_frozen_amount | card_frozen_amount | float→NUMERIC(18,2)（`parse_decimal`） | 与上一个类似，偏向“某张卡的被冻结金额”，也与会员卡/储值账户相关 |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`refund_transactions.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Order/GetRefundPayLogList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetSiteTableOrderDetails_table_fee_transactions.md

@@ -0,0 +1,78 @@
+# 台费流水（GetSiteTableOrderDetails） → table_fee_transactions 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Site/GetSiteTableOrderDetails` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.table_fee_transactions` |
+| JSON 数据路径 | `data.siteTableUseDetailsList` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 台费流水记录主键（事实表主键） |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID，本次数据全部来自同一门店（朗朗桌球） |
+| siteProfile | siteProfile | object→JSONB（原样存储） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| site_table_id | site_table_id | int→BIGINT（`parse_int`） | 球台 ID |
+| site_table_area_id | site_table_area_id | int→BIGINT（`parse_int`） | 门店内“台桌区域” ID（站在门店物理布局的角度） |
+| site_table_area_name | site_table_area_name | string→TEXT（原样） | 台桌区域的名称，用于门店表现和区域统计 |
+| tenant_table_area_id | tenant_table_area_id | int→BIGINT（`parse_int`） | 租户维度的台桌区域 ID（品牌层面的同一类区域） |
+| order_trade_no | order_trade_no | string→TEXT（原样） | 订单交易号，是整笔订单的主编号 |
+| order_pay_id | order_pay_id | int→BIGINT（`parse_int`） | 订单支付记录 ID |
+| order_settle_id | order_settle_id | int→BIGINT（`parse_int`） | 结算单号/结账 ID，对应一次结账操作 |
+| ledger_name | ledger_name | string→TEXT（原样） | 台号名称，实际展示给员工/顾客看的桌台编号 |
+| ledger_amount | ledger_amount | float→NUMERIC(18,2)（`parse_decimal`） | 按单价与计费时长计算出的原始应收台费金额 |
+| ledger_count | ledger_count | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 台账记录的计费秒数，计费用秒数（应收时长） |
+| ledger_unit_price | ledger_unit_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 台费结算时设置的 每小时单价/计费单价 |
+| ledger_status | ledger_status | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| ledger_start_time | ledger_start_time | string→TIMESTAMP（`parse_timestamp`） | 台账上的计费起始时间 |
+| ledger_end_time | ledger_end_time | string→TIMESTAMP（`parse_timestamp`） | 台账上的计费结束时间 |
+| start_use_time | start_use_time | string→TIMESTAMP（`parse_timestamp`） | 台开始使用的时间（实际开台时间） |
+| last_use_time | last_use_time | string→TIMESTAMP（`parse_timestamp`） | 最后使用/操作时间 |
+| real_table_use_seconds | real_table_use_seconds | int→INT（`parse_int`） | 实际使用的总秒数（系统真实统计的使用时长） |
+| real_table_charge_money | real_table_charge_money | float→NUMERIC(18,2)（`parse_decimal`） | 台费中实际向顾客收取的金额（现金/实付维度，未含券方承担或内部调账的那一部分） |
+| add_clock_seconds | add_clock_seconds | int→INT（`parse_int`） | 加钟秒数，在原有使用基础上追加的时长 |
+| adjust_amount | adjust_amount | float→NUMERIC(18,2)（`parse_decimal`） | 调整金额/调账金额，用于将台费金额转移或冲减到其它项目，或手工调整 |
+| coupon_promotion_amount | coupon_promotion_amount | float→NUMERIC(18,2)（`parse_decimal`） | 由优惠券/活动/团购（平台/门店促销）承担的优惠金额，直接抵扣在台费上 |
+| member_discount_amount | member_discount_amount | float→NUMERIC(18,2)（`parse_decimal`） | 由会员权益产生的优惠金额，例如会员折扣、会员价等 |
+| used_card_amount | used_card_amount | float→NUMERIC(18,2)（`parse_decimal`） | 由储值卡、次卡等“卡内余额”抵扣的金额 |
+| mgmt_fee | mgmt_fee | float→NUMERIC(18,2)（`parse_decimal`） | 管理费字段，用于未来支持“台费附加管理费/服务费”的功能 |
+| service_money | service_money | float→NUMERIC(18,2)（`parse_decimal`） | 门店用于记录“服务费/成本/分成金额”的字段，类似助教流水里的 service_money |
+| fee_total | fee_total | float→NUMERIC(18,2)（`parse_decimal`） | 各种附加费用（如管理费、服务费）合计值 |
+| is_single_order | is_single_order | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标记（0=否，1=是） |
+| member_id | member_id | int→BIGINT（`parse_int`） | 门店/租户内的会员 ID |
+| operator_id | operator_id | int→BIGINT（`parse_int`） | 操作员 ID，负责开台/结账的员工账号 ID |
+| operator_name | operator_name | string→TEXT（原样） | 操作员姓名（冗余字段），便于直接阅读，不必再联表员工档案 |
+| salesman_name | salesman_name | string→TEXT（原样） | 业务员/营业员姓名，如果台费有单独提成员工，这里记录归属人 |
+| salesman_org_id | salesman_org_id | int→BIGINT（`parse_int`） | 营业员所属机构/部门 ID |
+| salesman_user_id | salesman_user_id | int→BIGINT（`parse_int`） | 营业员的用户 ID（与 salesman_name 搭配） |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 这条台费流水记录的创建时间，通常接近结账时间 |
+| activity_discount_amount | activity_discount_amount | float→NUMERIC(18,2)（`parse_decimal`） | 活动折扣金额（新增字段） |
+| order_consumption_type | order_consumption_type | int→INT（`parse_int`） | 订单消费类型（新增字段） |
+| real_service_money | real_service_money | float→NUMERIC(18,2)（`parse_decimal`） | 实际服务费金额（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`table_fee_transactions.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Site/GetSiteTableOrderDetails` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetSiteTableUseDetails_group_buy_redemption_records.md

@@ -0,0 +1,88 @@
+# 团购核销记录（GetSiteTableUseDetails） → group_buy_redemption_records 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Site/GetSiteTableUseDetails` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.group_buy_redemption_records` |
+| JSON 数据路径 | `data.siteTableUseDetailsList` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 本条“团购套餐流水”记录的 主键 ID |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID，与其它 JSON 中一致 |
+| siteName | siteName | string→TEXT（原样） | 门店名称，冗余展示用 |
+| table_id | table_id | int→BIGINT（`parse_int`） | 球台 ID |
+| tableName | tableName | string→TEXT（原样） | 本次使用券所关联的 球台名称/台号 |
+| tableAreaName | tableAreaName | string→TEXT（原样） | 该球台所属的 台区名称 |
+| tenant_table_area_id | tenant_table_area_id | int→BIGINT（`parse_int`） | 租户级台区分组 ID，表示当前使用券的台桌所属的区域组合 |
+| order_trade_no | order_trade_no | string→TEXT（原样） | 订单交易号，和其它消费明细（台费、商品、助教、团购）共用的订单主键 |
+| order_settle_id | order_settle_id | int→BIGINT（`parse_int`） | 结算单 ID（小票结账主键） |
+| order_pay_id | order_pay_id | int→BIGINT（`parse_int`） | 指向支付记录表中的支付流水 ID |
+| order_coupon_id | order_coupon_id | int→BIGINT（`parse_int`） | 订单中“券使用记录”的 ID |
+| order_coupon_channel | order_coupon_channel | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| coupon_code | coupon_code | string→TEXT（原样） | 团购券券码，核销时扫描/录入的字符串 |
+| coupon_money | coupon_money | float→NUMERIC(18,2)（`parse_decimal`） | 本次核销时，这张券在门店侧对应的金额额度（“可抵扣金额”） |
+| coupon_origin_id | coupon_origin_id | int→BIGINT（`parse_int`） | 平台/上游系统中的券记录主键 ID，“券来源 ID” |
+| ledger_name | ledger_name | string→TEXT（原样） | 台费侧关联的“团购项目名称”（记账名） |
+| ledger_group_name | ledger_group_name | string→TEXT（原样） | 团购项目所属的“记账分组名称”（例如“团购台费”“团购包厢”等） |
+| ledger_amount | ledger_amount | float→NUMERIC(18,2)（`parse_decimal`） | 本次券实际冲抵台费的金额 |
+| ledger_count | ledger_count | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 按此次优惠实际计算的“核销秒数” |
+| ledger_unit_price | ledger_unit_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 对应台费的标准单价，单位元/小时（从数值来看是类似29.9/小时这种定价） |
+| ledger_status | ledger_status | int→INT（`parse_int`） | 流水状态 |
+| table_charge_seconds | table_charge_seconds | int→INT（`parse_int`） | 本次结算中该球台总计计费的秒数（整台的台费计费时间） |
+| promotion_activity_id | promotion_activity_id | int→BIGINT（`parse_int`） | 团购/促销活动 ID |
+| promotion_coupon_id | promotion_coupon_id | int→BIGINT（`parse_int`） | 团购套餐定义 ID |
+| promotion_seconds | promotion_seconds | int→INT（`parse_int`） | 团购套餐定义的“标准时长”（券本身标称的可用时长） |
+| offer_type | offer_type | int→INT（`parse_int`） | 优惠类型 |
+| assistant_promotion_money | assistant_promotion_money | float→NUMERIC(18,2)（`parse_decimal`） | 分摊到“助教服务”的促销金额 |
+| assistant_service_promotion_money | assistant_service_promotion_money | float→NUMERIC(18,2)（`parse_decimal`） | 进一步细分助教服务的促销金额 |
+| table_service_promotion_money | table_service_promotion_money | float→NUMERIC(18,2)（`parse_decimal`） | 本次券使用中，分摊到“台费服务费”部分的促销金额 |
+| goods_promotion_money | goods_promotion_money | float→NUMERIC(18,2)（`parse_decimal`） | 本次券使用中，分摊到“商品”部分的促销金额 |
+| recharge_promotion_money | recharge_promotion_money | float→NUMERIC(18,2)（`parse_decimal`） | 来自“充值类优惠”的分摊金额（例如储值赠送部分） |
+| reward_promotion_money | reward_promotion_money | float→NUMERIC(18,2)（`parse_decimal`） | 本次促销中，属于“奖励金/积分抵扣”的金额 |
+| goodsOptionPrice | goodsOptionPrice | float→NUMERIC(18,2)（`parse_decimal`） | 商品规格价格，用于商品类促销分摊时使用 |
+| salesman_name | salesman_name | string→TEXT（原样） | 营业员姓名 |
+| sales_man_org_id | sales_man_org_id | int→BIGINT（`parse_int`） | 营业员所属组织 ID |
+| salesman_role_id | salesman_role_id | int→BIGINT（`parse_int`） | 营业员角色 ID |
+| salesman_user_id | salesman_user_id | int→BIGINT（`parse_int`） | 营业员/业务员用户 ID |
+| operator_id | operator_id | int→BIGINT（`parse_int`） | 执行本次核销/结算操作的 操作员 ID |
+| operator_name | operator_name | string→TEXT（原样） | 操作员名称（包含角色说明），与 operator_id 对应的冗余展示字段 |
+| is_single_order | is_single_order | int→INT（`parse_int`） | 是否单独作为一条订单行 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标记（0=否，1=是） |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 本条团购套餐使用流水创建时间（即券核销时间，或与结账时间接近） |
+| assistant_service_share_money | assistant_service_share_money | float→NUMERIC(18,2)（`parse_decimal`） | 助教服务分摊金额（新增字段） |
+| assistant_share_money | assistant_share_money | float→NUMERIC(18,2)（`parse_decimal`） | 助教分摊金额（新增字段） |
+| coupon_sale_id | coupon_sale_id | int→BIGINT（`parse_int`） | 券销售 ID（新增字段） |
+| good_service_share_money | good_service_share_money | float→NUMERIC(18,2)（`parse_decimal`） | 商品服务分摊金额（新增字段） |
+| goods_share_money | goods_share_money | float→NUMERIC(18,2)（`parse_decimal`） | 商品分摊金额（新增字段） |
+| member_discount_money | member_discount_money | float→NUMERIC(18,2)（`parse_decimal`） | 会员折扣金额（新增字段） |
+| recharge_share_money | recharge_share_money | float→NUMERIC(18,2)（`parse_decimal`） | 充值分摊金额（新增字段） |
+| table_service_share_money | table_service_share_money | float→NUMERIC(18,2)（`parse_decimal`） | 台费服务分摊金额（新增字段） |
+| table_share_money | table_share_money | float→NUMERIC(18,2)（`parse_decimal`） | 台费分摊金额（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`group_buy_redemption_records.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Site/GetSiteTableUseDetails` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetSiteTables_site_tables_master.md

@@ -0,0 +1,62 @@
+# 台桌主数据（GetSiteTables） → site_tables_master 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Table/GetSiteTables` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.site_tables_master` |
+| JSON 数据路径 | `data.siteTables` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 台桌主键 ID |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID |
+| siteName | siteName | string→TEXT（原样） | 门店名称快照，冗余字段，配合 site_id 使用 |
+| "appletQrCodeUrl" | "appletQrCodeUrl" | string→TEXT（原样） | 小程序二维码 URL（新增字段） |
+| areaName | areaName | string→TEXT（原样） | 区域名称，用于前台展示和区域维度管理 |
+| audit_status | audit_status | int→INT（`parse_int`） | 当前值：全部为 2 |
+| charge_free | charge_free | int→INT（`parse_int`） | 当前值：全部为 0 |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 台桌配置的创建时间或最近一次创建/复制时间 |
+| delay_lights_time | delay_lights_time | int→INT（`parse_int`） | 台灯熄灭延迟时间（单位多半是秒或分钟），用于结账后延时关灯 |
+| is_online_reservation | is_online_reservation | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| is_rest_area | is_rest_area | int→INT（`parse_int`） | 当前值：全部为 0 |
+| light_status | light_status | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| only_allow_groupon | only_allow_groupon | int→INT（`parse_int`） | 小程序二维码 URL |
+| order_delay_time | order_delay_time | int→INT（`parse_int`） | 订单层面允许的“自动延时时长”（例如到点后自动延长多少时间继续计费） |
+| self_table | self_table | int→INT（`parse_int`） | 当前值：全部为 1 |
+| show_status | show_status | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| site_table_area_id | site_table_area_id | int→BIGINT（`parse_int`） | 门店维度的“台桌区域 ID” |
+| tableStatusName | tableStatusName | string→TEXT（原样） | table_status 的中文名称，仅为展示用途 |
+| table_cloth_use_Cycle | table_cloth_use_Cycle | int→INT（`parse_int`） | 台呢使用周期阈值，例如达到某个秒数后提醒更换 |
+| table_cloth_use_time | table_cloth_use_time | string→TIMESTAMP（`parse_timestamp`） | 时间字段，用于记录业务时间点/发生时间 |
+| table_name | table_name | string→TEXT（原样） | 台号/台名称，用于前台操作界面展示，也出现在小票和各种流水中的 ledger_name 或 tableName 字段 |
+| table_price | table_price | float→NUMERIC(18,2)（`parse_decimal`） | 设计上应为“台的基础单价”字段（例如按小时或按局单价） |
+| table_status | table_status | int→INT（`parse_int`） | 台当前运行状态，真实反映某一时刻台的占用/暂停情况 |
+| temporary_light_second | temporary_light_second | int→INT（`parse_int`） | 临时点灯时长（秒），例如手动临时开灯一段时间 |
+| virtual_table | virtual_table | int→INT（`parse_int`） | 当前值：全部为 0 |
+| order_id | order_id | int→BIGINT（`parse_int`） | 关联订单 ID（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`site_tables_master.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Table/GetSiteTables` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetTaiFeeAdjustList_table_fee_discount_records.md

@@ -0,0 +1,64 @@
+# 台费优惠记录（GetTaiFeeAdjustList） → table_fee_discount_records 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `Site/GetTaiFeeAdjustList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.table_fee_discount_records` |
+| JSON 数据路径 | `data.taiFeeAdjustInfos` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 台费打折 / 调整流水主键 ID |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID，本批数据全部为同一家门店（朗朗桌球） |
+| siteProfile | siteProfile | object→JSONB（原样存储） | 门店信息快照，用于报表时直接读取，无需再联门店档案 |
+| site_table_id | site_table_id | int→BIGINT（`parse_int`） | 台桌 ID |
+| tableProfile | tableProfile | object→JSONB（原样存储） | 折扣发生时，对应台桌的配置信息快照 |
+| tenant_table_area_id | tenant_table_area_id | int→BIGINT（`parse_int`） | 租户维度的“台桌区域 ID” |
+| adjust_type | adjust_type | int→INT（`parse_int`） | 文件名是“台费打折”，字段名为“调整类型”，当前所有记录都是 1，即“台费打折/台费减免”这一种调整类型 |
+| ledger_amount | ledger_amount | float→NUMERIC(18,2)（`parse_decimal`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| ledger_count | ledger_count | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 这里不是“秒数”，而是“调整次数/条数”的量化，目前固定为 1，表示“一次调账事件” |
+| ledger_name | ledger_name | string→TEXT（原样） | 设计上应该用于记录“调账项目名称”或“打折原因描述”（例如某种优惠规则名称），但当前门店并未使用该字段 |
+| ledger_status | ledger_status | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| applicant_id | applicant_id | int→BIGINT（`parse_int`） | 打折/调账申请人 ID |
+| applicant_name | applicant_name | string→TEXT（原样） | 申请人姓名（带角色描述），为 applicant_id 的冗余显示字段 |
+| operator_id | operator_id | int→BIGINT（`parse_int`） | 实际执行调账操作的操作员 ID |
+| operator_name | operator_name | string→TEXT（原样） | 操作员姓名 |
+| order_settle_id | order_settle_id | int→BIGINT（`parse_int`） | 结算单/小票 ID |
+| order_trade_no | order_trade_no | string→TEXT（原样） | 订单交易号 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标记（0=否，1=是） |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 台费调整记录的创建时间，即打折操作被执行的时间戳 |
+| area_type_id | area_type_id | int→BIGINT（`parse_int`） | 台区类型 ID（新增字段） |
+| charge_free | charge_free | bool→BOOLEAN | 是否免费台（新增字段） |
+| site_table_area_id | site_table_area_id | int→BIGINT（`parse_int`） | 台桌所属区域 ID（新增字段） |
+| site_table_area_name | site_table_area_name | string→TEXT（原样） | 台桌所属区域名称（新增字段） |
+| sitename | sitename | string→TEXT（原样） | 门店名称（新增字段） |
+| table_name | table_name | string→TEXT（原样） | 台桌名称/编号（新增字段） |
+| table_price | table_price | float→NUMERIC(18,2)（`parse_decimal`） | 台费单价（新增字段） |
+| tenant_name | tenant_name | string→TEXT（原样） | 租户名称（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`table_fee_discount_records.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `Site/GetTaiFeeAdjustList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetTenantMemberCardList_member_stored_value_cards.md

@@ -0,0 +1,111 @@
+# 会员储值卡（GetTenantMemberCardList） → member_stored_value_cards 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `MemberProfile/GetTenantMemberCardList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.member_stored_value_cards` |
+| JSON 数据路径 | `data.tenantMemberCards` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID，与其他 JSON 中 tenant_id 一致 |
+| tenant_member_id | tenant_member_id | int→BIGINT（`parse_int`） | 当前商户（品牌/租户）中会员的主键 ID |
+| system_member_id | system_member_id | int→BIGINT（`parse_int`） | 系统级会员 ID（跨门店统一主键） |
+| register_site_id | register_site_id | int→BIGINT（`parse_int`） | 卡首次办理的门店 ID |
+| site_name | site_name | string→TEXT（原样） | 卡归属门店名称（视图中的展示字段） |
+| id | id | int→BIGINT（`parse_int`） | 本表主键 ID，用于唯一标识一条记录 |
+| member_card_grade_code | member_card_grade_code | int→BIGINT（`parse_int`） | 卡等级/卡类代码，和下面两个名称字段一一对应 |
+| member_card_grade_code_name | member_card_grade_code_name | string→TEXT（原样） | 卡等级/卡类名称 |
+| member_card_type_name | member_card_type_name | string→TEXT（原样） | 卡类型名称，实际与 member_card_grade_code_name 一致 |
+| member_name | member_name | string→TEXT（原样） | 持卡会员姓名快照 |
+| member_mobile | member_mobile | string→TEXT（原样） | 持卡会员手机号快照 |
+| card_type_id | card_type_id | int→BIGINT（`parse_int`） | 卡种 ID（定义“这是哪一种卡”） |
+| card_no | card_no | string→TEXT（原样） | 实体卡物理卡号／条码号 |
+| card_physics_type | card_physics_type | string→TEXT（原样） | 物理卡类型 |
+| balance | balance | float→NUMERIC(18,2)（`parse_decimal`） | 当前卡内余额（主要针对储值卡、部分券卡） |
+| denomination | denomination | float→NUMERIC(18,2)（`parse_decimal`） | 采用“几折”的记法：10=不打折，9=九折，8=八折 |
+| table_discount | table_discount | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 数量/时长字段，用于统计与计量 |
+| goods_discount | goods_discount | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 数量/时长字段，用于统计与计量 |
+| assistant_discount | assistant_discount | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 数量/时长字段，用于统计与计量 |
+| assistant_reward_discount | assistant_reward_discount | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 数量/时长字段，用于统计与计量 |
+| table_service_discount | table_service_discount | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 数量/时长字段，用于统计与计量 |
+| assistant_service_discount | assistant_service_discount | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 数量/时长字段，用于统计与计量 |
+| coupon_discount | coupon_discount | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 数量/时长字段，用于统计与计量 |
+| goods_service_discount | goods_service_discount | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 数量/时长字段，用于统计与计量 |
+| assistant_discount_sub_switch | assistant_discount_sub_switch | int→INT（`parse_int`） | 数量/时长字段，用于统计与计量 |
+| table_discount_sub_switch | table_discount_sub_switch | int→INT（`parse_int`） | 数量/时长字段，用于统计与计量 |
+| goods_discount_sub_switch | goods_discount_sub_switch | int→INT（`parse_int`） | 数量/时长字段，用于统计与计量 |
+| assistant_reward_discount_sub_switch | assistant_reward_discount_sub_switch | int→INT（`parse_int`） | 数量/时长字段，用于统计与计量 |
+| table_service_deduct_radio | table_service_deduct_radio | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistant_service_deduct_radio | assistant_service_deduct_radio | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| goods_service_deduct_radio | goods_service_deduct_radio | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistant_deduct_radio | assistant_deduct_radio | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| table_deduct_radio | table_deduct_radio | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| goods_deduct_radio | goods_deduct_radio | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| coupon_deduct_radio | coupon_deduct_radio | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| assistant_reward_deduct_radio | assistant_reward_deduct_radio | float→NUMERIC(10,4)（`parse_decimal(scale=4)`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| tableCardDeduct | tableCardDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 针对台费/商品/助教三类消费的扣卡金额配置（类似“每小时从卡里扣 xx 元”或“每次抵扣 xx 元”的规则） |
+| tableServiceCardDeduct | tableServiceCardDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 如果系统中区分“储值金、服务金、奖励金”等子账户，这三个字段对应“服务金”子账户的扣款配置 |
+| goodsCarDeduct | goodsCarDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 针对台费/商品/助教三类消费的扣卡金额配置（类似“每小时从卡里扣 xx 元”或“每次抵扣 xx 元”的规则） |
+| goodsServiceCardDeduct | goodsServiceCardDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 如果系统中区分“储值金、服务金、奖励金”等子账户，这三个字段对应“服务金”子账户的扣款配置 |
+| assistantCardDeduct | assistantCardDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 针对台费/商品/助教三类消费的扣卡金额配置（类似“每小时从卡里扣 xx 元”或“每次抵扣 xx 元”的规则） |
+| assistantServiceCardDeduct | assistantServiceCardDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 如果系统中区分“储值金、服务金、奖励金”等子账户，这三个字段对应“服务金”子账户的扣款配置 |
+| assistantRewardCardDeduct | assistantRewardCardDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 助教奖励金方向扣款的配置 |
+| cardSettleDeduct | cardSettleDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 结算时从卡中扣除的金额上限/规则配置（视图级 |
+| couponCardDeduct | couponCardDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 与卡绑定的“券额度扣除配置” |
+| deliveryFeeDeduct | deliveryFeeDeduct | float→NUMERIC(18,2)（`parse_decimal`） | 配送费可否/多少从卡中抵扣，目前无业务发生 |
+| use_scene | use_scene | int→INT（`parse_int`） | 卡使用场景说明（比如“仅店内使用”“仅团建”等），本门店尚未使用此字段 |
+| able_cross_site | able_cross_site | int→INT（`parse_int`） | 是否允许跨店使用 |
+| is_allow_give | is_allow_give | int→INT（`parse_int`） | 是否允许转赠/转让给其他会员 |
+| is_allow_order_deduct | is_allow_order_deduct | int→INT（`parse_int`） | 是否允许在“订单层面统一扣款” |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标志 |
+| bind_password | bind_password | string→TEXT（原样） | 卡绑定密码，用于消费或查询验证（目前未启用） |
+| goods_discount_range_type | goods_discount_range_type | int→INT（`parse_int`） | 数量/时长字段，用于统计与计量 |
+| goodsCategoryId | goodsCategoryId | int→BIGINT（`parse_int`） | 可用的商品分类 ID 列表 |
+| tableAreaId | tableAreaId | int→BIGINT（`parse_int`） | 限定可使用的台区 ID 列表 |
+| effect_site_id | effect_site_id | int→BIGINT（`parse_int`） | 卡片限定生效门店 ID |
+| start_time | start_time | string→TIMESTAMP（`parse_timestamp`） | 卡片生效开始时间（有效期起始） |
+| end_time | end_time | string→TIMESTAMP（`parse_timestamp`） | 卡片有效期结束时间 |
+| disable_start_time | disable_start_time | string→TIMESTAMP（`parse_timestamp`） | 停用时间段（比如临时冻结卡的起止时间） |
+| disable_end_time | disable_end_time | string→TIMESTAMP（`parse_timestamp`） | 停用时间段（比如临时冻结卡的起止时间） |
+| last_consume_time | last_consume_time | string→TIMESTAMP（`parse_timestamp`） | 最近一次消费时间 |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 卡片创建时间（开卡时间） |
+| status | status | int→INT（`parse_int`） | 状态枚举，用于标识记录当前业务状态 |
+| sort | sort | int→INT（`parse_int`） | 在前端展示或某些列表中的排序权重 |
+| tenantAvatar | tenantAvatar | string→TEXT（原样） | 品牌头像 URL（未配置） |
+| tenantName | tenantName | string→TEXT（原样） | 租户/品牌名称（当前导出为空） |
+| pdAssisnatLevel | pdAssisnatLevel | string→TEXT（原样） | 允许使用的“陪打/助教等级”列表 |
+| cxAssisnatLevel | cxAssisnatLevel | string→TEXT（原样） | 可能是“促销活动中的助教等级限制”（命名中 cx 多为“促销”缩写） |
+| able_share_member_discount | able_share_member_discount | bool→BOOLEAN | 是否共享会员折扣（新增字段） |
+| electricity_deduct_radio | electricity_deduct_radio | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 电费抵扣比例（百分比，100.0=全额可抵扣）（新增字段） |
+| electricity_discount | electricity_discount | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 电费折扣（10.0=不打折，采用"几折"记法）（新增字段） |
+| electricitycarddeduct | electricitycarddeduct | bool→BOOLEAN | 电费是否可从卡中抵扣（新增字段） |
+| member_grade | member_grade | int→BIGINT（`parse_int`） | 会员等级 ID（新增字段） |
+| principal_balance | principal_balance | float→NUMERIC(18,2)（`parse_decimal`） | 本金余额（储值卡中本金部分的余额）（新增字段） |
+| rechargefreezebalance | rechargefreezebalance | float→NUMERIC(18,2)（`parse_decimal`） | 充值冻结余额（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`member_stored_value_cards.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `MemberProfile/GetTenantMemberCardList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_GetTenantMemberList_member_profiles.md

@@ -0,0 +1,56 @@
+# 会员档案（GetTenantMemberList） → member_profiles 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `MemberProfile/GetTenantMemberList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.member_profiles` |
+| JSON 数据路径 | `data.tenantMemberInfos` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| register_site_id | register_site_id | int→BIGINT（`parse_int`） | 会员的注册门店 ID |
+| site_name | site_name | string→TEXT（原样） | 注册门店名称，属于冗余字段，用于直接展示 |
+| id | id | int→BIGINT（`parse_int`） | 这是“租户内会员账户”的主键 ID |
+| system_member_id | system_member_id | int→BIGINT（`parse_int`） | 这是“系统级会员 ID”，在全平台唯一，用来把一个会员在不同门店/不同卡类型下的账户统一到一个“人”的维度上 |
+| member_card_grade_code | member_card_grade_code | int→BIGINT（`parse_int`） | 这两个字段是成对出现的：一个数值码，一个中文名称 |
+| member_card_grade_name | member_card_grade_name | string→TEXT（原样） | 这是“会员卡种类/等级”的定义字段 |
+| mobile | mobile | string→TEXT（原样） | 会员绑定的手机号码 |
+| nickname | nickname | string→TEXT（原样） | 会员在当前租户下的显示名称（可以是姓名，也可以是昵称） |
+| point | point | float→NUMERIC(18,2)（`parse_decimal`） | 当前积分余额（这条会员账户的积分值） |
+| growth_value | growth_value | float→NUMERIC(18,2)（`parse_decimal`） | 成长值 / 经验值，用于会员等级晋升的累计指标 |
+| referrer_member_id | referrer_member_id | int→BIGINT（`parse_int`） | 推荐人会员 ID，用于记录该会员是由哪位老会员推荐 |
+| status | status | int→INT（`parse_int`） | 帐户状态（偏“卡状态/档案状态”） |
+| user_status | user_status | int→INT（`parse_int`） | 用户账号状态（偏“用户逻辑”层面的状态） |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 会员账户的创建时间（即这条档案/这张卡在系统中被创建的时间） |
+| pay_money_sum | pay_money_sum | float→NUMERIC(18,2)（`parse_decimal`） | 累计消费金额（新增字段，API 新版返回） |
+| person_tenant_org_id | person_tenant_org_id | int→BIGINT（`parse_int`） | 会员所属组织 ID（新增字段，API 新版返回） |
+| person_tenant_org_name | person_tenant_org_name | string→TEXT（原样） | 会员所属组织名称（新增字段，API 新版返回） |
+| recharge_money_sum | recharge_money_sum | float→NUMERIC(18,2)（`parse_decimal`） | 累计充值金额（新增字段，API 新版返回） |
+| register_source | register_source | string→TEXT（原样） | 注册来源（新增字段，API 新版返回） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`member_profiles.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `MemberProfile/GetTenantMemberList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_QueryGoodsOutboundReceipt_goods_stock_movements.md

@@ -0,0 +1,55 @@
+# 库存出入库流水（QueryGoodsOutboundReceipt） → goods_stock_movements 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `GoodsStockManage/QueryGoodsOutboundReceipt` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.goods_stock_movements` |
+| JSON 数据路径 | `data.queryDeliveryRecordsList` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| siteGoodsStockId | siteGoodsStockId | int→BIGINT（`parse_int`） | 门店某个“商品库存记录”的主键 ID |
+| tenantId | tenantId | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| siteId | siteId | int→BIGINT（`parse_int`） | 门店 ID |
+| siteGoodsId | siteGoodsId | int→BIGINT（`parse_int`） | 门店维度的商品 ID |
+| goodsName | goodsName | string→TEXT（原样） | 商品名称 |
+| goodsCategoryId | goodsCategoryId | int→BIGINT（`parse_int`） | 商品一级分类 ID |
+| goodsSecondCategoryId | goodsSecondCategoryId | int→BIGINT（`parse_int`） | 商品二级分类 ID |
+| unit | unit | string→TEXT（原样） | 库存计量单位 |
+| price | price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 商品单价（单位金额） |
+| stockType | stockType | int→INT（`parse_int`） | 1：89 条 |
+| changeNum | changeNum | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 本次库存数量变化值 |
+| startNum | startNum | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 变动前（这次出入库之前）的库存数量 |
+| endNum | endNum | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 变动后（出入库之后）的库存数量 |
+| changeNumA | changeNumA | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 辅助单位的变化量（与 changeNum 对应的第二计量单位变化），当前未使用 |
+| startNumA | startNumA | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 辅助计量单位的起始库存（例如件/箱等第二单位） |
+| endNumA | endNumA | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 辅助单位的变动后库存，同样未启用 |
+| remark | remark | string→TEXT（原样） | 备注信息，用于手工记录本次变更的特殊原因说明（例如“盘点差异调整”“报损”） |
+| operatorName | operatorName | string→TEXT（原样） | 执行此次库存变动的操作人 |
+| createTime | createTime | string→TIMESTAMP（`parse_timestamp`） | 这条库存变动记录的创建时间，即发生库存变更的时间点 |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`goods_stock_movements.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `GoodsStockManage/QueryGoodsOutboundReceipt` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_QueryPackageCouponList_group_buy_packages.md

@@ -0,0 +1,74 @@
+# 团购套餐定义（QueryPackageCouponList） → group_buy_packages 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `PackageCoupon/QueryPackageCouponList` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.group_buy_packages` |
+| JSON 数据路径 | `data.packageCouponList` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 门店侧套餐 ID，本文件内部的主键 |
+| package_id | package_id | int→BIGINT（`parse_int`） | “上层套餐 ID” 或“总部/系统级套餐 ID” |
+| package_name | package_name | string→TEXT（原样） | 团购套餐名称，用于前台展示和核销界面 |
+| selling_price | selling_price | float→NUMERIC(18,2)（`parse_decimal`） | 语义上应该是“团购售卖价”（顾客在平台购买券时的成交价格） |
+| coupon_money | coupon_money | float→NUMERIC(18,2)（`parse_decimal`） | 券面值或内部结算面值，表示该套餐在门店侧对应的金额额度 |
+| date_type | date_type | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| date_info | date_info | string→TEXT（原样） | 预留字段，通常用来存储更细粒度的日期信息，如具体日期列表、节假日特殊规则（可能是 JSON 字符串或编码） |
+| start_time | start_time | string→TIMESTAMP（`parse_timestamp`） | 套餐开始生效的日期时间 |
+| end_time | end_time | string→TIMESTAMP（`parse_timestamp`） | 套餐失效的日期时间（到这个时间点后不可使用） |
+| start_clock | start_clock | string→TEXT（原样） | 每日可用起始时间点（第一段） |
+| end_clock | end_clock | string→TEXT（原样） | 每日可用的结束时间点（第一段） |
+| add_start_clock | add_start_clock | string→TEXT（原样） | 附加可用时间段的起始时间（第二段） |
+| add_end_clock | add_end_clock | string→TEXT（原样） | 附加时段结束时间，多数情况配合 "00:00:00" 或 "10:00:00" 使用 |
+| duration | duration | int→INT（`parse_int`） | 套餐内包含的时长（秒） |
+| usable_count | usable_count | int→INT（`parse_int`） | 可使用次数上限 |
+| usable_range | usable_range | int→INT（`parse_int`） | 一般用于文字描述可用日期范围（例如“周一至周五”） |
+| table_area_id | table_area_id | int→BIGINT（`parse_int`） | 原始设计应为“单一台区 ID”，当套餐只限一个区域可以用这个字段存储 |
+| table_area_name | table_area_name | string→TEXT（原样） | 套餐适用的“门店台区名称”，用于显示和筛选 |
+| table_area_id_list | table_area_id_list | object→JSONB（原样存储） | 用来存放具体台区 ID 列表（例如 "1,2,3"），实现更细粒度的台桌限制 |
+| tenant_table_area_id | tenant_table_area_id | int→BIGINT（`parse_int`） | 与 table_area_id 类似，是租户层级的台区 ID，原本用于单区选择 |
+| tenant_table_area_id_list | tenant_table_area_id_list | object→JSONB（原样存储） | 实际代表“台区集合 ID”或“租户台区配置 ID”，用来限制套餐可用的台区范围 |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID |
+| site_name | site_name | string→TEXT（原样） | 门店名称 |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户 ID（品牌/商户 ID） |
+| card_type_ids | card_type_ids | object→JSONB（原样存储） | 原意是“适用会员卡类型 ID 列表”，例如某套餐只允许某几种会员卡使用，可以在此配置 |
+| group_type | group_type | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| system_group_type | system_group_type | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| type | type | int→INT（`parse_int`） | 内部业务子类型，具体含义需要结合系统文档 |
+| effective_status | effective_status | int→INT（`parse_int`） | 1：13 条 |
+| is_enabled | is_enabled | int→INT（`parse_int`） | 启用状态 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标志 |
+| max_selectable_categories | max_selectable_categories | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| area_tag_type | area_tag_type | int→INT（`parse_int`） | 1 很可能代表“按台区标签限制”，例如 A区、中八区、包厢、KTV 等 |
+| creator_name | creator_name | string→TEXT（原样） | 创建人信息，一般包含“角色：姓名” |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 该套餐在系统中创建的时间 |
+| is_first_limit | is_first_limit | bool→BOOLEAN | 是否限首次使用（新增字段） |
+| sort | sort | int→INT（`parse_int`） | 排序权重（新增字段） |
+| tenantcouponsaleorderitemid | tenantcouponsaleorderitemid | int→BIGINT（`parse_int`） | 租户券销售订单项 ID（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`group_buy_packages.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `PackageCoupon/QueryPackageCouponList` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_QueryPrimarySecondaryCategory_stock_goods_category_tree.md

@@ -0,0 +1,47 @@
+# 商品分类树（QueryPrimarySecondaryCategory） → stock_goods_category_tree 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `TenantGoodsCategory/QueryPrimarySecondaryCategory` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.stock_goods_category_tree` |
+| JSON 数据路径 | `data.goodsCategoryList` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 分类节点主键 ID（在商品分类维度中的唯一标识） |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户 ID（品牌/商户 ID） |
+| category_name | category_name | string→TEXT（原样） | 分类名称（实际业务分类名称） |
+| alias_name | alias_name | string→TEXT（原样） | 名称字段，用于展示与辅助识别 |
+| pid | pid | int→BIGINT（`parse_int`） | 父级分类 ID |
+| business_name | business_name | string→TEXT（原样） | 业务大类名称 |
+| tenant_goods_business_id | tenant_goods_business_id | int→BIGINT（`parse_int`） | 业务大类 ID |
+| open_salesman | open_salesman | int→INT（`parse_int`） | 是否启用“营业员”或“导购提成”相关的功能开关 |
+| categoryBoxes | categoryBoxes | object→JSONB（原样存储） | 子分类数组 |
+| sort | sort | int→INT（`parse_int`） | 分类的排序序号，用于前端展示顺序的控制 |
+| is_warehousing | is_warehousing | int→INT（`parse_int`） | 本文件可视为“所有参与库存管理的商品分类清单”，因此均为 1 |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`stock_goods_category_tree.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `TenantGoodsCategory/QueryPrimarySecondaryCategory` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_QueryTenantGoods_tenant_goods_master.md

@@ -0,0 +1,68 @@
+# 租户商品主数据（QueryTenantGoods） → tenant_goods_master 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `TenantGoods/QueryTenantGoods` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.tenant_goods_master` |
+| JSON 数据路径 | `data.tenantGoodsList` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 商品档案主键 ID，唯一标识一条商品 |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
+| goods_name | goods_name | string→TEXT（原样） | 商品名称（前台展示名称） |
+| goods_bar_code | goods_bar_code | string→TEXT（原样） | 商品条码（EAN 等），目前未维护 |
+| goods_category_id | goods_category_id | int→BIGINT（`parse_int`） | 商品一级分类 ID |
+| goods_second_category_id | goods_second_category_id | int→BIGINT（`parse_int`） | 商品二级分类 ID |
+| categoryName | categoryName | string→TEXT（原样） | 商品一级分类名称（业务可读） |
+| unit | unit | string→TEXT（原样） | 计量单位 |
+| goods_number | goods_number | string→TEXT（原样） | 商品内部编码（自定义货号/系统货号） |
+| out_goods_id | out_goods_id | string→TEXT（原样） | 外部系统商品 ID（对接第三方平台使用，如外卖、线上商城等） |
+| goods_state | goods_state | int→INT（`parse_int`） | 商品状态（上架/下架等） |
+| sale_channel | sale_channel | int→INT（`parse_int`） | 销售渠道类型，如“门店堂食/线下零售/线上小程序”等的一种编码 |
+| able_discount | able_discount | int→INT（`parse_int`） | 是否允许参与折扣/打折 |
+| able_site_transfer | able_site_transfer | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标志 |
+| is_warehousing | is_warehousing | int→INT（`parse_int`） | 是否启用库存管理 |
+| isInSite | isInSite | int→INT（`parse_int`） | 是否在当前门店启用/上架 |
+| cost_price | cost_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 成本价格 |
+| cost_price_type | cost_price_type | int→INT（`parse_int`） | 金额字段，用于计费/结算/分摊等金额计算 |
+| market_price | market_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 商品标价 / 售价（标准销售单价） |
+| min_discount_price | min_discount_price | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 该商品允许售卖的最低价格（底价） |
+| common_sale_royalty | common_sale_royalty | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 普通销售提成比例或提成金额的配置字段 |
+| point_sale_royalty | point_sale_royalty | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 积分销售提成/积分赠送规则相关配置 |
+| pinyin_initial | pinyin_initial | string→TEXT（原样） | 拼音首字母/助记码 |
+| commodityCode | commodityCode | string→TEXT（原样） | 与 commodity_code 是同一信息的数组形式（冗余存储），便于支持一个商品对应多个编码的场景 |
+| commodity_code | commodity_code | string→TEXT（原样） | 商品编码（通常为对外商品编码或条码） |
+| goods_cover | goods_cover | string→TEXT（原样） | 商品封面图片 URL 地址 |
+| supplier_id | supplier_id | int→BIGINT（`parse_int`） | 供应商 ID，用于关联到供应商档案 |
+| remark_name | remark_name | string→TEXT（原样） | 商品备注名/别名，通常用来配置简写或特殊显示名称 |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 商品档案创建时间 |
+| update_time | update_time | string→TIMESTAMP（`parse_timestamp`） | 商品档案最近一次修改时间 |
+| not_sale | not_sale | bool→INTEGER | 是否禁售（新增字段） |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`tenant_goods_master.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `TenantGoods/QueryTenantGoods` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_SearchAssistantInfo_assistant_accounts_master.md

@@ -0,0 +1,98 @@
+# 助教账号主数据（SearchAssistantInfo） → assistant_accounts_master 字段映射
+
+> 生成时间：2026-02-14
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `PersonnelManagement/SearchAssistantInfo` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.assistant_accounts_master` |
+| JSON 数据路径 | `data.assistantInfos` |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT（`parse_int`） | 助教账号主键 ID，在“助教流水.json”中对应 site_assistant_id |
+| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 品牌/租户 ID，对应“非球科技”系统中该商户的唯一标识 |
+| site_id | site_id | int→BIGINT（`parse_int`） | 门店 ID，对应本次数据的这家球房（朗朗桌球） |
+| assistant_no | assistant_no | string→TEXT（原样） | 助教工号 / 编号，便于业务侧识别 |
+| nickname | nickname | string→TEXT（原样） | 助教在前台展示的昵称，如“佳怡”“周周”“球球”等 |
+| real_name | real_name | string→TEXT（原样） | 助教真实姓名，如“何海婷”“梁婷婷”等 |
+| mobile | mobile | string→TEXT（原样） | 助教手机号，用于登录绑定、通知、钉钉同步等 |
+| team_id | team_id | int→BIGINT（`parse_int`） | 助教所属团队 ID |
+| team_name | team_name | string→TEXT（原样） | 团队名称，展示用，和 team_id 一一对应 |
+| user_id | user_id | int→BIGINT（`parse_int`） | 系统级“用户账号 ID”，通常对应登录账号 |
+| level | level | string→TEXT（原样） | 10 × 24 |
+| assistant_status | assistant_status | int→INT（`parse_int`） | 1 × 48 |
+| work_status | work_status | int→INT（`parse_int`） | 当 leave_status = 0 时，work_status = 1 |
+| leave_status | leave_status | int→INT（`parse_int`） | 0 × 21 |
+| entry_time | entry_time | string→TIMESTAMP（`parse_timestamp`） | 入职时间 |
+| resign_time | resign_time | string→TIMESTAMP（`parse_timestamp`） | 离职日期 |
+| start_time | start_time | string→TIMESTAMP（`parse_timestamp`） | 当前配置生效的开始日期 |
+| end_time | end_time | string→TIMESTAMP（`parse_timestamp`） | 当前配置生效的结束日期（例如一个周期性的排班/合同周期） |
+| create_time | create_time | string→TIMESTAMP（`parse_timestamp`） | 账号创建时间 |
+| update_time | update_time | string→TIMESTAMP（`parse_timestamp`） | 账号最近一次被修改的时间（例如修改等级、昵称等） |
+| order_trade_no | order_trade_no | string→TEXT（原样） | 该助教最近一次关联的订单号，用于快速跳转或回溯最近服务行为 |
+| staff_id | staff_id | int→BIGINT（`parse_int`） | 预留给“人事系统员工 ID”的字段，目前未接入或未启用 |
+| staff_profile_id | staff_profile_id | int→BIGINT（`parse_int`） | 人事档案 ID，与第三方 HR 系统或内部员工档案集成使用，当前未启用 |
+| system_role_id | system_role_id | int→BIGINT（`parse_int`） | 标识类 ID 字段，用于关联/定位相关实体 |
+| avatar | avatar | string→TEXT（原样） | 助教头像地址 |
+| birth_date | birth_date | string→TIMESTAMP（`parse_timestamp`） | 助教出生日期 |
+| gender | gender | int→INT（`parse_int`） | 0 × 40 |
+| height | height | float→NUMERIC(18,2)（`parse_decimal`） | 身高（单位：厘米） |
+| weight | weight | float→NUMERIC(18,2)（`parse_decimal`） | 体重（单位：公斤） |
+| job_num | job_num | string→TEXT（原样） | 备用工号字段，目前未在该门店启用 |
+| show_status | show_status | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| show_sort | show_sort | int→INT（`parse_int`） | 前台展示排序权重，值越小/越大对应不同的排序策略（当前看起来与 assistant_no 有一定对应关系） |
+| sum_grade | sum_grade | float→NUMERIC(18,2)（`parse_decimal`） | 评分总和，用于计算平均分（assistant_grade = sum_grade / get_grade_times），当前为 0 |
+| assistant_grade | assistant_grade | float→NUMERIC(18,2)（`parse_decimal`） | 助教综合评分（员工维度的平均分 snapshot），当前尚未启用评分 |
+| get_grade_times | get_grade_times | int→INT（`parse_int`） | 累计被评分次数 |
+| introduce | introduce | string→TEXT（原样） | 个人简介文案，预留给助教自我介绍使用 |
+| video_introduction_url | video_introduction_url | string→TEXT（原样） | 助教个人视频介绍地址 |
+| group_id | group_id | int→BIGINT（`parse_int`） | 上层“分组 ID”预留字段（例如集团/事业部），本门店未使用 |
+| group_name | group_name | string→TEXT（原样） | group_id 对应的名称，目前为空 |
+| shop_name | shop_name | string→TEXT（原样） | 门店名称，冗余字段，用于展示 |
+| charge_way | charge_way | int→INT（`parse_int`） | 2 代表当前门店为“计时收费”，其他值（1、3 等）可能对应按局、按课时等，当前未出现 |
+| entry_type | entry_type | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| allow_cx | allow_cx | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| is_guaranteed | is_guaranteed | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| salary_grant_enabled | salary_grant_enabled | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| light_status | light_status | int→INT（`parse_int`） | 灯光控制状态，如 1=启用控制、2=不启用 或相反 |
+| online_status | online_status | int→INT（`parse_int`） | 在线状态 |
+| is_delete | is_delete | int→INT（`parse_int`） | 逻辑删除标记（0=否，1=是） |
+| cx_unit_price | cx_unit_price | float→NUMERIC(18,2)（`parse_decimal`） | 促销时段的单价，本门店未在账号表层面设置 |
+| pd_unit_price | pd_unit_price | float→NUMERIC(18,2)（`parse_decimal`） | 某种标准单价（例如“普通时段单价”），这里未在账号上配置（实际单价在助教商品或套餐配置中） |
+| last_table_id | last_table_id | int→BIGINT（`parse_int`） | 该助教最近一次服务的球台 ID |
+| last_table_name | last_table_name | string→TEXT（原样） | 最近服务球台名称（展示用） |
+| person_org_id | person_org_id | int→BIGINT（`parse_int`） | 人事组织 ID，通常表示“某某门店-助教部-某小组”等层级组织 |
+| serial_number | serial_number | int→BIGINT（`parse_int`） | 系统内部生成的序列号或排序标识，用于全局排序或迁移 |
+| is_team_leader | is_team_leader | int→INT（`parse_int`） | 布尔/开关字段，用于表示权限、可用性或状态开关 |
+| criticism_status | criticism_status | int→INT（`parse_int`） | 1 × 49 |
+| last_update_name | last_update_name | string→TEXT（原样） | 最近修改该账号配置的管理员名称 |
+| ding_talk_synced | ding_talk_synced | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| site_light_cfg_id | site_light_cfg_id | int→BIGINT（`parse_int`） | 门店灯控配置 ID，本门店未在助教账号维度启用 |
+| light_equipment_id | light_equipment_id | string→TEXT（原样） | 灯控设备 ID，如果开启“助教开台自动控制灯”，会通过该字段关联到灯控硬件 |
+| entry_sign_status | entry_sign_status | int→INT（`parse_int`） | 来自 JSON 导出的原始字段，用于保留业务取值 |
+| resign_sign_status | resign_sign_status | int→INT（`parse_int`） | 离职协议签署状态，类似上面 |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
+| source_file | 固定值：`assistant_accounts_master.json`，标识原始导出文件 |
+| source_endpoint | API 端点路径，如 `PersonnelManagement/SearchAssistantInfo` |
+| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
+| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
+
+## 类型转换规则
+
+- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
+- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
+- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
+- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
+- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
+- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储