From 397d80c87b6684226937d2214ea06995706e5c02 Mon Sep 17 00:00:00 2001
From: YoungestSongMo <2130460579@qq.com>
Date: Wed, 3 Jun 2026 19:38:10 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=B7=A5=E4=BD=9C?=
 =?UTF-8?q?=E6=97=A5=E5=BF=97=E4=B8=8E=E5=BE=85=E5=8A=9E=E6=B8=85=E5=8D=95?=
 =?UTF-8?q?=EF=BC=88=E5=90=AB=E5=AE=89=E5=85=A8=E5=8A=A0=E5=9B=BA=E8=AE=A1?=
 =?UTF-8?q?=E5=88=92=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 TODO.md    | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++
 WORKLOG.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 243 insertions(+)
 create mode 100644 TODO.md
 create mode 100644 WORKLOG.md

diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..d10665a
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,118 @@
+# TODO — 船长·HeiXiu 待办与优化清单
+
+> 最后更新：2026-06-03
+
+---
+
+## 🔴 安全加固（优先级高）
+
+### 1. 敏感数据加密存储
+
+当前所有敏感数据存储在 `localStorage` 明文/Base64：
+
+| 数据 | 现状 | 目标方案 |
+|------|------|---------|
+| `access_token` | 明文 | Electron `safeStorage.encryptString()` |
+| `refresh_token` | 明文 | Electron `safeStorage.encryptString()` |
+| `passwordBase64` | Base64 编码 | 移除密码存储，仅靠 refresh_token 自动登录 |
+
+**方案 A（推荐）**：使用 Electron `safeStorage` API
+- macOS → Keychain
+- Windows → DPAPI
+- Linux → libsecret
+
+```ts
+// preload.ts 暴露安全方法
+contextBridge.exposeInMainWorld('safeStorage', {
+   encrypt: (plain: string) => ipcRenderer.invoke('safe-storage:encrypt', plain),
+   decrypt: (encrypted: Buffer) => ipcRenderer.invoke('safe-storage:decrypt', encrypted),
+});
+
+// 替代现有 setToken / setStoredRefreshToken
+// 渲染进程不再直接操作 localStorage
+```
+
+**方案 B**：敏感操作下沉到主进程
+- `access_token` / `refresh_token` 由主进程管理
+- 渲染进程通过 IPC 发起请求时由主进程追加 Token
+- 渲染进程永不持有明文 Token
+
+### 2. 密码存储策略调整
+
+- [ ] "记住密码" → 仅回填用户名，不再存储密码（已完成）
+- [ ] 清理 `StoredAuth.passwordBase64` 字段
+- [ ] "自动登录" 完全依赖 `refresh_token` 静默续期
+
+---
+
+## 🟡 功能待完善（优先级中）
+
+### 设置页面
+
+- [ ] 设置数据通过 IPC 同步到主进程（当前仅渲染进程 localStorage）
+- [ ] 存储路径有效性校验（检查路径是否存在）
+- [ ] "恢复默认设置"按钮
+
+### 路由与页面
+
+- [ ] 合规素材库页面（`/compliance-assets`）
+- [ ] 项目管理页面（`/projects`，企业版）
+- [ ] 账户/会员/充值/消费记录/订单明细页面
+- [ ] 忘记密码流程
+- [ ] 各页面暗色主题适配
+
+### 导航栏
+
+- [ ] 移除调试用的 `console.log`
+- [ ] 导航配置中的 `action: 'external'` 统一管理（白名单校验）
+- [ ] 未登录点击需登录项 → 登录成功后自动跳转到目标页
+
+### 公告
+
+- [ ] 公告已读/未读状态
+- [ ] 公告红点/角标提醒（有新公告时导航栏图标变化）
+- [ ] 公告缓存（减少重复请求）
+
+---
+
+## 🟢 工程优化（优先级低）
+
+### 构建与开发
+
+- [ ] CI/CD 流水线（GitHub Actions / 自建）
+- [ ] 代码签名自动化（Windows Authenticode / macOS notarization）
+- [ ] E2E 测试用例编写（Playwright）
+- [ ] 单元测试覆盖（Vitest）
+- [ ] Bundle 体积分析优化（rollup-plugin-visualizer 已有，定期检查）
+
+### 代码质量
+
+- [ ] 移除未使用的 `shared/` 类型和常量
+- [ ] 统一 IPC 通道注册/注销模式（避免重复监听）
+- [ ] React 组件 lazy loading（React.lazy + Suspense）
+- [ ] 错误边界组件（ErrorBoundary）
+
+### 文档
+
+- [ ] API 接口文档（Swagger / 手动维护）
+- [ ] 组件文档（Storybook）
+- [ ] 用户操作手册
+
+---
+
+## ⚠️ 已知技术债务
+
+| 问题 | 说明 | 影响 |
+|------|------|------|
+| localStorage 依赖 | 所有持久化数据依赖 localStorage | 清理浏览器数据会丢失所有配置 |
+| IPC 监听器 | useUpdater 已改为单例，其他 IPC hook 可能也有类似问题 | 长期运行可能内存泄漏 |
+| `test.py` | 仓库根目录残留测试文件 | 无实际作用，应清理 |
+| `null` 文件 | 仓库根目录名为 null 的文件 | 构建产物或误操作残留 |
+
+---
+
+## 📋 下次开发计划
+
+1. **safeStorage 加密改造**（安全加固 #1）
+2. **合规素材库页面**（功能待完善 Route 页面）
+3. **各页面 nav 导航补齐**
diff --git a/WORKLOG.md b/WORKLOG.md
new file mode 100644
index 0000000..94bd306
--- /dev/null
+++ b/WORKLOG.md
@@ -0,0 +1,125 @@
+# 船长·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