# SN 单品库存链（轻量闭环）- 前端联调方案

## 涉及页面

- SN 码列表 / 单件在库查询页
- SN 单件详情页（在库 / 去向）
- 仓库入库、出库（登记 SN）操作页
- 物料主数据（SN 开关配置）

## 业务流程与数据带入

1. 物料主数据 -> SN 开关：物料若启用「序列号管理」（`isSerialManaged`），才允许该物料登记 SN 入库/出库。
2. 入库登记 SN：用户扫码/手工录入 `code`，选择物料、仓库/库区/库位，调用 `POST /mes/wm/sn/in-stock`；后端先建 IN 库存事务再更新 SN 为「在库」并落库位。`snCode` 写入库存流水（`mes_wm_transaction.sn_code`）。
3. 出库核销 SN：录入 SN 码与物料，调用 `POST /mes/wm/sn/out-stock`；后端以 SN 记录的库存位置建 OUT 事务，并把 SN 置「已出库」、清空库位。
4. 单件查询：按 `code` 调 `GET /mes/wm/sn/detail`，返回 SN 在库状态、当前位置，以及最近一笔库存流水的类型/数量/业务单据/时间，用于核对去向。

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /mes/wm/sn/in-stock | SN 登记入库 |
| POST | /mes/wm/sn/out-stock | SN 出库核销 |
| GET | /mes/wm/sn/detail?code= | SN 单件详情（在库状态 + 最近流水去向） |
| GET | /mes/wm/sn/in-stock-page | 单件在库分页查询（按状态/库位/物料/批次过滤） |

**请求参数（in-stock）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | SN 码 |
| itemId | Long | 是 | 物料编号（须启用序列号管理） |
| warehouseId | Long | 是 | 仓库 |
| locationId | Long | 是 | 库区 |
| areaId | Long | 是 | 库位 |
| batchCode | String | 否 | 批次号 |
| remark | String | 否 | 备注 |

**请求参数（out-stock）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | SN 码 |
| itemId | Long | 是 | 物料编号 |
| remark | String | 否 | 备注 |

**响应字段（detail）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| code / status | String/Integer | SN 码、状态（1 在库 / 2 已出库） |
| warehouseId/locationId/areaId | Long | 在库位置（已出库为空） |
| lastTransactionType / TypeName | Integer/String | 最近一笔流水方向（1 入库 / 2 出库） |
| lastQuantity / lastBizType / lastBizCode / lastTime | decimal/Integer/String/datetime | 最近流水数量、业务类型、业务单据编码、时间 |

**响应字段新增（物料相关 VO：MdmItemRespDTO / MdmItemSaveReqVO 等）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| isSerialManaged | Boolean | 是否序列号管理开关（create/read/update 均支持） |

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| SN 码 / 物料 / 批次 | 列表、详情 | 单件标识 |
| 在库状态 | 列表、详情 | 在库 / 已出库 |
| 在库库位 | 列表、详情 | 仓库/库区/库位 |
| 最近去向 | 详情 | 最近流水对应的业务单据码 + 时间 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 未启用序列号 | 物料未开 `isSerialManaged` 时登记 SN 报错 |
| 重复入库 | 已「在库」的 SN 再次入库报错，须先出库 |
| 出库前提 | 仅「在库」且位置非空可出库；SN 与物料不匹配 / 位置不符会报错 |
| 出入库流转 | in-stock 建 IN 事务、out-stock 建 OUT 事务，均走库存流水并更新库存台账 |
| 商品 SN 溯源 | 通过 `mes_wm_transaction.sn_code` 关联流水，可按 SN 追溯历史进出 |

## 注意事项

- SN 登记/核销是「轻量」能力：单据行不拆成 SN 明细，SN 独立管理在 `mes_wm_sn`。
- 出库位置取自 SN 记录的库存位置，前端无需重复提交库位。
- 物料 `isSerialManaged` 开关在 MDM 物料主数据维护，MES 读取同一 `mdm_item` 数据。