root/ZQYY.FQ-ETL

Fork 0

Files

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

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

7.3 KiB

Raw Permalink Blame History

库存出入库流水 — QueryGoodsOutboundReceipt

模块：GoodsStockManage · ODS 表：goods_stock_movements · 事实表（增量）

一、接口概述

查询门店商品库存出入库流水明细，每条记录对应一次库存变动事件（销售出库、采购入库、盘点调整等）。包含变动前后库存数量、变动类型、操作员等信息。所有记录严格满足库存平衡公式：endNum = startNum + changeNum。支持双计量单位（主/副单位），当前门店仅使用主单位。

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

二、请求

请求体（JSON）

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

参数说明

参数	类型	必填	说明
`siteId`	int	是	门店 ID
`stockType`	int	是	库存变动类型筛选。`0` = 全部，`1` = 出库，`4` = 入库
`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": 100
  }
}

data.list 中每个对象即为一条库存变动记录，共 19 个字段，按逻辑分组说明如下。

四、响应字段详解（19 个字段）

4.1 商品与库存标识

字段	类型	示例	说明
`siteGoodsStockId`	int	`2957911857581957`	库存记录主键 ID，每条变动记录唯一。同一商品可在不同批次/仓位产生多条记录
`siteGoodsId`	int	`2793026183532613`	门店商品 ID。对应门店商品档案（`store_goods_master`）的 `id`，也对应库存汇总的 `siteGoodsId`
`siteId`	int	`2790685415443269`	门店 ID，与其他业务表一致
`tenantId`	int	`2790683160709957`	租户/品牌 ID，所有记录相同
`goodsCategoryId`	int	`2790683528350539`	一级分类 ID，对应分类树主键。约 5 个不同值
`goodsSecondCategoryId`	int	`2790683528350540`	二级分类 ID，对应分类树子节点。约 7 个不同值

4.2 商品基本信息

字段	类型	示例	说明
`goodsName`	string	`"阿萨姆"`	商品名称（当时的名称快照），与 `siteGoodsId` 一一对应
`unit`	string	`"瓶"`	库存计量单位。常见值：瓶、包、盒、根、个、桶、份
`price`	float	`8.0`	商品单价（静态快照），单位：元（人民币）。同一 `siteGoodsId` 的所有记录 `price` 一致，避免价格调整后历史记录无法还原

4.3 库存数量变动（主单位）

字段	类型	示例	说明
`startNum`	int	`28`	变动前库存数量
`endNum`	int	`27`	变动后库存数量。严格满足 `endNum = startNum + changeNum`
`changeNum`	int	`-1`	本次变化量。负数 = 出库/减少，正数 = 入库/增加。`stockType=1` 时全为负数，`stockType=4` 时全为正数

4.4 库存数量变动（副单位，预留）

字段	类型	示例	说明
`startNumA`	int	`0`	副单位变动前库存（如箱/瓶双单位场景）。当前门店未启用，全部为 0
`endNumA`	int	`0`	副单位变动后库存，当前全部为 0
`changeNumA`	int	`0`	副单位变化量，当前全部为 0

4.5 变动类型

字段	类型	示例	说明
`stockType`	int	`1`	库存变动类型枚举：`1` = 出库（销售出库，`changeNum` 为负数），`4` = 入库/盘盈/调整增加（`changeNum` 为正数）。其他可能值（如报损、盘亏、退货等）当前样本未出现

4.6 操作与时间

字段	类型	示例	说明
`createTime`	string	`"2025-11-09 23:23:34"`	库存变动记录创建时间。可与小票时间、台费时间交叉校验。同一秒内可能有多条记录（同桌多商品一起销售）
`operatorName`	string	`"收银员:郑丽珊"`	操作人。大部分为收银员（前台销售触发），个别为"系统"（自动盘点调整等）

4.7 备注

字段	类型	示例	说明
`remark`	string	`""`	备注信息，用于手工记录变更原因（如"盘点差异调整""报损"）。当前全部为空

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

{
  "siteGoodsStockId": 2957911857581957,
  "siteGoodsId": 2793026183532613,
  "siteId": 2790685415443269,
  "tenantId": 2790683160709957,
  "stockType": 1,
  "goodsName": "阿萨姆",
  "createTime": "2025-11-09 23:23:34",
  "startNum": 28,
  "endNum": 27,
  "changeNum": -1,
  "unit": "瓶",
  "price": 8.0,
  "operatorName": "收银员:郑丽珊",
  "changeNumA": 0,
  "startNumA": 0,
  "endNumA": 0,
  "remark": "",
  "goodsCategoryId": 2790683528350539,
  "goodsSecondCategoryId": 2790683528350540
}

六、跨表关联

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

本表字段	关联表字段	说明
`siteGoodsId`	`id`	门店商品 ID，关联商品基础信息、定价、库存快照
`goodsCategoryId`	`goods_category_id`	一级分类 ID
`goodsSecondCategoryId`	`goods_second_category_id`	二级分类 ID

与库存汇总（`goods_stock_summary`）

本表字段	关联表字段	说明
`siteGoodsId`	`siteGoodsId`	门店商品 ID。库存变动明细按 `siteGoodsId` + 时间范围聚合后即为库存汇总

结构关系：库存变动（明细表）→ 按 siteGoodsId + 时间范围聚合 → 库存汇总（汇总表）。

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

当 stockType = 1（出库）时，对应销售记录中的商品销售行为
通过 siteGoodsId / site_goods_id 和 createTime / create_time 可在结构上对齐

与商品分类树（`stock_goods_category_tree`）

本表字段	关联表字段	说明
`goodsCategoryId`	`id`（一级节点）	一级分类主键
`goodsSecondCategoryId`	`id`（二级节点）	二级分类主键

与操作员维度

operatorName 与其他流水（台费、助教、销售记录）中的 operator_name 一致，形成统一的操作员维度

7.3 KiB Raw Permalink Blame History Unescape Escape