# 门店商品库存主数据 — 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）

```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` | 排序权重，用于前端商品列表展示排序 |
| `commodity_code` | string | `10000002` | 商品编码，门店内部商品管理编号 |
| `goodsStockWarningInfo` | object | `{...}` | 库存预警信息对象，含预警阈值等子字段（暂不入 ODS，按需展开） |
| `not_sale` | integer | `2` | 非售卖标记枚举（如 2=正常售卖），控制商品是否参与销售 |
| `time_slot_sale` | integer | `2` | 时段售卖标记枚举（如 2=不限时段），控制商品是否仅在特定时段可售 |

---

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

```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`、成本等某一时刻的快照，库存变动表是全量出入库记录，两者互相补充。

<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/store_goods_master.md，按逻辑分组详解所有 45 个字段，含跨表关联；特别标注 siteId 必须为数组格式
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整

- 日期: 2026-02-14
- Prompt: P20260214-103000 — MD 占位符修正 + 临时文件清理
- 直接原因: v2 脚本自动插入的占位符描述需替换为正式中文业务说明
- 变更摘要: commodity_code、goodsStockWarningInfo、not_sale、time_slot_sale 四个新字段的占位符描述替换为正式中文说明
- 风险与验证: 纯文档文案修正，无运行时影响；验证：grep "新发现字段" 本文件应返回 0 结果
-->