# 库存可用量管理 - 前端联调方案

## 涉及页面

- 库存现有量页面

## 业务流程与数据带入

本次为库存台账字段扩展，无跨页面数据流转。

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/wm/material-stock/page | 库存台账分页查询 |
| GET | /mes/wm/material-stock/get | 单条库存查询 |

**响应字段新增：**

| 字段 | 类型 | 说明 |
|------|------|------|
| frozenQuantity | Decimal | 冻结数量 |
| reservedQuantity | Decimal | 占用量（已分配待出库） |
| inTransitQuantity | Decimal | 在途量（调拨在途） |
| availableQuantity | Decimal | 可用量（后端计算：在库数量 - 冻结数量 - 占用量） |

**响应示例：**

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "itemCode": "M001",
        "itemName": "钢板",
        "quantity": 100.00,
        "frozenQuantity": 10.00,
        "reservedQuantity": 20.00,
        "inTransitQuantity": 5.00,
        "availableQuantity": 70.00
      }
    ],
    "total": 1
  }
}
```

## 前端实现要点

### 1. 数据获取时机

- 页面打开时调用库存台账查询接口，响应中已包含新增字段
- 无需额外接口调用

### 2. 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 在库数量 | 列表、详情 | 现有字段，保持不变 |
| 冻结数量 | 列表、详情 | 新增字段，可能为 null 时显示 0 |
| 占用量 | 列表、详情 | 新增字段，可能为 null 时显示 0 |
| 在途量 | 列表、详情 | 新增字段，可能为 null 时显示 0 |
| 可用量 | 列表、详情 | 后端已计算，直接展示；为负数时建议高亮提示 |

### 3. 用户可编辑字段

无新增可编辑字段，本次仅为展示类字段扩展。

## 业务规则说明

### 1. 各字段含义

| 字段 | 含义 |
|------|------|
| 在库数量 | 仓库中实际存在的库存 |
| 冻结数量 | 因盘点、质检等原因被冻结的库存 |
| 占用量 | 已分配待出库的数量（拣货后未出库） |
| 在途量 | 调拨在途（源仓库已出库，目标仓库未入库） |
| 可用量 | 实际可用于分配的库存 |

### 2. 占用量产生与释放场景

| 场景 | 时机 | 影响 |
|------|------|------|
| 销售出库拣货 | 拣货操作时 | 占用量增加，可用量减少 |
| 生产领料拣货 | 拣货操作时 | 占用量增加，可用量减少 |
| 出库完成 | 执行出库时 | 占用量减少，在库数量减少 |
| 单据取消 | 取消出库单时 | 占用量释放，可用量恢复 |

## 注意事项

- 新增字段在历史数据中可能为 null，前端展示时需做空值处理，默认显示 0
- 可用量由后端计算，前端直接使用，无需自行计算
- 导出 Excel 已包含新字段，无需额外处理