WYF-koubo/docs/SYSTEM_TEMPLATES_USAGE_GUIDE.md

# 系统模板设置和使用指南

## 📍 在哪里创建系统模板？

现在您可以直接在现有的模板编辑器中创建系统模板，**无需创建专门的管理页面**。

---

## ✨ 新功能：在模板编辑器中设为系统模板

### 位置

**封面模板编辑器**

位置: `视频` → `创建视频` → `编辑封面模板`

或: 在 `CoverSettingsDialog` 中编辑封面模板

文件: `src/pages/Video/components/CoverCustomEditor/index.vue`

---

## 🎯 使用流程

### 第 1 步：编辑模板

1. 进入 **视频** 页面
2. 创建或编辑**封面模板**
3. 设计您的模板内容（使用 Canvas 编辑器）

### 第 2 步：设为系统模板（仅开发模式）

**⚠️ 仅在开发模式下可用**

在模板编辑器底部，您会看到：

```
┌──────────────────────────────────────────────┐
│ ✨ 设为系统模板                              │
│ （保存时自动导出到配置文件）                 │
│ [☐] ← 勾选此选项                            │
├──────────────────────────────────────────────┤
│                    [取消] [保存系统模板]      │
└──────────────────────────────────────────────┘
```

**如何使用:**

1. **创建新模板** → 设计内容
2. **勾选** "✨ 设为系统模板" 选项
3. **点击保存** → 系统会自动：
   - ✅ 保存到数据库
   - ✅ 导出到 `system-templates.json`
   - ✅ 显示成功提示

### 第 3 步：验证导出

保存成功后，会看到提示：

```
✅ 系统模板已保存并自动导出到配置文件
```

模板已自动导出到: `electron/config/system-templates.json`

---

## 🔄 工作流程图

```
┌─────────────────────────┐
│   打开封面模板编辑器    │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│   编辑模板（设计内容）  │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│  在开发模式下？         │
└────┬──────────────┬─────┘
     │ 是           │ 否
     ▼              ▼
  ✅ 显示          ❌ 不显示
  系统模板选项     系统模板选项
     │              │
     └──────┬───────┘
            │
            ▼
    ┌────────────────┐
    │ 勾选系统模板   │
    └────────┬───────┘
             │ (可选)
             ▼
  ┌────────────────────┐
  │ 点击"保存系统模板" │
  └────────┬───────────┘
           │
           ▼
  ┌─────────────────────────┐
  │ 后端处理：              │
  │ 1. 保存到 data.db      │
  │ 2. 导出到 JSON 文件    │
  └────────┬────────────────┘
           │
           ▼
  ┌─────────────────────────┐
  │ ✅ 系统模板已保存       │
  │    并自动导出!          │
  └─────────────────────────┘
           │
           ▼
  ┌─────────────────────────┐
  │ 重启应用后:             │
  │ 自动加载此系统模板      │
  └─────────────────────────┘
```

---

## 📋 功能说明

### 开发模式检测

系统会自动检测您是否在开发模式：

```typescript
// 开发模式 ✅
npm run dev:win
npm run dev:mac

// 生产模式 ❌
npm run build:win
npm run build:mac
export ELECTRON_ENV_PROD=1
```

**只有在开发模式下，才会显示"设为系统模板"选项。**

---

## 🔒 生产模式保护

### 生产环境中的行为

在生产模式下：

✅ **系统模板是只读的**
- 用户无法编辑系统模板
- 无法看到"设为系统模板"选项
- 系统模板被标记为 `readonly=1`

✅ **用户可以创建自己的模板**
- 自定义模板保存到数据库
- 不会自动导出到 JSON
- 用户可以编辑和删除自己的模板

---

## 💾 自动导出机制

### 什么被导出？

当您勾选"设为系统模板"并保存时：

```json
{
  "version": "1.0.0",
  "description": "系统内置模板配置",
  "timestamp": "2026-01-15T...",
  "subtitleTemplates": [ /* ... */ ],
  "coverTemplates": [
    {
      "id": "your_template_id",
      "name": "您的模板名称",
      "description": "模板描述",
      "is_system": 1,
      "readonly": 0,
      "config": { /* 完整的模板配置 */ },
      "createdAt": 1768396885438
    }
    // ... 其他系统模板
  ]
}
```

