# ProgressPilot

**Repository Path**: chazzorg/progress-pilot

## Basic Information

- **Project Name**: ProgressPilot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 进度簿 ProgressPilot

进度簿是一款面向中文个人工作者的本地桌面任务管理应用，提供 macOS 和 Windows 版本。应用将主题、描述、优先级、分类、状态、可选日期和标签保存为结构化数据，通过待办、全部任务、看板、统计、分类和数据与备份六个视图帮助用户记录和推进工作。

应用不需要账号，默认不联网，任务数据只保存在本机。

## 核心功能

### 快速记录

- 在“待办”页直接填写主题、描述、优先级和分类。
- macOS 可使用 `Command + N`、Windows 可使用 `Ctrl + N` 聚焦主题。
- 主题和描述支持回车流转，优先级和分类可直接点选。
- 可在原卡片内展开状态、计划日期和标签，无需打开额外弹窗。
- 快速记录完成后清空主题和描述，保留上次选择的分类，方便连续录入。

### 任务管理

- 支持新建、编辑、删除、完成和重新打开任务。
- 支持 P0、P1、P2 三种优先级。
- 支持待安排、已安排、进行中、卡住了、已完成五种状态。
- 计划日期为可选项；未设置日期的任务不显示日期，也不参与逾期计算。
- 标签可逐个添加和移除，已有标签可以在其他任务中复用。
- 分类支持新增、重命名和删除保护；使用中的分类不能直接删除。

### 待办与看板

- 待办展示全部未完成任务，并按待安排、进行中、已安排、卡住了分组；每个分组可独立收起和展开。
- 每个状态组内先显示逾期任务，再按 P0、P1、P2 排序。
- 看板按五种状态分栏展示任务。
- 支持在同一状态栏内拖动排序。
- 支持跨状态栏拖动，并插入指定任务前或追加到栏尾。
- 状态菜单可作为拖动操作的备用入口。
- 看板顺序会持久化，重新打开应用后仍然保持。

### 查询与统计

- 全部任务支持主题、描述和标签搜索。
- 支持按优先级、状态和分类筛选。
- 统计页展示任务总量、待处理数量、已完成数量、优先级分布和分类分布。

### 数据与备份

- 使用 JSON 文件在本地持久化任务和分类。
- 每次覆盖主数据前保留即时备份。
- 每个 UTC 日期首次保存前生成自动快照。
- 自动快照最多保留10份，并清理超过30天的旧快照。
- 支持立即备份、查看备份历史和恢复本地备份。
- 支持 macOS 与 Windows 之间导入、导出 `.progresspilot.json` 文件。
- 导入和恢复前会先生成备份，再整体替换本地数据。

## 系统要求

### macOS

运行要求：

- macOS 14 Sonoma 或更高版本。
- Apple Silicon 或 Intel 处理器，具体取决于使用的构建产物。

源码构建要求：

- Swift 6.2 或更高版本。
- 构建 Universal DMG 需要与 Swift 6.2 兼容的完整 Xcode。
- 项目只使用系统框架，无第三方运行时依赖。

### Windows

运行要求：

- Windows 10 22H2 或 Windows 11。
- x64 处理器。
- 安装包为 self-contained，终端用户无需单独安装 .NET。

源码构建要求：

- .NET 8 SDK。
- Windows SDK。
- Inno Setup 6。
- NuGet 网络访问。

## 安装与启动

### macOS

使用 App Bundle 时，将 `ProgressPilot.app` 复制到“应用程序”目录后启动。

使用 DMG 时：

1. 打开 `ProgressPilot-<版本>-macos-universal.dmg`。
2. 将“进度簿”拖到“Applications”。
3. 从“应用程序”目录启动“进度簿”。

用于外部分发的 macOS 应用应完成 Developer ID 签名和 Apple 公证。

### Windows

1. 运行 `ProgressPilot-<版本>-windows-x64-setup.exe`。
2. 按安装向导完成安装，可选择创建桌面快捷方式。
3. 从开始菜单或桌面快捷方式启动“进度簿”。

默认安装位置：

```text
%LOCALAPPDATA%\Programs\ProgressPilot
```

用于外部分发的 Windows 安装包建议完成 Authenticode 签名。

## 使用指南

### 记录任务

1. 打开“待办”。
2. 输入任务主题和可选描述。
3. 选择优先级与分类。
4. 如需状态、计划日期或标签，点击“展开填写”。
5. 点击“保存待办”；macOS 也可按描述框回车，Windows 可按 `Ctrl + Enter` 完成录入。

### 编辑任务

在“待办”或“全部任务”中点击任务卡片即可原地展开。可以修改主题、描述、优先级、分类、状态、计划日期和标签。切换到其他任务或页面区域时，当前有效内容会自动保存。

### 调整看板

