# 库存出入库流水 — 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`） |
| 响应数据路径 | `data.queryDeliveryRecordsList` |

---

## 二、请求

### 请求体（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` 一致，形成统一的操作员维度

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

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
-->
