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

# shb-cli product create

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

## 安全规则

- **创建前必须先查字段定义并检查必填项**：用 `product field list -o table` 查看字段，凡「必填=是」（即 `isNull=0`）的字段都必须有值——系统必填字段走对应快捷 flag（如 `--name`），必填的自定义字段（`isSystem=0`）放进 `--attr`。**任一必填字段缺值时，先向用户询问、拿到值再创建，不得用空值或编造值提交。**向用户询问时用字段的「显示名」，不要把 `fieldName` 等英文字段名抛给用户。
- **创建前必须先问用户「是否关联客户」**：
  - 关联 → `customerId`（关联客户）变为**必填**，还需带上该客户的联系人 `linkman`。先用 `customer list --keyword <名称>` 搜到客户 id，再用 `customer linkman search` 拿联系人 id；缺客户或联系人信息时先问用户。这种带联系人/地址的完整结构走 `--data`（快捷 `--customer-id` 只设 customerId、不含 linkman）。
  - 不关联 → 不传 `customerId`/`linkman`，`hasBindCustomer` 为 `0`。
- 自定义字段值通过 `--attr` 传入，字段名（`fieldName`）通过 `product field list` 查询获得。
- 需要目录/类型 ID 时，先用 `product catalog list -o table` 查询。


## 完整 flags 创建

```bash
shb-cli product create \
  --name "某型号设备" \
  --serial-number "SN-2024-001" \
  --type "设备类型A" \
  --customer-id "<customerId>" \
  --template-id "<templateId>" \
  --catalog-id 511205 \
  --create-qrcode \
  --attr '{"color":"蓝色","specification":"标准款"}'
```

## 完整 JSON 方式（--data / --file）

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

```bash
shb-cli product create --data '{
  "name": "某型号设备",
  "serialNumber": "SN-2024-001",
  "type": "设备类型A",
  "templateId": "<templateId>",
  "catalogId": 511205,
  "createQrcode": false,
  "hasBindCustomer": 1,
  "customerId": "<customerId>",
  "linkman": { "id": "<linkmanId>" },
  "productCompleteAddress": {
    "country": "中国", "province": "", "city": "", "dist": "",
    "street": "", "addressType": 0, "all": "中国"
  },
  "attribute": {
    "<自定义字段fieldName>": "值"
  }
}'
```

字段说明：

- `hasBindCustomer`：是否关联客户，关联为 `1`、不关联为 `0`。**不关联时省去下面的 `customerId`/`linkman`/`productCompleteAddress`**。
- `customerId`：关联客户时**必填**，取 `customer list --keyword <名称>` 搜到的客户 id。
- `linkman.id`：关联客户时需带上该客户的联系人 id，取自 `customer linkman search`。
- `productCompleteAddress`：产品地址，可留空字符串占位；如需填写按 `country/province/city/dist` 结构。
- `attribute`：仅放有值的自定义字段，空字段不必逐个列出。

## 支持的 Flags

| Flag | 说明 | 必填 |
|------|------|------|
| `--name` | 产品名称 | 是 |
| `--serial-number` | 产品编号 | — |
| `--type` | 产品类型文案 | — |
| `--customer-id` | 关联客户 ID | — |
| `--template-id` | 产品模板 ID | — |
| `--catalog-id` | 产品目录/类型 ID（数字） | — |
| `--create-qrcode` | 创建时自动生成二维码 | — |
| `--attr` | 自定义字段值，JSON 对象格式 | — |
| `--data` | 完整 JSON body，覆盖所有其他 flags | — |
| `--file` | JSON body 文件路径（最后选择，仅本地已有文件时用） | — |

## 自定义字段处理

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

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

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

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

2. 逐项核对「必填=是」的字段是否都已有值；缺值的（无论系统字段还是自定义字段）先向用户询问——用字段**显示名**，不要报 `fieldName`。

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

   ```bash
   shb-cli product create \
     --name "某设备" \
     --attr '{"color":"红色","power":"220V"}'
   ```

## 获取目录 ID

产品目录/类型 ID 是数字类型，需要先查询：

```bash
# 查询所有目录和类型
shb-cli product catalog list -o table

# 只看"类型"（conData=1）
shb-cli product catalog list --con-data 1 -o table
```

取 ID 列的数字值填入 `--catalog-id`。

## 注意

- 关联客户时，`hasBindCustomer` 会根据是否传了 `--customer-id` 自动设置。
- 创建成功后输出后端返回的 JSON，可从中提取新产品 `id`。
- 如果创建报错，请把错误信息反馈给用户，不要自动重试。