WYF-koubo/docs/SYSTEM_TEMPLATES_GUIDE.md

系统模板管理指南

概述

系统模板（字幕和封面）现在支持以下功能：

• 📁 保存在 JSON 配置文件中
• 🎨 开发模式下可以编辑
• 📦 打包时包含在发行版中
• 🔒 生产模式下用户无法修改

---

文件结构

关键文件

C:\aigcpanel-main\
├── electron/
│   ├── config/
│   │   └── system-templates.json          # ⭐ 系统模板配置文件
│   ├── mapi/
│   │   ├── db/
│   │   │   ├── migration.ts              # 数据库迁移 v23
│   │   │   └── initSystemTemplates.ts    # 初始化逻辑
│   │   └── subtitleCover/
│   │       ├── main.ts                   # 导出/管理实现
│   │       └── register.ts               # IPC 接口注册
├── src/
│   └── api/
│       └── systemTemplates.ts            # 前端 API 包装
└── scripts/
    └── export-system-templates.js        # 导出脚本

---

工作流程

1. 开发模式：编辑系统模板

方法 A：在应用中编辑并导出

import {
  getSystemTemplatesList,
  saveSystemTemplate,
  exportSystemTemplatesToFile,
  isDevMode
} from '@/api/systemTemplates';

// 检查是否开发模式
if (isDevMode()) {
  // 获取现有模板
  const result = await getSystemTemplatesList();
  console.log('系统模板:', result.templates);

  // 编辑字幕模板（例如：设置颜色）
  await saveSystemTemplate({
    type: 'subtitle',
    id: 'template_system_11',
    name: '11',
    description: '系统字幕模板 11',
    config: {
      subtitleStyleId: 'system-subtitle-11',
      subtitlePosition: 'bottom',
      // ... 其他配置
      subtitleStyle: {
        fontColor: '#FFFFFF',  // 普通字幕颜色
        // ... 其他字体设置
      }
    }
  });

  // 导出配置到文件（覆盖 system-templates.json）
  const exportResult = await exportSystemTemplatesToFile();
  if (exportResult.success) {
    console.log('✅ 配置已导出到:', exportResult.filePath);
  }
}

方法 B：使用 Node 脚本导出

# 从数据库导出所有系统模板配置到 system-templates.json
node scripts/export-system-templates.js

这个脚本会：

1. 连接到应用数据库
2. 读取所有系统模板配置（包括你设置的颜色）
3. 导出到 electron/config/system-templates.json

2. 打包生产版本

# 自动复制 system-templates.json 到打包资源中
npm run build:win

# 或者
npm run build:mac

打包流程：

1. ✅ 执行 prepare-package.cjs 脚本
2. ✅ 复制 system-templates.json → resources/extra/common/config/
3. ✅ 用户安装应用后，自动初始化数据库
4. ✅ 生产模式设置 readonly=1，用户无法修改

3. 生产模式：用户安装应用

用户安装后：

• ✅ 应用启动时自动从 JSON 初始化 8 套系统模板
• ✅ 字幕和封面模板都加载到数据库
• ✅ 系统模板标记为只读，用户无法编辑/删除
• ✅ 用户可以创建自己的自定义模板

---

API 参考

前端 API

getSystemTemplatesList()

获取系统模板列表

const result = await getSystemTemplatesList();
// 返回: { success: boolean, templates: { subtitleTemplates: [], coverTemplates: [] } }

saveSystemTemplate(template)

保存/编辑系统模板（开发模式）

const template = {
  type: 'subtitle' | 'cover',
  id: 'template_system_11',
  name: '11',
  description: 'Description',
  config: { /* 配置对象 */ },
  thumbnailPath: '/path/to/thumbnail.png'  // 仅 cover 类型
};

const result = await saveSystemTemplate(template);
// 返回: { success: boolean, id: string, message: string }

resetSystemTemplates()

重置为默认值（开发模式）

const result = await resetSystemTemplates();
// 返回: { success: boolean, message: string }

exportSystemTemplatesToFile()

导出配置到 JSON 文件（开发模式）

const result = await exportSystemTemplatesToFile();
// 返回: { success: boolean, filePath: string, message: string }

isDevMode()

检查是否开发模式

if (isDevMode()) {
  // 开发模式逻辑
}

后端 IPC 接口

systemTemplates:getList      // 获取模板列表
systemTemplates:save         // 保存模板
systemTemplates:delete       // 删除模板
systemTemplates:reset        // 重置模板
systemTemplates:export       // 导出到文件

---

常见场景

场景 1：更新系统模板的颜色设置

1. 在应用中编辑字幕模板的颜色
2. 调用 exportSystemTemplatesToFile() 导出
3. 提交 system-templates.json 到 Git
4. 下次打包时，新颜色会包含在发行版中

场景 2：添加新的系统模板

1. 在应用中创建新模板
2. 调用 saveSystemTemplate() 保存
3. 调用 exportSystemTemplatesToFile() 导出
4. 更新版本号和时间戳
5. 打包发行

场景 3：重置系统模板

1. 调用 resetSystemTemplates() 重置数据库
2. 调用 exportSystemTemplatesToFile() 导出当前配置
3. 用户将恢复到默认的 8 套系统模板

