在前后端开发联调前 的提交20260223

docs/database/BD_Manual_store_goods_master.md

@@ -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`（已归档）