# 库存现有量自定义出入库 - 前端联调方案

## 涉及页面

- 库存现有量列表页
- 库存调整弹窗/对话框

## 业务场景

库存现有量模块新增自定义出入库功能，用于：
- 库存盘点调整
- 库存损耗/报溢
- 手动入库/出库
- 其他非业务单据驱动的库存变动

## 新增 API

### 自定义入库

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /mes/wm/material-stock/adjust-in | 自定义入库 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| itemId | Long | 是 | 物料ID |
| warehouseId | Long | 是 | 仓库ID |
| locationId | Long | 是 | 库区ID |
| areaId | Long | 是 | 库位ID |
| batchId | Long | 否 | 批次ID（选择已有批次时传入） |
| batchCode | String | 否 | 批次号（新建批次时传入） |
| produceDate | DateTime | 否 | 生产日期（新建批次时传入） |
| expireDate | DateTime | 否 | 有效期（新建批次时传入） |
| vendorId | Long | 否 | 供应商ID |
| quantity | BigDecimal | 是 | 入库数量（必须大于0） |
| reason | String | 否 | 入库原因 |

**响应：**

```json
{
  "code": 0,
  "data": 123,  // 库存记录ID
  "msg": "操作成功"
}
```

### 自定义出库

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /mes/wm/material-stock/adjust-out | 自定义出库 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| itemId | Long | 是 | 物料ID |
| warehouseId | Long | 是 | 仓库ID |
| locationId | Long | 是 | 库区ID |
| areaId | Long | 是 | 库位ID |
| batchId | Long | 否 | 批次ID（出库时校验批次存在） |
| batchCode | String | 否 | 批次号 |
| vendorId | Long | 否 | 供应商ID |
| quantity | BigDecimal | 是 | 出库数量（必须大于0） |
| reason | String | 否 | 出库原因 |

**响应：**

```json
{
  "code": 0,
  "data": 123,  // 库存记录ID
  "msg": "操作成功"
}
```

## 前端修改点

### 1. 库存现有量列表页

在列表页工具栏添加"库存调整"按钮：

**按钮逻辑：**
1. 点击打开库存调整弹窗
2. 弹窗内填写调整信息

### 2. 库存调整弹窗

**操作类型选择：**
- 用户首先选择操作类型：入库 / 出库
- 根据操作类型调用不同的 API

**表单字段：**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 物料 | 选择器 | 是 | 弹出物料选择对话框 |
| 仓库 | 选择器 | 是 | 下拉选择仓库 |
| 库区 | 选择器 | 是 | 根据仓库联动加载库区 |
| 库位 | 选择器 | 是 | 根据库区联动加载库位 |
| 批次 | 选择器 | 否 | 弹出批次选择对话框（如果物料启用批次管理） |
| 供应商 | 选择器 | 否 | 下拉选择供应商 |
| 入库数量/出库数量 | 数字输入 | 是 | 必须大于0 |
| 入库原因/出库原因 | 文本输入 | 否 | 填写原因 |

**联动逻辑：**

1. 选择仓库后，加载该仓库下的库区列表
2. 选择库区后，加载该库区下的库位列表
3. 选择物料后：
   - 如果物料启用批次管理（batchCode=true），批次字段显示并必填
   - 如果物料未启用批次管理，批次字段隐藏

**提交逻辑：**

1. 校验必填字段
2. 根据操作类型调用不同 API：
   - 入库：`/mes/wm/material-stock/adjust-in`
   - 出库：`/mes/wm/material-stock/adjust-out`
3. 成功后提示"入库成功"/"出库成功"，刷新列表页
4. 失败时显示错误信息

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 入库 | 自动创建库存记录（如果不存在），增加库存数量 |
| 出库 | 校验库存记录存在且数量充足，扣减库存数量 |
| 批次管理 | 物料启用批次管理时，必须选择批次 |
| 库位混放 | 根据库位配置的混放规则校验 |

## 库存事务流水

调整操作会自动生成库存事务流水：

| 字段 | 入库 | 出库 |
|------|------|------|
| type | IN (入库) | OUT (出库) |
| bizType | WM_STOCK_ADJUST_IN (126) | WM_STOCK_ADJUST_OUT (127) |
| bizId | 库存记录ID | 库存记录ID |
| bizCode | STOCK_ADJUST_{库存ID} | STOCK_ADJUST_{库存ID} |

## 批次处理规则

自定义入库时，系统会根据物料批次配置自动处理批次：

> **批次配置来源**：基础数据（MDM）物料主数据的批次属性配置，在物料详情页维护。

### 入库批次处理逻辑

| 情况 | 处理方式 |
|------|---------|
| 物料未启用批次管理 | 不关联批次 |
| 传入 batchId | 校验批次存在且归属正确，使用已有批次 |
| 未传 batchId（物料启用批次管理） | 根据参数自动创建批次记录 |

### 新建批次时的参数

当物料启用批次管理且未传入 batchId 时，可传入以下参数用于创建批次：

| 参数 | 说明 |
|------|------|
| batchCode | 批次号（可选，不传则系统自动生成） |
| produceDate | 生产日期 |
| expireDate | 有效期 |
| vendorId | 供应商ID |

> 系统会根据物料的批次配置校验必填参数（如生产日期、有效期等）

### 出库批次处理逻辑

| 情况 | 处理方式 |
|------|---------|
| 物料未启用批次管理 | 不校验批次 |
| 传入 batchId | 校验批次存在且与物料匹配 |

## 注意事项

- 入库数量/出库数量必须大于0
- 出库时必须保证库存充足
- 入库和出库操作会分别记录库存事务流水，便于追溯
- 建议在原因中填写详细说明，便于后续查询和审计