ZQYY.FQ-ETL/docs/api-reference/store_goods_master.md

门店商品库存主数据 — GetGoodsInventoryList

模块：TenantGoods · ODS 表：store_goods_master · 维度表（快照）

---

一、接口概述

查询门店级商品库存主数据，包括商品基础信息、分类、库存数量、价格/成本、状态开关、销售表现等。每条记录对应一个门店维度的商品，是商品维度的核心维表。与租户商品档案（tenant_goods_master）通过 tenant_goods_id 关联，与库存/销售事实表通过 id（即 site_goods_id）关联。

属性	值
完整路径	POST /TenantGoods/GetGoodsInventoryList
Base URL	https://pc.ficoo.vip/apiprod/admin/v1/
鉴权	Authorization: Bearer <token>
分页	page + limit（最大 100）
时间范围	不需要（全量快照）

---

二、请求

请求体（JSON）

{
  "goodsSecondCategoryId": [],
  "goodsState": 0,
  "enableStatus": 0,
  "siteId": [2790685415443269],
  "existsGoodsStock": 0,
  "page": 1,
  "limit": 100
}

⚠️ 注意：siteId 参数必须为数组格式 [sid]，而非单个整数值。这是本接口的特殊要求。

参数说明

参数	类型	必填	说明
goodsSecondCategoryId	array	是	二级分类 ID 列表，空数组 [] = 全部
goodsState	int	是	商品状态筛选。0 = 全部，1 = 正常，2 = 特殊状态
enableStatus	int	是	启用状态筛选。0 = 全部，1 = 启用
siteId	array	是	门店 ID 数组（如 [2790685415443269]）。必须为数组格式
existsGoodsStock	int	是	是否有库存筛选。0 = 全部
page	int	是	页码，从 1 开始
limit	int	是	每页条数，最大 100

---

三、响应结构

{
  "code": 200,
  "data": {
    "list": [ { ... }, { ... } ],
    "total": 161
  }
}

data.list 中每个对象即为一条门店商品记录，共 45 个字段，按逻辑分组说明如下。

---

四、响应字段详解（45 个字段）

4.1 门店与租户维度

字段	类型	示例	说明
tenant_id	int	2790683160709957	租户/品牌 ID，所有记录相同
site_id	int	2790685415443269	门店 ID，与其他业务表一致
siteName	string	"朗朗桌球"	门店名称，冗余展示字段

4.2 商品标识与分类

字段	类型	示例	说明
id	int	2793025851560005	门店商品 ID（主键）。在其他表中以 site_goods_id / siteGoodsId 出现，用于关联库存、销售记录
tenant_goods_id	int	2792178593255301	租户级商品 ID（全局商品 ID），对应 tenant_goods_master.id。一个全局商品可在多个门店生成多条门店商品
goods_name	string	"合味道泡面"	商品名称，业务展示字段
goods_category_id	int	2791941988405125	一级分类 ID，对应分类树主键，与 oneCategoryName 搭配
goods_second_category_id	int	2793236829620037	二级分类 ID，对应分类树子节点，与 twoCategoryName 搭配
oneCategoryName	string	"零食"	一级分类名称，与 goods_category_id 一一对应
twoCategoryName	string	"面"	二级分类名称，与 goods_second_category_id 对应
unit	string	"桶"	计量单位。常见值：包、瓶、个、份、根、盒、杯、桶、盘、支等
goods_cover	string	"https://oss.ficoo.vip/..."	商品图片 URL（OSS 存储）
pinyin_initial	string	"HWDPM,GWDPM"	拼音首字母/助记码，多别名逗号分隔，用于前台拼音检索
goods_bar_code	string	""	商品条形码（EAN 等），当前门店未配置，全部为空

4.3 库存与数量

字段	类型	示例	说明
stock	int	18	当前可用库存数量（以 unit 为单位）。可为 0（售罄）或很大（虚拟库存）
stock_A	int	0	副单位库存数量（双单位场景如箱/瓶）。当前门店未启用，全部为 0
batch_stock_quantity	int	43	当前批次库存数量（主单位）。有成本价时 batch_stock_quantity × cost_price ≈ provisional_total_cost
sale_num	int	104	当前统计口径下的销售数量（总销量），与 total_sales 一致
total_sales	int	104	累计销售数量。当前与 sale_num 相同，字段保留了区间销量 vs 历史总销量的扩展空间
safe_stock	int	0	安全库存量（阈值），低于此值可提示补货。当前未设置，全部为 0

4.4 价格、成本与金额

字段	类型	示例	说明
sale_price	float	12.0	标准销售价（挂牌价），单位：元（人民币）。实际结算可能打折
cost_price	float	0.0	成本价（单件成本），单位：元。部分为 0（未录入），部分有值如 1.788
cost_price_type	int	1	成本价类型：1 = 固定成本价（手工维护），2 = 动态成本价（按采购单平均价结转）
provisional_total_cost	float	0.0	暂估总成本，单位：元。有成本价时 ≈ batch_stock_quantity × cost_price
total_purchase_cost	float	0.0	总采购成本，单位：元。当前与 provisional_total_cost 相等，字段为后续结算/重算成本保留空间
min_discount_price	float	7.0	最低允许成交价（限价），单位：元。0 表示不设置限价。收银改价时系统校验不低于此值
able_discount	int	1	是否允许参与折扣：1 = 允许。当前全部为 1

