# 库存出入库流水 — QueryGoodsOutboundReceipt > 模块：`GoodsStockManage` · ODS 表：`goods_stock_movements` · 事实表（增量） --- ## 一、接口概述 查询门店商品库存出入库流水明细，每条记录对应一次库存变动事件（销售出库、采购入库、盘点调整等）。包含变动前后库存数量、变动类型、操作员等信息。所有记录严格满足库存平衡公式：`endNum = startNum + changeNum`。支持双计量单位（主/副单位），当前门店仅使用主单位。 | 属性 | 值 | |------|-----| | 完整路径 | `POST /GoodsStockManage/QueryGoodsOutboundReceipt` | | Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` | | 鉴权 | `Authorization: Bearer ` | | 分页 | `page` + `limit`（最大 100） | | 时间范围 | 需要（`startTime` / `endTime`） | --- ## 二、请求 ### 请求体（JSON） ```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 | `""` | 备注信息，用于手工记录变更原因（如"盘点差异调整""报损"）。当前全部为空 | --- ## 五、响应样例（单条记录） ```json { "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` 一致，形成统一的操作员维度