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

# shb-cli task alloc

工单派发/分配。`task alloc submit` 是写操作，默认先调用确认接口检查是否需要审批；无需审批时才执行派单。

## 安全规则

- 派单前确认用户明确要求把工单分配给某个执行人，或使用自动派单。
- 默认不要使用 `--no-approve`。该标志会跳过确认/审批检查并直接派单。
- `--task-id` 是工单系统 ID，不是工单编号 `taskNo`。不知道 ID 时先用 `task search` 定位。
- 只知道执行人姓名时用 `--search-user <姓名>`，命令会自动搜索用户并选择，**不要通过搜索工单来反推 userId**。
- 已知 userId 时用 `--executor-id <userId>`；需要自动派单时传特殊值 `auto_dispatch`。

## 只知道执行人名字时（推荐路径）

**CRITICAL — 只知道执行人姓名时，直接用 `--search-user`，不要绕道搜索工单来获取 userId：**

```bash
shb-cli task alloc submit \
  --task-id <taskId> \
  --search-user "林子"
```

命令会自动搜索匹配的用户，返回列表供选择，无需手动获取 userId。

## 快捷 flag 派单（已知 userId）

```bash
shb-cli task alloc submit \
  --task-id <taskId> \
  --executor-id <userId>
```

带计划时间：

```bash
shb-cli task alloc submit \
  --task-id <taskId> \
  --executor-id <userId> \
  --plan-start-time "2026-04-25T09:00:00" \
  --plan-end-time "2026-04-25T18:00:00"
```

自动派单：

```bash
shb-cli task alloc submit --task-id <taskId> --executor-id auto_dispatch
```

不使用 `--data` / `--file` 时，`--task-id` 和 `--executor-id` 必填。

## 完整 JSON 派单

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

```bash
shb-cli task alloc submit --file ./alloc-task.json
shb-cli task alloc submit --data '{"taskId":"xxx","executorId":"yyy"}'
```

示例 JSON：

```json
{
  "taskId": "xxx",
  "executorId": "yyy",
  "synergies": "",
  "operateCode": "allot",
  "planStartTime": "2026-04-25T09:00:00",
  "planEndTime": "2026-04-25T18:00:00"
}
```

## 支持的 flags

| Flag | 说明 |
|------|------|
| `--task-id` | 工单 ID，快捷 flags 模式必填 |
| `--executor-id` | 执行人 userId 或特殊值 `auto_dispatch`，快捷 flags 模式必填（与 `--search-user` 二选一） |
| `--search-user` | 按关键字搜索用户并交互选择，可替代 `--executor-id` 手动输入 userId |
| `--synergies` | 协同人 JSON 字符串 |
| `--operate-code` | 操作码 |
| `--plan-start-time` | 计划开始时间，ISO 8601 |
| `--plan-end-time` | 计划结束时间，ISO 8601 |
| `--data` | 完整 JSON body |
| `--file` | JSON body 文件（最后选择，仅本地已有文件时用） |
| `--no-approve` | 跳过确认/审批检查并直接派单 |

## 审批流程

默认执行顺序：

1. 调用派单确认接口检查是否需要审批。
2. 如果返回 `errorCode = 10003`，命令输出审批信息并停止。
3. 无需审批时调用派单接口。

如果返回 “Approval required”，把后端返回的审批信息反馈给用户，不要自动改用 `--no-approve`。

## 如何获取 taskId

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

```bash
# 按工单编号搜索
shb-cli task search --keyword "WO-20240101" -o raw | jq -r '.content[0].id'

# 按客户名搜索并选择
shb-cli task search --keyword "客户名称" -o raw | jq '.content[] | {id, taskNo, state, executorName}'
```

## 注意

- `executorId` 使用 userId；后端支持特殊值 `auto_dispatch` 自动派单。
- `synergies` 是 JSON 字符串；复杂协同人结构建议使用 `--file`。
- 派单成功后会输出后端返回的 JSON。