root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init: 项目初始提交 - NeoZQYY Monorepo 完整代码

Browse Source
This commit is contained in:
Neo
2026-02-15 14:58:14 +08:00
commit ded6dfb9d8
769 changed files with 182616 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/.gitkeep Normal file
View File

50
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetAbolitionAssistant_assistant_cancellation_records.md Normal file
View File

@@ -0,0 +1,50 @@
# 助教撤销记录（GetAbolitionAssistant） → assistant_cancellation_records 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `AssistantPerformance/GetAbolitionAssistant` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

102
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetAllOrderSettleList_settlement_records.md Normal file
View File

@@ -0,0 +1,102 @@
# 结账记录（GetAllOrderSettleList） → settlement_records 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetAllOrderSettleList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

83
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetGoodsInventoryList_store_goods_master.md Normal file
View File

@@ -0,0 +1,83 @@
# 门店商品库存主数据（GetGoodsInventoryList） → store_goods_master 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/GetGoodsInventoryList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

87
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetGoodsSalesList_store_goods_sales_records.md Normal file
View File

@@ -0,0 +1,87 @@
# 门店商品销售记录（GetGoodsSalesList） → store_goods_sales_records 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/GetGoodsSalesList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

50
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetGoodsStockReport_goods_stock_summary.md Normal file
View File

@@ -0,0 +1,50 @@
# 库存汇总报表（GetGoodsStockReport） → goods_stock_summary 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/GetGoodsStockReport` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

64
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetMemberCardBalanceChange_member_balance_changes.md Normal file
View File

@@ -0,0 +1,64 @@
# 会员余额变动（GetMemberCardBalanceChange） → member_balance_changes 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `MemberProfile/GetMemberCardBalanceChange` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

62
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetOfflineCouponConsumePageList_platform_coupon_redemption_records.md Normal file
View File

@@ -0,0 +1,62 @@
# 平台券核销记录（GetOfflineCouponConsumePageList） → platform_coupon_redemption_records 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Promotion/GetOfflineCouponConsumePageList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

102
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetOrderAssistantDetails_assistant_service_records.md Normal file
View File

@@ -0,0 +1,102 @@
# 助教服务流水（GetOrderAssistantDetails） → assistant_service_records 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `AssistantPerformance/GetOrderAssistantDetails` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

74
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetOrderSettleTicketNew_settlement_ticket_details.md Normal file
View File

@@ -0,0 +1,74 @@
# 结账小票明细（GetOrderSettleTicketNew） → settlement_ticket_details 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Order/GetOrderSettleTicketNew` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

48
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetPayLogListPage_payment_transactions.md Normal file
View File

@@ -0,0 +1,48 @@
# 支付流水（GetPayLogListPage） → payment_transactions 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `PayLog/GetPayLogListPage` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

102
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetRechargeSettleList_recharge_settlements.md Normal file
View File

@@ -0,0 +1,102 @@
# 充值结算记录（GetRechargeSettleList） → recharge_settlements 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetRechargeSettleList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

68
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetRefundPayLogList_refund_transactions.md Normal file
View File

@@ -0,0 +1,68 @@
# 退款流水（GetRefundPayLogList） → refund_transactions 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Order/GetRefundPayLogList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

78
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetSiteTableOrderDetails_table_fee_transactions.md Normal file
View File

@@ -0,0 +1,78 @@
# 台费流水（GetSiteTableOrderDetails） → table_fee_transactions 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetSiteTableOrderDetails` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

88
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetSiteTableUseDetails_group_buy_redemption_records.md Normal file
View File

@@ -0,0 +1,88 @@
# 团购核销记录（GetSiteTableUseDetails） → group_buy_redemption_records 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetSiteTableUseDetails` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

62
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetSiteTables_site_tables_master.md Normal file
View File

@@ -0,0 +1,62 @@
# 台桌主数据（GetSiteTables） → site_tables_master 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Table/GetSiteTables` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

64
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetTaiFeeAdjustList_table_fee_discount_records.md Normal file
View File

@@ -0,0 +1,64 @@
# 台费优惠记录（GetTaiFeeAdjustList） → table_fee_discount_records 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `Site/GetTaiFeeAdjustList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

111
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetTenantMemberCardList_member_stored_value_cards.md Normal file
View File

@@ -0,0 +1,111 @@
# 会员储值卡（GetTenantMemberCardList） → member_stored_value_cards 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `MemberProfile/GetTenantMemberCardList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

56
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_GetTenantMemberList_member_profiles.md Normal file
View File

@@ -0,0 +1,56 @@
# 会员档案（GetTenantMemberList） → member_profiles 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `MemberProfile/GetTenantMemberList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

55
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_QueryGoodsOutboundReceipt_goods_stock_movements.md Normal file
View File

@@ -0,0 +1,55 @@
# 库存出入库流水（QueryGoodsOutboundReceipt） → goods_stock_movements 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `GoodsStockManage/QueryGoodsOutboundReceipt` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

74
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_QueryPackageCouponList_group_buy_packages.md Normal file
View File

@@ -0,0 +1,74 @@
# 团购套餐定义（QueryPackageCouponList） → group_buy_packages 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `PackageCoupon/QueryPackageCouponList` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

47
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_QueryPrimarySecondaryCategory_stock_goods_category_tree.md Normal file
View File

@@ -0,0 +1,47 @@
# 商品分类树（QueryPrimarySecondaryCategory） → stock_goods_category_tree 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoodsCategory/QueryPrimarySecondaryCategory` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

68
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_QueryTenantGoods_tenant_goods_master.md Normal file
View File

@@ -0,0 +1,68 @@
# 租户商品主数据（QueryTenantGoods） → tenant_goods_master 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/QueryTenantGoods` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储

98
apps/etl/pipelines/feiqiu/docs/database/ODS/mappings/mapping_SearchAssistantInfo_assistant_accounts_master.md Normal file
View File

@@ -0,0 +1,98 @@
# 助教账号主数据（SearchAssistantInfo） → assistant_accounts_master 字段映射
> 生成时间：2026-02-14
## 端点信息
| 属性 | 值 |
|------|-----|
| 接口路径 | `PersonnelManagement/SearchAssistantInfo` |
| 请求方法 | POST |
| ODS 对应表 | `billiards_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` 类型存储