### 文件位置

导出位置: `electron/config/system-templates.json`

### 什么时候导出？

- ✅ 保存时自动导出（勾选了"设为系统模板"）
- ✅ 修改系统模板时自动导出
- ✅ 每次导出都会更新时间戳

---

## 🔧 技术细节

### 修改的文件

**`src/pages/Video/components/CoverCustomEditor/index.vue`**

新增功能：
- 开发模式检测 (`useDevMode()`)
- 系统模板选项 (`isSystemTemplate` ref)
- 自动导出逻辑 (`saveCoverTemplateWithAutoExport()`)
- 保存时的条件判断

新增状态变量：
```typescript
const { isDev } = useDevMode();           // 开发模式检测
const isSystemTemplate = ref(false);      // 系统模板选项
const isSaving = ref(false);              // 保存状态
```

新增保存逻辑：
```typescript
if (isSystemTemplate.value && isDev) {
  // 使用自动导出 API 保存系统模板
  await saveCoverTemplateWithAutoExport({...});
} else {
  // 普通模板保存
  await saveCoverTemplate({...});
}
```

### 相关 API

**前端 API** (`src/api/systemTemplates.ts`):
- `saveCoverTemplateWithAutoExport(template)` - 保存并自动导出
- `saveSubtitleTemplateWithAutoExport(template)` - 字幕模板（如适用）
- `isDevMode()` - 检查开发模式

**后端 IPC** (`electron/mapi/subtitleCover/`):
- `systemTemplates:saveCoverAndExport` - IPC 处理程序
- `saveCoverTemplateAndExport()` - 后端实现

**Composable** (`src/composables/useDevMode.ts`):
- `useDevMode()` - 开发模式检测 hook

---

## 📊 模板数据结构

### 覆盖模板配置示例

```typescript
{
  // 基础信息
  id: "template_custom_1234567890",
  name: "我的系统模板",
  description: "这是一个自定义的系统模板",

  // 系统标记
  is_system: 1,           // 1=系统模板, 0=用户模板
  readonly: 0,            // 1=只读(生产), 0=可编辑(开发)

  // 时间戳
  created_at: 1768396885438,
  updated_at: 1768396885438,

  // 完整的设计配置
  config: {
    name: "我的系统模板",
    backgroundEnabled: true,
    backgroundBlurEnabled: true,
    backgroundBlurIntensity: 10,
    // ... 其他 1000+ 个配置字段
    titleText: "标题",
    subtitleText: "副标题",
    // ... 完整的封面配置
  },

  // 可选
  thumbnailPath: "/path/to/thumbnail.png"
}
```

---

## ✅ 验证导出成功

### 方法 1：检查文件变化

```bash
# 检查 system-templates.json 文件是否已更新
ls -la electron/config/system-templates.json

# 查看文件内容（搜索您的模板 ID）
cat electron/config/system-templates.json | grep "your_template_id"
```

### 方法 2：查看浏览器控制台

保存系统模板时，会输出日志：

```
[CoverCustomEditor] 保存为系统模板: template_custom_1234567890
[CoverCustomEditor] 系统模板已导出: template_custom_1234567890
```

### 方法 3：检查数据库

```sql
-- 检查数据库中的系统模板
SELECT id, name, is_system, readonly FROM cover_templates
WHERE is_system = 1
ORDER BY created_at DESC;

-- 输出示例：
-- id                          name                is_system  readonly
-- template_custom_1234567890  我的系统模板         1         0
```

---

## 🚀 下次启动时的行为

### 应用启动流程

```
1️⃣  应用启动
    ↓
2️⃣  initSystemTemplates() 运行
    ├─ 读取 system-templates.json
    └─ 初始化数据库
    ↓
3️⃣  您的系统模板被加载
    ├─ is_system = 1（标记为系统模板）
    ├─ readonly = 0（开发模式可编辑）
    └─ 完整的配置被加载到数据库
    ↓
4️⃣  应用正常运行
    └─ 您的系统模板可以被选择和使用
```

