---
name: shb-event
version: "1.1.0"
description: "当用户提到事件相关操作时触发，包括：搜索/查询/查看事件列表或详情、我创建的事件/我负责的事件/我协同的事件、某状态下的事件、某客户的事件、按类型/时间筛选事件、查询事件类型或字段、创建事件、更新/修改/编辑事件。通过 shb-cli 操作事件列表搜索、格式化数据、详情查看、类型列表、字段查询、事件创建和事件更新。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli event --help"
---

# event (v1.1)

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

## Core Concepts

- **Event（事件）**：售后宝 事件系统中的事件实例，标识为 `id`（UUID）；对外展示编号是 `eventNo`。
- **Template / EventType（事件类型）**：事件类型模板，标识为 `templateId` / `id`。
- **Field（事件字段）**：事件表单字段定义，用于确定 `fieldName`、字段文案、字段类型、是否系统字段。通过 `event field list --type-id <templateId>` 获取该类型可配置字段；`executorName`/`synergies`/`state`/`createUserName`/`createTime`/`source` 等固定系统列不在该接口返回范围内，但 `--format-data` 已自动补上，无需手动处理。
- **State（状态）**：事件当前状态。过滤（`state` 字段 / `--state`）时只能传下表英文 `value`（**不是中文、不是其它拼写**），展示给用户时转成中文标签：

  | value | 中文标签 |
  |-------|---------|
  | `created` | 待分配 |
  | `allocated` | 待处理 |
  | `processing` | 处理中 |
  | `finished` | 已完成 |
  | `closed` | 已关闭 |
  | `offed` | 已取消 |
  | `convert2Task` | 转为工单 |
  | `allFinished`（筛选虚拟值） | 已完成（含转工单） |
  | `exception`（筛选虚拟值） | 异常事件 |

  用户说「待处理/未分配/我负责的」等口语时，按语义映射到上表 value（如「待分配」→ `created`、「处理中」→ `processing`），拿不准就向用户确认，**不要臆造表中没有的 value**。
- **满意度（`degree`）**：值本身就是中文（非常不满意/不满意/一般/满意/非常满意），无需再做映射。
- **搜索关键字（`keyword`）**：只模糊匹配四个字段——事件编号 `eventNo`、客户名称 `cusName`、联系人姓名 `lmName`、联系人电话 `lmPhone`。**不搜索自定义字段**，用户想按自定义字段搜索时改用 `conditions` 条件对象（见 [`references/shb-event-search.md`](references/shb-event-search.md)）。
- **分页**：事件搜索接口分页字段是 **`pageNum`（从 1 开始）**，响应结构是 PageInfo（`{pageNum, pageSize, total, pages, list}`），**与工单不同**（工单是 `page`/`content`/`totalElements`）。
- **Executor（负责人）/ mySearch**：查"我负责的事件"等语义化范围，用 `mySearch` 字段（`create` 我创建 / `execute` 我负责 / `synergy` 我协同 / `all` 综合 / `team` 部门 / `none` 忽略），而不是拼接 `executor` 字段。
- **Formatted Data（格式化数据）**：把列表原始字段转换为 `columns + rows`，字段文案来自字段元数据，字段值转为人类可读文案。
- **事件类型列表**：接口返回两组：`writeList`（可创建）、`readList`（可查看）。
- **创建事件 vs 分配负责人**：创建事件（`event create submit`）和分配负责人是两个独立动作——`/event/createInner` 先建事件，**只有传了 `--executor-id` 时**才会紧接着检查指派审批。命令返回码 0（成功）但提示"分配需要审批"时，**事件已经创建成功**，只是分配还没生效，不要当成失败重试创建。
- **更新事件的覆盖语义（重要）**：`/event/update` 会用请求体**无条件覆盖**客户/联系人/地址/产品/计划时间等字段——请求里没带的字段会被清空。`event update submit` 的快捷 flag 模式已经内置"先查详情、拿全量字段、再合并你的改动"的逻辑，**放心用快捷 flags，不用担心覆盖问题**；但如果你自己用 `--data`/`--file` 传完整 JSON，必须自己带上不想清空的字段。
- **审批中的事件不能改**：`inApprove` 为 1（审批中）时 `event update submit` 会直接报错拒绝，不发请求。

