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

# shb-cli event create

事件创建。`event create submit` 是写操作，执行前确认用户明确要求创建事件。

## 安全规则

- 创建前确认用户明确要求创建事件，关键字段（事件类型、客户）不确定时先问用户或用查询命令核实。
- 默认不传 `--executor-id`（不指派负责人直接创建）；只有用户明确要求同时指派时才传。
- 命令提示"事件已创建，但指派需要审批"时，**不是失败**——事件已经建好，只是指派挂起等审批。把这句话转成自然语言告诉用户，不要重复执行创建，也不要说成"创建失败"。
- **创建前必须读字段、判断哪些必填，缺值时向用户询问**：先用 `event field list --type-id <templateId>` 取该类型字段，`isNull=0` 的字段是必填字段，必须有值才能创建；没有值时直接用中文向用户要那几项（如「请提供客户」「请提供计划开始时间」），不要凭空编造，也不要在没有必填值的情况下硬着头皮提交。**读字段、判断哪些必填都是纯后台内部步骤**：绝不要把 `isNull`、「必填字段清单」、字段配置，或「我看到字段配置是…」这类判断过程复述给用户。
- **客户字段的关联信息**：`event field list` 返回的 `customer` 字段（`formType: "customer"`）里有 `setting.customerOption` 对象，用它判断该事件类型除了客户本身还需要哪些关联信息。原始结构示例（**仅供你内部读取判断，绝不照搬进回复**）：

  ```json
  {
    "product": true,
    "address": true,
    "linkman": true,
    "productIsShow": true
  }
  ```

  | key | 含义 |
  |-----|------|
  | `product` | 是否需要「产品」 |
  | `address` | 是否需要「客户地址」 |
  | `linkman` | 是否需要「联系人」 |
  | `productIsShow` | 是否显示「产品」字段 |

  据此判断需要哪些关联信息后，**直接用中文向用户开口要**（如「请提供联系人」「需要关联哪个产品」）。**回复里绝不出现 `customerOption`、它的字段名或 true/false 值，也不要复述你的判断过程**。
- **客户、联系人、产品、地址必须是系统内真实存在的数据，严禁捏造**，id 必须来自查询结果：
  - 客户：当场执行 `customer list` 查找确认（客户模块没有 `search` 子命令），拿到本次查询结果里的 `customer.id`——**不得**直接复用对话上下文中之前出现过的客户 id，创建事件的客户一律重新查（这是「复用已知 ID」规则的例外）。
  - 联系人：`customer linkman search --customer-id <id>` 获取该客户名下真实联系人（含 id）；地址：`customer address list --customer-id <id>` 获取真实地址（含 id）。主/默认联系人或地址看 `isMain` 字段。
  - 产品：从客户关联的产品查询结果中取 `products` 数组元素。
  - 若用户口头提供的客户/联系人/产品/地址在系统中查不到，告知用户并让其确认或先创建对应数据，**不得**用编造的 id 或信息提交。

## 创建前查看字段

创建前先确认该事件类型有哪些字段、哪些必填（见上方安全规则）：

```bash
# 只想看字段时，使用只读字段命令
shb-cli event field list --type-id <templateId>

# 显示字段后继续按当前参数创建
shb-cli event create submit --template-id <templateId> --show-fields --customer-id <customerId>
```

## 快捷 flag 创建

```bash
shb-cli event create submit \
  --template-id <templateId> \
  --template-name "事件类型名称" \
  --customer-id <customerId> \
  --customer-name "客户名称"
```

带联系人和地址：

```bash
shb-cli event create submit \
  --template-id <templateId> \
  --template-name "事件类型名称" \
  --customer-id <customerId> --customer-name "客户名称" \
  --linkman-id <linkmanId> --linkman-name "联系人姓名" --linkman-phone "13800000000" \
  --province "浙江省" --city "杭州市" --district "西湖区" --detail-address "详细地址"
```

带计划时间（毫秒时间戳）：

