feat(appearance): 主题与壁纸搬到服务端（账号级）—— 回答"为什么背景存在本地"
用户质问：「为什么背景是保存在本地而不是服务器！」当时的实情是主题与壁纸只写 localStorage：换设备/换浏览器就没了，而且**多账号共用一份**（键是全局常量 `agentmail.background`）—— 同一台机器换账号背景不跟着走。而 localStorage 的 ~5MB 配额也解释了客户端那套"压到 2.4MB 以内"的限制本来就是为本地存储设计的。 现在：**服务端是权威（账号级），本地只是缓存**（首屏秒开、离线可用）。 ## 服务端 - 新表 `user_appearance`（两种方言），用**列**而不是 JSON：blob GC 要一眼看出 "这张图还有没有人用"。 - `/api/v1/me/appearance`：GET / PUT（主题+背景档）/ POST image（multipart）/ GET image / DELETE image。鉴权同其余 /me/*（cookie 或 Bearer）。 - 图片走**内容寻址的 blob 存储**（与附件同一套），库里只存 sha256；上限 4MB 兜底 （客户端会先压到 ~2.4MB），只收图片类型（非图片 415 —— 浏览器会把非图片渲染成 空白，用户只会看到"设置了却没变化"），超限 413 不静默截断。 - ★ **blob GC 的引用源加了这张表**：我在实现前先读了 `SweepUnreferencedBlobs`， 它只认 attachments / calendar_attachments。漏了这一处，壁纸会在下次 GC 时被当 孤儿删掉，而库里那行还在 —— 表现为"图 404、设置却显示已设置"。判据同时验了 壁纸存活**与**孤儿确实被清（否则"还在"可能只是因为 GC 没跑）。 ## 客户端 - `lib/appearance.ts`（纯函数：两侧形状换算、data URL→Blob）+ `stores/appearanceSync.ts` （pull / push / 去抖订阅 / 账号切换重新拉取）。 - 三条不变量都有判据：拉取以服务端为准；★ **拉取不会再推回去**（否则是自触发回环， 一次拉取顺带一次 PUT，服务端 updated_at 被无意义刷新）；本地改动会推上去。 - 壁纸**只在换图时上传一次**（几 MB 不该每次 PUT 都跟着走）。 - 降级**必须可见**：未登录/不可达 → `local-only`，推失败 → `pending`，背景设置里 有徽标与说明（"已同步 / 待同步 / 仅本机"）。静默降级会让人以为已经同步， 然后在另一台机器上发现没有 —— 正是这次的缺陷。 - 图片用**带认证的 fetch** 取回再转 data URL：`<img src>` 发不出 Bearer，而 `?token=` 会把密钥写进历史记录与服务端日志（明确不做）。 ## 判据 - Go 10 条：往返、★多账号隔离、非法值归一、上传/取回字节一致、非图片 415、 超限 413、删除、未登录 401（五个端点）、★GC 存活 + 孤儿对照。 - 客户端 10 条：形状换算、image 无图退回 none、越界夹取、拉取生效、 ★拉取不推送、推送 payload、未登录/500 → local-only、推失败 → pending、 ★壁纸只上传一次。 - 全量：server 10 包全绿、客户端 249 通过（含打包一致性判据 —— 它先红后绿， 因为前端改了必须重打安装包，这条护栏是先前特意留下的）。 ## 线上验证与交付 - jianf 设置 → 回包 saved=true；**gui-lab 读到自己那份默认值**（隔离生效）； gui-lab 上传 67B PNG → 取回 sha256 一致、`has_image=true`；DELETE 后 404。 - 网关已重打（WebUI 内嵌）并部署；Electron 安装包已重打（AppImage + deb）。 遗留：鸿蒙端还没有外观功能（数据已在服务端，将来可直接读）；本地缓存仍在（离线可用）。
This commit is contained in:
148
client/electron/test/stores/appearanceSync.test.ts
Normal file
148
client/electron/test/stores/appearanceSync.test.ts
Normal file
@ -0,0 +1,148 @@
|
||||
/**
|
||||
* 外观同步的行为判据（2026-09-14）。
|
||||
*
|
||||
* 背景：用户质问「为什么背景是保存在本地而不是服务器！」⇒ 主题与壁纸搬到服务端
|
||||
* （账号级），本地只做缓存。这一层出错**不会抛异常**，只会表现为"设置看起来保存了，
|
||||
* 换设备却是别的样子"或"改动没存上却显示已同步" —— 所以必须逐条钉住：
|
||||
*
|
||||
* 1. 拉取以服务端为准（换设备能拿回来）
|
||||
* 2. ★ 拉取**不会**再推回去（否则自己触发自己：一次拉取顺带一次 PUT，
|
||||
* 服务端 updated_at 被无意义刷新，还会掩盖真实的本地改动）
|
||||
* 3. 本地改动会推上去（payload 形状要对）
|
||||
* 4. 推不上去要变成 pending，未登录/不可达是 local-only —— **降级可见**
|
||||
* 5. 壁纸只在换图时上传一次（几 MB 的东西不该每次 PUT 都跟着走）
|
||||
*/
|
||||
import { beforeEach, describe, expect, it, vi } from 'vitest';
|
||||
|
||||
import { setActiveAuth } from '../../src/api/config';
|
||||
import { useAppearanceSync } from '../../src/stores/appearanceSync';
|
||||
import { useBackgroundStore } from '../../src/stores/backgroundStore';
|
||||
import { useThemeStore } from '../../src/stores/themeStore';
|
||||
import { payloadFromLocal, snapshotFromResponse } from '../../src/lib/appearance';
|
||||
|
||||
type Call = { url: string; method: string; body?: any };
|
||||
|
||||
function fakeFetch(handler: (call: Call) => Response | Promise<Response>) {
|
||||
const calls: Call[] = [];
|
||||
globalThis.fetch = (async (input: any, init: any = {}) => {
|
||||
const url = String(input);
|
||||
const call: Call = { url, method: init.method || 'GET', body: init.body };
|
||||
calls.push(call);
|
||||
return handler(call);
|
||||
}) as any;
|
||||
return calls;
|
||||
}
|
||||
|
||||
const json = (body: unknown, status = 200) =>
|
||||
new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
|
||||
|
||||
const REMOTE = {
|
||||
theme: 'dark',
|
||||
bg_kind: 'preset',
|
||||
bg_preset_id: 'dusk',
|
||||
bg_dim: 33,
|
||||
bg_blur: 7,
|
||||
has_image: false
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
localStorage.clear();
|
||||
setActiveAuth({ base: 'http://gw', token: 'tok' });
|
||||
useAppearanceSync.setState({ status: 'idle', lastSyncedAt: 0, applyingRemote: false });
|
||||
useThemeStore.getState().setPref('system');
|
||||
useBackgroundStore.setState({ kind: 'none', presetId: 'aurora', imageDataUrl: '', dim: 12, blur: 4 });
|
||||
});
|
||||
|
||||
describe('快照换算（纯函数）', () => {
|
||||
it('服务端的值能灌进本地形状，认不出的退回默认', () => {
|
||||
expect(snapshotFromResponse(REMOTE)).toEqual({
|
||||
theme: 'dark',
|
||||
bgKind: 'preset',
|
||||
bgPresetId: 'dusk',
|
||||
bgDim: 33,
|
||||
bgBlur: 7
|
||||
});
|
||||
expect(snapshotFromResponse({ theme: 'neon', bg_kind: 'video' } as any)).toMatchObject({
|
||||
theme: 'system',
|
||||
bgKind: 'none'
|
||||
});
|
||||
});
|
||||
|
||||
it('★ image 档但没图 → 退回 none（免得服务端存成"有图却没有"）', () => {
|
||||
const p = payloadFromLocal({ theme: 'dark', kind: 'image', presetId: 'aurora', imageDataUrl: '', dim: 12, blur: 4 });
|
||||
expect(p.bg_kind).toBe('none');
|
||||
const q = payloadFromLocal({ theme: 'dark', kind: 'image', presetId: 'aurora', imageDataUrl: 'data:image/png;base64,AA', dim: 12, blur: 4 });
|
||||
expect(q.bg_kind).toBe('image');
|
||||
});
|
||||
|
||||
it('越界的 dim/blur 被夹住（服务端也会夹，但本地不该先送出脏值）', () => {
|
||||
const p = payloadFromLocal({ theme: 'light', kind: 'preset', presetId: 'aurora', imageDataUrl: '', dim: 999, blur: -3 });
|
||||
expect(p.bg_dim).toBe(90);
|
||||
expect(p.bg_blur).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('拉取与推送', () => {
|
||||
it('拉取以服务端为准（换设备能拿回来）', async () => {
|
||||
fakeFetch(() => json(REMOTE));
|
||||
await useAppearanceSync.getState().pull();
|
||||
expect(useThemeStore.getState().pref).toBe('dark');
|
||||
const bg = useBackgroundStore.getState();
|
||||
expect(bg.kind).toBe('preset');
|
||||
expect(bg.presetId).toBe('dusk');
|
||||
expect(bg.dim).toBe(33);
|
||||
expect(useAppearanceSync.getState().status).toBe('synced');
|
||||
});
|
||||
|
||||
it('★ 拉取不会再推回去（否则是自触发回环）', async () => {
|
||||
const calls = fakeFetch(() => json(REMOTE));
|
||||
await useAppearanceSync.getState().pull();
|
||||
const writes = calls.filter(c => c.method !== 'GET');
|
||||
expect(writes, `拉取期间不该有任何写请求：${JSON.stringify(writes)}`).toEqual([]);
|
||||
});
|
||||
|
||||
it('本地改动推上去，且 payload 形状对', async () => {
|
||||
const calls = fakeFetch(() => json({ saved: true }));
|
||||
useThemeStore.getState().setPref('light');
|
||||
useBackgroundStore.getState().setPreset('mint');
|
||||
await useAppearanceSync.getState().push();
|
||||
|
||||
const put = calls.find(c => c.method === 'PUT');
|
||||
expect(put, '应当发出 PUT').toBeTruthy();
|
||||
const body = JSON.parse(String(put!.body));
|
||||
expect(body).toMatchObject({ theme: 'light', bg_kind: 'preset', bg_preset_id: 'mint' });
|
||||
expect(useAppearanceSync.getState().status).toBe('synced');
|
||||
});
|
||||
|
||||
it('未登录 → local-only（降级必须可见）', async () => {
|
||||
setActiveAuth({ base: '', token: '' });
|
||||
fakeFetch(() => json(REMOTE));
|
||||
await useAppearanceSync.getState().pull();
|
||||
expect(useAppearanceSync.getState().status).toBe('local-only');
|
||||
});
|
||||
|
||||
it('服务端不可达 → local-only，不是"已同步"', async () => {
|
||||
fakeFetch(() => json({}, 500));
|
||||
await useAppearanceSync.getState().pull();
|
||||
expect(useAppearanceSync.getState().status).toBe('local-only');
|
||||
});
|
||||
|
||||
it('推送失败 → pending（稍后重试，而不是假装成功）', async () => {
|
||||
fakeFetch(() => json({}, 503));
|
||||
await useAppearanceSync.getState().push();
|
||||
expect(useAppearanceSync.getState().status).toBe('pending');
|
||||
});
|
||||
|
||||
it('★ 壁纸只在换图时上传一次（几 MB 不该每次 PUT 都跟着走）', async () => {
|
||||
const calls = fakeFetch(() => json({ has_image: true }));
|
||||
useBackgroundStore.getState().setImage('data:image/png;base64,AAAB');
|
||||
await useAppearanceSync.getState().push();
|
||||
const posts = () => calls.filter(c => c.method === 'POST').length;
|
||||
expect(posts(), '第一次推送应上传图片').toBe(1);
|
||||
|
||||
// 只改参数、不换图 → 不该再上传
|
||||
useBackgroundStore.getState().setDim(40);
|
||||
await useAppearanceSync.getState().push();
|
||||
expect(posts(), '没换图时不该重复上传').toBe(1);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user