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

# shb-cli customer field

查询客户表单的字段定义列表，用于了解客户模块可用字段、字段类型、是否必填，以及创建/编辑客户时自定义字段的 `fieldName`。

> **用户问「有哪些字段/字段列表」时，只回答字段清单**——用表格列出各字段的**显示名**（可附类型、是否必填），到此为止。**不要**顺带输出 `--name`/`--attr` 等参数，也**不要**讲「创建/编辑时怎么传」——那是创建场景才需要的（见 [`shb-customer-create.md`](./shb-customer-create.md)），用户没问就不要带出来。下文「与 customer create 的配合」一节仅供你**创建客户时**内部参考，不是回答「有哪些字段」的内容。

## 基础用法

```bash
# 查询客户字段定义（默认视角）
shb-cli customer field list

# 从设置页视角查询（包含更多配置信息）
shb-cli customer field list --from-setting

# 表格展示
shb-cli customer field list -o table
shb-cli customer field list --from-setting -o table
```

## 完整 Flags

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--from-setting` | 从设置页视角获取字段（含更多配置项） | false |

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

| 列 | 说明 |
|----|------|
| 字段名 | `fieldName`，创建/编辑时作为 key 使用 |
| 显示名 | 界面上展示的名称 |
| 类型 | 表单控件类型（text, select, date 等） |
| 必填 | 是/否 |
| 系统字段 | 是（isSystem=1）/否（isSystem=0） |
| 排序 | 显示顺序 |

## 与 customer create 的配合

> 仅在**创建/编辑客户**时参考；用户只是问「有哪些字段」时不要引用本节、不要输出下面这些参数。

系统字段（`isSystem=1`）通过 `customer create` 的快捷 flags 传入：

| fieldName | 对应 flag |
|-----------|-----------|
| name | `--name` |
| lmPhone | `--lm-phone` |
| lmEmail | `--lm-email` |
| lmName | `--lm-name` |
| serialNumber | `--serial-number` |
| customerManager | `--manager-id` |

自定义字段（`isSystem=0`）通过 `--attr` 以 JSON 对象传入：

```bash
# 查字段列表
shb-cli customer field list -o raw

# 创建时传入自定义字段
shb-cli customer create \
  --name "某客户" \
  --lm-phone "13800000000" \
  --attr '{"industry":"制造业","customerLevel":"A级"}'
```

## 注意

- **向用户展示或询问字段时，默认只用字段的「显示名」**：`fieldName`（英文字段名，如 `customerLevel`）仅供你内部拼 `--attr`/JSON 用。除非用户**明确要求**查看字段名，否则不要把 `fieldName` 输出给用户——给用户的应是「客户等级」这类可读显示名，而非 `customerLevel`。
- 此接口返回的字段定义不因客户 ID 不同而变化（全局统一字段配置）。
- `formType=customer` 类型的字段在工单创建中有特殊意义，其 `setting.customerOption` 控制是否需要填写产品、地址、联系人等关联信息。