home-PC
dfc306818a
新增开发文档，说明当前 MVP 能力、目录结构、配置位置、运行验证方式、开发注意事项和后续优先级。 同时记录提交信息约定，确保后续迭代继续保持规范中文 git 记录。
148 lines
4.3 KiB
Markdown
148 lines
4.3 KiB
Markdown
# 个人工具箱开发文档
|
||
|
||
## 当前项目状态
|
||
|
||
- 项目名称：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. 为组合校验、快捷键解析和配置读写增加单元测试。
|