docs: v1.0.0 独立代码审计 - 重新评估(58/100) + 制定v1.1~v1.5优化路线图 + TDD计划

2026-04-18 10:20:31 +08:00
1 parent c4bf43f58f
commit 60c3d868c5
@@ -19,250 +19,277 @@
 | v0.9.0 | **Optimization** | P0/P1 全面优化 | ✅ 已完成 |
 | v0.10.0 | **v0.3.0-release** | 核心功能实现 | ✅ 已完成 |
 | v1.0.0 | **Stable** | 生产可用 | ✅ 已完成 |
+| **v1.1.0** | **Cleanup** | **代码质量清理** | 🔄 进行中 |
+| **v1.2.0** | **Refactor** | **组件拆分重构** | 📋 规划中 |
+| **v1.3.0** | **Testing** | **测试覆盖达标** | 📋 规划中 |
+| **v1.4.0** | **Upgrade** | **依赖升级+安全加固** | 📋 规划中 |
+| **v1.5.0** | **Polish** | **功能补全+性能优化** | 📋 规划中 |
+| v2.0.0 | **Professional** | 专业版发布 | 📋 远期规划 |

 ---

-## v0.5.0 Pre-Stable ✅
+## v1.1.0 代码质量清理 🔄

-**完成日期**: 2026-04-05
+**目标**: 清除生产代码中的调试残留，补全 SFTP 核心功能
+**预计**: 1 周
+**评分目标**: 代码质量 45→70

-### ✅ 已完成功能清单
+### 任务清单

-#### SFTP 传输队列优化
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| 传输队列显示 | `SFTPView.tsx` | 显示进行中的上传/下载任务 |
-| 传输历史记录 | `SFTPView.tsx` | 显示最近完成的传输任务 |
-| 可收起面板 | `SFTPView.tsx` | 点击展开/收起传输面板 |
-| 多文件上传队列 | `SFTPView.tsx` | 逐个上传并显示各任务进度 |
-| Downloads 目录 | `SFTPView.tsx` | 跨平台默认下载路径 |
-| 移除删除按钮 | `SFTPView.tsx` | 简化界面 |
+| # | 任务 | 优先级 | 文件 | 状态 |
+|---|------|--------|------|------|
+| 1 | 移除所有 console.log 和彩色调试函数 | P0 | `TerminalView.tsx`, `useSFTP.ts`, `ssh-service.ts` | ⬜ |
+| 2 | 移除 `DEBUG = true` 硬编码 | P0 | `TerminalView.tsx:16` | ⬜ |
+| 3 | 移除 Mock 数据残留 | P0 | `useSFTP.ts:154-161` | ⬜ |
+| 4 | 补全 SFTP 上传 IPC 实现 | P0 | `useSFTP.ts:399`, `sftp.ipc.ts` | ⬜ |
+| 5 | 补全 disconnect() 资源释放 | P1 | `useSFTP.ts:359-373` | ⬜ |
+| 6 | Math.random → uuid 生成 ID | P1 | `TerminalView.tsx:383,463` | ⬜ |
+| 7 | IPC 通道名引用 IPC_CHANNELS 常量 | P2 | `preload.ts` | ⬜ |
+| 8 | 移除未使用依赖 react-router-dom | P2 | `package.json` | ⬜ |
+| 9 | 替换重复的彩色日志函数为统一 logger | P2 | `TerminalView.tsx`, `useSFTP.ts` | ⬜ |
+| 10 | 修复 `if (false)` 等无用代码 | P2 | `TerminalView.tsx:50` | ⬜ |
+
+### 验收标准
+
+```bash
+# 零调试残留
+grep -r "console.log" src/ electron/ | wc -l  # → 0
+grep -r "DEBUG = true" src/ | wc -l            # → 0
+grep -r "logHeader\|logInfo\|logSuccess\|logError\|logWarning" src/ electron/ | wc -l  # → 0
+
+# SFTP 上传功能可用
+# 手动测试：连接 → SFTP → 上传文件 → 验证远端文件存在
+```

 ---

-## v0.6.0 Pre-Stable ✅
+## v1.2.0 组件拆分重构 📋

-**完成日期**: 2026-04-05
+**目标**: 终端组件拆分为可维护的 Hook 体系
+**预计**: 1.5 周
+**评分目标**: 架构 72→85

