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

# shb-cli warehouse replacement detail / by-original（替换详情与有效替换候选）

查看单条替换记录详情（`replacement detail`）和按原始物料查当前有效替换候选（`replacement by-original`）。列表搜索见 [`shb-warehouse-replacement-search.md`](shb-warehouse-replacement-search.md)。

## 查看替换记录详情（`replacement detail`）

```bash
shb-cli warehouse replacement detail --id <替换记录id>
```

- `--id` 必填，是替换记录自己的 `id`（**整数**），不是物料 id，来自 `replacement search` 返回结果中的 `id` 字段（来源约束见 SKILL.md「复用已知 ID」节）。
- 支持 `--format-data --fields <字段列表>`，不传 `--fields` 时默认输出全部已知字段。字段中文名与格式化行为同列表，见 [`shb-warehouse-replacement-search.md`](shb-warehouse-replacement-search.md) 的「--format-data 输出结构速查」。
- 详情响应内部是 `{id, replacementVO, replacementList}` 嵌套结构，`replacementVO.originalId`/`replaceId` 在原始响应里是完整的物料对象；`--format-data` 已自动展平成 `originalId`/`originalSN`/`originalName`/`replaceId`/`replaceSN`/`replaceName` 扁平字段，无需自己处理嵌套。

## 查当前有效的替换候选（`replacement by-original`）

```bash
shb-cli warehouse replacement by-original --original-id <原始物料id>

# 同样支持格式化输出
shb-cli warehouse replacement by-original --original-id <原始物料id> --format-data --fields replaceSN,replaceName,priority
```

- `--original-id` 必填。
- **这不是 `search --original-id X` 的简单重复**：服务端在这个接口里自动排除了已过期（且非永久有效）和已删除的记录，返回的是"此刻真正可用、按优先级排好序"的替换候选清单——典型场景是"这个物料现在缺货了，能用什么顶替，按什么顺序试"。用 `search` 加过滤条件理论上也能拼出类似结果，但要自己记得加 `--state active`，容易漏掉。
- 响应是裸数组（不是分页结构），但依然支持 `--format-data`。

## 典型组合场景

### 某个物料缺货了，查它能被什么替换

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

# 2. 查当前有效的替换候选，按优先级排好序
shb-cli warehouse replacement by-original --original-id <上一步的id> --format-data --fields replaceSN,replaceName,priority
```