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`、验证并提交后才开始下一任务。
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 0 交叉审核加固

审核整改任务沿用全局防撞编号;路线图原有最大编号为 T-603,因此从 T-604 起编号。整改按 `docs/review/phase0-skeleton-review.md` 的定稿顺序串行落成和执行。

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-604 | 隔离 modern 与 Win7 workspace | T-004 | 根 workspace 只含 modern/core;Win7 使用独立 Go 1.20 workspace;双 workspace 分别 sync;版本检查证明 Gio v0.10.1/v0.6.0 不交叉解析 |

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

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

#### Phase 1 交叉审核加固

Phase 1 安全整改按 `docs/review/phase1-security-review.md` 的交叉复核定稿顺序串行落成。T-605 与 T-612 已关闭;后续断电耐久和签名向量任务在前一整改完成并提交后再正式编号,T-302 继续后置。

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-605 | 统一 Windows 安全路径校验并封堵 ZIP 逃逸 | T-102, T-201, T-202, T-604 | Catalog/ZIP/installed-app 共用逐段 Windows 安全相对路径策略;拒绝尾随空格/点与 DOS 设备名;输出路径增加 destination 包含性兜底;原生 Windows 用例证明不写出 staging |
| T-612 | 在 ZIP 打开前限制包大小与中央目录元数据 | T-605 | 已验签 Catalog size、已完成普通下载文件长度与同句柄 EOCD/ZIP64 预扫描一致;在 `zip.NewReader` 前限制原始包、中央目录与声明条目数 |

### 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 2 交叉审核加固

Phase 2 整改按 `docs/review/phase2-review.md` 的交叉复核定稿顺序串行落成。T-606 已关闭正式图标接入前的并发、读取和内存边界;T-607 建立后台图标结果经 application event 回到 Gio UI goroutine 的线程契约;T-608 为两个隔离 Gio 适配器建立交互契约;T-609 修正 `VisibleItems` 快照生命周期;T-610 在不改变行为的前提下拆分双端 Gio shell 职责;T-611 已用真实 fail-closed 传播、双端安全诊断和人工 runbook 关闭最终观察项。

| ID | 任务 | 依赖 | 验收要点 |
| --- | --- | --- | --- |
| T-606 | 收紧图标缓存并发与内存边界 | T-204, T-605 | 按 key in-flight 去重且不同 key 并行;Fetcher 流式有界读取;memory LRU 同时限制字节/条目;modern/win7 删除 app 时剪枝内存 ImageOp |
| T-607 | 建立图标后台结果的 UI 线程事件投递 | T-606 | 后台 Load/Decode 只发布 application event;有界 relay 请求重绘;UI goroutine drain 后 ApplyIcon;过期结果不回写已删除或已换图标的 app |
| T-608 | 建立双 Gio 适配器交互契约 | T-607 | 双端同场景验证 Editor/Clickable 接线、AppID 行身份、详情上下文、500 项 viewport 与控件释放;不重复 ViewModel 纯逻辑 |
| T-609 | 修正 VisibleItems 快照生命周期 | T-608 | refilter 构造新 backing array 后替换;旧快照跨 model 更新保持稳定;每帧读取不复制;明确单 owner 与只读约定 |
| T-610 | 拆分双端 Gio shell 职责 | T-609 | 两端按状态/根编排、header/navigation、catalog/list、detail、style 拆为同 package 镜像文件;行为、事件顺序、视觉与 Gio 隔离不变 |
| T-611 | 建立不安全图标缓存诊断与人工恢复指引 | T-610 | 真实非普通 entry 贯通 unsafe_cache event;双端详情显示无敏感字段的 fail-closed/人工处理提示;不自动删除或 quarantine |

### Phase 3 · 下载与安装

Phase 3 的 T-301 → T-302 → T-303 是安全关键依赖链,任务之间保持串行。T-302 起继续由单 Agent 完成规格、实现、测试、安全检查和提交,不启动子 Agent;完整规则见 [`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 拆分(独立仓库,待协议稳定后)。