# 门店商品库存主数据（GetGoodsInventoryList） → store_goods_master 字段映射

> 生成时间：2026-02-14

## 端点信息

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