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

# shb-cli customer create

创建新客户。`customer create` 是写操作，执行前确认用户明确要求创建。

## 安全规则

- 创建前确认用户明确要求"创建/新建客户"。
- **创建前必须先查字段定义并检查必填项**：用 `customer field list -o table` 查看字段，凡「必填=是」（即 `isNull=0`）的字段都必须有值——系统必填字段走对应快捷 flag（如 `--name`、`--lm-phone`），必填的自定义字段（`isSystem=0`）放进 `--attr`。**任一必填字段缺值时，先向用户询问、拿到值再创建，不得用空值或编造值提交。**向用户询问时用字段的「显示名」，不要把 `fieldName` 等英文字段名抛给用户。
- **客户编号（serialNumber）是否需要用户提供，看是否自动生成**：在字段列表里找 `fieldName` 为 `serialNumber` 的对象，若其 `setting.autoSerialNumber` 为 `true`，则编号由后端自动生成——**不要向用户索要编号，也不要传 `--serial-number`**；为 `false`/缺省时才按普通字段处理并且为必填字段。
- 创建前默认对 `serialNumber`（客户编号）做唯一性校验；若不需要可加 `--force`。
- 自定义字段值通过 `--attr` 传入，字段名（`fieldName`）通过 `customer field list` 查询获得。

## 最小参数创建

```bash
shb-cli customer create \
  --name "某客户有限公司" \
  --lm-phone "13800000000"
```

`--name` 和（`--lm-phone` 或 `--lm-email`）是必填项。

## 完整 flags 创建

```bash
shb-cli customer create \
  --name "某客户有限公司" \
  --lm-phone "13800000000" \
  --lm-email "contact@example.com" \
  --lm-name "张三" \
  --serial-number "CU-2024-001" \
  --manager-id "<userId>" \
  --attr '{"industry":"制造业","level":"VIP"}'
```

## 完整 JSON 方式（--data / --file）
`--data` / `--file` 优先级最高，会覆盖所有其他 flags。

```bash
shb-cli customer create --data '{
  "name": "某客户有限公司",
  "lmName": "张三",
  "lmPhone": "13800000000",
  "lmEmail": "contact@example.com",
  "serialNumber": "CU-2024-001",
  "customerManager": "<userId>",
  "attribute": {
    "industry": "制造业",
    "level": "VIP"
  },
  "customerAddress": {
    "adCountry": "中国",
    "adProvince": "上海市",
    "adCity": "上海市",
    "adDist": "浦东新区",
    "adAddress": "xx路xx号",
    "adStreet": "",
    "adLatitude": "",
    "adLongitude": "",
    "addressType": 0
  },
  "tenantTagList": [{ "id": "tagId" }]
}'
```

```bash
shb-cli customer create --file ./create-customer.json
```

## 支持的 Flags

| Flag | 说明 | 必填 |
|------|------|------|
| `--name` | 客户名称（最大 50 字） | 是 |
| `--lm-phone` | 联系人手机号（lm-phone 或 lm-email 二选一） | 条件必填 |
| `--lm-email` | 联系人邮箱（lm-phone 或 lm-email 二选一） | 条件必填 |
| `--lm-name` | 联系人姓名 | — |
| `--serial-number` | 客户编号 | — |
| `--manager-id` | 客户负责人用户 ID | — |
| `--attr` | 自定义字段值，JSON 对象格式 | — |
| `--force` | 跳过 serialNumber 唯一性校验 | — |
| `--data` | 完整 JSON body，覆盖所有其他 flags | — |
| `--file` | JSON body 文件路径（最后选择，仅本地已有文件时用） | — |

## 自定义字段处理

系统字段（`isSystem=1`）通过快捷 flags 传入（`--name`、`--lm-phone` 等）；自定义字段（`isSystem=0`）通过 `--attr` 以 JSON 对象传入，key 为 `fieldName`。

**创建流程（务必：先查字段 → 核必填 → 缺值问用户 → 再创建）：**

1. 查字段定义，重点看「必填」列（`isNull=0` 即必填）：

   ```bash
   shb-cli customer field list -o table
   ```

2. 逐项核对「必填=是」的字段是否都已有值；缺值的（无论系统字段还是自定义字段）先向用户询问——用字段**显示名**，不要报 `fieldName`。
   - 例外：`serialNumber` 字段若 `setting.autoSerialNumber` 为 `true`，由后端自动生成，**跳过、不向用户索要**。

3. 必填的自定义字段放进 `--attr`、系统字段走快捷 flag，再创建：

   ```bash
   shb-cli customer create \
     --name "某客户" \
     --lm-phone "13800000000" \
     --attr '{"industry":"制造业","customerLevel":"A级"}'
   ```

## 唯一性校验

创建时若传了 `--serial-number`，默认会先调用后端唯一性接口校验编号是否已存在：
- 编号已存在 → 报错提示，停止创建
- 加 `--force` → 跳过校验，直接创建
- 未传 `--serial-number` → 不触发校验

## 注意

- 创建成功后输出后端返回的 JSON，可从中提取新客户 `id`。
- 如果创建报错，请把错误信息反馈给用户，不要自动重试。