- 将任务拖到同一栏的另一张卡片前，可调整栏内顺序。
- 将任务拖到其他状态栏的卡片前，可改变状态并插入指定位置。
- 将任务拖到状态栏底部，可追加到该栏末尾。
- 也可以使用卡片右上角的状态菜单移动任务。

### 导出与导入

在“数据与备份”页面或“数据”菜单中选择导出，生成 `.progresspilot.json` 文件。

导入时应用会：

1. 完整校验文件格式、版本和任务字段。
2. 创建导入前备份。
3. 整体替换当前任务和分类。

导入不是数据合并，也不提供自动同步。执行导入前应确认导入文件内容正确。

### 备份与恢复

- “立即备份”会在应用数据目录生成一份命名备份。
- “备份历史”列出即时备份、自动快照、导入前备份和恢复前备份。
- 恢复历史备份前，应用会先保存当前数据的恢复前备份。
- 如果主数据和即时备份都无法解析，应用会停止写入，避免用空数据覆盖原文件。

## 构建与部署

### macOS App Bundle

在项目根目录执行：

```bash
./Scripts/check.sh
./Scripts/package_app.sh
```

产物：

```text
dist/ProgressPilot.app
```

该脚本使用当前 Mac 的目标架构构建应用，并执行临时签名和签名结构校验。

开发时也可以直接运行：

```bash
swift build
swift run ProgressPilot
```

### macOS Universal DMG

安装完整 Xcode 后，在项目根目录执行：

```bash
./Scripts/package_macos.sh
```

产物：

```text
dist/ProgressPilot-<版本>-macos-universal.dmg
```

脚本会构建 `arm64 x86_64` Universal App、复制应用图标、执行临时签名并生成 DMG。正式外部分发时，应将临时签名替换为 Developer ID Application 签名，并对最终产物执行 Apple 公证。

### Windows x64 安装包

在 Windows PowerShell 中执行：

```powershell
.\Scripts\package_windows.ps1 -Version 1.0.0
```

脚本依次执行：

1. NuGet 还原。
2. Release 单元测试。
3. `win-x64` self-contained 发布。
4. Inno Setup 安装包构建。

产物：

```text
dist\ProgressPilot-1.0.0-windows-x64-setup.exe
```

NuGet 还原会联网下载 `Microsoft.WindowsAppSDK` 和测试依赖，执行前应确认构建环境允许联网和运行依赖脚本。外部分发时应对最终安装包执行 Authenticode 签名。

### 使用 Xcode 开发

1. 打开 `ProgressPilot.xcodeproj`。
2. 选择 `ProgressPilot` Scheme 和 `My Mac`。
3. 使用 `Command + R` 运行。
4. 使用 `Command + U` 运行测试。

也可以在 Xcode 中直接打开仓库根目录的 `Package.swift`。Swift Package 与 Xcode 工程共用同一套源码。

## 数据存储

macOS 数据目录：

```text
~/Library/Application Support/ProgressPilot
```

Windows 数据目录：

```text
%LOCALAPPDATA%\ProgressPilot
```

主要文件：

| 文件 | 作用 |
|---|---|
| `tasks.json` | 当前任务和分类 |
| `tasks.json.bak` | 上一次覆盖前的即时备份 |
| `tasks.snapshot-<UTC时间>.json` | 自动快照 |
| `tasks.pre-import-<UTC时间>.json` | 导入前备份 |
| `tasks.pre-restore-<UTC时间>.json` | 恢复前备份 |

旧版 macOS 数据中的 `projectName` 会作为分类读取，并在下一次成功保存后升级为当前结构。跨平台文件格式见 [跨平台数据格式](docs/cross-platform-data.md)。

## 升级与卸载

升级前建议先在“数据与备份”中导出数据。

- macOS 升级：退出应用后，用新版本 `ProgressPilot.app` 替换旧版本。
- Windows 升级：退出应用后运行新版安装程序。
- macOS 卸载：退出应用并移除 `ProgressPilot.app`。
- Windows 卸载：使用 Windows“已安装的应用”卸载“进度簿”。

应用程序和用户数据位于不同目录。卸载应用不会自动删除任务数据；如需彻底移除，应先导出所需数据，再单独处理对应的数据目录。

## 项目结构

```text
.
├── ProgressPilot.xcodeproj/       # macOS Xcode 工程
├── Package.swift                  # Swift Package 配置
├── ProgressPilot/                 # macOS SwiftUI 应用
├── ProgressPilotCore/             # macOS 共享任务规则与统计
├── Tests/                         # macOS 测试
├── Checks/                        # macOS 命令行检查
├── windows/                       # WinUI 3 应用、核心逻辑、测试和安装器
├── shared/fixtures/               # 跨平台数据协议样例
├── Resources/                     # 应用元数据与图标
├── Scripts/                       # 检查和打包脚本
└── docs/                          # 产品、架构和数据格式文档
```