doc:基础文档

需求与设计文档.md

@@ -0,0 +1,105 @@
+# 个人工具箱 (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` 事件。