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

1

Browse Source
This commit is contained in:
Neo
2026-03-15 10:15:02 +08:00
parent 2dd217522c
commit 72bb11b34f
916 changed files with 65306 additions and 16102803 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_assistant_accounts_master.md Normal file
View File

@@ -0,0 +1,106 @@
# BD_Manual：assistant_accounts_master（助教账号档案）
> ODS 表：`ods.assistant_accounts_master`
> DWD 表：`dwd.dim_assistant`（主表）、`dwd.dim_assistant_ex`（扩展表）
> API 接口：助教账号列表
> JSON 路径：`assistant_accounts_master.json → data.assistantInfos`
> 装载方式：SCD2 维度合并（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dim_assistant（主表）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `assistant_id` | BIGINT | `id` | FACT_MAPPINGS | 助教唯一标识（PK 之一） | 飞球系统雪花 ID，如 `2947562271297029` |
| `user_id` | BIGINT | `user_id` | FACT_MAPPINGS | 关联的系统用户 ID，0 表示未绑定用户账号 | `0` 或飞球用户 ID |
| `assistant_no` | TEXT | `assistant_no` | 自动映射 | 助教编号（门店内序号），用于排班和展示 | 如 `31`、`1` |
| `real_name` | TEXT | `real_name` | 自动映射 | 助教真实姓名 | 如 `张静然` |
| `nickname` | TEXT | `nickname` | 自动映射 | 助教昵称，用于小程序端展示 | 如 `小然` |
| `mobile` | TEXT | `mobile` | 自动映射 | 助教手机号 | 11 位手机号 |
| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 所属租户 ID | 飞球租户 ID |
| `site_id` | BIGINT | `site_id` | 自动映射 | 所属门店 ID | 飞球门店 ID |
| `team_id` | BIGINT | `team_id` | 自动映射 | 所属团队 ID，0 表示未分组 | `0` 或团队 ID |
| `team_name` | TEXT | `team_name` | 自动映射 | 团队名称 | 如 `1组`，NULL 表示未分组 |
| `level` | INTEGER | `level` | 自动映射 | 助教等级（技能等级编号） | 如 `20`（对应"高级"等） |
| `entry_time` | TIMESTAMPTZ | `entry_time` | 自动映射 | 入职时间 | ISO 时间戳 |
| `resign_time` | TIMESTAMPTZ | `resign_time` | 自动映射 | 离职时间，NULL 表示在职 | ISO 时间戳或 NULL |
| `leave_status` | INTEGER | `leave_status` | 自动映射 | 在职状态：0=在职，1=已离职 | `0` / `1` |
| `assistant_status` | INTEGER | `assistant_status` | 自动映射 | 助教状态：1=正常，2=停用 | `1` / `2` |
| `scd2_start_time` | TIMESTAMPTZ | — | DWD 元数据 | SCD2 版本生效起点 | — |
| `scd2_end_time` | TIMESTAMPTZ | — | DWD 元数据 | SCD2 版本失效时间，`9999-12-31` 表示当前版本 | — |
| `scd2_is_current` | INT | — | DWD 元数据 | 当前版本标记：1=当前，0=历史 | `0` / `1` |
| `scd2_version` | INT | — | DWD 元数据 | SCD2 版本号（自增） | — |
---
## 2. dim_assistant_ex（扩展表）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `assistant_id` | BIGINT | `id` | FACT_MAPPINGS | 助教唯一标识（PK 之一） | 同主表 |
| `gender` | INTEGER | `gender` | 自动映射 | 性别：0=未设置 | `0` |
| `birth_date` | TIMESTAMPTZ | `birth_date` | 自动映射 | 出生日期 | `0001-01-01` 表示未设置 |
| `avatar` | TEXT | `avatar` | 自动映射 | 头像 URL | HTTPS 链接 |
| `introduce` | TEXT | `introduce` | FACT_MAPPINGS | 个人简介文本 | 自由文本或 NULL |
| `video_introduction_url` | TEXT | `video_introduction_url` | 自动映射 | 视频介绍 URL | HTTPS 链接或 NULL |
| `height` | NUMERIC(5,2) | `height` | 自动映射 | 身高（cm），0 表示未填写 | `0.00` 或实际身高 |
| `weight` | NUMERIC(5,2) | `weight` | 自动映射 | 体重（kg），0 表示未填写 | `0.00` 或实际体重 |
| `shop_name` | TEXT | `shop_name` | 自动映射 | 所属门店名称快照 | 如 `朗朗桌球` |
| `group_id` | BIGINT | `group_id` | 自动映射 | 分组 ID，0 表示未分组 | `0` 或分组 ID |
| `group_name` | TEXT | `group_name` | FACT_MAPPINGS | 分组名称 | NULL 或分组名 |
| `person_org_id` | BIGINT | `person_org_id` | 自动映射 | 人事组织 ID | 飞球组织 ID |
| `staff_id` | BIGINT | `staff_id` | 自动映射 | 员工 ID，0 表示未绑定员工档案 | `0` 或员工 ID |
| `staff_profile_id` | BIGINT | `staff_profile_id` | 自动映射 | 员工档案 ID，0 表示无档案 | `0` 或档案 ID |
| `assistant_grade` | DOUBLE PRECISION | `assistant_grade` | 自动映射 | 助教评分（客户评价均分） | `0.0` ~ `5.0` |
| `sum_grade` | DOUBLE PRECISION | `sum_grade` | 自动映射 | 累计评分总和 | `0.0` 或累计值 |
| `get_grade_times` | INTEGER | `get_grade_times` | 自动映射 | 被评价次数 | `0` 或正整数 |
| `charge_way` | INTEGER | `charge_way` | 自动映射 | 计费方式：2=按时长计费（当前门店全部为 2） | `2` |
| `allow_cx` | INTEGER | `allow_cx` | 自动映射 | 是否允许促销服务：1=允许（当前全部为 1） | `1` |
| `is_guaranteed` | INTEGER | `is_guaranteed` | 自动映射 | 是否保底：0=不保底，1=保底 | `0` / `1` |
| `salary_grant_enabled` | INTEGER | `salary_grant_enabled` | 自动映射 | 工资发放开关：2=启用 | `2` |
| `entry_type` | INTEGER | `entry_type` | 自动映射 | 入职类型：1=正常入职 | `1` |
| `entry_sign_status` | INTEGER | `entry_sign_status` | 自动映射 | 入职签到状态：0=未签到 | `0` |
| `resign_sign_status` | INTEGER | `resign_sign_status` | 自动映射 | 离职签到状态：0=未签到 | `0` |
| `work_status` | INTEGER | `work_status` | 自动映射 | 工作状态：1=在岗，2=离岗 | `1` / `2` |
| `show_status` | INTEGER | `show_status` | 自动映射 | 展示状态：1=展示 | `1` |
| `show_sort` | INTEGER | `show_sort` | 自动映射 | 展示排序序号 | 正整数 |
| `online_status` | INTEGER | `online_status` | 自动映射 | 在线状态：1=在线 | `1` |
| `is_delete` | INTEGER | `is_delete` | 自动映射 | 软删除标记：0=正常，1=已删除 | `0` / `1` |
| `criticism_status` | INTEGER | `criticism_status` | 自动映射 | 差评处理状态：1=正常 | `1` |
| `create_time` | TIMESTAMPTZ | `create_time` | 自动映射 | 助教记录创建时间 | ISO 时间戳 |
| `update_time` | TIMESTAMPTZ | `update_time` | 自动映射 | 助教记录最后更新时间 | ISO 时间戳 |
| `start_time` | TIMESTAMPTZ | `start_time` | 自动映射 | 合同/排班开始时间 | ISO 时间戳 |
| `end_time` | TIMESTAMPTZ | `end_time` | 自动映射 | 合同/排班结束时间 | ISO 时间戳 |
| `last_table_id` | BIGINT | `last_table_id` | 自动映射 | 最近服务的台桌 ID，0 表示无 | `0` 或台桌 ID |
| `last_table_name` | TEXT | `last_table_name` | 自动映射 | 最近服务的台桌名称 | 如 `TV`、`1号台` |
| `last_update_name` | TEXT | `last_update_name` | 自动映射 | 最后操作人姓名（带职位前缀） | 如 `管理员：郑丽珊` |
| `order_trade_no` | BIGINT | `order_trade_no` | 自动映射 | 当前关联的订单交易号，0 表示空闲 | `0` 或订单号 |
| `ding_talk_synced` | INTEGER | `ding_talk_synced` | 自动映射 | 钉钉同步状态：1=已同步 | `1` |
| `site_light_cfg_id` | BIGINT | `site_light_cfg_id` | 自动映射 | 门店灯控配置 ID，0 表示未配置 | `0` 或配置 ID |
| `light_equipment_id` | TEXT | `light_equipment_id` | FACT_MAPPINGS | 灯控设备 ID | NULL 或设备编号 |
| `light_status` | INTEGER | `light_status` | 自动映射 | 台灯状态：2=已开灯 | `1` / `2` |
| `is_team_leader` | INTEGER | `is_team_leader` | 自动映射 | 是否组长：0=否，1=是 | `0` / `1` |
| `serial_number` | BIGINT | `serial_number` | 自动映射 | 序列号，0 表示未分配 | `0` 或序列号 |
| `system_role_id` | BIGINT | `system_role_id` | FACT_MAPPINGS | 系统角色 ID，标识助教在系统中的角色类型。当前门店全部为 10 | `10` |
| `job_num` | TEXT | `job_num` | FACT_MAPPINGS | 工号，助教的内部编号标识。当前门店未启用，全部为 NULL | NULL |
| `cx_unit_price` | NUMERIC(18,2) | `cx_unit_price` | FACT_MAPPINGS | 促销单价（元），助教提供促销服务时的计费单价。当前门店未在账号表层面设置，全部为 0.00 | `0.00` |
| `pd_unit_price` | NUMERIC(18,2) | `pd_unit_price` | FACT_MAPPINGS | 陪打单价（元），助教提供陪打服务时的计费单价。当前门店未在账号表层面设置，全部为 0.00 | `0.00` |
| `scd2_*` | — | — | DWD 元数据 | SCD2 慢变维度追踪字段（同主表） | — |
---
## 3. 跳过字段说明
| ODS 字段 | 跳过原因 |
|---------|---------|
| `siteprofile` | JSONB 嵌套列，已由 `dim_site` / `dim_site_ex` 通过 JSONB 提取映射 |
---
## 4. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dim_assistant"]` / `FACT_MAPPINGS["dwd.dim_assistant_ex"]`
- TABLE_MAP：`"dwd.dim_assistant" → "ods.assistant_accounts_master"`
- DWS 下游：`dws_assistant_daily_task.py`（助教日业绩汇总）、`dws_salary_task.py`（工资计算）

