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：在应用中编辑并导出

```typescript
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 脚本导出

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

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

### 2. 打包生产版本

```bash
# 自动复制 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()`
获取系统模板列表

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

#### `saveSystemTemplate(template)`
保存/编辑系统模板（开发模式）

```typescript
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()`
重置为默认值（开发模式）

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

#### `exportSystemTemplatesToFile()`
导出配置到 JSON 文件（开发模式）

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

#### `isDevMode()`
检查是否开发模式

```typescript
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 表

```sql
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 表

```sql
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
);
```

---

## 开发模式标志

### 检查开发/生产模式

```typescript
// 方法 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;
}
```

### 启动开发模式

```bash
# Windows
npm run dev:win

# macOS
npm run dev:mac

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

### 启动生产模式

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

---

## JSON 配置文件格式

```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` 的变化

---

## 故障排查

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

**解决：**
```typescript
// 1. 确保在开发模式
console.log('开发模式:', isDevMode());

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

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

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

**解决：**
```typescript
// 检查环境变量
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
```

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

**解决：**
```bash
# 确保应用已启动过至少一次，创建了数据库
# 检查数据库位置：
# 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)
- ✅ 创建系统模板配置文件
- ✅ 实现导出功能
- ✅ 添加开发/生产模式区分
- ✅ 支持打包时包含配置文件
- ✅ 实现生产模式只读保护