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

# shb-cli event field

事件字段查询。用于在搜索/详情格式化输出前确认字段 key、字段文案、字段类型和是否系统字段。

## 查询字段

```bash
# 查询某个事件类型的事件表单字段（table-name 默认 event）
shb-cli event field list --type-id <templateId>

# 查询回执字段
shb-cli event field list --type-id <templateId> --table-name event_receipt

# 不传 type-id 时只返回一个很小的通用兜底字段集（不是"全部类型字段"，与工单 field list 不同）
shb-cli event field list
```

返回结构：一个字段对象数组：

```json
[
  {"fieldName": "...", "displayName": "...", "formType": "...", "isSystem": 1, "setting": {...}},
  ...
]
```

## 字段含义

常见字段元数据（EventTemplateVO）：

| 字段 | 说明 |
|------|------|
| `fieldName` | 字段 key，`--fields` 和 JSON payload（`conditions.property`）中通常使用它 |
| `displayName` | 字段文案（中文） |
| `formType` | 字段类型，如 text、textarea、number、select、cascader、user、date、datetime、phone、email、address、level（优先级）、customer、eventNo、formula 等 |
| `isSystem` | 是否系统字段 |
| `setting` | 字段配置；select/level 类型的枚举选项在 `setting.dataSource`，多语言文案在 `setting.dataSourceLanguage` |

> select/level 类型字段的选项 value 本身就是中文文本，格式化输出时一般无需再做值转换。

### `--format-data` 额外补充的系统字段

`event field list` 只返回该事件类型**可配置的表单字段**，不包含 `executorName`（负责人）、`synergies`（协同人）、`state`（状态）、`createUserName`（创建人）、`createTime`（创建时间）、`source`（创建方式）这类固定系统列——这与前端事件详情页（`EventDetailView.vue` 的 `getEventFields`）的行为一致，前端也是额外硬编码补充这些字段。

`event search --format-data` / `event detail --format-data` 已经在 CLI 内部自动补上这些系统字段（连同 `eventNo`/`cusName`/`lmName`/`lmPhone`/`completeTime`/`degree`/`updateTime`/`productId`/`taskNo`），**不需要你再手动拼接**；只有直接查看 `event field list` 原始输出时才不会看到它们。

## 典型使用场景

### 给格式化输出选择字段

```bash
# 先确认字段 key
shb-cli event field list --type-id <templateId> -o raw | jq -r '.[].fieldName'

# 再传给 --fields
shb-cli event search --template-id <templateId> --format-data --fields eventNo,state,cusName,executorName,createTime -o table
```

### 按自定义字段搜索前确认字段 key

```bash
shb-cli event field list --type-id <templateId> -o raw | jq '.[] | {fieldName, displayName, formType}'
```

再用该 `fieldName` 拼 `conditions`（见 [`shb-event-search.md`](shb-event-search.md) 的「自定义字段条件」）。

## 注意

- **向用户展示或询问字段时，默认只用字段文案（`displayName`）**：`fieldName`（英文字段 key，如 `field_priority`）仅供你内部拼 `--fields`/`conditions` 用。除非用户**明确要求**查看字段名，否则不要把 `fieldName` 输出给用户。
- `type-id` 即事件类型 ID / `templateId`。**留空不会返回全部类型的字段**，只返回一个通用兜底字段集——按具体类型查字段时务必传 `--type-id`。
- `field list` 的 `--table-name` 只接受 `event`（默认）或 `event_receipt`。
- 字段返回数据为当前用户在当前租户下可见范围。