114
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_assistant_service_records.md Normal file
View File

@@ -0,0 +1,114 @@
# BD_Manual：assistant_service_records（助教服务流水）
> ODS 表：`ods.assistant_service_records`
> DWD 表：`dwd.dwd_assistant_service_log`（主表）、`dwd.dwd_assistant_service_log_ex`（扩展表）
> API 接口：助教服务记录列表
> JSON 路径：`assistant_service_records.json → data.orderAssistantLedgers`
> 装载方式：事实表增量插入（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dwd_assistant_service_log（主表，33 列）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `assistant_service_id` | BIGINT | `id` | FACT_MAPPINGS | 助教服务记录唯一标识（PK） | 飞球雪花 ID |
| `order_trade_no` | BIGINT | `order_trade_no` | 自动映射 | 关联的订单交易号 | 飞球订单号 |
| `order_settle_id` | BIGINT | `order_settle_id` | 自动映射 | 关联的结算单 ID | 飞球结算单 ID |
| `order_pay_id` | BIGINT | `order_pay_id` | 自动映射 | 关联的支付单 ID | 飞球支付单 ID |
| `order_assistant_id` | BIGINT | `order_assistant_id` | 自动映射 | 订单级助教明细 ID，标识本次服务在订单中的唯一记录 | 飞球雪花 ID |
| `order_assistant_type` | INTEGER | `order_assistant_type` | 自动映射 | 助教服务类型：1=陪打，2=促销 | `1` / `2` |
| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 租户 ID | 飞球租户 ID |
| `site_id` | BIGINT | `site_id` | 自动映射 | 门店 ID | 飞球门店 ID |
| `site_table_id` | BIGINT | `site_table_id` | 自动映射 | 服务台桌 ID，关联 `dim_table.table_id` | 飞球台桌 ID |
| `tenant_member_id` | BIGINT | `tenant_member_id` | 自动映射 | 租户维度会员 ID | 飞球会员 ID 或 0 |
| `system_member_id` | BIGINT | `system_member_id` | 自动映射 | 系统维度会员 ID（跨租户唯一） | 飞球会员 ID 或 0 |
| `assistant_no` | VARCHAR(64) | `assistantno` | FACT_MAPPINGS | 助教编号（门店内序号） | 如 `31` |
| `nickname` | VARCHAR(64) | `nickname` | 自动映射 | 助教昵称 | 如 `小张` |
| `site_assistant_id` | BIGINT | `site_assistant_id` | FACT_MAPPINGS | 门店维度助教档案 ID，关联 `dim_assistant.assistant_id`。⚠️ 已于 2026-02-20 修正映射源（原错误映射自 `order_assistant_id`） | 飞球助教 ID |
| `user_id` | BIGINT | `user_id` | 自动映射 | 助教用户 ID | 飞球用户 ID |
| `assistant_team_id` | BIGINT | `assistant_team_id` | 自动映射 | 助教团队 ID | 飞球团队 ID |
| `person_org_id` | BIGINT | `person_org_id` | 自动映射 | 人员组织 ID | 飞球组织 ID |
| `assistant_level` | INTEGER | `assistant_level` | 自动映射 | 助教等级编码 | 枚举值 |
| `level_name` | VARCHAR(64) | `levelname` | FACT_MAPPINGS | 助教等级名称 | 如 `高级`、`中级` |
| `skill_id` | BIGINT | `skill_id` | 自动映射 | 服务技能 ID | 飞球技能 ID |
| `skill_name` | VARCHAR(64) | `skillname` | FACT_MAPPINGS | 服务技能名称 | 如 `陪打`、`促销` |
| `ledger_unit_price` | NUMERIC(10,2) | `ledger_unit_price` | 自动映射 | 分账单价（元/小时） | 金额值 |
| `ledger_amount` | NUMERIC(10,2) | `ledger_amount` | 自动映射 | 分账总金额（元） | 金额值 |
| `projected_income` | NUMERIC(10,2) | `projected_income` | 自动映射 | 预计收入（元） | 金额值 |
| `coupon_deduct_money` | NUMERIC(10,2) | `coupon_deduct_money` | 自动映射 | 优惠券抵扣金额（元） | `0.00` ~ 金额值 |
| `income_seconds` | INTEGER | `income_seconds` | 自动映射 | 计费时长（秒） | 正整数 |
| `real_use_seconds` | INTEGER | `real_use_seconds` | 自动映射 | 实际使用时长（秒） | 正整数 |
| `add_clock` | INTEGER | `add_clock` | 自动映射 | 加钟次数 | `0` ~ 正整数 |
| `create_time` | TIMESTAMPTZ | `create_time` | 自动映射 | 记录创建时间 | ISO 时间戳 |
| `start_use_time` | TIMESTAMPTZ | `start_use_time` | 自动映射 | 服务开始时间 | ISO 时间戳 |
| `last_use_time` | TIMESTAMPTZ | `last_use_time` | 自动映射 | 最后使用时间（服务结束时间） | ISO 时间戳 |
| `is_delete` | INTEGER | `is_delete` | 自动映射 | 是否已删除：0=正常，1=已删除 | `0` / `1` |
| `real_service_money` | NUMERIC(18,2) | `real_service_money` | FACT_MAPPINGS | 实际服务金额（元），扣除折扣后的实收 | `0.00` ~ 金额值 |
---
## 2. dwd_assistant_service_log_ex（扩展表，33 列）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `assistant_service_id` | BIGINT | `id` | FACT_MAPPINGS | 助教服务记录唯一标识（PK） | 同主表 |
| `table_name` | VARCHAR(64) | `tablename` | FACT_MAPPINGS | 台桌名称快照 | 如 `1号台` |
| `assistant_name` | VARCHAR(64) | `assistantname` | FACT_MAPPINGS | 助教姓名快照 | 如 `张静然` |
| `ledger_name` | VARCHAR(128) | `ledger_name` | 自动映射 | 分账项名称 | 如 `陪打费` |
| `ledger_group_name` | VARCHAR(128) | `ledger_group_name` | FACT_MAPPINGS | 分账组名称 | 分账组名或 NULL |
| `ledger_count` | INTEGER | `ledger_count` | 自动映射 | 分账数量 | 正整数 |
| `member_discount_amount` | NUMERIC(10,2) | `member_discount_amount` | 自动映射 | 会员折扣金额（元） | `0.00` ~ 金额值 |
| `manual_discount_amount` | NUMERIC(10,2) | `manual_discount_amount` | 自动映射 | 手动折扣金额（元） | `0.00` ~ 金额值 |
| `service_money` | NUMERIC(10,2) | `service_money` | 自动映射 | 服务原价金额（元） | 金额值 |
| `returns_clock` | INTEGER | `returns_clock` | 自动映射 | 退钟次数 | `0` ~ 正整数 |
| `ledger_start_time` | TIMESTAMPTZ | `ledger_start_time` | 自动映射 | 分账开始时间 | ISO 时间戳 |
| `ledger_end_time` | TIMESTAMPTZ | `ledger_end_time` | 自动映射 | 分账结束时间 | ISO 时间戳 |
| `ledger_status` | INTEGER | `ledger_status` | 自动映射 | 分账状态 | 枚举值 |
| `is_confirm` | INTEGER | `is_confirm` | 自动映射 | 是否已确认：0=未确认，1=已确认 | `0` / `1` |
| `is_single_order` | INTEGER | `is_single_order` | 自动映射 | 是否单独订单 | `0` / `1` |
| `is_not_responding` | INTEGER | `is_not_responding` | 自动映射 | 是否未响应 | `0` / `1` |
| `is_trash` | INTEGER | `is_trash` | 自动映射 | 是否已废除：0=正常，1=已废除 | `0` / `1` |
| `trash_applicant_id` | BIGINT | `trash_applicant_id` | 自动映射 | 废除申请人 ID | 员工 ID 或 NULL |
| `trash_applicant_name` | VARCHAR(64) | `trash_applicant_name` | FACT_MAPPINGS | 废除申请人姓名 | 姓名或 NULL |
| `trash_reason` | VARCHAR(255) | `trash_reason` | FACT_MAPPINGS | 废除原因 | 自由文本或 NULL |
| `salesman_user_id` | BIGINT | `salesman_user_id` | 自动映射 | 销售员用户 ID | 用户 ID 或 NULL |
| `salesman_name` | VARCHAR(64) | `salesman_name` | FACT_MAPPINGS | 销售员姓名 | 姓名或 NULL |
| `salesman_org_id` | BIGINT | `salesman_org_id` | 自动映射 | 销售员组织 ID | 组织 ID 或 NULL |
| `skill_grade` | INTEGER | `skill_grade` | 自动映射 | 技能评分 | 评分值 |
| `service_grade` | INTEGER | `service_grade` | 自动映射 | 服务评分 | 评分值 |
| `composite_grade` | NUMERIC(5,2) | `composite_grade` | 自动映射 | 综合评分 | 如 `4.50` |
| `sum_grade` | NUMERIC(10,2) | `sum_grade` | 自动映射 | 累计评分 | 累计值 |
| `get_grade_times` | INTEGER | `get_grade_times` | 自动映射 | 获评次数 | 正整数 |
| `grade_status` | INTEGER | `grade_status` | 自动映射 | 评分状态 | 枚举值 |
| `composite_grade_time` | TIMESTAMPTZ | `composite_grade_time` | 自动映射 | 综合评分时间 | ISO 时间戳 |
| `assistant_team_name` | TEXT | `assistantteamname` | FACT_MAPPINGS | 助教团队名称快照 | 如 `1组` |
| `operator_id` | BIGINT | `operator_id` | FACT_MAPPINGS | 操作员 ID，录入/结算这条助教服务的员工。0 表示系统自动 | `0` 或员工 ID |
| `operator_name` | TEXT | `operator_name` | FACT_MAPPINGS | 操作员姓名（带职位前缀），便于直接阅读 | 如 `收银员:郑丽珊`，NULL 表示系统自动 |
---
## 3. 映射修正记录
| 日期 | 字段 | 修正内容 |
|------|------|---------|
| 2026-02-20 | `site_assistant_id` | ODS 源从 `order_assistant_id`（订单级 ID）修正为 `site_assistant_id`（助教档案 ID） |
| 2026-02-26 | （下游）`table_area_name` | DWS 任务 `_extract_service_records()` 原错误引用 `asl.table_area_name`（本表无此列），改为 JOIN `dwd.dim_table` 取 `site_table_area_name`。详见 `BD_Manual_fix_dws_assistant_daily_table_area.md` |
---
## 4. 跳过字段说明
| ODS 字段 | 跳过原因 |
|---------|---------|
| `siteprofile` | JSONB 嵌套列，已由 `dim_site` / `dim_site_ex` 通过 JSONB 提取映射 |
---
## 5. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dwd_assistant_service_log"]` / `FACT_MAPPINGS["dwd.dwd_assistant_service_log_ex"]`
- TABLE_MAP：`"dwd.dwd_assistant_service_log" → "ods.assistant_service_records"`
- DWS 下游：`dws_assistant_daily_task.py`（助教日业绩汇总）
- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__fix_assistant_service_site_assistant_id.sql`（已归档）、`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__add_assistant_service_log_ex_fields.sql`（已归档）

62
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_goods_stock_movements.md Normal file
View File

@@ -0,0 +1,62 @@
# BD_Manual：goods_stock_movements（库存变动流水）
> ODS 表：`ods.goods_stock_movements`
> DWD 表：`dwd.dwd_goods_stock_movement`（事实表，无 ex 扩展表）
> API 接口：库存变动记录列表
> JSON 路径：`goods_stock_movements.json → data.goodsStockList`
> 装载方式：事实表按 `create_time` 增量加载（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dwd_goods_stock_movement
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `site_goods_stock_id` | BIGINT | `sitegoodsstockid`（ODS 驼峰 → PG 小写） | FACT_MAPPINGS (cast bigint) | 库存变动记录唯一标识（PK） | 飞球雪花 ID |
| `tenant_id` | BIGINT | `tenantid` | FACT_MAPPINGS (cast bigint) | 租户 ID | 飞球租户 ID |
| `site_id` | BIGINT | `siteid` | FACT_MAPPINGS (cast bigint) | 门店 ID | 飞球门店 ID |
| `site_goods_id` | BIGINT | `sitegoodsid` | FACT_MAPPINGS (cast bigint) | 门店商品 ID，关联 `dim_store_goods.site_goods_id` | 飞球商品 ID |
| `goods_name` | TEXT | `goodsname` | FACT_MAPPINGS | 商品名称 | 如 `百威啤酒` |
| `goods_category_id` | BIGINT | `goodscategoryid` | FACT_MAPPINGS (cast bigint) | 一级商品分类 ID | 飞球分类 ID |
| `goods_second_category_id` | BIGINT | `goodssecondcategoryid` | FACT_MAPPINGS (cast bigint) | 二级商品分类 ID | 飞球分类 ID |
| `unit` | TEXT | `unit` | FACT_MAPPINGS | 计量单位 | 如 `瓶`、`包`、`张` |
| `price` | NUMERIC(18,4) | `price` | FACT_MAPPINGS (cast numeric) | 商品单价（元） | 金额值 |
| `stock_type` | INTEGER | `stocktype` | FACT_MAPPINGS (cast integer) | 库存变动类型枚举（详见下方枚举表） | `1`/`2`/`4`/`7`/`8`/`9` |
| `change_num` | NUMERIC(18,4) | `changenum` | FACT_MAPPINGS (cast numeric) | 变动数量（正数为增加，负数为减少） | 正/负数值 |
| `start_num` | NUMERIC(18,4) | `startnum` | FACT_MAPPINGS (cast numeric) | 变动前库存量 | `0.0000` ~ 正数 |
| `end_num` | NUMERIC(18,4) | `endnum` | FACT_MAPPINGS (cast numeric) | 变动后库存量 | `0.0000` ~ 正数 |
| `change_num_a` | NUMERIC(18,4) | `changenuma` | FACT_MAPPINGS (cast numeric) | 辅助单位变动量（用于双单位商品，如"箱→瓶"换算） | 数值或 0 |
| `start_num_a` | NUMERIC(18,4) | `startnuma` | FACT_MAPPINGS (cast numeric) | 辅助单位变动前库存 | 数值或 0 |
| `end_num_a` | NUMERIC(18,4) | `endnuma` | FACT_MAPPINGS (cast numeric) | 辅助单位变动后库存 | 数值或 0 |
| `remark` | TEXT | `remark` | FACT_MAPPINGS | 备注说明 | 如 `结账退货`、`采购退货`、`系统自动领用`，或 NULL |
| `operator_name` | TEXT | `operatorname` | FACT_MAPPINGS | 操作人姓名 | 姓名或 NULL |
| `create_time` | TIMESTAMPTZ | `createtime` | FACT_MAPPINGS (cast timestamptz) | 变动发生时间 | ISO 时间戳 |
| `fetched_at` | TIMESTAMPTZ | `fetched_at` | 自动映射 | ETL 采集时间戳 | ISO 时间戳 |
---
## 2. stock_type 枚举值详解
| stock_type | 含义 | 典型 remark | 数据量 |
|-----------|------|------------|--------|
| 1 | 销售出库 | NULL（系统自动扣减） | 29,573 条 |
| 2 | 采购入库 | NULL | 1,033 条 |
| 4 | 退货入库 | `结账退货` | 3,300 条 |
| 7 | 采购退货（出库） | `采购退货` | 33 条 |
| 8 | 领用出库 | `系统自动领用` | 1,033 条 |
| 9 | 领用退回（入库） | `系统自动领用退回` | 33 条 |
---
## 3. ODS 列名映射说明
ODS DDL 中列名使用驼峰式（如 `siteGoodsStockId`），PostgreSQL 在无引号时自动小写化。FACT_MAPPINGS 中使用带引号的 ODS 列名以正确引用。部分列（`unit`、`price`、`remark`）在 ODS 中已是小写，无需引号。
---
## 4. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dwd_goods_stock_movement"]`
- TABLE_MAP：`"dwd.dwd_goods_stock_movement" → "ods.goods_stock_movements"`
- DWS 下游：暂无直接 DWS 汇总（库存汇总基于 `dwd_goods_stock_summary`）

