> **前置条件** — 执行前请先确认已完成认证（参见 [`../../shb-shared/SKILL.md`](../../shb-shared/SKILL.md)）。输出措辞禁令、id 复用规则、传参优先级见本 skill 的 [`SKILL.md`](../SKILL.md)。

# shb-cli warehouse material search（物料列表搜索）

云仓物料列表查询。详情查询见 [`shb-warehouse-material-detail.md`](shb-warehouse-material-detail.md)，字段定义见 [`shb-warehouse-material-field.md`](shb-warehouse-material-field.md)，创建/编辑/删除等写操作先读 [`shb-warehouse-material-mutation-common.md`](shb-warehouse-material-mutation-common.md)。

## 快捷 flag 方式（推荐）

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

# 按编号搜索
shb-cli warehouse material search --sn <物料编号>

# 按名称搜索
shb-cli warehouse material search --name <物料名称>

# 按属性/类型/规格筛选
shb-cli warehouse material search --property <属性> --type <类型> --standard <规格>

# 只看启用中的物料
shb-cli warehouse material search --material-status true

# 按创建时间范围筛选
shb-cli warehouse material search --create-time-start "2026-01-01 00:00:00" --create-time-end "2026-06-30 23:59:59"

# 分页
shb-cli warehouse material search --page 1 --page-size 20

# 组合使用
shb-cli warehouse material search --keyword "螺丝" --material-status true --page-size 20

# 格式化数据输出：字段文案和值都会转换为可读内容，可用 --fields 指定字段
shb-cli warehouse material search --keyword "螺丝" --format-data --fields sn,name,property,unit,materialStatus,salePrice,costPrice

# 获取全量数据：仅当用户明确要求"全部/所有/全量"数据时才加 --all
shb-cli warehouse material search --material-status true --all --format-data --fields sn,name,materialStatus
```

## 完整 JSON body 方式

```bash
# 内联 JSON （推荐）
shb-cli warehouse material search --data '{"pageNum":1,"pageSize":10,"keyword":"螺丝","materialStatus":true}'

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

需要完整或复杂 JSON（如 `conditions`、`catalogIds`、`labelQuery`、`formValueConditions` 等高级字段）时用 `--data`。

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

| 字段 | 类型 | 说明 |
|------|------|------|
| `keyword` | string | 关键字模糊搜索 |
| `sn` | string | 物料编号 |
| `snList` | string[] | 按物料编号列表过滤 |
| `excludeSnList` | string[] | 排除指定物料编号 |
| `name` | string | 物料名称，模糊匹配 |
| `property` | string | 物料属性 |
| `description` | string | 说明，模糊匹配 |
| `unit` | string | 单位 |
| `standard` | string | 规格 |
| `type` | string | 物料类型 |
| `snManage` | string | SN 管理：`"是"`/`"否"` |
| `forSale` | string | 是否销售：`"是"`/`"否"` |
| `materialStatus` | bool | 启用状态：`true` 启用 / `false` 停用（**布尔值，不是字符串**） |
| `costPrice`/`depositPrice`/`channelPrice`/`salePrice` | string | 价格过滤 |
| `createTimeStart`/`createTimeEnd` | string | 创建时间范围，`"yyyy-MM-dd HH:mm:ss"` |
| `createUser` | string[] | 创建人用户 id 列表 |
| `bomSn` | string | BOM 编号 |
| `batchNumManage` | int | 批次管理标记 |
| `isPeriodManage` | int | 期效管理标记 |
| `productTypeId` | int | 关联产品目录类型 id |
| `catalogIds` | int[] | 产品目录 id 过滤 |
| `ids` | int[] | 按指定物料 id 过滤 |
| `pageNum` | int | 页码，**从 1 开始**（默认 1） |
| `pageSize` | int | 每页条数（默认 10） |
| `conditions`/`labelQuery`/`formValueConditions` | object | 高级筛选条件，仅通过 `--data`/`--file` 传，无专用 flag |

