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

# shb-cli customer list

> ⚠️ **命令是 `customer list`，不是 `customer search`**。客户模块没有 `search` 子命令，所有搜索操作都通过 `list` 加 flags 完成。

搜索客户列表，支持关键字、编号、状态、联系方式、负责人、创建时间等多维度筛选，分页返回。数据来自 Elasticsearch，近实时。

## 搜索客户列表

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

```bash
# 关键字搜索（名称、编号等）
shb-cli customer list --keyword "某客户"

# 按客户编号精确查找
shb-cli customer list --serial-number "CU-001"

# 只看启用状态的客户
shb-cli customer list --status 1

# 按负责人筛选（传 userId，不是姓名）
shb-cli customer list --customer-manager <userId>

# 按联系人手机/邮箱筛选
shb-cli customer list --lm-phone "138xxxxxxxx"
shb-cli customer list --lm-email "xxx@example.com"

# 按创建时间筛选
shb-cli customer list --create-time-start "2024-01-01T00:00:00" --create-time-end "2024-03-31T23:59:59"

# 分页
shb-cli customer list --page 1 --page-size 20

# 格式化输出
shb-cli customer list --keyword "某客户" -o json
shb-cli customer list --keyword "某客户" -o table
```

### 完整 JSON body 方式

用 `--data`（内联 JSON）传入完整请求体，可使用所有搜索字段（适合快捷 flags 表达不了的复杂筛选）：

```bash
# 内联 JSON
shb-cli customer list --data '{"keyword":"某客户","pageNum":1,"pageSize":20}'

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

**使用优先级：快捷 flags ＞ `--data` ＞ `--file`**——常规筛选用快捷 flags；复杂/完整 JSON 用 `--data`；`--file` 仅本地已有现成 JSON 文件时用。

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

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

```bash
shb-cli customer list --data '{"keyword":"南图","labelQuery":{"labelIds":[12345,67890]}}'
```

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

| 字段 | 类型 | 说明 |
|------|------|------|
| `keyword` | string | 关键字搜索（名称、编号等） |
| `keywords` | string[] | 关键字列表，匹配任意一个即可 |
| `ids` | string[] | 按客户 ID 列表批量查询 |
| `status` | int | 客户状态（1=启用，不传=不过滤） |
| `createUser` | string | 创建人用户 ID。**字段名是 `createUser`，不是 `creatorId` / `creator`** |
| `customerManager` | string | 客户负责人用户 ID。**字段名是 `customerManager`，不是 `managerId` / `manager`** |
| `serialNumber` | string | 客户编号精确匹配 |
| `serialNumberList` | string[] | 客户编号列表 |
| `lmPhone` | string | 联系人手机号 |
| `lmEmail` | string | 联系人邮箱 |
| `createTimeStart` | string | 创建时间起始（ISO 8601） |
| `createTimeEnd` | string | 创建时间截止（ISO 8601） |
| `updateTimeStart` | string | 更新时间起始（ISO 8601） |
| `updateTimeEnd` | string | 更新时间截止（ISO 8601） |
| `labelQuery` | object | 智能标签过滤，`{"labelIds": number[]\|null, "labelExists": boolean\|null}`。只能通过 `--data`/`--file` 传入，无对应快捷 flag。详见 [`../../shb-label/SKILL.md`](../../shb-label/SKILL.md) |
| `pageNum` | int | 页码，**从 1 开始**（默认 1，不是 0） |
| `pageSize` | int | 每页条数（默认 10） |

人员类过滤字段一律传 userId，不要传姓名。当前登录用户的 userId 可通过 `shb-cli config` 查看（chat 场景下系统上下文已提供）。

## 典型组合场景

### 场景一：关键字搜索客户

```bash
shb-cli customer list --keyword "南图" -o json
```

---

### 场景二：查询我创建的客户

createUser 传当前用户的 userId（不是姓名）：

```bash
shb-cli customer list --data '{"createUser":"<当前用户userId>","pageNum":1,"pageSize":20}' -o json
```

---

### 场景三：查询某负责人名下的客户

customerManager 传负责人的 userId（不是姓名）：

```bash
# 单页预览
shb-cli customer list --data '{"customerManager":"<userId>","pageNum":1,"pageSize":20}' -o json

# 配合状态过滤
shb-cli customer list --data '{"customerManager":"<userId>","status":1}' -o json
```

---

### 场景四：按客户编号列表批量查询

```bash
shb-cli customer list --data '{"serialNumberList":["CU-001","CU-002","CU-003"]}' -o json
```

---

### 场景五：按时间范围查询

时间格式为 ISO 8601（`2024-01-01T00:00:00`）：

```bash
shb-cli customer list --data '{
  "createTimeStart": "2024-01-01T00:00:00",
  "createTimeEnd": "2024-03-31T23:59:59",
  "pageSize": 50
}' -o json
```

---

### 场景六：联合条件搜索

```bash
shb-cli customer list --data '{
  "keyword": "南图",
  "status": 1,
  "customerManager": "<userId>",
  "pageNum": 1,
  "pageSize": 20
}' -o json
```

---

## 注意

- **页码从 1 开始**（不是 0）；JSON body 用 `pageNum`，快捷 flag 用 `--page`，两者含义相同。
- `createUser` / `customerManager` 等人员字段传 userId，不要传姓名；传姓名无效。
- 数据来自 Elasticsearch，近实时；刚创建的客户可能有短暂延迟才出现在搜索结果中。
- **报数量只用真实数字，不要预告计划**：回复里说的条数必须是工具**本次实际返回的条数**或响应里的**总数**，绝不说"数据量可能较大、先展示前 N 条"这类预设话术——更不能出现与实际不符的数字。客户列表分页返回（默认每页 10 条），若总数大于本次返回条数，如实告知"共 X 个客户，当前展示前 N 个，还有更多"，不要让用户误以为这就是全部。
- **客户 `id`（UUID）是内部用的，绝不展示给用户**：列表/格式化输出里带 `id`（形如 `0f384496-…`）列，仅供你内部串联后续调用（如拿到 id 再查地址/联系人）。给用户的回复要把它剔除，只呈现客户名称、客户编号（`serialNumber`，如 `CUS20260605001`）等可读信息。
- 若需要获取特定客户的联系人或地址，需先拿到 `id`，再用 `customer linkman search` / `customer address list`。