62
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_goods_stock_summary.md Normal file
View File

@@ -0,0 +1,62 @@
# BD_Manual：goods_stock_summary（库存汇总）
> ODS 表：`ods.goods_stock_summary`
> DWD 表：`dwd.dwd_goods_stock_summary`（事实表，无 ex 扩展表）
> API 接口：库存汇总查询（支持 `startTime`/`endTime` 时间窗口参数）
> JSON 路径：`goods_stock_summary.json → data.goodsStockSummaryList`
> 装载方式：事实表按时间窗口增量加载（`DwdLoadTask`）
> ODS 配置：`requires_window=True`，`time_fields=("startTime", "endTime")`
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dwd_goods_stock_summary
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `site_goods_id` | BIGINT | `sitegoodsid`（ODS DDL 驼峰 → PG 小写） | FACT_MAPPINGS (cast bigint) | 门店商品 ID（PK 之一），关联 `dim_store_goods.site_goods_id` | 飞球商品 ID，如 `3028609051954117` |
| `goods_name` | TEXT | `goodsname` | FACT_MAPPINGS | 商品名称 | 如 `酱香爆珠槟榔`、`百威啤酒` |
| `goods_unit` | TEXT | `goodsunit` | FACT_MAPPINGS | 计量单位 | 如 `包`、`瓶`、`张`、`罐` |
| `goods_category_id` | BIGINT | `goodscategoryid` | FACT_MAPPINGS (cast bigint) | 一级商品分类 ID | 飞球分类 ID |
| `goods_category_second_id` | BIGINT | `goodscategorysecondid` | FACT_MAPPINGS (cast bigint) | 二级商品分类 ID | 飞球分类 ID |
| `category_name` | TEXT | `categoryname` | FACT_MAPPINGS | 一级分类名称 | 如 `槟榔`、`酒水`、`其他` |
| `range_start_stock` | NUMERIC(18,4) | `rangestartstock` | FACT_MAPPINGS (cast numeric) | 期初库存（查询时间窗口起点的库存量） | 如 `100.0000`、`0.0000` |
| `range_end_stock` | NUMERIC(18,4) | `rangeendstock` | FACT_MAPPINGS (cast numeric) | 期末库存（查询时间窗口终点的库存量） | 如 `100.0000`、`0.0000` |
| `range_in` | NUMERIC(18,4) | `rangein` | FACT_MAPPINGS (cast numeric) | 入库数量（时间窗口内的采购/调拨入库总量） | `0.0000` ~ 正数 |
| `range_out` | NUMERIC(18,4) | `rangeout` | FACT_MAPPINGS (cast numeric) | 出库数量（时间窗口内的调拨出库/报损总量） | `0.0000` ~ 正数 |
| `range_sale` | NUMERIC(18,4) | `rangesale` | FACT_MAPPINGS (cast numeric) | 销售数量（时间窗口内的销售出库总量） | `0.0000` ~ 正数 |
| `range_sale_money` | NUMERIC(18,2) | `rangesalemoney` | FACT_MAPPINGS (cast numeric) | 销售金额（元），时间窗口内的销售总金额 | `0.00` ~ 金额值 |
| `range_inventory` | NUMERIC(18,4) | `rangeinventory` | FACT_MAPPINGS (cast numeric) | 盘点调整量（时间窗口内的盘盈/盘亏净量） | 正数（盘盈）或负数（盘亏） |
| `current_stock` | NUMERIC(18,4) | `currentstock` | FACT_MAPPINGS (cast numeric) | 当前库存（API 返回时的实时库存量） | `0.0000` ~ 正数 |
| `site_id` | BIGINT | `site_id` | 自动映射 | 门店 ID（ETL 注入） | 飞球门店 ID |
| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 租户 ID（ETL 注入） | 飞球租户 ID |
| `fetched_at` | TIMESTAMPTZ | `fetched_at` | 自动映射 | ETL 采集时间戳（PK 之一），标识本次快照的采集时间 | ISO 时间戳 |
---
## 2. 主键说明
主键为 `(site_goods_id, fetched_at)` 复合键。同一商品在不同采集时间窗口会产生多条记录，每条记录代表该时间窗口内的库存汇总快照。
---
## 3. ODS 列名映射说明
ODS DDL 中列名使用驼峰式（如 `siteGoodsId`），但 PostgreSQL 在无引号时自动小写化为 `sitegoodsid`。FACT_MAPPINGS 中使用带引号的 ODS 列名（如 `"siteGoodsId"`）以正确引用。
---
## 4. DWS 下游
- `dws.dws_goods_stock_daily_summary`：日度库存汇总
- `dws.dws_goods_stock_weekly_summary`：周度库存汇总（ISO 周）
- `dws.dws_goods_stock_monthly_summary`：月度库存汇总
---
## 5. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dwd_goods_stock_summary"]`
- TABLE_MAP：`"dwd.dwd_goods_stock_summary" → "ods.goods_stock_summary"`
- ODS 任务配置：`tasks/ods/ods_tasks.py` → `OdsTaskSpec("ODS_GOODS_STOCK_SUMMARY", requires_window=True, time_fields=("startTime", "endTime"))`
- DWS 任务：`tasks/dws/goods_stock_daily_task.py`、`goods_stock_weekly_task.py`、`goods_stock_monthly_task.py`

