PC效率工具箱 - 项目架构说明书

版本: 1.0.0
文档日期: 2026-02-19

1. 项目概述

1.1 项目定位

PC效率工具箱是一个模块化的桌面效率工具集合，采用插件化架构设计，每个功能模块独立开发、独立运行，通过统一的主框架进行管理。

1.2 设计目标

目标	描述
模块化	各功能模块独立，便于扩展和维护
轻量化	最小化资源占用，快速启动
易用性	简洁直观的用户界面
可扩展	支持快速添加新的效率工具模块

1.3 版本信息

属性	值
项目名称	PCProductivityToolbox
版本号	1.0.0
开发语言	C++17
GUI框架	Qt 6.9.0
构建系统	CMake 3.16+
目标平台	Windows 10/11

2. 技术栈

2.1 核心技术

技术	版本	用途
C++	C++17	核心开发语言
Qt	6.9.0	GUI框架
CMake	3.16+	构建系统

2.2 Qt模块依赖

模块	用途
Qt6::Core	核心功能（信号槽、事件循环、JSON处理等）
Qt6::Widgets	GUI组件（窗口、按钮、布局等）
Qt6::Gui	图形渲染、字体处理

2.3 平台特定API

平台	API	用途
Windows	Win32 API (SetWindowPos)	窗口置顶控制

3. 目录结构

d:\gitee\Kitools/
│
├── assets/                          # 资源文件目录
│   └── resources.qrc                # Qt资源文件定义
│
├── docs/                            # 文档目录
│   └── 使用说明书.md                # 用户使用手册
│
├── src/                             # 源代码目录
│   │
│   ├── main.cpp                     # 程序入口点
│   │
│   ├── core/                        # 核心框架
│   │   ├── mainwindow.h             # 主窗口头文件
│   │   └── mainwindow.cpp           # 主窗口实现
│   │
│   └── modules/                     # 功能模块目录
│       │
│       ├── timer/                   # 计时器模块
│       │   ├── timercontroller.h    # 控制器头文件
│       │   ├── timercontroller.cpp  # 控制器实现
│       │   ├── overlaywidget.h      # 置顶窗口头文件
│       │   ├── overlaywidget.cpp    # 置顶窗口实现
│       │   ├── timersettingspanel.h # 设置面板头文件
│       │   ├── timersettingspanel.cpp # 设置面板实现
│       │   ├── settingsmanager.h    # 设置管理器头文件
│       │   └── settingsmanager.cpp  # 设置管理器实现
│       │
│       └── todo/                    # 待办事项模块
│           ├── todocontroller.h     # 控制器头文件
│           ├── todocontroller.cpp   # 控制器实现
│           ├── desktoptodowidget.h  # 桌面窗口头文件
│           ├── desktoptodowidget.cpp # 桌面窗口实现
│           ├── taskitemwidget.h     # 任务项组件头文件
│           ├── taskitemwidget.cpp   # 任务项组件实现
│           ├── taskmanager.h        # 任务管理器头文件
│           ├── taskmanager.cpp      # 任务管理器实现
│           ├── logmanager.h         # 日志管理器头文件
│           ├── logmanager.cpp       # 日志管理器实现
│           ├── todosettingspanel.h  # 设置面板头文件
│           ├── todosettingspanel.cpp # 设置面板实现
│           └── tododatatypes.h      # 数据类型定义
│
├── CMakeLists.txt                   # CMake构建配置
├── .gitignore                       # Git忽略配置
└── 开发文档.md                      # 开发说明文档

4. 架构设计

4.1 整体架构

项目采用 分层架构 + 模块化设计：