4.5 时间与销售表现

字段	类型	示例	说明
create_time	string	"2025-07-16 11:52:51"	门店商品档案创建时间
update_time	string	"2025-11-09 07:23:47"	最后修改时间（价格调整、状态变更等）
days_available	int	13	商品在架天数/可售天数。0 表示刚建档/刚启用
average_monthly_sales	float	1.32	平均月销量（件/月），辅助补货/品类管理的历史行为指标

4.6 状态与开关

字段	类型	示例	说明
goods_state	int	1	商品基本状态：1 = 正常，2 = 特殊状态（新建/停售/未完整启用，通常 stock=0、days_available=0）
audit_status	int	2	审核状态：2 = 审核通过。其他可能值：0 = 待提交，1 = 待审核，3 = 不通过
enable_status	int	1	启用状态：1 = 启用，2 = 停用（未出现）
send_state	int	1	上架/可售状态：1 = 可销售/可下单
sale_channel	int	1	销售渠道：1 = 门店线下渠道
is_warehousing	int	1	是否纳入库存管理：1 = 参与库存管理
is_delete	int	0	逻辑删除标志：0 = 未删除，1 = 已删除
freeze	int	0	冻结状态：0 = 未冻结。非 0 可能表示"锁库存""禁止出库"
forbid_sell_status	int	1	禁止销售状态：1 = 未禁止（允许销售），2 = 被禁止
able_site_transfer	int	2	是否允许跨门店调拨：2 = 不允许（绝大多数），0 = 未配置
custom_label_type	int	2	自定义标签类型：2 = 使用自定义标签/分类
option_required	int	1	是否需要选择规格/选项：1 = 不要求（单规格商品）

4.7 其他辅助

字段	类型	示例	说明
remark	string	""	商品备注（口味说明、供应商等），当前未使用
sort	int	100	排序权重，用于前端商品列表展示排序

---

五、响应样例（单条记录）

{
  "siteName": "朗朗桌球",
  "oneCategoryName": "零食",
  "twoCategoryName": "面",
  "id": 2793025851560005,
  "tenant_goods_id": 2792178593255301,
  "site_id": 2790685415443269,
  "tenant_id": 2790683160709957,
  "goods_name": "合味道泡面",
  "goods_cover": "https://oss.ficoo.vip/admin/8M1WM7_1753204221337.jpg",
  "goods_state": 1,
  "goods_category_id": 2791941988405125,
  "unit": "桶",
  "sale_num": 104,
  "cost_price": 0.0,
  "provisional_total_cost": 0.0,
  "total_purchase_cost": 0.0,
  "batch_stock_quantity": 43,
  "sale_price": 12.0,
  "stock_A": 0,
  "stock": 18,
  "create_time": "2025-07-16 11:52:51",
  "is_delete": 0,
  "custom_label_type": 2,
  "goods_second_category_id": 2793236829620037,
  "total_sales": 104,
  "remark": "",
  "audit_status": 2,
  "update_time": "2025-11-09 07:23:47",
  "pinyin_initial": "HWDPM,GWDPM",
  "goods_bar_code": "",
  "able_discount": 1,
  "min_discount_price": 7.0,
  "sort": 100,
  "freeze": 0,
  "days_available": 13,
  "average_monthly_sales": 1.32,
  "safe_stock": 0,
  "send_state": 1,
  "enable_status": 1,
  "sale_channel": 1,
  "able_site_transfer": 2,
  "cost_price_type": 1,
  "forbid_sell_status": 1,
  "is_warehousing": 1,
  "option_required": 1
}

---

六、跨表关联

与租户商品档案（tenant_goods_master）

本表字段	关联表字段	说明
tenant_goods_id	id	门店商品 → 品牌级商品。一个全局商品可在多个门店生成多条门店商品
goods_category_id	goods_category_id	一级分类 ID 一致
goods_second_category_id	goods_second_category_id	二级分类 ID 一致

与门店销售记录（store_goods_sales_records）

本表字段	关联表字段	说明
id	site_goods_id	门店商品主键 → 销售明细中的商品 ID
tenant_goods_id	tenant_goods_id	全局商品 ID 一致

本表是维表，销售记录是事实表。

与库存汇总（goods_stock_summary）

本表字段	关联表字段	说明
id	siteGoodsId	门店商品 ID
goods_category_id	goodsCategoryId	一级分类 ID
goods_second_category_id	goodsCategorySecondId	二级分类 ID
unit	goodsUnit	计量单位

与库存变动（goods_stock_movements）

本表字段	关联表字段	说明
id	siteGoodsId	门店商品 ID
goods_category_id	goodsCategoryId	一级分类 ID

与商品分类树（stock_goods_category_tree）

本表字段	关联表字段	说明
goods_category_id	id（一级节点）	一级分类主键
goods_second_category_id	id（二级节点）	二级分类主键

本表提供 stock、batch_stock_quantity、成本等某一时刻的快照，库存变动表是全量出入库记录，两者互相补充。