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

# shb-cli event update

事件更新。`event update submit` 是写操作，默认先取当前事件全量数据再合并你的改动，避免覆盖未修改的字段。

## 安全规则

- 更新前确认用户明确要求修改该事件的哪些字段。
- **不支持改负责人**：`executorId`/`executorName`/`synergies` 会被后端忽略，用户要求改负责人时明确告知暂不支持（需要走 `/event/updateExecutor`，本 CLI 暂未覆盖）。
- 事件处于审批中（`inApprove==1`）时无法修改，命令会在发请求前直接报错拒绝。

## 覆盖语义（为什么必须先查后改）

后端 `/event/update` 会用请求体**无条件覆盖**这些字段：客户、联系人、地址、产品、计划开始/结束时间等——请求里没带的字段会被清空，不是"保留原值"。

`event update submit` 的快捷 flag 模式已经内置这个流程：

1. 先调用只读接口取该事件当前的完整数据
2. 以当前数据为底稿，只把你通过 flag 指定的字段替换掉
3. 提交合并后的完整请求

所以**放心用快捷 flags 改动个别字段，其它字段会原样保留**，不用担心覆盖问题。

> 唯一的例外：自定义字段（`attribute`）在后端是增量合并的，但其中的 `level`（优先级）会被请求整体覆盖——快捷 flag 模式下 CLI 已经把当前 `level` 带回去。修改优先级推荐用 `--level`；在 `--custom-fields` 里传 `level` 也生效（CLI 会自动提升到顶层），两者同时给时 `--level` 优先。

## 快捷 flag 更新

```bash
# 只改客户
shb-cli event update submit --event-id <eventId> --customer-id <newCustomerId> --customer-name "新客户名称"

# 只改联系人
shb-cli event update submit --event-id <eventId> --linkman-name "新联系人" --linkman-phone "13900000000"

# 只改地址
shb-cli event update submit --event-id <eventId> --province "浙江省" --city "杭州市" --district "西湖区" --detail-address "新地址"

# 只改计划时间
shb-cli event update submit --event-id <eventId> --plan-start-time 1735689600000 --plan-end-time 1735693200000

# 只改自定义字段（增量合并，不影响其它自定义字段）
shb-cli event update submit --event-id <eventId> --custom-fields '{"field_priority":"高"}'

# 组合修改
shb-cli event update submit --event-id <eventId> --customer-name "新客户名称" --level high

> 联系人邮箱（lmEmail）无法通过更新接口修改——后端 /event/update 不复制该字段，CLI 因此不提供 --linkman-email。
```

不使用 `--data`/`--file` 时，`--event-id` 必填。

## 完整 JSON 更新

**使用优先级：快捷 flags ＞ `--data` ＞ `--file`**——常规改动用快捷 flags（CLI 会自动处理覆盖语义）；只有确实需要发送完整自定义 JSON 时才用 `--data`/`--file`。

```bash
shb-cli event update submit --data '{
  "id": "event-uuid-xxx",
  "cusId": "cust_001",
  "cusName": "客户A",
  "attribute": {}
}'
```

> **CRITICAL** — 用 `--data`/`--file` 时，CLI **不会**帮你先查详情再合并，你必须自己带上所有不想被清空的字段（`cusId`/`cusName`/`lmId`/`lmName`/`lmPhone`/`cusAddress`/`products`/`planStartTime`/`planEndTime` 等）以及非空的 `attribute`。没把握就优先用快捷 flags。

## 响应处理

- 成功：输出 `✓ Event updated (id=<eventId>)`，随后是完整原始响应。
- 事件审批中：命令直接报错"审批中事件无法修改"，不会发起请求。
- 其它失败：命令返回非零退出码并报错。

## 典型组合场景

### 场景一：改客户后核对

```bash
# 1. 更新
shb-cli event update submit --event-id <eventId> --customer-id <newCustomerId> --customer-name "新客户名称"

# 2. 核对：确认联系人/地址等未改字段仍然保留
shb-cli event detail --id <eventId> --format-data
```

### 场景二：只改一个自定义字段

```bash
shb-cli event update submit --event-id <eventId> --custom-fields '{"field_priority":"低"}'
```

其它自定义字段和所有系统字段都不受影响。

## 注意

- `--event-id` 是事件的系统 UUID，不是事件编号（`eventNo`）。不知道 id 时先用 `event search --keyword <eventNo>` 定位。
- 若本轮对话中已经搜索过该事件（结果里出现过它的 `id`），直接复用，不要重新搜索。
- `--plan-start-time`/`--plan-end-time` 必须是毫秒级 Unix 时间戳。