-### ✅ 已完成功能清单
+### 拆分计划

-#### 终端 rz/sz 支持
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| rz 命令拦截 | `TerminalView.tsx` | 检测 rz 并打开文件选择器 |
-| sz 文件接收 | `TerminalView.tsx` | 捕获 Zmodem 数据并保存 |
-| 文件读写 API | `preload.ts`, `main.ts` | 支持 rz 上传和 sz 下载 |
+#### TerminalView.tsx (645行) → 拆分
+
+```
+src/components/terminal/TerminalView.tsx        (~150行) 纯渲染层
+src/hooks/useTerminal.ts                        (~200行) 终端初始化 + 数据流
+src/hooks/useTerminalConnection.ts              (~150行) SSH 连接管理
+src/hooks/useTerminalSnapshot.ts                (~100行) 快照保存/恢复
+src/hooks/useZmodem.ts                          (~100行) rz/sz 文件传输
+```
+
+#### useSFTP.ts (510行) → 拆分
+
+```
+src/hooks/useSFTPNavigation.ts                  (~200行) 本地/远程目录导航
+src/hooks/useSFTPTransfer.ts                    (~200行) 上传/下载/传输队列
+src/hooks/useSFTPConnection.ts                  (~100行) SFTP 连接管理
+```
+
+#### App.tsx (258行) → 业务逻辑外提
+
+```
+src/components/App.tsx                          (~150行) 纯 UI 编排
+src/services/sessionImport.ts                   (~80行)  导入/导出逻辑
+```
+
+### Store 解耦
+
+```
+当前: lifecycleStore → 直接调用 poolStore.getState()
+目标: 引入 ConnectionFacade 统一接口，Store 通过事件通信
+```
+
+### 验收标准
+
+- 单文件不超过 300 行
+- Hook 可独立导入、独立测试
+- 现有功能无回归

 ---

-## v0.7.0 Professional ✅
+## v1.3.0 测试覆盖达标 📋

-**完成日期**: 2026-04-05
+**目标**: 核心模块测试覆盖率 ≥60%，总覆盖率 ≥50%
+**预计**: 2 周
+**评分目标**: 测试 15→50

-### ✅ 已完成功能清单
+### 测试批次

-#### 专业连接管理架构
+| 批次 | 目标模块 | 用例目标 | 优先级 |
+|------|----------|----------|--------|
+| 1 | `crypto.ts` (加密/解密正确性) | 15+ | P0 |
+| 2 | `ssh-service.ts` (mock ssh2) | 20+ | P0 |
+| 3 | `database-service.ts` (CRUD) | 15+ | P1 |
+| 4 | `error-handler.ts` (错误推断) | 10+ | P1 |
+| 5 | `poolStore.ts` + `lifecycleStore.ts` | 20+ | P1 |
+| 6 | `IPC handlers` (8个模块) | 25+ | P1 |
+| 7 | `TerminalView` 组件测试 | 10+ | P2 |
+| 8 | `useSFTP` hooks 测试 | 15+ | P2 |
+| **总计** | | **130+** | |

-| 功能 | 文件 | 说明 |
-|------|------|------|
-| 连接状态机 | `connectionPool.ts` | disconnected/connecting/connected/background/suspended |
-| 连接池管理 | `connectionPool.ts` | 最大 10 并发，LRU 淘汰策略 |
-| 后台连接保持 | `connectionPool.ts` | 最大 5 个后台连接，空闲 5 分钟挂起 |
-| 自动保活机制 | `connectionPool.ts` | 每分钟发送心跳包 |
-| 连接复用 | `connectionPool.ts` | 相同配置标签共享 SSH 连接 |
-| 终端快照 | `terminalSnapshotStore.ts` | 切换标签保存/恢复终端内容 |
-| 快照恢复 | `TerminalView.tsx` | 快速恢复显示，避免黑屏 |
-| 挂起恢复 UI | `TerminalView.tsx` | 手动恢复或重新连接选项 |
-| 连接状态指示 | `TerminalView.tsx` | 实时显示连接状态（绿/蓝/黄/红） |
-| 专业设置面板 | `SettingsView.tsx` | 可配置连接池参数 |
+### 验收标准

