feat(update-center): add update list icons

docs/superpowers/specs/2026-04-10-update-center-icons-design.md

@@ -0,0 +1,214 @@
+# 更新中心列表图标设计
+
+## 背景
+
+当前 Electron 更新中心已经可以展示更新项、来源、迁移标记、进度和日志，但更新列表仍然只有文字信息，没有应用图标。对于 APM 包、传统 deb 包和迁移项，纯文字列表会降低识别效率，尤其在批量更新和搜索场景下不够直观。
+
+仓库现状里已经存在多套可复用的图标来源逻辑：
+
+1. 主商店卡片通过远程商店 URL 拼接 `icon.png`。
+2. 已安装应用列表支持本地图标和远程 URL 双来源。
+3. 旧 Qt 更新器会为 APM 更新项解析 desktop 与 entries/icons，并在无本地图标时继续使用其他数据源。
+
+目标是在更新中心列表中加入应用图标，同时保持最小改动、兼容当前后端结构，并遵循“本地解析优先，其次远程 URL，最后占位图标”的策略。
+
+## 目标
+
+1. 在更新中心列表中为每个更新项展示应用图标。
+2. 图标来源优先级为：本地解析 > 远程 URL > 前端占位图标。
+3. 前后端仅增加一个最小公共字段，不引入复杂的图标对象结构。
+4. 图标缺失或加载失败时，界面仍然保持稳定、整齐、不闪烁。
+
+## 非目标
+
+1. 不为图标来源新增额外网络探测请求。
+2. 不在本次设计中重构应用详情页、已安装列表或主商店卡片的图标逻辑。
+3. 不在 UI 中展示“图标来源”说明文字。
+
+## 方案概览
+
+采用“主进程解析来源、渲染层只展示”的方案：
+
+1. 更新中心主进程在加载更新项时解析图标来源，并将结果写入更新项的 `icon` 字段。
+2. 渲染层更新列表只消费 `item.icon`，不参与解析来源。
+3. 前端负责单次图片加载失败回退到占位图标。
+
+## 数据结构变化
+
+### 主进程
+
+修改：`electron/main/backend/update-center/types.ts`
+
+为 `UpdateCenterItem` 增加：
+
+```ts
+icon?: string;
+```
+
+### 渲染层
+
+修改：`src/global/typedefinition.ts`
+
+为 `UpdateCenterItem` 增加：
+
+```ts
+icon?: string;
+```
+
+### Service 映射
+
+修改：`electron/main/backend/update-center/service.ts`
+
+在主进程 snapshot -> renderer snapshot 的映射中透传 `icon` 字段。
+
+## 图标来源策略
+
+### 优先级
+
+每个更新项统一按以下顺序取图标：
+
+1. 本地图标路径
+2. 远程商店图标 URL
+3. 前端占位图标
+
+### 1. 本地图标路径
+
+#### 传统 deb / Spark 更新项
+
+优先复用仓库中已有的 desktop 文件扫描与 `Icon=` 解析思路，来源参考：
+
+- `electron/main/backend/install-manager.ts`
+
+解析策略：
+
+1. 从已安装包对应的 desktop 文件中读取 `Icon=`。
+2. 如果解析结果为绝对路径，直接返回。
+3. 如果解析结果为图标名，则尝试根据系统图标路径补全。
+4. 若无法得到有效路径，则继续下一层来源。
+
+#### APM 更新项
+
+优先复用旧 Qt 更新器已存在的 APM 图标解析逻辑，来源参考：
+
+- `spark-update-tool/src/aptssupdater.cpp`
+
+解析策略：
+
+1. 查找 APM 包的 `entries/applications/*.desktop`。
+2. 从 desktop 的 `Icon=` 字段中解析图标。
+3. 若 `Icon=` 为绝对路径，直接返回。
+4. 若 `Icon=` 为图标名，则尝试拼接 APM 包内 `entries/icons/...` 路径。
+5. 若仍无结果，则继续下一层来源。
+
+### 2. 远程商店图标 URL
+
+如果本地图标解析失败，则为更新项生成远程图标 URL。
+
+实现原则：
+
+1. 不主动探测 URL 是否可用。
+2. 仅按现有商店规则拼接 URL，并交给浏览器加载。
+3. 浏览器加载失败后由前端回退占位图标。
+
+对 Spark/传统 deb：
+
+1. 使用当前商店已有的远程图标拼接规则。
+2. 若更新项可以推断出对应 category 和 arch，则拼接：
+   `${APM_STORE_BASE_URL}/${arch}/${category}/${pkgname}/icon.png`
+
+对 APM：
+
+1. 若仓库中已有 APM 对应商店资源约定，则使用同样的 `icon.png` 规则。
+2. 若当前数据无法可靠推断 category，则允许直接跳过远程 URL，进入前端占位图标。
+
+### 3. 占位图标
+
+如果主进程未能提供 `icon`，或者前端加载失败，则使用统一占位图标。
+
+占位规则：
+
+1. 图标尺寸与正常图标一致。
+2. 使用仓库现有品牌资源或统一默认应用图标。
+3. 不因失败状态改变列表布局高度或间距。
+
+## 模块边界
+
+新增：
+
+- `electron/main/backend/update-center/icons.ts`
+
+职责：
+
+1. `resolveUpdateItemIcon()`
+2. `resolveApmIcon()`
+3. `resolveDesktopIcon()`
+4. `buildRemoteFallbackIconUrl()`
+
+该模块只负责“根据更新项得到一个 `icon?: string`”，不参与更新队列、安装、刷新、忽略等逻辑。
+
+## 数据流
+
+### 主进程加载更新项
+
+1. 查询并合并更新项。
+2. 对每个更新项执行图标解析。
+3. 将解析到的 `icon` 字段写入 `UpdateCenterItem`。
+4. 由 `service.ts` 将该字段透传到渲染层 snapshot。
+
+### 渲染层展示
+
+1. `UpdateCenterItem.vue` 读取 `item.icon`。
+2. 如果 `item.icon` 为本地绝对路径，则转成 `file://` URL。
+3. 如果 `item.icon` 为远程 URL，则直接作为图片地址使用。
+4. 若图片加载失败，则切换为占位图标，并记住失败状态避免重复尝试。
+
+## UI 设计
+
+### 列表项布局
+
+在更新列表中新增一个固定图标位：
+
+1. 位置：复选框后、应用信息前。
+2. 尺寸：`40x40`。
+3. 样式：圆角矩形，视觉与商店应用卡片图标一致。
+4. 图标位固定占位，避免有图和无图的项出现布局跳动。
+
+### 失败回退
+
+前端仅做一次失败回退：
+
+1. 优先渲染 `item.icon`。
+2. 触发 `@error` 后切换为占位图。
+3. 记录该项失败状态，避免反复向无效地址重新请求。
+
+## 测试方案
+
+### 主进程测试
+
+新增或扩展测试覆盖：
+
+1. 本地图标优先于远程 URL。
+2. APM 更新项可解析包内 desktop/icons。
+3. 传统 deb 更新项可解析 desktop `Icon=`。
+4. 无本地图标时能生成远程 URL 或返回空值。
+
+### 组件测试
+
+扩展 `UpdateCenterItem.vue` 组件测试：
+
+1. 有 `item.icon` 时渲染图片。
+2. 图片加载失败时回退到占位图。
+3. 图标存在时不影响当前状态标签、迁移标签、进度条显示。
+
+## 风险与约束
+
+1. 更新项当前不一定总能推断出 category，因此远程 URL 兜底对部分项可能不可用；这是可接受的，因为前端还有占位图兜底。
+2. 本地图标解析涉及多个来源路径，必须限制在读取路径和拼接路径，不做额外昂贵的同步探测。
+3. APM 图标路径依赖当前系统安装结构，若个别包结构不标准，应直接退回远程或占位图，而不是阻断更新列表。
+
+## 决策总结
+
+1. 更新中心增加单字段 `icon?: string`，不引入复杂图标对象。
+2. 主进程解析图标来源，渲染层只负责展示和失败回退。
+3. 图标来源顺序固定为：本地解析 > 远程 URL > 占位图。
+4. UI 仅新增稳定图标位，不改变现有更新列表信息层级。