root/ZQYY.FQ-ETL

Fork 0

Files

Neo 3c51f5485d 初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00

7.2 KiB

Raw Blame History

库存汇总报表 — 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）

{
  "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`（门店商品档案中的销售单价）

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

{
  "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`（一级节点）	一级分类名称

7.2 KiB Raw Blame History Unescape Escape