# 认证

> Shoplazza CLI 的 OAuth 2.0 + PKCE 认证：浏览器登录、CI 非交互式登录、作用域选择、多店铺切换与凭证存储位置。

Shoplazza CLI v2 使用 OAuth 2.0 + PKCE 进行安全认证。本指南涵盖交互式登录、CI/CD 非交互式认证、作用域管理和多店铺工作流。

## 交互式登录（浏览器）

标准认证流程通过浏览器进行 OAuth 授权：

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com
```

**流程：**

1. CLI 在 Shoplazza 合作伙伴平台创建 OAuth 会话。在交互式终端中，CLI 会先询问你未传入的店铺或业务域
2. CLI 打印授权 URL，在浏览器中打开即可授权
3. 授权后，CLI 接收并存储凭证，该店铺成为你的当前 [Profile](./commands/profile)
4. 凭证加密后保存在 CLI 的配置目录中（操作系统用户配置目录下的 `shoplazza-cli/`，如 macOS 上的 `~/Library/Application Support/shoplazza-cli/`）

不带 `--store-domain` 时，`auth login` 只登录账户。选定店铺至少需要一个作用域：传入 `--domain` 或 `--scope`，或在提示时选择业务域。

### 登录时指定作用域

使用 `--domain` 请求特定业务域的访问权限：

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers
```

或使用 `--scope` 精细控制 OAuth 作用域：

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --scope read_product,write_product,read_order
```

每次登录都会替换账户已授权的作用域。如需追加作用域并保留已有的，加上 `--merge-scopes`：

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain discounts --merge-scopes
```

### 查看可用作用域

```shell
shoplazza auth scopes
```

## 非交互式登录（CI/CD）

在 CI/CD 流水线和自动化环境中，使用用户访问令牌（UAT）：

```shell
shoplazza auth login --uat <your-token> --store-domain my-store.myshoplaza.com
```

或设置 `SHOPLAZZA_UAT`，`auth login` 会用它代替 `--uat`：

```shell
export SHOPLAZZA_UAT=your-token
shoplazza auth login --store-domain my-store.myshoplaza.com
shoplazza products +search --keyword "shirt"
```

:::tip
在有浏览器的机器上运行一次 `shoplazza auth login` 即可获得 UAT，登录输出中包含该值（`uat`）。将其作为密钥存储在 CI/CD 系统中——切勿提交到源代码仓库。
:::

## 查看认证状态

```shell
shoplazza auth status
```

显示内容：是否已登录及当前账户、已授权的 OAuth 作用域、UAT 过期时间，以及每个已配置的 Profile（店铺、作用域、令牌状态、是否为当前 Profile）。

## 切换店铺

无需注销即可切换到另一个店铺：

```shell
shoplazza auth store use --store-domain another-store.myshoplaza.com
```

CLI 会复用已有的账户凭证为新店铺申请店铺令牌，并创建或复用该店铺的 Profile。如需直接管理 Profile，或用 `--profile <名称>` 让单条命令操作其他店铺，参见 [Profile 管理](./commands/profile)。

## 注销

移除所有 Profile 和存储的凭证（在交互式终端中会先请你确认）：

```shell
shoplazza auth logout
```

:::caution
注销会删除本机存储的所有令牌和 Profile。下次使用 CLI 时需要重新认证。
:::

## 作用域映射

`--domain <模块>` 会展开为以下作用域：

| 模块 | 所需作用域 |
|------|-----------|
| `products` | `read_product`, `write_product`, `read_collection`, `write_collection`, `read_inventory`, `write_inventory`, `read_comments`, `write_comments`, `read_gift_cards`, `write_gift_cards` |
| `orders` | `read_order`, `write_order` |
| `customers` | `read_customer`, `write_customer` |
| `discounts` | `read_price_rules`, `write_price_rules` |
| `shop` | `read_shop`, `write_shop`, `read_shop_navigation`, `write_shop_navigation`, `read_collection`, `write_collection`, `read_product`, `write_product` |
| `themes` | `read_themes`, `write_themes`, `read_shop` |
| `checkout` | `read_themes`, `write_themes` |
| `app` | `read_themes`, `write_themes`, `read_shop` |
| `billing` | 无 |
| `webhook` | 无 |
| `all` | 以上全部作用域 |

`billing` 和 `webhook` 不带任何作用域，因此只带 `--domain billing` 或 `--domain webhook`（且不使用 UAT）的店铺登录会因没有作用域而被拒绝。

如果令牌缺少所需作用域，API 会拒绝调用（HTTP 403），CLI 返回 `auth` 错误（退出码 3）并提示如何重新认证。

## 安全最佳实践

* **加密存储** — 凭证加密保存在 CLI 的配置目录中，而非明文配置文件
* **定期轮换令牌** — 定期重新认证以刷新令牌
* **最小作用域** — 只请求工作流所需的作用域
* **CI/CD 密钥** — 将 UAT 令牌作为加密密钥存储在 CI/CD 系统中
* **不要提交令牌** — 将 `.shoplazza/` 添加到 `.gitignore`