---
name: shb-product
version: "1.0.0"
description: "当用户需要搜索、查看、创建产品，或查询产品字段定义、产品目录类型时触发。通过 shb-cli 操作产品列表搜索、产品创建、产品字段查询和产品目录类型管理。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli product --help"
---

# product (v1)

**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../shb-shared/SKILL.md`](../shb-shared/SKILL.md)，其中包含 profile 初始化、环境选择、OAuth2 登录、token 导入、租户切换、安全规则。所有 product 命令都依赖 `shb-shared` 描述的认证状态。**

## Core Concepts

- **Product（产品）**：售后宝 产品档案，标识为 `id`，可关联客户（`customerId`）。
- **Catalog（产品目录/类型）**：产品的分类体系，分为"目录"（`conData=0`）和"类型"（`conData=1`），标识为 `id`（数字）。
- **Field（字段）**：产品表单的字段定义，包含系统字段（`isSystem=1`）和自定义字段（`isSystem=0`），自定义字段值存于 `attribute` 中。
- **SerialNumber（产品编号）**：产品的唯一业务编号。
- **Template（产品模板）**：产品关联的模板，标识为 `templateId`。

## Important Notes

### 面向用户的输出措辞（禁止回显接口字段名与内部机制）

**CRITICAL** — 以下两类内容**只供你内部使用，禁止出现在给用户的回复里**：

1. **接口/JSON 字段名**：`totalElements`、`totalPages`、`page`、`rows`、`columns`、`id`、`customerId`、`catalogId`、`templateId`、`serialNumber`、`conData`、`isSystem`、`attribute` 等，一律转成自然语言。  
   例：「totalElements 为 189」→「共 189 个产品」；「totalPages=3」→「总共 3 页」；「conData=1」→「类型」。
2. **命令与一切技术细节**：任何 shb-cli 命令、子命令、flag、参数名，以及取数过程（分页、数量判断、全量拉取、字段裁剪、截断重试）都是后台实现细节，**回复里绝不出现，也不要解释你用了什么命令/参数、怎么取的数**，换种说法也不行。直接给结果。
3. **自定义字段（`attribute`）的显示**：`attribute` 对象的 key 是 `fieldName`（如 `field_xxx`），**绝不能直接拿这个 key 显示给用户**。展示前用 `product field list` 取字段定义，按 `fieldName` 匹配出对应的「显示名」（中文字段名），给用户看「中文字段名：值」；匹配不到的字段宁可不展示，也不要把英文 key 抛给用户。用 `--format-data` 输出时 CLI 已按字段元数据转换，一般无需自行映射。

此规则适用于所有 product 子命令（search / field / catalog / create）。

### 命令分层

- **`shb-cli product <subcommand>`** —— 产品模块主入口，推荐路径。

### 输出格式

所有命令支持全局 `--output` / `-o` 标志：

```bash
shb-cli product search --output json    # 默认，完整 pretty JSON
shb-cli product search --output table   # 表格格式
```

### 写操作安全

- `product create` 是写操作，执行前确认用户明确要求创建。
- 自定义字段值通过 `--attr` 以 JSON 对象传入，key 为 `fieldName`。
- 复杂场景使用 `--data` / `--file` 提供完整 JSON body。

## API Resources

**CRITICAL — 执行任何 product 子命令前，必须先用 skill 工具加载对应 reference 文档，再执行命令：**

| 操作 | 必须先加载 |
|------|-----------|
| 搜索产品（`product search`） | [`references/shb-product-search.md`](references/shb-product-search.md) |
| 查询产品字段定义（`product field list`） | [`references/shb-product-field.md`](references/shb-product-field.md) |
| 查询产品目录/类型（`product catalog list` / `product catalog field list`） | [`references/shb-product-catalog.md`](references/shb-product-catalog.md) |
| 创建产品（`product create`） | [`references/shb-product-create.md`](references/shb-product-create.md) |

同一会话中每个 reference 只需加载一次。命令的完整 flags、字段、分页与注意事项都在对应 reference 里，**不要仅凭本页示例直接执行**。

## 权限与安全

- 只读命令：`search`、`field list`、`catalog list`、`catalog field list`。
- 写命令：`create`。不要在未确认用户意图时执行。
- 可见和可写范围 = 当前 profile 用户在 SHB 后端的权限范围。

## 排错

- 401 / `token is empty` → 回到 `shb-shared` 技能重新认证。
- `--name is required` → 创建时未传 `--name`，该字段必填。
- 列表为空但无错误 → 检查筛选条件，尝试去掉筛选或扩大 `--page-size`。
- 目录类型 ID 不确定 → 先用 `product catalog list -o table` 查询，取 ID 列的值。

## References

- [`references/shb-product-search.md`](references/shb-product-search.md)
- [`references/shb-product-create.md`](references/shb-product-create.md)
- [`references/shb-product-field.md`](references/shb-product-field.md)
- [`references/shb-product-catalog.md`](references/shb-product-catalog.md)