Implement resumable download queue (T-301)

docs/api.md

@@ -200,6 +200,42 @@ T-102 Phase 1 原型进一步固定:
 
 phase 只允许:`prepared`、`current_backed_up`、`staging_activated`、`rollback_required`、`committed`。日志使用临时文件 + 同目录 backup 原子替换;恢复时同时检查日志与 current/staging/backup 实际状态。未完成健康检查的 current 不视为可信:有旧版时恢复 backup,首次安装则撤销 current。
 
+### 2.6 下载任务元数据 download-task.json(本地)
+
+每个任务以稳定 `request_id` 为主键,元数据位于 `downloads/tasks/<request_id>.json`,字节文件位于 `downloads/files/<request_id>.part|.download`。本地路径只由客户端从 request_id 派生,不接受 URL 或 Content-Disposition 提供的文件名。
+
+```json
+{
+  "schema_version": 1,
+  "request_id": "download-json-parser-001",
+  "app_id": "json-parser",
+  "url": "https://download.example.com/json-parser.zip",
+  "status": "paused",
+  "attempt": 2,
+  "done": 1048576,
+  "total_known": true,
+  "total": 12345678,
+  "validator": {
+    "etag": "\"release-1.4.2\""
+  },
+  "error_code": "",
+  "created_at": "2026-07-16T00:00:00Z"
+}
+```
+
+规则:
+
+- Schema 为 `schemas/download-task.schema.json`;内部状态只允许 queued/downloading/paused/failed/completed。paused 对 UI 映射为 queued + DownloadPaused 事件,不增加第 13 个 AppStatus。
+- 默认最多 2 个 downloading;同一 request_id 幂等,身份/URL/size 不同则冲突;同一 app 同时只允许一个非 completed 任务。
+- 暂停保留 `.part` 和元数据;失败 retry 保留 `.part`;取消固定删除该 request_id 精确派生的 part/final/metadata,不使用递归删除。取消已线性化后,body close/sync 等非致命错误只记录日志,不能把取消反转成 failed 或跳过清理。
+- 续传只在存在 strong ETag 或合法 Last-Modified 时发送 Range + If-Range;无可靠 validator 时从 0 重下。请求固定 `Accept-Encoding: identity`,所有 redirect 重新校验 HTTPS。
+- `206` 必须严格匹配 Content-Range 起点、长度、total 与期望 size;已有 part 但服务端返回 `200` 时截断并创建新 attempt,不能 old+new 拼接。
+- known total 使用已验签 Catalog package.size 作为精确传输长度;unknown total 使用显式 `total_known: false` 并受 4 GiB 默认硬上限保护。
+- known total 的 `.part` 已达到精确 total 时,同进程 resume/retry 与重启恢复都直接 sync、核对身份并 finalize,不得再请求 `Range: bytes=<total>-`。
+- 完成顺序为 part sync/close → 核对实际写入文件身份 → rename `.download` → metadata completed → DownloadCompleted。rename 前后必须仍是同一普通文件;恢复时以普通文件实际长度对账,不信任 metadata.done。
+- 事件投递是 best-effort,失败不得反向把已完成/已取消的持久任务改成失败。队列必须把投递错误交给 `OnObserverError` 记录;application/UI 在启动或事件通道重连后必须用 `Queue.Tasks()` 对账持久状态,不能只依赖某一次终态事件。
+- `.download` 仍是**不可信隔离字节**。T-302 必须重新从已验签 Catalog 取得 app/version/arch/size/SHA-256/signature 并验证,通过后才可读取 app.json 或解压。
+
 ## 3. 许可证(服务端签发 → 本地离线验证)
 
 ```json
@@ -229,11 +265,12 @@ phase 只允许:`prepared`、`current_backed_up`、`staging_activated`、`rollba
 | --- | --- | --- | --- |
 | CatalogRefreshed | 清单验签并缓存成功 | catalog 摘要、generated_at | 列表刷新 |
 | CatalogRejected | 清单验签失败 | 原因码 | 提示 + 继续用缓存 |
-| DownloadStarted | 下载任务开始 | request_id, app_id | 状态 → downloading |
-| DownloadProgress | 进度更新 | request_id, app_id, done, total, speed | 进度条刷新 |
-| DownloadPaused | 用户暂停 | request_id, app_id | 状态 → queued(暂停态) |
-| DownloadCompleted | 下载并校验通过 | request_id, app_id | 状态 → verifying/extracting |
-| DownloadFailed | 失败(网络/哈希/磁盘) | request_id, app_id, error_code | 状态 → failed + 可重试 |
+| DownloadStarted | 一个下载 attempt 开始/因安全重下而重置 | request_id, app_id, attempt, done, total_known, total | 状态 → downloading |
+| DownloadProgress | 当前 attempt 进度更新 | request_id, app_id, attempt, done, total_known, total, speed | 进度条刷新;done 在同 attempt 内单调 |
+| DownloadPaused | 用户暂停且旧 worker 已完全退出 | request_id, app_id, attempt, done | 状态 → queued(暂停态) |
+| DownloadCompleted | 字节完整落盘,尚未通过 SHA/签名 | request_id, app_id, attempt, done, path | 状态 → verifying;T-302 接管信任校验 |
+| DownloadFailed | 传输/Range/存储失败 | request_id, app_id, attempt, done, error_code | 状态 → failed + 可重试 |
+| DownloadCanceled | 取消清理完成且旧 attempt 不再发事件 | request_id, app_id, attempt | 从任务视图移除并回到本地基础状态 |
 | InstallCompleted | 原子切换成功 + 健康检查通过 | app_id, version | 状态 → installed |
 | InstallRolledBack | 切换失败恢复 backup | app_id, error_code | 状态 → rollback 完成提示 |
 | AppStarted / AppExited | 进程启动/退出检测 | app_id, pid | 状态 → running / installed |