# 个人工具箱 (Personal ToolBox) 需求与设计文档

**文档版本：** V1.0
**目标平台：** Windows 10 / Windows 11

## 一、 技术栈推荐 (Tech Stack)

考虑到这是一款纯 Windows 平台的本地工具，且需要涉及**全局快捷键注册**、**系统托盘**、**开机自启动**以及**本地文件操作**，我强烈推荐以下技术栈：

*   **开发语言与框架**：**C# + WPF (.NET 8)**
    *   *推荐理由*：C# 是开发 Windows 桌面应用的最佳选择，调用底层 Windows API（如全局快捷键、托盘）非常稳定。WPF 支持高度定制的 UI，且性能优于 Electron。
*   **UI 库**：**ModernWpf** 或 **MaterialDesignInXAML**
    *   *推荐理由*：自带极简风格，原生支持**黑夜/白天模式一键切换**。
*   **图标库**：内置 **FontAwesome** 或 **Segoe Fluent Icons**（Windows自带字体图标）。
*   **数据存储**：**本地 JSON 文件** (`config.json`)。
    *   *推荐理由*：轻量，非常方便进行数据的导入/导出备份，不需要引入笨重的数据库。

---

## 二、 核心功能需求 (PRD)

### 2.1 工具管理模块
*   **手动添加/编辑**：用户可通过弹窗表单添加工具，字段包含：
    *   `显示名称` (String, 必填)
    *   `工具路径` (String, 支持选择文件或直接填写 URL)
    *   `运行参数` (String, 选填)
    *   `所属标签页` (String, 下拉选择或新建)
    *   `工具图标` (从内置图标库中选择)
    *   `全局快捷键` (选填，如 `Ctrl+Alt+T`)
*   **工具执行**：双击图标或点击运行按钮，程序根据路径和参数拉起对应工具（支持 `.exe`, `.bat`, `.py`, 网址等）。

### 2.2 分类与检索
*   **标签页分类 (Tabs)**：以标签页作为一级分类（如：开发工具、系统设置、常用脚本）。
*   **全局搜索框**：位于界面顶部，输入关键字实时过滤当前所有工具，支持按名称检索。

### 2.3 进阶功能
*   **独立快捷键触发**：即使工具箱主窗口处于隐藏状态，只要在后台运行，按下为某工具设定的全局快捷键，即可直接运行该工具。
*   **开机自启动**：在软件设置中提供开关，通过写入注册表或放入 Startup 文件夹实现静默自启（直接最小化到托盘）。
*   **数据备份与容错机制（重点）**：
    *   支持导出/导入 `config.json` 文件。
    *   **容错处理**：程序启动或导入配置时，遍历所有工具的本地路径。若发现路径失效（文件缺失），**不删除该数据**，但在 UI 上将该工具置灰（或打上警告角标），同时在**底部信息打印栏**输出：`[警告] 工具 "XXX" 路径失效，找不到文件: D:\xxx.exe`。

---

## 三、 UI 与交互设计 (UI/UX)

### 3.1 界面布局 (Layout)
采用经典的三段式布局：
1.  **左侧导航区 (Left Panel)**：
    *   顶部：用户头像或软件 Logo。
    *   中间：**标签页 (Tabs)** 列表，支持垂直切换（如：全部、组A、组B）。
    *   底部：设置按钮（齿轮图标）、明暗主题切换按钮。
2.  **右侧主内容区 (Main Panel)**：
    *   顶部：**搜索框** 和 “添加工具” 按钮。
    *   中间：工具展示区。采用网格布局 (Grid)，每个工具显示为一个小卡片，包含图标和自定义名称。
3.  **底部信息栏 (Bottom Log Bar)**：
    *   高度固定（约 100px），可折叠或清空。
    *   用于打印软件运行日志，如：`[2023-10-27 10:00] 成功启动：Postman`，`[错误] 快捷键 Ctrl+D 冲突，注册失败`。

### 3.2 窗口形态与托盘交互
*   **常规状态**：标准 Windows 窗体。
*   **关闭/最小化行为**：点击右上角“X”或最小化时，默认**隐藏窗口而不是退出进程**。
*   **系统托盘 (System Tray)**：
    *   常驻右下角托盘。
    *   **左键单击托盘图标**：呼出/隐藏主窗口。
    *   **右键单击托盘图标**：弹出菜单（显示主窗口、设置、退出）。

---

## 四、 系统架构与数据模型 (SDD)

### 4.1 数据结构设计 (`config.json`)
为了满足数据备份和恢复的需求，配置文件的结构建议如下：

```json
{
  "Settings": {
    "Theme": "Dark",
    "AutoStart": true
  },
  "Categories": [
    { "Id": "1", "Name": "开发工具" },
    { "Id": "2", "Name": "常用脚本" }
  ],
  "Tools": [
    {
      "Id": "uuid-0001",
      "Name": "内网穿透小工具",
      "IconCode": "f0c2",          // 内置图标库的字符编码
      "Path": "D:\\tools\\ngrok.exe",
      "Arguments": "http 8080",
      "CategoryId": "1",
      "HotKey": "Ctrl+Shift+N"
    }
  ]
}
```

### 4.2 核心模块逻辑描述
1.  **启动逻辑 (Startup)**：
    *   读取 `config.json` -> 渲染 UI -> 验证工具路径 -> 若缺失，打印日志到底部信息栏 -> 注册全局快捷键 -> 根据设置决定是否显示主窗口。
2.  **执行逻辑 (Execution)**：
    *   使用 C# 的 `System.Diagnostics.Process.Start(Path, Arguments)` 方法执行。如果执行失败（如权限不足），在底部信息栏打印 Exception 错误信息。
3.  **全局快捷键拦截 (Global Hooks)**：
    *   使用 Windows API `RegisterHotKey` 进行系统级键盘钩子注册。当捕获到设定的组合键时，触发对应的 `Process.Start` 事件。