批量创建页面功能配置指南

## 概述

批量创建页面功能允许模板定义一个专门的界面，让用户能够批量导入/创建页面。这个功能通过在模板的 `schema` 中配置 `batch_create_url` 来实现。
使站点在管理端中可以按需提供批量创建页面的功能。

## 工作流程

### 系统交互流程

```
1. 用户在页面管理界面中点击"批量创建"按钮
   ↓
2. 系统获取该页面的模板及其子模板信息
   ↓
3. 如果子模板的 schema 中配置了 batch_create_url，则显示批量创建选项
   ↓
4. 用户点击某个模板的批量创建选项
   ↓
5. 系统生成包含认证信息的 batch_create_url 并在 iframe 中打开
   ↓
6. 用户在 iframe 中进行批量导入操作
   ↓
7. iframe 中的页面通过 API 调用创建页面
```

## 配置步骤

### 1. 在模板 Schema 中添加 `batch_create_url`

在你的 `.liquid` 模板文件中，在 `{% schema %}` 部分添加 `batch_create_url` 配置：

```liquid
{% schema %}
  {
    "name": "页面模板名称",
    "description": "页面模板描述",
    "batch_create_url": "https://your-import-service.com/batch_import", // 或者 "/s/batch_import"（模版中静态地址）
    "settings": [
      // ... 其他模板设置
    ]
  }
{% endschema %}
```

### 2. `batch_create_url` 的两种形式

#### 2.1 绝对 URL（推荐用于外部服务）

```json
{
  "batch_create_url": "https://external-service.com/batch_import"
}
```

绝对 URL 使用完整的 http/https 地址。系统会自动追加以下查询参数：
- `token`: 用户的临时 API token（JWT 格式）
- `site_id`: 当前站点 ID
- `full_path`: 父页面的完整路径
- `template_name`: 模板名称
- `template_style`: 模板风格

**示例生成的 URL：**
```
https://external-service.com/batch_import?
  token=JWT+eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE3NzAyOTY1NTh9...
  &site_id=34
  &full_path=%2F80ec12
  &template_name=page
  &template_style=style
```

#### 2.2 相对路径 URL（建议页面构建在模版中静态页面中）

```json
{
  "batch_create_url": "/s/batch_import"
}
```

相对路径会被转换为完整的站点门户 URL。系统会使用站点的门户地址作为基础 URL，并追加相同的查询参数。

**示例生成的 URL：**
```
http://site-demo.baklib.localhost:3000/s/batch_import?
  token=JWT+eyJhbGciOiJIUzI1NiJ9...
  &site_id=34
  &full_path=%2Fparent
  &template_name=page
  &template_style=style
```

### 3. 完整的模板配置示例

```liquid
{%
  # 模板的 HTML/Liquid 内容
%}

{% schema %}
  {
    "name": "数据批量导入页面",
    "description": "支持批量创建页面的模板",
    "thumb_url": "images/theme/batch_import_page.png",
    "batch_create_url": "https://api.example.com/pages/batch_import",
    "settings": [
      {
        "id": "title",
        "type": "text",
        "label": "页面标题"
      },
      {
        "id": "description",
        "type": "richtext",
        "label": "页面描述"
      },
      {
        "id": "enable_batch_import",
        "type": "checkbox",
        "label": "启用批量导入",
        "default": true
      }
    ]
  }
{% endschema %}
```

## 在批量创建 iframe 中的操作

### 接收的查询参数

当 iframe 中的页面加载时，会收到以下查询参数：

| 参数 | 说明 | 示例 |
|------|------|------|
| `token` | JWT 格式的 API 认证 token | `JWT eyJhbGciOiJIUzI1NiJ9...` |
| `site_id` | 站点的数字 ID | `34` |
| `full_path` | 父页面的完整路径（URL 编码） | `%2F80ec12` |
| `template_name` | 模板名称 | `page` |
| `template_style` | 模板风格 | `style` |

### 调用 API 创建页面

iframe 中的页面可以通过以下 Baklib API 创建新页面：
> baklib api接口文档： https://dev.baklib.cn/api#/paths/sites-site_id--pages/post

## 最佳实践

### 1. 选择合适的 URL 类型

- **外部服务**：使用绝对 URL（完整的 http/https 地址）
- **站点内部**：使用相对路径（以 `/` 开头）

### 2. 安全考虑

- 传递给 iframe 的 `token` 是临时 API token，有过期时间限制
- 确保你的批量创建服务在安全的 HTTPS 连接上运行
- 验证 `site_id` 和 `full_path` 参数的有效性

### 3. 用户体验

- 在模板中明确说明支持批量创建功能
- 在 `batch_create_url` 指向的页面中提供清晰的导入说明
- 实现进度提示和错误处理

### 4. 模板命名规范

- `template_name`: 模板的基础名称（如 `page`, `article`）
- `template_style`: 模板的风格变体（如 `default`, `dark`, `compact`）

## 故障排查

### 问题：批量创建选项不显示

**可能原因：**
- 模板的 schema 中没有配置 `batch_create_url`
- `batch_create_url` 值为空或 `null`
- 子模板没有正确关联到父模板

**解决方案：**
1. 检查模板文件中的 `schema` 部分
2. 确保 `batch_create_url` 有有效的值
3. 验证模板的 `sub_page_templates` 配置

### 问题：iframe 加载失败

**可能原因：**
- URL 解析错误
- 网络不可达
- CORS 跨域问题

**解决方案：**
1. 检查浏览器控制台的错误信息
2. 验证 URL 是否正确生成
3. 确保批量创建服务正在运行
4. 检查是否配置了适当的 CORS 头

### 问题：无法创建页面

**可能原因：**
- API token 已过期
- 用户权限不足
- API 参数格式错误

**解决方案：**
1. 刷新页面重新获取 token
2. 检查用户是否有页面创建权限
3. 验证 API 请求体格式是否正确