-#### 多标签连接隔离
-
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| 独立连接实例 | `tabStore.ts` | 每个标签独立的 connectionInstance |
-| 标签切换优化 | `TabContent.tsx` | opacity 过渡，保持组件实例 |
-| 连接引用计数 | `connectionPool.ts` | 正确管理连接生命周期 |
-| 关闭自动断开 | `TabBar.tsx` | 标签关闭时释放对应连接 |
+```bash
+npm test -- --coverage
+# Statements  ≥ 50%
+# Branches    ≥ 40%
+# Functions   ≥ 50%
+# Lines       ≥ 50%
+```

 ---

-## v0.8.0 Modular ✅
+## v1.4.0 依赖升级 + 安全加固 📋

-**完成日期**: 2026-04-05
+**目标**: 依赖更新到最新稳定版，安全漏洞清零
+**预计**: 1 周
+**评分目标**: 安全 55→75, 依赖 50→80

-### ✅ 已完成架构重构清单
+### 依赖升级

-#### IPC Handler 分层
+| 依赖 | 当前 | 目标 | 风险 |
+|------|------|------|------|
+| `electron` | v28 | v33+ | 高 - Breaking changes |
+| `better-sqlite3` | v9 | v11 | 中 - API 变化 |
+| `zustand` | v4 | v5 | 低 - 订阅 API 变化 |
+| `lucide-react` | 0.294 | 0.4xx | 低 - 图标名可能有变化 |
+| `eslint` | v8 | v9 | 中 - flat config 迁移 |

-| 模块 | 文件 | 说明 |
-|------|------|------|
-| SSH IPC | `electron/ipc/ssh.ipc.ts` | 连接/断开/exec/Shell/端口转发 |
-| SFTP IPC | `electron/ipc/sftp.ipc.ts` | SFTP 操作/传输进度 |
-| 会话 IPC | `electron/ipc/session.ipc.ts` | CRUD 操作 |
-| 设置 IPC | `electron/ipc/settings.ipc.ts` | 读写设置 |
-| 对话框 IPC | `electron/ipc/dialog.ipc.ts` | 文件对话框 |
-| 文件 IPC | `electron/ipc/file.ipc.ts` | 本地文件操作 |
-| Zmodem IPC | `electron/ipc/zmodem.ipc.ts` | rz/sz 传输 |
-| 应用 IPC | `electron/ipc/app.ipc.ts` | 版本/路径信息 |
+### 安全加固

-#### 共享类型统一
-
-| 类型 | 文件 | 说明 |
-|------|------|------|
-| Session 类型 | `shared/types/session.types.ts` | 会话配置、认证类型 |
-| Connection 类型 | `shared/types/connection.types.ts` | 连接池、连接状态 |
-| SFTP 类型 | `shared/types/sftp.types.ts` | 文件项、传输任务 |
-| IPC 类型 | `shared/types/ipc.types.ts` | IPC 通道常量 |
-
-#### 连接池 Store 拆分
-
-| Store | 文件 | 说明 |
-|------|------|------|
-| Pool Store | `src/stores/connection/poolStore.ts` | 连接池核心：创建/获取/释放 |
-| Lifecycle Store | `src/stores/connection/lifecycleStore.ts` | 状态机、超时、事件 |
-| Store Hooks | `src/stores/connection/storeHooks.ts` | 组合接口 |
-
-#### SFTP 组件拆分
-
-| 组件 | 文件 | 说明 |
-|------|------|------|
-| Breadcrumb | `src/components/sftp/Breadcrumb.tsx` | 路径导航 |
-| SortHeader | `src/components/sftp/SortHeader.tsx` | 列排序 |
-| FileRow | `src/components/sftp/FileRow.tsx` | 文件行渲染 |
-| ContextMenu | `src/components/sftp/ContextMenu.tsx` | 右键菜单 |
-| TransferItem | `src/components/sftp/TransferItem.tsx` | 传输任务项 |
-| ConnectionSelector | `src/components/sftp/ConnectionSelector.tsx` | 服务器选择 |
+| 任务 | 说明 |
+|------|------|
+| 启用 sandbox 模式 | preload 适配 |
+| CSP 移除 unsafe-inline | Tailwind nonce 配置 |
+| IPC 参数验证 | zod schema |
+| 密码 IPC 传输审查 | 确保加密后传输 |
+| 审查 socksv5 安全性 | 评估是否替换 |

 ---

