# 门店商品库存主数据（GetGoodsInventoryList）

> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本

## 基本信息

| 属性 | 值 |
|------|-----|
| 接口路径 | `TenantGoods/GetGoodsInventoryList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/TenantGoods/GetGoodsInventoryList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `store_goods_master` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要 |

## 请求参数

| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `goodsSecondCategoryId` | array | `[]` | 二级分类 ID 列表（空=全部） |
| `goodsState` | int | `0` | 商品状态（0=全部） |
| `enableStatus` | int | `0` | 启用状态（0=全部） |
| `siteId` | array | `[2790685415443269]` | 门店 ID |
| `existsGoodsStock` | int | `0` | 是否有库存（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |

## 响应字段（共 45 个）

| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteName` | string | '朗朗桌球' |
| 2 | `oneCategoryName` | string | '零食' |
| 3 | `twoCategoryName` | string | '面' |
| 4 | `id` | int | 2793025851560005 |
| 5 | `tenant_goods_id` | int | 2792178593255301 |
| 6 | `site_id` | int | 2790685415443269 |
| 7 | `tenant_id` | int | 2790683160709957 |
| 8 | `goods_name` | string | '合味道泡面' |
| 9 | `goods_cover` | string | 'https://oss.ficoo.vip/admin/8M1WM7_1753204221337.jpg' |
| 10 | `goods_state` | int | 1 |
| 11 | `goods_category_id` | int | 2791941988405125 |
| 12 | `unit` | string | '桶' |
| 13 | `sale_num` | int | 104 |
| 14 | `cost_price` | float | 0.0 |
| 15 | `provisional_total_cost` | float | 0.0 |
| 16 | `total_purchase_cost` | float | 0.0 |
| 17 | `batch_stock_quantity` | int | 43 |
| 18 | `sale_price` | float | 12.0 |
| 19 | `stock_A` | int | 0 |
| 20 | `stock` | int | 18 |
| 21 | `create_time` | string | '2025-07-16 11:52:51' |
| 22 | `is_delete` | int | 0 |
| 23 | `custom_label_type` | int | 2 |
| 24 | `goods_second_category_id` | int | 2793236829620037 |
| 25 | `total_sales` | int | 104 |
| 26 | `remark` | string | '' |
| 27 | `audit_status` | int | 2 |
| 28 | `update_time` | string | '2025-11-09 07:23:47' |
| 29 | `pinyin_initial` | string | 'HWDPM,GWDPM' |
| 30 | `goods_bar_code` | string | '' |
| 31 | `able_discount` | int | 1 |
| 32 | `min_discount_price` | float | 7.0 |
| 33 | `sort` | int | 100 |
| 34 | `freeze` | int | 0 |
| 35 | `days_available` | int | 13 |
| 36 | `average_monthly_sales` | float | 1.32 |
| 37 | `safe_stock` | int | 0 |
| 38 | `send_state` | int | 1 |
| 39 | `enable_status` | int | 1 |
| 40 | `sale_channel` | int | 1 |
| 41 | `able_site_transfer` | int | 2 |
| 42 | `cost_price_type` | int | 1 |
| 43 | `forbid_sell_status` | int | 1 |
| 44 | `is_warehousing` | int | 1 |
| 45 | `option_required` | int | 1 |

## 新增字段（相对本地 JSON 样本）

以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：

| 字段名 | 类型 |
|--------|------|
| `commodity_code` | string |
| `goodsStockWarningInfo` | object |
| `not_sale` | int |
| `time_slot_sale` | int |

## 详细字段分析

