soft_quay/docs/tasks/T-204.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-204	软件详情与图标缓存	2	T-203	DONE	2026-07-16	null	db8d93e843	null	agent/codex/T-204	docs/tasks/T-204.md core/catalog/ core/application/ app-modern/ui/gio/ app-win7/ui/gio/ docs/api.md docs/routes.md docs/04-architecture.md docs/current-state.md

问题 / 背景

软件行已经可选择，但还没有详情视图，也没有可信图标的后台缓存链路。若 Gio Layout 自行读文件、解码或请求图标，会直接违反每帧无 IO 约束；若磁盘图标不复核 Catalog 内容哈希，损坏或替换的缓存也可能被展示。

方案

1. 在 core/catalog 建立 IconCache：以 sha256:<digest> + DPI 为键，按内存 → 磁盘 → 注入 Fetcher 顺序加载。
2. 远端图标必须满足大小上限、SHA-256 与可解码图片/尺寸上限后才能原子写入磁盘；磁盘命中同样复核哈希与图片头。
3. 磁盘文件按 digest + DPI 隔离；新进程在 Fetcher 离线时仍可读取已验证缓存。
4. CatalogListItem 补充 icon/homepage/tutorial 数据与 selected item 查询。
5. modern/win7 在选中软件时显示右侧详情面板，含关闭、版本、分类、简介、tags、状态、不可用原因和教程/主页信息。
6. UI 只提供 ApplyIcon(appID, image.Image) 接收后台已解码结果；Layout 仅绘制内存图像，未命中时显示字母占位。

验收要点

• 同一 digest+DPI 首次远端加载，随后内存命中；新 cache 实例断网时可从磁盘命中。
• 不同 DPI 使用不同磁盘键；哈希不符、超限、不可解码/超尺寸图标不写缓存。
• 损坏磁盘缓存不会被返回；有网络时可重新获取修复，离线时返回明确错误。
• 点击行后详情右栏可见且可关闭；列表/详情均能显示后台 ApplyIcon 的内存图像或稳定占位。
• 两个 Gio Layout 中无磁盘、网络、哈希或图片解码。
• Go 1.20 core vet/test、modern/win7 UI 测试与构建、完整闸门和治理校验通过。

边界（不改什么）

• 不决定图标 URL/变体的最终 Catalog 字段；Fetcher 由装配层按发布端协议注入。
• 不实现网络请求装配、图片缩放生成、LRU/容量淘汰或 CDN 缓存策略。
• 不实现真实下载/安装/启动动作和许可证详情；详情只展示当前可用事实与后续操作语义。
• 不在 UI 中调用 image.Decode、os、http 或 sha256。

协作约束

未启用 Gitea；本任务在 agent/codex/T-204 分支串行执行。延续 ui-ux-pro-max 的扁平高对比、44dp、清晰返回/关闭、上下文保留和无昂贵 Layout 工作约束。

执行记录

• 2026-07-16:在 core/catalog 建立 IconCache；键为规范化 SHA-256 digest + DPI，加载顺序为 memory → verified disk → injected fetcher，返回 source 与非致命磁盘写 warning。
• 2026-07-16:远端和磁盘统一复核内容哈希、图片完整解码、默认 2 MiB 与 2048×2048 上限；只把验证成功字节用同目录临时文件原子写入，symlink/非普通缓存项拒绝。
• 2026-07-16:测试覆盖首次 remote、随后 memory、新实例断网 disk、96/144 DPI 分盘、哈希不符、非法图片、字节/尺寸超限、坏磁盘在线修复与坏磁盘离线明确失败。
• 2026-07-16:CatalogListItem 增加 IconRef/Homepage/Tutorial 与 SelectedItem 查询；筛选/滚动上下文不因打开或关闭详情而重置。
• 2026-07-16:modern/win7 均实现右侧详情、明确“关闭”文字按钮、版本/分类/简介/tags/状态/不可用原因/教程/主页展示；未接入的安装/启动/授权没有伪装为可执行动作。
• 2026-07-16:两个 Gio 适配增加 ApplyIcon(appID, image.Image)，在调用时预建 paint.ImageOp；列表和详情每帧只复用内存绘制操作，未命中使用非 emoji 字母占位。
• 2026-07-16:按 ui-ux-pro-max 交付复查确认关闭按钮有可访问文字名、返回保持上下文，详情延续高对比扁平/44dp 交互体系。
• 2026-07-16:同步 docs/api.md、docs/routes.md、docs/04-architecture.md 与 docs/current-state.md；图标下载位置/分辨率映射仍明确留给发布端协议，客户端不猜 URL。
• 定向验证通过:go -C core test -count=1 ./catalog ./application、modern/win7 go test -count=1 ./ui/gio。
• Layout IO/解码扫描通过:rg 检查两个 ui/gio 下无 image.Decode、os、net/http、文件读写、filepath 或 sha256 调用。
• 完整验证通过:./scripts/verify_phase0.ps1，包含 Go 1.20.14 core vet/test、治理/边界/版本检查及 modern/win7 双目标测试与构建。
• 提交前检查通过:git diff --check。
• 工作区中的未跟踪 soft_quay.code-workspace 与本任务无关，已保留且未纳入提交。