ele-HeiXiu/WORKLOG.md

船长·HeiXiu 工作日志

项目：船长·HeiXiu（Electron + React 19 + TypeScript + Ant Design 6 + Tailwind CSS 4） 仓库：E:\code\ele-heixiu

---

2026-06-01 ~ 2026-06-02 — 项目初始化与基础设施

项目初始化

• 创建 Vite + React 19 + TypeScript 项目骨架
• 集成 Electron 主进程 + preload
• 配置 Tailwind CSS 4 + Ant Design 6
• 创建共享类型层 shared/（Platform / Edition / IPC channels / AppConfig）
• 操作系统平台工具（main + renderer 双端）
• 窗口图标自适应（.ico / .icns / .png）
• 窗口标题格式：船长·HeiXiu V{version} {OS}{版本}

主题系统

• 蓝紫渐变设计令牌（tokens.ts）
• Ant Design lightTheme / darkTheme（含 darkAlgorithm）
• Tailwind CSS 4 @theme 指令 + CSS 变量
• 主题切换 Hook（useTheme）+ ConfigProvider 注入

导航栏

• NavBar 组件（56px 高度、渐变背景、macOS 80px 左偏移）
• 个人版/企业版双布局（nav-config.ts）
• 未登录拦截：点击需登录项 → 弹出提示 + 登录 Modal
• 公告抽屉（AnnouncementDrawer）+ API 联调

登录/注册

• LoginPage Modal（可关闭、事件总线触发）
• LoginForm + RegisterForm 动态字段渲染
• 跨字段校验（confirmPassword）
• 短信验证码发送 + 60s 冷却
• 记住密码 / 自动登录（联动勾选）
• 用户协议弹窗（LegalTextModal，.txt 文件 raw import）
• 暗色主题适配

HTTP 请求层

• axios 封装（request.ts）
• 请求/响应拦截器（Bearer token、业务码、401 事件总线）
• ApiResponse<T> / PaginatedData<T> / RequestError 类型
• 公告模块（services/modules/announcement.ts）
• IPC 安全守卫（safeIpcOn / safeIpcInvoke）

自动更新

• electron-updater → 自定义 API 架构迁移
• GET /api/v1/update/check 接口设计
• 手动下载安装包（Electron net.request + 流式写入 + SHA512 校验）
• NSIS /S 静默安装 + app.quit()
• useUpdater Hook（状态机：idle→checking→available→downloading→downloaded）
• 检查更新按钮 + 进度条 + 安装确认
• 5 秒启动静默检查

构建工具链

• build.mjs — 构建总管（--win/--mac/--linux --personal/--enterprise）
• scripts/clean.mjs — 清理 release + dist + dist-electron
• scripts/generate-update-info.mjs — 自动生成 update-info.json
• scripts/upload-oss.mjs — OSS 上传（HMAC-SHA1 签名）
• scripts/publish-release.mjs — POST 版本信息到 API
• electron-builder 配置（NSIS / DMG / AppImage）

代码质量 & 文档

• ESLint + @typescript-eslint + eslint-plugin-react-hooks
• TypeScript 严格模式
• husky + lint-staged + commitlint（后续移除）
• Playwright E2E / Vitest 基础配置
• README.md / UpdateA.md / CHANGELOG.md / CLAUDE.md / PROJECT.md

打包调试 & 修复

• winCodeSign 7z 符号链接 → 管理员权限运行
• NSIS 工具 GitHub 下载超时 → npm config 镜像
• electron-builder.json5 不被读取 → 配置移入 package.json
• EDITION 环境变量传递失败 → cross-env 逐段设置
• files: [] 致 asar 为空 → 修正为 ["dist", "dist-electron"]

文件统计：98 个文件 | 状态：v0.0.1 开发中

---

2026-06-03 — 认证体系 + 设置页面 + 路由 + 错误系统

提交 3becdb8

JWT 认证体系

• 实现双 Token 机制：access_token + refresh_token
• Axios 拦截器 401 自动刷新 + 并发请求去重队列
• setTokenRefreshHandler 解耦模式：request.ts 不知晓 auth
• 启动时 refresh_token 静默续期（自动登录）
• 记住密码：Base64 编码存储，表单自动回填
• 公告列表 API 对接 + AnnouncementDrawer 组件

设置页面（Router + Modal 叠加）

• 引入 react-router-dom，HashRouter 路由系统
• 设置页以居中 Modal 叠加首页，仅 X 按钮关闭
• SettingsContext 集中式状态管理（类似 Vue Pinia）
• 主题切换 / 存储路径 / 系统信息 / 版本更新 四个区块
• 文件夹选择 IPC（渲染进程 → 主进程原生对话框）
• 个人版/企业版差异化存储路径配置
• NavBar 使用 useNavigate() 真实路由导航

自定义错误类型系统

• RefreshError 继承 RequestError，type = AUTH_EXPIRED
• 全局拦截器捕获 → 自动 clearToken + emit(AUTH_REQUIRED)
• 任何位置 throw new RefreshError() 即可触发登录 Modal

Bug 修复

• MaxListenersExceededWarning：useUpdater 改为模块级单例 IPC 监听器
• Auth refresh 无限循环：refresh 端点自身 401 直接拒绝，不走 handle401
• 记住密码 stale closure：saveAuth 参数由调用方显式传入
• 自动登录失败丢失用户名：clearAutoLoginFlag 仅清除标记，保留表单数据

优化

• 公告卡片长文本 Tooltip + 点击详情 Modal
• 暗色主题公告卡片 border-0 + shadow-sm
• 架构文档 ARCHITECTURE.md

文件变更：新增 15 个 / 修改 19 个 / +2668 -2295 行

架构关键决策

1. 路由方案：HashRouter（兼容 Electron file:// 协议），设置页在 Routes 外部以 Modal 叠加
2. 状态管理：Context + Provider 模式（AppContext / ThemeContext / SettingsContext），不用 Redux/Zustand
3. 请求层：Axios 实例 + 拦截器链，Token 刷新通过 setTokenRefreshHandler 注册回调解耦
4. 错误处理：自定义错误类型（RefreshError）→ 全局拦截器捕获 → 事件总线（AUTH_REQUIRED）→ 登录 Modal