docs: reorganize docs into guide/ and electron/, add 6 new guide docs, update README

docs/electron/packaging-guide.md

@@ -0,0 +1,269 @@
+# Electron 打包完整指南
+
+## 概述
+
+本指南介绍如何将 Vue/HTML 项目打包成 Electron 应用，采用**本地服务器方案**，无需修改源码。
+
+## 核心优势
+
+✅ **零源码修改** - 项目代码完全不需要改动
+✅ **自动端口查找** - 自动处理端口冲突（9527-9999）
+✅ **跨平台兼容** - 浏览器和 Electron 都能正常工作
+✅ **易于维护** - 打包逻辑集中在 Electron 目录
+✅ **性能优秀** - 本地服务器响应快速
+
+## 项目结构
+
+```
+branch-engine/
+├── dist/                    # 构建输出目录
+├── electron/                # Electron 相关文件
+│   ├── main.js             # 主进程入口
+│   ├── server.js           # 本地服务器
+│   └── package.json        # Electron 依赖
+├── scripts/
+│   ├── prepare-electron.cjs # 打包前准备
+│   └── pack-html.cjs       # HTML 打包
+├── src/                    # Vue 源码
+├── editor/                 # 编辑器
+└── package.json            # 主项目配置
+```
+
+## 工作原理
+
+### 开发环境
+```
+npm run dev
+↓
+Vite 开发服务器 (localhost:5173)
+↓
+浏览器访问 → 正常工作 ✅
+```
+
+### 打包环境
+```
+npm run pack:win
+↓
+1. npm run build (生成 dist)
+2. 复制 dist 到 electron
+3. 启动 Express 服务器 (localhost:9527-9999)
+4. Electron 加载 http://127.0.0.1:PORT ✅
+```
+
+## 详细步骤
+
+### 1. 安装依赖
+
+```bash
+# 主项目依赖
+npm install
+
+# Electron 依赖
+cd electron
+npm install express
+```
+
+### 2. 开发
+
+```bash
+# 启动开发服务器
+npm run dev
+```
+
+### 3. 构建
+
+```bash
+# 构建 Vue 项目
+npm run build
+```
+
+### 4. 打包
+
+```bash
+# 打包 Windows 版本
+npm run pack:win
+
+# 打包 Mac 版本
+npm run pack:mac
+```
+
+### 5. 运行
+
+打包完成后，在 `release/` 目录下找到生成的应用：
+- Windows: `release/MyGame-win32-x64/MyGame.exe`
+- Mac: `release/MyGame-mas-x64/MyGame.app`
+
+## 核心文件说明
+
+### electron/main.js
+
+主进程入口，负责：
+- 启动本地服务器
+- 创建浏览器窗口
+- 加载应用
+- 处理应用生命周期
+
+### electron/server.js
+
+本地服务器，负责：
+- 自动查找可用端口（9527-9999）
+- 提供静态文件服务
+- 处理资源请求
+
+### scripts/prepare-electron.cjs
+
+打包前准备脚本，负责：
+- 将 dist 目录复制到 electron
+- 验证构建文件
+
+## 端口自动查找
+
+### 功能特性
+- 起始端口：9527
+- 最大端口：9999
+- 自动检测：逐个检测端口可用性
+- 冲突处理：自动跳过被占用的端口
+
+### 使用示例
+
+#### 正常情况
+```
+✅ Local server running at http://127.0.0.1:9527
+🚀 Loading app from: http://127.0.0.1:9527/index.html
+```
+
+#### 端口冲突
+```
+🔒 Port 9527 is blocked
+✅ Local server running at http://127.0.0.1:9528
+🚀 Loading app from: http://127.0.0.1:9528/index.html
+```
+
+## 配置选项
+
+### 修改端口范围
+
+编辑 `electron/server.js`:
+
+```javascript
+const START_PORT = 9527  // 起始端口
+const MAX_PORT = 9999    // 最大端口
+```
+
+### 修改窗口配置
+
+编辑 `electron/main.js`:
+
+```javascript
+const win = new BrowserWindow({
+  fullscreen: true,           // 全屏模式
+  autoHideMenuBar: true,      // 隐藏菜单栏
+  webPreferences: {
+    nodeIntegration: false,   // 禁用 node 集成
+    contextIsolation: true    // 启用上下文隔离
+  }
+})
+```
+
+## 常见问题
+
+### Q1: 打包后白屏
+**A:** 检查 dist 目录是否正确复制到 electron 目录。
+
+### Q2: 端口被占用
+**A:** 系统会自动查找下一个可用端口，无需手动处理。
+
+### Q3: 资源加载失败
+**A:** 确保使用绝对路径（如 `/scenes/config.json`），本地服务器会正确处理。
+
+### Q4: 开发者工具如何关闭
+**A:** 删除 `electron/main.js` 中的 `win.webContents.openDevTools()` 行。
+
+### Q5: 如何添加应用图标
+**A:** 在打包配置中添加图标文件路径。
+
+## 性能优化
+
+### 1. 减小包体积
+```bash
+# 使用 electron-builder 替代 electron-packager
+npm install --save-dev electron-builder
+```
+
+### 2. 启用代码压缩
+在 `vite.config.ts` 中配置：
+```typescript
+build: {
+  minify: 'terser',
+  terserOptions: {
+    compress: {
+      drop_console: true
+    }
+  }
+}
+```
+
+### 3. 优化资源加载
+- 使用 CDN 加载第三方库
+- 启用 gzip 压缩
+- 懒加载非关键资源
+
+## 安全建议
+
+1. **禁用 Node 集成**
+   ```javascript
+   webPreferences: {
+     nodeIntegration: false,
+     contextIsolation: true
+   }
+   ```
+
+2. **只监听本地地址**
+   ```javascript
+   server.listen(PORT, '127.0.0.1')
+   ```
+
+3. **验证用户输入**
+   - 检查 URL 参数
+   - 验证文件路径
+   - 防止 XSS 攻击
+
+## 调试技巧
+
+### 查看服务器日志
+```javascript
+console.log('Server started on port:', PORT)
+```
+
+### 查看网络请求
+打开开发者工具 → Network 标签，查看所有请求。
+
+### 查看控制台错误
+打开开发者工具 → Console 标签，查看错误信息。
+
+## 部署建议
+
+### 1. 代码签名
+```bash
+# Windows
+electron-builder --win --x64 --publish never
+
+# Mac
+electron-builder --mac --x64 --publish never
+```
+
+### 2. 自动更新
+使用 `electron-updater` 实现自动更新功能。
+
+### 3. 安装包配置
+在 `electron-builder.yml` 中配置安装选项。
+
+## 总结
+
+本方案采用**本地服务器 + 自动端口查找**的方式，完美解决了 Electron 打包中的路径问题，同时保持了源码的纯净性。这是一个简单、优雅、可维护的解决方案。
+
+## 相关文档
+
+- [Electron 官方文档](https://www.electronjs.org/docs)
+- [Express 文档](https://expressjs.com/)
+- [Vite 文档](https://vitejs.dev/)