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 文件    │
  └────────┬────────────────┘
           │
           ▼
  ┌─────────────────────────┐
  │ ✅ 系统模板已保存       │
  │    并自动导出!          │
  └─────────────────────────┘
           │
           ▼
  ┌─────────────────────────┐
  │ 重启应用后:             │
  │ 自动加载此系统模板      │
  └─────────────────────────┘

---

📋 功能说明

开发模式检测

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

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

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

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

---

🔒 生产模式保护

生产环境中的行为

在生产模式下：

✅ 系统模板是只读的

• 用户无法编辑系统模板
• 无法看到"设为系统模板"选项
• 系统模板被标记为 readonly=1

✅ 用户可以创建自己的模板

• 自定义模板保存到数据库
• 不会自动导出到 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())
• 保存时的条件判断

新增状态变量：

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

新增保存逻辑：

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

---

📊 模板数据结构

覆盖模板配置示例

{
  // 基础信息
  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：检查文件变化

# 检查 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：检查数据库

-- 检查数据库中的系统模板
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
✅ 系统模板已保存并自动导出到配置文件

时间戳自动更新

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

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

---

📝 常见问题

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

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

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

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

A: 可能原因：

1. ❌ 不在开发模式

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

2. ❌ 设置了生产环境变量

   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

调试

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

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

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

---

🎉 总结

现在您可以：

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

就这么简单！ 🚀