> **前置条件** — 执行前请先确认已完成认证（参见 [`../../shb-shared/SKILL.md`](../../shb-shared/SKILL.md)）。输出措辞禁令、id 复用规则、传参优先级见本 skill 的 [`SKILL.md`](../SKILL.md)。

# 物料域公共变更规范（全部写操作的强制前置）

本文档是云仓物料域**所有跨命令变更规则的唯一出处**，执行任何写操作（`material create` / `material update` / `material update batch` / `material update status` / `material delete`）前必须已加载本文档，再加载对应操作的专属文档（[`create`](shb-warehouse-material-create.md) / [`update`](shb-warehouse-material-update.md) / [`delete`](shb-warehouse-material-delete.md)）。

## 变更操作安全规则

**CRITICAL** — 写命令按风险分两档，动手前先判断落在哪一档：

| 档位 | 命令 | 需要 `--yes`/`--dry-run` |
|---|---|---|
| 低风险 | `material create` / `material update` / `material update status` | 否 |
| 高风险（全有全无 / 批量覆盖） | `material delete` / `material update batch` | **是** |

1. **`material delete` / `material update batch` 必须传 `--yes`**（或 `--dry-run` 仅预览、不真正发起请求），否则命令直接拒绝执行——这两个操作影响面大（`delete` 是全批次全有全无的软删除，`update batch` 是把同一个值写到多个物料）。`--yes`/`--dry-run` 不要代用户自动加上，除非用户已明确表达了执行意图。
2. **`material update` 必须 fetch-then-merge，禁止手写不完整的 `--data`**：后端 `/update` 接口对系统字段是**全量替换**语义——凡是这次请求 `formValueList` 里没带的当前可见系统字段都会被清空（仅 4 个币种字段例外），自定义字段则是安全的增量更新（没提到的不受影响）。用快捷 flag 时命令会自动先查当前完整字段状态再叠加改动，安全；但如果用户坚持用 `--data`/`--file` 自己构造请求体，必须提醒其先拿到当前完整字段值再在此基础上只改要改的字段，否则会静默丢数据（操作步骤见 [`shb-warehouse-material-update.md`](shb-warehouse-material-update.md)）。
3. **`material update batch` 禁止批量改 `sn`**：后端对批量改 `sn` 没有查重，会导致物料编号重复；命令对多 id 场景下改 `sn` 会硬性拒绝，不接受 `--yes` 绕过；单 id 场景不受影响（等价于单条更新）。
4. **`material create` 前先确认该租户有哪些物料字段、哪些必填**：`isNull=0` 的字段（系统字段或租户自定义字段都算）必须有值，没有值时向用户询问，不要凭空编造或直接漏传。字段定义的查询方法与「读字段/判断必填都是后台内部步骤、缺值直接用中文向用户要」的完整措辞规范见 [`shb-warehouse-material-field.md`](shb-warehouse-material-field.md)。
5. 变更操作失败时如实告知用户失败原因（整理成可读信息），不要谎称成功、不要盲目重试。

## 写操作通用注意

- 所有变更命令默认输出未格式化的原始响应（已解包信封）；`create`/`update` 支持 `--format-data` 在成功后立即按查询格式展示最新状态，便于确认改动生效。
- `update`/`update batch`/`update status`/`delete` 操作前，如果不确定目标物料范围，先用 `material search` 或 `material detail` 确认一遍，不要凭用户口头描述直接批量操作。
- **失败后不要用"多改几个字段试试"的方式探索重试**：每次调用都是一次真实的写请求，不是沙盒。失败时先看报错信息定位到具体是哪个字段/哪个值被拒绝（格式错误、超出范围、唯一性冲突等），只针对报错涉及的字段调整后重新提交一次；报错信息看不出具体原因时，问用户确认该字段的取值，不要连续多次改动多个字段"看看哪次能通过"。
- 变更请求失败时，报错信息通常已包含具体原因（必填字段缺失、`--yes` 未传、`sn` 重复、库存/BOM 阻塞等），整理成人话讲给用户，不要笼统说"失败了"；也不要在没有新信息的情况下重复重试同一个失败请求。
- `material update batch`/`material delete` 提交前，如果用户没有明确说"确认执行"，先复述一遍将要影响的 id 范围和字段/操作，等用户确认意图后再加 `--yes` 执行——这两个操作没有回滚入口。

## 命令速查表

| 命令 | 必填 flag | 是否需要 `--yes` |
|---|---|---|
| `material create` | 至少一个字段 flag 或 `--custom-fields`（或 `--data`/`--file`） | 否 |
| `material update` | `--id` | 否（内部自动 fetch-then-merge） |
| `material update batch` | `--ids` `--field` `--value`/`--value-json`（或 `--data`/`--file`） | **是** |
| `material update status` | `--ids` `--status` | 否 |
| `material delete` | `--ids` | **是** |
| `material field check` | `--field-name` `--field-value` | 否（只读预检，见 [`field`](shb-warehouse-material-field.md)） |