69 lines
4.3 KiB
Markdown
69 lines
4.3 KiB
Markdown
|
---
|
|||
|
|
id: T-202
|
|||
|
|
title: 本地安装状态识别
|
|||
|
|
phase: 2
|
|||
|
|
deps: [T-201, T-103]
|
|||
|
|
status: DONE
|
|||
|
|
created: 2026-07-16
|
|||
|
|
issue: null
|
|||
|
|
context_ref: 2e21c9f327bc56ab719fafee7ca5303f90747b4c
|
|||
|
|
claim_branch: null
|
|||
|
|
work_branch: agent/codex/T-202
|
|||
|
|
write_paths:
|
|||
|
|
- docs/tasks/T-202.md
|
|||
|
|
- core/domain/
|
|||
|
|
- core/storage/
|
|||
|
|
- core/catalog/
|
|||
|
|
- schemas/
|
|||
|
|
- docs/api.md
|
|||
|
|
- docs/04-architecture.md
|
|||
|
|
- docs/current-state.md
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 问题 / 背景
|
|||
|
|
|
|||
|
|
Catalog 已能给出可信远端版本和兼容性，但客户端还不能从 `apps/<id>/installed-app.json` 恢复实际安装版本，也没有统一的 SemVer 比较与 12 种用户状态推导。若 UI 自行拼接磁盘、版本和任务状态，状态优先级会漂移且容易在 Layout 中引入 IO。
|
|||
|
|
|
|||
|
|
## 方案
|
|||
|
|
|
|||
|
|
1. 在 `core/domain` 实现 SemVer 2.0.0 解析/比较，正确处理 prerelease，忽略 build metadata 的排序影响。
|
|||
|
|
2. 在 `core/storage` 定义 installed-app.json v1 模型和严格校验，使用临时文件 + 同目录 backup 原子替换，主文件缺失时可读取中断遗留 backup。
|
|||
|
|
3. 本地 Inspector 识别安装记录与 `install-transaction.json`/backup 是否存在，只返回快照，不推导 UI 状态。
|
|||
|
|
4. 在 domain 建立纯 `ResolveAppStatus`：按恢复事务、活跃操作、运行状态、兼容性、本地版本与 Catalog 版本推导已有 12 种 AppStatus。
|
|||
|
|
5. Catalog 版本字段校验复用 domain SemVer，避免协议解析与本地比较出现两套版本规则。
|
|||
|
|
6. 落地 `schemas/installed-app.schema.json`，同步协议、架构与当前状态文档。
|
|||
|
|
|
|||
|
|
## 验收要点
|
|||
|
|
|
|||
|
|
- installed-app.json 可严格读写；未知字段、ID 不匹配、非法版本/架构/channel/文件路径/哈希被拒绝。
|
|||
|
|
- 写入使用同目录临时文件 + backup 替换；主文件缺失时能读取中断遗留 backup。
|
|||
|
|
- 未完成安装事务能被识别为 `rollback_pending` 输入事实。
|
|||
|
|
- SemVer 覆盖 major/minor/patch、prerelease precedence、build metadata 和非法格式。
|
|||
|
|
- 表驱动测试逐一得到 12 个 AppStatus；Catalog 版本更高时为 update_available。
|
|||
|
|
- Go 1.20 core vet/test、完整双目标闸门和治理校验通过。
|
|||
|
|
|
|||
|
|
## 边界（不改什么）
|
|||
|
|
|
|||
|
|
- 不实现下载/安装任务持久化或进程检测；这些状态只消费后续用例提供的事实。
|
|||
|
|
- 不实现 Gio 列表或在 Layout 中扫描磁盘（T-203）。
|
|||
|
|
- 不修改 T-103 的切换/恢复策略；这里只读识别其持久事务文件。
|
|||
|
|
- 不引入第三方 SemVer 或存储依赖。
|
|||
|
|
|
|||
|
|
## 协作约束
|
|||
|
|
|
|||
|
|
未启用 Gitea；本任务在 `agent/codex/T-202` 分支串行执行。存储 IO 与状态推导必须分层，后续 UI 只能消费快照/状态结果。
|
|||
|
|
|
|||
|
|
## 执行记录
|
|||
|
|
|
|||
|
|
- 2026-07-16:在 `core/domain` 实现完整 SemVer 2.0.0 解析与 precedence 比较；支持任意长度数字、prerelease 排序，build metadata 不影响更新判断，非法前导零/标识符被拒绝。
|
|||
|
|
- 2026-07-16:Catalog 的 `min_box_version` 与 app `version` 校验改为复用 domain SemVer，消除远端解析与本地更新判断的双规则。
|
|||
|
|
- 2026-07-16:在 `core/storage` 建立 installed-app.json v1 模型、严格 reader/writer 与 Inspector；写入采用同目录临时文件 + backup 原子替换，主文件缺失时读取并重验 backup。
|
|||
|
|
- 2026-07-16:安装记录校验覆盖未知字段、路径 ID 不匹配、架构/channel、文件安全相对路径、Windows 大小写折叠重复路径、size 与 SHA-256；transaction 主文件或 backup 可被识别为恢复待处理事实。
|
|||
|
|
- 2026-07-16:增加纯 `ResolveAppStatus`，状态优先级为恢复事务 → 活跃操作 → 运行 → 不兼容 → 是否安装 → SemVer 更新；表驱动测试逐一覆盖全部 12 个 AppStatus。
|
|||
|
|
- 2026-07-16:新增 `schemas/installed-app.schema.json`，同步三份 Schema 的严格 SemVer pattern，并更新 `docs/api.md`、`docs/04-architecture.md`、`docs/current-state.md`。
|
|||
|
|
- 定向验证通过:`go -C core test -count=1 ./domain ./storage ./catalog`。
|
|||
|
|
- Schema 语法验证通过:`python -m json.tool` 解析 manifest/app/installed-app 三份 Schema。
|
|||
|
|
- 完整验证通过:`./scripts/verify_phase0.ps1`，包含 Go 1.20.14 core vet/test、治理/边界/版本检查及 modern/win7 双目标测试与构建。
|
|||
|
|
- 提交前检查通过:`git diff --check`。
|
|||
|
|
- 工作区中的未跟踪 `soft_quay.code-workspace` 与本任务无关，已保留且未纳入提交。
|