102
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_goods_stock_warning_info.md Normal file
View File

@@ -0,0 +1,102 @@
# BD Manual: goodsStockWarningInfo（库存预警信息）
## 变更概述
- 日期：2026-02-24
- 触发：一致性检查报告发现 API 独有嵌套字段 `goodsStockWarningInfo` 未映射到 ODS/DWD
- 迁移脚本：`db/etl_feiqiu/migrations/2026-02-24__add_goods_stock_warning_info.sql`
## 字段来源
API 端点 `/TenantGoods/GetGoodsInventoryList` 返回的 `store_goods_master` 记录中包含嵌套对象：
```json
{
"goodsStockWarningInfo": {
"tenant_goods_id": 0, // 冗余，已有同名顶层字段
"site_goods_id": 0, // 冗余，对应顶层 id
"sales_day": 0.0, // → warning_sales_day
"warning_day_max": 0, // → warning_day_max
"warning_day_min": 0 // → warning_day_min
}
}
```
仅提取 3 个有效字段，冗余 ID 不重复收录。
## 新增字段
| 层 | 表 | 列名 | 类型 | 说明 |
|---|---|---|---|---|
| ODS | `ods.store_goods_master` | `warning_sales_day` | NUMERIC(18,2) | 库存预警参考的日均销量 |
| ODS | `ods.store_goods_master` | `warning_day_max` | INTEGER | 预警天数上限 |
| ODS | `ods.store_goods_master` | `warning_day_min` | INTEGER | 预警天数下限 |
| DWD | `dwd.dim_store_goods_ex` | `warning_sales_day` | NUMERIC(18,2) | 同 ODS，直接映射 |
| DWD | `dwd.dim_store_goods_ex` | `warning_day_max` | INTEGER | 同 ODS，直接映射 |
| DWD | `dwd.dim_store_goods_ex` | `warning_day_min` | INTEGER | 同 ODS，直接映射 |
## 数据流
```
API goodsStockWarningInfo (嵌套 JSON)
↓ _merge_record_layers 扁平化（_STOCK_WARNING_FIELD_MAP）
ODS ods.store_goods_master (warning_sales_day / warning_day_max / warning_day_min)
↓ DWD FACT_MAPPINGS 直接映射
DWD dwd.dim_store_goods_ex (同名列)
```
## 代码变更
| 文件 | 变更 |
|---|---|
| `apps/etl/connectors/feiqiu/tasks/ods/ods_tasks.py` | `_merge_record_layers` 增加 `goodsStockWarningInfo` 扁平化逻辑 |
| `apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py` | `FACT_MAPPINGS["dwd.dim_store_goods_ex"]` 增加 3 个映射 |
| `db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/schemas/ods.sql` | baseline 同步 |
| `db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/schemas/dwd.sql` | baseline 同步 |
## 兼容性
- 后端 API：无影响（后端不直接读取 ODS/DWD 层这些字段）
- 小程序：无影响
- ETL：ODS schema-aware 插入自动识别新列；DWD 通过 FACT_MAPPINGS 映射
- 管理后台：如需展示库存预警信息，可从 `dwd.dim_store_goods_ex` 读取
## 回滚策略
```sql
ALTER TABLE ods.store_goods_master
DROP COLUMN IF EXISTS warning_sales_day,
DROP COLUMN IF EXISTS warning_day_max,
DROP COLUMN IF EXISTS warning_day_min;
ALTER TABLE dwd.dim_store_goods_ex
DROP COLUMN IF EXISTS warning_sales_day,
DROP COLUMN IF EXISTS warning_day_max,
DROP COLUMN IF EXISTS warning_day_min;
```
## 验证 SQL
```sql
-- 1. 确认 ODS 新列存在
SELECT column_name, data_type FROM information_schema.columns
WHERE table_schema = 'ods' AND table_name = 'store_goods_master'
AND column_name IN ('warning_sales_day', 'warning_day_max', 'warning_day_min')
ORDER BY column_name;
-- 预期：3 行
-- 2. 确认 DWD 新列存在
SELECT column_name, data_type FROM information_schema.columns
WHERE table_schema = 'dwd' AND table_name = 'dim_store_goods_ex'
AND column_name IN ('warning_sales_day', 'warning_day_max', 'warning_day_min')
ORDER BY column_name;
-- 预期：3 行
-- 3. 确认注释已设置
SELECT c.column_name, pgd.description
FROM information_schema.columns c
JOIN pg_catalog.pg_statio_all_tables st ON st.schemaname = c.table_schema AND st.relname = c.table_name
JOIN pg_catalog.pg_description pgd ON pgd.objoid = st.relid AND pgd.objsubid = c.ordinal_position
WHERE c.table_schema = 'ods' AND c.table_name = 'store_goods_master'
AND c.column_name LIKE 'warning_%';
-- 预期：3 行，description 非空
```

92
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_group_buy_package_details.md Normal file
View File

@@ -0,0 +1,92 @@
# BD_Manual：ods.group_buy_package_details 团购套餐详情表
> 日期：2026-03-05
> 涉及库：`etl_feiqiu` / `test_etl_feiqiu`
> DDL 路径：`db/etl_feiqiu/ods/group_buy_package_details.sql`
> 直接原因：整合团购详情接口（QueryPackageCouponInfo），新建 ODS 详情表存储每个团购套餐的详情数据
> Prompt 摘要：etl-coupon-detail spec — 需求 3 验收标准 1-4
---
## 1. 变更说明
### 变更内容
新建 `ods.group_buy_package_details` 表，用于存储 `QueryPackageCouponInfo` 详情接口的原始数据。
| Schema | 表 | 操作 | 说明 |
|--------|-----|------|------|
| ods | group_buy_package_details | 新建 | 团购套餐详情，主键 `coupon_id`，含 12 个结构化字段 + 6 个 JSONB 数组字段 + 3 个 ETL 元数据字段 |
### 数据获取方式
通过 `ODS_GROUP_PACKAGE` 任务的 `detail_endpoint` 二级详情拉取子流程：
- 主流程拉取团购列表 → `ods.group_buy_packages`
- 子流程遍历每个 `id`，串行调用 `QueryPackageCouponInfo` → 本表
- 全量快照模式，UPSERT on `coupon_id`
### 关键字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `coupon_id` | BIGINT PK | 团购套餐 ID（= group_buy_packages.id） |
| `table_area_ids` | JSONB | 可用台区 ID 列表 |
| `table_area_names` | JSONB | 可用台区名称列表 |
| `assistant_services` | JSONB | 助教服务关联数组 |
| `groupon_site_infos` | JSONB | 关联门店信息数组 |
| `package_services` | JSONB | 套餐服务数组（待调研） |
| `coupon_details_list` | JSONB | 券明细数组（待调研） |
| `content_hash` | TEXT | 内容哈希，用于变更检测 |
| `payload` | JSONB | 完整原始 JSON 响应 |
---
## 2. 兼容性影响
| 组件 | 影响 | 说明 |
|------|------|------|
| ETL ODS 层 | 新增表 | `ODS_GROUP_PACKAGE` 任务通过 `detail_endpoint` 配置自动写入 |
| ETL DWD 层 | 需配合修改 | `dwd_load_task.py` 需 LEFT JOIN 本表将 4 个 JSONB 字段合并到 `dim_groupbuy_package_ex` |
| 后端 API | 无影响 | 当前无接口直接查询本表 |
| 小程序 | 无影响 | 不直接使用 ODS 层表 |
---
## 3. 回滚策略
```sql
DROP TABLE IF EXISTS ods.group_buy_package_details;
```
回滚后需同步移除 `ODS_GROUP_PACKAGE` 任务中的 `detail_endpoint` 相关配置。
---
## 4. 验证 SQL
```sql
-- 1. 确认表存在且主键正确
SELECT column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name = 'group_buy_package_details'
ORDER BY ordinal_position;
-- 预期：22 列，coupon_id 为 BIGINT NOT NULL
-- 2. 确认主键约束
SELECT constraint_name, constraint_type
FROM information_schema.table_constraints
WHERE table_schema = 'ods'
AND table_name = 'group_buy_package_details'
AND constraint_type = 'PRIMARY KEY';
-- 预期：1 行，pk_group_buy_package_details
-- 3. 确认 JSONB 列存在
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name = 'group_buy_package_details'
AND data_type = 'jsonb'
ORDER BY ordinal_position;
-- 预期：8 行（table_area_ids, table_area_names, assistant_services, groupon_site_infos, package_services, coupon_details_list, payload）
```

74
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_member_balance_changes.md Normal file
View File

