259 lines
11 KiB
Markdown
259 lines
11 KiB
Markdown
# 门店商品库存主数据 — 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` | 排序权重，用于前端商品列表展示排序 |
|
||
|
||
---
|
||
|
||
## 五、响应样例（单条记录）
|
||
|
||
```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/ 确认字段覆盖完整
|
||
-->
|