From dfc306818a23427cbd648a994d0f74b0ecd5d91c Mon Sep 17 00:00:00 2001
From: home-PC <gamewhale@163.com>
Date: Wed, 27 May 2026 13:57:30 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=E5=BD=93=E5=89=8D?=
 =?UTF-8?q?=E5=BC=80=E5=8F=91=E7=8A=B6=E6=80=81=E5=92=8C=E7=BB=B4=E6=8A=A4?=
 =?UTF-8?q?=E7=BA=A6=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增开发文档，说明当前 MVP 能力、目录结构、配置位置、运行验证方式、开发注意事项和后续优先级。

同时记录提交信息约定，确保后续迭代继续保持规范中文 git 记录。
---
 docs/development.md | 147 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 docs/development.md

diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..6a402a6
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,147 @@
+# 个人工具箱开发文档
+
+## 当前项目状态
+
+- 项目名称：Personal Toolbox / ToolboxApp
+- 技术栈：WPF + .NET 8 + C#
+- 架构方向：MVVM 分层，UI 层通过 ViewModel 调用服务层
+- 当前阶段：MVP 基础版本已搭建，可编译运行
+- 主要入口：`src/ToolboxApp/MainWindow.xaml`
+
+## 已实现能力
+
+1. 基础工程
+   - `PersonalToolbox.sln`
+   - `src/ToolboxApp/ToolboxApp.csproj`
+   - WPF 桌面应用，启用 WinForms 托盘能力
+
+2. 数据与配置
+   - 本地 JSON 配置读写
+   - 原子写入：先写 `.tmp`，再替换正式文件
+   - 默认配置目录：`%AppData%\ToolboxApp`
+   - 配置文件：
+     - `appsettings.json`
+     - `categories.json`
+     - `tools.json`
+     - `autorun.json`
+     - `icons/`
+   - 导入、导出、重置配置基础能力
+
+3. 工具模型
+   - 系统工具
+   - 本地工具
+   - 网址工具
+   - 组合工具
+   - 一级分类
+   - 自动运行项
+   - 快捷键配置和状态
+
+4. 默认系统工具
+   - 首次创建系统工具分类和未分类
+   - 内置记事本、计算器、任务管理器、控制面板、设置、Windows 更新、设备管理器、磁盘管理、服务、注册表、网络连接和应用列表
+   - 设置页支持补回缺失默认系统工具
+
+5. 启动服务
+   - 所有入口统一走 `ToolLaunchService`
+   - 本地工具使用 Windows Shell 打开
+   - 网址使用默认浏览器打开
+   - 系统工具使用内置启动目标
+   - 支持管理员启动配置
+   - 启动结果输出到底部信息区
+
+6. 组合与自动运行
+   - 组合成员引用已有工具或组合
+   - 支持成员启用、禁用、排序、间隔
+   - 支持失败后继续或停止
+   - 保存前检测循环引用和展开后重复工具
+   - 自动运行列表从工具自身 `AutoRunEnabled` 动态汇总
+
+7. 托盘、自启和快捷键
+   - 托盘常驻服务
+   - 托盘菜单：显示/隐藏主界面、全局快捷键开关、设置、退出
+   - 关闭窗口时隐藏到托盘
+   - 当前用户开机自启
+   - 全局快捷键注册、注销、内部冲突和注册失败提示
+
+8. 界面
+   - 顶部搜索和操作按钮
+   - 左侧一级分类
+   - 右侧工具卡片网格
+   - 底部信息输出区
+   - 工具编辑窗口
+   - 组合编辑窗口
+   - 设置窗口
+   - 主要 UI 元素均提供 `ToolTip` 悬浮说明
+
+## 运行与验证
+
+构建：
+
+```powershell
+dotnet build PersonalToolbox.sln
+```
+
+运行：
+
+```powershell
+dotnet run --project src\ToolboxApp\ToolboxApp.csproj
+```
+
+当前验证结果：
+
+```text
+dotnet build PersonalToolbox.sln
+0 个警告
+0 个错误
+```
+
+## 目录说明
+
+```text
+src/ToolboxApp
+├─ Commands       命令封装
+├─ Models         工具、分类、组合、配置、日志等模型
+├─ Services       配置、启动、托盘、自启、快捷键、路径校验等服务
+├─ ViewModels     主界面和卡片视图模型
+└─ Views          编辑、组合、设置和提示窗口
+```
+
+## 开发需知
+
+- 不要绕过 `ToolLaunchService` 写启动逻辑。
+- 组合只保存成员工具 ID，不复制工具内容。
+- 普通错误优先输出到底部信息区，只有删除、导入覆盖、重置、退出等操作使用确认弹窗。
+- 默认系统工具只在首次配置创建或用户主动恢复时补回，避免覆盖用户删除/隐藏意图。
+- 所有新增可交互 UI 控件都应提供 `ToolTip`。
+- 配置写入必须保持原子写入策略，避免中途失败写坏 JSON。
+- 快捷键必须包含至少一个修饰键，不支持纯单键快捷键。
+- 开机自启只写当前用户注册表，不要求管理员权限。
+
+## Git 记录约定
+
+提交信息使用 Conventional Commits 格式，并使用中文说明：
+
+```text
+feat: 添加某项用户能力
+
+说明本次变更做了什么、为什么这样做，以及是否影响数据结构或用户行为。
+```
+
+常用类型：
+
+- `feat`: 新功能
+- `fix`: 修复问题
+- `docs`: 文档
+- `chore`: 构建、仓库、维护类变更
+- `refactor`: 不改变行为的重构
+- `test`: 测试相关
+
+## 后续优先事项
+
+1. 自动图标提取和轻量内置图标库。
+2. 更完整的图标选择器和分类图标编辑。
+3. 更细的快捷键录入控件，减少手写格式错误。
+4. 拖拽调整卡片和分类顺序。
+5. 导入配置后的更详细路径失效报告。
+6. UI 视觉打磨和深浅色主题。
+7. 为组合校验、快捷键解析和配置读写增加单元测试。