feat: 初始化船长·HeiXiu 桌面应用项目（错误是svg的问题）

Electron + React 19 + TypeScript + Ant Design 6 + Tailwind CSS 4 【核心架构】 - Electron 主进程（窗口管理、平台检测、图标适配） - Vite 构建链（双产物 dist/ + dist-electron/） - 共享层 shared/（类型、常量、工具函数） - IPC 通信框架 + 安全守卫【主题系统】 - 蓝紫渐变主题（亮色/暗色双模式） - Ant Design ConfigProvider 适配（lightAlgorithm / darkAlgorithm） - Tailwind CSS 4 @theme 指令 + CSS 变量 - 设计令牌三处同步（tokens.ts / globals.css / antd-theme.ts）【导航栏】 - 自定义 H5 导航栏替代系统菜单 - 个人版/企业版双布局 - 未登录拦截 + 事件总线驱动登录弹窗【登录注册】 - Modal 弹层（Portal）+ Tabs 切换 - 登录/注册表单动态字段渲染 - 记住密码 / 自动登录 / 用户协议【更新系统】 - 自定义 API 版本检查（替代 electron-updater generic provider） - 手动下载 + SHA512 校验 + spawn NSIS 安装 - 渲染进程更新状态机 Hook（useUpdater） - 检查更新按钮 + 下载进度展示【构建工具链】 - build.mjs 构建总管（--win/--mac/--linux --personal/--enterprise --build/--clean/--sign/--upload/--publish） - scripts/ 自动化脚本（clean / generate-update-info / upload-oss / publish-release） - electron-builder NSIS 安装器（可选路径、多版本打包） - update-info.json 自动生成（fileSize/sha512/changelog/releaseDate）【代码质量】 - ESLint + TypeScript strict + Prettier - husky + lint-staged（提交前自动检查） - commitlint（规范提交信息） - Playwright E2E + Vitest 单元测试框架 - rollup-plugin-visualizer 打包体积分析【文档】 - README.md（快速开始 + 目录结构 + 命令速查） - UpdateA.md（发布手册：API/签名/发版流程/数据库） - CHANGELOG.md（更新日志） - .env.example（构建环境变量模板）
2026-06-03 15:00:51 +08:00
commit 767bb8b297
95 changed files with 20814 additions and 0 deletions
--- a/src/utils/event-bus.ts
+++ b/src/utils/event-bus.ts
@@ -0,0 +1,47 @@
+// ============================================================
+// 事件总线 — 跨组件/跨模块事件通信
+// 用于 axios 拦截器 → App 触发登录弹窗等解耦场景
+// ============================================================
+
+type Listener = (...args: unknown[]) => void;
+
+const listeners = new Map<string, Set<Listener>>();
+
+/** 监听事件 */
+export function on(event: string, fn: Listener): void {
+   if (!listeners.has(event)) {
+      listeners.set(event, new Set());
+   }
+   listeners.get(event)!.add(fn);
+}
+
+/** 取消监听 */
+export function off(event: string, fn: Listener): void {
+   listeners.get(event)?.delete(fn);
+}
+
+/** 触发事件 */
+export function emit(event: string, ...args: unknown[]): void {
+   listeners.get(event)?.forEach((fn) => {
+      try {
+         fn(...args);
+      } catch (e) {
+         console.error(`[EventBus] ${event} 回调出错:`, e);
+      }
+   });
+}
+
+// ============================================================
+// 预定义事件名
+// ============================================================
+
+export const EVENTS = {
+   /** 需要登录（axios 返回 401 时触发） */
+   AUTH_REQUIRED: 'auth:required',
+   /** 显示登录弹窗（用户点击登录按钮触发） */
+   SHOW_LOGIN: 'auth:show-login',
+   /** 登录成功 */
+   LOGIN_SUCCESS: 'auth:login-success',
+   /** 退出登录 */
+   LOGOUT: 'auth:logout',
+} as const;
--- a/src/utils/ipc.ts
+++ b/src/utils/ipc.ts
@@ -0,0 +1,43 @@
+// ============================================================
+// IPC 安全访问守卫
+// window.ipcRenderer 仅在 Electron 环境中存在（由 preload 注入），
+// 浏览器环境下为 undefined，所有调用必须先行判断。
+// ============================================================
+
+/** 检查是否在 Electron 环境中（window.ipcRenderer 可用） */
+export function hasIpc(): boolean {
+   return typeof window !== 'undefined' && window.ipcRenderer != null;
+}
+
+/** 安全地监听 IPC 消息 */
+export function safeIpcOn(
+   channel: string,
+   listener: (event: unknown, ...args: unknown[]) => void,
+): void {
+   if (hasIpc()) {
+      window.ipcRenderer.on(channel, listener);
+   }
+}
+
+/** 安全地取消监听 IPC 消息 */
+export function safeIpcOff(channel: string, listener: (...args: unknown[]) => void): void {
+   if (hasIpc()) {
+      window.ipcRenderer.off(channel, listener);
+   }
+}
+
+/** 安全地发送 IPC 消息（不等待响应） */
+export function safeIpcSend(channel: string, ...args: unknown[]): void {
+   if (hasIpc()) {
+      window.ipcRenderer.send(channel, ...args);
+   }
+}
+
+/** 安全地调用 IPC（等待响应） */
+export async function safeIpcInvoke(channel: string, ...args: unknown[]): Promise<unknown> {
+   if (!hasIpc()) {
+      console.warn(`[IPC] 非 Electron 环境，invoke "${channel}" 被忽略`);
+      return undefined;
+   }
+   return window.ipcRenderer.invoke(channel, ...args);
+}
--- a/src/utils/logo.ts
+++ b/src/utils/logo.ts
@@ -0,0 +1,53 @@
+// ============================================================
+// 渲染进程 Logo 自适应工具
+// 提供按平台返回正确 Logo 资源路径的函数，
+// 用于 <img src> 等场景。
+//
+// 资源存放在 src/assets/logo/
+//   heixiu.ico — Windows 多尺寸图标
+//   HX.png     — 通用 PNG Logo
+//   HX2.png    — 备用 PNG Logo（方形变体）
+// ============================================================
+
+import { isMacOS, isWindows } from './platform';
+
+// Vite 中直接 import 图片资源得到编译后的 URL
+import hxPng from '../assets/logo/HX.png';
+import hx2Png from '../assets/logo/HX2.png';
+// .ico 文件通常不太适合 <img> 标签，但在 Electron 窗口图标中使用
+
+/**
+ * 获取主 Logo 图片 URL（用于界面展示、关于对话框等）
+ * 所有平台统一使用 PNG
+ */
+export function getMainLogoUrl(): string {
+   return hxPng;
+}
+
+/**
+ * 获取备用/方形 Logo 图片 URL
+ */
+export function getAltLogoUrl(): string {
+   return hx2Png;
+}
+
+/**
+ * 获取浏览器 favicon 路径
+ * Windows 可用 .ico，其他平台用 .png
+ */
+export function getFaviconPath(): string {
+   if (isWindows()) {
+      return '/src/assets/logo/heixiu.ico';
+   }
+   return hxPng;
+}
+
+/**
+ * 获取平台推荐的应用图标格式说明
+ * 用于调试或信息展示
+ */
+export function getPlatformIconFormatInfo(): string {
+   if (isMacOS()) return '.icns（当前使用 .png 回退）';
+   if (isWindows()) return '.ico';
+   return '.png';
+}
--- a/src/utils/platform.ts
+++ b/src/utils/platform.ts
@@ -0,0 +1,89 @@
+// ============================================================
+// 渲染进程平台判定工具
+// 通过 preload 暴露的 process.platform 或 navigator.userAgent 判定
+// ============================================================
+
+import type { Platform } from '@shared/types';
+
+/**
+ * 获取当前平台标识
+ * 优先使用 preload 暴露的 Electron process.platform，
+ * 降级使用 navigator.userAgent 推断
+ */
+export function getPlatform(): Platform {
+   // 如果 preload 暴露了 platform 信息，优先使用
+   if (typeof window !== 'undefined' && window.ipcRenderer) {
+      // 通过 IPC 或 User-Agent 判断
+      const ua = navigator.userAgent.toLowerCase();
+      if (ua.includes('mac os') || ua.includes('macintosh')) return 'darwin';
+      if (ua.includes('windows') || ua.includes('win32') || ua.includes('win64')) return 'win32';
+      if (ua.includes('linux')) return 'linux';
+   }
+
+   // 降级方案：基于 userAgent 判断
+   const ua = navigator.userAgent.toLowerCase();
+   if (ua.includes('mac')) return 'darwin';
+   if (ua.includes('win')) return 'win32';
+   if (ua.includes('linux')) return 'linux';
+
+   // 默认为 Windows
+   return 'win32';
+}
+
+/** 是否为 macOS */
+export function isMacOS(): boolean {
+   return getPlatform() === 'darwin';
+}
+
+/** 是否为 Windows */
+export function isWindows(): boolean {
+   return getPlatform() === 'win32';
+}
+
+/** 是否为 Linux */
+export function isLinux(): boolean {
+   return getPlatform() === 'linux';
+}
+
+/** 获取平台名称（中文） */
+export function getPlatformName(): string {
+   if (isMacOS()) return 'macOS';
+   if (isWindows()) return 'Windows';
+   if (isLinux()) return 'Linux';
+   return '未知平台';
+}
+
+/**
+ * 获取快捷键修饰符展示文本
+ * macOS 用户习惯 ⌘ 符号，Windows/Linux 显示 Ctrl
+ */
+export function getShortcutDisplay(key: string): string {
+   if (isMacOS()) {
+      return `⌘+${key}`;
+   }
+   return `Ctrl+${key}`;
+}
+
+/**
+ * 获取适合当前平台的菜单行为提示
+ */
+export function getContextMenuHint(): string {
+   if (isMacOS()) {
+      return '右键点击 或 Ctrl+点击';
+   }
+   return '右键点击';
+}
+
+/**
+ * 判断是否为开发环境
+ */
+export function isDev(): boolean {
+   return import.meta.env.DEV;
+}
+
+/**
+ * 判断是否为生产环境
+ */
+export function isProd(): boolean {
+   return import.meta.env.PROD;
+}