193 lines
7.3 KiB
Markdown
193 lines
7.3 KiB
Markdown
# 库存出入库流水 — 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）
|
||
|
||
```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/ 确认字段覆盖完整
|
||
-->
|