# 错误提示文案精确性规则

## 规则

- 面向用户的校验/异常提示（后端异常 message、Excel 导入校验提示、前端 toast、接口报错文案），**禁止写成把多个条件堆在一个笼统句里**，例如：`库存记录与提交的物料、批次或库位信息不一致`、`数据不合法`、`参数错误`、`记录不一致`。
- 用户看到提示后应能**一眼知道是哪个条件不满足、差在哪、怎么改**，而不是只知道"出错了"。

## 多条件校验提示要求

提示必须同时包含三要素：

1. **具体维度**：指出是哪一个字段/规则不满足（如：物料、批次、批次号、仓库、库区、库位、数量）。
2. **双方实际值**：给出"库存/单据侧"与"提交值"两侧的可读值对比，并尽量解析成业务名称（如 `成品仓/2区/A-01`），**不要直接暴露纯数字 ID**；名称解析失败时才回退 `ID=xxx` 并明确标注。
3. **可执行动作**：告诉用户接下来怎么办（重新选择哪一项、如何刷新重试、删除后重新添加、退回哪一步、联系谁）。

### 写法示例

```java
// ❌ 笼统、多条件堆叠、无法定位
throw exception(WM_MATERIAL_STOCK_SELECTION_MISMATCH);

// ❌ 只给条件不给值、不给动作、暴露生硬 ID
throw new ServiceException(WM_MATERIAL_STOCK_SELECTION_MISMATCH.getCode(),
    "不一致：库位(库存 8 ≠ 提交 null)");

// ✅ 维度 + 两侧可读值 + 动作
throw new ServiceException(WM_MATERIAL_STOCK_SELECTION_MISMATCH.getCode(),
    "所选库存记录与单据不一致：所选库存库位[A-01]，单据库位为[未选择]。"
        + "请重新选择该物料正确的库存；若仓库/库区/库位/批次被禁用无法修改，请删除本条明细后重新添加。");
```

## 实现要点

- 逐维度独立比较（`itemId → batchId → batchCode → warehouseId → locationId → areaId`），**按业务优先级只返回/抛出第一处不满足**，避免一次抛多条让用户抓不住重点。
- 同一错误码但业务上下文不同（如"执行扣减时库存已被移库/合并/拆分" vs "新增明细时带错字段" vs "退货来源库存物料不符"），**各自给出贴合场景的专属文案**，不要都复用同一句笼统话。
- 名称解析放在**异常分支**再执行（罕见路径），避免每次正常保存都多查表；解析失败必须回退为可读的 `ID=xxx` 而非抛二次异常。
- 如果某个字段本应由系统自动带出（如选库存后回填的仓库/库区/库位/批次），一旦不一致基本等于前端回填缺失或数据被改，提示里要写明"请重新选择以自动带出"。

## 自查清单

新增或修改任何可能由多个原因触发的提示前，逐项确认：

- [ ] 提示是否指明了"具体是哪个条件"？
- [ ] 是否同时给出了"期望值 vs 实际值"（尽量用业务名称而非 ID）？
- [ ] 是否给出了"用户下一步能做的动作"？
- [ ] 是否避免了把多个条件堆进一句"XX不一致"？