ele-HeiXiu/TODO.md

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

// 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 已有，定期检查）

增量更新改造

当前状态：

• electron-builder 已配置 "differential": true，打包时已生成 .exe.blockmap 文件 ✅
• electron/main/updater.ts 为手写全量下载（net.request），未使用 electron-updater npm 包 ❌
• blockmap 文件生成了但从未被消费，每次更新都是完整下载

目标方案 — 自定义 Provider + electron-updater：

// electron/main/updater-v2.ts
import { autoUpdater } from 'electron-updater';
import { Provider } from 'electron-updater/out/providers/Provider';

class HeiXiuProvider extends Provider<UpdateInfo> {
  // 版本检查 → 走自定义 API（保留灰度/强更控制）
  async getLatestVersion(): Promise<UpdateInfo> {
    const res = await fetch(`${API_BASE}/api/v1/update/check?...`);
    const data = await res.json();
    return {
      version: data.latestVersion,
      files: [{
        url: data.downloadUrl,
        sha512: data.sha512,
        size: data.fileSize,
        blockMapSize: data.blockMapSize,  // 后端新增字段
      }],
      path: data.downloadUrl,
      sha512: data.sha512,
      releaseDate: data.releaseDate,
    };
  }
}

改造内容：

• 安装 electron-updater npm 包
• 重写 electron/main/updater.ts 为自定义 Provider 模式
• 发布脚本 upload-oss.mjs 增加 blockmap 文件上传
• generate-update-info.mjs 增加 blockmap 字段（blockMapUrl、blockMapSize）
• 后端 API /api/v1/update/check 响应增加 blockMapUrl、blockMapSize 字段
• 后端 releases 表增加 blockmap_url、blockmap_size 列
• OSS 上传每次版本需同时上传 .exe + .exe.blockmap 两个文件

增量效果预估：日常更新下载量从完整安装包 → 仅变化的块（预计节省 60%~90% 流量）。

代码质量

• 移除未使用的 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 导航补齐