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

# shb-cli product field

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

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

## 基础用法

```bash
# 查询产品字段定义（默认视角）
shb-cli product field list

# 从设置页视角查询
shb-cli product field list --from-setting

# 包含关联客户字段
shb-cli product field list --related-customer

# 包含目录/分类相关字段
shb-cli product field list --catalog-flag

# 表格展示
shb-cli product field list -o table
```

## 完整 Flags

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--from-setting` | 从设置页视角获取字段 | false |
| `--related-customer` | 包含关联客户字段 | false |
| `--catalog-flag` | 包含目录/分类相关字段 | false |

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

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

## 与 product create 的配合

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

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

| fieldName | 对应 flag |
|-----------|-----------|
| name | `--name` |
| serialNumber | `--serial-number` |
| type | `--type` |
| customerId | `--customer-id` |
| templateId | `--template-id` |
| catalogId | `--catalog-id` |

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

```bash
# 查字段名
shb-cli product field list -o table

# 创建时传入自定义字段
shb-cli product create \
  --name "某设备" \
  --attr '{"color":"蓝色","power":"220V"}'
```

## 注意

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