# ODS 数据字典

## 概述

ODS（Operational Data Store）层是数据仓库的操作数据存储层，保留从上游 SaaS API 抽取的原始数据。所有 ODS 表位于 `ods` schema，字段以 API 导出原样为主，ETL 补充 `content_hash`、`source_file`、`source_endpoint`、`fetched_at`、`payload` 等元数据字段。

- Schema：`ods`
- 来源 DDL：`database/schema_ODS_doc.sql`
- 主键模式：所有 ODS 表均采用 `(业务主键, content_hash)` 复合主键，用于 SCD 变更检测
- 表级文档：`docs/database/ODS/main/BD_manual_{表名}.md`
- 字段映射文档：`docs/database/ODS/mappings/mapping_{API端点名}_{表名}.md`

## 表清单

| 序号 | 表名 | 中文说明 | 主键 | 记录数 | 数据来源（API 端点） |
|------|------|----------|------|-------:|----------------------|
| 1 | `assistant_accounts_master` | 助教档案主数据 | id, content_hash | 223 | `PersonnelManagement/SearchAssistantInfo` |
| 2 | `assistant_cancellation_records` | 助教作废/取消记录 | id, content_hash | 100 | `AssistantPerformance/GetAbolitionAssistant` |
| 3 | `assistant_service_records` | 助教服务流水 | id, content_hash | 10,203 | `AssistantPerformance/GetOrderAssistantDetails` |
| 4 | `goods_stock_movements` | 商品库存变动流水 | sitegoodsstockid, content_hash | 35,005 | `GoodsStockManage/QueryGoodsOutboundReceipt` |
| 5 | `goods_stock_summary` | 商品库存汇总 | sitegoodsid, content_hash | 867 | `TenantGoods/GetGoodsStockReport` |
| 6 | `group_buy_packages` | 团购套餐主数据 | id, content_hash | 52 | `PackageCoupon/QueryPackageCouponList` |
| 7 | `group_buy_redemption_records` | 团购核销记录 | id, content_hash | 19,532 | `Site/GetSiteTableUseDetails` |
| 8 | `member_balance_changes` | 会员余额变更流水 | id, content_hash | 7,366 | `MemberProfile/GetMemberCardBalanceChange` |
| 9 | `member_profiles` | 会员档案/会员账户信息 | id, content_hash | 1,202 | `MemberProfile/GetTenantMemberList` |
| 10 | `member_stored_value_cards` | 会员储值/卡券账户列表 | id, content_hash | 2,008 | `MemberProfile/GetTenantMemberCardList` |
| 11 | `payment_transactions` | 支付流水 | id, content_hash | 24,674 | `PayLog/GetPayLogListPage` |
| 12 | `platform_coupon_redemption_records` | 平台券核销/使用记录 | id, content_hash | 18,125 | `Promotion/GetOfflineCouponConsumePageList` |
| 13 | `recharge_settlements` | 充值结算记录 | id, content_hash | 3,333 | `Site/GetRechargeSettleList` |
| 14 | `refund_transactions` | 退款流水 | id, content_hash | 50 | `Order/GetRefundPayLogList` |
| 15 | `settlement_records` | 结账/结算记录 | id, content_hash | 55,137 | `Site/GetAllOrderSettleList` |
| 16 | `settlement_ticket_details` | 结算小票明细 | ordersettleid, content_hash | 193 | `Order/GetOrderSettleTicketNew` |
| 17 | `site_tables_master` | 门店桌台主数据 | id, content_hash | 949 | `Table/GetSiteTables` |
| 18 | `stock_goods_category_tree` | 商品分类树 | id, content_hash | 9 | `TenantGoodsCategory/QueryPrimarySecondaryCategory` |
| 19 | `store_goods_master` | 门店商品主数据 | id, content_hash | 1,398 | `TenantGoods/GetGoodsInventoryList` |
| 20 | `store_goods_sales_records` | 门店商品销售流水 | id, content_hash | 17,563 | `TenantGoods/GetGoodsSalesList` |
| 21 | `table_fee_discount_records` | 台费折扣记录 | id, content_hash | 3,100 | `Site/GetTaiFeeAdjustList` |
| 22 | `table_fee_transactions` | 台费流水 | id, content_hash | 28,881 | `Site/GetSiteTableOrderDetails` |
| 23 | `tenant_goods_master` | 租户商品主数据 | id, content_hash | 176 | `TenantGoods/QueryTenantGoods` |

