> **先读** [`shb-warehouse-material-mutation-common.md`](shb-warehouse-material-mutation-common.md)（本域全部变更安全规则的唯一出处，含 fetch-then-merge 与全量替换语义、批量改 `sn` 禁令）与 [`shb-warehouse-material-field.md`](shb-warehouse-material-field.md)（可改字段范围与转述规范）。

# shb-cli warehouse material update（编辑物料：单条/批量/启停用）

覆盖 `material update`（单条编辑）、`material update batch`（批量同值编辑）、`material update status`（批量启停用）。

## 单条编辑（`material update`）

**可修改哪些字段以 `material field list` 的查询结果为准**（查询方法与回答用户时的措辞规范见 [`shb-warehouse-material-field.md`](shb-warehouse-material-field.md)）。

快捷 flag 模式**自动 fetch-then-merge**（原因见 mutation-common 安全规则第 2 条）：命令先查该物料当前完整字段状态（`material field list` + `material detail`），把所有当前可见字段值原样带上，再叠加本次改动一起提交——这个过程对你透明，正常使用快捷 flag 即可，不用担心清空问题：

```bash
# 只改一个字段，其余字段自动保持不变
shb-cli warehouse material update --id <id> --property 耗材

# 改多个字段
shb-cli warehouse material update --id <id> --sale-price 18.00 --cost-price 10.00

# 改产品目录关联（不传此 flag 则目录关系不受影响；传空字符串会清空所有关联）
shb-cli warehouse material update --id <id> --property 耗材 --product-catalog-ids 101,102
```

**`--data`/`--file` 模式不会自动 fetch-then-merge**——如果确实需要用这种方式（比如要改高级字段），必须先手动查一次当前完整字段状态再构造请求体：

```bash
# 1. 先查当前完整字段值
shb-cli warehouse material detail --id <id> -o json

# 2. 基于查到的完整字段值构造 formValueList，只改要改的字段，再提交
shb-cli warehouse material update --data '{"id":<id>,"formValueList":[...当前完整字段...]}'
```

**绝不要**只传本次想改的一两个字段就调用 `--data`，那会把其余系统字段清空——这是本域最容易踩的坑。

**失败重试**：`material update`（单条）不支持 `--dry-run`，每次调用都是真实写请求。按 mutation-common「失败后定位字段再针对性重试」执行时，本命令有一个便利：只需针对报错涉及的那一两个字段调整快捷 flag 后重新提交一次即可——命令内部的 fetch-then-merge 会自动重新拉取当前完整状态并叠加，不需要手动把之前改对的字段再传一遍。

## 批量编辑（`material update batch`）

把**同一个字段值**批量写到多个物料（`idList + updateMap`，不是逐条不同的值）：

```bash
shb-cli warehouse material update batch --ids <id1>,<id2>,<id3> --field property --value 耗材 --yes

# 非字符串值（如布尔/数字），用 --value-json
shb-cli warehouse material update batch --ids <id1>,<id2> --field materialStatus --value-json true --yes

# 预览请求体而不真正发起
shb-cli warehouse material update batch --ids <id1>,<id2> --field property --value 耗材 --dry-run
```

- **必须传 `--yes`**（或 `--dry-run` 仅预览），且批量改 `sn` 会被硬性拒绝——两条规则的原因见 mutation-common 安全规则第 1、3 条。
- 最多一次 500 条 id。
- **只有以下系统字段真正生效**，其余系统字段名会被后端静默忽略（不报错，也不生效）：`sn`、`name`、`property`、`snManage`、`unit`、`forSale`、`costPrice`、`depositPrice`、`channelPrice`、`salePrice`、`images`、`standard`、`type`、`description`。租户自定义字段名不受此白名单限制，正常生效。

## 批量启用/停用（`material update status`）

```bash
shb-cli warehouse material update status --ids <id1>,<id2> --status true   # 批量启用
shb-cli warehouse material update status --ids <id1>,<id2> --status false  # 批量停用
```

无 `--yes` 要求（无阻塞前置条件，风险低于删除/批量改字段）。

## 典型组合场景

### 批量停用一批物料

```bash
# 1. 先搜到目标物料，拿到 id 列表（搜索用法见 shb-warehouse-material-search.md）
shb-cli warehouse material search --property 耗材 --format-data --fields sn,id,name

# 2. 批量停用
shb-cli warehouse material update status --ids <id1>,<id2>,<id3> --status false
```