# 租户商品主数据（QueryTenantGoods） → tenant_goods_master 字段映射

> 生成时间：2026-02-14

## 端点信息

| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/QueryTenantGoods` |
| 请求方法 | POST |
| ODS 对应表 | `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` 类型存储