## 按业务域分类

### 会员域

| 表名 | 说明 | 记录数 |
|------|------|-------:|
| `member_profiles` | 会员档案/会员账户信息 | 1,202 |
| `member_stored_value_cards` | 会员储值/卡券账户列表 | 2,008 |
| `member_balance_changes` | 会员余额变更流水 | 7,366 |

### 助教域

| 表名 | 说明 | 记录数 |
|------|------|-------:|
| `assistant_accounts_master` | 助教档案主数据 | 223 |
| `assistant_service_records` | 助教服务流水 | 10,203 |
| `assistant_cancellation_records` | 助教作废/取消记录 | 100 |

### 订单/结算域

| 表名 | 说明 | 记录数 |
|------|------|-------:|
| `settlement_records` | 结账/结算记录 | 55,137 |
| `settlement_ticket_details` | 结算小票明细 | 193 |
| `payment_transactions` | 支付流水 | 24,674 |
| `refund_transactions` | 退款流水 | 50 |
| `recharge_settlements` | 充值结算记录 | 3,333 |

### 台费域

| 表名 | 说明 | 记录数 |
|------|------|-------:|
| `table_fee_transactions` | 台费流水 | 28,881 |
| `table_fee_discount_records` | 台费折扣记录 | 3,100 |
| `site_tables_master` | 门店桌台主数据 | 949 |

### 商品/库存域

| 表名 | 说明 | 记录数 |
|------|------|-------:|
| `tenant_goods_master` | 租户商品主数据 | 176 |
| `store_goods_master` | 门店商品主数据 | 1,398 |
| `store_goods_sales_records` | 门店商品销售流水 | 17,563 |
| `stock_goods_category_tree` | 商品分类树 | 9 |
| `goods_stock_summary` | 商品库存汇总 | 867 |
| `goods_stock_movements` | 商品库存变动流水 | 35,005 |

### 团购/平台域

| 表名 | 说明 | 记录数 |
|------|------|-------:|
| `group_buy_packages` | 团购套餐主数据 | 52 |
| `group_buy_redemption_records` | 团购核销记录 | 19,532 |
| `platform_coupon_redemption_records` | 平台券核销/使用记录 | 18,125 |

---

## ETL 元数据字段说明

所有 ODS 表均包含以下 ETL 补充字段：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `content_hash` | TEXT | 对业务字段计算 SHA256，作为复合主键的一部分，用于 SCD 变更检测 |
| `source_file` | TEXT | 数据来源文件名（如 `member_profiles.json`） |
| `source_endpoint` | TEXT | 数据来源 API 端点路径 |
| `fetched_at` | TIMESTAMPTZ | 数据抓取/入库时间戳 |
| `payload` | JSONB | 完整原始 JSON 记录快照，用于数据回溯 |

## 数据更新策略

| 更新方式 | 说明 |
|----------|------|
| 全量抓取 | 主数据表（`*_master`、`*_profiles`、`*_packages`、`*_tree`）每次全量拉取 |
| 增量抓取 | 流水/事实表（`*_records`、`*_transactions`、`*_changes`）按时间窗口增量拉取 |
| 幂等入库 | 通过 `(业务主键, content_hash)` 复合主键实现 upsert，相同内容不重复写入 |

## 相关文档

- 表级文档：[`docs/database/ODS/main/`](../ODS/main/) — 每张表的详细字段说明
- 字段映射：[`docs/database/ODS/mappings/`](../ODS/mappings/) — API JSON → ODS 字段映射
- DDL 定义：[`database/schema_ODS_doc.sql`](../../database/schema_ODS_doc.sql)
- DWD 数据字典：[`docs/database/overview/dwd_main_tables_dictionary.md`](dwd_main_tables_dictionary.md)
- DWS 数据字典：[`docs/database/overview/dws_tables_dictionary.md`](dws_tables_dictionary.md)
