--- name: shb-warehouse-bom version: "1.0.0" description: "当用户提到云仓物料服务BOM相关操作时触发，包括：搜索/查询/查看物料服务BOM列表或详情、按主物料/编号/启用状态筛选BOM、查询BOM组成物料树、创建物料服务BOM、编辑BOM、BOM启停用、删除BOM、摘除组成物料、撤销BOM删除。通过 shb-cli 操作云仓物料服务BOM的查询与创建/编辑/删除。物料主数据见 shb-warehouse-material，物料替换见 shb-warehouse-replacement。" metadata: requires: bins: ["shb-cli"] cliHelp: "shb-cli warehouse bom --help" --- # warehouse bom (v1.0) **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../shb-shared/SKILL.md`](../shb-shared/SKILL.md)，其中包含 profile 初始化、环境选择、OAuth2 登录、token 导入、租户切换、安全规则。所有 warehouse 命令都依赖 `shb-shared` 描述的认证状态。** ## Core Concepts - **物料服务BOM**：云仓物料主数据下的一个子概念——一个物料服务BOM = 一个"主物料"（整机/备件） + 它的"组成物料"（子物料，可多级嵌套，如整机 → 部件 → 零件）。标识为 `id`（**整数**），对外展示编号是 `sn`（服务端自动生成，创建时不可自定义）。 - **BOM 编号 ≠ 物料编号**：两者是不同的编号体系。主物料通过 `materialId`/`materialSn`/`materialName` 关联到物料域（[`../shb-warehouse-material/SKILL.md`](../shb-warehouse-material/SKILL.md)），用户说"这个物料的 BOM"要用 `materialSn`/`materialId` 过滤，不要把物料编号传给 BOM 的 `--sn`。 - **一个主物料只能有一个启用中的物料服务BOM**：重复为同一主物料建 BOM 会报错。 - **组成物料树**：组成物料是多级 `children` 嵌套树，`bom materials` 直接输出原始 JSON，不支持 `--format-data`（现有格式化工具只处理扁平行）。 - **物料服务BOM ≠ 物料替换**：物料替换（[`../shb-warehouse-replacement/SKILL.md`](../shb-warehouse-replacement/SKILL.md)）是完全不同的业务概念，两者都挂在物料主数据下但互不相关，不要混淆。 - **物料主数据的查询与写入不在本 skill**：查物料 id、物料详情、创建/编辑物料，走 [`../shb-warehouse-material/SKILL.md`](../shb-warehouse-material/SKILL.md)。 - **分页与响应信封**：与物料域一致——分页字段 `pageNum`（从 1 开始），响应带 `{success,code,message,data}` 信封，`--format-data` 已自动解包（完整说明见 material skill 的 Core Concepts）。 ## Important Notes ### 面向用户的输出措辞（禁止回显接口字段名与内部机制） **CRITICAL** — 以下内容**只供你内部使用，禁止出现在给用户的回复里**（适用于本 skill 全部命令，查询回复同样受约束）： 1. **接口/JSON 字段名**：`total`、`pageNum`、`list`、`sn`、`materialSn`、`enabled`、`materialNum` 等，一律转成自然语言。例：「total 为 12」→「共 12 个物料服务BOM」；「enabled=1」→「启用」。 2. **命令与一切技术细节**：任何 shb-cli 命令、子命令、flag、参数名，以及取数过程（分页、信封解包、全量拉取、字段裁剪、fetch-then-merge）都是后台实现细节，**回复里绝不出现，也不要解释你用了什么命令/参数、怎么取的数**，换种说法也不行。直接给结果。 正例：「共查到 12 个物料服务BOM，其中 3 个已禁用」「这个 BOM 的主物料是空调整机，一级组件有 5 种」。 ### 复用已知 ID（禁止重复搜索、禁止捏造） **CRITICAL** — BOM 的 `id` **只能来自已有结果**：本轮对话里任意一次 `bom search`/`bom detail` 的返回，或 `bom create` 成功后打印的 `id`。两条铁律： 1. 只要本轮对话里出现过某 BOM 的 `id`，后续再提到同一 BOM **必须直接复用已有 id，禁止重新发起搜索**。 2. 当前对话里从未出现过该 BOM 时，必须先 `bom search` 查到再用——**严禁凭空编造数字、严禁把 BOM 编号（`sn`）、物料编号或用户口头报的数字直接当 `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 bom search -o json # 默认，完整 pretty JSON shb-cli warehouse bom search -o raw # 紧凑单行 JSON，适合 jq 管道 shb-cli warehouse bom search -o yaml # YAML 格式 shb-cli warehouse bom search --format-data -o table # 字段文案和值均格式化后的表格 ``` ### 写操作前置 **CRITICAL** — 执行任何创建/编辑/删除/启停用等写操作前，必须先加载 [`references/shb-warehouse-bom-mutation-common.md`](references/shb-warehouse-bom-mutation-common.md)——它是本域全部变更安全规则的**唯一出处**，本 SKILL.md 不含任何变更安全规则。 ## API Resources **CRITICAL — 执行任何 bom 子命令前，必须先加载下表该操作对应的全部 reference 文档（一个不能少），再执行命令：** | 操作 | 必须加载（全部） | |------|-----------------| | 搜索物料服务BOM列表（`bom search`） | [`references/shb-warehouse-bom-search.md`](references/shb-warehouse-bom-search.md) | | 查看BOM详情 / 组成物料树（`bom detail` / `bom materials`） | [`references/shb-warehouse-bom-detail.md`](references/shb-warehouse-bom-detail.md) | | 创建BOM（`bom create`） | [`references/shb-warehouse-bom-mutation-common.md`](references/shb-warehouse-bom-mutation-common.md) + [`references/shb-warehouse-bom-create.md`](references/shb-warehouse-bom-create.md) | | 编辑BOM / 启停用（`bom edit` / `bom edit status`） | [`references/shb-warehouse-bom-mutation-common.md`](references/shb-warehouse-bom-mutation-common.md) + [`references/shb-warehouse-bom-edit.md`](references/shb-warehouse-bom-edit.md) | | 删除BOM / 摘除组成物料 / 撤销删除（`bom delete` / `bom delete materials` / `bom revert`） | [`references/shb-warehouse-bom-mutation-common.md`](references/shb-warehouse-bom-mutation-common.md) + [`references/shb-warehouse-bom-delete.md`](references/shb-warehouse-bom-delete.md) | 同一会话中每份 reference 只需加载一次。 ## 权限与安全 - 只读命令：`bom search`、`bom detail`、`bom materials`。 - 写命令：`bom create`、`bom edit`、`bom edit status`、`bom delete`、`bom delete materials`、`bom revert`——风险档位与全部安全规则的唯一出处是 [`references/shb-warehouse-bom-mutation-common.md`](references/shb-warehouse-bom-mutation-common.md)。 - 可见范围 = 当前 profile 用户在 SHB 云仓后端的租户/权限范围，服务端根据登录用户自动注入，无需也不能自己传 `tenantId`；BOM 查询/操作另需 `BOM_VIEW` 权限。 ## 排错 - 404 / `No message available` —— 通常是请求路径或环境不匹配，用 `shb-cli version --json` 确认 `build_env`，再用 `shb-cli config` 确认当前环境和 base URL。 - 401 / `token is empty` / `valid: false` → 回到 `shb-shared` 技能重新认证。 - `--bom-id is required` → `bom detail`/`bom materials`/`bom delete materials` 缺少必填字段。 - `--material-property must be one of: whole, spare` / `--enabled must be one of: enabled, disabled, all` → `bom search` 的这两个 flag 只接受列出的取值，不接受原始数字或中文。 - `... requires --yes to confirm ...` → `bom delete`/`bom delete materials` 未传 `--yes`（也未传 `--dry-run`），按设计拒绝执行；确认操作意图后补上 `--yes`。 - 该主物料已存在物料服务BOM → `bom create` 想创建的主物料已经有一个启用中的物料服务BOM 了，一个主物料只能有一个；改用 `bom edit` 修改现有物料服务BOM，或先确认用户是否记错了物料。 - 组成物料重复 / 组成物料不能是主物料本身 → `bom create`/`bom edit` 的 `materialList` 里有重复 `materialId`，或包含了主物料自己的 id。 - `--material-ids is required` → `bom delete materials` 缺少必填字段。 - 这会级联删除整个 BOM（提示文案）→ `bom delete materials` 检测到 `--material-ids` 覆盖了全部现存组件，属于正常提示，不是错误，需要用户确认这就是预期行为。 ## 后续扩展（规划中，当前不支持） - BOM 的操作记录查询（`/records`）、爆炸图完整管理（`bomPicFormList` / `/pic/*`）、标签（`label`）批量管理、物料关联 BOM 反查（`/material/relation/info`）——这些只能通过 `--data` 高级用法零散涉及，没有专用命令。 用户提出以上需求时，明确告知当前版本暂不支持，不要臆造命令。 ## References - [`references/shb-warehouse-bom-search.md`](references/shb-warehouse-bom-search.md) —— 物料服务BOM列表搜索（只读） - [`references/shb-warehouse-bom-detail.md`](references/shb-warehouse-bom-detail.md) —— 物料服务BOM详情与组成物料树查询（只读） - [`references/shb-warehouse-bom-mutation-common.md`](references/shb-warehouse-bom-mutation-common.md) —— BOM 域公共变更规范（全部写操作的强制前置） - [`references/shb-warehouse-bom-create.md`](references/shb-warehouse-bom-create.md) —— 物料服务BOM创建 - [`references/shb-warehouse-bom-edit.md`](references/shb-warehouse-bom-edit.md) —— 物料服务BOM编辑与启停用 - [`references/shb-warehouse-bom-delete.md`](references/shb-warehouse-bom-delete.md) —— 物料服务BOM删除、组成物料摘除与撤销删除