---
name: shb-warehouse-material
version: "1.0.0"
description: "当用户提到云仓物料相关操作时触发，包括：搜索/查询/查看云仓物料列表或详情、按编号/名称/属性/类型/规格/启用状态筛选物料、查询物料字段定义、创建物料、编辑物料（单条/批量）、启用停用物料、删除物料、字段唯一性校验。通过 shb-cli 操作云仓物料主数据的查询与创建/编辑/删除。物料服务BOM 见 shb-warehouse-bom，物料替换见 shb-warehouse-replacement，备件见 shb-part。当前不含入库/出库/调拨/盘点等库存操作。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli warehouse material --help"
---

# warehouse material (v1.0)

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

## Core Concepts

- **Material（云仓物料）**：云仓（cloud-warehouse）系统中的物料主数据，标识为 `id`（**整数**，不是 UUID）；对外展示编号是 `sn`。本 skill 覆盖物料的查询与创建/编辑/批量编辑/删除/启停用/唯一性校验，不含入库/出库/调拨/盘点等库存操作。
- **物料（Material）≠ 备件（Sparepart / `shb-part` 技能）**：两者是完全不同的业务系统和数据表，字段名也不同——物料的编号字段是 `sn`（备件是 `serialNumber`），启用状态字段是 `materialStatus` 布尔值（备件是 `enable` 字符串 `"1"`/`"0"`）。用户口语含糊说"查一下这个东西"/"看看库存"时，先确认指的是云仓物料还是 `shb-part` 备件，不要凭经验猜。
- **启用状态（`materialStatus`）**：**布尔值**，`true` = 启用，`false` = 停用。过滤时传 `true`/`false` 字符串（会被转换为 JSON 布尔），**不要**传 `"1"`/`"0"`（那是备件域 `enable` 字段的写法，物料域不通用）。展示给用户时转成中文（`启用`/`停用`）。
- **分页与响应信封**：物料搜索接口分页字段是 **`pageNum`（从 1 开始）**，响应结构是 `Result<PageInfo<MaterialVO>>` —— **响应本身带 `{success,code,message,data}` 信封**，`data` 才是 `{pageNum,pageSize,total,pages,list}` 分页结构，`--format-data` 已自动解包，无需自己处理信封。（这一点与 `shb-part` 相反：备件域响应是裸 `PageInfo`，没有信封。）
- **价格字段**：`salePrice`（终端销售价）、`costPrice`（成本价）、`depositPrice`（押金价）、`channelPrice`（渠道价），均为字符串数值，展示时保留两位小数（`--format-data` 已自动处理）。
- **Field（物料字段）**：物料表单字段定义（新增/编辑用）。通过 `warehouse material field list` 获取，返回原始表单字段定义，不代表列表页展示字段。
- **Formatted Data（格式化数据）**：把列表/详情原始字段转换为 `columns + rows`，字段值转为人类可读文案（价格两位小数、启用状态中文）。默认列表列：编号、名称、属性、单位、启用状态、终端销售价、成本价、创建时间。
- **关联子域**：物料服务BOM（一个主物料 + 组成物料树）走 [`../shb-warehouse-bom/SKILL.md`](../shb-warehouse-bom/SKILL.md)，物料替换（原始物料 → 替换候选的有向映射）走 [`../shb-warehouse-replacement/SKILL.md`](../shb-warehouse-replacement/SKILL.md)；两者都挂在物料主数据下但**互不相关**，不要混淆。

## Important Notes

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

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

1. **接口/JSON 字段名**：`total`、`pageNum`、`list`、`sn`、`materialStatus`、`salePrice` 等，一律转成自然语言。例：「total 为 30」→「共 30 个物料」；「materialStatus=true」→「启用」。
2. **命令与一切技术细节**：任何 shb-cli 命令、子命令、flag、参数名，以及取数过程（分页、信封解包、全量拉取、字段裁剪、fetch-then-merge）都是后台实现细节，**回复里绝不出现，也不要解释你用了什么命令/参数、怎么取的数**，换种说法也不行。直接给结果。
3. **转述字段定义时只用中文展示名**——完整规范（禁止括号注释格式、禁止解释字段元数据、必填的说法、正反例）的唯一出处是 [`references/shb-warehouse-material-field.md`](references/shb-warehouse-material-field.md)，凡涉及字段定义的操作按下方加载表必然会加载它。

正例：「共查到 12 个启用中的物料，其中螺丝、螺母……」「这个物料的成本价是 8.50 元，销售价是 15.00 元」。

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

**CRITICAL** — 物料的 `id` **只能来自已有结果**：本轮对话里任意一次 `material search`/`material detail` 的返回，或 `material create` 成功后打印的 `id`。两条铁律：

