---
name: shb-warehouse-replacement
version: "1.0.0"
description: "当用户提到云仓物料替换相关操作时触发，包括：搜索/查询/查看物料替换记录列表或详情、按原始物料/替换物料/有效性筛选替换记录、按原始物料查当前有效替换候选、查询替换字段定义、创建物料替换记录（含批量）、编辑替换记录、物料替换启停用、删除替换记录。通过 shb-cli 操作云仓物料替换关系的查询与创建/编辑/删除。物料主数据见 shb-warehouse-material，物料服务BOM见 shb-warehouse-bom。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli warehouse replacement --help"
---

# warehouse replacement (v1.0)

**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../shb-shared/SKILL.md`](../shb-shared/SKILL.md)，其中包含 profile 初始化、环境选择、OAuth2 登录、token 导入、租户切换、安全规则。所有 warehouse 命令都依赖 `shb-shared` 描述的认证状态。**

## Core Concepts

- **物料替换（Replacement）**：云仓物料主数据下的一个子概念。一条替换记录是**有方向的映射**：`originalId`（原始物料，被替换的）→ `replaceId`（替换物料，拿来顶替的），**不是双向关系**——如果要让"替换物料"反过来也能被"原始物料"顶替，需要单独再建一条方向相反的记录。标识为记录自己的 `id`（**整数**），不是物料编号。
- **优先级（`priority`）**：同一个原始物料可以有多个替换候选，按 `priority` 排序（数字越小优先级越高，创建时后端自动追加到末尾），出库缺货时按优先级从小到大依次尝试替换。
- **时间窗与开关**：每条记录带生效/失效时间窗（或 `isPermanently` 永久有效）、独立的启停用开关（`enable`）、可选的产品目录适用范围（`catalogIds`）。
- **物料替换 ≠ 物料服务BOM**：物料服务BOM（[`../shb-warehouse-bom/SKILL.md`](../shb-warehouse-bom/SKILL.md)）是完全不同的业务概念，两者都挂在物料主数据下但互不相关，不要混淆。
- **物料主数据的查询与写入不在本 skill**：查物料 id、物料详情、创建/编辑物料，走 [`../shb-warehouse-material/SKILL.md`](../shb-warehouse-material/SKILL.md)。用户说"这个物料能被什么替换"要用 `originalId`/`originalSN` 过滤替换记录，不要和物料本身的查询混淆。
- **分页与响应信封**：与物料域一致——分页字段 `pageNum`（从 1 开始），响应带 `{success,code,message,data}` 信封，`--format-data` 已自动解包（完整说明见 material skill 的 Core Concepts）。

## Important Notes

### 面向用户的输出措辞（禁止回显接口字段名与内部机制）

**CRITICAL** — 以下内容**只供你内部使用，禁止出现在给用户的回复里**（适用于本 skill 全部命令，查询回复同样受约束）：

1. **接口/JSON 字段名**：`total`、`pageNum`、`list`、`originalSN`、`replaceSN`、`priority`、`enable`、`state` 等，一律转成自然语言。例：「total 为 8」→「共 8 条替换关系」；「state=1」→「生效中」。
2. **命令与一切技术细节**：任何 shb-cli 命令、子命令、flag、参数名，以及取数过程（分页、信封解包、全量拉取、字段裁剪、fetch-then-merge）都是后台实现细节，**回复里绝不出现，也不要解释你用了什么命令/参数、怎么取的数**，换种说法也不行。直接给结果。

正例：「共查到 8 条替换关系，其中 2 条已失效」「缺货时可以用备用整机顶替，其次是旧款整机」。

### 复用已知 ID（禁止重复搜索、禁止捏造）

**CRITICAL** — 替换记录的 `id` **只能来自已有结果**：本轮对话里任意一次 `replacement search`/`replacement detail`/`replacement by-original` 的返回，或 `replacement create` 成功后打印的 `id`。两条铁律：

1. 只要本轮对话里出现过某条替换记录的 `id`，后续再提到同一条记录**必须直接复用已有 id，禁止重新发起搜索**。
2. 当前对话里从未出现过该记录时，必须先查到再用——**严禁凭空编造数字、严禁把物料编号或用户口头报的数字直接当 `id` 用**。

### 参数传递方式与解析优先级

所有 search/create/edit 类命令支持三种传参：快捷 flag、`--data`（内联 JSON）、`--file`（JSON 文件）。**解析优先级 `--file` ＞ `--data` ＞ 快捷 flags——传了 `--file` 或 `--data` 时快捷 flags 会被整体忽略（不合并）**。使用取舍：常规字段用快捷 flags；快捷 flag 未覆盖的复杂/高级字段用 `--data` 内联；`--file` 仅本地已有现成 JSON 文件时用。

### 输出格式

所有命令支持全局 `--output` / `-o` 标志：

```bash
shb-cli warehouse replacement search -o json          # 默认，完整 pretty JSON
shb-cli warehouse replacement search -o raw           # 紧凑单行 JSON，适合 jq 管道
shb-cli warehouse replacement search -o yaml          # YAML 格式
shb-cli warehouse replacement search --format-data -o table   # 字段文案和值均格式化后的表格
```

### 写操作前置

**CRITICAL** — 执行任何创建/编辑/删除/启停用等写操作前，必须先加载 [`references/shb-warehouse-replacement-mutation-common.md`](references/shb-warehouse-replacement-mutation-common.md)——它是本域全部变更安全规则的**唯一出处**，本 SKILL.md 不含任何变更安全规则。

## API Resources

**CRITICAL — 执行任何 replacement 子命令前，必须先加载下表该操作对应的全部 reference 文档（一个不能少），再执行命令：**

| 操作 | 必须加载（全部） |
|------|-----------------|
| 搜索替换记录列表（`replacement search`） | [`references/shb-warehouse-replacement-search.md`](references/shb-warehouse-replacement-search.md) |
| 查看替换详情 / 按原始物料查有效替换候选（`replacement detail` / `replacement by-original`） | [`references/shb-warehouse-replacement-detail.md`](references/shb-warehouse-replacement-detail.md) |
| 查询替换字段定义（`replacement field list` / `replacement field save-fields`） | [`references/shb-warehouse-replacement-field.md`](references/shb-warehouse-replacement-field.md) |
| 创建替换记录（`replacement create` / `replacement create batch`） | [`references/shb-warehouse-replacement-mutation-common.md`](references/shb-warehouse-replacement-mutation-common.md) + [`references/shb-warehouse-replacement-create.md`](references/shb-warehouse-replacement-create.md) |
| 编辑替换记录 / 启停用（`replacement edit` / `replacement edit enable`） | [`references/shb-warehouse-replacement-mutation-common.md`](references/shb-warehouse-replacement-mutation-common.md) + [`references/shb-warehouse-replacement-edit.md`](references/shb-warehouse-replacement-edit.md) |
| 删除替换记录（`replacement delete`） | [`references/shb-warehouse-replacement-mutation-common.md`](references/shb-warehouse-replacement-mutation-common.md) + [`references/shb-warehouse-replacement-delete.md`](references/shb-warehouse-replacement-delete.md) |

同一会话中每份 reference 只需加载一次。

## 权限与安全

- 只读命令：`replacement search`、`replacement detail`、`replacement by-original`、`replacement field list`、`replacement field save-fields`。
- 写命令：`replacement create`、`replacement create batch`、`replacement edit`、`replacement edit enable`、`replacement delete`——风险档位与全部安全规则的唯一出处是 [`references/shb-warehouse-replacement-mutation-common.md`](references/shb-warehouse-replacement-mutation-common.md)。
- 可见范围 = 当前 profile 用户在 SHB 云仓后端的租户/权限范围，服务端根据登录用户自动注入，无需也不能自己传 `tenantId`。

## 排错

- 404 / `No message available` —— 通常是请求路径或环境不匹配，用 `shb-cli version --json` 确认 `build_env`，再用 `shb-cli config` 确认当前环境和 base URL。
- 401 / `token is empty` / `valid: false` → 回到 `shb-shared` 技能重新认证。
- `--original-id is required` / `--replace-id is required` / `--id is required` → `replacement create`/`replacement edit`/`replacement detail`/`replacement by-original`/`replacement edit enable`（快捷 flag 模式）缺少必填字段。
- `originalId and replaceId must not be equal` 类拒绝信息（客户端产生，未发起网络请求）→ 用户想创建/编辑出一个物料替换它自己的记录，按设计直接拒绝；确认是否记错了物料 id。
- `该替换物料已替换过该原始物料`（错误码 411000）→ 同一 `(originalId, replaceId)` 组合已存在，服务端强校验，无需重复创建，可用 `replacement by-original` 复查现状。
- `--condition-type must be one of: original, replace` / `--state must be one of: active, expired, pending` → `replacement search` 的这两个 flag 只接受列出的取值。
- `--enabled must be true or false` → `replacement search`/`replacement edit enable` 的 `--enabled`/`--enable` 只接受 `true`/`false`。
- `... requires --yes to confirm ...` → `replacement delete` 未传 `--yes`（也未传 `--dry-run`），按设计拒绝执行；确认操作意图后补上 `--yes`。

## 后续扩展（规划中，当前不支持）

- 物料替换优先级批量重排的专用命令（可通过 `--data` 携带 `replacementList`/`sortList` 手动实现，无专用 flag）。
- 物料替换标签管理。

用户提出以上需求时，明确告知当前版本暂不支持，不要臆造命令。

## References

- [`references/shb-warehouse-replacement-search.md`](references/shb-warehouse-replacement-search.md) —— 物料替换记录列表搜索（只读）
- [`references/shb-warehouse-replacement-detail.md`](references/shb-warehouse-replacement-detail.md) —— 物料替换详情与按原始物料查有效替换候选（只读）
- [`references/shb-warehouse-replacement-field.md`](references/shb-warehouse-replacement-field.md) —— 物料替换字段定义查询（只读）
- [`references/shb-warehouse-replacement-mutation-common.md`](references/shb-warehouse-replacement-mutation-common.md) —— 替换域公共变更规范（全部写操作的强制前置）
- [`references/shb-warehouse-replacement-create.md`](references/shb-warehouse-replacement-create.md) —— 物料替换记录创建（含批量）
- [`references/shb-warehouse-replacement-edit.md`](references/shb-warehouse-replacement-edit.md) —— 物料替换记录编辑与启停用
- [`references/shb-warehouse-replacement-delete.md`](references/shb-warehouse-replacement-delete.md) —— 物料替换记录删除