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:
142
client/electron/src/stores/appearanceSync.ts
Normal file
142
client/electron/src/stores/appearanceSync.ts
Normal file
@ -0,0 +1,142 @@
|
||||
import { create } from 'zustand';
|
||||
|
||||
import { activeAuth } from '../api/config';
|
||||
import {
|
||||
payloadFromLocal,
|
||||
pullAppearance,
|
||||
pushAppearance,
|
||||
uploadAppearanceImage,
|
||||
type AppearanceAuth
|
||||
} from '../lib/appearance';
|
||||
import { useAccountStore } from './accountStore';
|
||||
import { useBackgroundStore } from './backgroundStore';
|
||||
import { useThemeStore } from './themeStore';
|
||||
|
||||
/**
|
||||
* 外观同步：服务端是权威，本地是缓存。
|
||||
*
|
||||
* 三条不变量（都有判据）：
|
||||
* 1. **登录后以服务端为准**（换设备/换浏览器能拿回来）；
|
||||
* 2. **本地改动会推上去**（换设备再看还是这个外观）；
|
||||
* 3. **拉下来的东西不会再推回去**（否则就是自己触发自己的回环 —— 一次拉取
|
||||
* 会连带 PUT 一次，服务端 updated_at 被无意义地刷新，还会掩盖真实的本地改动）。
|
||||
*
|
||||
* 服务端不可达时状态是 `local-only`，界面上**必须看得见** —— 静默失败会让用户
|
||||
* 以为"已经同步了"，然后在另一台机器上发现没有，正是这次的缺陷。
|
||||
*/
|
||||
export type SyncStatus = 'idle' | 'synced' | 'pending' | 'local-only';
|
||||
|
||||
interface AppearanceSyncState {
|
||||
status: SyncStatus;
|
||||
/** 最近一次成功同步的时刻（ms）。0 = 从没成功过。 */
|
||||
lastSyncedAt: number;
|
||||
/** 正在把服务端的值灌进 store —— 此时不推回服务端。 */
|
||||
applyingRemote: boolean;
|
||||
pull: () => Promise<void>;
|
||||
push: () => Promise<void>;
|
||||
}
|
||||
|
||||
/** 上一次成功上传的壁纸（data URL）。相同就不重复上传几 MB。 */
|
||||
let lastUploadedImage = '';
|
||||
let pushTimer: ReturnType<typeof setTimeout> | null = null;
|
||||
|
||||
function currentAuth(): AppearanceAuth | null {
|
||||
const a = activeAuth();
|
||||
if (!a?.base || !a.token) return null;
|
||||
return { base: a.base, token: a.token };
|
||||
}
|
||||
|
||||
export const useAppearanceSync = create<AppearanceSyncState>((set) => ({
|
||||
status: 'idle',
|
||||
lastSyncedAt: 0,
|
||||
applyingRemote: false,
|
||||
|
||||
pull: async () => {
|
||||
const auth = currentAuth();
|
||||
if (!auth) {
|
||||
// 没登录（或还没选账号）：本地就是全部，且要让用户知道。
|
||||
set({ status: 'local-only' });
|
||||
return;
|
||||
}
|
||||
const remote = await pullAppearance(auth);
|
||||
if (!remote) {
|
||||
set({ status: 'local-only' });
|
||||
return;
|
||||
}
|
||||
set({ applyingRemote: true });
|
||||
try {
|
||||
useThemeStore.getState().setPref(remote.snapshot.theme);
|
||||
const bg = useBackgroundStore.getState();
|
||||
// 背景档与参数以服务端为准；图片只在服务端有图时才覆盖本地
|
||||
// （服务端没图而本地有 = 本地还没推上去，别把用户的图擦掉）。
|
||||
if (remote.snapshot.bgKind === 'preset') bg.setPreset(remote.snapshot.bgPresetId);
|
||||
else if (remote.snapshot.bgKind === 'none') bg.setKind('none');
|
||||
else if (remote.snapshot.bgKind === 'image' && remote.imageDataUrl) bg.setImage(remote.imageDataUrl);
|
||||
if (remote.imageDataUrl) lastUploadedImage = remote.imageDataUrl;
|
||||
bg.setDim(remote.snapshot.bgDim);
|
||||
bg.setBlur(remote.snapshot.bgBlur);
|
||||
} finally {
|
||||
set({ applyingRemote: false });
|
||||
}
|
||||
set({ status: 'synced', lastSyncedAt: Date.now() });
|
||||
},
|
||||
|
||||
push: async () => {
|
||||
const auth = currentAuth();
|
||||
if (!auth) {
|
||||
set({ status: 'local-only' });
|
||||
return;
|
||||
}
|
||||
const theme = useThemeStore.getState().pref;
|
||||
const bg = useBackgroundStore.getState();
|
||||
const payload = payloadFromLocal({
|
||||
theme,
|
||||
kind: bg.kind,
|
||||
presetId: bg.presetId,
|
||||
imageDataUrl: bg.imageDataUrl,
|
||||
dim: bg.dim,
|
||||
blur: bg.blur
|
||||
});
|
||||
|
||||
let ok = await pushAppearance(auth, payload);
|
||||
// 壁纸本体单独传：几 MB 的图不该每次都跟着 PUT 走，只在换图时传一次。
|
||||
if (ok && bg.kind === 'image' && bg.imageDataUrl && bg.imageDataUrl !== lastUploadedImage) {
|
||||
const uploaded = await uploadAppearanceImage(auth, bg.imageDataUrl);
|
||||
if (uploaded) lastUploadedImage = bg.imageDataUrl;
|
||||
else ok = false;
|
||||
}
|
||||
set(ok ? { status: 'synced', lastSyncedAt: Date.now() } : { status: 'pending' });
|
||||
}
|
||||
}));
|
||||
|
||||
/** 本地一改就推（去抖），但**拉取期间不推**（见文件头第 3 条）。 */
|
||||
function schedulePush(): void {
|
||||
if (useAppearanceSync.getState().applyingRemote) return;
|
||||
if (pushTimer) clearTimeout(pushTimer);
|
||||
pushTimer = setTimeout(() => {
|
||||
pushTimer = null;
|
||||
void useAppearanceSync.getState().push();
|
||||
}, 600);
|
||||
}
|
||||
|
||||
/**
|
||||
* 接线：订阅两个 store 的改动，并在账号切换时重新拉取。
|
||||
*
|
||||
* 账号切换必须重新拉 —— 外观是**账号级**的，而 localStorage 里的缓存键是全局的
|
||||
* （这正是"放本地"时最直接的缺陷：同一台机器换账号背景不跟着走）。
|
||||
*
|
||||
* @returns 取消订阅（React 的 effect 清理用）
|
||||
*/
|
||||
export function initAppearanceSync(): () => void {
|
||||
const unsubBg = useBackgroundStore.subscribe(schedulePush);
|
||||
const unsubTheme = useThemeStore.subscribe(schedulePush);
|
||||
const unsubAccount = useAccountStore.subscribe((state, prev) => {
|
||||
if (state.activeId !== prev.activeId) void useAppearanceSync.getState().pull();
|
||||
});
|
||||
return () => {
|
||||
unsubBg();
|
||||
unsubTheme();
|
||||
unsubAccount();
|
||||
if (pushTimer) clearTimeout(pushTimer);
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user