# 库存汇总报表（GetGoodsStockReport） → goods_stock_summary 字段映射

> 生成时间：2026-02-14

## 端点信息

| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/GetGoodsStockReport` |
| 请求方法 | POST |
| ODS 对应表 | `ods.goods_stock_summary` |
| JSON 数据路径 | `$（平铺结构）` |

## 字段映射

| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
|-----------|----------|----------|------|
| siteGoodsId | siteGoodsId | int→BIGINT（`parse_int`） | 门店商品 ID，本库存汇总表的主键，对应某个具体商品在本店的唯一标识 |
| goodsName | goodsName | string→TEXT（原样） | 商品名称，冗余于门店商品档案的 goods_name |
| goodsUnit | goodsUnit | string→TEXT（原样） | 商品的计量单位（售卖单位） |
| goodsCategoryId | goodsCategoryId | int→BIGINT（`parse_int`） | 一级商品分类 ID |
| goodsCategorySecondId | goodsCategorySecondId | int→BIGINT（`parse_int`） | 二级（次级）商品分类 ID，是 goodsCategoryId 的下级分类 |
| categoryName | categoryName | string→TEXT（原样） | 一级分类名称，属于冗余字段，用于直接展示 |
| rangeStartStock | rangeStartStock | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间 起始时刻 的库存数量（期初库存） |
| rangeEndStock | rangeEndStock | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间 结束时刻 的库存数量（期末库存） |
| rangeIn | rangeIn | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间内的 入库数量汇总（正值），包括采购入库、调拨入库等 |
| rangeOut | rangeOut | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间内的 出库数量汇总，以 负数 表示从库存扣减（出库/销售） |
| rangeSale | rangeSale | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间内，该商品的 销售数量汇总（售出多少“包/瓶/份”等） |
| rangeSaleMoney | rangeSaleMoney | float→NUMERIC(18,2)（`parse_decimal`） | 查询区间内，该商品销售的 金额小计（按商品维度汇总） |
| rangeInventory | rangeInventory | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 查询区间内的 盘点调整净变动量（盘盈–盘亏） |
| currentStock | currentStock | float→NUMERIC(18,4)（`parse_decimal(scale=4)`） | 导出时刻的实时库存数量 |

## ETL 补充字段

| ODS 列名 | 生成逻辑 |
|-----------|----------|
| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
| source_file | 固定值：`goods_stock_summary.json`，标识原始导出文件 |
| source_endpoint | API 端点路径，如 `TenantGoods/GetGoodsStockReport` |
| 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` 类型存储
