> **前置条件** — 执行以下任何命令前，请先确认已完成认证。如未认证，参见 [`../../shb-shared/SKILL.md`](../../shb-shared/SKILL.md)。

# shb-cli part search

备件搜索。

> **本文档出现的命令、子命令、flag、参数名、接口/JSON 字段名，以及取数过程（分页、数量判断、全量拉取、字段裁剪）都只供你后台执行，绝不出现在给用户的回复里**——不解释、不转述、不当理由说。回复只给业务结果与真实数量（如「共 30 个备件，其中启用 25 个」）。

## 搜索备件列表

### 快捷 flag 方式（推荐）

```bash
# 关键字搜索
shb-cli part search --keyword <关键字>

# 按名称筛选
shb-cli part search --name <名称>

# 按类型筛选
shb-cli part search --type <类型>

# 按启用状态筛选：1=启用，0=停用
shb-cli part search --enable 1

# 分页
shb-cli part search --page 1 --page-size 20

# 组合使用
shb-cli part search --keyword "刹车" --enable 1 --page-size 20

# 格式化数据输出：字段文案和值都会转换为可读内容，可用 --fields 指定字段
shb-cli part search --keyword "刹车" --format-data --fields serialNumber,name,type,salePrice,enable

# 获取全量数据：确定量不大就直接 --all 一次拿齐
shb-cli part search --enable 1 --all --format-data --fields serialNumber,name,salePrice,enable
```

### 完整 JSON body 方式

```bash
# 内联 JSON （推荐）
shb-cli part search --data '{"pageNum":1,"pageSize":10,"keyWord":"刹车","enable":"1"}'

# 从文件读取
shb-cli part search --file ./search.json
```

**使用优先级：快捷 flags ＞ `--data` ＞ `--file`**——常规筛选直接用快捷 flags；需要完整或复杂 JSON（如 `productTypeList`、时间范围）时用 `--data`；`--file` 仅在本地已有现成 JSON 文件时用。

## 支持的搜索字段（JSON body，字段名为 SparepartSearchModelDTO）

| 字段 | 类型 | 说明 |
|------|------|------|
| `keyWord` | string | 关键字模糊搜索（**注意大写 W**，写成 `keyword` 会被后端静默忽略、不过滤） |
| `name` | string | 备件名称 |
| `type` | string | 备件类型 |
| `standard` | string | 规格，模糊匹配 |
| `description` | string | 说明，模糊匹配 |
| `enable` | string | 启用状态：`"1"` 启用 / `"0"` 停用 |
| `productTypeList` | string[] | 关联产品目录类型 ID 数组 |
| `pageNum` | int | 页码，**从 1 开始**（默认 1） |
| `pageSize` | int | 每页条数，0 表示查全量 |
| `timeStart` / `timeEnd` | string | 创建时间范围，格式 `yyyy-MM-dd HH:mm:ss` |
| `sortBy` | object | 排序，`{字段名: true\|false}`，`true` 为升序 |
| `ids` | string[] | 按指定备件 id 列表过滤 |
| `labelQuery` | object | 智能标签过滤，`{"labelIds": number[]\|null, "labelExists": boolean\|null}`。只能通过 `--data`/`--file` 传入，无对应快捷 flag。详见 [`../../shb-label/SKILL.md`](../../shb-label/SKILL.md) |

### 按标签过滤（智能标签）

标签过滤走 `--data`（无快捷 flag），传入 `labelQuery`。**先读 [`../../shb-label/SKILL.md`](../../shb-label/SKILL.md)**——查 labelId、`labelQuery` 字段含义都在那份文档里，这里只给备件场景的示例：

```bash
shb-cli part search --data '{"keyWord":"刹车","labelQuery":{"labelIds":[12345,67890]}}'
```

> **flag 名与 JSON 字段名的对应**：快捷 flag 用**短横线**命名，`--data` 里的 JSON 用**驼峰**命名。对照：`--page`↔`pageNum`、`--page-size`↔`pageSize`、`--keyword`↔`keyWord`（注意大写 W）、`--name`↔`name`、`--type`↔`type`、`--enable`↔`enable`。

## 获取全量数据：决策规则

**全量请求的处理顺序（`--all` 每个查询条件最多执行一次，别重复拉）：**

- **能判断数据量不大（≤500）**——按名称 / 按类型 / 按启用状态的日常查询多属此类——**直接执行一次 `--all`** 拿齐即可，**无需先探量**（`--all` 自带总数与全部数据）。
- **不确定是否会超过 500**——先用 `--page-size 1` 探一次 `total`，再判断：`total ≤ 500` 用 `--all`，`total ≥ 501` 改分页叠加。

> **`--all` 用法要点：**
> - **必须 `--format-data --fields <少数列>` 两者一起**才能收窄输出，否则接口原始响应含全部字段容易被截断。
> - **每个查询条件最多执行一次**：`--all` 已遍历所有页、返回完整结果与总数，不要再补跑分页或再次 `--all`。

## --format-data 输出结构速查

`--format-data -o raw` 返回：

```json
{
  "page":    {"page": 1, "pageSize": 10, "totalElements": 30, "totalPages": 3},
  "columns": [{"field": "serialNumber", "label": "编号"}, ...],
  "rows":    [{"serialNumber": "SP-001", "name": "刹车片", "salePrice": "99.50", "enable": "启用", ...}, ...]
}
```

不加 `--fields` 时默认输出字段：`serialNumber`（编号）、`name`（名称）、`type`（类型）、`standard`（规格）、`unit`（单位）、`salePrice`（销售价格，两位小数）、`costPrice`（成本价格，两位小数）、`enable`（启用状态，中文）、`createTime`（创建时间）。

其余可选字段：`id`（内部 ID，一般无需展示给用户）、`description`（说明）、`productTypeList`（关联产品类型，逗号分隔的名称串）。

## 注意

- `part search` 默认输出原始响应（裸 PageInfo：`{pageNum, pageSize, total, pages, list}`，**没有** status/data 信封）；需要字段文案和值格式化时显式传 `--format-data`。
- 搜索结果为空时，检查 `enable`、`type` 等筛选条件是否匹配当前租户下实际存在的值。
- **统计需求优先用计数查询**：只需要总数时用 `--page-size 1` 取 `page.totalElements`，不要为了数数把全量明细拉进来。