@@ -0,0 +1,74 @@
# BD_Manual：member_balance_changes（会员余额变动）
> ODS 表：`ods.member_balance_changes`
> DWD 表：`dwd.dwd_member_balance_change`（主表）、`dwd.dwd_member_balance_change_ex`（扩展表）
> API 接口：会员余额变动记录列表
> JSON 路径：`member_balance_changes.json → data.memberAccountChanges`
> 装载方式：事实表增量插入（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dwd_member_balance_change（主表，22 列）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `balance_change_id` | BIGINT | `id` | FACT_MAPPINGS | 余额变动记录唯一标识（PK） | 飞球雪花 ID |
| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 租户 ID | 飞球租户 ID |
| `site_id` | BIGINT | `site_id` | 自动映射 | 门店 ID | 飞球门店 ID |
| `register_site_id` | BIGINT | `register_site_id` | 自动映射 | 会员注册门店 ID | 飞球门店 ID |
| `tenant_member_id` | BIGINT | `tenant_member_id` | 自动映射 | 租户维度会员 ID | 飞球会员 ID |
| `system_member_id` | BIGINT | `system_member_id` | 自动映射 | 系统维度会员 ID（跨租户唯一） | 飞球会员 ID |
| `tenant_member_card_id` | BIGINT | `tenant_member_card_id` | 自动映射 | 会员卡 ID | 飞球会员卡 ID |
| `card_type_id` | BIGINT | `card_type_id` | 自动映射 | 会员卡类型 ID | 飞球卡类型 ID |
| `card_type_name` | VARCHAR(32) | `membercardtypename` | FACT_MAPPINGS | 会员卡类型名称快照 | 如 `普通会员卡` |
| `member_name` | VARCHAR(64) | `membername` | FACT_MAPPINGS | 会员姓名快照 | 姓名 |
| `member_mobile` | VARCHAR(20) | `membermobile` | FACT_MAPPINGS | 会员手机号快照 | 11 位手机号 |
| `balance_before` | NUMERIC(18,2) | `before` | FACT_MAPPINGS | 变动前余额（元） | 金额值 |
| `change_amount` | NUMERIC(18,2) | `account_data` | FACT_MAPPINGS | 变动金额（元），正数为充入，负数为扣减 | 正/负金额 |
| `balance_after` | NUMERIC(18,2) | `after` | FACT_MAPPINGS | 变动后余额（元） | 金额值 |
| `from_type` | INTEGER | `from_type` | 自动映射 | 变动来源类型：1=结算扣款，2=充值，3=退款返还，4=系统调整，7=转账，9=其他 | `1`/`2`/`3`/`4`/`7`/`9` |
| `payment_method` | INTEGER | `payment_method` | 自动映射 | 支付方式 | 枚举值 |
| `change_time` | TIMESTAMPTZ | `create_time` | FACT_MAPPINGS | 变动发生时间 | ISO 时间戳 |
| `is_delete` | INTEGER | `is_delete` | 自动映射 | 是否已删除：0=正常，1=已删除 | `0` / `1` |
| `remark` | VARCHAR(255) | `remark` | 自动映射 | 备注说明 | 自由文本或 NULL |
| `principal_before` | NUMERIC(18,2) | `principal_before` | FACT_MAPPINGS | 变动前本金余额（元），不含赠送金 | 金额值 |
| `principal_after` | NUMERIC(18,2) | `principal_after` | FACT_MAPPINGS | 变动后本金余额（元） | 金额值 |
| `principal_change_amount` | NUMERIC(18,2) | *计算列* | FACT_MAPPINGS | 本金变动金额（元），= `principal_after - principal_before` | 正/负金额 |
---
## 2. dwd_member_balance_change_ex（扩展表，8 列）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `balance_change_id` | BIGINT | `id` | FACT_MAPPINGS | 余额变动记录唯一标识（PK） | 同主表 |
| `pay_site_name` | VARCHAR(64) | `paysitename` | FACT_MAPPINGS | 支付门店名称快照 | 如 `朗朗桌球` |
| `register_site_name` | VARCHAR(64) | `registersitename` | FACT_MAPPINGS | 注册门店名称快照 | 如 `朗朗桌球` |
| `refund_amount` | NUMERIC(18,2) | `refund_amount` | 自动映射 | 退款金额（元） | `0.00` ~ 金额值 |
| `operator_id` | BIGINT | `operator_id` | 自动映射 | 操作员 ID，执行本次余额变动的员工。0 表示系统自动 | `0` 或员工 ID |
| `operator_name` | VARCHAR(64) | `operator_name` | 自动映射 | 操作员姓名 | 姓名或 NULL |
| `principal_data` | TEXT | `principal_data` | FACT_MAPPINGS | 本金变动金额（元），正数为充入本金，负数为扣减本金 | 正/负金额 |
| `relate_id` | BIGINT | `relate_id` | FACT_MAPPINGS | 关联业务单据 ID，指向触发本次余额变动的业务记录。按 `from_type` 不同指向不同表：1→结算单 ID，2→充值单 ID，3→退款单 ID，7→转账单 ID。`from_type=4`（系统调整）和 `9`（其他）时为 0 | `0` 或业务单据 ID |
---
## 3. from_type 枚举值详解
| from_type | 含义 | relate_id 指向 | 数据量 |
|-----------|------|---------------|--------|
| 1 | 结算扣款（消费） | 结算单 ID（`dwd_settlement_head.order_settle_id`） | 5637 条 |
| 2 | 充值 | 充值单 ID（`dwd_recharge_order.recharge_order_id`） | 110 条 |
| 3 | 退款返还 | 退款单 ID（`dwd_refund.refund_id`） | 650 条 |
| 4 | 系统调整 | 0（无关联单据） | 775 条 |
| 7 | 转账 | 转账单 ID | 15 条 |
| 9 | 其他 | 0（无关联单据） | 179 条 |
---
## 4. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dwd_member_balance_change"]` / `FACT_MAPPINGS["dwd.dwd_member_balance_change_ex"]`
- TABLE_MAP：`"dwd.dwd_member_balance_change" → "ods.member_balance_changes"`
- DWS 下游：`dws_member_analysis_task.py`（会员消费分析）
- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__add_member_balance_change_ex_relate_id.sql`（已归档）

103
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_recharge_settlements.md Normal file
View File

@@ -0,0 +1,103 @@
# BD_Manual：recharge_settlements（充值结算）
> ODS 表：`ods.recharge_settlements`
> DWD 表：`dwd.dwd_recharge_order`（主表）、`dwd.dwd_recharge_order_ex`（扩展表）
> API 接口：充值结算记录列表
> JSON 路径：`recharge_settlements.json → data.orderSettles`
> 装载方式：事实表增量插入（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dwd_recharge_order（主表）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `recharge_order_id` | BIGINT | `id` | FACT_MAPPINGS | 充值结算记录唯一标识（PK） | 飞球雪花 ID |
| `tenant_id` | BIGINT | `tenantid` | FACT_MAPPINGS | 租户 ID | 飞球租户 ID |
| `site_id` | BIGINT | `siteid` | FACT_MAPPINGS | 门店 ID | 飞球门店 ID |
| `member_id` | BIGINT | `memberid` | FACT_MAPPINGS | 会员 ID | 飞球会员 ID |
| `member_name_snapshot` | TEXT | `membername` | FACT_MAPPINGS | 会员姓名快照 | 姓名 |
| `member_phone_snapshot` | TEXT | `memberphone` | FACT_MAPPINGS | 会员手机号快照 | 11 位手机号 |
| `tenant_member_card_id` | BIGINT | `tenantmembercardid` | FACT_MAPPINGS | 会员卡 ID | 飞球会员卡 ID |
| `member_card_type_name` | TEXT | `membercardtypename` | FACT_MAPPINGS | 会员卡类型名称 | 如 `普通会员卡` |
| `settle_relate_id` | BIGINT | `settlerelateid` | FACT_MAPPINGS | 关联结算单 ID | 飞球结算 ID |
| `settle_type` | INTEGER | `settletype` | FACT_MAPPINGS | 结算类型枚举 | 枚举值 |
| `settle_name` | TEXT | `settlename` | FACT_MAPPINGS | 结算类型名称 | 如 `充值` |
| `is_first` | INTEGER | `isfirst` | FACT_MAPPINGS | 是否首次充值：0=否，1=是 | `0` / `1` |
| `pay_amount` | NUMERIC | `payamount` | FACT_MAPPINGS | 实付金额（元） | 金额值 |
| `refund_amount` | NUMERIC | `refundamount` | FACT_MAPPINGS | 退款金额（元） | `0.00` ~ 金额值 |
| `point_amount` | NUMERIC | `pointamount` | FACT_MAPPINGS | 积分抵扣金额（元） | `0.00` ~ 金额值 |
| `cash_amount` | NUMERIC | `cashamount` | FACT_MAPPINGS | 现金支付金额（元） | `0.00` ~ 金额值 |
| `payment_method` | TEXT | `paymentmethod` | FACT_MAPPINGS | 支付方式 | 如 `微信`、`支付宝` |
| `create_time` | TIMESTAMPTZ | `createtime` | FACT_MAPPINGS | 充值记录创建时间 | ISO 时间戳 |
| `pay_time` | TIMESTAMPTZ | `paytime` | FACT_MAPPINGS | 支付完成时间 | ISO 时间戳 |
| `pl_coupon_sale_amount` | NUMERIC | `plcouponsaleamount` | FACT_MAPPINGS | 平台券销售金额（元）。当前门店业务未启用，全部为 0 | `0.00` |
| `mervou_sales_amount` | NUMERIC | `mervousalesamount` | FACT_MAPPINGS | 储值券销售金额（元）。当前门店业务未启用，全部为 0 | `0.00` |
| `electricity_money` | NUMERIC | `electricitymoney` | FACT_MAPPINGS | 电费金额（元）。当前门店业务未启用，全部为 0 | `0.00` |
| `real_electricity_money` | NUMERIC | `realelectricitymoney` | FACT_MAPPINGS | 实际电费金额（元），扣除调整后的电费。当前门店业务未启用，全部为 0 | `0.00` |
| `electricity_adjust_money` | NUMERIC | `electricityadjustmoney` | FACT_MAPPINGS | 电费调整金额（元），电费手动调整的差额。当前门店业务未启用，全部为 0 | `0.00` |
---
## 2. dwd_recharge_order_ex（扩展表）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `recharge_order_id` | BIGINT | `id` | FACT_MAPPINGS | 充值结算记录唯一标识（PK） | 同主表 |
| `site_name_snapshot` | TEXT | `sitename` | FACT_MAPPINGS | 门店名称快照 | 如 `朗朗桌球` |
| `settle_status` | INTEGER | `settlestatus` | FACT_MAPPINGS | 结算状态枚举 | 枚举值 |
| `is_bind_member` | BOOLEAN | `isbindmember` | FACT_MAPPINGS (cast boolean) | 是否绑定会员 | `true` / `false` |
| `is_activity` | BOOLEAN | `isactivity` | FACT_MAPPINGS (cast boolean) | 是否参与活动 | `true` / `false` |
| `is_use_coupon` | BOOLEAN | `isusecoupon` | FACT_MAPPINGS (cast boolean) | 是否使用优惠券 | `true` / `false` |
| `is_use_discount` | BOOLEAN | `isusediscount` | FACT_MAPPINGS (cast boolean) | 是否使用折扣 | `true` / `false` |
| `can_be_revoked` | BOOLEAN | `canberevoked` | FACT_MAPPINGS (cast boolean) | 是否可撤销 | `true` / `false` |
| `online_amount` | NUMERIC | `onlineamount` | FACT_MAPPINGS | 线上支付金额（元） | 金额值 |
| `balance_amount` | NUMERIC | `balanceamount` | FACT_MAPPINGS | 余额支付金额（元） | 金额值 |
| `card_amount` | NUMERIC | `cardamount` | FACT_MAPPINGS | 银行卡支付金额（元） | 金额值 |
| `coupon_amount` | NUMERIC | `couponamount` | FACT_MAPPINGS | 优惠券抵扣金额（元） | 金额值 |
| `recharge_card_amount` | NUMERIC | `rechargecardamount` | FACT_MAPPINGS | 充值卡支付金额（元） | 金额值 |
| `gift_card_amount` | NUMERIC | `giftcardamount` | FACT_MAPPINGS | 赠送卡支付金额（元） | 金额值 |
| `prepay_money` | NUMERIC | `prepaymoney` | FACT_MAPPINGS | 预付金额（元） | 金额值 |
| `consume_money` | NUMERIC | `consumemoney` | FACT_MAPPINGS | 消费总金额（元） | 金额值 |
| `goods_money` | NUMERIC | `goodsmoney` | FACT_MAPPINGS | 商品金额（元） | 金额值 |
| `real_goods_money` | NUMERIC | `realgoodsmoney` | FACT_MAPPINGS | 实收商品金额（元） | 金额值 |
| `table_charge_money` | NUMERIC | `tablechargemoney` | FACT_MAPPINGS | 台费金额（元） | 金额值 |
| `service_money` | NUMERIC | `servicemoney` | FACT_MAPPINGS | 服务费金额（元） | 金额值 |
| `activity_discount` | NUMERIC | `activitydiscount` | FACT_MAPPINGS | 活动折扣金额（元） | 金额值 |
| `all_coupon_discount` | NUMERIC | `allcoupondiscount` | FACT_MAPPINGS | 全部优惠券折扣金额（元） | 金额值 |
| `goods_promotion_money` | NUMERIC | `goodspromotionmoney` | FACT_MAPPINGS | 商品促销金额（元） | 金额值 |
| `assistant_promotion_money` | NUMERIC | `assistantpromotionmoney` | FACT_MAPPINGS | 助教促销金额（元） | 金额值 |
| `assistant_pd_money` | NUMERIC | `assistantpdmoney` | FACT_MAPPINGS | 助教陪打金额（元） | 金额值 |
| `assistant_cx_money` | NUMERIC | `assistantcxmoney` | FACT_MAPPINGS | 助教促销服务金额（元） | 金额值 |
| `assistant_manual_discount` | NUMERIC | `assistantmanualdiscount` | FACT_MAPPINGS | 助教手动折扣金额（元） | 金额值 |
| `coupon_sale_amount` | NUMERIC | `couponsaleamount` | FACT_MAPPINGS | 券销售金额（元） | 金额值 |
| `member_discount_amount` | NUMERIC | `memberdiscountamount` | FACT_MAPPINGS | 会员折扣金额（元） | 金额值 |
| `point_discount_price` | NUMERIC | `pointdiscountprice` | FACT_MAPPINGS | 积分折扣价格（元） | 金额值 |
| `point_discount_cost` | NUMERIC | `pointdiscountcost` | FACT_MAPPINGS | 积分折扣成本（元） | 金额值 |
| `adjust_amount` | NUMERIC | `adjustamount` | FACT_MAPPINGS | 调整金额（元） | 金额值 |
| `rounding_amount` | NUMERIC | `roundingamount` | FACT_MAPPINGS | 抹零金额（元） | 金额值 |
| `operator_id` | BIGINT | `operatorid` | FACT_MAPPINGS | 操作员 ID | 员工 ID |
| `operator_name_snapshot` | TEXT | `operatorname` | FACT_MAPPINGS | 操作员姓名快照 | 如 `郑丽珊` |
| `salesman_user_id` | BIGINT | `salesmanuserid` | FACT_MAPPINGS | 销售员用户 ID | 用户 ID |
| `salesman_name` | TEXT | `salesmanname` | FACT_MAPPINGS | 销售员姓名 | 姓名或 NULL |
| `order_remark` | TEXT | `orderremark` | FACT_MAPPINGS | 订单备注 | 自由文本或 NULL |
| `table_id` | BIGINT | `tableid` | FACT_MAPPINGS | 台桌 ID | 飞球台桌 ID |
| `serial_number` | INTEGER | `serialnumber` | FACT_MAPPINGS | 流水号 | 正整数 |
| `revoke_order_id` | BIGINT | `revokeorderid` | FACT_MAPPINGS | 撤销关联的订单 ID | 订单 ID 或 0 |
| `revoke_order_name` | TEXT | `revokeordername` | FACT_MAPPINGS | 撤销关联的订单名称 | 名称或 NULL |
| `revoke_time` | TIMESTAMPTZ | `revoketime` | FACT_MAPPINGS | 撤销时间 | ISO 时间戳或 NULL |
---
## 3. B 类表说明
本表属于 B 类（仅补 FACT_MAPPINGS），5 个电费/券字段的 DWD 列在 DDL 中已存在，但之前缺少 FACT_MAPPINGS 条目导致数据未从 ODS 流入 DWD。2026-02-20 补充映射后，这 5 个字段的数据可正常流转。当前门店这 5 个字段的 ODS/DWD 数据全部为 0（业务未启用电费和券销售功能）。
---
## 4. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dwd_recharge_order"]` / `FACT_MAPPINGS["dwd.dwd_recharge_order_ex"]`
- TABLE_MAP：`"dwd.dwd_recharge_order" → "ods.recharge_settlements"`
- DWS 下游：`dws_finance_daily_task.py`（财务日报，充值汇总）