-## v0.9.0 Optimization ✅
+## v1.5.0 功能补全 + 性能优化 📋

-**完成日期**: 2026-04-05
+**目标**: 补全缺失功能，性能指标全面达标
+**预计**: 2 周
+**评分目标**: 功能 82→95, 综合 80+

-### ✅ 已完成功能清单
+### 功能补全

-#### 测试框架建立
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| Vitest 配置 | `vitest.config.ts` | 测试环境配置 |
-| 测试设置 | `test/setup.ts` | Electron API mock |
-| TabStore 测试 | `test/stores/tabStore.test.ts` | 16 个测试用例 |
-| ConnectionPool 测试 | `test/stores/connectionPool.test.ts` | 8 个测试用例 |
-| SFTP Utils 测试 | `test/components/sftp/utils.test.ts` | 14 个测试用例 |
+| 功能 | 优先级 | 说明 |
+|------|--------|------|
+| SFTP 拖拽上传/下载 | P1 | 界面已就绪，补全 drag/drop 事件 |
+| SFTP 断点续传 | P2 | 大文件传输可靠性 |
+| 会话分组树形显示 | P2 | 侧边栏分组 + 文件夹 |
+| 终端分屏 | P3 | 水平/垂直分屏 |
+| 命令片段(Snippets) | P3 | 常用命令快速执行 |
+| 同步功能 | P3 | 多设备会话同步 |

-#### SFTP 右键菜单完善
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| 新建文件夹 | `SFTPView.tsx` | 本地新建文件夹 |
-| 复制路径 | `SFTPView.tsx` | 复制文件完整路径 |
-| 查看属性 | `SFTPView.tsx` | 显示文件详情 |
-| sftpMkdir IPC | `sftp.ipc.ts` | 远程创建目录支持 |
+### 性能优化

-#### WebGL 渲染优化
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| WebGL Addon | `TerminalView.tsx` | GPU 加速渲染 |
-| 自动降级 | `TerminalView.tsx` | WebGL 不可用时降级 |
-
-#### 会话导入完善
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| JSON 格式导入 | `App.tsx` | 支持数组和对象格式 |
-| SSH Config 导入 | `App.tsx` | 支持 Host/HostName/User |
-| 批量创建 | `App.tsx` | 自动创建所有会话 |
+| 指标 | 当前 | 目标 | 方案 |
+|------|------|------|------|
+| 冷启动 | ~3s | <2s | 延迟加载非核心模块 |
+| 包体积 | ~120MB | <100MB | asar + tree-shaking |
+| 内存(10标签) | ~200MB | <150MB | 连接池优化 + 终端回收 |
+| SSH 连接 | ~1s | <500ms | 连接预热 |

 ---

-## v0.10.0 v0.3.0-release ✅
+## 远期规划 (v2.0.0)

-**完成日期**: 2026-04-06
+### 专业版特性

-### ✅ 已完成功能清单
-
-#### SSH 终端核心功能
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| 密码认证 | `ssh-service.ts` | 用户名密码连接 |
-| 密钥认证 | `ssh-service.ts` | RSA/ED25519 私钥认证 |
-| XTerm.js 终端 | `TerminalView.tsx` | 高性能终端仿真 |
-| 多主题配色 | `terminal.ts` | Dracula/Monokai/Solarized/One Dark |
-| IP 高亮显示 | `TerminalView.tsx` | Last login IP 绿色高亮 |
-| 端口转发 | `PortForwardView.tsx` | 本地/远程/SOCKS5 动态代理 |
-
-#### SFTP 文件管理
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| 双栏文件管理 | `SFTPView.tsx` | 本地/远程双栏对比 |
-| 上传下载 | `useSFTP.ts` | 文件传输队列 |
-| 传输进度 | `TransferPanel.tsx` | 实时进度显示 |
-| 服务器选择 | `ConnectionSelector.tsx` | 快速选择已保存会话 |
-
-#### 架构改进
-| 功能 | 文件 | 说明 |
-|------|------|------|
-| 模块化 IPC | `electron/ipc/*.ts` | 8 个独立 IPC 模块 |
-| 连接池管理 | `poolStore.ts` | 连接复用和生命周期管理 |
-| 统一日志 | `logger.ts` | 彩色高亮调试日志 |
-| 错误处理 | `error-handler.ts` | 统一错误边界处理 |
+- 插件系统 — 支持第三方扩展
+- 主题编辑器 — 自定义配色方案
+- 脚本录制/回放 — 操作自动化
+- 协作共享 — 团队会话管理
+- 云同步 — 加密会话配置同步
+- API 网关 — 命令行/CI 集成
+- 容器管理 — Docker/Podman 集成

 ---

