jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
305 Commits 1 Branch 0 Tags
436de6ee4d9d2316fa66bfe99b9ea4516da10a14
Commit Graph

4 Commits

Author SHA1 Message Date
JianFeeeee
be13ae5959 feat(webui): 界面加构建戳 —— 让"我这边改了没"变成可核对的 
用户连续三轮说「webui 还没改」，而我每次都能证明部署是活的（入口 no-cache、
资源哈希 immutable、线上 bundle 与本地构建逐字节一致、无头浏览器实测生效）——
问题在于**隔着屏幕说不清对方的浏览器跑的是哪一份**。

现在界面里显示一行 `界面构建 <git短哈希>·<月日-时分>`（外观设置面板页脚）：

- `vite.config.ts` 在构建时注入 `__BUILD_STAMP__`（git 短哈希 + 构建时刻）
- `BackgroundPicker` 渲染它，并带 title 说明格式
- 判据 4 条（vite 注入 / 组件渲染 / **产物里真的有** / 判据自检：正则不能匹配随便一段文本）

实测：产物与线上都是 `d2904fc·0914-0910`；刷新后数字变了就是拿到了新构建。

顺带修正一处过时文案：图片说明还写着"保存在本机"，而它现在同时存到账号里
（服务端 + 本地缓存）。

前端 254 条 + 新增 4 条、打包一致性、server 10 包全绿；桌面包已重打。
 2026-09-14 09:11:36 +08:00
JianFeeeee
5b6fef764f 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）。

遗留：鸿蒙端还没有外观功能（数据已在服务端，将来可直接读）；本地缓存仍在（离线可用）。
 2026-09-14 08:32:22 +08:00
JianFeeeee
c19eea5e3c feat(webui): 真正动可见层的现代化 —— 字号、层次、间距、分隔线 
# 起因：上一轮的「现代化」基本不算现代化

用户指出「我说的是 webui 现代化」。回看上一轮，我交付的其实是**底层改进**：
圆角加大一档、自定义滚动条、焦点环、过渡、reduce-motion、令牌与可访问性。
这些都对，但**可见变化几乎只有圆角** —— 界面看起来还是老样子。

实测数据确认了「老」在哪：

  text-xs(12px)  172 处   ← 被当正文用
  text-[10px]     84 处
  text-[11px]     68 处
  text-[9px]      19 处   ← 现代显示器上基本读不了
  text-sm(14px)   69 处
  text-base(16px)  4 处

  57 处 border-b + 21 处 border-r，其中 67 条是 border-gray-200 的硬灰线

  阴影：全站共 10 处，且全是 Tailwind 系统默认档；
        index.css 里 --shadow-1/2/3 三个语义令牌**定义了但零处使用**

所以真正的病因是三条：**字太小、层次为零、硬线切分**。

# 改动

## 1. 字号体系抬一档（tailwind.config.js）

不用 Tailwind 默认档，重定为：

  3xs 11px（角标下限，取代 9/10px 魔法数字）
  2xs 12px（元信息，取代 11px）
  xs  13px（次要正文，原 12px —— 拿它当正文的地方自动变舒适）
  sm  14px（正文）
  base 15px

并把 171 处裸 px 类名（text-[9px]/[10px]/[11px]）统一换成令牌 ——
顺带消除魔法数字。行高一起给：小档位 1.35/1.45，正文 1.55，
只放大字号不放行高会把密排列表顶得很难看。

## 2. 把层次接出来（原本是死代码）

tailwind.config.js 新增 boxShadow 映射 `--shadow-1/2/3` + 新增
`--shadow-panel`（横向偏移 + 大扩散，竖向几乎不偏移，否则全高面板像浮在半空）。

用于：列表面板（lg:shadow-panel，**同时去掉 border-r 硬线**）、
登录/初始化卡片（shadow-sm → shadow-2 + 去硬边框）、
地址自动补全下拉（shadow-lg → shadow-2）、窄屏滑入详情面板
（shadow-2xl → shadow-3 + 去 border-l）、主题分段控件的选中滑块。

深色下层次比浅色更难感知，所以 --shadow-panel 在深色里更实一些；
深色里靠边框分组几乎看不见，层次是**唯一**有效的分组手段。

## 3. 分隔线软化（改令牌而不是改 67 处类名）

