20 KiB
门店商品库存主数据（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 个字段逐一说明）
我按“维度分类”来拆，确保每个字段都覆盖到。
- 门店/租户维度
tenant_id
类型：int
含义：租户/品牌 ID。同一品牌下多个门店共享一个 tenant_id。
枚举情况：本文件中为单一固定值（同一品牌）。
site_id
类型：int
含义：门店 ID。
枚举情况：本文件中为单一固定值（同一家门店“朗朗桌球”），和其它 JSON 中的 site_id 一致。
siteName
类型：string
观察值：全为 "朗朗桌球"
含义：门店名称，是对 site_id 的冗余展示，方便直接阅读，无需再去关联门店档案。
- 商品标识和分类维度
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" 等。
含义：商品名称的拼音首字母缩写，有时多个别名用逗号分隔。
作用：
用于前端按拼音检索、排序，加快模糊搜索（输入字母即可搜到商品）。
- 库存与数量相关字段
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，仅起到结构占位作用。
- 价格、成本与金额相关字段
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=不参与任何折扣策略的商品。
- 时间与销售表现相关字段
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 等。
含义：平均月销量（件/月），根据某个统计周期内的销售数据折算而来。
结构特征：
实际计算公式系统内部掌握即可，你这边只需知道该字段是“历史行为汇总指标”，不参与账务，只是帮助做补货/品类管理的辅助指标。
- 状态与开关类字段
这类字段很多都是“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 主要用于后台管理上的状态区分。
- 其它辅助字段
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 和名称。
整个系统的分类树（父子关系）由分类表维护，这里只是把“已经归类好”的结果冗余在商品档案里，便于业务侧直接使用。