---
name: shb-part
version: "1.2.0"
description: "当用户提到备件相关操作时触发，包括：搜索/查询/查看备件列表或详情、按名称/类型/规格/启用状态筛选备件、查询备件字段定义、查询备件库存/库存不足预警、查询单备件在各仓库的库存分布、查询个人备件库/领用记录/使用记录/持有数量。通过 shb-cli 操作备件列表搜索、格式化数据、详情查看、字段查询、库存查询和个人备件库查询。当前覆盖备件、备件库存与个人备件库的只读查询，不含创建/编辑/删除等写操作。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli part --help"
---

# part (v1.2)

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

## Core Concepts

- **Sparepart（备件）**：售后宝备件系统中的备件实例，标识为 `id`（UUID）；对外展示编号是 `serialNumber`。当前版本（v1.2）覆盖备件本身、备件库存与个人备件库的只读查询，不含创建/编辑/删除等写操作。
- **三层概念，不要混用**：
  - `part search`/`part detail` —— 备件静态信息（名称、规格、价格），与仓库/人无关。
  - `part stock search`/`part stock distribution` —— **库存记录 = 备件 × 仓库**，含库存数量、安全库存、库存状态。
  - `part personal *` —— **个人库记录 = 备件 × 人**，某人手上（含待退回中）持有多少备件、领用/退回流水、工单使用流水。
  用户问"还有多少库存"要分清楚问的是"仓库库存"还是"某人手上的库存"，前者用 `stock`，后者用 `personal`，都不要用 `part detail`（不含库存/持有字段）。
- **Field（备件字段）**：备件表单字段定义。通过 `part field list` 获取。
- **启用状态（`enable`）**：`1` = 启用，`0` = 停用。过滤时传 `"1"`/`"0"` 字符串，**不要**传中文。展示给用户时转成中文（`启用`/`停用`）。
- **搜索关键字大小写坑**：`part search`/`part stock search`/`part personal search`/`part personal stock-record`/`part personal use-record` 的快捷 flag 都是 `--keyword`，但 JSON body/query 里的字段名是 **`keyWord`（大写 W）**，写 `keyword` 会被后端静默忽略、不报错。**唯独 `part personal users` 是例外**：它的 query 参数就是小写 `keyword`，别弄反。
- **分页**：备件/库存/个人库搜索接口分页字段都是 **`pageNum`（从 1 开始）**，响应结构是裸 `PageInfo`（`{pageNum, pageSize, total, pages, list}`），**响应本身没有 status/data 信封**（`part personal holding` 例外，见下）。这与工单（`page`/`content`/`totalElements`）、事件（信封+PageInfo）都不同。
- **价格字段**：`salePrice`（销售价格）、`costPrice`（成本价格），展示时保留两位小数（`--format-data` 已自动处理）。
- **关联产品类型（`productTypeList`）**：备件关联的产品目录类型列表，元素含 `catalogName`；`--format-data` 会自动拼接为逗号分隔的名称串。
- **库存状态（`stockStatus`，仅 `stock search`）**：派生列，综合"当前库存已降到安全库存以下"和"后端预警标记"两个信号，显示"不足"/"预警"/"不足/预警"/"正常"，详见 [`references/shb-part-stock.md`](references/shb-part-stock.md)。
- **个人库"数量"（`quantity`，仅 `personal search`）**：派生列 = `repertoryCount`（在手数量）+ `applyBacking`（退回中数量），因为退回中的备件仍算此人持有。**这个数字通常比 `stock distribution` 里同一人"个人库"条目显示的 `repertoryCount` 大**（后者是纯在手数量，不含退回中）——两处对不上是正常的，不是数据错误，别当 bug 报告给用户。
- **个人库 userId 语义（重要，容易踩坑）**：`part personal search`/`stock-record`/`use-record` **不传 `--user-id` 不等于"查我自己"**，而是按当前登录人的数据权限查团队/全部可见成员。**要查特定某人，必须先用 `part personal users --keyword <姓名>` 拿到 `userId` 再显式传 `--user-id`**，不要凭空猜测或省略。
- **`part personal holding` 是本模块唯一带信封的接口**：响应是 `{status,succ,message,data}`，`--format-data` 均已自动解包出 `data`（一个 `[{sparepartId,sparepartNumber}]` 数组），无需用户关心信封细节。
- **Formatted Data（格式化数据）**：把列表/详情原始字段转换为 `columns + rows`，字段文案固定（备件没有像工单/事件那样的自定义属性系统），字段值转为人类可读文案（价格两位小数、启用状态中文、关联产品类型名称；`stock search`/`personal *` 额外把嵌套的 `sparepart{...}`/`repertory{...}` 展平为扁平字段）。

