---
name: shb-task
version: "1.5.0"
description: "当用户提到工单相关操作时触发，包括：搜索/查询/查看工单列表或详情、我的工单/我创建的工单/分配给我的工单/属于我的工单、某状态下的工单、某客户的工单、按执行人/创建人/时间筛选工单、按服务类型/创建方式/异常标记/里程/自定义字段等条件高级搜索工单、创建工单、更新/修改/编辑工单、派发/分配/指派工单、查询工单类型或字段、查询工单回访/满意度/客户评价/回访状态/回访动态/满意度问卷。通过 shb-cli 操作工单列表搜索、格式化数据、详情查看、类型列表、字段查询、工单创建、工单更新、工单派发和回访满意度查询。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli task --help"
---

# task (v1.5)

**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../shb-shared/SKILL.md`](../shb-shared/SKILL.md)，其中包含 profile 初始化、环境选择、OAuth2 登录、token 导入、租户切换、安全规则。所有 Task 命令都依赖 `shb-shared` 描述的认证状态。**

## Core Concepts

- **Task（工单）**：售后宝 工单系统中的工单实例，标识为 `id`（UUID）。
- **Template / TaskType（工单类型）**：工单类型模板，标识为 `templateId` / `id`。
- **Field（工单字段）**：工单主表或回执表字段定义，常用来确定 `fieldName`、字段文案、类型、是否系统字段。
- **State（状态）**：工单当前状态。过滤（`state` 字段 / `--state`）时只能传下表英文 `value`（**不是中文、不是其它拼写**），展示给用户时转成中文标签：

  | value | 中文标签 |
  |-------|---------|
  | `created` | 待指派 |
  | `allocated` | 已指派 |
  | `accepted` | 已接受 |
  | `processing` | 进行中 |
  | `finished` | 已完成 |
  | `refused` | 已拒绝 |
  | `costed` | 已结算 |
  | `closed` | 已关闭 |
  | `offed` | 已取消 |
  | `taskPool` | 工单池 |

  用户说「待处理/未派/派给我的」等口语时，按语义映射到上表 value（如「待指派」→ `created`、「进行中/处理中」→ `processing`），拿不准就向用户确认，**不要臆造表中没有的 value**。
- **Executor（执行人）**：
  - 搜索过滤时用 JSON body 字段 `executor`（值为 userId）——**不是 `executorId`**
  - 派单时用 flag `--executor-id <userId>` 或 JSON body 字段 `executorId`
- **高级搜索条件（`systemConditions` / `conditions`）**：顶层快捷字段覆盖不到的过滤维度（服务类型、创建方式、异常标记、里程、各类时间、自定义字段…），以及需要 `in` / `between` / `like` / 不等于等操作符时，走这两个数组——即 PC 端「高级搜索」提交的参数，只能通过 `--data` / `--file` 传，**没有快捷 flag**。系统字段（`isSystem=1`）放 `systemConditions`，自定义字段（`isSystem=0`，`field_xxx`）放 `conditions`；放错数组后端不报错、直接空结果。字段归属、`property` 命名对照、操作符与值格式见 [`references/shb-task-search.md`](references/shb-task-search.md)。
- **Approval（审批）**：创建和派单默认先检查是否需要审批；需要审批时命令会输出审批信息并停止，不会继续执行写入。
- **Formatted Data（格式化数据）**：把列表原始字段转换为 `columns + rows`，字段文案来自字段元数据，字段值转为人类可读文案。
- **工单类型列表**：接口返回三组：`writeList`（可创建）、`readList`（可查看）、`notEnableList`（已禁用）。
- **Review（回访）**：工单完成后的满意度回访，分两套模型，用 `reviewType` 区分，二者的过滤参数与输出列**互斥**：

  | reviewType | 名称 | 状态过滤参数 | 取值 |
  |---|---|---|---|
  | `1` | 人工回访 | `--is-review` | `0` 未回访 / `1` 已回访 / `2` 全部 / `3` 跟进中 / `5` 指派给我 |
  | `2` | 自动回访（客户评价） | `--is-evaluate` | `0` 未评价 / `1` 已评价 / `2` 全部 |

  回访状态是**三态**（`已回访` / `未回访` / `跟进中`），不要当布尔处理。满意度 `degree` 只接受五个中文值：`非常满意` / `满意` / `一般` / `不满意` / `非常不满意`。
- **满意度问卷**：部分租户的满意度是一张自定义表单，每个工单类型有各自的题目列表。此时回访列表里的满意度/服务标签列被问卷题目取代，答案落在工单的自定义字段里；CLI 用 `review search --format-data`（配合 `--template-id`）自动把题目转成中文列。未启用问卷的租户走旧的星级评价（`starEvaluate*`）+ 满意度 + 服务标签模型。

## Important Notes

### 面向用户的输出措辞（禁止回显接口字段名与内部机制）

**CRITICAL** — 以下两类内容**只供你内部使用，禁止出现在给用户的回复里**：

1. **接口/JSON 字段名**：`totalElements`、`page`、`rows`、`taskNo`、`templateId`、`state` 等，一律转成自然语言。例：「totalElements 为 189」→「共 189 条工单」；「state=processing」→「进行中」。
2. **命令与一切技术细节**：任何 shb-cli 命令、子命令、flag、参数名，以及取数过程（分页、数量判断、全量拉取、字段裁剪、截断重试）都是后台实现细节，**回复里绝不出现，也不要解释你用了什么命令/参数、怎么取的数**，换种说法也不行。直接给结果。
3. **自定义字段（`attribute`）的显示**：`attribute` 对象的 key 是 `fieldName`（如 `field_xxx`），**绝不能直接拿这个 key 显示给用户**。展示前用 `task field list --type-id <templateId>` 取字段定义，按 `fieldName` 匹配出对应的 `displayName`（中文字段名），给用户看「中文字段名：值」；匹配不到的字段宁可不展示，也不要把英文 key 抛给用户。用 `--format-data` 输出时 CLI 已按字段元数据转换，一般无需自行映射。

正例：「你名下共有 18 条工单：自己创建 13 条、被分配 5 条。下面是详细分析……」。

此规则适用于所有 task 子命令（search / detail / type / field / create / alloc / update）。

### 复用已知 ID（禁止重复搜索）

**CRITICAL** — 只要本轮对话的任意一次 search/list 结果里出现过某工单的 `id`，后续用户再提到该工单（无论通过 taskNo、关键字还是描述），**必须从已有结果中匹配出 id 直接使用**，禁止再发起 `task search --keyword <taskNo>` 来"重新获取 id"。  
例：刚查过"最近30天工单列表"，列表里有 `taskNo=WO-001, id=xxx`，用户说"帮我看 WO-001 详情"→ 直接用 `xxx`，不再 search。  
只有当前对话中从未出现该工单时才允许发起新搜索。

### 命令分层

- **`shb-cli task <subcommand>`** —— 工单模块的主入口，推荐路径。
- **`shb-cli task task-search`** / **`shb-cli task task-detail`** —— 高级快捷入口；当前只覆盖搜索和详情。

### 输出格式

所有命令支持全局 `--output` / `-o` 标志：

```bash
shb-cli task search -o json          # 默认，完整 pretty JSON
shb-cli task search -o raw           # 紧凑单行 JSON，适合 jq 管道
shb-cli task search -o yaml          # YAML 格式
shb-cli task search --format-data -o table   # 字段文案和值均格式化后的表格
```

### 写操作安全

- `task create submit`、`task alloc submit` 和 `task update submit` 是写操作；执行前确认用户明确要求创建/派发/更新。
- 默认不要加 `--no-approve`。该标志会跳过审批检查并直接执行写操作，只在用户明确要求或已确认风险时使用。
- 若命令输出 "Approval required" / "VIP Approval required"，表示后端要求审批，命令已停止，下一步应把审批信息反馈给用户。
**使用优先级：快捷 flags ＞ `--data` ＞ `--file`**——常规字段用快捷 flags；复杂字段（附件、产品、自定义 attribute、嵌套结构等）用 `--data` 内联；`--file` 仅本地已有现成 JSON 文件时用。   

## API Resources

**CRITICAL — 执行任何 task 子命令前，必须先用 skill 工具加载对应 reference 文档，再执行命令：**

| 操作 | 必须先加载 |
|------|-----------|
| 搜索工单（`task search` / `task task-search`） | [`references/shb-task-search.md`](references/shb-task-search.md) |
| 查看工单详情（`task detail` / `task task-detail`） | [`references/shb-task-detail.md`](references/shb-task-detail.md) |
| 查询工单类型（`task type list`） | [`references/shb-task-type.md`](references/shb-task-type.md) |
| 查询工单字段（`task field list/common`） | [`references/shb-task-field.md`](references/shb-task-field.md) |
| 创建工单（`task create submit`） | [`references/shb-task-create.md`](references/shb-task-create.md) |
| 派发/分配工单（`task alloc submit`） | [`references/shb-task-alloc.md`](references/shb-task-alloc.md) |
| 更新工单（`task update submit`） | [`references/shb-task-update.md`](references/shb-task-update.md) |
| 查询回访/满意度（`task review search/init/fields/dynamic`） | [`references/shb-task-review.md`](references/shb-task-review.md) |

同一会话中每个 reference 只需加载一次。

## 权限与安全

- 只读命令：`search`、`detail`、`type list`、`field list`、`field common`、`review search`、`review init`、`review fields`、`review dynamic`。
- 回访相关能力**仅只读**：CLI 不支持提交回访、暂存回访与发送回访短信，用户提出这类需求时请说明需到 PC 端操作。
- 写命令：`create submit`、`alloc submit`、`update submit`。不要在未确认用户意图时执行。
- 可见和可写范围 = 当前 profile 用户在 SHB 后端的权限范围。

## 排错

- 404 / `No message available` —— 通常是请求路径或环境不匹配，用 `shb-cli version --json` 确认 `build_env`，再用 `shb-cli config` 确认当前环境和 base URL。
- 401 / `token is empty` / `valid: false` → 回到 `shb-shared` 技能重新认证。
- `--template-id is required` / `--task-id is required` / `--executor-id is required` → 快捷 flags 模式缺少必填字段；也可改用 `--data` / `--file` 提供完整 JSON。
- 更新工单时 `500002 系统错误` → 检查请求体中 `task.attribute` 是否存在（不能为 null，最少传 `{}`）。
- 高级搜索条件查出 0 条 → 依次核对：字段是否放对数组（`task field list --type-id <templateId>` 看 `isSystem`）、`property` 是否按对照表转换（如负责人 `in` 用 `executorUser`、`eq` 用 `executor`）、操作符与值字段是否配套（`in` 配 `inValue`、`between` 配 `betweenValue1/2`）、时间是否用 `yyyy-MM-dd HH:mm:ss`、人员/客户是否传的 id 而非姓名。详见 [`references/shb-task-search.md`](references/shb-task-search.md)。
- 创建字段不确定 → 先用 `task type list --list-type writeList` 找类型，再用 `task field list --type-id <templateId>` 查字段。
- `task review search` 结果为空 → 先用 `task review init` 确认该**租户**是否启用了对应回访（`reviewOn` / `autoReviewOn` 是租户级开关，不是逐工单类型的），再检查 `--review-type` 与状态过滤是否配套（`--is-review` 只在 `--review-type 1` 下生效）。`review init` 的工单类型列表只是回访列表的筛选项，**不代表这些类型都开了回访，也区分不出人工/自动**。
- 回访输出里问卷题目没有中文名（只见 `field_xxx`）→ 多半是没传 `--template-id`，或该租户走的是旧星级评价模型（此时用 `task review fields --template-id <id>` 验证：返回为空即旧模型）；可用 `--survey-mode on|off` 强制切换列集。

## References

- [`references/shb-task-search.md`](references/shb-task-search.md) —— 工单搜索
- [`references/shb-task-detail.md`](references/shb-task-detail.md) —— 工单详情查询
- [`references/shb-task-type.md`](references/shb-task-type.md) —— 工单类型查询
- [`references/shb-task-field.md`](references/shb-task-field.md) —— 工单字段查询
- [`references/shb-task-create.md`](references/shb-task-create.md) —— 工单创建
- [`references/shb-task-alloc.md`](references/shb-task-alloc.md) —— 工单派发/分配
- [`references/shb-task-update.md`](references/shb-task-update.md) —— 工单更新
- [`references/shb-task-review.md`](references/shb-task-review.md) —— 工单回访/满意度查询