# 库存汇总报表 — GetGoodsStockReport

> 模块：`TenantGoods` · ODS 表：`goods_stock_summary` · 汇总事实表（按时间范围聚合）

---

## 一、接口概述

查询门店商品在指定时间范围内的库存汇总数据，每条记录对应一个门店商品在查询区间内的期初/期末库存、出入库数量、盘点调整、销售数量与金额的汇总。所有记录严格满足库存平衡公式：`rangeStartStock + rangeIn + rangeInventory + rangeOut = rangeEndStock`。是库存变动明细（`goods_stock_movements`）按商品维度 + 时间范围聚合后的结果。

| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /TenantGoods/GetGoodsStockReport` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |

---

## 二、请求

### 请求体（JSON）

```json
{
  "siteId": 2790685415443269,
  "startTime": "2026-02-01 08:00:00",
  "endTime": "2026-02-13 08:00:00",
  "page": 1,
  "limit": 100
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

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

`data.list` 中每个对象即为一条商品库存汇总记录，共 14 个字段，按逻辑分组说明如下。

---

## 四、响应字段详解（14 个字段）

### 4.1 商品主键与基本信息

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteGoodsId` | int | `3089190204491141` | 门店商品 ID，本表主键（每个 `siteGoodsId` 仅一条记录）。对应门店商品档案（`store_goods_master`）的 `id`，也对应库存变动的 `siteGoodsId` |
| `goodsName` | string | `"小合味道"` | 商品名称，冗余于门店商品档案的 `goods_name`，方便直接阅读汇总报表 |
| `goodsUnit` | string | `"桶"` | 计量单位，与门店商品档案的 `unit` 一致。常见值：包（59）、瓶（46）、个（17）、份（13）、根（10）、盒、杯、桶、盘、支等 |

### 4.2 分类维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `goodsCategoryId` | int | `2791941988405125` | 一级分类 ID，共 9 个不同值，与 `categoryName` 一一对应。对应分类树主键 |
| `goodsCategorySecondId` | int | `2793236829620037` | 二级分类 ID，共 14 个不同值。对应分类树子节点，名称需到分类表或门店商品档案中查询 |
| `categoryName` | string | `"零食"` | 一级分类名称（冗余展示字段）。枚举值共 9 个：零食、酒水、香烟、其他、雪糕、器材、小吃、槟榔、果盘 |

### 4.3 库存数量（查询区间）

> 库存平衡公式：`rangeStartStock + rangeIn + rangeInventory + rangeOut = rangeEndStock`

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `rangeStartStock` | int | `0` | 查询区间起始时刻的库存数量（期初库存） |
| `rangeEndStock` | int | `22` | 查询区间结束时刻的库存数量（期末库存） |
| `rangeIn` | int | `24` | 区间内入库数量汇总（正值），包括采购入库、调拨入库等 |
| `rangeOut` | int | `-2` | 区间内出库数量汇总，以**负数**表示（出库/销售扣减）。注意：直接做代数求和，无需取绝对值 |
| `rangeInventory` | int | `0` | 区间内盘点调整净变动量（盘盈 − 盘亏）。当前样本全部为 0（无盘点或盘点无净影响） |

### 4.4 实时库存快照

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `currentStock` | int | `22` | 导出时刻的实时库存数量。与 `rangeEndStock` 不一定相等——后者是查询区间结束瞬间的库存，前者是当前瞬间的库存。部分记录存在 1–4 的差值（区间后又发生了出入库） |

### 4.5 销量与销售金额

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `rangeSale` | int | `2` | 区间内销售数量汇总（售出多少"包/瓶/份"等）。与 `rangeOut` 绝对值大致一致（也可能有非销售出库如报损/调拨） |
| `rangeSaleMoney` | float | `16.0` | 区间内销售金额小计（按商品维度汇总），单位：元（人民币）。有销量时 `rangeSaleMoney / rangeSale ≈ sale_price`（门店商品档案中的销售单价） |

---

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

```json
{
  "siteGoodsId": 3089190204491141,
  "goodsName": "小合味道",
  "goodsUnit": "桶",
  "goodsCategoryId": 2791941988405125,
  "goodsCategorySecondId": 2793236829620037,
  "rangeStartStock": 0,
  "rangeEndStock": 22,
  "rangeIn": 24,
  "rangeOut": -2,
  "rangeInventory": 0,
  "rangeSale": 2,
  "rangeSaleMoney": 16.0,
  "currentStock": 22,
  "categoryName": "零食"
}
```

---

## 六、跨表关联

### 与门店商品档案（`store_goods_master`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `id` | 门店商品 ID，关联商品基础信息（售价、成本、状态等） |
| `goodsName` | `goods_name` | 商品名称一致 |
| `goodsUnit` | `unit` | 计量单位一致 |
| `goodsCategoryId` | `goods_category_id` | 一级分类 ID |
| `goodsCategorySecondId` | `goods_second_category_id` | 二级分类 ID |

> 门店商品档案是静态维表，库存汇总是按时间范围聚合的衍生事实表。

### 与库存变动明细（`goods_stock_movements`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `siteGoodsId` | 门店商品 ID |

> 结构关系：库存变动明细（明细表）→ 按 `siteGoodsId` + 时间范围聚合 → 库存汇总（本表）。`rangeIn`、`rangeOut`、`rangeInventory` 分别对应明细中不同 `stockType` 的 `changeNum` 汇总。

### 与门店销售记录（`store_goods_sales_records`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `site_goods_id` | 门店商品 ID |

> 销售记录是每一条销售明细，库存汇总是按商品维度在时间段内的汇总。`rangeSale` 对应销售记录按商品聚合的 `ledger_count` 之和，`rangeSaleMoney` 对应 `ledger_amount` 之和。

### 与商品分类树（`stock_goods_category_tree`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `goodsCategoryId` | `id`（一级节点） | 一级分类主键 |
| `goodsCategorySecondId` | `id`（二级节点） | 二级分类主键 |
| `categoryName` | `category_name`（一级节点） | 一级分类名称 |

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