> **先读** [`shb-warehouse-replacement-mutation-common.md`](shb-warehouse-replacement-mutation-common.md)（本域全部变更安全规则的唯一出处，含自我替换拦截、`priority` 自动追加、重复组合 411000）。

# shb-cli warehouse replacement create（创建替换记录，含批量）

覆盖 `replacement create`（单条创建）与 `replacement create batch`（批量新建）。

## 单条创建（`replacement create`）

```bash
# 基本创建
shb-cli warehouse replacement create --original-id <原始物料id> --replace-id <替换物料id>

# 带生效期/失效期
shb-cli warehouse replacement create --original-id <原始id> --replace-id <替换id> \
  --effective-date "2026-01-01 00:00:00" --expiration-date "2026-12-31 23:59:59"

# 永久有效（不传 --expiration-date，显式设 --permanently=true）
shb-cli warehouse replacement create --original-id <原始id> --replace-id <替换id> --permanently true

# 限定适用产品类型
shb-cli warehouse replacement create --original-id <原始id> --replace-id <替换id> --catalog-ids 101,102
```

- `--original-id`/`--replace-id` 均必填（快捷 flag 模式），且**两者不能相等**——命令会在发请求前拦下来（见 mutation-common 安全规则第 2 条）。物料 id 的查询走 [`../../shb-warehouse-material/SKILL.md`](../../shb-warehouse-material/SKILL.md)。
- 创建前建议先用 `replacement search --original-sn <原始物料编号>` 或 `replacement by-original --original-id <id>`（见 [`shb-warehouse-replacement-detail.md`](shb-warehouse-replacement-detail.md)）检查这对组合是否已存在，避免撞上服务端的重复校验（411000，见 mutation-common 安全规则第 6 条）。
- 优先级由后端自动追加到末尾，快捷 flag 不支持指定 `--priority`（原因见 mutation-common 安全规则第 5 条）。
- 创建成功后打印新记录 `id`（后续操作直接复用）；加 `--format-data` 会立即查一次详情并按格式化输出展示。
- 无需 `--yes`（风险档位见 [`shb-warehouse-replacement-mutation-common.md`](shb-warehouse-replacement-mutation-common.md)）。

## 批量新建（`replacement create batch`）

```bash
shb-cli warehouse replacement create batch --data '{
  "valueList": [
    {"formValueList": [{"fieldName":"originalId","value":2001},{"fieldName":"replaceId","value":2002}]},
    {"formValueList": [{"fieldName":"originalId","value":2001},{"fieldName":"replaceId","value":2003}]}
  ]
}'
```

- 只能通过 `--data`/`--file` 提交，没有快捷 flag（每条记录的字段组合本来就比较多，不适合拆成一堆重复 flag）。
- `valueList` 里每一项的形状和单条 `create` 的 `formValueList` 完全一样；`originalId`/`replaceId` 相等的项会被 CLI 逐项检查、命中即整体拒绝提交（见 mutation-common 安全规则第 2 条）。
- 可选 `sortList: [{id, priority}, ...]` 在批量新建的同时重排已有兄弟记录的优先级，高级用法。

## 典型组合场景

### 给一个缺货物料新增一个替换选项

```bash
# 1. 分别查到两个物料的 id（物料域查询，见 ../../shb-warehouse-material/SKILL.md）
shb-cli warehouse material search --sn <原始物料编号> --format-data --fields sn,id,name
shb-cli warehouse material search --sn <替换物料编号> --format-data --fields sn,id,name

# 2. 创建替换关系
shb-cli warehouse replacement create --original-id <原始id> --replace-id <替换id> --remark "临时替代方案"

# 3. 确认已生效（by-original 用法见 shb-warehouse-replacement-detail.md）
shb-cli warehouse replacement by-original --original-id <原始id> --format-data
```