┌─────────────────────────────────────────────────────────────┐
│                      表现层 (Presentation)                   │
│  ┌─────────────────┐  ┌─────────────────┐                   │
│  │TimerSettingsPanel│  │TodoSettingsPanel│                   │
│  │  OverlayWidget   │  │DesktopTodoWidget│                   │
│  │                  │  │ TaskItemWidget  │                   │
│  └────────┬─────────┘  └────────┬────────┘                   │
├───────────┼─────────────────────┼────────────────────────────┤
│           │      控制层 (Controller)      │                   │
│  ┌────────┴─────────┐  ┌────────┴────────┐                   │
│  │ TimerController  │  │  TodoController │                   │
│  └────────┬─────────┘  └────────┬────────┘                   │
├───────────┼─────────────────────┼────────────────────────────┤
│           │       业务层 (Business)        │                  │
│  ┌────────┴─────────┐  ┌────────┴────────┐                   │
│  │ SettingsManager  │  │   TaskManager   │                   │
│  │     (单例)       │  │   LogManager    │                   │
│  └──────────────────┘  └─────────────────┘                   │
├─────────────────────────────────────────────────────────────┤
│                      核心框架 (Core)                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                    MainWindow                         │   │
│  │              (主框架/模块容器/托盘管理)                 │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

4.2 模块交互图

                    ┌─────────────┐
                    │  MainWindow │
                    │  (主框架)    │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
           ▼               ▼               ▼
    ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
    │   Module 1  │ │   Module 2  │ │   Module N  │
    │   Timer     │ │    Todo     │ │   (扩展)    │
    └──────┬──────┘ └──────┬──────┘ └─────────────┘
           │               │
    ┌──────┴──────┐ ┌──────┴──────┐
    │ Controller  │ │ Controller  │
    │     +       │ │     +       │
    │   Widget    │ │   Widget    │
    │     +       │ │     +       │
    │   Manager   │ │   Manager   │
    └─────────────┘ └─────────────┘

4.3 模块内部结构

每个功能模块遵循统一的内部结构：

Module/
├── xxxcontroller.h/cpp     # 模块控制器 - 协调各组件
├── xxxwidget.h/cpp         # 主界面组件 - 用户交互
├── xxxsettingspanel.h/cpp  # 设置面板 - 配置管理
├── xxxmanager.h/cpp        # 业务管理器 - 数据处理
└── xxxdatatypes.h          # 数据类型定义

5. 核心模块详解

5.1 核心框架 (Core)

MainWindow

职责：主窗口管理、模块容器、系统托盘集成

关键成员：

class MainWindow : public QMainWindow {
    QStackedWidget *m_stackedWidget;    // 模块切换容器
    QSystemTrayIcon *m_trayIcon;        // 系统托盘图标
    TimerController *m_timerController; // 计时器模块控制器
    TodoController *m_todoController;   // 待办模块控制器
};

关键功能：

卡片式工具选择界面
模块切换管理
最小化到托盘
托盘菜单管理

5.2 计时器模块 (Timer)

类图

┌─────────────────┐     ┌─────────────────┐
│ TimerController │────▶│  OverlayWidget  │
│   (控制器)      │     │   (置顶窗口)     │
└────────┬────────┘     └─────────────────┘
         │
         │              ┌─────────────────┐
         └─────────────▶│TimerSettingsPanel│
                        │   (设置面板)     │
                        └────────┬────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │ SettingsManager │
                        │   (设置管理器)   │
                        │    [单例]       │
                        └─────────────────┘

TimerController

职责：计时逻辑控制、组件协调

关键成员：

class TimerController : public QObject {
    QTimer *m_timer;              // 计时器
    int m_remainingSeconds;       // 剩余秒数
    int m_elapsedSeconds;         // 已计秒数（正向计时）
    TimerSettingsPanel::TimerMode m_currentMode; // 当前模式
};

OverlayWidget

职责：置顶显示窗口

关键特性：

无边框窗口 (Qt::FramelessWindowHint)
置顶显示 (Qt::WindowStaysOnTopHint)
支持拖动
闪烁提示

SettingsManager

职责：设置持久化管理（单例模式）

存储方式：QSettings (INI格式)

5.3 待办事项模块 (Todo)

类图

