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