# 设备入库单 - 前端联调方案

## 涉及页面

- 设备入库单列表（页面路径与路由待前端补充）
- 设备入库单详情 / 编辑（主单信息 + 明细行）

## 业务流程与数据带入

1. 设备台账 -> 设备入库单明细行：从「设备台账」页选择设备后，`machineryId`、`itemId`（设备物料编号）自动带入并传入 `POST /mes/wm/equipment-receipt-line/create`；物料编码/名称/规格/单位由后端按 `itemId` 实时拼接返回。
2. 设备入库单创建 -> 编号：`code` 在前端编辑页可调用自动编码规则（`WM_EQUIP_RECEIPT_CODE`）生成，传给 `POST /mes/wm/equipment-receipt/create`。
3. 审批流程：主管单提交审批后，走 BPM，审批通过后由「执行入库」把明细行按固定「设备仓三元组」（`SYS-EQUIPMENT` / `SYS-EQUIP-LOC-01` / `SYS-EQUIP-BIN-01`）入设备仓、数量默认 1。

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /mes/wm/equipment-receipt/create | 创建设备入库单（草稿） |
| PUT | /mes/wm/equipment-receipt/update | 修改设备入库单（仅草稿） |
| DELETE | /mes/wm/equipment-receipt/delete | 删除设备入库单（仅草稿，级联删行） |
| GET | /mes/wm/equipment-receipt/get?id= | 获得设备入库单详情 |
| GET | /mes/wm/equipment-receipt/page | 设备入库单分页 |
| PUT | /mes/wm/equipment-receipt/submit-approval?id=&processDefinitionKey= | 提交 BPM 审批（草稿→审批中） |
| GET | /mes/wm/equipment-receipt/approval-process-list | 获得设备入库可选流程定义列表 |
| PUT | /mes/wm/equipment-receipt/finish?id= | 执行入库（已审批→已完成，逐行入设备仓） |
| PUT | /mes/wm/equipment-receipt/cancel?id= | 取消设备入库单 |
| POST | /mes/wm/equipment-receipt-line/create | 新增明细行 |
| PUT | /mes/wm/equipment-receipt-line/update | 修改明细行 |
| DELETE | /mes/wm/equipment-receipt-line/delete?id= | 删除明细行 |
| GET | /mes/wm/equipment-receipt-line/get?id= | 获得明细行 |
| GET | /mes/wm/equipment-receipt-line/list-by-receipt-id?receiptId= | 按主单获得明细行列表 |
| GET | /mes/wm/equipment-receipt-line/page | 明细行分页 |

**请求参数（create/update）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | 单据编码（可自动编码生成） |
| name | String | 否 | 单据名称 |
| receiptDate | datetime | 是 | 入库日期 |
| source | String | 否 | 入库来源 |
| remark | String | 否 | 备注 |

**请求参数（明细行 create/update）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| receiptId | Long | 是 | 入库单编号 |
| machineryId | Long | 是 | 设备台账编号 |
| itemId | Long | 是 | 设备物料编号（从设备台账带入） |
| quantity | decimal | 是 | 入库数量（默认 1，可同单多台） |
| remark | String | 否 | 备注 |

**响应字段新增（主单）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| processInstanceId | String | BPM 流程实例编号，非空表示已提交审批 |

**响应字段（明细行）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| machineryId / machineryCode / machineryName | Long/String | 设备台账信息 |
| itemId / itemCode / itemName / specification / unitMeasureName | Long/String | 物料及单位信息 |

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 单据编码/名称/入库日期/来源 | 列表、详情 | 主单基础信息 |
| 状态 | 列表、详情 | 0 草稿 / 2 审批中 / 3 已审批 / 4 已完成 / 5 已取消 |
| processInstanceId | 详情 | 有值时前端展示「查看审批流程实例」入口 |
| 明细行表格 | 详情、编辑 | 展示设备、物料、数量、单位 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 明细行新增 | 必须选择已关联物料（itemId 非空）的设备，否则报「所选设备未关联物料」 |
| 数量 | 必须 > 0，默认 1 |
| 编辑 | 仅草稿状态下可增删改主单与明细行 |
| 提交审批 | 至少有一条明细行；提交后进入审批中，不可再编辑 |
| 审批结果 | 通过→已审批；驳回→回草稿可改重提；取消→已取消 |
| 执行入库 | 仅已审批可执行；逐行为每台设备在设备仓 +1 库存并写库存流水；完成后不可重复执行 |
| 库存生效 | 审批通过不立即扣库存，仅「执行入库」才入设备仓 |

## 注意事项

- 明细行末端固定入「设备仓三元组」，前端无需提交仓库/库区/库位字段。
- 库存数量变化通过既有库存/库存流水查询接口查看，本单据不复制库存数据。
- BPM 流程定义需在后台以分类 `equipment_receipt_approve` 手工部署后，`approval-process-list` 才会返回可用流程。