Initial clean project import

2026-06-19 18:41:41 +08:00
commit a13b804c7a
1306 changed files with 220568 additions and 0 deletions
@@ -0,0 +1,424 @@
+# 系统模板管理指南
+
+## 概述
+
+系统模板（字幕和封面）现在支持以下功能：
+- 📁 保存在 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)
+- ✅ 创建系统模板配置文件
+- ✅ 实现导出功能
+- ✅ 添加开发/生产模式区分
+- ✅ 支持打包时包含配置文件
+- ✅ 实现生产模式只读保护