┌─────────────────┐     ┌─────────────────┐
│ TodoController  │────▶│DesktopTodoWidget│
│   (控制器)      │     │  (桌面窗口)      │
└────────┬────────┘     └────────┬────────┘
         │                       │
         │              ┌────────┴────────┐
         │              │                 │
         │              ▼                 ▼
         │     ┌─────────────┐   ┌─────────────┐
         │     │TaskItemWidget│   │   其他组件   │
         │     │ (任务项)     │   └─────────────┘
         │     └─────────────┘
         │
         │              ┌─────────────────┐
         ├─────────────▶│   TaskManager   │
         │              │  (任务管理器)    │
         │              │    [单例]       │
         │              └─────────────────┘
         │
         │              ┌─────────────────┐
         └─────────────▶│   LogManager    │
                        │  (日志管理器)    │
                        │    [单例]       │
                        └─────────────────┘

TodoController

职责：模块协调、窗口生命周期管理

DesktopTodoWidget

职责：桌面待办窗口

关键特性：

双模式显示（置顶/桌面固定）
窗口拖动与锁定
透明背景支持
Windows原生API置顶

TaskManager

职责：任务数据管理（单例模式）

关键功能：

任务CRUD操作
数据持久化 (JSON)
状态变更信号

LogManager

职责：操作日志管理（单例模式）

关键功能：

日志记录
JSON/CSV导出
数据持久化

数据结构

struct TaskData {
    int id;                      // 任务ID
    QString description;         // 任务描述
    bool isCompleted;            // 完成状态
    int completionScore;         // 完成度评分 (0-100)
    QDateTime creationTime;      // 创建时间
    QDateTime completionTime;    // 完成时间
};

struct LogEntry {
    QDateTime timestamp;         // 时间戳
    QString action;              // 操作类型
    QString taskDescription;     // 任务描述
    int score;                   // 评分
};

6. 数据流设计

6.1 计时器数据流

用户操作 ──▶ TimerSettingsPanel ──▶ TimerController ──▶ OverlayWidget
                    │                      │
                    │                      ▼
                    │              SettingsManager
                    │                (持久化)
                    │
                    └──────────────────────┘

6.2 待办事项数据流

用户操作 ──▶ DesktopTodoWidget ──▶ TaskManager ──▶ tasks.json
                    │                    │
                    │                    ▼
                    │              LogManager ──▶ logs.json
                    │                    │
                    └────────────────────┘

6.3 信号槽连接

TaskManager 信号

signals:
    void taskAdded(const TaskData &task);
    void taskUpdated(int id);
    void taskRemoved(int id);
    void taskCompleted(int id, bool completed);
    void taskScoreChanged(int id, int score);
    void tasksCleared();

LogManager 信号

signals:
    void logAdded();
    void logsCleared();

7. 设计模式应用

7.1 单例模式 (Singleton)

应用场景：全局唯一的管理器

实现示例：

class TaskManager : public QObject {
public:
    static TaskManager* instance() {
        static TaskManager instance;
        return &instance;
    }
private:
    TaskManager() = default;
    TaskManager(const TaskManager&) = delete;
    TaskManager& operator=(const TaskManager&) = delete;
};

使用位置：

SettingsManager - 计时器设置管理
TaskManager - 任务数据管理
LogManager - 日志管理

7.2 观察者模式 (Observer)

应用场景：Qt信号槽机制

实现方式：

// 数据变更通知
connect(taskManager, &TaskManager::taskAdded, 
        widget, &TodoWidget::onTaskAdded);

// 状态同步
connect(logManager, &LogManager::logAdded,
        panel, &SettingsPanel::updateStats);

7.3 MVC模式

应用场景：模块架构

角色	组件	职责
Model	TaskManager, LogManager	数据管理和业务逻辑
View	DesktopTodoWidget, TaskItemWidget	界面展示
Controller	TodoController	协调Model和View

7.4 组合模式 (Composite)

应用场景：任务列表组件

// TaskItemWidget 组合成任务列表
QVBoxLayout *m_taskLayout;
for (const TaskData &task : tasks) {
    TaskItemWidget *widget = new TaskItemWidget(task);
    m_taskLayout->insertWidget(0, widget);
}

