# Workflow Template Export/Import

## 概述 Overview

这是一个独立的脚本工具，用于导出和导入工作流模板（表单模板和打印模板），支持从 Blaze 格式转换为 Liquid 格式。

This is a standalone script tool for exporting and importing workflow templates (form templates and print templates), supporting conversion from Blaze to Liquid format.

## 安装 Installation

在运行脚本前，需要先安装依赖：
Before running the script, install dependencies:

```bash
cd steedos-packages/plugin-workflow
npm install
```

脚本使用原生 MongoDB 驱动连接数据库，连接信息从环境变量 `MONGO_URL` 读取。
The script uses native MongoDB driver to connect to the database. Connection info is read from `MONGO_URL` environment variable.

## 快速开始 Quick Start

```bash
cd steedos-packages/plugin-workflow

# 导出所有模板 Export all templates
node run.js export

# 导出特定流程 Export specific flow
node run.js export <flowId>

# 转换 .blaze 文件为 .liquid (手动或使用 Copilot)
# Convert .blaze files to .liquid (manually or with Copilot)

# 导入转换后的模板 Import converted templates
node run.js import <flowId>
```

## 目录结构 Directory Structure

```
flows-template/
├── {flowId}.instance_template.blaze    # 导出的表单模板 (Blaze 格式)
├── {flowId}.print_template.blaze       # 导出的打印模板 (Blaze 格式)
├── {flowId}.fields.json                # 字段定义
├── {flowId}.instance_template.liquid   # 转换后的表单模板 (Liquid 格式，用于导入)
└── {flowId}.print_template.liquid      # 转换后的打印模板 (Liquid 格式，用于导入)
```

## 命令使用 Commands

### 导出模板 Export Templates

```bash
# 导出所有包含模板的流程
# Export all flows with templates
node run.js export

# 导出特定流程
# Export specific flow
node run.js export <flowId>

# 导出到自定义目录
# Export to custom directory
node run.js export <flowId> /path/to/output
```

**示例 Example:**
```bash
node run.js export abc123
```

**输出 Output:**
```
Found 1 flow(s) to export.

Exporting flow: Leave Request (abc123)
  ✓ abc123.instance_template.blaze
  ✓ abc123.print_template.blaze
  ✓ abc123.fields.json
  Exported 3 file(s)

✅ Export completed. Files saved to: /path/to/flows-template
```

### 导入模板 Import Templates

```bash
# 导入流程的所有模板
# Import both templates for a flow
node run.js import <flowId>

# 仅导入表单模板
# Import only instance_template
node run.js import <flowId> instance_template

# 仅导入打印模板
# Import only print_template
node run.js import <flowId> print_template

# 从自定义目录导入
# Import from custom directory
node run.js import <flowId> instance_template /path/to/input
```

**示例 Example:**
```bash
node run.js import abc123
```

**输出 Output:**
```
Importing templates for flow: Leave Request (abc123)
  ℹ Backing up old instance_template to instance_template_backup
  ✓ Imported instance_template from abc123.instance_template.liquid
  ℹ Backing up old print_template to print_template_backup
  ✓ Imported print_template from abc123.print_template.liquid

✅ Import completed. Imported 2 template(s).
  - instance_template: updated (old value backed up)
  - print_template: updated (old value backed up)
```

## 工作流程 Workflow

1. **导出 Export**: 运行导出命令，将模板保存为 `.blaze` 文件
2. **转换 Convert**: 使用 Copilot 或其他工具将 `.blaze` 文件转换为 `.liquid` 格式
3. **导入 Import**: 运行导入命令，将转换后的 `.liquid` 模板加载回数据库
4. **备份 Backup**: 导入时自动备份旧模板到 `{模板名}_backup` 字段

## 备份字段 Backup Fields

导入模板时，旧值会自动备份到：
When importing templates, old values are backed up to:

- `instance_template_backup`: 表单模板备份 (Form template backup)
- `print_template_backup`: 打印模板备份 (Print template backup)

这些备份字段在界面中隐藏，但可以通过程序访问。
These backup fields are hidden in the UI but can be accessed programmatically.

## 字段定义 Field Definitions

`.fields.json` 文件包含表单的字段定义（来自 `current.fields`），为模板转换工具（如 Copilot）提供字段结构和类型的上下文信息。

The `.fields.json` file contains field definitions from the form's `current.fields`, providing context about field structure and types for conversion tools like Copilot.

**示例 Example:**
```json
[
  {
    "_id": "field1",
    "code": "userName",
    "name": "User Name",
    "type": "text",
    "is_required": true
  },
  {
    "_id": "field2",
    "code": "requestDate",
    "name": "Request Date",
    "type": "date",
    "is_required": true
  }
]
```

## 数据库配置 Database Configuration

脚本使用环境变量配置的 MongoDB 连接（通过 `.env` 文件中的 `MONGO_URL`）。

The script uses the MongoDB connection configured via environment variables (through `MONGO_URL` in `.env` file).

## 错误处理 Error Handling

脚本提供清晰的错误信息：
The script provides clear error messages:

- `Flow not found: abc123` - 验证流程 ID 是否存在 (Verify the flow ID exists)
- `No template files found for flow abc123` - 确保 `.liquid` 文件存在 (Ensure `.liquid` files exist)
- `Permission denied reading file` - 检查文件权限 (Check file permissions)
- `No flows found with templates` - 没有包含模板的流程 (No flows have templates)

## 使用提示 Tips

1. 导入模板前务必备份数据库 (Always backup your database before importing)
2. 旧模板值会自动备份到 `{模板名}_backup` 字段 (Old values are automatically backed up)
3. 先在开发环境测试导入 (Test imports in development environment first)
4. 使用字段定义了解模板结构 (Use field definitions to understand template structure)
5. 导入前仔细检查转换后的模板 (Review converted templates carefully before importing)
6. `flows-template` 目录自动被 git 忽略 (The directory is automatically ignored by git)

## 完整示例 Complete Example

```bash
# 1. 导出模板 Export templates
cd steedos-packages/plugin-workflow
node run.js export abc123

# 2. 查看导出的文件 View exported files
ls -la flows-template/
# abc123.instance_template.blaze
# abc123.print_template.blaze
# abc123.fields.json

# 3. 转换模板 Convert templates
# 使用 Copilot 或手动将 .blaze 文件转换为 .liquid
# Use Copilot or manually convert .blaze files to .liquid
# 
# 示例转换 Example conversion:
# {{#if userName}} → {% if userName %}
# {{userName}} → {{ userName }}
# {{/if}} → {% endif %}

# 4. 导入转换后的模板 Import converted templates
node run.js import abc123

# 5. 验证 Verify
# 检查数据库中的 flows 记录，确认模板已更新且备份已创建
# Check flows record in database to confirm templates are updated and backups are created
```