### 生产模式下

```
1️⃣  应用启动
2️⃣  initSystemTemplates() 运行
3️⃣  您的系统模板被加载
    └─ readonly = 1（设为只读）
4️⃣  用户无法编辑系统模板
    ├─ UI 不显示编辑选项
    ├─ IPC 调用被拒绝
    └─ 数据库标记为只读
```

---

## 🎁 额外特性

### 自动导出失败处理

如果导出到 JSON 失败：

✅ **保存操作仍然成功**
- 数据已保存到数据库
- 只是 JSON 导出失败
- 后端会记录警告日志

❌ **不会中断保存过程**

示例：
```
[CoverCustomEditor] 保存为系统模板: template_id
[CoverCustomEditor] 系统模板已导出: template_id
✅ 系统模板已保存并自动导出到配置文件
```

### 时间戳自动更新

每次导出都会自动更新时间戳：

```json
{
  "timestamp": "2026-01-15T14:30:45.123Z",
  // ... 其他字段
}
```

---

## 📝 常见问题

### Q1：在哪里找到系统模板选项？

**A:** 在模板编辑器底部，只有在**开发模式**下才会显示。

```
开发模式: npm run dev:win
查看位置: 底部按钮上方
```

### Q2：为什么看不到系统模板选项？

**A:** 可能原因：

1. ❌ 不在开发模式
   ```bash
   # 检查是否开发模式
   npm run dev:win  # ✅ 正确
   npm run build:win  # ❌ 这是生产构建
   ```

2. ❌ 设置了生产环境变量
   ```bash
   unset ELECTRON_ENV_PROD  # 清除环境变量
   ```

### Q3：系统模板和普通模板的区别？

| 特性 | 系统模板 | 普通模板 |
|------|--------|--------|
| 开发模式可编辑 | ✅ | ✅ |
| 生产模式只读 | ✅ | ❌ |
| 自动导出到 JSON | ✅ | ❌ |
| 包含在发行版中 | ✅ | ❌ |
| 用户可删除 | ❌ | ✅ |
| is_system 标记 | 1 | 0 |

### Q4：如何修改已保存的系统模板？

**A:** 再次编辑并保存：

1. 打开模板编辑器
2. 修改内容
3. **再次勾选** "✨ 设为系统模板"
4. 点击保存
5. 配置文件会自动更新

---

## 🎓 工作原理总结

### 简化流程

```
编辑模板 + 勾选"系统模板" + 点保存
           ↓
    自动执行后端逻辑
    ├─ 保存到 data.db
    ├─ 导出到 system-templates.json
    └─ 更新时间戳
           ↓
    重启应用时
    ├─ 从 JSON 加载配置
    └─ 初始化到数据库
           ↓
    ✅ 系统模板被成功保留
```

### 关键优势

✨ **无需手动导出** - 自动完成
✨ **不需要新页面** - 复用现有编辑器
✨ **开发友好** - 编辑即导出
✨ **生产安全** - 系统模板只读

---

## 📞 技术支持

### 查看日志

**浏览器控制台:**
```
F12 → Console → 搜索 [CoverCustomEditor]
```

**应用日志:**
```
electron/mapi/log/main.ts
搜索关键字: saveSubtitleTemplateAndExport, saveCoverTemplateAndExport
```

### 调试

```typescript
// 检查开发模式
console.log('isDev:', isDev.value);

// 检查系统模板选项
console.log('isSystemTemplate:', isSystemTemplate.value);

// 检查导出结果
console.log('[CoverCustomEditor] 系统模板已导出');
```

---

## 🎉 总结

现在您可以：

1. ✅ 在模板编辑器中创建和设计系统模板
2. ✅ 勾选选项自动导出到 JSON
3. ✅ 重启应用后自动加载系统模板
4. ✅ 生产版本中系统模板保持只读
5. ✅ 无需创建专门的管理页面

**就这么简单！** 🚀