```bash
shb-cli event create submit \
  --template-id <templateId> \
  --template-name "事件类型名称" \
  --plan-start-time 1735689600000 \
  --plan-end-time 1735693200000
```

带自定义字段：

```bash
shb-cli event create submit \
  --template-id <templateId> \
  --template-name "事件类型名称" \
  --custom-fields '{"field_priority":"高"}'
```

同时指派负责人（可能触发审批，见下文）：

```bash
shb-cli event create submit \
  --template-id <templateId> \
  --template-name "事件类型名称" \
  --customer-id <customerId> \
  --executor-id <userId> --executor-name "执行人姓名"
```

不使用 `--data`/`--file` 时，`--template-id` 和 `--template-name` 都必填；`--template-name` 必须与 `--template-id` 对应的事件类型名称一致（来自 `event type list --list-type writeList`），**不要随意捏造**——省略或写错时后端不会报错，但新建的事件会缺少可读的事件类型名称，列表/详情里显示不出类型。

## 完整 JSON 创建

**使用优先级：快捷 flags ＞ `--data` ＞ `--file`**——常规字段用快捷 flags；复杂/完整 JSON 用 `--data`；`--file` 仅本地已有现成 JSON 文件时用。

```bash
shb-cli event create submit --data '{
  "templateId": "xxx",
  "templateName": "事件类型名称",
  "cusId": "cust_001",
  "cusName": "客户A",
  "attribute": {}
}'
```

> 用 `--data`/`--file` 时**必须自带 `attribute`**（哪怕是空对象 `{}`）——后端对 `attribute` 做 `put` 操作，缺失会报错。快捷 flags 模式下 CLI 已自动带上，无需关心。
>
> ⚠️ **`templateName` 必须传**，且要与 `templateId` 对应的事件类型名称一致，**请不要随意捏造**（来自 `event type list --list-type writeList` 返回的名称）。快捷 flags 模式下 CLI 会强制要求 `--template-name`，但 `--data`/`--file` 时 CLI 不会替你校验，必须自己带上。

## 响应处理

创建结果分三种：

1. **成功（无审批）**：输出 `✓ Event created (id=<eventId>)`，随后是完整原始响应。
2. **成功但指派待审批**：输出 `✓ Event created (id=<eventId>), but assignment requires approval: <message>`——**事件已创建**，只是分配给 `--executor-id` 的动作还在等审批。极少数情况下响应里拿不到 `eventId`（`message` 为 `needwait` 时），此时提示用户"事件已创建但需要稍后用搜索确认"，可用 `event search` 按刚用的客户名/时间定位。
3. **真失败**：命令返回非零退出码并报错（如时间校验不通过），此时**没有创建任何事件**。

## 典型组合场景

### 场景一：先看类型和字段，再创建

```bash
# 1. 找到目标类型
shb-cli event type list --list-type writeList --format-data

# 2. 查该类型字段（可选，确定自定义字段 key）
shb-cli event field list --type-id <templateId>

# 3. 创建（--template-name 用第 1 步返回的类型名称，不要臆造）
shb-cli event create submit --template-id <templateId> --template-name "<类型名称>" --customer-id <customerId> --customer-name "客户名称"
```

### 场景二：创建并立即指派负责人

```bash
shb-cli event create submit \
  --template-id <templateId> \
  --template-name "<类型名称>" \
  --customer-id <customerId> \
  --executor-id <userId> --executor-name "执行人姓名"
```

若返回"指派需要审批"，告诉用户"事件已创建（编号会在详情里显示），负责人指派正在等待审批"，不要重复创建。

## 注意

- `--executor-id`/`--executor-name` 是可选的；不传就创建一个未指派负责人的事件（如果租户配置允许）。
- `--plan-start-time`/`--plan-end-time` 必须是毫秒级 Unix 时间戳，且开始时间不能晚于结束时间，否则会被拒绝。
- `--level`（优先级）会被写入自定义字段（`attribute.level`），无需单独处理。
- 创建成功后想看完整字段，用 `event detail --id <eventId> --format-data` 核对。