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:
@ -138,21 +138,21 @@ func (u User) CanUsePath(path string) bool {
|
||||
|
||||
// Mail 是会话中的一封邮件
|
||||
type Mail struct {
|
||||
ID uuid.UUID `json:"mail_id"`
|
||||
SessionID uuid.UUID `json:"session_id"`
|
||||
ParentMailID *uuid.UUID `json:"parent_mail_id"`
|
||||
FromName string `json:"from_name"`
|
||||
FromWorkspace string `json:"from_workspace"`
|
||||
ToName string `json:"to_name"`
|
||||
ToWorkspace string `json:"to_workspace"`
|
||||
CCList []Address `json:"cc_list"`
|
||||
Subject string `json:"subject"`
|
||||
Body string `json:"body"`
|
||||
MailType string `json:"mail_type"`
|
||||
PermOptions []string `json:"permission_options,omitempty"`
|
||||
PermResult string `json:"permission_result,omitempty"`
|
||||
PermissionKind string `json:"permission_kind,omitempty"`
|
||||
PermissionMulti bool `json:"permission_multi_select,omitempty"`
|
||||
ID uuid.UUID `json:"mail_id"`
|
||||
SessionID uuid.UUID `json:"session_id"`
|
||||
ParentMailID *uuid.UUID `json:"parent_mail_id"`
|
||||
FromName string `json:"from_name"`
|
||||
FromWorkspace string `json:"from_workspace"`
|
||||
ToName string `json:"to_name"`
|
||||
ToWorkspace string `json:"to_workspace"`
|
||||
CCList []Address `json:"cc_list"`
|
||||
Subject string `json:"subject"`
|
||||
Body string `json:"body"`
|
||||
MailType string `json:"mail_type"`
|
||||
PermOptions []string `json:"permission_options,omitempty"`
|
||||
PermResult string `json:"permission_result,omitempty"`
|
||||
PermissionKind string `json:"permission_kind,omitempty"`
|
||||
PermissionMulti bool `json:"permission_multi_select,omitempty"`
|
||||
|
||||
// PermissionExpiresAt 是这条权限待办的失效时刻（仅仍未决策的 permission_request 有）。
|
||||
//
|
||||
@ -162,9 +162,9 @@ type Mail struct {
|
||||
//
|
||||
// 由读路径按 CreatedAt 推导后填充，**不落库** —— 它是时间的函数，存下来会失真。
|
||||
PermissionExpiresAt *time.Time `json:"permission_expires_at,omitempty"`
|
||||
Status string `json:"status"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
HopLimit int `json:"hop_limit"`
|
||||
Status string `json:"status"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
HopLimit int `json:"hop_limit"`
|
||||
|
||||
SessionAlias string `json:"session_alias,omitempty"`
|
||||
|
||||
@ -223,12 +223,12 @@ type Mail struct {
|
||||
|
||||
// PermissionRequest 是 Agent 向人类发起的权限请求
|
||||
type PermissionRequest struct {
|
||||
ID uuid.UUID `json:"request_id"`
|
||||
MailID uuid.UUID `json:"mail_id"`
|
||||
SessionID uuid.UUID `json:"session_id"`
|
||||
AgentName string `json:"agent_name"`
|
||||
Question string `json:"question"`
|
||||
Options []string `json:"options"`
|
||||
ID uuid.UUID `json:"request_id"`
|
||||
MailID uuid.UUID `json:"mail_id"`
|
||||
SessionID uuid.UUID `json:"session_id"`
|
||||
AgentName string `json:"agent_name"`
|
||||
Question string `json:"question"`
|
||||
Options []string `json:"options"`
|
||||
Context string `json:"context"`
|
||||
Kind string `json:"kind"` // permission | question
|
||||
MultiSelect bool `json:"multi_select"` // 仅 question 使用
|
||||
@ -319,3 +319,59 @@ type Attachment struct {
|
||||
SHA256 string `json:"sha256"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
}
|
||||
|
||||
// Appearance 是**账号级**的用户外观（主题 + 壁纸）。
|
||||
//
|
||||
// 背景的取值范围刻意收窄（kind 三值、dim/blur 有上限），因为服务端要
|
||||
// 兜住"客户端被改坏"的情况：这些值最终会写进 CSS 变量，越界值会让界面不可读。
|
||||
type Appearance struct {
|
||||
Theme string `json:"theme"` // light / dark / system
|
||||
BgKind string `json:"bg_kind"` // none / preset / image
|
||||
BgPresetID string `json:"bg_preset_id"`
|
||||
BgDim int `json:"bg_dim"` // 遮罩强度 %（0-90）
|
||||
BgBlur int `json:"bg_blur"` // 照片模糊 px（0-40）
|
||||
ImageSHA256 string `json:"-"`
|
||||
ImageType string `json:"-"`
|
||||
ImageBytes int64 `json:"image_bytes"`
|
||||
UpdatedAt string `json:"updated_at,omitempty"`
|
||||
}
|
||||
|
||||
// DefaultAppearance 是"从没设置过"时的外观 —— 与客户端 backgroundStore /
|
||||
// themeStore 的默认值一致（dim 12、blur 4 是 2026-09-13 壁纸修复后的取值）。
|
||||
func DefaultAppearance() Appearance {
|
||||
return Appearance{Theme: "system", BgKind: "none", BgPresetID: "aurora", BgDim: 12, BgBlur: 4}
|
||||
}
|
||||
|
||||
// NormalizeAppearance 把客户端传来的值夹进合法范围。
|
||||
// 认不出的 kind/theme 一律退回默认 —— 静默接受非法值会让界面白屏且无从排查。
|
||||
func NormalizeAppearance(a Appearance) Appearance {
|
||||
switch a.Theme {
|
||||
case "light", "dark", "system":
|
||||
default:
|
||||
a.Theme = "system"
|
||||
}
|
||||
switch a.BgKind {
|
||||
case "none", "preset", "image":
|
||||
default:
|
||||
a.BgKind = "none"
|
||||
}
|
||||
if a.BgPresetID == "" {
|
||||
a.BgPresetID = "aurora"
|
||||
}
|
||||
if len(a.BgPresetID) > 64 {
|
||||
a.BgPresetID = a.BgPresetID[:64]
|
||||
}
|
||||
if a.BgDim < 0 {
|
||||
a.BgDim = 0
|
||||
}
|
||||
if a.BgDim > 90 {
|
||||
a.BgDim = 90
|
||||
}
|
||||
if a.BgBlur < 0 {
|
||||
a.BgBlur = 0
|
||||
}
|
||||
if a.BgBlur > 40 {
|
||||
a.BgBlur = 40
|
||||
}
|
||||
return a
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user