-## v1.0.0 Stable - 生产可用 ✅
+## 已完成版本
+
+<details>
+<summary>展开查看历史版本</summary>
+
+### v1.0.0 Stable - 生产可用 ✅

 **状态**: 已完成

-### 功能完成清单
+#### 功能完成清单

-#### SSH 终端
+##### SSH 终端
 - ✅ 密码/密钥认证
 - ✅ XTerm.js 高性能终端
 - ✅ 多主题配色方案
 - ✅ IP 地址高亮显示

-#### SFTP 管理
+##### SFTP 管理
 - ✅ 双栏文件管理器
 - ✅ 上传/下载文件
 - ✅ 传输队列管理
 - 🟡 拖拽上传下载 (界面就绪，待完善)
 - 📋 断点续传 (规划中)

-#### 端口转发
+##### 端口转发
 - ✅ 本地端口转发
 - ✅ 远程端口转发
 - ✅ 动态 SOCKS5 代理
 - ✅ 转发规则管理

-#### 架构特性
+##### 架构特性
 - ✅ IPC Handler 模块化
 - ✅ 共享类型定义
 - ✅ 连接池 Store 拆分
 - ✅ 统一日志系统

---
+### v0.10.0 v0.3.0-release ✅

-## 开发优先级
+**完成日期**: 2026-04-06

-```
-v0.6.0 完成清单 ✅
+- ✅ SSH 终端核心功能（密码/密钥认证、XTerm.js、多主题、IP高亮、端口转发）
+- ✅ SFTP 文件管理（双栏、上传下载、传输队列、服务器选择）
+- ✅ 架构改进（模块化 IPC、连接池管理、统一日志、错误处理）

-v1.0.0 开发顺序:
-├── 1. 测试框架建立 (P0)
-├── 2. 文件列表右键菜单 (P1)
-├── 3. WebGL 渲染优化 (P1)
-└── 4. 会话导入完整实现 (P1)
-```
+### v0.9.0 Optimization ✅

---
+**完成日期**: 2026-04-05

-## 里程碑检查点
+- ✅ 测试框架建立（Vitest + 38 测试用例）
+- ✅ SFTP 右键菜单（新建文件夹/复制路径/属性）
+- ✅ WebGL 终端渲染优化
+- ✅ 会话导入完整实现

-### v1.0.0 Stable 完成条件
+### v0.8.0 Modular ✅

- [x] 测试框架建立 (vitest + 38 测试用例)
- [x] 文件列表右键菜单 (新建/复制/属性)
- [x] WebGL 终端渲染优化
- [x] 会话导入完整实现
- [ ] 无 critical/major 级别 bug
- [ ] 打包后可在 macOS/Windows 运行
- [ ] 性能指标达标
+**完成日期**: 2026-04-05
+
+- ✅ IPC Handler 分层（8 个独立模块）
+- ✅ 共享类型统一
+- ✅ 连接池 Store 拆分
+- ✅ SFTP 组件拆分
+
+### v0.7.0 Professional ✅
+
+**完成日期**: 2026-04-05
+
+- ✅ 连接状态机（6 个状态）
+- ✅ 连接池管理（LRU淘汰、保活、超时）
+- ✅ 终端快照机制
+- ✅ 多标签连接隔离
+
+### v0.6.0 ~ v0.1.0 ✅
+
+- ✅ rz/sz 文件传输
+- ✅ SFTP 传输队列优化
+- ✅ AES-256-GCM 加密存储
+- ✅ 端口转发
+- ✅ 功能骨架 + 核心 SSH
+
+</details>