> 以下内容迁移自旧版 `store_goods_master-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。

二、记录级字段详解（45 个字段逐一说明）

我按“维度分类”来拆，确保每个字段都覆盖到。

1. 门店/租户维度

tenant_id

类型：int

含义：租户/品牌 ID。同一品牌下多个门店共享一个 tenant_id。

枚举情况：本文件中为单一固定值（同一品牌）。

site_id

类型：int

含义：门店 ID。

枚举情况：本文件中为单一固定值（同一家门店“朗朗桌球”），和其它 JSON 中的 site_id 一致。

siteName

类型：string

观察值：全为 "朗朗桌球"

含义：门店名称，是对 site_id 的冗余展示，方便直接阅读，无需再去关联门店档案。

2. 商品标识和分类维度

id

类型：int

含义：门店商品 ID，门店维度的商品主键。

用途：在其它文件中经常以 site_goods_id 的名字出现，与这里的 id 一致，用来关联库存记录、销售记录等。

tenant_goods_id

类型：int

含义：租户/品牌维度的商品 ID，相当于“全局商品 ID”。

用途：用于跨门店或与“商品档案（商品档案.json）”对齐时使用。

goods_name

类型：string

含义：商品名称，例如“合味道泡面”“地道肠”“麻将房茶位费”等。

用途：业务展示字段，历史流水里也会冗余存一份商品名。

goods_category_id

类型：int

含义：商品一级分类 ID。

用途：

对应“分类表”（在库存变化记录 2 等文件里）中的主键。

与 oneCategoryName 搭配使用。

goods_second_category_id

类型：int

含义：商品二级分类 ID。

用途：

同样对应分类表中的某个分类 id，其 pid 为一级分类。

与 twoCategoryName 搭配使用。

oneCategoryName

类型：string

含义：一级分类名称，如“零食”“酒水”“服务费”等。

说明：与 goods_category_id 一一对应，是易读文本字段。

twoCategoryName

类型：string

含义：二级分类名称，如“面”“洋酒”“纸巾”等。

说明：与 goods_second_category_id 对应。

unit

类型：string

观察值示例："包", "瓶", "个", "份", "根", "杯", "盒", "桶", "盘", "支" 等。

含义：商品计量单位（销售单位）。

goods_bar_code

类型：string

观察值：当前导出中全部为空字符串。

含义：商品条形码（如 EAN-13 编码），用于扫码销售。此字段设计为可填，但此店目前未配置。

goods_cover

类型：string

含义：商品图片 URL（如 OSS 对象存储地址），用于前端展示商品图片。

pinyin_initial

类型：string

观察值示例："HWDPM,GWDPM", "HJM", "DDC", "QJF150", "15YHGBL" 等。

含义：商品名称的拼音首字母缩写，有时多个别名用逗号分隔。

作用：

用于前端按拼音检索、排序，加快模糊搜索（输入字母即可搜到商品）。

3. 库存与数量相关字段

stock

类型：int

含义：当前可用库存数量（以 unit 为单位）。

特征：可以是 0（库存卖完），也可以非常大（例如纸巾、茶位费这种按“份”计的虚拟库存设定）。

stock_A

类型：int

观察值：本文件全部为 0。

含义（系统设计）：副单位库存数量。如果商品存在双单位（例如箱/瓶），stock_A 通常用于记录副单位库存。当前门店没有启用副单位库存管理，因此为 0。

batch_stock_quantity

类型：int

含义：当前“批次”的库存数量（主单位）。

典型特征：

与 stock 和历史销量有强相关：

对于长期在售商品，batch_stock_quantity 通常大于等于 stock，两者差额可理解为：本批次进货数量减去该批次已消耗数量。

对于刚建档但未真正建立采购记录的商品，可能只是 1 等占位值。

结构性结论：

在有成本价的商品上，batch_stock_quantity × cost_price ≈ provisional_total_cost，说明它是“当前成本批次”的数量基数。

sale_num

类型：int

含义：在当前统计口径下的销售数量（总销量，单位同 unit）。

特征：和 total_sales 完全一致（当前导出时的统计口径下），说明两者是同一统计周期。

total_sales

类型：int

含义（从命名看）：累计销售数量。

实际：当前数据中 total_sales == sale_num，说明此接口的统计区间 = “截至当前的全部历史”，因此数量一致。

结构意义：如果将来系统只查询一段时间，则 sale_num 可能是区间销量，total_sales 可能是历史总销量；字段保留了扩展空间。

safe_stock

类型：int

观察值：全部为 0。

含义：安全库存量（阈值），低于该值时系统可以提示补货。

当前门店尚未设置安全库存，所以全部为 0，仅起到结构占位作用。

4. 价格、成本与金额相关字段

sale_price

类型：float

含义：商品标准销售价（挂牌价），单位为元。

说明：实际结算时可能会打折或用券抵扣，但这个字段表示“定价”。

cost_price

类型：float

含义：商品成本价（单件成本）。

观察：

部分商品为 0（未录入或通过其它方式结转成本），

部分商品为正数，比如“地道肠” cost_price=1.788。

cost_price_type

类型：int，枚举

观察值：

1：154 条

2：7 条

含义（结合成本字段推测）：

1 代表使用“固定成本价”（手工维护的 cost_price），provisional_total_cost 按“数量 × cost_price”算。

2 代表使用“动态成本价”（例如按采购单平均价结转），当前导出中这部分商品 provisional_total_cost 多为 0，说明成本尚未按采购单结转。

provisional_total_cost

类型：float

含义：暂估总成本，单位为元。

观测规律：

对于有成本价的商品，provisional_total_cost ≈ batch_stock_quantity × cost_price（四舍五入差 0.00X 级别）。

结构上的作用：

用于在不逐条展开采购明细的前提下，快速给出当前库存价值的估算。

total_purchase_cost

类型：float

含义：总采购成本，单位为元。

当前数据：与 provisional_total_cost 完全相等。

解释：

从名字看，“total_purchase_cost” 更偏向“已确认采购成本”，而“provisional_total_cost” 更偏向“暂估成本”；在你这份导出中两者还没有区分开来，但字段为后续做结算/重算成本保留了结构空间。

min_discount_price

类型：float

观察值：有的为 0，有的明显小于等于 sale_price（如 sale_price=12, min_discount_price=7）。

含义：最低允许成交价（限价）。

用法逻辑（推测）：

收银/后台手动改价时，系统会校验最终成交价是否 ≥ min_discount_price，低于此价格则不允许成交或需要额外权限。

为 0 时，可能表示“不设置限价/由其它规则控制”。

able_discount

类型：int，枚举

观察值：全部为 1。

含义（结合命名）：

是否允许参与折扣。当前全部为 1，说明所有商品都允许打折。

若系统开启限制，可能会出现 0=不参与任何折扣策略的商品。

5. 时间与销售表现相关字段

create_time

类型：string，格式 YYYY-MM-DD HH:MM:SS

含义：门店商品档案创建时间（商品在门店建立档案的时间点）。

update_time

类型：string

含义：最后一次修改该商品档案的时间（包括价格调整、状态变更等）。

days_available

类型：int

观察值示例：0、1、2、3、12、13、56、100、400、500、2875 等，大范围分布。

含义（结构推断很明确）：

商品“在架天数”或“可售天数”，大致等于当前时间减去首次上架时间。

为 0 的多数是刚建档/刚启用不久的商品。

average_monthly_sales

类型：float

观察值：如 1.32、0.42、13.06、0.16 等。

含义：平均月销量（件/月），根据某个统计周期内的销售数据折算而来。

结构特征：

实际计算公式系统内部掌握即可，你这边只需知道该字段是“历史行为汇总指标”，不参与账务，只是帮助做补货/品类管理的辅助指标。

6. 状态与开关类字段

这类字段很多都是“0/1/2 枚举标志”，需要集中看清。

goods_state

类型：int，枚举

观察值：

1：152 条

2：9 条

结构性判断：

1：正常状态（主流值）。

2：特殊状态（例如“新建未完全启用”、“停售但未下架”等）——这 9 条商品特点是：stock=0、batch_stock_quantity=1、days_available=0，说明它们处于一种“建档但未形成完整库存/销售”的边缘状态。

和 enable_status、send_state 叠加使用，共同确定对外是否可售。

audit_status

类型：int，枚举

观察值：全部为 2。

含义（典型业务语义）：

2：审核通过。

其他值（未在本数据中出现）可能是 0=待提交，1=待审核，3=审核不通过等。

说明：代表这批商品档案已经通过审核，才允许参与业务。

enable_status

类型：int，枚举

观察值：全部为 1。

含义（结合名称与常见编码）：

1：启用。

可能存在 2：停用（未在本数据中出现，但可以推断）。

作用：控制商品档案是否参与任何业务（库存、销售等）。

send_state

类型：int，枚举

观察值：全部为 1。

含义（命名趋近“上架状态/可售状态”）：

1：可销售/可下单。

其它值可能表示“停售”“仅内部使用”等，本数据暂未出现。

备注：和 enable_status、goods_state 一起使用，表达商品对外可售的综合状态。

sale_channel

类型：int，枚举

观察值：全部为 1。

含义：销售渠道类型。

常见模式：

1 可能代表“门店堂食/线下”；

其他值（未出现）可能代表“外卖/线上商城/第三方平台”等。

is_warehousing

类型：int，枚举

观察值：全部为 1。

含义：是否纳入库存管理。

1：启用库存管理（会有出入库流水）。

其他值（0/2）在你其它文件中出现过，一般代表“不计库存”或“历史遗留编码”。

当前门店所有商品都启用了库存管理。

is_delete

类型：int，枚举

观察值：全部为 0。

含义：逻辑删除标志。

0：未删除（有效档案）；

1：已删除（逻辑上删除，不再参与业务，但历史流水保留）。

freeze

类型：int，枚举

观察值：全部为 0。

含义：冻结状态。

0：未冻结；

非 0（未出现在当前数据中）可能表示“锁库存”“禁止出库”等特殊状态。

forbid_sell_status

类型：int，枚举

观察值：全部为 1。

命名上是“禁止销售状态”，结合常见模式：

1：未禁止（允许销售）；

2：被禁止销售（即使上架也不能卖）。

当前门店没有被单独禁售的商品。

able_site_transfer

类型：int，枚举

观察值：

2：160 条

0：1 条

含义（结合命名与值分布）：

表示是否允许跨门店调拨或跨站点共享库存。

2 多半表示“不允许跨店调拨”；0 可能是“未配置/默认值”。

当前门店商品基本都不允许做跨店调拨。

custom_label_type

类型：int，枚举

观察值：全部为 2。

含义（推测）：自定义标签类型。

1：使用系统默认标签（未出现）；

2：使用自定义标签/分类（当前所有商品都为 2）。

从字段名看，和一二级分类、标签打印等功能有关。

option_required

类型：int，枚举

观察值：全部为 1。

含义（推测）：是否需要在销售时选择规格/选项。

1：不要求额外选项（单规格商品）；

若出现其他值，可能代表“必须选择配料/口味/规格”等。

当前门店把所有商品都当作“单规格”处理，未开启复杂选项体系。

able_discount（前面已分析）

类型：int，枚举

观察值：全部为 1，表示所有商品允许参与折扣。

**send_state / enable_status / goods_state 综合说明：

这三个字段都与商品状态相关，但侧重点不同：

goods_state：商品基本状态（建档层面的状态）。

enable_status：是否启用这条商品档案。

send_state：是否在销售端可下单。

当前数据看：绝大多数商品是完全“正常可售”的状态（1/1/1），有少数 goods_state = 2 的边缘状态商品，其他两个字段依然是启用和可售，说明 goods_state 主要用于后台管理上的状态区分。

7. 其它辅助字段

remark

类型：string

观察值：全部为空字符串。

含义：商品备注（可以写口味说明、供应商、注意事项等）。当前尚未使用。

sort

类型：int

观察值：如 100、120 等。

含义：排序权重，用于前端商品列表展示时的排版顺序，数值越小/越大哪个优先，具体规则看系统设定（一般是数值越小排序越靠前）。

batch_stock_quantity / total_purchase_cost / provisional_total_cost 关系补充

对于成本价非 0 的商品，大致满足：

total_purchase_cost ≈ batch_stock_quantity × cost_price

provisional_total_cost ≈ total_purchase_cost

说明：

这套字段主要服务于库存价值估算，和盈利分析无关，是为后续进销存对账、成本核算准备的结构。

三、字段枚举与可能取值小结

为方便后续开发或建模使用，枚举字段集中整理如下（仅基于当前导出数据推断）：

goods_state：

1：正常状态（主流值）

2：特殊状态（新建/停售/未完整启用，配合 stock=0、days_available=0）

audit_status：

2：审核通过（当前唯一值）

enable_status：

1：启用（当前唯一值；停用值未出现在数据中）

send_state：

1：可销售（当前唯一值）

sale_channel：

1：线下门店渠道（当前唯一值）

is_warehousing：

1：参与库存管理（当前唯一值）

is_delete：

0：未删除（当前唯一值）

freeze：

0：未冻结（当前唯一值）

forbid_sell_status：

1：未被禁止销售（当前唯一值）

able_site_transfer：

2：不允许跨店/跨站点调拨（绝大多数记录）

0：未配置（个别记录）

cost_price_type：

1：固定成本价

2：动态成本价（暂未生成实际成本）

custom_label_type：

2：自定义标签（当前唯一值）

option_required：

1：不要求额外选项（单规格商品）

able_discount：

1：允许参与折扣（当前唯一值）

四、从结构角度看，这个文件在整体数据体系中的位置

虽然你目前只要求这个文件本身的字段分析，但结合之前已看过的其它 JSON，可以从字段结构看出以下几条重要关系（纯结构角度，不做任何金额/盈利分析）：

与“商品档案（全局）”的关系

tenant_goods_id 对应全局商品档案中的 id，表示“品牌维度”的商品。

id 则是“门店维度”的商品 ID，对应其它文件中的 site_goods_id。

这说明：

一个全局商品可以在多个门店下产生多个 id（门店商品），各自维护自己的库存、定价、状态。

与库存类文件的关系

在“库存变化记录”“库存汇总”等文件中，字段 siteGoodsId 就是这里的 id，goodsCategoryId/goodsSecondCategoryId 就是这里的 goods_category_id/goods_second_category_id。

也就是说：

门店商品档案 = 商品“主档”；

库存变化记录 = 商品“流水”；

库存汇总 = 商品“统计汇总”。

本文件提供的 stock、batch_stock_quantity、成本相关字段是某一时刻的快照，而库存变动表是全量出入库记录，两者在结构上互相补充。

与销售类文件的关系

“门店销售记录.json” 中的 site_goods_id 与本文件的 id 对应，tenant_goods_id 也一致。

销售记录只记录每一笔销售的数量和金额；而“门店商品档案”提供了商品的基础信息和聚合信息（如 sale_num、average_monthly_sales等）。

从结构角度看，商品档案是维表，销售记录是事实表。

与分类结构的关系

goods_category_id、goods_second_category_id + oneCategoryName、twoCategoryName 在库存分类文件中也有完全对应的 ID 和名称。

整个系统的分类树（父子关系）由分类表维护，这里只是把“已经归类好”的结果冗余在商品档案里，便于业务侧直接使用。