# 设备台账创建自动建物料并入设备仓 - 前端联调方案

## 涉及页面

- MES 设备管理 → 设备台账：新增/编辑表单、列表
- MES 设备管理 → 设备台账：Excel 导入
- MDM 主数据 → 物料（可在“设备”分类下看到自动生成的设备物料）
- MES 仓储 → 库存查询 / 库存流水查询（查看设备仓数量与流水）

## 业务流程与数据带入

1. 新增设备（单条/Excel 导入）→ 后端在同一事务内自动完成：
   - 创建 MDM 物料（类型=设备、分类=设备、单位=台、编码=设备编码、名称=设备名称、规格=设备规格型号）
   - 同步创建 MES 物料（编码/名称/规格与 MDM 对齐，两套物料 id 相等）
   - 落设备台账并回写 `itemId`（设备详情/列表可查）
   - 生成一条库存流水并入设备仓（SYS-EQUIPMENT / SYS-EQUIP-LOC-01 / SYS-EQUIP-BIN-01），库存数量 +1
2. 编辑设备（单条/Excel 更新）→ 只改设备台账，不重复建物料、不重复入库，`itemId` 保持不变
3. 删除设备 → 已生成物料并入设备仓的设备禁止删除（需先通过库存调整处理库存）

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /mes/dv-machinery/create | 新增设备（自动建物料并入库） |
| PUT | /mes/dv-machinery/update | 编辑设备（不重复建物料/入库） |
| DELETE | /mes/dv-machinery/delete?id= | 删除设备（已入设备仓则拦截） |
| POST | /mes/dv-machinery/import | Excel 导入（创建行同样建物料并入库） |
| GET | /mes/dv-machinery/page | 设备分页列表 |
| GET | /mes/dv-machinery/get?id= | 设备详情 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | 设备编码（将作为对应物料的物料编码） |
| name | String | 是 | 设备名称（将作为对应物料的物料名称） |
| specification | String | 否 | 规格型号（同步到物料规格） |
| machineryTypeId | Long | 是 | 设备类型 |
| workshopId | Long | 是 | 所属车间 |
| status | Integer | 是 | 设备状态 |

新增/导入时前端**无需传 `itemId`**（系统自动生成并回写）。

**响应字段新增（`get` / `page` / `simple-list` 返回的 RespVO 中）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| itemId | Long | 该设备对应的物料编号（=MDM 物料 id，同时等于 MES 物料 id） |

**关于创建响应：** `POST /create` 返回体 `data` 仍为 `Long`（新建设备 id），不直接携带 `itemId`。前端保存成功后若需立即展示对应物料编号，可再调用 `GET /get?id=<新id>` 取 `data.itemId`；`/page`、`/simple-list` 列表行也会返回该字段。

**详情响应示例：**

```json
{
  "code": 0,
  "data": { "id": 1024, "code": "EQ-001", "itemId": 100001 }
}
```

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 对应物料编号(itemId) | 设备列表、详情 | 后端自动生成；可用于跳转 MDM 物料详情或按物料查库存 |
| 设备仓库存 | 库存查询页（仓库=设备仓） | 新建设备自动入设备仓，数量为 1 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 新增设备 | 同一事务：建 MDM 物料 → 同步 MES 物料 → 落台账 → 入设备仓（+1）。任一步失败整体回滚，不留脏数据 |
| 编辑设备 | 不重建物料、不入库；`itemId` 只读不回传 |
| 删除设备 | `itemId` 非空的设备禁止删除（防止库存流水失去业务主体），需先做库存调整 |
| Excel 导入 | 创建行与单条新增走同一套“建物料 + 入设备仓”逻辑；编码冲突行报错不落库 |
| 缺主数据 | 若“设备”分类/“台”单位或设备仓未初始化，新增/导入报“主数据未初始化”，提示联系管理员 |

## 注意事项

- 设备编码即物料编码，请保持设备编码在物料维度也唯一（系统对物料编码做唯一校验，冲突会导致新增失败）。
- 列表/详情接口返回的 `itemId` 可在“库存/流水”查询中作为筛选条件查看该设备在设备仓的库存与流水。
- 若需在 MDM 物料页按分类筛选查看设备物料，选中“设备”分类即可。
- 数据库需先执行初始化脚本 `docs/sql/equipment_material_stock_link.sql`（新增 `mes_dv_machinery.item_id`、“设备”分类/类型、“台”单位），否则新建设备会提示主数据未初始化。