# 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-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 进度簿 ProgressPilot

一款面向中文个人工作者的本地桌面任务管理应用。macOS 版使用 SwiftUI，Windows 版使用 WinUI 3；两端都把主题、描述、优先级、分类、状态、可选日期和标签整理成结构化数据，并提供待办、全部任务、看板、统计、分类和数据与备份六个视图。

## 功能

- 任务新建、编辑、删除与一键完成
- “待办”页纵向四项快速记录卡片：主题、描述、优先级、分类
- `Command + N` 聚焦主题，P0 / P1 / P2 与分类可直接点选，回车快速流转
- 快速记录可在原卡片内展开，补充状态、计划日期和标签，不打开弹窗
- 待办任务默认紧凑查看，点击后临时展开并直接修改全部字段
- 全部任务同样按需展开，并在卡片内维护全部信息，无需编辑弹窗
- 分类独立维护，支持新增、重命名和删除保护
- P0 / P1 / P2 优先级
- 待安排、已安排、进行中、卡住了、已完成五种状态
- 可选计划日期、备注、可复用标签和分类
- 快速新建默认不启用计划日期；开启后才显示日期选择
- 无日期任务不显示日期，也不参与逾期计算
- 标签逐个添加和移除，已在任务中使用的标签可直接复用
- 待办展示全部未完成任务，按待安排、已安排、进行中、卡住了分组
- 每个待办状态组内先显示逾期任务，再按 P0 / P1 / P2 排序
- 待办统计展示待办总数、逾期数和高优先级数
- 搜索、优先级/状态/分类筛选
- 五列状态看板，支持拖动调整栏内顺序、插入其他状态栏指定位置，并保留菜单移动入口
- JSON 纯本地持久化与自动备份
- macOS / Windows 数据导入导出与导入前备份

## 环境要求

### macOS

- macOS 14 Sonoma 或更高版本
- Swift 6.2 或更高版本；Xcode 为可选
- 无第三方依赖，无需联网

### Windows

- Windows 10 22H2 或 Windows 11，x64
- 构建需要 .NET 8 SDK、Windows SDK 和 Inno Setup 6
- 安装包为 self-contained，终端用户无需单独安装 .NET

## macOS 构建与运行

在项目根目录运行：

```bash
./Scripts/check.sh
./Scripts/package_app.sh
open dist/ProgressPilot.app
```

开发时也可以直接运行 Swift Package：

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

生成同时支持 Apple Silicon 与 Intel 的内测 DMG 需要安装与 Swift 6.2 兼容的完整 Xcode：

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

产物为 `dist/ProgressPilot-<版本>-macos-universal.dmg`。当前使用临时签名，未做 Developer ID 签名或 Apple 公证。

## Windows 构建与打包

在 Windows PowerShell 中运行：

```powershell
.\Scripts\package_windows.ps1
```

脚本会执行 NuGet 还原、单元测试、`win-x64` self-contained 发布和 Inno Setup 打包。NuGet 还原会联网下载 `Microsoft.WindowsAppSDK` 与测试依赖；首次执行前应确认构建环境允许下载。产物为 `dist\ProgressPilot-<版本>-windows-x64-setup.exe`。当前安装程序未做 Authenticode 签名，内测设备可能显示 SmartScreen 提示。

## 使用 Xcode 运行（可选）

1. 双击 `ProgressPilot.xcodeproj`。
2. 在顶部 Scheme 中选择 `ProgressPilot` 和 `My Mac`。
3. 按 `Command + R` 运行。

也可以在 Xcode 中打开仓库根目录的 `Package.swift`，Swift Package 与 Xcode 工程共用同一套源码。完整 Xcode 中可用 `Command + U` 运行 `TaskCoreTests`。

## 项目结构

