doc:基础文档

详细开发路径文档.md

@@ -0,0 +1,115 @@
+# 个人工具箱 (Personal ToolBox) - 详细开发路径文档
+**Target Audience:** OpenCode (DeepSeek-v4-flash)
+**Architecture Pattern:** MVVM (Model-View-ViewModel)
+**Tech Stack:** C# / .NET 8 / WPF / CommunityToolkit.Mvvm
+
+---
+
+## 🤖 【全局系统提示词 (System Prompt)】
+*(在开始任何代码生成前，请先将以下全局设定发给 AI)*
+
+> "你现在是一位资深的 Windows 桌面客户端架构师和 C# WPF 专家。我们将一起开发一款名为“个人工具箱”的本地效率软件。
+> **开发规范要求：**
+> 1. 使用 **.NET 8 WPF** 技术栈。
+> 2. 严格遵循 **MVVM 架构**，引入 `CommunityToolkit.Mvvm` 库以简化开发。
+> 3. 采用**依赖注入 (DI)** 思想管理服务（如存储服务、日志服务）。
+> 4. UI 设计需极简现代化，原生支持暗黑/明亮模式切换。
+> 5. 必须提供完整、可运行的代码，且包含关键的中文注释。
+> 6. 请严格按照我后续给出的 Phase 阶段进行开发，不要跨越阶段。"
+
+---
+
+## 📍 Phase 0: 项目初始化与基础架构
+**【输入给 AI 的指令】：**
+> "现在我们开始 Phase 0：项目初始化。请帮我：
+> 1. 创建一个名为 `PersonalToolBox` 的 WPF 应用程序。
+> 2. 引入必要的 NuGet 包：`CommunityToolkit.Mvvm`、`System.Text.Json`。
+> 3. 建立标准 MVVM 目录结构：`Models`、`ViewModels`、`Views`、`Services`、`Helpers`。
+> 4. 编写 `ILogService` 接口和 `LogService` 实现类，用于管理底部的日志打印栏数据（需要包含时间、日志级别 Info/Warning/Error、日志内容），并能通过事件或 ObservableCollection 将日志实时推送到 UI。
+> 请给出项目结构树以及 `LogService` 的完整代码。"
+
+---
+
+## 📍 Phase 1: 数据模型与本地存储服务
+**【输入给 AI 的指令】：**
+> "进入 Phase 1：数据模型与存储。我们需要用本地 JSON 文件作为数据库。请帮我实现：
+> 1. 在 `Models` 文件夹下创建数据模型：
+>    - `ToolItem`: 包含 Id, Name, IconCode, ExecutablePath, Arguments, CategoryId, HotKey, IsValid(布尔值，用于标记文件是否丢失，不存入JSON，仅运行时计算)。
+>    - `Category`: 包含 Id, Name。
+>    - `AppConfig`: 包含 Theme(Dark/Light), AutoStart(bool), List<Category>, List<ToolItem>。
+> 2. 在 `Services` 下创建 `IDataService` 和 `JsonDataService`：
+>    - 实现数据的加载 (Load) 和 保存 (Save)，文件默认保存在 `AppDomain.CurrentDomain.BaseDirectory + "config.json"`。
+>    - **核心业务逻辑（容错机制）**：在 `Load` 时，遍历所有的 `ToolItem`，检查 `ExecutablePath` 是否存在（使用 `File.Exists`）。如果不存在，将该工具的 `IsValid` 设为 `false`，并调用 `ILogService` 打印警告日志 `[警告] 工具 {Name} 路径失效...`，**绝对不要从集合中删除它**。
+> 请提供这些 Model 和 Service 的完整 C# 代码。"
+
+---
+
+## 📍 Phase 2: 主窗口 UI 布局与主题切换
+**【输入给 AI 的指令】：**
+> "进入 Phase 2：主界面搭建。请帮我编写 `MainWindow.xaml` 及其 ViewModel `MainViewModel.cs`。
+> **UI 布局要求 (Grid 布局)：**
+> 1. **整体分为三部分**：左侧边栏 (宽200)、右侧主体区 (按比例占满)、底部日志栏 (高120)。
+> 2. **左侧边栏**：顶部显示软件名称，中间使用 `ListBox` 绑定 Categories（标签页分类），底部放置一个切换“黑夜/白天模式”的 Button。
+> 3. **右侧主体区**：顶部包含一个 `TextBox` (全局搜索框) 和一个 "添加工具" Button。下方使用 `ItemsControl` + `WrapPanel` 绑定当前分类下的 ToolItems，以卡片形式展示工具图标和名称。
+> 4. **底部日志栏**：包含一个标题栏（附带“清空日志”按钮）和一个只读的 `RichTextBox` 或 `ListBox`，绑定 `LogService` 的日志数据。
+> 
+> **功能要求：**
+> 1. 实现简单的黑夜/白天模式切换（动态替换 WPF 的 `ResourceDictionary` 中的颜色画笔）。
+> 2. 当 `ToolItem.IsValid` 为 false 时，UI 上的工具卡片需变灰（Opacity=0.5）。
+> 请提供 `MainWindow.xaml` 的布局代码、`ThemeHelper` 切换主题代码、以及绑定的 `MainViewModel` 代码。"
+
+---
+
+## 📍 Phase 3: 核心逻辑 - 增删改查与运行进程
+**【输入给 AI 的指令】：**
+> "进入 Phase 3：工具的管理与执行。请帮我实现：
+> 1. **新建/编辑工具弹窗**：创建一个 `ToolEditWindow.xaml`，包含表单字段（名称、路径选择按钮、参数、分类下拉框、快捷键输入框）。保存时更新到 `JsonDataService` 并刷新主界面。
+> 2. **搜索功能**：在 `MainViewModel` 中实现搜索框的过滤逻辑。根据 `TextBox` 的输入，实时过滤展示的 ToolItems。
+> 3. **运行进程服务**：新建 `ProcessExecutionService.cs`。
+>    - 接收 `ToolItem` 作为参数。
+>    - 如果 `!IsValid`，调用日志服务提示用户无法运行。
+>    - 使用 `System.Diagnostics.Process.Start(new ProcessStartInfo { FileName = path, Arguments = args, UseShellExecute = true })` 启动进程。
+>    - 如果发生异常（如权限不足），被 `try-catch` 捕获并将 Error 写入底部日志栏。
+> 请给出编辑窗口的 XAML 与代码，以及进程执行服务类的核心代码。"
+
+---
+
+## 📍 Phase 4: 高级特性 - 全局快捷键拦截 (Win32 API)
+**【输入给 AI 的指令】：**
+> "进入 Phase 4：全局快捷键支持。这个工具箱即使在后台，按下为某个工具配置的全局快捷键也需要能直接拉起该工具。
+> 1. 在 `Helpers` 目录下创建 `HotKeyManager.cs`。
+> 2. 使用 Win32 API (`RegisterHotKey` 和 `UnregisterHotKey`)。
+> 3. 在 `MainWindow.xaml.cs` 中重写 `OnSourceInitialized`，通过 `HwndSource.FromHwnd` 挂载 `AddHook` 拦截系统 Windows 消息 (`WM_HOTKEY`)。
+> 4. 当拦截到快捷键时，根据热键 ID 匹配对应的 `ToolItem`，并调用 `ProcessExecutionService` 启动它，同时在底部日志打印“通过快捷键启动：XXX”。
+> 请提供完整的 Win32 API 声明代码以及快捷键注册、解绑、拦截执行的完整逻辑。"
+
+---
+
+## 📍 Phase 5: 高级特性 - 系统托盘与开机自启
+**【输入给 AI 的指令】：**
+> "进入最后一个阶段 Phase 5：系统托盘与自启动。
+> 1. **系统托盘集成**：不需要引入复杂的第三方库，请直接使用 `System.Windows.Forms.NotifyIcon` 来实现。
+>    - 托盘图标常驻。
+>    - 鼠标左键点击托盘图标：如果主窗口隐藏则显示，如果显示则隐藏。
+>    - 重写 `MainWindow` 的 `OnClosing` 事件：点击右上角关闭按钮时，取消关闭 (`e.Cancel = true`)，改为隐藏窗口 (`this.Hide()`)。
+>    - 右键托盘图标提供菜单：“显示主界面”、“设置”、“彻底退出”。
+> 2. **开机自启动设置**：
+>    - 在 `Helpers` 目录下创建 `AutoStartHelper.cs`。
+>    - 通过写入 Windows 注册表 `HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run` 实现开机自启动。
+>    - 如果启动参数带有 `-autostart`，则主程序启动后直接隐藏到系统托盘，不弹出主窗口。
+> 请给出托盘管理逻辑代码和自启动帮助类的实现代码。"
+
+---
+
+### 💡 辅助除错指南 (针对 DeepSeek 可能会犯的错误)
+
+如果在开发过程中，AI 返回的代码运行报错：
+
+*   **如果 UI 数据不刷新**：
+    > "界面没有刷新。请检查 ViewModel 中的属性是否使用了 `[ObservableProperty]`（CommunityToolkit.Mvvm），以及集合是否使用了 `ObservableCollection<T>` 而不是 `List<T>`。"
+*   **如果快捷键注册失败**：
+    > "RegisterHotKey 返回 false。请确保热键 ID 唯一，且修饰键（Ctrl/Alt/Shift）和虚拟键码（VK）的转换正确。请检查是否与其他系统快捷键冲突，并在 LogService 中打印错误码。"
+*   **如果读取 JSON 失败**：
+    > "反序列化 JSON 失败。请检查 `System.Text.Json` 的配置，是否需要开启 `PropertyNameCaseInsensitive = true`，或者类定义缺少了无参构造函数。"
+*   **如果托盘图标不显示**：
+    > "NotifyIcon 没有显示。请确保为其分配了有效的 `.ico` 文件资源，并且设置了 `Visible = true`。请确保在程序退出时调用了 `NotifyIcon.Dispose()` 释放图标。"