`--c-gray-200` 浅色 229 231 235 → 234 236 241，深色 44 49 59 → 39 43 52。
改在令牌上，67 条边框 + 8 处底色一次性生效且不会漏。

**刻意没有一起调 gray-300**：它同时是滚动条滑块色，调淡会让滑块更难看见。

## 4. 配比放宽（列表行的呼吸感）

MailList：行内距 px-3 py-2.5 → px-3.5 py-3，列表 gap space-y-0.5 → space-y-1，
表头 py-3 → py-3.5。未读主题字重 medium → semibold，已读 gray-500 → gray-600。

## 5. 量出来的两个真实对比度缺陷（不是估算）

新增 `test/manual/modernization-verify.mjs`，用真实渲染做四条判据。
它量出浅色下两个 WCAG AA 不达标（阈值 4.5:1）：

  - 会话别名 `text-blue-500` 白底 3.68:1（别名在 mail list / thread / mailview
    共 4 处，都是 11px 小字）→ 改 blue-600/700，达 5.17:1
  - 时间戳 `text-gray-400` 压在选中行淡蓝底 `bg-blue-50` 上 4.44:1

第二个的**根因是调色板缺一档**：浅色下 `--c-gray-400` 与 `--c-gray-500`
完全相同（都是 107 114 128），于是「比次要文字再深一档的中间色」根本不存在，
时间戳无处可退。拉开 gray-500 → 90 98 112（5.65:1），并把 5 个列表组件的
行内元信息（19 处）从 gray-400 提到 gray-500。

# 验证

- typecheck 干净
- 前端全量 `npm test` EXIT=0（markdown-xss / narrow-layout / theme 30 /
  background 15 / vitest 216）
- **真实渲染** `modernization-verify.mjs`：浅色 8/8、深色 8/8，判据含
  最小字号 ≥ 11px（改造前 9px）、邮件正文 ≥ 14px、列表面板真有 box-shadow、
  gray-200 是软化值、40 处正文对比度全部达标

# 我自己的三处错（都被这次的度量拦下）

1. **判据量错对象**：第一版拿「收件箱列表」要求 40% 元素 ≥13px，量出 39.7%
   判失败 —— 而收件箱本质是元信息密集区，发件人/时间/别名本来就该小。
   改成量真正该达标的**邮件正文**（≥14px）。
2. **探针忽略 alpha**：`parseRgb` 把 `rgba(239,246,255,0.4)` 的 alpha 丢掉当实色，
   于是把淡蓝底当纯蓝算出 4.44:1 的假缺陷。改为按画家算法合成整条背景链。
3. **config 注释换算写错**：3xs 注释写 10px，0.6875rem 其实是 11px。
 2026-09-12 09:54:31 +08:00
JianFeeeee
84c1d749cd feat(webui): 自定义背景 + 外观现代化；修正实心按钮白字在深色下的对比度 
# 自定义背景（新功能）

三选一：不设 / 预设渐变 / 自定义图片，另加压暗与模糊两条滑杆。

**预设的色值全部复用现有调色板变量**，因此自动随主题变化 —— 那一组
（50–300）在深色下本来就是暗的（见 .dark 与 theme.test.mjs 第 19 条），
于是浅色得到柔和 pastel、深色得到低沉暗调，不需要维护两套渐变，也不会
出现「深色模式下原样落下浅色渐变」这类绕过主题变量的错误。

图片路径的关键取舍：
- **先压缩再存**。手机直出照片 4–8MB，而 localStorage 配额约 5MB，直接写会抛
  异常，用户看到的是「选了图片没反应」。等比缩到最长边 2560px、转 JPEG；
  仍超限则再缩一档；再不行就**明确拒绝并说明原因**（不是静默失败）。
- 失败一律返回 `{ok:false, reason}` 并渲染成 `role="alert"`。

# 背景层为什么不放进主题 store

主题（light/dark/system）是必须全局一致的语义；背景是纯装饰偏好，取值空间
与主题毫无关系。混在一起会让「跟随系统」的实现被背景字段淹没。

# 背景层实现在 CSS，不改 27 个组件

按 Tailwind 生成的实际类名统一接管：背景开启时让出不透明的页面底
（body / bg-gray-50 / bg-slate-100 → 透明），并把卡片（bg-white）与框架
（bg-chrome-800/900）变成半透明 + 背景模糊。