> **flag 名与 JSON 字段名的对应**：快捷 flag 用**短横线**命名，`--data` 里的 JSON 用**驼峰**命名。对照：`--page`↔`pageNum`、`--page-size`↔`pageSize`、`--keyword`↔`keyword`、`--sn`↔`sn`、`--material-status`（`true`/`false` 字符串）↔`materialStatus`（JSON 布尔）、`--create-time-start`/`--create-time-end`↔`createTimeStart`/`createTimeEnd`。

> `tenantId`/`searchUserId` 由服务端根据当前登录用户自动注入，**不需要也不能**在请求里传，结果口径与用户在网页看到的一致。

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

**CRITICAL — 默认不要用 `--all`。** 用户没有明确要求"全部/所有/全量"数据时，一律走默认分页（或按需 `--page-size`），只返回用户关心的那一部分——多数"查一下""看看有哪些""搜索 xxx"类请求，返回默认第一页即可满足，不要主动升级成全量拉取。

- **用户明确要求全部/所有/全量数据**（或需要精确统计需要遍历所有页）时才使用 `--all`：
  - **能判断数据量不大（≤500）**——直接执行一次 `--all` 拿齐即可，**无需先探量**（`--all` 自带总数与全部数据）。
  - **不确定是否会超过 500**——先用 `--page-size 1` 探一次 `total`，再判断：`total ≤ 500` 用 `--all`，`total ≥ 501` 改分页叠加。
  - **每个查询条件最多执行一次**：`--all` 已遍历所有页、返回完整结果与总数，不要再补跑分页或再次 `--all`。
  - **必须 `--format-data --fields <少数列>` 两者一起**才能收窄输出，否则接口原始响应含全部字段容易被截断。
- **只需要总数（不需要明细）**：用 `--page-size 1` 取 `page.totalElements` 即可，不要用 `--all` 把明细也拉下来。
- **用户只是想看看/搜一下，没提"全部"**：用默认分页（或加 `--page-size` 适度调整条数），不要自作主张加 `--all`；如结果被截断或用户后续追问"还有别的吗"，再考虑翻页或改用 `--all`。

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

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

```json
{
  "page":    {"page": 1, "pageSize": 10, "totalElements": 30, "totalPages": 3},
  "columns": [{"field": "sn", "label": "物料编号"}, ...],
  "rows":    [{"sn": "M-001", "name": "螺丝", "property": "整机", "unit": "个", "materialStatus": "启用", "salePrice": "15.00", "costPrice": "8.50", "createTime": "2026-01-10 10:00:00", ...}, ...]
}
```

不加 `--fields` 时默认输出字段：`sn`（物料编号）、`name`（名称）、`property`（属性）、`unit`（单位）、`materialStatus`（启用状态）、`salePrice`（终端销售价）、`costPrice`（成本价）、`createTime`（创建时间）。

其余可选字段：`id`（物料内部 ID，整数）、`standard`（规格）、`type`（类型）、`description`（说明）、`snManage`（SN 管理）、`forSale`（是否销售）、`depositPrice`（押金价）、`channelPrice`（渠道价）、`batchNumManage`（批次管理）、`isPeriodManage`（期效管理）、`shelfLife`（保质期）、`createUserName`（创建人）、`updateTime`（更新时间）、`catalogNameJoin`（关联产品目录）。

### 字段说明

- `materialStatus` 是 JSON 布尔值，`--format-data` 转换为「启用」/「停用」中文展示；用 `--material-status` 过滤时传字符串 `true`/`false`（会被转换为 JSON 布尔），不要传 `1`/`0`。
- 价格字段（`salePrice`/`costPrice`/`depositPrice`/`channelPrice`）原始为字符串，`--format-data` 统一格式化为两位小数。
- 响应本身带 `{success,code,message,data}` 信封，`--format-data` 已自动解包出 `data`（即 `PageInfo`），无需关心信封细节。

## 典型组合场景

### 查所有已停用的物料

```bash
shb-cli warehouse material search --material-status false --all --format-data \
  --fields sn,name,property,materialStatus
```

## 注意

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