From 19bdb3078a702d24ad2155f4dcfb921b5dee2301 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Tue, 26 May 2026 08:20:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20CLAUDE.md=20?= =?UTF-8?q?=E5=8F=8D=E6=98=A0=E6=9C=80=E6=96=B0=E9=A1=B9=E7=9B=AE=E7=8A=B6?= =?UTF-8?q?=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新架构图（移除已删除的 string-list.ts，补充 Modal/buttons/ErrorBoundary） - 新增数据模型章节（不可变 string[] + snapshot 比较 isModified） - 新增撤销/重做 API 说明 - 新增错误处理章节（前端 + Rust 完整覆盖表） - 补充 TypeScript strict 模式、Rust SAFETY 注释等质量约束 Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 166 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 116 insertions(+), 50 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 54457f6..e307a36 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,83 +13,149 @@ npm install # 开发模式（热更新） npx tauri dev -# 仅前端 +# 仅前端（浏览器预览，无注册表功能） npm run dev # 前端测试 npm test npm run test:watch -# 构建生产版本 -npm run build - # Rust 后端检查 cd src-tauri && cargo check -# Rust 后端测试 +# Rust 后端测试（需要 MinGW bin 在 PATH） cd src-tauri && cargo test -# 完整构建（安装包） +# 生产构建 +npm run build + +# 完整构建（生成 NSIS 安装包） npx tauri build ``` ## 架构 -前后端分离，通过 Tauri IPC 通信： +前后端分离，通过 Tauri IPC 通信。核心原则：**纯逻辑放前端 `core/`，只有注册表/系统操作用 Rust 后端**。 ``` -src/ # React 前端 (TypeScript) -├── core/ # 纯逻辑 — 零 React 依赖 -│ ├── string-list.ts # StringList 数据结构 -│ ├── undo-redo.ts # 撤销/重做管理器（8 种操作类型） -│ ├── path-manager.ts # 路径增删移清理 -│ ├── import-export.ts # JSON/CSV/TXT 导入导出 -│ └── validation.ts # 路径格式验证 -├── store/ # Zustand 状态管理 -│ ├── app-store.ts # 主状态（路径、撤销、CRUD、加载/保存） -│ └── theme-store.ts # 深色/浅色模式 -├── components/ # React UI 组件 -│ ├── layout/ # AppShell、TitleBar、StatusBar -│ ├── path-list/ # PathTable、MergePreview -│ ├── toolbar/ # ToolBar、ActionButtons、UndoRedoButtons、SearchInput -│ └── dialogs/ # PathEditDialog、HelpDialog、ImportDialog -├── hooks/ # use-keyboard、use-path-validation -├── i18n/ # i18next 中英文翻译 -└── config/ # default.json UI 参数配置 +src/ # React 前端 (TypeScript strict 模式) +├── core/ # 纯逻辑 — 零 React/零 Tauri 依赖 +│ ├── undo-redo.ts # 撤销/重做管理器（8 种操作类型，不可变 string[]） +│ ├── path-manager.ts # 路径分析、清理（纯函数，不可变） +│ ├── import-export.ts # JSON/CSV/TXT 导入导出 +│ └── validation.ts # 路径格式验证、split/join +├── store/ # Zustand 状态管理 +│ ├── app-store.ts # 主状态（路径、撤销、CRUD、加载/保存、isSaving 守卫、snapshot 比较） +│ └── theme-store.ts # 深色/浅色模式（localStorage 持久化） +├── components/ +│ ├── layout/ # AppShell、TitleBar、StatusBar、ErrorBoundary +│ ├── path-list/ # PathTable（异步验证、颜色编码、tooltip）、MergePreview +│ ├── toolbar/ # ToolBar、ActionButtons、UndoRedoButtons、SearchInput +│ ├── dialogs/ # PathEditDialog、HelpDialog、ImportDialog +│ └── ui/ # Modal（共享遮罩层）、buttons（共享样式） +├── hooks/ +│ ├── use-app-actions.ts # CRUD/导入导出/键盘/双击操作集中管理 +│ ├── use-keyboard.ts # 全局快捷键（ref 模式避免重复注册） +│ └── use-path-validation.ts # 路径验证 hook（空壳，验证逻辑在 PathTable 内联） +├── i18n/ +│ ├── index.ts # i18next 初始化 +│ └── locales/ # zh-CN.json / en.json +└── config/ + └── default.json # 撤销上限、PATH 长度限制 -src-tauri/ # Tauri Rust 后端 +src-tauri/ # Tauri Rust 后端 ├── src/ │ ├── commands/ -│ │ ├── registry.rs # 注册表读写（load/save system & user paths） -│ │ ├── system.rs # check_admin、validate_path、expand_env_vars、broadcast -│ │ └── backup.rs # backup_registry、get_appdata_dir -│ ├── error.rs -│ └── lib.rs # 注册所有 IPC commands -├── Cargo.toml +│ │ ├── registry.rs # 注册表读写（通用 load/save 函数 + 6 个单元测试） +│ │ ├── system.rs # check_admin、validate_path、expand_env_vars、broadcast（+ 4 个测试） +│ │ └── backup.rs # backup_registry、get_appdata_dir（共享 backup_base_dir） +│ ├── error.rs # AppError 结构体（保留供未来迁移） +│ └── lib.rs # 注册所有 IPC commands + tauri-plugin-dialog +├── Cargo.toml # winreg + dirs + chrono └── tauri.conf.json -tests/unit/ # Vitest 前端单元测试 +tests/unit/ # Vitest 前端单元测试（4 文件 45 个测试） +``` + +## 数据模型 + +所有路径数据在前端用 **不可变 `string[]`** 存储。每次 CRUD 操作创建新数组通过 `set()` 写入 Zustand，Zustand 通过引用比较自动触发重渲染。 + +```typescript +// app-store.ts 核心模式 +addPath: (path, target) => { + const newList = [...list, path]; // 不可变：创建新数组 + state.undoRedo.push({ ... }); // 记录撤销 + set({ sysPaths: newList }); // Zustand 检测到新引用 → 重渲染 +}, +``` + +`isModified` 通过与上次保存时的快照比较判断，而非简单设 `true`/`false`： +```typescript +_markDirty: () => { + const { _savedSys, _savedUser, sysPaths, userPaths } = get(); + set({ isModified: !(arraysEqual(sysPaths, _savedSys) && arraysEqual(userPaths, _savedUser)) }); +}, ``` ## IPC 接口（Rust → Frontend） -| Command | 功能 | -|---------|------| -| `load_system_paths` | 从 HKLM 注册表读取系统 PATH | -| `load_user_paths` | 从 HKCU 注册表读取用户 PATH | -| `save_system_paths` | 保存系统 PATH 到注册表 | -| `save_user_paths` | 保存用户 PATH 到注册表 | -| `check_admin` | 检测管理员权限 | -| `validate_path` | 验证路径目录是否存在 | -| `expand_env_vars` | 展开 %VAR% 环境变量 | -| `broadcast_env_change` | 广播 WM_SETTINGCHANGE | -| `backup_registry` | 备份注册表 PATH 到文件 | -| `get_appdata_dir` | 获取备份目录路径 | +| Command | 参数 | 返回值 | 功能 | +|---------|------|--------|------| +| `load_system_paths` | — | `Result, String>` | 从 HKLM 注册表读取系统 PATH | +| `load_user_paths` | — | `Result, String>` | 从 HKCU 注册表读取用户 PATH | +| `save_system_paths` | `paths: Vec` | `Result<(), String>` | 保存系统 PATH（含 32767 字符上限检查） | +| `save_user_paths` | `paths: Vec` | `Result<(), String>` | 保存用户 PATH | +| `check_admin` | — | `bool` | 通过尝试 KEY_WRITE 检测管理员权限 | +| `validate_path` | `path: &str` | `bool` | 检查目录是否存在（含 `%` 自动返回 true） | +| `expand_env_vars` | `path: &str` | `String` | 展开 `%VAR%` 环境变量（API 失败时返回原始路径 + `log::warn`） | +| `broadcast_env_change` | — | `()` | 广播 `WM_SETTINGCHANGE` 通知其他进程 | +| `backup_registry` | `custom_dir, sysPaths, userPaths` | `Result` | 备份 PATH 到时间戳文件 | +| `get_appdata_dir` | — | `String` | 获取备份目录路径 | + +## 撤销/重做 + +`UndoRedoManager` 类（`src/core/undo-redo.ts`），8 种操作类型，最多 50 步历史。 + +核心 API：`undo/redo` 接收 `string[]`，返回新 `[string[], string[]] | null`。 + +```typescript +class UndoRedoManager { + push(record: OpRecord): void; + undo(sys: string[], user: string[]): [string[], string[]] | null; + redo(sys: string[], user: string[]): [string[], string[]] | null; + canUndo(): boolean; + canRedo(): boolean; +} +``` + +## 错误处理 + +### 前端 + +| 场景 | 处理 | +|------|------| +| IPC 调用失败 | `Promise.allSettled` 精确报告哪个 hive 保存失败 | +| JSON 文件损坏 | `importFromJson` try/catch，返回空结果 | +| 保存并发双击 | `isSaving` 守卫，第二次调用直接 return | +| 备份创建失败 | `.catch()` 显示 warning_backup，保存继续 | +| 渲染异常 | ErrorBoundary 捕获 + console.error + 重试按钮 | +| 取消按钮误点 | 检查 `isModified`，弹出确认框 | +| 拖拽非文件夹 | `webkitGetAsEntry().isDirectory` 过滤 | + +### Rust 后端 + +- 注册表操作：全部返回 `Result`，中文错误消息 +- FFI 调用：失败时 `log::warn` + 返回安全回退值 +- PATH 长度：写入前检查 32767 字符上限 +- SAFETY 注释：所有 `unsafe` 块均有文档 ## 关键约束 -- Rust 工具链：`stable-x86_64-pc-windows-gnu`（项目已设 override） -- `.cargo/config.toml` 添加了 `-lmcfgthread` 兼容 GCC 15.2.0 MinGW -- 移除 `cdylib` crate-type 避免 DLL 导出序数溢出 -- 运行需要管理员权限才能编辑系统 PATH -- `cargo test` 需要 MinGW bin 在 PATH 中（GCC 15.2.0 运行时依赖 `libmcfgthread-2.dll`），开发模式下可用 `npx tauri dev` 替代 +- **TypeScript**：`strict: true`，零编译错误 +- **Rust 工具链**：`stable-x86_64-pc-windows-gnu`（项目已设 override） +- **MinGW 兼容**：`.cargo/config.toml` 添加 `-lmcfgthread`（GCC 15.2.0 运行时） +- **crate-type**：移除 `cdylib` 避免 DLL 导出序数溢出 +- **运行权限**：需要管理员权限才能编辑系统 PATH，非管理员自动进入只读模式 +- **Rust 测试**：`cargo test` 需要 MinGW bin 在 PATH 中（`libmcfgthread-2.dll`），开发模式建议 `npx tauri dev` +- **构建产物**：NSIS 安装包，约 8MB