1. 只要本轮对话里出现过某物料的 `id`，后续再提到同一物料（无论通过编号、关键字还是描述）**必须直接复用已有 id，禁止重新发起搜索**。
2. 当前对话里从未出现过该物料时，必须先 `material search` 查到再用——**严禁凭空编造数字、严禁把物料编号（`sn`）或用户口头报的数字直接当 `id` 用**。

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

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

### 输出格式

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

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

### 写操作前置

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

## API Resources

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

| 操作 | 必须加载（全部） |
|------|-----------------|
| 搜索物料列表（`material search`） | [`references/shb-warehouse-material-search.md`](references/shb-warehouse-material-search.md) |
| 查看物料详情（`material detail`） | [`references/shb-warehouse-material-detail.md`](references/shb-warehouse-material-detail.md) |
| 查询字段定义 / 字段唯一性预检（`material field list` / `material field check`） | [`references/shb-warehouse-material-field.md`](references/shb-warehouse-material-field.md) |
| 创建物料（`material create`） | [`references/shb-warehouse-material-mutation-common.md`](references/shb-warehouse-material-mutation-common.md) + [`references/shb-warehouse-material-create.md`](references/shb-warehouse-material-create.md) + [`references/shb-warehouse-material-field.md`](references/shb-warehouse-material-field.md) |
| 编辑物料（`material update` / `material update batch` / `material update status`） | [`references/shb-warehouse-material-mutation-common.md`](references/shb-warehouse-material-mutation-common.md) + [`references/shb-warehouse-material-update.md`](references/shb-warehouse-material-update.md) + [`references/shb-warehouse-material-field.md`](references/shb-warehouse-material-field.md) |
| 删除物料（`material delete`） | [`references/shb-warehouse-material-mutation-common.md`](references/shb-warehouse-material-mutation-common.md) + [`references/shb-warehouse-material-delete.md`](references/shb-warehouse-material-delete.md) |

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

## 权限与安全

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

## 排错

- 404 / `No message available` —— 通常是请求路径或环境不匹配，用 `shb-cli version --json` 确认 `build_env`，再用 `shb-cli config` 确认当前环境和 base URL。
- 401 / `token is empty` / `valid: false` → 回到 `shb-shared` 技能重新认证。
- `--id is required` → `material detail`/`material update`（快捷 flag 模式）缺少必填字段。
- `--material-status must be true or false` / `--status must be true or false` → 只接受 `true`/`false`，不接受 `1`/`0`/中文。
- `... requires --yes to confirm ...` → `material delete`/`material update batch` 未传 `--yes`（也未传 `--dry-run`），按设计拒绝执行；确认操作意图后补上 `--yes`。
- `refusing batch-update of field "sn" across N materials` → 用户想批量改多个物料的编号，命令按设计硬性拒绝；改用 `material update --id <id> --sn <value>` 逐条处理。
- `material update` 报错提示无法获取字段列表 → `material-query field-list` 调用失败，命令为避免静默清空系统字段选择整体中止，需先排查该接口本身是否可用。
- `MATERIAL_CAN_NOT_DELETE_CAUSE_INVENTORY` / `MATERIAL_CAN_NOT_DELETE_CAUSE_BOM`（或类似错误信息里提到库存/BOM）→ `material delete` 请求里有物料仍有库存或被 BOM 引用，按设计整批拒绝删除，需要先处理库存/BOM 引用，或从本次删除列表中剔除该物料。

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

- 物料入库、出库、调拨、盘点等库存写操作。
- 按产品目录/BOM/标签等高级条件的复杂筛选（可通过 `--data`/`--file` 传原始 JSON 的 `conditions`/`catalogIds`/`labelQuery` 等字段实现，但暂无专用 flag）。
- `material create` 的产品目录关联（当前仅可通过 `--data` 高级用法传入，无专用快捷 flag）。

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

## References

- [`references/shb-warehouse-material-search.md`](references/shb-warehouse-material-search.md) —— 云仓物料列表搜索（只读）
- [`references/shb-warehouse-material-detail.md`](references/shb-warehouse-material-detail.md) —— 云仓物料详情查询（只读）
- [`references/shb-warehouse-material-field.md`](references/shb-warehouse-material-field.md) —— 云仓物料字段定义查询与字段唯一性预检（只读）
- [`references/shb-warehouse-material-mutation-common.md`](references/shb-warehouse-material-mutation-common.md) —— 物料域公共变更规范（全部写操作的强制前置）
- [`references/shb-warehouse-material-create.md`](references/shb-warehouse-material-create.md) —— 云仓物料创建
- [`references/shb-warehouse-material-update.md`](references/shb-warehouse-material-update.md) —— 云仓物料编辑（单条/批量/启停用）
- [`references/shb-warehouse-material-delete.md`](references/shb-warehouse-material-delete.md) —— 云仓物料删除