# 三层命令体系

> Shoplazza CLI 的三层命令体系：快捷命令、API 命令与原始 API，各自擅长什么，以及如何按任务挑选。

Shoplazza CLI 将命令组织为三层，每层提供不同的控制级别和便利性。

## 概览

```
第一层：快捷命令     →  人机友好，智能默认值
第二层：API 命令     →  1:1 API 映射，完整参数控制
第三层：原始 API     →  逃生舱，100% 端点覆盖
```

## 第一层：快捷命令

以 `+` 为前缀，专为高频操作设计。提供智能默认值、具名参数和简化的接口。

**适用场景：** 日常操作，便利性优先于完整参数控制。

```shell
shoplazza products +search --keyword "shirt" --format table
shoplazza orders +ship --order-id 12345 --tracking SF123456789
shoplazza discounts +percent-code
```

**特征：** `+` 前缀区分快捷命令和 API 命令；在交互式终端中会询问漏填的必填参数；为人类开发者和 AI Agent 双向设计。

## 第二层：API 命令

与 Shoplazza 平台 API 端点 1:1 映射，提供对请求参数和响应处理的完整控制。

**适用场景：** 需要精确控制 API 参数时，或没有对应快捷命令时。

```shell
shoplazza products list --params '{"per_page": 50, "published_status": "published"}'
shoplazza products create --data @product.json
shoplazza orders list --format json --jq '.data.orders[] | {id, status, total_price}'
```

**特征：** 300+ 命令从 OpenAPI 规范自动生成；`--params` 用于路径参数和查询参数（API 命令不接受位置参数）；`--data` 用于请求体。

## 第三层：原始 API

`api rest` 命令提供逃生舱，可直接调用任意 Shoplazza API 端点。

**适用场景：** 需要调用 API 命令尚未覆盖的端点时，或需要完整 HTTP 控制时。

```shell
shoplazza api rest GET /openapi/2026-01/products --params '{"per_page": 10}'
shoplazza api rest POST /openapi/2026-01/webhooks --data '{"webhook": {"topic": "orders/create", "address": "https://example.com/hook"}}'
```

## 如何选择

| 场景 | 推荐层级 |
|------|---------|
| 按关键词搜索商品 | 快捷命令：`products +search` |
| 创建包含 20+ 字段的商品 | API 命令：`products create` |
| 调用全新的 API 端点 | 原始 API：`api rest` |
| 日常订单管理 | 快捷命令：`orders +ship`, `orders +refund` |
| 调试或探索 API | 原始 API：`api rest` + `--dry-run` |

## 发现命令

```shell
shoplazza schema              # 查看所有模块
shoplazza schema products     # 查看模块下的命令
shoplazza schema products.list # 查看命令的完整 Schema
```