逐个组件加 class 必然漏 —— 漏掉的那块就是一张不透明卡片浮在背景上。
这段 CSS **刻意放在所有 @layer 之外**：它要覆盖的正是 utilities 生成的
`.bg-white`，写进 @layer components 会被 utilities 压过去（静默失效），
而分层 CSS 恒输给未分层 CSS，这是唯一稳定可靠的位置。

**chrome-600/700 刻意保持不透明**：它们不是大面板，而是导航项与 15px 的
计数徽标。真实渲染量得半透明会把徽标上的数字压到 4.46:1，低于 AA 4.5 ——
小控件的可读性优先于装饰效果（已用脚本量出，见下）。

# 「跟随系统」的可见性

三态本来就已实现（system 为默认值 + matchMedia 监听）。这次做的是让它可被
发现与信任：选择器改成分段控件（role=radiogroup + aria-checked），说明文案
写清「跟随系统会随系统的深色开关自动切换」，并保留单选按钮入口的
「当前跟随系统：深色/浅色」提示。

# 外观现代化

- **圆角整体调大一档**（默认 0.25→0.5rem）。原值是几年前的紧凑风格，
  在宽屏桌面应用上偏硬。只改比例尺，200 处圆角一次性刷新，不产生
  「新组件大圆角、旧组件小圆角」的断层。
- 语义化圆角令牌：`rounded-card` / `rounded-control`（数值档位答的是「多大」，
  这两个名字答的是「用在哪」）。
- 自定义滚动条（桌面应用里常驻可见，系统默认样式偏旧）。
- 键盘焦点环（`:focus-visible`，仅键盘导航时出现；可访问性硬要求）。
- 交互元素统一过渡；并尊重 `prefers-reduced-motion`。

# 顺带修正两处真实问题（都由真实渲染量出，不是估算）

1. **实心按钮白字在深色下 4.46:1，低于 AA**。
   深色 `--c-on-accent` 是「近白」244 246 250（为了不刺眼），而结构检查第 23
   条只拿**浅色**的纯白 255 去算 → 4.83 通过。**测试存在盲区**：
   同一个实心底，白字换暗一点点就越过 AA 线。导航未读徽标「12」正是这个组合。

   两处都修：把第 23 条改成**两种模式的 on-accent 都算**（闭合盲区），
   并把深色 on-accent 抬到 250 250 252（4.65:1，仍非纯白，保留原初衷）。

2. **theme.test.mjs 切颜色块的方式很脆**：它用 `indexOf('.dark')` 切片，于是在
   :root 的注释里写一句带点的选择器写法就会把浅色块提前截断（我加注释时
   真的踩到了，第 8 条假失败）。更危险的是反向情形：块被截短后变量集合变小，
   「覆盖齐全」这类断言可能**真空通过**。改为所有块切分都基于**剥注释后**的文本。

# 测试

- 新增 `test/background.test.mjs`（15 条结构检查）：遮罩两主题各一份、
  背景层必须负 z-index（0 会盖住界面）、背景开启时必须让出页面底、
  玻璃化只在 data-bg=on 下、悬停态一并接管、预设复用调色板变量、
  图片上限与失败原因存在、尊重 reduced-motion 等。
- 新增 `test/stores/background.test.ts`（16 条）：脏数据归一化（未知预设、
  kind=image 却无图、越界数值）、CSS 变量写入与清理成对（残留 --bg-image 会
  让「关掉背景」后仍显示旧图）、localStorage 抛异常不打断操作。
- 新增 `test/manual/background-verify.mjs`：连真实 Chromium 验收**渲染结果**
  （背景层是否真的可见、玻璃化的计算样式、正文在背景之上是否仍达 WCAG AA、
  自动模式在**不刷新**页面时跟随系统切换、显式选择不被系统覆盖）。
  它拦住了上面两个真问题，也拦住了我自己两次写错的判据。

# 验证

- typecheck 干净
- 主题 30/30、背景 15/15、vitest 216/216（新增 16）
- 真实渲染验收 23/23（AGENTMAIL_DIST 注入本地构建 + 活 Gateway，未部署即验收）
- 截图对照：浅色/深色 + 极光背景，面板玻璃化与层次均符合预期
 2026-09-12 08:02:30 +08:00