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

# shb-cli task field

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

## 查询字段

```bash
# 查询某个工单类型的主表字段（tableName 默认 task）
shb-cli task field list --type-id <templateId>

# 显式查询主表字段
shb-cli task field list --type-id <templateId> --table-name task

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

# 不传 type-id 时查询全部类型范围内字段
shb-cli task field list
```

## 查询公共字段

```bash
# 查询某个工单类型的公共字段
shb-cli task field common --type-id <templateId>

# table-name 默认 all
shb-cli task field common --type-id <templateId> --table-name all

# 不传 type-id 时查询全局公共字段
shb-cli task field common
```

## 字段含义

常见字段元数据：

| 字段 | 说明 |
|------|------|
| `fieldName` | 字段 key，`--fields` 和 JSON payload 中通常使用它 |
| `displayName` / `label` / `name` | 字段文案 |
| `formType` / `type` | 字段类型，如 text、select、user、date、address |
| `isSystem` / `system` | 是否系统字段 |
| `isNull` | 是否允许为空：`0` 必填，`1` 非必填 |
| `show` | 是否展示 |
| `orderId` / `sort` | 排序 |
| `setting` | 字段配置，如选项、校验规则等 |

## 典型使用场景

### 创建工单前确认字段

```bash
# 1. 查询可创建的工单类型
shb-cli task type list --list-type writeList -o raw | jq '.[] | {id, name}'

# 2. 查询目标类型字段
shb-cli task field list --type-id <templateId> -o raw | jq '.[] | {fieldName, displayName, formType, isSystem, isNull}'

# 3. 查询回执字段
shb-cli task field list --type-id <templateId> --table-name task_receipt
```

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

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

# 再传给 --fields
shb-cli task search --template-id <templateId> --format-data --fields taskNo,state,customer,executorName,createTime -o table
```

## 注意

- **向用户展示或询问字段时，默认只用字段文案（`displayName`/`label`）**：`fieldName`（英文字段 key，如 `serviceType`）仅供你内部拼 `--fields`/JSON payload 用。除非用户**明确要求**查看字段名，否则不要把 `fieldName` 输出给用户——给用户的应是「服务类型」这类可读文案，而非 `serviceType`。
- `type-id` 即工单类型 ID / `templateId`。
- `field list` 的 `--table-name` 推荐只使用 `task` 或 `task_receipt`。
- `field common` 的 `--table-name` 默认是 `all`。
- 字段返回数据为当前用户在当前租户下可见范围。