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（构建环境变量模板）
This commit is contained in:
180
PROJECT.md
Normal file
180
PROJECT.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# 项目概览
|
||||
|
||||
- 本项目使用 Vite + React 19 + TypeScript + Electron 重构现有 Python Qt
|
||||
桌面应用，打造跨平台（Windows/macOS）的多窗口桌面程序。
|
||||
- 核心界面为单页应用（SPA），同时支持通过 Electron 打开独立窗口以承载子功能。
|
||||
|
||||
# 核心需求
|
||||
|
||||
- 完整还原原有 Qt 应用的业务逻辑与视觉体验，并对交互进行现代化改造。
|
||||
|
||||
- 必须支持 多窗口（主窗口 + 可动态创建的辅助窗口），窗口间需通过事件/消息进行低耦合通信。
|
||||
|
||||
- 适配 Windows 与 macOS，处理好快捷键、托盘、菜单、窗口边框等平台差异。
|
||||
|
||||
- 采用 离线优先 架构，保障本地数据处理性能，合理使用本地存储（如 electron-store 或 SQLite）。
|
||||
|
||||
- 所有对系统底层能力的调用必须通过 Electron 主进程，严禁在渲染进程直接使用 Node.js API（除非通过 preload 安全暴露）。
|
||||
|
||||
# 技术架构
|
||||
|
||||
## 整体分层
|
||||
|
||||
- 主进程（Main Process）：Electron 主进程，管理窗口生命周期、系统菜单、托盘、IPC 事件调度、本地文件/数据库操作。
|
||||
|
||||
- 预加载脚本（Preload）：桥接渲染进程与主进程，使用 contextBridge 安全暴露有限 API。
|
||||
|
||||
- 渲染进程（Renderer）：基于 React 19 的 SPA（主窗口）与独立窗口的 React 入口，负责 UI 展示与用户交互。
|
||||
|
||||
- 共享层（Shared）：进程间共享的 TypeScript 类型、常量、工具函数、事件名称枚举。
|
||||
|
||||
## 前端架构原则
|
||||
|
||||
- 组件化：以函数组件 + Hooks 为唯一组件形式，UI 拆分为展示组件与容器组件（若无特殊需求，可使用 Hooks 直接连接 Redux）。
|
||||
|
||||
- 单向数据流：全局状态使用 Redux Toolkit，严格遵循 Action → Reducer → Store → View 单向流动。组件内部状态使用
|
||||
useState/useReducer，不污染全局 Store。
|
||||
|
||||
- 事件驱动（EDA）：
|
||||
1. 主进程与渲染进程通信基于 Electron IPC（ipcMain/ipcRenderer），定义明确的事件通道与载荷类型。
|
||||
|
||||
2. 渲染进程内跨组件通信优先使用 Redux；需要解耦的场景可借助自定义事件总线（如 mitt），但严禁滥用。
|
||||
|
||||
3. 窗口间通信统一通过主进程转发（或使用 MessagePort 等 Electron 支持的机制），保持窗口独立性。
|
||||
|
||||
- 路由与导航：主窗口为 单页应用，使用 React Router v7+ 管理页面切换，支持嵌套路由。
|
||||
|
||||
- 辅助窗口（设置、预览、导入导出等）为独立 BrowserWindow，加载独立的 HTML 入口（可根据路由参数或 windowId 决定内部路由），不与主窗口共享
|
||||
DOM。
|
||||
|
||||
# 目录结构
|
||||
|
||||
```md
|
||||
├── electron/ # Electron 主进程与预加载脚本
|
||||
│ ├── main/ # 主进程代码
|
||||
│ │ ├── index.ts # 入口，初始化应用
|
||||
│ │ ├── windowManager.ts # 多窗口管理器（创建、销毁、聚焦）
|
||||
│ │ ├── ipc/ # IPC 事件注册与处理
|
||||
│ │ ├── menu/ # 系统菜单模板（按平台拆分）
|
||||
│ │ └── utils/ # 平台判断、路径处理等
|
||||
│ └── preload/ # 预加载脚本
|
||||
│ ├── index.ts # 主窗口预加载
|
||||
│ └── subWindow.ts # 辅助窗口预加载
|
||||
├── src/ # 渲染进程（React 应用）
|
||||
│ ├── main/ # 主窗口 SPA 入口
|
||||
│ │ ├── index.html # HTML 入口
|
||||
│ │ ├── main.tsx # React 挂载点
|
||||
│ │ └── App.tsx # 根组件（路由、主题）
|
||||
│ ├── sub/ # 辅助窗口独立入口（一个窗口对应一个子目录）
|
||||
│ │ ├── settings/ # 设置窗口示例
|
||||
│ │ │ ├── index.html
|
||||
│ │ │ └── main.tsx
|
||||
│ │ └── preview/ # 预览窗口示例
|
||||
│ ├── components/ # 通用 UI 组件
|
||||
│ ├── containers/ # 业务容器组件（连接 Redux）
|
||||
│ ├── store/ # Redux Toolkit 配置
|
||||
│ │ ├── index.ts # Store 创建
|
||||
│ │ ├── slices/ # 按功能拆分 Slice
|
||||
│ │ └── hooks.ts # 类型化 useAppSelector/useAppDispatch
|
||||
│ ├── hooks/ # 自定义 Hooks
|
||||
│ ├── theme/ # 主题适配器与定制
|
||||
│ │ ├── adapters/ # Ant Design 主题配置、Tailwind 扩展
|
||||
│ │ ├── tokens.ts # 设计令牌（颜色、圆角、阴影等）
|
||||
│ │ └── globals.css # Tailwind 指令 + 全局样式
|
||||
│ ├── router/ # 路由配置（主窗口）
|
||||
│ ├── utils/ # 纯函数工具
|
||||
│ │ └── platform.ts # 平台判定工具（process.platform 封装）
|
||||
│ └── types/ # 渲染进程专用类型
|
||||
├── shared/ # 主进程 & 渲染进程共享
|
||||
│ ├── types/ # IPC 通道、载荷类型、通用接口
|
||||
│ ├── constants/ # 事件名称、配置常量
|
||||
│ └── utils/ # 通用逻辑（如版本比较）
|
||||
├── package.json
|
||||
├── vite.config.ts # Vite 配置（多入口）
|
||||
├── tailwind.config.ts # Tailwind 主题扩展
|
||||
├── tsconfig.json
|
||||
└── electron-builder.yml # 打包配置（跨平台适配）
|
||||
```
|
||||
|
||||
# 多窗口与平台判定
|
||||
|
||||
- windowManager.ts 负责统一创建 BrowserWindow，根据环境变量/参数加载不同入口（如 src/main/index.html 或
|
||||
src/sub/settings/index.html）。
|
||||
|
||||
- src/utils/platform.ts 提供 isMacOS、isWindows 等函数（基于 navigator.userAgent 或 preload 暴露的 process.platform）。在主进程的
|
||||
electron/main/utils/platform.ts 中直接使用 Node.js API。
|
||||
|
||||
- 打包配置 (electron-builder.yml) 须针对平台设置不同的图标、签名策略、安装包格式。
|
||||
|
||||
# 代码风格
|
||||
|
||||
## TypeScript
|
||||
|
||||
- 所有语句必须以分号 ; 结尾，缺失分号将被视为错误。
|
||||
|
||||
- 启用 strict 模式，禁止隐式 any，优先使用 interface 定义对象类型，复杂类型可适度使用 type。
|
||||
|
||||
- 文件名使用小写短横线连接（kebab-case），如 use-window-state.ts；组件文件名与组件名保持一致（PascalCase），如
|
||||
ThemeAdapter.tsx。
|
||||
|
||||
- 导入顺序：第三方库 → 项目内共享模块 → 相对路径模块，中间用空行分隔。
|
||||
|
||||
## React
|
||||
|
||||
- 只允许函数组件与 Hooks，禁止使用类组件。
|
||||
|
||||
- 每个组件必须有明确的 Props 类型，使用 React.FC<Props> 或直接标注函数参数类型（推荐直接标注）。
|
||||
|
||||
- 事件处理函数命名以 handle 开头（如 handleClick），自定义 Hook 以 use 开头。
|
||||
|
||||
- 避免直接操作 DOM，除非封装在自定义 Hook 中（如焦点管理）。
|
||||
|
||||
- 使用 React.memo、useMemo、useCallback 优化性能，但不要过早优化。
|
||||
|
||||
## Redux
|
||||
|
||||
- 使用 Redux Toolkit 的 createSlice 管理状态，异步逻辑使用 createAsyncThunk。
|
||||
|
||||
- Slice 按业务领域划分，每个 Slice 文件导出 actions 与 reducer。
|
||||
|
||||
- 组件中通过自定义 Hooks (useAppSelector, useAppDispatch) 访问 Store，避免直接使用 useDispatch/useSelector。
|
||||
|
||||
# 样式与主题
|
||||
|
||||
- 优先使用 Tailwind 工具类 完成布局与常规样式，自定义设计令牌应映射为 Tailwind 扩展（在 tailwind.config.ts 中配置
|
||||
theme.extend）。
|
||||
|
||||
- Ant Design 组件样式通过 ConfigProvider 的 theme 属性覆盖，确保与 Tailwind 主题令牌同步。在 src/theme/adapters/ 中创建
|
||||
antd-theme.ts，导出主题配置对象，引用 tokens.ts 中的设计变量。
|
||||
|
||||
- 禁止在组件中硬编码颜色、字号等设计令牌，一律使用主题变量或 Tailwind 类名。
|
||||
|
||||
- 全局样式文件 globals.css 只引入 Tailwind 指令和必要的重置样式，不堆积组件样式。
|
||||
|
||||
# 事件与 IPC
|
||||
|
||||
- 所有 IPC 通道名称定义在 shared/constants/ipc-channels.ts 中，避免魔法字符串。
|
||||
|
||||
- 主进程事件处理函数需做好错误捕获与日志记录，渲染进程调用 IPC 时使用 try-catch 并处理超时。
|
||||
|
||||
- 窗口间通信走主进程转发：发送窗口 ipcRenderer.send，主进程接收后定位目标窗口并 webContents.send。
|
||||
|
||||
# 开发与构建命令
|
||||
|
||||
- 开发模式：npm run dev 或 yarn dev（同时启动 Vite 与 Electron，支持热重载）。
|
||||
|
||||
- 构建：npm run build 编译渲染进程 → 打包 Electron 应用。
|
||||
|
||||
- 代码检查：npm run lint（ESLint + Prettier，规则已配置为强制分号、单引号等）。
|
||||
|
||||
- 类型检查：npm run typecheck（tsc --noEmit）。
|
||||
|
||||
# 与其他 AI 协作的补充说明
|
||||
|
||||
- 所有生成的代码片段必须放在完整的文件上下文中，并注明所属文件路径。
|
||||
|
||||
- 若涉及跨平台逻辑，必须同时给出 Windows 与 macOS 的兼容实现或判断分支。
|
||||
|
||||
- 新增窗口时，需同步说明窗口入口、预加载脚本、主进程创建逻辑及 IPC 通道注册。
|
||||
|
||||
- 修改主题令牌时，需同步更新 tokens.ts、tailwind.config.ts 及 antd-theme.ts，确保三处一致。
|
||||
Reference in New Issue
Block a user