# TODO

**Repository Path**: incoparab/todo

## Basic Information

- **Project Name**: TODO
- **Description**: 待办事项管理
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Python

## README

# 待办事项管理

基于 Python + PyQt6 的本地待办事项管理工具，支持普通模式和极简模式两种视图。

## 功能清单

### 清单管理
- 每日清单：同一天只保留一个，自动按日期标题命名（如"6月15日 周一"）
- 项目清单：自定义名称，适合长期跟踪的项目任务
- 清单置顶：项目清单支持置顶/取消置顶，置顶清单排在最前
- 清单颜色：6 种可选颜色标识
- 清单排序：置顶优先 → 进行中置顶 → 已完成沉底

### 任务管理
- 添加/编辑/删除任务
- 任务完成/取消完成
- 三种优先级：紧急（红）、正常（紫）、长期（绿）
- 任务按未完成→已完成、优先级、创建时间排序

- 编辑弹窗支持修改任务内容和优先级
- 任务行显示创建时间和完成时间
- 撤销删除（Ctrl+Z，最多 20 步）

### 任务提醒
- 任务行「提醒」按钮（极简模式为右键菜单）可设置/修改/清除提醒时间
- 快捷时间：1 小时后 / 3 小时后 / **下午 4 点** / 明天 09:00（下午 4 点已过则自动顺延到明天）
- 时间选择：**圆角日历弹窗**选日期 + 时/分下拉，**分钟最小单位 10 分钟**（00/10/20/30/40/50）
- 到点后弹出提醒窗口（**无声音**），列出所有到点事项，可一键跳转对应清单
- 弹窗为独立置顶窗口，**主窗口最小化/不在前台时同样会弹出**；Windows 上抢前台失败会闪烁任务栏提示
- 任务行显示提醒时间；任务勾选完成后自动不再提醒；程序未运行期间不提醒
- **事件驱动调度**：只在"下一个提醒时刻"和每次变动（设置/完成/删除）时检查，**没有待提醒时不启动任何定时器**（无周期性轮询），空闲时最多每 10 分钟兜底重算一次

### 视图模式
- **普通模式**（980×680 起）：左侧清单列表 + 右侧任务详情（默认 1120 宽度）
- **极简模式**（320×520 起，最大宽 380）：每日待办 / 项目待办两组卡片
- 支持抽屉折叠/展开，模式切换不丢失滚动位置
- 日历视图：点击日期快速跳转到对应每日清单；有未完成任务的日期显示橙色圆点，任务全部完成的日期显示绿色圆点
- 全局搜索：侧边栏单个搜索框，按清单名称或任务内容过滤清单列表和任务列表

### 数据管理
- 本地 JSON 存储，无需数据库，带格式版本号（旧数据自动兼容迁移）
- 每次修改立即保存（原子写入，无防抖丢失窗口），关闭/退出时兜底保存
- 保存前自动备份（最多保留 10 份带时间戳的备份文件），主文件损坏时自动从备份恢复
- 导出为 JSON 文件
- 从 JSON 文件导入（自动生成新 ID 避免冲突）

### 系统集成
- 窗口置顶切换（Win32 API）
- 开机自启动（Windows 注册表）
- 单实例保护：重复打开会提示"程序已经在运行"，避免多实例并发读写数据文件
- 快捷键：Ctrl+N 聚焦输入框、Ctrl+Z 撤销删除

## 项目架构

```text
待办事项管理/
├── main.py                  # 入口：QApplication 初始化、主题加载、启动主窗口
├── build.ps1                # PyInstaller 打包脚本
├── requirements.txt         # 依赖：PyQt6, pyinstaller
├── icon.ico / icon.svg      # 应用图标
├── test_smoke.py            # 冒烟测试
└── todo_app/                # 核心模块
    ├── models.py            # 数据模型层（Note / TodoItem / 排序 / 规范化）
    ├── store.py             # 持久化层（JSON 读写 / 版本化 / 自动备份 / 资源路径）
    ├── controller.py        # 数据层控制器（清单/任务增删改查、排序、撤销、提醒查询）
    ├── reminder.py          # 提醒（设置时间对话框 / 到点弹窗 / 前台激活与任务栏闪烁）
    ├── main_window.py       # 窗口与 UI 交互（视图切换 / 置顶 / 自启 / 导入导出 / 设置持久化）
    ├── sidebar.py           # 普通模式 - 侧边栏（清单列表 + 日历 + 任务搜索 + 操作按钮）
    ├── task_panel.py        # 普通模式 - 任务面板（筛选 / 任务列表 / 输入框）
    ├── compact_view.py      # 极简模式 - 卡片布局
    ├── widgets.py           # 可复用 UI 组件（日历 / 任务行 / 置顶按钮 / 抽屉等）
    ├── task_edit_dialog.py  # 任务编辑弹窗
    ├── autostart.py         # 开机自启（Windows 注册表）
    └── theme.py             # 全局 QSS 样式表
```

### 模块关系

```text
main.py
  └─► MainWindow (main_window.py)
        │
        ├─ 普通模式 ─┬─► sidebar.py      左侧：日历 + 清单列表 + 任务搜索 + 工具按钮
        │            └─► task_panel.py    右侧：标题 + 筛选 + 任务列表 + 输入框
        │
        ├─ 极简模式 ───► compact_view.py  每日 / 项目两组卡片（含置顶按钮）
        │
        ├─ 数据层 ───┬─► controller.py    NoteController：业务逻辑 / 排序 / 撤销 / 提醒查询
        │            ├─► models.py        Note / TodoItem
        │            └─► store.py         JSON 读写 / 版本化 / 自动备份
        │
        ├─ 提醒 ───────► reminder.py      设置提醒对话框 / 到点弹窗（无声音，最小化也能弹出）
        │
        ├─ UI 组件 ─┬─► widgets.py       TaskRow / CompactNoteCard / RoundedCalendar / DrawerHeader 等
        │           └─► task_edit_dialog.py
        │
        └─ 系统 ─────► autostart.py      开机自启
                       theme.py          全局 QSS 样式
```

### 数据流

```text
用户操作 ──► MainWindow（UI 交互）──► NoteController（业务逻辑）──► models 修改对象 ──► store 持久化 ──► 刷新 UI
```

### 极简模式布局

```text
┌─ ~380×520+ ────────────────────────┐
│ 我的待办        [正常][自启][置顶]     │
│ 2 个清单 · 5/8 已完成                 │
├─ 每日待办 ──────────────────────────┤
│ ▼ 6月15日 周一              [+]    │
│   [✓] 买菜                          │
│   [ ] 写报告                        │
├─ 项目待办 ──────────────────────────┤
│ ▶ 项目A                 [+]        │
│ ▼ 项目B     [▲] [删除]    [+]       │
│   [ ] 设计稿                        │
│ ▼ 项目C     [▲] [删除]    [+]       │
│   [ ] 文档更新                       │
└─────────────────────────────────────┘
```

## 数据位置

| 场景 | 路径 |
|------|------|
| 开发运行 | `./notes.json` |
| 打包后 exe | `%APPDATA%\TodoManager\notes.json` |

## 开发

```powershell
pip install -r requirements.txt
python main.py
```

## 测试

```powershell
pip install pytest
python -m pytest test_smoke.py -v
```

## 打包

```powershell
.\build.ps1
```

输出：`dist\待办事项管理.exe`