soft_quay/docs/06-tasks.md

# 任务路线图(Roadmap)

> 本文是**只读路线图**:维护阶段划分、里程碑、待办池和建议拆分清单,把 MVP 拆成小步、可独立交付的任务,让 AI 一步一步开发,避免一次生成整个项目。
> 真实任务以「一任务一文件」存放在 [`tasks/`](tasks/README.md)(`docs/tasks/T-<编号>.md`)。未启用 Gitea 时以任务文件 frontmatter 为状态权威;启用后以 Issue 为实时状态、合并后的任务文件为长期事实。**本文不跟踪单任务状态**。

## 使用规则

1. **开工先落文件**:从下方「建议拆分清单」把下一个任务按 [`tasks/README.md`](tasks/README.md) 落成 `docs/tasks/T-<编号>.md`(沿用建议编号),把验收要点展开成可执行、可观察的步骤,再开始实现。
2. **每个 agent 一次只做一个任务**:领取、状态流转、执行记录、完成定义全部遵循 [`tasks/README.md`](tasks/README.md) 和 [编码规则](05-coding-rules.md);`DONE` 需要可运行证据,多 agent 只并行写路径互不重叠的任务。
3. **不跳步**:依赖未完成的任务不能开工。
4. **本文只在规划变化时修改**:调整阶段划分、里程碑、增删建议任务或 Backlog 条目时才动本文;单个任务开工或完成**不**修改本文。
5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。

## 建议拆分清单

以下是按阶段列出的建议任务;`T-编号` 为建议编号,落成任务文件时沿用。

### Phase 0 · 工程骨架

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-001 | 初始化 monorepo 骨架 | - | `go.work` + core/app-modern/app-win7 三模块;core `go test ./...` 在 Linux 通过;两个 EXE 可交叉编译(modern 用锁定 Go,win7 强制 Go 1.20);用真实命令替换 `init.sh`/`init.ps1` 顶部三个变量,并同步 `00-ai-start-here.md`、`03-tech-stack.md`、`05-coding-rules.md`、`current-state.md` |
| T-002 | 建立 domain 状态模型与事件总线 | T-001 | 软件状态机枚举与迁移规则、application.Event 定义与 runtime 骨架;状态机表驱动测试覆盖非法迁移 |
| T-003 | Gio 空窗口 + 平台层 stub | T-001 | 两个 app 打开空主窗口(AppShell 骨架);platform/windows 接口 + 非 Windows stub;core 不 import Gio 的检查脚本 |
| T-004 | CI 双目标编译闸门 | T-001 | CI(或本地脚本)执行:core vet+test、modern 构建、win7 用 Go 1.20 构建、依赖 go 版本检查 |

### Phase 1 · 最高风险原型

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-101 | 签名清单验签与缓存回退原型 | T-002 | Ed25519 验签;伪造/篡改清单被拒绝(testdata 恶意样例);断网回退最后验证成功缓存;结论写入文档 |
| T-102 | ZIP 安全解压原型 | T-002 | 表驱动攻击样例全部被拒:绝对路径、`../`、符号链接、zip bomb(数量/体积/压缩比上限)、entrypoint 外逃 |
| T-103 | staging/backup 原子切换与回滚原型 | T-102 | 切换成功、切换中断(模拟崩溃)、回滚三条路径测试通过;状态可从磁盘恢复 |

### Phase 2 · 清单与软件列表

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-201 | catalog 模块正式接入 | T-101 | 清单获取、验签、缓存、min_os/架构过滤、status 处理;app.json/manifest Schema 落入 `schemas/` |
| T-202 | 本地安装状态识别 | T-201, T-103 | installed-app.json 读写;12 种状态正确呈现;版本比较用 SemVer |
| T-203 | 主界面软件列表 | T-202, T-003 | 虚拟列表 + 搜索/分类/视图切换;控件状态按软件 ID;数百项滚动流畅;Layout 无 IO |
| T-204 | 软件详情与图标缓存 | T-203 | 详情弹层;图标内存+磁盘缓存(按 DPI);断网可显示缓存图标 |

