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

# shb-cli product search

搜索产品列表，支持关键字、名称、编号、类型、客户、模板等多维度筛选，分页返回。

## 基础用法

```bash
# 搜索产品（默认第 1 页，每页 10 条）
shb-cli product search

# 关键字搜索
shb-cli product search --keyword "设备"

# 按客户筛选
shb-cli product search --customer-id <customerId>

# 按产品编号查找
shb-cli product search --serial-number "P-001"

# 表格展示
shb-cli product search -o table

# 翻页
shb-cli product search --page 2 --page-size 20
```

## 完整 Flags

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--keyword` | 关键字搜索 | — |
| `--name` | 产品名称 | — |
| `--serial-number` | 产品编号 | — |
| `--type` | 产品类型 | — |
| `--customer-id` | 按客户 ID 筛选 | — |
| `--template-id` | 按模板 ID 筛选 | — |
| `--sort` | 排序字段 | createTime |
| `--desc` | 是否降序 | true |
| `--page` | 页码（从 1 开始） | 1 |
| `--page-size` | 每页条数 | 10 |
| `--data` | 完整 JSON body | — |
| `--file` | JSON body 文件路径（最后选择，仅本地已有文件时用） | — |

### 支持的搜索字段（JSON body）

| 字段 | 类型 | 说明 |
|------|------|------|
| `keyword` | string | 关键字搜索 |
| `pageNum` | int | 页码，**从 1 开始**（默认 1） |
| `pageSize` | int | 每页条数，默认 10 |
| `createUser` | string | 创建人名称模糊搜索  **注意当前字段是传人员用户名称**|
| `labelQuery` | object | 智能标签过滤，`{"labelIds": number[]\|null, "labelExists": boolean\|null}`。只能通过 `--data`/`--file` 传入，无对应快捷 flag。详见 [`../../shb-label/SKILL.md`](../../shb-label/SKILL.md) |

当前的的createUser必须传的是用户名称，其余人员类过滤字段一律传 userId, 不要传姓名。当前登录用户的 userId 可通过 `shb-cli config` 查看(chat 场景下系统上下文已提供)。

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

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

```bash
shb-cli product search --data '{"keyword":"设备","labelQuery":{"labelIds":[12345,67890]}}'
```

## 返回字段（表格模式）

| 列 | 说明 |
|----|------|
| ID | 产品唯一标识 |
| 产品名称 | 产品全名 |
| 产品编号 | 业务编号 |
| 产品类型 | 类型文案 |
| 客户 | 关联客户名称 |
| 创建时间 | 档案创建时间 |

## 注意

- 产品列表是**分页**返回的（默认每页 10 条）。回复用户时用自然语言告知**总数**（如"共 128 个产品"，不要回显 `totalElements` 字段名）；若总数大于本次返回条数，必须明确告知"当前只是部分数据（第 1 页），还有更多"，不要让用户误以为这就是全部。需要全部时按 `pageNum` 递增逐页拉取后汇总（产品搜索没有 `--all`）。
- 列表数据来自 Elasticsearch，近实时；刚创建的产品可能有短暂延迟。
- 当工单创建需要产品信息时，先通过此命令找到产品 `id`，再填入工单创建参数的 `products` 数组。