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

# shb-cli task detail

工单详情查询。返回指定工单的完整信息，包含表单字段内容、流程节点、执行人等。

## ⚠️ 响应结构速查（必读，避免反复探测）

`-o raw` 返回顶层结构为 `{title, initJson}`，**工单数据全部在 `.initJson.task` 下**，顶层没有 `taskNo`/`state` 等字段。

**标准一条命令取所有常用字段（直接复用，不要先 `jq '.'` 再逐字段摸索）：**

```bash
shb-cli task detail --id <taskId> -o raw | jq '.initJson.task | {taskNo, state, templateName, description, tlmName, tlmPhone, taddressStr, customer: .customer.name, executor: .executor.displayName, createUser: .createUser.displayName, createTime, planStartTime, planEndTime}'
```

如需探索不确定的字段，先存文件再查，**不要重复请求接口**：

```bash
shb-cli task detail --id <taskId> -o raw > /tmp/task.json
jq '.initJson.task | keys' /tmp/task.json      # 看所有可用 key
jq '.initJson.task.<fieldName>' /tmp/task.json  # 按需取值
```

---

## 获取工单详情

```bash
shb-cli task detail --id <taskId>
```

`--id` 为工单的系统唯一标识（UUID），**不是**工单编号（taskNo）。

### 格式化输出

```bash
shb-cli task detail --id <taskId> --format-data
shb-cli task detail --id <taskId> --format-data --fields taskNo,state,customer,executorName,createTime
shb-cli task detail --id <taskId> --format-data --fields taskNo,state,customer,executorName,createTime -o table
```

`--format-data` 会根据详情里的 `templateId` 加载字段元数据，把字段文案和值整理成 `columns + row`。`--fields` 为逗号分隔的字段 key。

### Shortcut 方式

```bash
shb-cli task task-detail --id <taskId>
```

## 响应内容

`-o raw` 返回的顶层结构是 `{title, initJson}`，**工单数据在 `.initJson.task` 下**（`initJson` 其余 50+ 个 key 是页面配置/按钮权限，查数据时一律忽略）。常用字段路径速查（直接用，不要再探测结构）：

| 数据 | jq 路径 |
|------|---------|
| 工单编号 / 状态 | `.initJson.task.taskNo` / `.initJson.task.state` |
| 工单类型 | `.initJson.task.templateId` / `.templateName` |
| 描述 / 优先级 / 服务类型 | `.initJson.task.description` / `.level` / `.serviceType` |
| **工单联系人** | `.initJson.task | {tlmId, tlmName, tlmPhone}`（前缀 `tlm` = task linkman） |
| **工单地址** | `.initJson.task.taddress`（对象）、`.initJson.task.taddressStr`（字符串） |
| 客户信息 | `.initJson.task.customer | {id, name, lmName, lmPhone}`（`lm*` 是客户默认联系人，≠ 工单联系人） |
| 客户默认地址 | `.initJson.task.customer.customerAddress`（`adProvince`/`adCity`/`adAddress`/`allAddress`） |
| 计划时间 | `.initJson.task.planStartTime` / `.planEndTime`（毫秒时间戳） |
| 执行人 / 创建人 | `.initJson.task.executor` / `.createUser` |
| 自定义字段 | `.initJson.task.attribute`（key 是 `fieldName`，需映射成中文显示名，见下方「注意」） |
| 产品 | `.initJson.task.products` |
| 审批记录 | `.initJson.task.approveInfoList` |

一次查询多个字段的推荐写法（**一条命令拿全，不要逐字段反复调用**）：

```bash
shb-cli task detail --id <taskId> -o raw | jq '.initJson.task | {taskNo, state, templateName, description, customer: .customer.name, linkman: {id: .tlmId, name: .tlmName, phone: .tlmPhone}, address: .taddressStr, planStartTime, planEndTime}'
```

如需多轮探索结构，先把响应存成本地文件再用 jq 反复查，避免每次都重新请求接口：

```bash
shb-cli task detail --id <taskId> -o raw > /tmp/task-detail.json
jq '.initJson.task | keys' /tmp/task-detail.json
```

## 如何获取 taskId

工单详情接口需要传入 `id`（系统 UUID），而非 `taskNo`（工单编号）。

**如果当前对话中已有该工单的 `id`（UUID），直接用，不要再搜索一遍。**  
只有 id 真的未知时才按以下方式获取：

### 方式一：按工单编号搜索

```bash
# 用 taskNo 作为关键字搜索，取第一条结果的 id
shb-cli task search --keyword "WO-20240101" -o raw | jq '.content[0].id'
```

### 方式二：按客户名或关键字搜索

```bash
# 返回 id 和 taskNo 供选择
shb-cli task search --keyword "客户名称" -o raw | jq '.content[] | {id, taskNo}'
```

### 方式三：从工单列表中提取

```bash
# 获取指定类型下所有工单的 id 列表
shb-cli task search --template-id <templateId> --all -o raw | jq '[.content[] | {id, taskNo}]'
```

## 典型组合场景

### 场景一：已知工单编号，查看完整详情

```bash
# 1. 搜索拿到 id
TASK_ID=$(shb-cli task search --keyword "WO-20240601-001" -o raw | jq -r '.content[0].id')

# 2. 查看详情
shb-cli task detail --id "$TASK_ID"
```

---

### 场景二：查看某客户名下最新工单的详情

```bash
# 1. 搜索客户名，按 createTime 找最新工单
shb-cli task search --keyword "客户名称" -o raw | jq '.content | sort_by(.createTime) | reverse | .[0] | {id, taskNo, state}'

# 2. 查看详情
shb-cli task detail --id <id>
```

---

### 场景三：遍历一批工单查看详情

```bash
# 先获取指定类型下所有待处理工单的 id
shb-cli task search --template-id <templateId> --state created --all -o raw \
  | jq -r '.content[].id' \
  | while read id; do
      echo "=== $id ==="
      shb-cli task detail --id "$id" -o raw | jq '.initJson.task | {taskNo, state, executor}'
    done
```

---

### 场景四：查看工单的审批记录

```bash
shb-cli task detail --id <taskId> -o raw | jq '.initJson.task.approveInfoList'
```

---

### 场景五：提取工单自定义字段内容

```bash
shb-cli task detail --id <taskId> -o raw | jq '.initJson.task.attribute'
```

## 注意

- `--id` 必须传工单的系统 UUID，不是工单编号（taskNo）。
- 如果不知道 id，先用 `task search --keyword <taskNo>` 搜索定位。
- 返回数据为当前登录用户在当前租户下可见范围，不同用户可见详情可能不同。
- **自定义字段（`.initJson.task.attribute`）的 key 是 `fieldName`（如 `field_xxx`），绝不能直接拿这个 key 显示给用户**。展示前先用 `task field list --type-id <templateId>` 取字段定义，按 `fieldName` 匹配出对应的 `displayName`（中文字段名），给用户看「中文字段名：值」；匹配不到的字段宁可不展示，也不要把 `field_xxx` 这类英文 key 抛给用户。用 `--format-data` 输出时 CLI 已按字段元数据转换，一般无需自行映射。