8. 扩展指南

8.1 添加新模块步骤

创建模块目录

src/modules/newmodule/
├── newmodulecontroller.h/cpp
├── newmodulewidget.h/cpp
├── newmodulesettingspanel.h/cpp
└── newmodulemanager.h/cpp

实现控制器接口

class NewModuleController : public QObject {
public:
    QWidget* settingsPanel();  // 返回设置面板
    QWidget* mainWidget();     // 返回主界面组件
};

注册到主窗口

// mainwindow.cpp
m_newModuleController = new NewModuleController(this);
m_newModulePanel = m_newModuleController->settingsPanel();
m_stackedWidget->addWidget(m_newModulePanel);

添加入口卡片

QPushButton *newModuleBtn = new QPushButton("🔧 新工具");
connect(newModuleBtn, &QPushButton::clicked, this, &MainWindow::onNewModuleClicked);

更新CMakeLists.txt

set(SOURCES
    ...
    src/modules/newmodule/newmodulecontroller.cpp
    ...
)

8.2 模块开发规范

规范	说明
命名规范	模块名作为前缀，如 `TodoController`
文件组织	每个类一对.h/.cpp文件
信号槽	使用Qt5+新式连接语法
内存管理	使用Qt父子对象机制自动管理
数据持久化	JSON格式，存储在AppData目录

8.3 推荐的模块接口

class IModule {
public:
    virtual ~IModule() = default;
    virtual QString name() const = 0;
    virtual QString description() const = 0;
    virtual QWidget* settingsPanel() = 0;
    virtual void initialize() = 0;
    virtual void shutdown() = 0;
};

附录

A. 文件统计

类型	数量
C++ 头文件	12 个
C++ 源文件	13 个
总代码行数	~3000 行

B. 依赖关系图

MainWindow
    ├── Qt6::Widgets
    │   ├── QMainWindow
    │   ├── QStackedWidget
    │   ├── QSystemTrayIcon
    │   └── QPushButton
    │
    ├── TimerController
    │   ├── QTimer
    │   ├── OverlayWidget (Qt6::Widgets)
    │   └── SettingsManager (QSettings)
    │
    └── TodoController
        ├── DesktopTodoWidget (Qt6::Widgets)
        ├── TaskManager (QFile, QJsonDocument)
        └── LogManager (QFile, QJsonDocument)

C. 构建配置

cmake_minimum_required(VERSION 3.16)
project(PCProductivityToolbox VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)

find_package(Qt6 REQUIRED COMPONENTS Core Widgets Gui)

add_executable(${PROJECT_NAME} ${SOURCES} ${HEADERS})
target_link_libraries(${PROJECT_NAME} PRIVATE Qt6::Core Qt6::Widgets Qt6::Gui)

文档维护者: Kitools开发团队
最后更新: 2026-02-19

Kitools 架构设计

PC效率工具箱 - 项目架构说明书

目录

1. 项目概述

1.1 项目定位

1.2 设计目标

1.3 版本信息

2. 技术栈

2.1 核心技术

2.2 Qt模块依赖

2.3 平台特定API

3. 目录结构

4. 架构设计

4.1 整体架构

4.2 模块交互图

4.3 模块内部结构

5. 核心模块详解

5.1 核心框架 (Core)

MainWindow

5.2 计时器模块 (Timer)

类图

TimerController

OverlayWidget

SettingsManager

5.3 待办事项模块 (Todo)

类图

TodoController

DesktopTodoWidget

TaskManager

LogManager

数据结构

6. 数据流设计

6.1 计时器数据流

6.2 待办事项数据流

6.3 信号槽连接

TaskManager 信号

LogManager 信号

7. 设计模式应用

7.1 单例模式 (Singleton)

7.2 观察者模式 (Observer)

7.3 MVC模式

7.4 组合模式 (Composite)

8. 扩展指南

8.1 添加新模块步骤

8.2 模块开发规范

8.3 推荐的模块接口

附录

A. 文件统计

B. 依赖关系图

C. 构建配置