> **先读** [`shb-warehouse-material-mutation-common.md`](shb-warehouse-material-mutation-common.md)（本域全部变更安全规则的唯一出处）与 [`shb-warehouse-material-field.md`](shb-warehouse-material-field.md)（字段定义与必填判断）。

# shb-cli warehouse material create（创建物料）

## 创建前置步骤

1. **确认字段与必填项**：先按 [`shb-warehouse-material-field.md`](shb-warehouse-material-field.md) 跑 `material field list`，判断本次创建缺哪些必填值、缺值时如何向用户开口（规范见该文档）。租户自定义必填字段通过 `--custom-fields` 提供。
2. **预检编号唯一性**（建议）：`sn` 在租户内必须唯一，先用 `material field check --field-name sn --field-value <sn>`（用法见 [`shb-warehouse-material-field.md`](shb-warehouse-material-field.md)）预检，避免创建失败后再排查原因。

## 用法

系统字段（`sn`/`name`/`property`/`unit`/`type`/`standard`/`description`/`sale-price`/`cost-price`/`deposit-price`/`channel-price`/`sn-manage`/`for-sale`/`material-status`）都有快捷 flag，会自动组装成后端要求的 `formValueList` 结构（`{fieldName, formType, isSystem, value}` 数组）：

```bash
# 快捷 flag（推荐，日常创建）
shb-cli warehouse material create --sn M-2001 --name "六角螺丝" --unit 个 --material-status true

# 带自定义字段（isSystem=0，fieldName 为租户自定义字段名，通过 material field list 查询）
shb-cli warehouse material create --sn M-2002 --name "六角螺母" --unit 个 \
  --custom-fields '{"custom_supplier":"某供应商"}'

# 完整 JSON body（高级用法：产品目录关联、业务标签等专用快捷 flag 未覆盖的字段）
shb-cli warehouse material create --data '{"formValueList":[{"fieldName":"sn","formType":"text","isSystem":1,"value":"M-2003"},{"fieldName":"name","formType":"text","isSystem":1,"value":"垫片"}]}'
```

- `--data`/`--file` 传入时快捷 flag 整体被忽略，需自行构造完整 `formValueList`。
- 创建成功后打印新物料 `id`（后续操作直接复用）；加 `--format-data` 会立即查一次详情并按格式化输出展示。
- 无需 `--yes`（风险档位见 [`shb-warehouse-material-mutation-common.md`](shb-warehouse-material-mutation-common.md)）。

## 典型组合场景

### 创建一个物料并修改其中一个字段

```bash
# 1. 创建前先预检编号是否冲突
shb-cli warehouse material field check --field-name sn --field-value M-2001

# 2. 创建
shb-cli warehouse material create --sn M-2001 --name "六角螺丝" --unit 个 --material-status true

# 3. 后续只改价格，其余字段自动保持不变（编辑用法见 shb-warehouse-material-update.md）
shb-cli warehouse material update --id <上一步返回的id> --sale-price 18.00
```