61
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_site_tables_master.md Normal file
View File

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

103
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_store_goods_master.md Normal file
View File

@@ -0,0 +1,103 @@
# BD_Manual：store_goods_master（门店商品档案）
> ODS 表：`ods.store_goods_master`
> DWD 表：`dwd.dim_store_goods`（主表）、`dwd.dim_store_goods_ex`（扩展表）
> API 接口：门店商品列表
> JSON 路径：`store_goods_master.json → data.orderGoodsList`
> 装载方式：SCD2 维度合并（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dim_store_goods（主表）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `site_goods_id` | BIGINT | `id` | FACT_MAPPINGS | 门店商品唯一标识（PK 之一） | 飞球雪花 ID |
| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 租户 ID | 飞球租户 ID |
| `site_id` | BIGINT | `site_id` | 自动映射 | 门店 ID | 飞球门店 ID |
| `tenant_goods_id` | BIGINT | `tenant_goods_id` | 自动映射 | 租户商品 ID，关联 `dim_tenant_goods` | 飞球商品 ID |
| `goods_name` | TEXT | `goods_name` | 自动映射 | 商品名称 | 如 `百威啤酒` |
| `goods_category_id` | BIGINT | `goods_category_id` | 自动映射 | 一级分类 ID | 飞球分类 ID |
| `goods_second_category_id` | BIGINT | `goods_second_category_id` | 自动映射 | 二级分类 ID | 飞球分类 ID |
| `category_level1_name` | TEXT | `onecategoryname` | FACT_MAPPINGS | 一级分类名称 | 如 `酒水` |
| `category_level2_name` | TEXT | `twocategoryname` | FACT_MAPPINGS | 二级分类名称 | 如 `啤酒` |
| `batch_stock_qty` | INTEGER | `batch_stock_quantity` | FACT_MAPPINGS | 批次库存数量（按批次管理的库存）。⚠️ 2026-02-20 修正映射源（原错误映射自 `stock`，即当前库存） | 数值 |
| `sale_qty` | INTEGER | `sale_num` | FACT_MAPPINGS | 累计销售数量 | 数值 |
| `total_sales_qty` | INTEGER | `total_sales` | FACT_MAPPINGS | 累计销售总额 | 数值 |
| `sale_price` | NUMERIC(18,2) | `sale_price` | 自动映射 | 商品售价（元） | 金额值 |
| `created_at` | TIMESTAMPTZ | `create_time` | FACT_MAPPINGS | 商品创建时间 | ISO 时间戳 |
| `updated_at` | TIMESTAMPTZ | `update_time` | FACT_MAPPINGS | 商品最后更新时间 | ISO 时间戳 |
| `avg_monthly_sales` | NUMERIC(18,4) | `average_monthly_sales` | FACT_MAPPINGS | 月均销量 | 数值 |
| `goods_state` | INTEGER | `goods_state` | 自动映射 | 商品状态 | 枚举值 |
| `enable_status` | INTEGER | `enable_status` | 自动映射 | 启用状态 | 枚举值 |
| `send_state` | INTEGER | `send_state` | 自动映射 | 配送状态 | 枚举值 |
| `is_delete` | INTEGER | `is_delete` | 自动映射 | 是否已删除：0=正常，1=已删除 | `0` / `1` |
| `commodity_code` | TEXT | `commodity_code` | FACT_MAPPINGS | 商品编码 | 编码字符串 |
| `not_sale` | INTEGER | `not_sale` | FACT_MAPPINGS | 是否停售：0=在售，1=停售 | `0` / `1` |
| `scd2_*` | — | — | DWD 元数据 | SCD2 慢变维度追踪字段 | — |
---
## 2. dim_store_goods_ex（扩展表）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `site_goods_id` | BIGINT | `id` | FACT_MAPPINGS | 门店商品唯一标识（PK 之一） | 同主表 |
| `site_name` | TEXT | `sitename` | FACT_MAPPINGS | 门店名称快照 | 如 `朗朗桌球` |
| `unit` | TEXT | `unit` | 自动映射 | 计量单位 | 如 `瓶`、`包` |
| `goods_barcode` | TEXT | `goods_bar_code` | FACT_MAPPINGS | 商品条码 | 条码字符串或 NULL |
| `goods_cover_url` | TEXT | `goods_cover` | FACT_MAPPINGS | 商品封面图 URL | HTTPS 链接或 NULL |
| `pinyin_initial` | TEXT | `pinyin_initial` | 自动映射 | 拼音首字母（用于搜索） | 如 `BWPJ` |
| `stock_qty` | INTEGER | `stock` | FACT_MAPPINGS | 当前库存数量（实时库存） | 数值 |
| `stock_secondary_qty` | INTEGER | `stock_a` | FACT_MAPPINGS | 辅助单位库存数量（双单位商品） | 数值 |
| `safety_stock_qty` | INTEGER | `safe_stock` | FACT_MAPPINGS | 安全库存数量（低于此值触发预警） | 数值 |
| `cost_price` | NUMERIC(18,4) | `cost_price` | 自动映射 | 成本价（元） | 金额值 |
| `cost_price_type` | INTEGER | `cost_price_type` | 自动映射 | 成本价类型 | 枚举值 |
| `provisional_total_cost` | NUMERIC(18,2) | `provisional_total_cost` | FACT_MAPPINGS | 暂估总成本（元），按暂估价计算的库存成本。⚠️ 2026-02-20 修正映射源（原错误映射自 `total_purchase_cost`，即实际采购成本） | 金额值 |
| `total_purchase_cost` | NUMERIC(18,2) | `total_purchase_cost` | 自动映射 | 实际采购总成本（元） | 金额值 |
| `min_discount_price` | NUMERIC(18,2) | `min_discount_price` | 自动映射 | 最低折扣价（元） | 金额值 |
| `is_discountable` | INTEGER | `able_discount` | FACT_MAPPINGS | 是否可打折：0=不可，1=可 | `0` / `1` |
| `days_on_shelf` | INTEGER | `days_available` | FACT_MAPPINGS | 上架天数 | 正整数 |
| `audit_status` | INTEGER | `audit_status` | 自动映射 | 审核状态 | 枚举值 |
| `sale_channel` | INTEGER | `sale_channel` | 自动映射 | 销售渠道 | 枚举值 |
| `is_warehousing` | INTEGER | `is_warehousing` | 自动映射 | 是否入库管理：0=否，1=是 | `0` / `1` |
| `freeze_status` | INTEGER | `freeze` | FACT_MAPPINGS | 冻结状态：0=正常，1=冻结 | `0` / `1` |
| `forbid_sell_status` | INTEGER | `forbid_sell_status` | 自动映射 | 禁售状态 | 枚举值 |
| `able_site_transfer` | INTEGER | `able_site_transfer` | 自动映射 | 是否允许门店间调拨：0=否，1=是 | `0` / `1` |
| `custom_label_type` | INTEGER | `custom_label_type` | 自动映射 | 自定义标签类型 | 枚举值 |
| `option_required` | INTEGER | `option_required` | 自动映射 | 是否必选规格：0=否，1=是 | `0` / `1` |
| `remark` | TEXT | `remark` | FACT_MAPPINGS | 商品备注 | 自由文本或 NULL |
| `sort_order` | INTEGER | `sort` | FACT_MAPPINGS | 排序序号 | 正整数 |
| `batch_stock_quantity` | NUMERIC | `batch_stock_quantity` | 自动映射 | 批次库存数量（冗余，与主表 `batch_stock_qty` 同源） | 数值 |
| `time_slot_sale` | INTEGER | `time_slot_sale` | FACT_MAPPINGS | 分时段销售标记（当前观测全部为 2）。2026-02-21 新增 | `2` |
| `scd2_*` | — | — | DWD 元数据 | SCD2 慢变维度追踪字段 | — |
---
## 3. 映射修正记录
| 日期 | 字段 | 修正内容 |
|------|------|---------|
| 2026-02-20 | `batch_stock_qty` | ODS 源从 `stock`（当前库存）修正为 `batch_stock_quantity`（批次库存）。验证：仅 7.3% 行两列值相等 |
| 2026-02-20 | `provisional_total_cost` | ODS 源从 `total_purchase_cost`（实际采购成本）修正为 `provisional_total_cost`（暂估成本）。验证：93.5% 行相等但 113 行不同 |
| 2026-02-21 | `time_slot_sale` | 新增字段。ODS `ods.store_goods_master` + DWD `dwd.dim_store_goods_ex` 同步新增 `time_slot_sale INTEGER`。API 返回值当前全部为 `2` |
---
## 4. 跳过字段说明
| ODS 字段 | 跳过原因 |
|---------|---------|
| ~~`time_slot_sale`~~ | ~~ODS 列不存在~~ → 2026-02-21 已新增，见映射修正记录 |
| `goodsStockWarningInfo` | JSONB 嵌套对象，展开不在本次范围内 |
---
## 5. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dim_store_goods"]` / `FACT_MAPPINGS["dwd.dim_store_goods_ex"]`
- TABLE_MAP：`"dwd.dim_store_goods" → "ods.store_goods_master"`
- DWS 下游：`dws_finance_daily_task.py`（财务日报，商品维度关联）
- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__fix_store_goods_master_mapping.sql`（已归档）
- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-21__add_time_slot_sale_merge_commodity_code.sql`（已归档）

