# 生产退料 - 前端联调方案

## 问题背景

退料明细（detail）的 `warehouseId`/`locationId`/`areaId` 语义变更：
- **变更前**：来源仓库（从库存记录带入，即虚拟线边库）
- **变更后**：上架目标仓库（退料要放回的实际仓库）

前端传虚拟线边库信息 → 后端入库也入虚拟库 → 实际仓库库存没恢复。

## 涉及页面

- 生产退料单 - 明细新增/编辑弹窗
- 生产退料单 - 上架操作页面

## 核心变更

### 退料明细的仓库字段语义

| 字段 | 变更前语义 | 变更后语义 | 说明 |
|------|-----------|-----------|------|
| `materialStockId` | 虚拟线边库库存记录 ID | 不变 | 用于从虚拟线边库出库 |
| `warehouseId` | 来源仓库（虚拟库） | **上架目标仓库（实际仓库）** | 退料入库的目标仓库 |
| `locationId` | 来源库区 | **上架目标库区** | 退料入库的目标库区 |
| `areaId` | 来源库位 | **上架目标库位** | 退料入库的目标库位 |

### 后端已做的兼容

后端 `createTransactionList` 已做兜底：
- 如果 detail 的 `warehouseId` 仍是虚拟线边库（旧数据/前端未改），会自动通过事务流水反查原始仓库
- 前端改完后，直接使用 detail 的仓库信息作为入库目标，不再走反查

## 前端修改点

### 1. 明细新增/编辑弹窗 - 仓库选择逻辑

**当前逻辑**：选择虚拟线边库库存记录后，自动带入该库存记录的 warehouseId/locationId/areaId（虚拟库）

**改为**：
- `materialStockId`：仍从虚拟线边库库存记录获取（用于标识从哪个库存出）
- `warehouseId`/`locationId`/`areaId`：**改为让用户选择上架目标库位**（实际仓库的库位），不再自动从库存记录带入

#### 选择库存记录时

```
选择库存记录 → 自动带入：itemId, batchId, batchCode, materialStockId
                不再带入：warehouseId, locationId, areaId
```

#### 上架目标库位选择

新增一个库位选择器，让用户选择退料要放回的实际仓库库位：
- 仓库下拉：过滤掉虚拟线边仓库（code = `WIP_VIRTUAL_WAREHOUSE`）
- 库区下拉：联动仓库
- 库位下拉：联动库区

### 2. 数据带入说明

| 场景 | 从哪带入 | 字段 |
|------|---------|------|
| 选择库存记录 | 虚拟线边库库存 | materialStockId, itemId, batchId, batchCode |
| 选择上架库位 | 用户手动选择 | warehouseId, locationId, areaId |
| 默认上架库位 | 领料出库时的原始仓库 | warehouseId, locationId, areaId |

**建议**：选择库存记录后，自动查询该物料的领料出库记录，将原始出库仓库作为默认上架目标库位，用户可修改。

### 3. API 说明

保存明细的接口不变：

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /mes/wm-return-issue-detail/create | 新增明细 |
| PUT | /mes/wm-return-issue-detail/update | 修改明细 |

**请求参数（同之前，但语义变更）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| materialStockId | Long | 否 | 虚拟线边库库存记录 ID（来源） |
| warehouseId | Long | 是 | **上架目标仓库 ID**（不再是来源仓库） |
| locationId | Long | 是 | **上架目标库区 ID** |
| areaId | Long | 是 | **上架目标库位 ID** |

### 4. 后端校验变更

后端校验已调整：
- ✅ 校验 `materialStockId` 对应的库存记录存在、物料一致、库存充足
- ❌ 不再校验 `materialStockId` 的仓库与 `warehouseId` 一致（因为来源是虚拟库，目标是实际库）
- ✅ 校验上架目标库位的混放规则

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 退料出库 | 从虚拟线边库扣减（checkFlag=false，允许负库存） |
| 退料入库 | 入到用户选择的实际仓库库位 |
| 默认上架库位 | 建议默认填入领料出库时的原始仓库库位 |
| 仓库过滤 | 上架目标仓库下拉应排除虚拟线边仓库 |

## 注意事项

- 后端已做兼容：如果前端暂时不改，旧数据（warehouseId=虚拟库）仍能通过事务流水反查原始仓库，不会报错
- 前端改完后，新的退料单 detail 应传实际仓库的库位，逻辑更清晰
- 已存在的旧退料数据不受影响（反查兜底）