### Phase 3 · 下载与安装

Phase 3 的 T-301 → T-302 → T-303 是安全关键依赖链,任务之间保持串行。每个任务内部默认采用“一个写入 Agent + 测试设计/安全审查只读 Agents”;只有先落成子任务、提交共享接口且写路径无重叠时才并行编码,完整规则见 [`tasks/README.md`](tasks/README.md) 与仓库 `AGENTS.md`。

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-301 | 下载队列 | T-202 | 并发默认 2;暂停/取消/重试;Range 续传;任务元数据持久化,重启恢复;事件驱动进度 |
| T-302 | 安装流程整合 | T-301, T-102, T-103 | 完整链:下载→SHA-256→app.json 比对→安全解压→staging→切换→健康检查→回滚;`04-architecture.md` 关键安全流程顺序逐步可观察 |
| T-303 | 失败处理与磁盘预检查 | T-302 | 哈希不符、磁盘不足、包损坏、程序占用各有确定结果与错误码;不破坏旧版本 |

### Phase 4 · 启动、运行与更新

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-401 | 进程检测与软件启动 | T-302 | Toolhelp 快照检测运行状态;启动前检查文件/兼容/占用;WorkingDirectory 正确 |
| T-402 | 子软件更新流程 | T-401 | 可更新识别→确认退出→更新→失败回滚仍可启动旧版;更新不触碰 data/licenses |
| T-403 | SoftBoxUpdater 盒子自更新 | T-402 | 独立 Updater 按 CLI 合约工作;更新中断可恢复;新版健康状态写入 |

### Phase 5 · 授权

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-501 | 机器指纹(machine_hash) | T-001 | 平台层采集多标识→清洗生成 hash;不落原始序列号/MAC;非 Windows stub 可测 |
| T-502 | Ed25519 许可证验证 | T-501 | licensing 模块离线验签;复制到不匹配机器被拒;测试用专用密钥对 |
| T-503 | 授权界面与试用/导入/换绑 | T-502, T-204 | 导入、授权列表、试用状态展示;撤销名单验签与宽限期 |

### Phase 6 · Win7 加固与发布

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-601 | Win7 API 降级与真机冒烟 | T-403 | 动态加载检查(导入表无 Win10+ API);Win7 SP1 真机/VM 完成清单→下载→安装→启动 |
| T-602 | Win7 兼容矩阵验证 | T-601 | DPI(100/125/150)、中文 IME、经典主题/Aero、远程桌面、非管理员、旧证书按矩阵记录结果 |
| T-603 | 发布流水线 | T-403, T-503 | 构建→注入版本→签名→打包 ZIP→哈希→生成签名 manifest;双通道互不交叉;干净机器完成下载/更新/回滚/授权测试 |

## 里程碑

- M1:工程骨架完成,双目标可编译,core 无头可测(Phase 0)。
- M2:三大高风险原型(验签、解压、原子切换)全部验证(Phase 1)。
- M3:「清单→列表→下载→安装→启动」核心闭环跑通(Phase 2-4 前半)。
- M4:自更新 + 授权完成,MVP 验收(Phase 4-5)。
- M5:Win7 遗留版可交付,双通道发布(Phase 6)。

## 待办池(Backlog)

- files.json 复核与修复功能(V1.1)。
- 命名管道 prepare_update/ready 优雅退出协议(V1.1)。
- --softbox-info / --softbox-health 健康检查接入(V1.1)。
- Win7 x86(386)构建目标(按真实用户占比)。
- 便携模式(portable.flag + `.softbox/` 相对目录)。
- beta 通道支持。
- 托盘图标与最小化到托盘。
- 拼音搜索。
- SBOM 生成与发布归档。
- softbox-sdk 拆分(独立仓库,待协议稳定后)。