93
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_store_goods_sales_records.md Normal file
View File

@@ -0,0 +1,93 @@
# BD_Manual：store_goods_sales_records（门店商品销售流水）
> ODS 表：`ods.store_goods_sales_records`
> DWD 表：`dwd.dwd_store_goods_sale`（主表）、`dwd.dwd_store_goods_sale_ex`（扩展表）
> API 接口：门店商品销售记录列表
> JSON 路径：`store_goods_sales_records.json → data.orderGoodsLedgers`
> 装载方式：事实表增量插入（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dwd_store_goods_sale（主表，25 列）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `store_goods_sale_id` | BIGINT | `id` | FACT_MAPPINGS | 销售记录唯一标识（PK） | 飞球雪花 ID |
| `order_trade_no` | BIGINT | `order_trade_no` | 自动映射 | 关联的订单交易号 | 飞球订单号 |
| `order_settle_id` | BIGINT | `order_settle_id` | 自动映射 | 关联的结算单 ID | 飞球结算单 ID |
| `order_pay_id` | BIGINT | `order_pay_id` | 自动映射 | 关联的支付单 ID | 飞球支付单 ID |
| `order_goods_id` | BIGINT | `order_goods_id` | 自动映射 | 订单商品明细 ID | 飞球雪花 ID |
| `site_id` | BIGINT | `site_id` | 自动映射 | 门店 ID | 飞球门店 ID |
| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 租户 ID | 飞球租户 ID |
| `site_goods_id` | BIGINT | `site_goods_id` | 自动映射 | 门店商品 ID，关联 `dim_store_goods` | 飞球商品 ID |
| `tenant_goods_id` | BIGINT | `tenant_goods_id` | 自动映射 | 租户商品 ID，关联 `dim_tenant_goods` | 飞球商品 ID |
| `tenant_goods_category_id` | BIGINT | `tenant_goods_category_id` | 自动映射 | 商品分类 ID | 飞球分类 ID |
| `tenant_goods_business_id` | BIGINT | `tenant_goods_business_id` | 自动映射 | 商品业务类型 ID | 飞球业务 ID |
| `site_table_id` | BIGINT | `site_table_id` | 自动映射 | 消费台桌 ID，关联 `dim_table.table_id` | 飞球台桌 ID |
| `ledger_name` | VARCHAR(200) | `ledger_name` | 自动映射 | 分账项名称（商品名称快照） | 如 `百威啤酒` |
| `ledger_group_name` | VARCHAR(100) | `ledger_group_name` | 自动映射 | 分账组名称 | 分账组名或 NULL |
| `ledger_unit_price` | NUMERIC(18,2) | `ledger_unit_price` | 自动映射 | 分账单价（元/单位） | 金额值 |
| `ledger_count` | INTEGER | `ledger_count` | 自动映射 | 分账数量（销售数量） | 正整数 |
| `ledger_amount` | NUMERIC(18,2) | `ledger_amount` | 自动映射 | 分账总金额（元），= 单价 × 数量 | 金额值 |
| `discount_money` | NUMERIC(18,2) | `discount_money` | FACT_MAPPINGS | 折扣金额（元），会员折扣减免的金额。⚠️ 2026-02-20 由原 `discount_price` 重命名而来，修正列名误导 | `0.00` ~ 金额值 |
| `real_goods_money` | NUMERIC(18,2) | `real_goods_money` | 自动映射 | 实收商品金额（元），扣除折扣后 | 金额值 |
| `cost_money` | NUMERIC(18,2) | `cost_money` | 自动映射 | 成本金额（元） | 金额值 |
| `ledger_status` | INTEGER | `ledger_status` | 自动映射 | 分账状态 | 枚举值 |
| `is_delete` | INTEGER | `is_delete` | 自动映射 | 是否已删除：0=正常，1=已删除 | `0` / `1` |
| `create_time` | TIMESTAMPTZ | `create_time` | 自动映射 | 销售记录创建时间 | ISO 时间戳 |
| `coupon_share_money` | NUMERIC(18,2) | `coupon_share_money` | FACT_MAPPINGS | 优惠券分摊金额（元），该商品分摊的优惠券减免 | `0.00` ~ 金额值 |
| `discount_price` | NUMERIC(18,2) | `discount_price` | FACT_MAPPINGS | 折后单价（元），会员折扣后的商品单价。⚠️ 2026-02-20 新增，映射自 ODS 真正的 `discount_price` | `0.00` ~ 金额值 |
---
## 2. dwd_store_goods_sale_ex（扩展表，28 列）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `store_goods_sale_id` | BIGINT | `id` | FACT_MAPPINGS | 销售记录唯一标识（PK） | 同主表 |
| `legacy_order_goods_id` | BIGINT | `ordergoodsid` | FACT_MAPPINGS | 旧版订单商品 ID（兼容字段） | 飞球 ID |
| `site_name` | TEXT | `sitename` | FACT_MAPPINGS | 门店名称快照 | 如 `朗朗桌球` |
| `legacy_site_id` | BIGINT | `siteid` | FACT_MAPPINGS | 旧版门店 ID（兼容字段） | 飞球门店 ID |
| `goods_remark` | TEXT | `goods_remark` | 自动映射 | 商品备注 | 自由文本或 NULL |
| `option_value_name` | TEXT | `option_value_name` | FACT_MAPPINGS | 商品规格选项名称 | 如 `大杯`、NULL |
| `operator_name` | TEXT | `operator_name` | 自动映射 | 操作员姓名 | 姓名或 NULL |
| `open_salesman_flag` | INTEGER | `opensalesman` | FACT_MAPPINGS (cast integer) | 是否开启销售员提成：0=否，1=是 | `0` / `1` |
| `salesman_user_id` | BIGINT | `salesman_user_id` | 自动映射 | 销售员用户 ID | 用户 ID 或 NULL |
| `salesman_name` | TEXT | `salesman_name` | FACT_MAPPINGS | 销售员姓名 | 姓名或 NULL |
| `salesman_role_id` | BIGINT | `salesman_role_id` | 自动映射 | 销售员角色 ID | 角色 ID 或 NULL |
| `salesman_org_id` | BIGINT | `sales_man_org_id` | FACT_MAPPINGS | 销售员组织 ID | 组织 ID 或 NULL |
| `discount_money` | NUMERIC(18,2) | `discount_money` | 自动映射 | 折扣金额（元），扩展表中的折扣明细 | `0.00` ~ 金额值 |
| `returns_number` | INTEGER | `returns_number` | 自动映射 | 退货数量 | `0` ~ 正整数 |
| `coupon_deduct_money` | NUMERIC(18,2) | `coupon_deduct_money` | 自动映射 | 优惠券抵扣金额（元） | `0.00` ~ 金额值 |
| `member_discount_amount` | NUMERIC(18,2) | `member_discount_amount` | 自动映射 | 会员折扣金额（元） | `0.00` ~ 金额值 |
| `point_discount_money` | NUMERIC(18,2) | `point_discount_money` | 自动映射 | 积分抵扣金额（元） | `0.00` ~ 金额值 |
| `point_discount_money_cost` | NUMERIC(18,2) | `point_discount_money_cost` | 自动映射 | 积分抵扣成本（元） | `0.00` ~ 金额值 |
| `package_coupon_id` | BIGINT | `package_coupon_id` | 自动映射 | 套餐券 ID | 券 ID 或 NULL |
| `order_coupon_id` | BIGINT | `order_coupon_id` | 自动映射 | 订单券 ID | 券 ID 或 NULL |
| `member_coupon_id` | BIGINT | `member_coupon_id` | 自动映射 | 会员券 ID | 券 ID 或 NULL |
| `option_price` | NUMERIC(18,2) | `option_price` | 自动映射 | 规格选项加价（元） | `0.00` ~ 金额值 |
| `option_member_discount_money` | NUMERIC(18,2) | `option_member_discount_money` | 自动映射 | 规格选项会员折扣金额（元） | `0.00` ~ 金额值 |
| `option_coupon_deduct_money` | NUMERIC(18,2) | `option_coupon_deduct_money` | 自动映射 | 规格选项优惠券抵扣金额（元） | `0.00` ~ 金额值 |
| `push_money` | NUMERIC(18,2) | `push_money` | 自动映射 | 推销提成金额（元） | `0.00` ~ 金额值 |
| `is_single_order` | INTEGER | `is_single_order` | 自动映射 | 是否单独订单 | `0` / `1` |
| `sales_type` | INTEGER | `sales_type` | 自动映射 | 销售类型 | 枚举值 |
| `operator_id` | BIGINT | `operator_id` | 自动映射 | 操作员 ID | 员工 ID 或 NULL |
---
## 3. 映射修正记录
| 日期 | 字段 | 修正内容 |
|------|------|---------|
| 2026-02-20 | `discount_price` → `discount_money` | 原 DWD `discount_price` 实际映射自 ODS `discount_money`（折扣金额），列名与语义不符，重命名为 `discount_money` |
| 2026-02-20 | `discount_price`（新增） | 新增 DWD 列，映射自 ODS 真正的 `discount_price`（折后单价） |
---
## 4. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dwd_store_goods_sale"]` / `FACT_MAPPINGS["dwd.dwd_store_goods_sale_ex"]`
- TABLE_MAP：`"dwd.dwd_store_goods_sale" → "ods.store_goods_sales_records"`
- DWS 下游：`dws_finance_daily_task.py`（财务日报，商品销售汇总）
- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__fix_store_goods_sale_discount_price.sql`（已归档）

80
apps/etl/connectors/feiqiu/docs/database/cross_layer/BD_Manual_tenant_goods_master.md Normal file
View File

@@ -0,0 +1,80 @@
# BD_Manual：tenant_goods_master（租户商品档案）
> ODS 表：`ods.tenant_goods_master`
> DWD 表：`dwd.dim_tenant_goods`（主表）、`dwd.dim_tenant_goods_ex`（扩展表）
> API 接口：租户商品列表
> JSON 路径：`tenant_goods_master.json → data.tenantGoodsList`
> 装载方式：SCD2 维度合并（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
---
## 1. dim_tenant_goods（主表）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `tenant_goods_id` | BIGINT | `id` | FACT_MAPPINGS | 租户商品唯一标识（PK 之一） | 飞球雪花 ID |
| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 租户 ID | 飞球租户 ID |
| `supplier_id` | BIGINT | `supplier_id` | 自动映射 | 供应商 ID | 飞球供应商 ID 或 0 |
| `category_name` | VARCHAR | `categoryname` | FACT_MAPPINGS | 一级分类名称 | 如 `酒水` |
| `goods_category_id` | BIGINT | `goods_category_id` | 自动映射 | 一级分类 ID | 飞球分类 ID |
| `goods_second_category_id` | BIGINT | `goods_second_category_id` | 自动映射 | 二级分类 ID | 飞球分类 ID |
| `goods_name` | VARCHAR | `goods_name` | 自动映射 | 商品名称 | 如 `百威啤酒` |
| `goods_number` | VARCHAR | `goods_number` | 自动映射 | 商品编号 | 编号字符串 |
| `unit` | VARCHAR | `unit` | 自动映射 | 计量单位 | 如 `瓶`、`包` |
| `market_price` | NUMERIC | `market_price` | 自动映射 | 市场价/建议售价（元） | 金额值 |
| `goods_state` | INTEGER | `goods_state` | 自动映射 | 商品状态 | 整数枚举 |
| `create_time` | TIMESTAMPTZ | `create_time` | 自动映射 | 商品创建时间 | ISO 时间戳 |
| `update_time` | TIMESTAMPTZ | `update_time` | 自动映射 | 商品最后更新时间 | ISO 时间戳 |
| `is_delete` | INTEGER | `is_delete` | 自动映射 | 软删除标记：0=正常，1=已删除 | `0` / `1` |
| `not_sale` | INTEGER | `not_sale` | FACT_MAPPINGS | 是否停售：0=在售，1=停售 | `0` / `1` |
| `scd2_*` | — | — | DWD 元数据 | SCD2 慢变维度追踪字段 | — |
---
## 2. dim_tenant_goods_ex（扩展表）
| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `tenant_goods_id` | BIGINT | `id` | FACT_MAPPINGS | 租户商品唯一标识（PK 之一） | 同主表 |
| `remark_name` | VARCHAR(128) | `remark_name` | FACT_MAPPINGS | 商品备注名称 | 自由文本或 NULL |
| `pinyin_initial` | VARCHAR | `pinyin_initial` | 自动映射 | 商品名称拼音首字母，用于快速检索 | 如 `BWPJ` |
| `goods_cover` | VARCHAR | `goods_cover` | 自动映射 | 商品封面图 URL | HTTPS 链接或 NULL |
| `goods_bar_code` | VARCHAR | `goods_bar_code` | FACT_MAPPINGS | 商品条码 | 条码字符串或 NULL |
| `commodity_code` | VARCHAR | `commodity_code` | 自动映射 | 商品编码（单值，旧字段） | 编码字符串或 NULL |
| `commodity_code_list` | TEXT[] | `commoditycode` | FACT_MAPPINGS (cast TEXT[]) | 商品编码数组。ODS `commoditycode` 存储 PG 数组格式 `{CODE1}`，CAST 为 `TEXT[]`。2026-02-21 从 VARCHAR(256) 改为 TEXT[] | `['1234571']` |
| `min_discount_price` | NUMERIC | `min_discount_price` | 自动映射 | 最低折扣价（元） | 金额值 |
| `cost_price` | NUMERIC | `cost_price` | 自动映射 | 成本价（元） | 金额值 |
| `cost_price_type` | INTEGER | `cost_price_type` | 自动映射 | 成本价类型 | 整数枚举 |
| `able_discount` | INTEGER | `able_discount` | 自动映射 | 是否允许折扣：0=不允许，1=允许 | `0` / `1` |
| `sale_channel` | INTEGER | `sale_channel` | 自动映射 | 销售渠道 | 整数枚举 |
| `is_warehousing` | INTEGER | `is_warehousing` | 自动映射 | 是否入库管理：0=否，1=是 | `0` / `1` |
| `is_in_site` | BOOLEAN | `isinsite` | FACT_MAPPINGS (cast boolean) | 是否已分配到门店 | `true` / `false` |
| `able_site_transfer` | INTEGER | `able_site_transfer` | 自动映射 | 是否允许门店间调拨 | `0` / `1` |
| `common_sale_royalty` | INTEGER | `common_sale_royalty` | 自动映射 | 普通销售提成（分） | 整数 |
| `point_sale_royalty` | INTEGER | `point_sale_royalty` | 自动映射 | 积分销售提成（分） | 整数 |
| `out_goods_id` | BIGINT | `out_goods_id` | 自动映射 | 外部商品 ID（第三方系统关联） | 外部 ID 或 0 |
| `scd2_*` | — | — | DWD 元数据 | SCD2 慢变维度追踪字段 | — |
## 3. 映射修正记录
| 日期 | 字段 | 修正内容 |
|------|------|---------|
| 2026-02-21 | `commodity_code_list` | 类型从 `VARCHAR(256)` 改为 `TEXT[]`。映射源从 `commodity_code`（单值）改为 `commoditycode`（PG 数组格式 `{xxx}`），通过 `::TEXT[]` CAST。现有数据通过 `ARRAY[commodity_code_list]` 迁移 |
---
## 4. 跳过字段说明
所有 ODS 业务字段均已映射到 DWD 主表或扩展表，无跳过字段。
> `commoditycode`（ODS 列）已作为 `commodity_code_list` 的映射源（`commoditycode::TEXT[]`），同时 `commodity_code`（单值旧字段）也保留在扩展表中。
---
## 5. 代码引用
- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dim_tenant_goods"]` / `FACT_MAPPINGS["dwd.dim_tenant_goods_ex"]`
- TABLE_MAP：`"dwd.dim_tenant_goods" → "ods.tenant_goods_master"`
- DWS 下游：无直接 DWS 汇总引用
- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-21__add_time_slot_sale_merge_commodity_code.sql`（已归档）