soft_quay/docs/tasks/T-202.md

id, title, phase, deps, status, created, issue, context_ref, claim_branch, work_branch, write_paths

id	title	phase	deps	status	created	issue	context_ref	claim_branch	work_branch	write_paths
T-202	本地安装状态识别	2	T-201 T-103	DONE	2026-07-16	null	2e21c9f327	null	agent/codex/T-202	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 与本任务无关，已保留且未纳入提交。