## Important Notes

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

**CRITICAL** — 以下内容**只供你内部使用，禁止出现在给用户的回复里**：

1. **接口/JSON 字段名**：`total`、`pageNum`、`list`、`serialNumber`、`enable`、`repertoryCount`、`sparepartNumTotal` 等，一律转成自然语言。例：「total 为 30」→「共 30 个备件」；「enable=1」→「启用」；「stockStatus=不足」→「库存不足」。
2. **命令与一切技术细节**：任何 shb-cli 命令、子命令、flag、参数名，以及取数过程（分页、数量判断、全量拉取、字段裁剪）都是后台实现细节，**回复里绝不出现**。直接给结果。

正例：「共查到 8 个启用中的备件，其中刹车片、机油滤芯……」「有 3 个仓库的备件库存不足：……」「天驰手上有 20 个聚氨酯管（含 1 个退回中）」。

此规则适用于所有 part 子命令（`search` / `detail` / `field list` / `stock search` / `stock distribution` / `personal search` / `personal stock-record` / `personal use-record` / `personal users` / `personal holding`）。

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

**CRITICAL** — 只要本轮对话的任意一次 search 结果里出现过某备件的 `id` 或某用户的 `userId`（无论来自 `part search`、`part stock search` 还是 `part personal users`），后续再提到同一对象时**必须直接复用已有 id，禁止重新发起搜索**。只有当前对话中从未出现该对象时才允许发起新搜索。

### 输出格式

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

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

### 只读模块

本模块（v1.2）**只有查询命令，没有写操作**。用户要求创建/编辑/删除备件、入库/出库/调拨/盘点库存、领用/归还/审批个人备件时，明确告知当前 shb-cli 暂不支持，不要假装执行成功。

## API Resources

**CRITICAL — 执行任何 part 子命令前，必须先用 skill 工具加载对应 reference 文档，再执行命令：**

| 操作 | 必须先加载 |
|------|-----------|
| 搜索备件（`part search`） | [`references/shb-part-search.md`](references/shb-part-search.md) |
| 查看备件详情（`part detail`） | [`references/shb-part-detail.md`](references/shb-part-detail.md) |
| 查询备件字段（`part field list`） | [`references/shb-part-field.md`](references/shb-part-field.md) |
| 查询备件库存/库存不足/单备件库存分布（`part stock search` / `part stock distribution`） | [`references/shb-part-stock.md`](references/shb-part-stock.md) |
| 查询个人备件库/领用记录/使用记录/持有数量/人员搜索（`part personal *`） | [`references/shb-part-personal.md`](references/shb-part-personal.md) |

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

## 权限与安全

- 全部为只读命令：`search`、`detail`、`field list`、`stock search`、`stock distribution`、`personal search`、`personal stock-record`、`personal use-record`、`personal users`、`personal holding`。
- 可见范围 = 当前 profile 用户在 SHB 后端的权限范围；库存/个人库查询额外按团队数据权限过滤（服务端根据登录用户自动注入，无需也不能自己传）。

## 排错

- 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` → `part detail` / `part stock distribution` 快捷 flags 模式缺少必填字段。
- `--user-id is required` / `--sparepart-ids is required` → `part personal holding` 两个参数都必填，缺一即报错，不要凭空编造。
- `part personal search`/`stock-record`/`use-record` 结果比预期多很多 → 大概率是没传 `--user-id`，命令查的是团队/全部人的数据而不是"我"或某个具体人；先用 `personal users` 找到目标 userId 再传。

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

- 备件的创建、编辑、批量操作、删除。
- 库存的入库、出库、调拨、盘点等写操作。
- 个人备件库的领用、归还、审批等写操作。

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

## References

- [`references/shb-part-search.md`](references/shb-part-search.md) —— 备件搜索
- [`references/shb-part-detail.md`](references/shb-part-detail.md) —— 备件详情查询
- [`references/shb-part-field.md`](references/shb-part-field.md) —— 备件字段查询
- [`references/shb-part-stock.md`](references/shb-part-stock.md) —— 备件库存搜索与单备件库存分布
- [`references/shb-part-personal.md`](references/shb-part-personal.md) —— 个人备件库搜索、领用/使用记录、人员搜索、持有数量