# 应用开发

> Shoplazza CLI 的 app 命令覆盖应用全生命周期：init、dev、deploy、config link、extension create、versions 以及 Function 的编译与发布。

管理应用的完整开发生命周期——初始化、开发、部署和版本管理。

## init

创建新的 Shoplazza 应用项目或连接到已有应用。命令会在当前目录下创建一个以应用命名的子目录。

两种互斥模式：

- **创建模式**（`--name`）：创建新应用并搭建项目。
- **链接模式**（`--client-id`）：通过 Client ID 链接已有应用并搭建项目。

必须提供 `--name` 或 `--client-id` 其中之一。

```shell
shoplazza app init --name "My App" [--partner <id>]
shoplazza app init --client-id <client_id>
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--name <名称>` | string | 创建模式：新应用的名称，与 `--client-id` 互斥 |
| `--partner <id>` | string | 创建模式：创建应用所属的合作伙伴（组织）ID；仅在账户有多个合作伙伴时需要（链接模式下忽略） |
| `--client-id <id>` | string | 链接模式：通过 Client ID 链接已有应用，与 `--name` 互斥 |

### 示例

```shell
# 创建新应用（单合作伙伴账户）
shoplazza app init --name "my-app"

# 在指定合作伙伴下创建新应用
shoplazza app init --name "my-app" --partner partner-id

# 链接到已有应用
shoplazza app init --client-id your-client-id
```

## list

列出账户下的所有应用。

```shell
shoplazza app list [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--partner <id>` | string | 按合作伙伴 ID 筛选（账户有多个合作伙伴时需要） |

## info

显示当前应用的元数据，包括合作伙伴、用户和本地扩展信息。

```shell
shoplazza app info [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--path <路径>` | string | 项目根目录（默认：`.`；使用 `--client-id` 时忽略） |
| `--client-id <id>` | string | 通过 Client ID 查询指定应用（跳过本地项目；不列出扩展） |

## dev

启动本地开发服务器，支持所有扩展的热模块替换。

```shell
shoplazza app dev [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--path <路径>` | string | 项目根目录（默认：`.`） |
| `--debug` | bool | 以调试模式构建扩展（默认：`false`） |
| `--ngrok-authtoken <token>` | string | 个人 ngrok 认证令牌。保存到 `<项目>/.env` 的 `NGROK_AUTHTOKEN` 字段，后续运行会自动复用。仅在主隧道 cloudflared 无法启动时作为备选方案使用 |

## deploy

构建并部署应用及其所有扩展到生产环境。

```shell
shoplazza app deploy [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--path <路径>` | string | 项目根目录（默认：`.`） |
| `--debug` | bool | 以调试模式构建扩展（默认：`false`） |

### 示例

```shell
# 从当前目录部署
shoplazza app deploy

# 部署指定项目
shoplazza app deploy --path ./my-app
```

## config link

将应用配置文件写入当前项目。与 `app init` 不同，不会搭建模板——仅添加 `shoplazza.app.<name>.toml`。

两种互斥模式：

- **链接模式**（`--client-id`）：从 Dashboard 拉取已有应用的配置。
- **创建模式**（`--create --name`）：在后端创建新应用，然后写入配置。

```shell
shoplazza app config link --client-id <client_id>
shoplazza app config link --create --name "My App" [--partner <id>]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--client-id <id>` | string | 链接模式：通过 Client ID 拉取已有应用的配置，与 `--create` 互斥 |
| `--create` | bool | 创建模式：在后端创建新应用并写入配置，与 `--client-id` 互斥 |
| `--name <名称>` | string | 创建模式：新应用的名称（使用 `--create` 时必填） |
| `--partner <id>` | string | 创建模式：创建应用所属的合作伙伴（组织）；仅有一个合作伙伴时自动选择 |
| `--config <名称>` | string | 应用配置名称（默认：应用名称）——写入 `shoplazza.app.<名称>.toml`，已存在则合并 |
| `--path <路径>` | string | 项目根目录（默认：`.`） |

## config use

切换当前活跃的应用配置（在线验证）。

```shell
shoplazza app config use [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--config <名称>` | string | 要切换到的应用配置名称（默认：基础 `shoplazza.app.toml`） |
| `--path <路径>` | string | 项目根目录（默认：`.`） |

## extension create

在当前应用项目中搭建新的扩展。

```shell
shoplazza app extension create [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--type <类型>` | string | 扩展类型：`theme`、`checkout` 或 `function`（必填） |
| `--name <名称>` | string | 扩展名称 / `extensions/` 下的目标目录（必填） |
| `--theme-type <子类型>` | string | 主题子类型：`basic` 或 `embed`（`--type` 为 `theme` 时必填） |
| `--path <路径>` | string | 项目根目录（默认：`.`） |

### 示例

```shell
# 创建主题扩展
shoplazza app extension create --type theme --name my-theme --theme-type basic

# 创建函数扩展
shoplazza app extension create --type function --name my-function
```

## versions

列出应用的所有已部署版本（分页）。

```shell
shoplazza app versions [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--client-id <id>` | string | 应用 Client ID（默认：当前活跃配置） |
| `--partner <id>` | string | 合作伙伴 ID（默认：当前活跃配置） |
| `--path <路径>` | string | 项目根目录（默认：`.`） |
| `--offset <数量>` | int | 分页偏移量（默认：`0`） |
| `--limit <数量>` | int | 分页限制（默认：`20`） |

## function compile

将单个函数扩展的 `src/index.js` 通过 javy 工具链编译为 WASM。

```shell
shoplazza app function compile [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--name <名称>` | string | `extensions/` 下的函数扩展名称（必填） |
| `--path <路径>` | string | 项目根目录（默认：`.`） |

## function release

编译并发布单个函数扩展。如需发布整个应用，请使用 `shoplazza app deploy`。

```shell
shoplazza app function release [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--name <名称>` | string | `extensions/` 下的函数扩展名称（必填） |
| `--client-id <id>` | string | 应用 Client ID（默认：当前活跃配置） |
| `--path <路径>` | string | 项目根目录（默认：`.`） |
| `--debug` | bool | 预留的调试模式标志（默认：`false`） |

## function list

列出当前应用的函数扩展。

```shell
shoplazza app function list [参数]
```

### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `--path <路径>` | string | 项目根目录（默认：`.`） |

## 配置文件

### shoplazza.app.toml

应用主配置文件：

```toml
# 应用 Client ID（必填）
client_id = "your-client-id"

# 应用权限作用域
scopes = "read_customer write_cart_transform"
```

### shoplazza.extension.toml

每个扩展有独立的配置文件：

```toml
# 扩展 ID（系统生成）
id = "extension-id"

# 扩展名称
name = "My Extension"

# 扩展类型（theme / checkout / function）
type = "theme"
```