mirror of
https://gitee.com/spark-store-project/spark-store
synced 2026-04-26 09:20:18 +08:00
feat(update-center): add update list icons
This commit is contained in:
674
docs/superpowers/plans/2026-04-10-update-center-icons.md
Normal file
674
docs/superpowers/plans/2026-04-10-update-center-icons.md
Normal file
@@ -0,0 +1,674 @@
|
||||
# Update Center Icons Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Add icons to the Electron update-center list using local icon resolution first, remote URL fallback second, and a frontend placeholder last.
|
||||
|
||||
**Architecture:** Add a focused `icons.ts` helper in the update-center backend to resolve icon paths/URLs while loading update items, then pass the single `icon` field through the service snapshot into the renderer. Keep the Vue side minimal by rendering a fixed icon slot in `UpdateCenterItem.vue` and falling back to a placeholder icon on `img` load failure.
|
||||
|
||||
**Tech Stack:** Electron main process, Node.js `fs`/`path`, Vue 3 `<script setup>`, Tailwind CSS 4, Vitest, Testing Library Vue, TypeScript strict mode.
|
||||
|
||||
---
|
||||
|
||||
## File Map
|
||||
|
||||
- Create: `electron/main/backend/update-center/icons.ts` — resolves update-item icons from local desktop/APM metadata and remote fallback URLs.
|
||||
- Modify: `electron/main/backend/update-center/types.ts` — add backend `icon?: string` field.
|
||||
- Modify: `electron/main/backend/update-center/index.ts` — enrich loaded update items with resolved icons.
|
||||
- Modify: `electron/main/backend/update-center/service.ts` — expose `icon` in renderer-facing snapshots.
|
||||
- Modify: `src/global/typedefinition.ts` — add renderer-facing `icon?: string` field.
|
||||
- Modify: `src/components/update-center/UpdateCenterItem.vue` — render icon slot and placeholder fallback.
|
||||
- Test: `src/__tests__/unit/update-center/icons.test.ts` — backend icon-resolution tests.
|
||||
- Modify: `src/__tests__/unit/update-center/load-items.test.ts` — verify loaded update items include icon data when available.
|
||||
- Create: `src/__tests__/unit/update-center/UpdateCenterItem.test.ts` — component-level icon rendering and fallback tests.
|
||||
|
||||
### Task 1: Add Backend Icon Resolution Helpers
|
||||
|
||||
**Files:**
|
||||
|
||||
- Create: `electron/main/backend/update-center/icons.ts`
|
||||
- Modify: `electron/main/backend/update-center/types.ts`
|
||||
- Test: `src/__tests__/unit/update-center/icons.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```ts
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import {
|
||||
buildRemoteFallbackIconUrl,
|
||||
resolveApmIcon,
|
||||
resolveDesktopIcon,
|
||||
} from "../../../../electron/main/backend/update-center/icons";
|
||||
|
||||
describe("update-center icons", () => {
|
||||
beforeEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
it("prefers local desktop icon paths for aptss items", () => {
|
||||
const existsSync = vi.spyOn(require("node:fs"), "existsSync");
|
||||
const readdirSync = vi.spyOn(require("node:fs"), "readdirSync");
|
||||
const readFileSync = vi.spyOn(require("node:fs"), "readFileSync");
|
||||
|
||||
existsSync.mockImplementation((target) =>
|
||||
String(target).includes("/usr/share/applications"),
|
||||
);
|
||||
readdirSync.mockReturnValue(["spark-weather.desktop"]);
|
||||
readFileSync.mockReturnValue(
|
||||
"Name=Spark Weather\nIcon=/usr/share/icons/hicolor/128x128/apps/spark-weather.png\n",
|
||||
);
|
||||
|
||||
expect(resolveDesktopIcon("spark-weather")).toBe(
|
||||
"/usr/share/icons/hicolor/128x128/apps/spark-weather.png",
|
||||
);
|
||||
});
|
||||
|
||||
it("resolves APM icon names from entries/icons when desktop icon is not absolute", () => {
|
||||
const existsSync = vi.spyOn(require("node:fs"), "existsSync");
|
||||
const readdirSync = vi.spyOn(require("node:fs"), "readdirSync");
|
||||
const readFileSync = vi.spyOn(require("node:fs"), "readFileSync");
|
||||
|
||||
existsSync.mockImplementation(
|
||||
(target) =>
|
||||
String(target).includes(
|
||||
"/var/lib/apm/apm/files/ace-env/var/lib/apm/com.qihoo.360zip/entries/icons/hicolor/48x48/apps/360zip.png",
|
||||
) ||
|
||||
String(target).includes(
|
||||
"/var/lib/apm/apm/files/ace-env/var/lib/apm/com.qihoo.360zip/entries/applications",
|
||||
),
|
||||
);
|
||||
readdirSync.mockReturnValue(["360zip.desktop"]);
|
||||
readFileSync.mockReturnValue("Name=360压缩\nIcon=360zip\n");
|
||||
|
||||
expect(resolveApmIcon("com.qihoo.360zip")).toBe(
|
||||
"/var/lib/apm/apm/files/ace-env/var/lib/apm/com.qihoo.360zip/entries/icons/hicolor/48x48/apps/360zip.png",
|
||||
);
|
||||
});
|
||||
|
||||
it("builds a remote fallback URL when category and arch are available", () => {
|
||||
expect(
|
||||
buildRemoteFallbackIconUrl({
|
||||
pkgname: "spark-weather",
|
||||
source: "aptss",
|
||||
arch: "amd64",
|
||||
category: "network",
|
||||
}),
|
||||
).toBe(
|
||||
"https://erotica.spark-app.store/amd64-store/network/spark-weather/icon.png",
|
||||
);
|
||||
});
|
||||
|
||||
it("returns empty string when neither local nor remote icon can be determined", () => {
|
||||
expect(
|
||||
buildRemoteFallbackIconUrl({
|
||||
pkgname: "spark-weather",
|
||||
source: "aptss",
|
||||
arch: "amd64",
|
||||
}),
|
||||
).toBe("");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `npm run test -- --run src/__tests__/unit/update-center/icons.test.ts`
|
||||
|
||||
Expected: FAIL with `Cannot find module '../../../../electron/main/backend/update-center/icons'`.
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
```ts
|
||||
// electron/main/backend/update-center/types.ts
|
||||
export interface UpdateCenterItem {
|
||||
pkgname: string;
|
||||
source: UpdateSource;
|
||||
currentVersion: string;
|
||||
nextVersion: string;
|
||||
icon?: string;
|
||||
ignored?: boolean;
|
||||
downloadUrl?: string;
|
||||
fileName?: string;
|
||||
size?: number;
|
||||
sha512?: string;
|
||||
isMigration?: boolean;
|
||||
migrationSource?: UpdateSource;
|
||||
migrationTarget?: UpdateSource;
|
||||
aptssVersion?: string;
|
||||
}
|
||||
```
|
||||
|
||||
```ts
|
||||
// electron/main/backend/update-center/icons.ts
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
|
||||
const APM_STORE_BASE_URL = "https://erotica.spark-app.store";
|
||||
const APM_BASE_PATH = "/var/lib/apm/apm/files/ace-env/var/lib/apm";
|
||||
|
||||
export const resolveDesktopIcon = (pkgname: string): string => {
|
||||
const desktopRoots = [
|
||||
"/usr/share/applications",
|
||||
`/opt/apps/${pkgname}/entries/applications`,
|
||||
];
|
||||
|
||||
for (const root of desktopRoots) {
|
||||
if (!fs.existsSync(root)) continue;
|
||||
for (const file of fs.readdirSync(root)) {
|
||||
if (!file.endsWith(".desktop")) continue;
|
||||
const content = fs.readFileSync(path.join(root, file), "utf8");
|
||||
const match = content.match(/^Icon=(.+)$/m);
|
||||
if (!match) continue;
|
||||
const iconValue = match[1].trim();
|
||||
if (iconValue.startsWith("/")) return iconValue;
|
||||
}
|
||||
}
|
||||
|
||||
return "";
|
||||
};
|
||||
|
||||
export const resolveApmIcon = (pkgname: string): string => {
|
||||
const entriesPath = path.join(
|
||||
APM_BASE_PATH,
|
||||
pkgname,
|
||||
"entries",
|
||||
"applications",
|
||||
);
|
||||
if (!fs.existsSync(entriesPath)) return "";
|
||||
|
||||
for (const file of fs.readdirSync(entriesPath)) {
|
||||
if (!file.endsWith(".desktop")) continue;
|
||||
const content = fs.readFileSync(path.join(entriesPath, file), "utf8");
|
||||
const match = content.match(/^Icon=(.+)$/m);
|
||||
if (!match) continue;
|
||||
const iconValue = match[1].trim();
|
||||
if (iconValue.startsWith("/")) return iconValue;
|
||||
|
||||
const iconPath = path.join(
|
||||
APM_BASE_PATH,
|
||||
pkgname,
|
||||
"entries",
|
||||
"icons",
|
||||
"hicolor",
|
||||
"48x48",
|
||||
"apps",
|
||||
`${iconValue}.png`,
|
||||
);
|
||||
if (fs.existsSync(iconPath)) return iconPath;
|
||||
}
|
||||
|
||||
return "";
|
||||
};
|
||||
|
||||
export const buildRemoteFallbackIconUrl = (input: {
|
||||
pkgname: string;
|
||||
source: "aptss" | "apm";
|
||||
arch: string;
|
||||
category?: string;
|
||||
}): string => {
|
||||
if (!input.category) return "";
|
||||
const finalArch =
|
||||
input.source === "aptss" ? `${input.arch}-store` : `${input.arch}-apm`;
|
||||
return `${APM_STORE_BASE_URL}/${finalArch}/${input.category}/${input.pkgname}/icon.png`;
|
||||
};
|
||||
|
||||
export const resolveUpdateItemIcon = (item: {
|
||||
pkgname: string;
|
||||
source: "aptss" | "apm";
|
||||
arch?: string;
|
||||
category?: string;
|
||||
}): string => {
|
||||
const localIcon =
|
||||
item.source === "apm"
|
||||
? resolveApmIcon(item.pkgname)
|
||||
: resolveDesktopIcon(item.pkgname);
|
||||
|
||||
if (localIcon) {
|
||||
return localIcon;
|
||||
}
|
||||
|
||||
if (!item.arch) {
|
||||
return "";
|
||||
}
|
||||
|
||||
return buildRemoteFallbackIconUrl({
|
||||
pkgname: item.pkgname,
|
||||
source: item.source,
|
||||
arch: item.arch,
|
||||
category: item.category,
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `npm run test -- --run src/__tests__/unit/update-center/icons.test.ts`
|
||||
|
||||
Expected: PASS with 4 tests passed.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add electron/main/backend/update-center/types.ts electron/main/backend/update-center/icons.ts src/__tests__/unit/update-center/icons.test.ts
|
||||
git commit -m "feat(update-center): add icon resolution helpers"
|
||||
```
|
||||
|
||||
### Task 2: Enrich Loaded Update Items with Icons
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `electron/main/backend/update-center/index.ts`
|
||||
- Modify: `electron/main/backend/update-center/service.ts`
|
||||
- Modify: `src/global/typedefinition.ts`
|
||||
- Modify: `src/__tests__/unit/update-center/load-items.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```ts
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
vi.mock("../../../../electron/main/backend/update-center/icons", () => ({
|
||||
resolveUpdateItemIcon: vi.fn((item) =>
|
||||
item.pkgname === "spark-weather"
|
||||
? "/usr/share/icons/hicolor/128x128/apps/spark-weather.png"
|
||||
: "",
|
||||
),
|
||||
}));
|
||||
|
||||
import { loadUpdateCenterItems } from "../../../../electron/main/backend/update-center";
|
||||
|
||||
describe("update-center load items", () => {
|
||||
it("adds icon data to loaded update items", async () => {
|
||||
const result = await loadUpdateCenterItems(async (command, args) => {
|
||||
const key = `${command} ${args.join(" ")}`;
|
||||
if (key.includes("list --upgradable")) {
|
||||
return {
|
||||
code: 0,
|
||||
stdout: "spark-weather/stable 2.0.0 amd64 [upgradable from: 1.0.0]",
|
||||
stderr: "",
|
||||
};
|
||||
}
|
||||
|
||||
if (key.includes("dpkg-query")) {
|
||||
return {
|
||||
code: 0,
|
||||
stdout: "spark-weather\tinstall ok installed\n",
|
||||
stderr: "",
|
||||
};
|
||||
}
|
||||
|
||||
return { code: 0, stdout: "", stderr: "" };
|
||||
});
|
||||
|
||||
expect(result.items).toContainEqual(
|
||||
expect.objectContaining({
|
||||
pkgname: "spark-weather",
|
||||
icon: "/usr/share/icons/hicolor/128x128/apps/spark-weather.png",
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `npm run test -- --run src/__tests__/unit/update-center/load-items.test.ts`
|
||||
|
||||
Expected: FAIL because loaded items do not yet include `icon`.
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
```ts
|
||||
// electron/main/backend/update-center/index.ts
|
||||
import { resolveUpdateItemIcon } from "./icons";
|
||||
|
||||
const withResolvedIcons = (items: UpdateCenterItem[]): UpdateCenterItem[] => {
|
||||
return items.map((item) => ({
|
||||
...item,
|
||||
icon: resolveUpdateItemIcon(item),
|
||||
}));
|
||||
};
|
||||
|
||||
export const loadUpdateCenterItems = async (
|
||||
runCommand: UpdateCenterCommandRunner = runCommandCapture,
|
||||
): Promise<UpdateCenterLoadItemsResult> => {
|
||||
const [aptssResult, apmResult, aptssInstalledResult, apmInstalledResult] =
|
||||
await Promise.all([
|
||||
runCommand(
|
||||
APTSS_LIST_UPGRADABLE_COMMAND.command,
|
||||
APTSS_LIST_UPGRADABLE_COMMAND.args,
|
||||
),
|
||||
runCommand("apm", ["list", "--upgradable"]),
|
||||
runCommand(
|
||||
DPKG_QUERY_INSTALLED_COMMAND.command,
|
||||
DPKG_QUERY_INSTALLED_COMMAND.args,
|
||||
),
|
||||
runCommand("apm", ["list", "--installed"]),
|
||||
]);
|
||||
|
||||
const warnings = [
|
||||
getCommandError("aptss upgradable query", aptssResult),
|
||||
getCommandError("apm upgradable query", apmResult),
|
||||
getCommandError("dpkg installed query", aptssInstalledResult),
|
||||
getCommandError("apm installed query", apmInstalledResult),
|
||||
].filter((message): message is string => message !== null);
|
||||
|
||||
const aptssItems =
|
||||
aptssResult.code === 0
|
||||
? parseAptssUpgradableOutput(aptssResult.stdout)
|
||||
: [];
|
||||
const apmItems =
|
||||
apmResult.code === 0 ? parseApmUpgradableOutput(apmResult.stdout) : [];
|
||||
|
||||
if (aptssResult.code !== 0 && apmResult.code !== 0) {
|
||||
throw new Error(warnings.join("; "));
|
||||
}
|
||||
|
||||
const installedSources = buildInstalledSourceMap(
|
||||
aptssInstalledResult.code === 0 ? aptssInstalledResult.stdout : "",
|
||||
apmInstalledResult.code === 0 ? apmInstalledResult.stdout : "",
|
||||
);
|
||||
|
||||
const enrichedApmItems = await enrichApmItems(apmItems, runCommand);
|
||||
|
||||
return {
|
||||
items: withResolvedIcons(
|
||||
mergeUpdateSources(aptssItems, enrichedApmItems.items, installedSources),
|
||||
),
|
||||
warnings: [...warnings, ...enrichedApmItems.warnings],
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
```ts
|
||||
// electron/main/backend/update-center/service.ts
|
||||
const toState = (
|
||||
snapshot: UpdateCenterQueueSnapshot,
|
||||
): UpdateCenterServiceState => ({
|
||||
items: snapshot.items.map((item) => ({
|
||||
taskKey: getTaskKey(item),
|
||||
packageName: item.pkgname,
|
||||
displayName: item.pkgname,
|
||||
currentVersion: item.currentVersion,
|
||||
newVersion: item.nextVersion,
|
||||
source: item.source,
|
||||
icon: item.icon,
|
||||
ignored: item.ignored,
|
||||
downloadUrl: item.downloadUrl,
|
||||
fileName: item.fileName,
|
||||
size: item.size,
|
||||
sha512: item.sha512,
|
||||
isMigration: item.isMigration,
|
||||
migrationSource: item.migrationSource,
|
||||
migrationTarget: item.migrationTarget,
|
||||
aptssVersion: item.aptssVersion,
|
||||
})),
|
||||
tasks: snapshot.tasks.map((task) => ({
|
||||
taskKey: getTaskKey(task.item),
|
||||
packageName: task.pkgname,
|
||||
source: task.item.source,
|
||||
status: task.status,
|
||||
progress: task.progress,
|
||||
logs: task.logs.map((log) => ({ ...log })),
|
||||
errorMessage: task.error ?? "",
|
||||
})),
|
||||
warnings: [...snapshot.warnings],
|
||||
hasRunningTasks: snapshot.hasRunningTasks,
|
||||
});
|
||||
```
|
||||
|
||||
```ts
|
||||
// src/global/typedefinition.ts
|
||||
export interface UpdateCenterItem {
|
||||
taskKey: string;
|
||||
packageName: string;
|
||||
displayName: string;
|
||||
currentVersion: string;
|
||||
newVersion: string;
|
||||
source: UpdateSource;
|
||||
icon?: string;
|
||||
ignored?: boolean;
|
||||
downloadUrl?: string;
|
||||
fileName?: string;
|
||||
size?: number;
|
||||
sha512?: string;
|
||||
isMigration?: boolean;
|
||||
migrationSource?: UpdateSource;
|
||||
migrationTarget?: UpdateSource;
|
||||
aptssVersion?: string;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `npm run test -- --run src/__tests__/unit/update-center/load-items.test.ts`
|
||||
|
||||
Expected: PASS with icon assertions included.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add electron/main/backend/update-center/index.ts electron/main/backend/update-center/service.ts src/global/typedefinition.ts src/__tests__/unit/update-center/load-items.test.ts
|
||||
git commit -m "feat(update-center): pass resolved icons to renderer"
|
||||
```
|
||||
|
||||
### Task 3: Render Update-List Icons with Placeholder Fallback
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `src/components/update-center/UpdateCenterItem.vue`
|
||||
- Create: `src/__tests__/unit/update-center/UpdateCenterItem.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
```ts
|
||||
import { fireEvent, render, screen } from "@testing-library/vue";
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import UpdateCenterItem from "@/components/update-center/UpdateCenterItem.vue";
|
||||
|
||||
const item = {
|
||||
taskKey: "aptss:spark-weather",
|
||||
packageName: "spark-weather",
|
||||
displayName: "Spark Weather",
|
||||
currentVersion: "1.0.0",
|
||||
newVersion: "2.0.0",
|
||||
source: "aptss" as const,
|
||||
icon: "/usr/share/icons/hicolor/128x128/apps/spark-weather.png",
|
||||
};
|
||||
|
||||
describe("UpdateCenterItem", () => {
|
||||
it("renders an icon image when item.icon exists", () => {
|
||||
render(UpdateCenterItem, {
|
||||
props: { item, selected: false },
|
||||
});
|
||||
|
||||
const image = screen.getByRole("img", { name: "Spark Weather 图标" });
|
||||
expect(image.getAttribute("src")).toBe(
|
||||
"file:///usr/share/icons/hicolor/128x128/apps/spark-weather.png",
|
||||
);
|
||||
});
|
||||
|
||||
it("falls back to a placeholder icon when the image fails", async () => {
|
||||
render(UpdateCenterItem, {
|
||||
props: { item, selected: false },
|
||||
});
|
||||
|
||||
const image = screen.getByRole("img", { name: "Spark Weather 图标" });
|
||||
await fireEvent.error(image);
|
||||
|
||||
expect(screen.getByTestId("update-center-icon-fallback")).toBeTruthy();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `npm run test -- --run src/__tests__/unit/update-center/UpdateCenterItem.test.ts`
|
||||
|
||||
Expected: FAIL because `UpdateCenterItem.vue` does not render icon markup yet.
|
||||
|
||||
- [ ] **Step 3: Write minimal implementation**
|
||||
|
||||
```vue
|
||||
<!-- src/components/update-center/UpdateCenterItem.vue -->
|
||||
<template>
|
||||
<label
|
||||
class="flex flex-col gap-4 rounded-2xl border border-slate-200/70 bg-white/90 p-4 shadow-sm dark:border-slate-800/70 dark:bg-slate-900/70"
|
||||
>
|
||||
<div class="flex items-start gap-3">
|
||||
<input
|
||||
type="checkbox"
|
||||
class="mt-1 h-4 w-4 rounded border-slate-300 accent-brand focus:ring-brand"
|
||||
:checked="selected"
|
||||
:disabled="item.ignored === true"
|
||||
@change="$emit('toggle-selection')"
|
||||
/>
|
||||
<div
|
||||
class="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl bg-slate-100 dark:bg-slate-800"
|
||||
>
|
||||
<img
|
||||
v-if="resolvedIcon && !iconFailed"
|
||||
:src="resolvedIcon"
|
||||
:alt="`${item.displayName} 图标`"
|
||||
class="h-8 w-8 object-contain"
|
||||
@error="iconFailed = true"
|
||||
/>
|
||||
<i
|
||||
v-else
|
||||
data-testid="update-center-icon-fallback"
|
||||
class="fas fa-cube text-lg text-slate-400"
|
||||
></i>
|
||||
</div>
|
||||
<div class="min-w-0 flex-1">
|
||||
<div class="flex flex-wrap items-center gap-2">
|
||||
<p class="font-semibold text-slate-900 dark:text-white">
|
||||
{{ item.displayName }}
|
||||
</p>
|
||||
<span
|
||||
class="rounded-full bg-slate-100 px-2.5 py-1 text-xs font-semibold text-slate-600 dark:bg-slate-800 dark:text-slate-200"
|
||||
>
|
||||
{{ sourceLabel }}
|
||||
</span>
|
||||
<span
|
||||
v-if="item.isMigration"
|
||||
class="rounded-full bg-brand/10 px-2.5 py-1 text-xs font-semibold text-brand"
|
||||
>
|
||||
将迁移到 APM
|
||||
</span>
|
||||
<span
|
||||
v-if="item.ignored === true"
|
||||
class="rounded-full bg-slate-200 px-2.5 py-1 text-xs font-semibold text-slate-500 dark:bg-slate-800 dark:text-slate-300"
|
||||
>
|
||||
已忽略
|
||||
</span>
|
||||
</div>
|
||||
<p class="mt-1 text-sm text-slate-500 dark:text-slate-400">
|
||||
{{ item.packageName }} · 当前 {{ item.currentVersion }} · 更新至
|
||||
{{ item.newVersion }}
|
||||
</p>
|
||||
<p
|
||||
v-if="item.ignored === true"
|
||||
class="mt-2 text-xs font-medium text-slate-500 dark:text-slate-400"
|
||||
>
|
||||
已忽略的更新不会加入本次任务。
|
||||
</p>
|
||||
</div>
|
||||
<div
|
||||
v-if="task"
|
||||
class="text-right text-sm font-semibold text-slate-600 dark:text-slate-300"
|
||||
>
|
||||
<p>{{ statusLabel }}</p>
|
||||
<p v-if="showProgress" class="mt-1">{{ progressText }}</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div v-if="showProgress" class="space-y-2">
|
||||
<div
|
||||
class="h-2 overflow-hidden rounded-full bg-slate-200 dark:bg-slate-800"
|
||||
>
|
||||
<div
|
||||
class="h-full rounded-full bg-gradient-to-r from-brand to-brand-dark"
|
||||
:style="progressStyle"
|
||||
></div>
|
||||
</div>
|
||||
</div>
|
||||
</label>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { computed, ref } from "vue";
|
||||
|
||||
import type {
|
||||
UpdateCenterItem,
|
||||
UpdateCenterTaskState,
|
||||
} from "@/global/typedefinition";
|
||||
|
||||
const props = defineProps<{
|
||||
item: UpdateCenterItem;
|
||||
task?: UpdateCenterTaskState;
|
||||
selected: boolean;
|
||||
}>();
|
||||
|
||||
const iconFailed = ref(false);
|
||||
|
||||
const resolvedIcon = computed(() => {
|
||||
if (!props.item.icon) return "";
|
||||
return props.item.icon.startsWith("/")
|
||||
? `file://${props.item.icon}`
|
||||
: props.item.icon;
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `npm run test -- --run src/__tests__/unit/update-center/UpdateCenterItem.test.ts`
|
||||
|
||||
Expected: PASS with 2 tests passed.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/components/update-center/UpdateCenterItem.vue src/__tests__/unit/update-center/UpdateCenterItem.test.ts
|
||||
git commit -m "feat(update-center): render update item icons"
|
||||
```
|
||||
|
||||
### Task 4: Verify the Icon Feature End-to-End
|
||||
|
||||
**Files:**
|
||||
|
||||
- Modify: `electron/main/backend/update-center/icons.ts`
|
||||
- Modify: `electron/main/backend/update-center/index.ts`
|
||||
- Modify: `electron/main/backend/update-center/service.ts`
|
||||
- Modify: `src/global/typedefinition.ts`
|
||||
- Modify: `src/components/update-center/UpdateCenterItem.vue`
|
||||
- Modify: `src/__tests__/unit/update-center/icons.test.ts`
|
||||
- Modify: `src/__tests__/unit/update-center/load-items.test.ts`
|
||||
- Modify: `src/__tests__/unit/update-center/UpdateCenterItem.test.ts`
|
||||
|
||||
- [ ] **Step 1: Format the changed files**
|
||||
|
||||
Run: `npm run format`
|
||||
|
||||
Expected: Prettier rewrites changed `src/` and `electron/` files without errors.
|
||||
|
||||
- [ ] **Step 2: Run lint and the targeted update-center suite**
|
||||
|
||||
Run: `npm run lint && npm run test -- --run src/__tests__/unit/update-center/icons.test.ts src/__tests__/unit/update-center/load-items.test.ts src/__tests__/unit/update-center/UpdateCenterItem.test.ts`
|
||||
|
||||
Expected: ESLint exits 0 and the new icon-related tests pass.
|
||||
|
||||
- [ ] **Step 3: Run the complete unit suite and production build**
|
||||
|
||||
Run: `npm run test -- --run && npm run build:vite`
|
||||
|
||||
Expected: all existing unit tests remain green and `vue-tsc` plus Vite production build complete successfully.
|
||||
|
||||
- [ ] **Step 4: Commit the verified icon feature**
|
||||
|
||||
```bash
|
||||
git add electron/main/backend/update-center/types.ts electron/main/backend/update-center/icons.ts electron/main/backend/update-center/index.ts electron/main/backend/update-center/service.ts src/global/typedefinition.ts src/components/update-center/UpdateCenterItem.vue src/__tests__/unit/update-center/icons.test.ts src/__tests__/unit/update-center/load-items.test.ts src/__tests__/unit/update-center/UpdateCenterItem.test.ts
|
||||
git commit -m "feat(update-center): show icons in update list"
|
||||
```
|
||||
214
docs/superpowers/specs/2026-04-10-update-center-icons-design.md
Normal file
214
docs/superpowers/specs/2026-04-10-update-center-icons-design.md
Normal file
@@ -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 仅新增稳定图标位，不改变现有更新列表信息层级。
|
||||
Reference in New Issue
Block a user