personal-toolbox/需求与设计文档.md

个人工具箱 (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)

为了满足数据备份和恢复的需求，配置文件的结构建议如下：

{
  "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 事件。