# 门店商品库存主数据 — 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 ` | | 分页 | `page` + `limit`（最大 100） | | 时间范围 | 不需要（全量快照） | --- ## 二、请求 ### 请求体（JSON） ```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` | 排序权重，用于前端商品列表展示排序 | --- ## 五、响应样例（单条记录） ```json { "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`、成本等某一时刻的快照，库存变动表是全量出入库记录，两者互相补充。