## Important Notes

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

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

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

正例：「你名下共有 12 条事件：待分配 5 条、处理中 7 条。下面是详细分析……」。

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

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

**CRITICAL** — 只要本轮对话的任意一次 search 结果里出现过某事件的 `id`，后续用户再提到该事件（无论通过 eventNo、关键字还是描述），**必须从已有结果中匹配出 id 直接使用**，禁止再发起 `event search --keyword <eventNo>` 来"重新获取 id"。  
只有当前对话中从未出现该事件时才允许发起新搜索。

### 输出格式

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

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

### 写操作安全

- `event create submit` 和 `event update submit` 是写操作；执行前确认用户已明确要求创建/修改事件，不要臆测执行。
- 创建/更新前，关键字段（事件类型、客户、联系人、负责人等）如果不确定，先向用户确认或用查询命令核实，不要凭空编造。
- **创建前必须用 `event field list --type-id <templateId>` 读取字段，按 `isNull=0` 判断哪些是必填字段**，缺值时直接用中文向用户询问（详见 [`references/shb-event-create.md`](references/shb-event-create.md)），不要在必填信息缺失时硬着头皮提交，也不要把 `isNull`/字段配置这类判断过程说给用户听。
- `event create submit` 返回"事件已创建，但指派需要审批"时，**不要**把它当失败重新执行创建——那会重复建事件。应把这条信息原样转述给用户（用自然语言，不带命令细节）。
- `event update submit` 遇到"审批中事件无法修改"时，明确告知用户该事件正在审批中，需等审批结束后再改。
- **改负责人不支持**：当前 `event update submit` 会忽略请求里的 `executorId`/`executorName`/`synergies`（后端就是这么处理的），改负责人需要走 `/event/updateExecutor`，本 CLI 暂未覆盖。用户要求改负责人时明确告知暂不支持，不要假装执行成功。
- **使用优先级：快捷 flags ＞ `--data` ＞ `--file`**——常规字段用快捷 flags；复杂字段（自定义 attribute、地址、时间戳等）用 `--data` 内联；`--file` 仅本地已有现成 JSON 文件时用。

## API Resources

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

| 操作 | 必须先加载 |
|------|-----------|
| 搜索事件（`event search`） | [`references/shb-event-search.md`](references/shb-event-search.md) |
| 查看事件详情（`event detail`） | [`references/shb-event-detail.md`](references/shb-event-detail.md) |
| 查询事件类型（`event type list`） | [`references/shb-event-type.md`](references/shb-event-type.md) |
| 查询事件字段（`event field list`） | [`references/shb-event-field.md`](references/shb-event-field.md) |
| 创建事件（`event create submit`） | [`references/shb-event-create.md`](references/shb-event-create.md) |
| 更新事件（`event update submit`） | [`references/shb-event-update.md`](references/shb-event-update.md) |

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

## 权限与安全

- 只读命令：`search`、`detail`、`type list`、`field list`。
- 写命令：`create 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` 技能重新认证。
- `--id is required` → `event detail` 快捷 flags 模式缺少必填字段。
- `--template-id is required` / `--event-id is required` → 快捷 flags 模式缺少必填字段；也可改用 `--data` / `--file` 提供完整 JSON。
- `event update submit` 报"审批中事件无法修改" → 事件当前处于审批流程中，需等审批结束。
- 字段/类型不确定 → 先用 `event type list --format-data` 找 templateId，再用 `event field list --type-id <templateId>` 查字段。

## References

- [`references/shb-event-search.md`](references/shb-event-search.md) —— 事件搜索
- [`references/shb-event-detail.md`](references/shb-event-detail.md) —— 事件详情查询
- [`references/shb-event-type.md`](references/shb-event-type.md) —— 事件类型查询
- [`references/shb-event-field.md`](references/shb-event-field.md) —— 事件字段查询
- [`references/shb-event-create.md`](references/shb-event-create.md) —— 事件创建
- [`references/shb-event-update.md`](references/shb-event-update.md) —— 事件更新