---

数据库架构

subtitle_templates 表

CREATE TABLE subtitle_templates (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT,
  config TEXT,                -- JSON 格式配置
  is_system INTEGER DEFAULT 0, -- 1=系统模板, 0=用户模板
  readonly INTEGER DEFAULT 0,  -- 1=只读(生产模式), 0=可编辑(开发模式)
  created_at INTEGER,
  updated_at INTEGER
);

cover_templates 表

CREATE TABLE cover_templates (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  config TEXT,                -- JSON 格式配置
  is_system INTEGER DEFAULT 0, -- 1=系统模板, 0=用户模板
  readonly INTEGER DEFAULT 0,  -- 1=只读(生产模式), 0=可编辑(开发模式)
  thumbnail_path TEXT,
  created_at INTEGER,
  updated_at INTEGER
);

---

开发模式标志

检查开发/生产模式

// 方法 1：前端
import { isDevMode } from '@/api/systemTemplates';
const isDev = isDevMode();

// 方法 2：后端
function isProductionMode(): boolean {
  return process.env.ELECTRON_ENV_PROD === '1' ||
         process.env.NODE_ENV === 'production' ||
         !process.env.DEV;
}

启动开发模式

# Windows
npm run dev:win

# macOS
npm run dev:mac

# 预发布模式（仍可编辑系统模板）
npm run dev:win:pre
npm run dev:mac:pre

启动生产模式

# 直接设置环境变量为生产模式
set ELECTRON_ENV_PROD=1  # Windows
export ELECTRON_ENV_PROD=1  # macOS/Linux
npm run dev:win

---

JSON 配置文件格式

{
  "version": "1.0.0",
  "description": "系统内置模板配置 - 包含8套字幕模板和8套封面模板",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "subtitleTemplates": [
    {
      "id": "template_system_11",
      "name": "11",
      "description": "系统字幕模板 11",
      "isSystem": true,
      "readonly": false,
      "createdAt": 1768396885438,
      "config": {
        "subtitleStyleId": "system-subtitle-11",
        "subtitlePosition": "bottom",
        "subtitleStyle": {
          "fontColor": "#FFFFFF",
          "outlineColor": "#000000",
          "outlineWidth": 3,
          "fontSize": 48
        }
        // ... 其他配置
      }
    }
    // ... 其他7个字幕模板
  ],
  "coverTemplates": [
    // ... 8个封面模板
  ]
}

---

安全性注意事项

✅ 开发模式保护

• API 调用前检查 isDev 标志
• 编辑后立即导出到文件
• 配置文件纳入版本控制

🔒 生产模式保护

• 系统模板标记为 readonly=1
• IPC 接口检查开发/生产模式
• 用户无法编辑/删除系统模板
• 只能创建自己的自定义模板

🔄 版本管理

• 每次导出时更新 timestamp
• 增加版本号时更新 version
• 在 Git 中追踪 system-templates.json 的变化

---

故障排查

问题：编辑的颜色没有保存到文件

解决：

// 1. 确保在开发模式
console.log('开发模式:', isDevMode());

// 2. 确认编辑已保存到数据库
const list = await getSystemTemplatesList();
console.log('当前模板:', list.templates);

// 3. 手动导出到文件
const result = await exportSystemTemplatesToFile();
console.log('导出结果:', result);

问题：生产模式仍然可以编辑系统模板

解决：

// 检查环境变量
console.log('ELECTRON_ENV_PROD:', process.env.ELECTRON_ENV_PROD);
console.log('NODE_ENV:', process.env.NODE_ENV);

// 检查数据库中的 readonly 标记
// SELECT * FROM subtitle_templates WHERE is_system = 1;
// 应该看到 readonly = 1

问题：导出脚本找不到数据库

解决：

# 确保应用已启动过至少一次，创建了数据库
# 检查数据库位置：
# Windows: %APPDATA%\zhenqianba\data.db
# macOS: ~/Library/Application Support/zhenqianba/data.db
# Linux: ~/.config/zhenqianba/data.db

# 或者手动指定数据库路径：
node scripts/export-system-templates.js --db-path /path/to/data.db

---

最佳实践

1. 定期导出：每次编辑系统模板后都导出
2. 版本控制：将 system-templates.json 提交到 Git
3. 备份配置：发行前备份 system-templates.json
4. 测试生产模式：确保生产版本中系统模板是只读的
5. 文档更新：模板变化时更新 description 字段

---

相关文件

• 配置文件：electron/config/system-templates.json
• 前端 API：src/api/systemTemplates.ts
• 后端实现：electron/mapi/subtitleCover/main.ts
• 数据库初始化：electron/mapi/db/initSystemTemplates.ts
• 迁移脚本：electron/mapi/db/migration.ts (v23)
• 打包脚本：scripts/prepare-package.cjs
• 导出脚本：scripts/export-system-templates.js

---

更新历史

v1.0.0 (2026-01-15)

• ✅ 创建系统模板配置文件
• ✅ 实现导出功能
• ✅ 添加开发/生产模式区分
• ✅ 支持打包时包含配置文件
• ✅ 实现生产模式只读保护