```text
.
├── ProgressPilot.xcodeproj/       # 可直接打开的 Xcode 工程
├── Package.swift                  # 无 Xcode 时也可编译和测试
├── ProgressPilot/
│   ├── ProgressPilotApp.swift     # 应用入口与共享任务仓库
│   ├── Models/
│   │   └── WorkTask.swift         # Codable 模型与 JSON 任务仓库
│   └── Views/
│       ├── ContentView.swift      # 侧边栏、路由和全局操作
│       ├── TodayView.swift        # 待办分组与快速记录
│       ├── TaskListView.swift     # 全部任务、筛选与完整内联编辑
│       ├── BoardView.swift        # 状态看板
│       ├── StatisticsView.swift   # 汇总与分类统计
│       ├── CategoryManagementView.swift # 分类独立维护
│       ├── TaskEditorView.swift   # 完整新建与其他页面详细编辑
│       └── Components.swift       # 通用视觉组件
├── ProgressPilotCore/             # 任务规则与统计聚合
├── Tests/ProgressPilotCoreTests/  # Xcode 模型与统计测试
├── Checks/ProgressPilotCoreChecks # 命令行核心逻辑检查
├── windows/                       # WinUI 3 应用、核心逻辑、测试和安装器
├── shared/fixtures/               # 双平台数据协议样例
├── Scripts/                       # 检查与 Release App 打包脚本
├── Resources/Info.plist           # 本地 App Bundle 元数据
└── docs/
    ├── progress-pilot-prd.md      # 产品需求与验收标准
    └── information-architecture.md
```

## 数据说明

macOS 的任务与分类保存在 `~/Library/Application Support/ProgressPilot/tasks.json`，Windows 保存在 `%LOCALAPPDATA%\ProgressPilot\tasks.json`，都不会上传到网络。每次覆盖主文件前，应用会把上一份有效数据写入 `tasks.json.bak`；每天首次保存还会生成 `tasks.snapshot-<UTC时间>.json`。自动快照最多保留10份，超过30天会清理，但始终至少保留最新1份。旧版 Mac 任务中的 `projectName` 会自动读取为分类，并在下一次成功保存后升级为新版结构。如果主文件损坏会自动读取备份；主文件和备份都无法读取时会禁止写入，避免覆盖原数据。

“数据与备份”页面及“数据”菜单可导出或导入 `.progresspilot.json`。导入会完整校验文件，并在整体替换前生成 `tasks.pre-import-<UTC时间>.json`；恢复本地历史前会生成 `tasks.pre-restore-<UTC时间>.json`。导入和恢复都不会按任务 ID 合并。格式说明见 [跨平台数据文档](docs/cross-platform-data.md)。

## 手工验收建议

1. 在“分类”新增两个分类，确认立即出现在待办快速记录卡片。
2. 按 `Command + N`，填写主题和描述，点选优先级、分类后回车。
3. 确认任务立即出现在“待办”的“待安排”分组，描述、优先级和分类均正确。
4. 连续录入两条任务，确认保存后主题和描述清空、优先级恢复 P1、分类保持、主题继续聚焦。
5. 确认待办任务默认是紧凑查看状态；点击一条后自动展开并聚焦主题，同时只有这一条处于编辑状态。
6. 修改主题、描述、优先级、分类或状态，再点击另一条任务或页面空白处，确认前一条自动保存并收起。
7. 展开快速记录，确认可在原卡片内选择状态、逐个添加标签，且计划日期默认关闭。
8. 开启计划日期，确认日期选择器出现；关闭后确认日期选择器隐藏。
9. 不设置日期保存，确认任务出现在“待办”的“待安排”分组，且不显示日期、不被计为逾期。
10. 新增一个标签后编辑另一条任务，确认该标签出现在“常用”并可直接选择。
11. 进入“全部任务”，确认任务默认收起；展开后可直接维护主题、描述、优先级、分类、状态、日期和标签。
12. 确认搜索、优先级、状态和分类位于同一张圆角筛选卡，选中条件有明显高亮。
13. 修改多项后点击另一条任务或筛选区域，确认完整快照自动保存并收起，不出现编辑弹窗。
14. 重命名一个使用中的分类，确认对应任务同步更新；尝试删除时确认被阻止。
15. 在同一状态栏中把第三张任务卡拖到第一张前面，确认顺序立即改变；退出重开后确认顺序仍然保持。
16. 把任务卡拖到“进行中”的某张卡片前，确认任务改变状态并插入指定位置；拖到栏底确认排在最后。
17. 再用卡片菜单移动一次，确认任务追加到目标栏末尾，备用入口仍可用。
18. 确认待办列表只按待安排、已安排、进行中、卡住了分组；每组内逾期任务排在最前，同为逾期或非逾期时按 P0、P1、P2 排序。
19. 确认待办统计框依次显示待办总数、逾期和高优先级数量。
20. 确认录入、任务卡、看板和统计页都不显示工时或百分比进度。
21. 退出并重新打开 App，确认任务、分类和标签仍然存在。