177 lines
7.2 KiB
Markdown
177 lines
7.2 KiB
Markdown
# 库存汇总报表 — 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/ 确认字段覆盖完整
|
||
-->
|