jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
463 Commits 1 Branch 0 Tags
4ecddfc2b652fa30b509ebc6cd726e5d045b3513
Commit Graph

17 Commits

Author SHA1 Message Date
JianFeeeee
4ecddfc2b6 跨端: 语义色/三级文字在深色下没提亮（设备扫出 12 处）+ 判据取样法修到第三版 
## 一、判据基建先修对，否则是在听噪声

深色可读性扫描的**取样法迭代了三版**，每版都因为**假红**才改的
（记在这里，因为"判据自己错"比"界面错"更费时间）：

1. **取中心一个像素** ⇒ 落在笔画之间、读到的是底色 ⇒ 一片 ratio=1.00 假红。
2. **取全局最暗/最亮** ⇒ 会采到**两个不同的东西**：细字的抗锯齿中间色。
   实例：segmented「日」报 ink `rgb(32,34,35)` / bg `rgb(98,100,101)` 2.69:1 ——
   而截图里它要么蓝底白字、要么深底浅字，两种都远高于 3:1。
   **反复核对才确认是判据的错，不是界面的错。**
3. **步长采样 + 众数** ⇒ 仍然假红：周表头「一」报 2.03:1，
   而逐像素的真实墨是 `rgb(166,167,167)`（**6.6:1**）——
   稀疏网格**整个跳过了笔画**。这不是调参能修好的（字越小越糟）。
4. **逐像素 + 众数=底 + 离底最远者=墨**（最终版）。
   理由：一个文字框里**面积最大的一定是底**，而"离底色最远"就是笔画最实那部分。
   ⚠️ 逐像素是**负担得起的**（整屏已解码在内存，一个框最多 9 万像素）——
   **不要再为了省开销退回抽样**，前两版都因此假红。

## 二、真 bug 三批（都是"深色下没提亮"）

### ① 语义色前景（12 处 → 修完设备复扫 0）
WebUI 的语义色也是**双通道**，`.dark` 段把 `red/green/amber-700` 换成浅色
（`248/118/249 → 164/219/195` 那组）。鸿蒙只有一个深色值：
- 「归档」按钮 `Theme.danger` #B91C1C 压深面 ⇒ **2.47:1**（联系人页 7 处）
- 「今天」/「日」等 ⇒ **2.38–2.77:1**

加 `dangerDark/approveDark/warnFgDark`（逐字对齐 WebUI `.dark`）
+ `dangerFor()/approveFor()/warnFgFor()` 入口，22 处接入。

### ② 日历工具条整块配色抄错（不是"深色档选错"）
对照 WebUI `CalendarView.tsx:313-331`：

| 元素 | WebUI | 鸿蒙（改前） |
|---|---|---|
| 「今天」 | `border-gray-300` + `text-gray-700`（**中性**） | `accentSoft` 底 + `accentStrong` 字 |
| 月/周/日 未选中 | `bg-white` + `text-gray-700` | `accentSoft` 底 |

鸿蒙把**次要的中性按钮**画成了**品牌色按钮** —— 视觉重量跟主操作一样，
三个档看起来"都像选中"。已按 WebUI 改成中性。

### ③ 三级文字在深色下 2.82:1（**71 处**，全局最大的一个）
WebUI 的 `.dark` 段注释逐字写着这个坑：

> 「`gray-400/500`（次要文字）→ **提亮**。深底上的浅色 gray-400
>  只有约 2:1 对比度，远低于 WCAG AA 的 4.5:1 —— **看得见但读不动**。」

鸿蒙用的系统三级色 `ohos_id_color_text_tertiary` 深色下是 `rgb(102,103,105)`
压深面 **2.82–3.05:1**，而它被用在 10–11px 的**小字**上
（时间戳、农历、空态、辅助说明）。

**不换掉系统令牌**（"系统拥有的维度"纪律照旧），加 `textSubtleFor()`：
深色下改用二级色（实测 `rgb(166,167,167)` ≈ 7.15:1，
且与 WebUI 的 `gray-500` 同档位）。71 处接入。

**设备复扫（修后）**：通信/日历/联系三页 **176 段文字全部 ≥3:1**。

## 三、欠账与底本

- `baseline.sha` 第 4 次重算。仍**先逐个取证**：
  `git diff --quiet HEAD -- <f> && echo STALE || echo INTENTIONAL`
  ⇒ 三个全是 `INTENTIONAL`（我改的），不是变异残留。
  把这条取证命令也写进文件，下次照抄。
- `dangerDark/approveDark/warnFgDark` 已登记进 `SELF_OWNED_COLORS`
  + `Theme.ets` 登记表（各带理由与 WebUI 出处）。

`run-all.mjs` → `checks=514 pass=514 fail=0 skip=0 red=0 broken=0 unreported=0`。

**未验**：①「我的」页（底部头像按钮，扫描脚本没找到入口）没扫；
② 浅色下的对比度没扫（本轮全部针对深色）。
 2026-09-19 20:27:09 +08:00
JianFeeeee
13b557a742 跨端: 品牌蓝深色下没提亮（24 处字/图标看不见）+ 补深色可读性设备判据 
## 一、真 bug：WebUI 深色下把品牌蓝**提亮**了，这边没有

WebUI 的强调色是**双通道**（`tailwind.config.js` 的 `backgroundColor`
/`textColor` 覆盖 + `index.css` 两段定义）：

| 通道 | 用途 | 浅色 | 深色 |
|---|---|---|---|
| `--s-blue-600` | **实心按钮底** | `37 99 235` | `37 99 235`（**同值**）|
| `--c-blue-600` | 内容/交互的**蓝字与图标** | `37 99 235` | **`128 175 249`** |

`index.css:353` 写了理由：主按钮底跟着变「会让主按钮在深色页面上
失去『这是主操作』的视觉重量」；而蓝字必须提亮，否则深底上读不动。

鸿蒙只有一个 `Theme.accent = '#2563EB'` ⇒ 24 处字/图标在深色下
对比度 **2.61:1**（设备实测：管理页返回箭头 `‹`），低于 WCAG 图形下限 3:1。

**取证方式**：在跑着的 WebUI 上用 CDP 读**计算样式**（不是读 CSS 源）——
浅色 `37 99 235` / 深色 `128 175 249`，实测确认。

## 二、修法：加前景专用的深色档 + 唯一入口

- `Theme.accentDark = '#80AFF9'`（= WebUI `.dark --c-blue-600`）
- `Theme.accentFor(dark?)` 作为**前景**唯一入口
- **当背景的 20 处保持 `Theme.accent` 不动**（跟 WebUI 的 `--s-*` 一致）

24 处 `.fontColor/.iconColor(Theme.accent)` → `Theme.accentFor()`。

## 三、顺手修掉「转述一层就会漏」这个结构问题

`accentSoftFor(isDark)` 原本的约定是"页面算好深浅色传进来"。
给 `accentFor` 做准备时一数：**8 处**直接用了 `Theme.accentSoft`（没走入口）
—— 约定**已经漏了**，而漏掉的症状正是上一轮那个"深色下白底卡片刺眼"。

于是把两个 `For()` 的参数都改成**可选**：`AppStorage` 是 ArkTS 全局键值存储，
静态类可以直接读（原来"拿不到 Context"的理由不成立）。
⇒ `Theme.isDarkNow()` 成为唯一判断点，调用方不必再各自转述。

## 四、设备判据：深色可读性**扫一屏**

原来只有悬浮球那一条（单个点）。这个 bug 类一天撞到**两批**（12 处 + 24 处），
逐处写判据追不上 ⇒ 改成把当前页所有小段文字都量一遍对比度。

三个实现要点（第一版全踩了，都写进注释）：
- **不能只取中心一个像素**：中心多半落在笔画之间 ⇒ 读到的是底色，
  报出一片 ratio=1.00 的假红。改成**框内网格扫描取极值**（最亮=底/最暗=墨）。
- **整屏解码一次**：每点 spawn 一次 ffmpeg 太慢 ⇒ 新增
  `readPixels()`（157ms 解整屏，比逐点快三个数量级）。
- **只判"有真实墨迹"的框**（`hi.L - lo.L >= 0.02`），否则跳过而不是判红。

实测：修前 1 处低对比（2.61:1），修后 **40 段文字全部 ≥3:1**。

## 五、判据自身的三个修正

- `accentSoftFor(dark:)` 的签名断言跟着放宽成 `dark?`，并**补上 `accentFor` 的**。
- **孤儿令牌判据从"一跳"改成"走整条链"**：`KEY_IS_DARK` ← `isDarkNow()`
  ← `accentFor()` ← 24 处页面。只查一跳时它假红 ——
  ★ **"有没有人用"是可达性问题，不是邻接问题**；加中间层（抽 `For()` 入口）
  恰恰是我们鼓励的写法，而旧判据会因此假红。
- 手写色登记表补 `accentDark` 一行理由。

## 六、`baseline.sha` 重算（先核过不是残留）

三个文件哈希对不上。逐个 `git diff --quiet HEAD -- <f>` 取证：
- `AdminUsersPage.ets` / `SettingsPage.ets` —— 本次**有意编辑**；
- `api/AppearanceApi.ets` —— **与 HEAD 逐字节相同** ⇒ 底本取完后被**合法改过**
  （提交 `f811c98`），属 `stale` 不是 `residue`。

按该文件自己那条纪律（「重算必须是一次有记录的动作」）在文件里记了理由。

`run-all.mjs` → `checks=514 pass=514 fail=0 skip=0 red=0 broken=0 unreported=0`。
 2026-09-19 20:05:33 +08:00
JianFeeeee
fc295893cb 跨端: 深色模式下的品牌浅底不跟随 —— 12 处「选中/未读」底色在深色页上刺眼 
## 真 bug（设备实测）

深色主题下，「我的」页**选中**的那张账号卡片仍是接近纯白的浅蓝
（实测像素 `(255,255,255)` 级别的浅底压在 `(32,34,36)` 的深色页上）。

根因：`Theme.accentSoft = '#EFF6FF'` 是**写死的浅色**，而它被当作
「选中态背景」用在 12 处（未读邮件行、选中账号、分段选中、登录页模式切换…）。

**为什么只有 WebUI 没这个问题**：它有 CSS 变量的**反转发**机制 ——
`index.css:113` 的 `--c-blue-50: 239 246 255` 在 `.dark` 段（`:475`）被换成
`28 37 54`（深蓝黑）。ArkTS 的 `static readonly` **一个常量一个值**，
没有那层机制 ⇒ 静态常量必须自己提供两个取值。

## 修法

1. `Theme.accentSoftDark = '#1C2536'`（对齐 WebUI `.dark --c-blue-50` 的 `28 37 54`）
2. `Theme.accentSoftFor(dark)` 作为**唯一入口** —— 不在页面里各自
   `isDark ? a : b`：那样每处都会各写一遍，迟早漏一处
   （WebUI 那条"由 test/theme.test.mjs 逐档断言"就是为防这个）
3. **深浅色从哪来**：只有 `MainPage` 算得出（它读 `resourceManager` 的
   `colorMode`）。所以走 `AppStorage` 单向发布（与徽标、windowInsets 同一套）：
   MainPage 算 → 写 `agentmail.appearance.isDark` → 各窗格 `@StorageProp` 读。
   6 个文件、12 处，全部改用 `accentSoftFor(this.isDarkNow)`。

**设备实测**：深色下「我的」页账号卡片与收件箱未读行都变成深蓝底，
像素 `(32,34,36)` 与页面底一致（不再刺眼）。

## 判据（这条是新加的，形状值得记）

`cross-client-theme` 新增：**品牌浅底必须有深色变体**。断三件事：
1. 深色变体存在，且**取值从 WebUI 的 `.dark` 段反推**（不是随手挑一个深色）；
2. 有按主题选值的**入口**（防"页面各自写三元"）；
3. **用到它的地方真的走那个入口** —— 扫描所有 `backgroundColor(… accentSoft …)`
   并排除 `accentSoftFor`，把漏改的位置**逐行报出来**。

第 3 条在我改到一半时**当场列出了剩下 9 处**（`CalendarPage:1172`、
`ComposePage:255`、`LoginPage:327`…）—— 这就是它该有的样子：
不是"断言存在某个常量"，而是"断言没有一处漏改"。

★ 写这条判据时踩了自己一次：JS 模板串里嵌了反引号包围的标识符
（`` `accentSoft` ``），直接 SyntaxError。改用字符串拼接。

## 判据

`run-all.mjs` → `checks=506 pass=506 fail=0 skip=0 red=0 broken=0 unreported=0`。
`hvigorw assembleHap` 成功；前端重建。

**未验**：日历/登录页在深色下的观感（只逐处改了底色，没逐页截图）。
 2026-09-19 16:02:26 +08:00
JianFeeeee
f811c9887a 跨端: 三个真 bug（外观保存 400 / 改档位界面不动 / 内容列溢出屏幕）+ 设备判据 
这一轮从「全面对齐 WebUI 和鸿蒙」开始，先做设备层判据升级，结果**判据一上线就连撞三个真 bug**
—— 它们全都是静态判据照不到的形状：**数据对、界面不动**。

## 一、外观保存从来就没成功过（PUT 400）

`payloadFromLocal` 复用了 `AppearanceResponse` 当请求体，而那个类型是 **GET 的响应**：
带着 `has_image` / `image_bytes` / `saved`。服务端的 `Decode()` 是
`DisallowUnknownFields()`（严格，**有意为之**）⇒ **每一次保存都被拒收（400）**。

症状极隐蔽：本地 `@State` 立刻变 ⇒ 肉眼看着像成功了；只有看 hilog 的 HTTP 状态码
才发现 400。修法是加 `AppearancePayload`（**恰好**服务端 `models.Appearance` 的五个字段）。

★ 这是"两端共用同一个类型"的代价：请求与响应本来就不该同形。
★ 服务端严格是**对的** —— 它帮我们抓到了这个错误。修客户端，不是放宽服务端。

## 二、改了档位，页面背景一点不变（两层原因）

**第一层**：`SettingsPage` 存进 store 了，但 `MainPage` 的 `bgPlan` 只在启动时算一次，
之后没人动 ⇒ 发布一个 `AppStorage` revision（计数器，不是布尔 —— 布尔 true→true
不发变化通知），`MainPage` 用 `@StorageProp + @Watch` 接住。

**第二层（更隐蔽）**：接上之后**还是不动**。因为 `bgPlan` 是 `@State BackgroundPlan`，
而 **ArkTS 的 `@State` 观察不到类内部字段**的变化 —— 渲染读的正是
`this.bgPlan.kind` / `.layers`。hilog 一对证据同一次启动相差 100ms：

    Appearance: sync: bgKind=preset … hasImg=true    ← 数据是对的
    Wallpaper: kind=none layers=0 active=false       ← 渲染读到的还是旧值

修法：加 `@State bgContentRev: number`，每次算完 plan 就 +1，**并在 Builder 的
条件表达式里消费它**（ArkUI 按"这个 Builder 读了哪些 @State"决定是否重渲染；
只加计数器而渲染不读，等于没加 —— 判据同时断这两半）。

★ 同一个坑本仓出现过（`AppearanceStore` 的注释里写着这句），这次换了地方发作。

## 三、「我的」页右端内容被顶出屏幕（追了很久的 `56.000000` 之谜）

真相有**两层，两层都值得记**：

1. `dumpLayout` 里 `Slider` 节点的 `text='56.000000'` 是**无障碍文本**
   —— 屏幕上根本没这串字（截图可证）。**dump 的 text ≠ 看得见的字**。
2. 真正的问题是那个**看得见的** `Text('56%')` 落在 `x=3250`，而屏宽 3184
   ⇒ **它在屏幕外**。用户只看得到滑杆、看不到数值。

根因：`MainPage` 里"侧栏 + 内容列"是 `Row` 并排，内容列写 `.width('100%')`
—— 在 Row 里 `100%` 是**父容器全宽**，与侧栏的 60vp **相加** ⇒ 必然溢出。
实测内容列 `[229,28][3357,2204]`，右边缘超出屏幕整整 173px（= 60vp）。
修法：改 `.layoutWeight(1)`（吃剩余空间）。修完实测 `[229,28][3156,2204]`，
`Text('56%')` 落在 `[3049,1803]` —— 屏内。

★ 为什么值得一条设备判据：**同一处错误在不同 pane 上表现不同**
（日历页自己算宽度就没露出来），很容易被当成"某一页的样式问题"去调。

## 四、设备判据基建（这一轮加的能力）

- `lib/harmony-device.mjs` 新增 `launchOurApp` / `ourAppInFront` / `tapText` / `swipe`。
  `swipe` 里 clamp velocity 并写明那个坑：`uitest` 的 velocity 越界**不报错**，
  只回一句 "out of range, the default value will be used"，静默换成默认 600。
- 三条新设备判据（`harmony-appearance`）：壁纸档位真的切换 / 窗格内容不得超出屏幕。
- 修了一个**元问题**：设备判据在套件里**恒跳过**（要求"现场已经摆好"），
  只有手动摆好才通过 ⇒ 那等于没有判据。现在它们**自己搭现场**
  （拉起应用 → 导到目标页 → 操作 → 复位）。`cross-client-gesture` 与
  `harmony-appearance` 都改成了这样，套件里 `skip=0`。
- 途中撞出的两个判据自身缺陷（都写了注释）：
  · `root0` 用**切页前**的快照 ⇒ 套件里红、单独跑绿（通过与否取决于跑之前那一屏）
  · 侧栏项筛选没排除**品牌标** ⇒ 想点「日历」却点到「通信」

## 验证

`run-all.mjs` → `files=32 ran=32 checks=503 pass=503 fail=0 skip=0
red=0 broken=0 unreported=0`（含设备判据：gesture 9、appearance 27）。
`hvigorw assembleHap` 成功；前端重建 + 重打包（`build-stamp` 7/7、`packaging` 5/5）。

设备实测（HATriple 3184×2232）：
· `PUT /me/appearance` 从 **400 → 200**（服务端访问日志），
  库里 `jianf` 的记录从空变成 `bg_kind=preset / bg_dim=56 / bg_blur=3`。
· 壁纸真的透出来了：预设档缝隙 `#E0E2E4`、不设档 `#FFFFFF`（像素级对比）。
· 「我的」页 `56%` / `3px` 正常显示在屏内。

**未验**：壁纸在真机上的观感（渐变是否好看、压暗 56% 是否合适）；
这一轮只验了"数据通了、界面响应了、内容没被裁掉"。
 2026-09-19 15:03:40 +08:00
JianFeeeee
36ef15a8f2 跨端: 顶栏不再自己铺白条 + 日历改左右两栏 + 常驻窗格动画真的会播（用户三处实测指出） 
用户三条反馈，逐条对应：

① 「底栏数字为什么显示在图标下面？」
   WebUI 的徽标是 `absolute top-1 right-[22%]`（脱离文档流、浮在图标右上角），
   我写成了 `Column` 的第三个子节点 ⇒ 参与竖向布局、掉到文字下面。
   改用 `Stack({ alignContent: Alignment.TopEnd })` 锚在**图标**上。
   （顺带撞了 skill 里明写的坑：Stack 没有 `.justifyContent()`。）

② 「一个横着过去的白条，我真的服了」/「期望：融进背景」
   WebUI 的顶栏**自身没有底色** —— 只有 `border-b border-gray-200`
   （`ContactPanel.tsx:64`、`CommTabs.tsx:40`、`CalendarView.tsx:295`），
   底色由所在面板给；壁纸开启时那层面板是玻璃色（`index.css:876`）。
   鸿蒙三个窗格顶栏写死了 `Theme.surface`（实心白）⇒ 无论壁纸开没开，
   顶上都是一条不通明白带。改成与**页面底**同一口径
   （`bgActive ? Transparent : surface`）+ 补下边框。

③ 「日历页面和webui布局完全不同」
   WebUI 是**左右两栏**（`CalendarView.tsx:452-457`）：左 `flex-1` 网格、
   右 `400px` 常驻面板（日程 / 编辑器 / 小时网格三态互斥）。
   鸿蒙原来是**单栏竖堆**。重搭为两栏，`paneWide` 由 `.onAreaChange`
   量本页**自己的**宽度（不是屏幕宽度 —— 宽屏下这一页已被侧栏占掉一截）；
   编辑器改占右栏位置（不再整页盖掉正在看的那个月）。

④ 「最严重的动画问题你一点也不该改」
   日历是**常驻挂载**（`visibility` 控制，因为它里面 today 要随时间重算、
   也要保住"正在看哪个月"），而 `.transition()` 只在**挂载/卸载**时触发
   （SDK 原话 \"when it **appears and disappears**\"）⇒ 挂在它上面的
   `.transition(paneRiseIn())` **一帧也不会播**，切过去是硬弹。
   WebUI 踩过同一个坑并把错法写进了 `index.css:1305-1320`
   （「只挂了类，却没让触发窗口出现 ⇒ 类挂着、动画永远不播」），
   它的解法是 `html.view-switch` 重放窗口。ArkUI 对应物是
   `animateTo` + 显式 `calPaneIn` 属性（`opacity` + `translate`）。
   ★ reset 必须在 `animateTo` **外**：写进回调里会与同帧的 1 相抵，
     渲染层只看得见最终值 ⇒ 动画退化成一个瞬移。

顺带修：
· 宽屏侧栏 = 3 项（通信/日历/**联系**）+ 底部一簇（头像/主题/退出），
  与底栏的四项（含「我的」）**不是同一份清单** —— WebUI 的 Sidebar 与
  NarrowNav 本就不同（`Sidebar.tsx:26-44` vs `NarrowNav.tsx:37-40`+143）。
  新增 `NAV_SIDEBAR_ITEMS` / `ME_PANE_INDEX` / `SIDEBAR_ITEM_*`。
· 退出登录抽成 `api/Logout.ets` 的 `performLogout()`：侧栏底簇与「我的」页
  两个入口必须做同一件事（尤其"先注销推送 token"那一步），复制一份就会不一致。
· 徽标 `'plain'` 档底色：WebUI 是石板灰 `--c-chrome-600`（#475569），
  我写成与未读共用红色 ⇒ 「联系」的徽标看起来像"有未读"。
· 主题快捷开关（侧栏底簇）：对齐 `ThemeToggleButton` —— 从 `system` 翻转时
  落到**当前生效值的反面**（不是回 system；那可能毫无变化、让按钮看起来坏了）。
· 「浓度」→「压暗」+ 数值带单位（原先屏上印 `56.000000`；WebUI 是 `suffix="%"`）。

判据（8 个套件全绿：logic 28 / nav 18 / widescreen 7 / window 9 /
arkts 5 / contacts 5 / calendar 30 / system-api 5）：
· `harmony-widescreen` ② 重写：**回读 `Sidebar.tsx` 数 `short:` 的个数**
  要求鸿蒙同数，并断言底部一簇三键真的被调用（`this.onToggleTheme()` ——
  第一版写成 `/onToggleTheme/`，变异测试当场证明它不咬：属性**声明**还在，
  正则照样匹上）。新增 ⑧：三档色调各自底色，期望值从 `--c-chrome-600` 读出。
· `harmony-nav` 动画条重写：改判**机制真的存在且被驱动**
  （旧断言 `.visibility(...).transition(...)` 锁的正是那个 bug ——
  判据引自己写的注释当依据，就会把错误锁死）。新增 reset-在-animateTo-外
  这条断言（否则动画退化成瞬移）。
· `harmony-nav` 设备条：`navItemsOf` 的宽屏过滤从"左边缘靠左 1/6"
  改成"**整个盒子在侧栏轨道内**" —— 旧条件把日历网格的格子
  （实测 `[229,511][366,794]`）也当成导航项，一屏数出 11~12 个。
  新增 `navRailItemsOf`：导航轨贴顶、底部簇在屏底，按位置切一刀。
· `harmony-logic` 两处：从 `NAV_ITEMS` / `NAV_SIDEBAR_ITEMS`
  **各自的数组**里取 label —— 原先把全文件 `label:` 一网打尽，
  得到 7 个（4+3 混在一起），任何一边改对了它都会红。

设备实测（HATriple 三折叠，3184×2232）：侧栏 3 项 + 底簇 / 底栏徽标回到
图标右上角 / 日历左右两栏与 WebUI 并排同构。

server/go.mod：补 2da38bb 漏提交的 lunar-go 依赖。
 2026-09-19 12:30:05 +08:00
JianFeeeee
686193458a fix(harmony): 底栏黑带 / 联系人点不开 / 我的页不守导航 / 顶栏硬截断 
用户（2026-09-17）连报五条：「一点动画都没有」「底部那个黑条是啥意思」
「日历页面、我的页面、联系人页面哪个跟 webui 对齐了」「联系人页面连点都点不开」
「你的顶栏为什么还是硬截断而不是渐变」。逐条查证后修：

── ① 底部黑条 = 系统导航栏区域，不是我们画的 ──
根因：窗口默认给系统导航条留位，那块在深色下是黑的；界面于是看起来底下多一条黑带。
修法：`setWindowSystemBarEnable(['status'])` 隐藏系统导航条（底部那条本就是我们自绘的
悬浮玻璃条），内容铺满全高。
★ 刻意**不用** `setWindowLayoutFullScreen(true)`：实测试过，它也能消掉黑带，但会连
状态栏区域一起吃进布局，页签栏被时钟/电量盖住（截图硬证「07:43」与「收件箱」重叠）。

── ② 联系人点不开（用户原话「连点都点不开」）──
根因：`ContactItem` / `WorkCard` **根本没有 onClick** —— 卡片画出来了，
但没有任何点击路径。当时判据只钉了"字段与 WebUI 一致"，没钉"点了会发生什么"。
修法：点卡片打开那条会话的邮件列表，就地在**本窗格内**展示（新增 `SessionMailsView`
＋ `GET /sessions/{id}/mails`），底部导航保留；每封可再点进详情。

── ③ 我的页不遵守导航规则 ──
根因：点底栏「我的」走 `pushUrl('pages/SettingsPage')` 推**独立 @Entry 页** ⇒
底部导航整条消失，要按返回才能再切窗格。WebUI 里 `account` 只是一个 `viewMode`，
与收件箱同级、导航常驻。
修法：`SettingsPage` → `SettingsPane`（去掉 @Entry 与返回键，从 main_pages.json 摘除），
作为**第 4 个内容窗格**挂到 `currentIndex === 3`；`NAV_CONTENT_COUNT` 3 → 4，
`NAV_ITEMS` 第 4 项去掉 `route`；拨动动画包 `getUIContext().animateTo`。
实测：`我的` 页底部导航可见，可滚到「退出登录」「管理」。

── ④ 顶栏硬截断 ──
根因：`Scroll` 与 `List` 都能挂 `fadingEdge`（同在 `ScrollableCommonMethod` 上），
但**只有 MainPage 的 List 挂了** —— MailDetailPage / CalendarPage / SettingsPage /
AdminUsersPage / SessionsPage / InboxPage 的滚动容器全漏。同一次滚动里
列表是渐隐、正文是硬切，看起来就是"顶栏没做渐变"。
修法：13 个容器全部补齐（LoginPage 例外：它的 Scroll 是整页根、不是列表，
写了理由）。实测：视口上沿被切断的文字最暗 170–196，而下方不透明正文是 **19**。

── ⑤ 一点动画都没有 ──
实测确认改造前全仓 `animateTo` / `transition` / `animation` **一次都没用过**。
补：Theme 加令牌（durFast 120 / durBase 180 / easeOutSoft = cubic-bezier(0.22,1,0.36,1)，
与 WebUI `--dur-*`/`--ease-out-soft` 同值同曲线）；切窗格包 `animateTo`；
导航项选中变色加 `.animation`。

判据（218 passed / 0 failed）：
· 新增「渐隐覆盖**所有**页面滚动容器」：按文件枚举 + 计数配平，
  并自检扫到的容器总数（防正则写坏 ⇒ 全绿）。**这条一写就抓到 LoginPage**。
· ①/②/⑤ 与 headless 那几条按新事实改写：内容窗格 3→4、
  `normalizeNavIndex(3)` 归一到自己、导航项里**禁止**再出现 `pushUrl`
  （那正是导航消失的形状）。
· 修掉自己引入的两处判据缺陷：`itemCode` 未定义；以及一条**窗口式断言**
  （从内容层 `}` 往后扫，靠数花括号定界，而注释里就有大量 `.padding({`，
  切片长到 1700+ 字符一路扫进 `onAreaChange` ⇒ 假红），改为纯负向断言。

未验：真机观感；横屏 Auto Split 双栏；日历页深度对齐（本轮只补了渐隐）。
 2026-09-17 21:15:11 +08:00
JianFeeeee
423ff9fbb2 跨端: feat(推送客户端) 收尾两处接线（pi 邮件 66bbd929 分工）+ 换账号补报 
`PushService.ets` 与 `pendingRoute` 都早就写好了，但**没人调用/没人读** ——
而"写好了"与"接上了"是两件事：ArkTS 只编译可达模块，往一个无人 import 的
文件里放必然报错的类型错误，`assembleHap` 照样 BUILD SUCCESSFUL
（pi 与我各复现过一个方向）。这次补的是**边**，不是点。

① 登录成功补报（LoginPage）：`EntryAbility.onCreate` 那次在**登录之前**跑，
   那时 `ApiClient` 还没有 token ⇒ 服务端 401，而 `reportToken` 的失败是静默的
   ⇒ "启动时报过"不等于"这个账号登记过"。补三条登录路径，一条都不能漏：
   快速路径（已有账号直接进主界面，老用户走这条）/ tryRestore / doLogin。

② 换账号补报（SettingsPage.switchTo，**我加的第三处**）：服务端语义是同一
   token 换账号**转移**而非并存 ⇒ 新账号其实没登记过。幂等标记按
   `accountKey|token` 存，所以这里调一次必然重发，不会被"我报过"挡掉。
   不补的症状：切完账号，通知仍推给上一个账号。

③ pendingRoute 消费端（MainPage.CommPage）：`EntryAbility` 已把通知 data
   解析成 `pendingRoute`（冷启 onCreate / 热启 onNewWant 都写了），
   **但没有任何东西读它** ⇒ 点通知只拉起 App、停在列表页。
   在 CommPage 消费（详情页是这个 Navigation 的 navPathStack 上的路由，
   栈只有它持有），消费后**立刻清空**（它是"待处理"不是"当前页"，
   不清则返回列表再进来会被反复跳走）。

判据：`harmony-push.test.mjs` 15 → 18 条，三条新判据钉的就是上面这三条边，
**三条都做了变异验证**（各自删掉对应接线即红、恢复即绿）。
`LoginPage` 那条数**恰好 3 处**调用：少了快速路径＝老用户永远不补报，
多了要问清是哪条路径。

编译验证（不是"命令成功"，是"它真读了这个文件"）：三处改动各植入一次必然
类型错误 ⇒ BUILD FAILED 且 `At File:` 指到**新代码那一行**（MainPage:1173 /
LoginPage:108 / SettingsPage:456），恢复后 BUILD SUCCESSFUL。
产物侧证：`modules.abc` 里能查到 `consumePendingRoute`(2) / `reportPushToken`(2)。
 2026-09-17 19:03:14 +08:00
JianFeeeee
c523c21e22 feat(harmony): 邮件详情与「我的」页 1:1 对齐 WebUI，并修两个线上 bug 
用户：「为什么邮件页面没有对齐 webui？」「我的页面也没有对齐」，
选定「完全 1:1」。两个页面都不是「没做」，而是**做了一半** ——
`AuthApi` 的 logout/listKeys/createKey/revokeKey 全都写好但没人调，
`Models.ets` 的字段声明漏了服务端一直在返回的那些。

── 邮件详情页（对齐 WebUI `MailView.Header` / `CollapsibleHeader`）──
· 头部改**可折叠**（默认收起）：收起只留标题 + 必须常驻的状态点
  （未读 / 权限请求）+ 箭头。WebUI 的理由：顶部信息常驻会把可读区压成
  一条缝（实测 1280×800 下头部 17% + 回复框 31%，正文只剩 48%）。
· 发件/收件改**三段式完整地址**：Agent → `pi@/home/program/agentmail.别名`，
  人 → 只有名字。新增 `model/ReplyTarget.ts`（逐字移植 WebUI `replyTarget.ts`，
  并对齐后端 `models.FormatAddress`）。
· 时间：`localDateTime()` → `2026/09/15 11:37:07`（原为裸 ISO `2026-09-15T03:37:07.14758Z`）。
· 档位：`permissionLabel()` → `只读/目录内/全权`（原为英文 `plan/workspace/full`；
  这个函数早就在 `MailGrouping.ts` 里、列表页也在用，只有详情页没用）。
· 新增抄送行；回复入口改**右下悬浮球**（WebUI `reply-fab`），
  不再是底部 56vp 通栏按钮。

── 「我的」页（对齐 WebUI `AccountPage`，补 5 个缺失 section）──
标题由「账号管理」改为「我的」（多账号只是其中一段，不是整页的目的）。
· 基本资料：用户名/显示名/角色/状态/创建时间/最后登录。
· 权限范围：可调用 Agent / 可访问目录（非管理员；空数组 = 不限）。
· 修改密码：三输入框 + 不一致就地提示（新增 `AuthApi.changePassword`，
  该端点服务端一直有、客户端从未包）。
· 客户端连接密钥：列表 / 新建 / 吊销 + 一次性全文提示
  （`AuthApi` 的三个方法终于被调用）。
· 退出登录：先注销推送 token → 清凭证 → **清全部账号** → 回登录页。
· 整页改为**一个 Scroll**：原来账号列表 `layoutWeight(1)` 占满剩余高度，
  排在它后面的 section 被挤出可视区且滚不到（WebUI 注释里正是这个坑），
  而「退出登录」在最下面 ⇒ 等于退不出去。

── 顺带修掉的两个线上 bug（都是判据发现的）──
① `MeApi.get()` 调 `GET /me`，但服务端**没有**这个路由（只有 `/auth/me`；
   `/me/*` 下是 mail/sessions/keys/appearance 子资源）。
   后果：这把调用恒 404 → `loadRole()` 恒走 catch → `isAdmin` 恒 false
   → 「管理」入口对**包括管理员在内**的所有人永远不显示。
   实证：`GET /api/v1/me` → 404；`GET /api/v1/auth/me` → 200
   `{"user":{"role":"admin",...}}`。修复后截图里「管理」入口已出现。
② 详情页回复写 `req.to = this.fromName + '@'`：那个游离的 `@` 让 `name@`
  被后端 `ParseAddress` 解析成「有 path、无 session」⇒ 落到该 Agent 的
  **默认会话**，而不是用户正在看的那条线索。改用 `replyTargetAddress()`。

── 判据（新增 7 + 8 条，全部含变异自检）──
· `harmony-reply-target.test.mjs`（新）：直接执行 `ReplyTarget.ts` 断言行为
  —— 空 path 必须留 `@`（否则整串被当成名字、投递 404）、人只有名字、
  会话位必须带上、`from_workspace` 不得用来拼地址（会得到 `dsh@dsh`）；
  并读 Go 源码比对三分支结构。
· `harmony-admin.test.mjs`（+5）：`/auth/me` 路径（含服务端注册与响应形状）、
  八个 section 齐全、退出清全部账号、整页一个滚动容器、字段来自服务端。
  变异自检：把 `/auth/me` 改回 `/me` → 判据变红（已验证）。

测试：212 passed / 0 failed；`devecocli build` 通过；
模拟器截图逐项核对（详情收起/展开两态、我的页全部 section）。
未验：真机观感；横屏 Auto Split 双栏。
 2026-09-17 17:43:03 +08:00
JianFeeeee
cfe7808af4 ke: 鸿蒙 UI 整改：emoji→AmIcon 图标、宽屏侧栏、Md 第三方库、通知可配置项 
- common/Icons.ets（生成器产出）：43 枚与 WebUI icons.tsx 同几何的 Path 图标
- NavItems.ts：icon(emoji) → iconKey，与 WebUI 导航同图标
- 全页面 emoji 清除（空态改单行灰字，按钮/头像/刷新等换 AmIcon）
- MailDetailPage 接入 @luvi/lv-markdown-in（第三方，替代手写解析器）
- WideSidebar + MainPage isWide(≥768vp)：宽屏侧栏 60vp 图标轨、藏底部条、onAreaChange 断点
- 通知=可配置项（默认关）：PushService.isEnabled/setEnabled + reportToken 最前 gate （关=不取token/不弹权限/不打网关）+ SettingsPage Toggle + 服务端通道状态提示
- EntryAbility.onCreate 解析 want：冷启点通知也能路由（原来只有 onNewWant）
- 判据：harmony-widescreen(4) + harmony-push-optin(4) 新增；harmony-nav 同步 iconKey/条件 padding
 2026-09-16 07:46:52 +08:00
JianFeeeee
9c6e9c66ad 跨端: 修复: 鸿蒙客户端"连不上服务器"—— 地址补 /api/v1 + 失败分类成人话（含网络白名单固化） 
症状
  鸿蒙客户端（client/harmony）连不上服务端，界面只显示"无法连接"，用户无法自助；
  而服务端 HTTPS 完全正常：https://mail.jianfgit.xyz/health → 200、
  /api/v1/auth/me → 401、/api/v1/events/stream → 401（Let's Encrypt *.jianfgit.xyz，
  TLS 校验通过；代理与直连 http://127.0.0.1:8180 行为一致）。

根因（两条，逐条核实过，其中一条**推翻了原判断**）
  ① apiBase 是"API 前缀本身"（ApiClient 里拼的是 '/auth/login' 这类相对路径），
     而 Ui 只做 trim+去尾斜杠：用户若只填 `https://mail.jianfgit.xyz/`，请求就打到
     `https://mail.jianfgit.xyz/auth/login` ⇒ 404，客户端再把它压成"无法连接"。
     **这是本次故障最可能的直接原因。**
  ② 默认值 `http://192.168.2.60:8180/api/v1` 是明文 + 写死内网 IP：手机不在同网段
     就永远不通（mail.jianfgit.xyz 解析到的就是这台内网机）。
     ★ 但"鸿蒙默认禁止明文 HTTP"这条**不成立**，已按本机离线官方文档核实：
     `devecocli docs read .../使用HTTP访问网络/http-request` 的《明文HTTP访问权限配置说明》
     写明 cleartextTrafficPermitted "默认为 true"，Network Kit 默认允许明文；
     另有 FAQ《Stage模型如何配置支持http明文传输》："无需配置，支持HTTP明文传输数据"。
     ⇒ network_config.json 按"显式固化意图"处理（照文档形状写对，但**不冒充**它是修复）。
     本机 SDK @ohos.net.http.d.ts 里确实有 2300997 Cleartext traffic not permitted（since 18），
     所以那条错误码在客户端被建成一条可读提示，而不是被忽略。

改法
  · 新增 model/ApiBase.ts（纯逻辑，无 @ohos，判据能用 node 直接跑）：
    normalizeApiBase（去尾斜杠**但不咬协议 //**、末尾没有 /api/v1 就补、已有的一字不动）、
    validateApiBase（自带修法的中文提示 + "公网明文才告警、内网明文不误报"）、
    describeFailure（404 自己写文案并点名 /api/v1；其它状态码让服务端文案说话；
    网络层按 2300006/2300007/2300028/2300997/2300998/2300058-60-77 分类成人话）。
  · Config.ets：DEFAULT_API_BASE → https://mail.jianfgit.xyz/api/v1。
  · ApiClient.ets：setBase/init **都**过 normalizeApiBase（唯一闸口 ⇒ 老装机里已经存下的
    坏地址在读回时就治好，光改默认值救不了它）；ApiError 带 nativeCode；错误路径改走
    describeFailure；404 的提示指向"地址少了 /api/v1"。
  · LoginPage.ets：地址先校验后持久化（不合法**不落库**、给可执行提示），明文警告常驻渲染；
    SettingsPage.ets：添加账号同样校验（多账号库直接喂 SseService，坏地址会让该账号的实时
    通道永久连不上）；AccountManager/SseService 落库与建连时各自再归一化一次。
  · 新增 resources/base/profile/network_config.json：按官方文档形状把内网明文
    （192.168.2.60 / 10.0.2.2 / localhost）显式列进 domain-config 白名单。
    文档给的就是这个**固定路径与文件名**，不需要在 module.json5 里写引用
    （仓库里既有的 HomeAgent 工程同样是这么放的）。
  · 新增判据 test/harmony-apibase.test.mjs（13 条）并接进 run-all.mjs 的 SUITE：
    值判据**直接跑** model/ApiBase.ts；.ets 那几条是**静态**接线判据（本机无设备）。

验证（都真跑过）
  · cd client/harmony && devecocli build clean && devecocli build
    → BUILD SUCCESSFUL in 7 s 186 ms；entry/build/default/outputs/default/entry-default-signed.hap
    存在（1214592 B，15:14）。
  · 解包 HAP：resources/base/profile/network_config.json 在包里、JSON 可解析、
    cleartextTrafficPermitted=true 且白名单含 192.168.2.60/10.0.2.2/localhost；
    bundleName 仍是 com.jianf.agentmail，module.json 没有多余的 metadata/securityConfiguration。
  · devecocli check lint → 0 error；我改过的文件**零发现**（总工性从 8 降到 7，
    顺带修掉 LoginPage 一条既有的 await-thenable）。
  · node --experimental-strip-types --no-warnings --test test/harmony-apibase.test.mjs
    → ℹ tests 13 / pass 13 / fail 0。
  · 变异验证 11/11 全红且**红在对应那条**（在 /tmp 的独立 worktree 里做的，不碰共享树）：
    归一化不补后缀、去斜杠咬掉协议、404 用通用文案、401 拿通用文案顶掉服务端原因、
    网络码不再分类、默认地址退回明文内网、setBase 直接赋值、登录页去掉守卫、
    内网白名单关掉明文、出现第二处自己拼 /api/v1、守卫变成空壳。
    （M8 第一次是**假绿**——只判了方法声明、没判调用点；改成切出 doLogin 方法体后再判才红。）

未验到（别把"编译过了"读成"连通了"）
  · **没有**在真机/模拟器上点过一次登录：本机当前无设备在线，所以"真的连上了服务端"
    这件事本轮**未被验证**；已验证的只是"地址会被补成带 /api/v1 的形态""构建产物正确"。
  · network_config.json 的**实际效果**未验：按官方文档明文默认就允许，这份文件是显式固化，
    没有做"关掉它再对比"的实验（也无法在无设备时做）。
  · DNS/超时/证书这几条分类的文案是按 SDK 错误码写的，**没有构造真人故障去实测**
    （即没有真的把 DNS 打坏、把证书换成自签来看提示）。
  · 登录页那条"未 /api/v1 会 404"的因果链是从服务端路由 + 客户端拼接方式推出的，
    没有用 curl 对 `https://mail.jianfgit.xyz/auth/login` 实打一次取证。
  · test/run-all.mjs 在本机（node v24.14.1）**本来就是红的**：它只认 `# pass N`，
    而 node 24 打的是 `ℹ pass N` ⇒ 25 个文件里 21 个被记成"没自报条数"。
    这是既有环境漂移（已在 HEAD 的 worktree 里复现同样的红），**本次没有动它**，
    所以新判据虽然已登记进 SUITE，要等 runner 的 marker 解析修好才会被套件真正计数。
 2026-09-15 15:15:17 +08:00
JianFeeeee
474cadaf54 跨端: harmony 管理页（用户管理）+ P4c 壁纸上传入口 —— 「功能做全再交付」的两块 
pi 的交付清单里缺的两块（`docs/GUI-PLAN-HARMONY.md` 原先把管理后台划在首版之外，
用户明确要求「功能做全再给我」之后收进来）。

标 `跨端:` 是因为本次的判据落在 `client/electron/test/`（鸿蒙的判据目录一向量在那里），
代码本体全在 `client/harmony/`。

## 管理页（用户管理）

- `pages/AdminUsersPage.ets`：新建 / 编辑（显示名·角色·白名单）/ 启停 / 重置密码。
  排布照 `AdminUsersPage.tsx`，包括「受限」徽标的口径（普通用户且白名单非空才显示）、
  最后登录缺席与空串都显示「从未登录」、管理员对白名单两项忽略。
- 入口在设置页底部，**仅管理员可见**（`role === 'admin'` 严格相等，与 `App.tsx` 同口径）。
  读不到身份时**不**显示也不报错（乐观放行会让每个普通用户看到一个点进去 403 的入口）。
- `api/AdminApi.ets` + `model/AdminUsers.ts`（纯逻辑，零 import ⇒ 判据能真跑）。
- 启停**只发 status 一个字段** —— 服务端是部分更新，多发字段会把显示名与白名单一起改掉。
- `model/Models.ets` 补管理端 DTO；`main_pages.json` 注册路由。

## P4c 壁纸上传

- `model/ImagePrep.ts`：阈值与两档策略（2560/0.85 → 1280/0.78，入口 20MB，压后上限 3.5MiB）。
  **一处有意不对齐 WebUI** 并写明理由：WebUI 卡 data-URL 长度（含 base64 膨胀），
  鸿蒙内存直传 ArrayBuffer，卡的是字节数。
- `common/BackgroundPicker.ets`：不设 / 预设 / 自定义图片 + 浓度与模糊滑杆。
  上传链：picker → 判可不可以 → 逐档按 desiredSize 解码压缩 → 上传 → **请页面以服务端为准重新同步**。
  失败**必带原因**（服务端 415/413 文案原样透出）。
- `ApiClient.uploadBytes`：MultiFormData.data 收 ArrayBuffer（核了 SDK，since 11；本工程 23）
  ⇒ 内存直传，不需要 base64、也不需要临时文件。
- 用户取消选图**不算失败**，什么都不说。

## 顺带修掉的两处真问题（都是变异测试逼出来的）

1. **压缩循环的第二档此前是死代码**：循环里的 break 与循环外那句 shouldRetryWithActual
   互相抵消 —— 把循环里那处改成 `if (true)`（永远只压一档）整套判据照样全绿。
   收成一处判定（overLimit），循环外只读结论。
2. **壁纸的模糊档一直是「只写不读」**（计划文档 §7.12 登记过）：滑杆能拖、值能存、
   blurStyleFor 也写了，就是**没有调用点**，壁纸一点没糊。本次补上调用点
   （壁纸层 .blur(px) = 图片内容模糊；导航条材质由 blurStyleFor 映射）。
   同时按 §7.12 的原承诺更新了那一行。

## 一并修正的旧判据（都是"太宽/太窄"，不是放宽标准）

- 「模糊归属」：原文「壁纸层不许有**任何**模糊调用」把**图片内容模糊**与**面板材质**
  混为一谈（WebUI 侧核实：.app-backdrop 的 filter 与它之上那层的 backdrop-filter
  是两个不同的量）⇒ 改成按两种模糊分别钉。
- 「bgBlur 只写不读，消费侧必须为 0」：值不再成立，**形状保留**（逐文件登记 + 计数 + 理由），
  标题与断言里的假话一并改掉。
- isDarkMode 那条 `/dark\s*\)/` 断的是**参数顺序**（加一个入参就误红）⇒ 改成"dark 在实参里"。
- 导航材质三处断言原本钉 `Theme.navMaterial` 字面量 ⇒ 改成钉新的映射写法。

## 判据

新增 `harmony-admin.test.mjs`（22 条）、`harmony-imageprep.test.mjs`（29 条）；
`harmony-presets.test.mjs` 加 1 条（模糊档搬运与归一，含 -0 那个洞）。
全量 203 条：**201 通过**，2 条失败为**改动前就红**的既有项
（BUILD_INFO 比对、词表↔余额）—— 用 stash 对照验证过。

两个新判据文件上跑了 **48 个变异体，全部被抓**（含"接线"类：删掉「受限」徽标、
组件自己宣布成功、release 不 await、按原图尺寸解码…），
其中 2 个变异体**红不了**，因此又补了 5 条判据（纯逻辑接线、退档判定只有一处、
两档都超限必拒、解码尺寸用的是目标尺寸而非原图尺寸、模糊档搬运）。
（数字口径：按 runner 的真实条件"锚点恰好命中 1 次才算跑过"统计；
另有 4 条锚点不命中、根本没跑，不算在这 48 里。我第一次写的是"40"——
凭记忆累加的，错了，已更正。）

**未验**：本机无设备/无模拟器 ⇒ 全部观感未验（管理页排版、滑杆手感、模糊在真机上的
实际档位观感）。代码齐 ≠ 真机验过。
 2026-09-15 11:03:22 +08:00
JianFeeeee
2a6ad93ec0 feat(harmony): P4 —— 外观（主题 + 壁纸）跟着账号走 
服务端 2026-09-13 起就是外观的权威（账号级 `/api/v1/me/appearance`），WebUI 接好了，
**鸿蒙这边此前完全没接**。这一期补上，并把"谁覆盖谁"的规则做成可判据的纯逻辑。

## 改了什么

- `api/AppearanceApi.ets`：`GET/PUT /me/appearance`、`POST /me/appearance/image`、
  `GET /me/appearance/image`（图片带认证取回本体：不用 `?token=`，也不让 Image 直连 http）。
- `api/ApiClient.ets`：新增 `getBytes()`（按 ARRAY_BUFFER 收）—— 复用 `request<T>` 会当场炸，
  因为它假定响应是 JSON（`JSON.parse`）。
- `model/Appearance.ts`（纯逻辑，判据直接执行）：归一化 / PUT 报文 / **合并决策** /
  模糊值→系统材质档次 / 主题→系统色彩模式 / 遮罩浓度 / 状态文案。
- `common/AppearanceStore.ets`：落地副作用 —— 主题交给**系统**（`setColorMode`，不自己维护
  深色色值）、壁纸取回 `PixelMap`、缓存**按账号**分键（`appearance.<accountId>`）。
- 入口两处：`MainPage`（进主界面就应用 —— 只在设置页生效的话"一进主界面就变回去"，
  WebUI 侧踩过）与 `SettingsPage` 新增「外观」段（三档主题 + 同步状态「已同步 / 仅本机」）。

## 为什么这么写（两条最贵的规则）

1. **服务端"没有记录"时以本地为准**（`saved === false`）：服务端这时回的是一份*默认值*，
   拿它覆盖本地 = 把用户已有的主题/壁纸抹掉（WebUI 原话：每个老用户升级后第一次登录
   都会发现被重置）。正确动作是把本地那份推上去。
2. **降级必须可见**（`local-only` → 显示「仅本机」）：否则用户以为换设备也能带走。

## 判据（新增 11 条，已接进 run-all；套件 10 → 11 个判据文件）

归一化（脏值/越界/小数/NaN 退回默认）；`image` 档无图 → 退回 `none`；PUT 报文蛇形字段名；
★服务端无记录 → 以本地为准且**一个字段都不能被默认值顶掉**；服务端有记录 → 以服务端为准但
**不擦掉**本地那张服务端还没有的图；离线状态可见且三种状态文案互不相同；
★模糊值→系统材质档次（与 SDK 的 `BlurStyle` 成员**逐一比对**）；
主题→色彩模式（数值与 SDK 的 `ConfigurationConstant.ColorMode` **逐一比对**）；
★路径必须**相对基地址**（WebUI 那条"整套同步从来没生效过而单测全绿"的坑）；
缓存键**带账号**；两处入口都真的应用。

变异验证（6 种，均判红）：默认值覆盖本地 / 不管"image 档但服务端无图" / 材质档次自造名字 /
路径多写 `/api/v1` / 缓存键不带账号 / 深浅色彩模式数值写反。

## 判据抓到的两个真 bug

- `snapshotFromResponse` 在字段缺失时给 `bgDim = 0`，而 WebUI 语义是退回 12 ——
  ArkTS 反序列化把缺失字段留成**类里写的默认值**，"字段不在"与"字段是 0"分不开。
  已把默认值对齐 WebUI 的 `clamp(..., dflt)` 语义（并让 `saved` 默认 false = 安全的那一侧）。
- 主题落地按"0=浅色、1=深色"写的 `setColorMode` —— **正好反了**
  （SDK：`COLOR_MODE_DARK = 0`、`COLOR_MODE_LIGHT = 1`），选深色会切成浅色。
  靠判据去 SDK 枚举文件读数比对发现；映射已搬进纯逻辑 `colorModeValue`，
  从"某处有个 setColorMode 调用"变成"可判据的行为"。

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（11 个判据文件全绿 + vitest 258/258）。
套件自检又抓到一次"判据写好没接进套件"（新文件第一版漏了 run-all），已修。

**未做**：壁纸**上传**入口（选图 → `POST /me/appearance/image`）—— 需要 picker，API 与命名已就位。
**未验**：壁纸在真机上的渲染 —— 需真机或模拟器。
 2026-09-14 14:19:26 +08:00
JianFeeeee
c6aaf8c468 refactor(harmony): 23 处废弃 API 换成 UIContext 写法（全局 promptAction.showToast 自 API 18 废弃） 
SDK 里写得很清楚：`@ohos.promptAction.d.ts` 的全局 `showToast` 标着 `@deprecated since 18`，
替代品是 `UIContext.getPromptAction()`。仓库里有 23 处这种调用（6 个页面，历史遗留）——
这一轮既然在按"用系统方案"整理鸿蒙侧，就一次扫干净，并加判据挡住回潮。

- `promptAction.showToast(...)` → `this.getUIContext().getPromptAction().showToast(...)`（23 处）
- 清掉不再需要的 `promptAction` import（多个 → 只留 `router` 等）
- 新增判据：不得再用全局写法。防的不是这次，而是**新增页面照抄旧代码**这条回退路径 ——
  它编译照样通过、只在真机上行为不同。自检同时验"认得出旧写法"与"不误伤新写法"。
- 顺带把权限徽标那条"点它弹说明"的判据改成钉**非废弃**写法（原来是 `promptAction.showToast(`）。

变异验证：把 `SettingsPage` 的一处改回全局写法 → 判红并点出文件。

验证：`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（harmony-logic 20 条）。
 2026-09-14 14:05:35 +08:00
JianFeeeee
36f3183bba feat(harmony): 系统方案第一批 —— 表面/文字/圆角交给系统、删手写玻璃、每项一张卡；跨端判据改"意图相同" 
jianf：「鸿蒙也同步，但是鸿蒙要求用系统方案」。按 pi 对齐的形状（A/B/C + 品牌色防线）落地。

## 鸿蒙侧改了什么

- `Theme.ets` 的表面/文字/分隔/遮罩/圆角**来源换成系统**：
  `pageBg→sys.color.ohos_id_color_background`、`surface→…_list_card_bg`、
  `surfaceMuted→…_sub_background`、`border→…_list_separator`、三级文字 `→…_text_primary/secondary/tertiary`、
  `overlay→…_mask_regular`、`radiusCard/Control→sys.float.ohos_id_corner_radius_card/button`。
  于是这些维度自动跟随深色模式与无障碍设置 —— 这正是"手抄 WebUI 色值"做不到的事。
- **删掉手写玻璃** `#B8FFFFFF`/`#B80F172A`：那两个值等于"我们替系统猜了深色该怎么做"。
  换成一个**档次**声明 `navMaterial: BlurStyle = BlurStyle.COMPONENT_THICK` + 导航条上的
  `.backgroundBlurStyle(...)`；深浅两套颜色与模糊半径由系统按主题给。
  遮罩的两段式（色 + 透明度）同样删掉：拆两段本就是为了"随主题换向"，而这件事系统已经做了。
- **每项一张卡/气泡**：收件箱行、会话组头、联系人列表行改成卡片（圆角 + 卡片底色 + 行间距），
  联系人列表那条贯通分隔线删除。
- 仍然自己写的只有两类：**品牌色**（`accent = #2563EB`，跨客户端身份）与**业务语义色**
  （权限三档、预算三档 —— 系统只有 warning/alert 两个情绪色，凑不出三档，硬套会丢语义）。

## 判据：从"取值相同"改"意图相同"（两侧一起改）

- 品牌蓝**唯一保留取值钉**，并新增防线：不得退化成 `$r('sys.color.*')`
  （系统强调色随主题/厂商皮肤变，"两个客户端是同一个产品"就靠不住了）。
- 圆角/材质/遮罩：改成"WebUI 自声明令牌 + 鸿蒙来自系统 + 差异被记录"（§7.12 有意差异表）。
- 新增 A（系统拥有的维度唯一来源是 `$r('sys.*')`，且不得退回 string/number）、
  B（旧机制不得回来：`navBg*`、8 位半透明色、`rgb(`/`rgba(`、写死的 14/8）、
  C（玻璃位置必须调 `backgroundBlurStyle` 且**只许一层**）。
- pi 指出的洞已补：裸色值判据原来只扫 `#RRGGBB(AA)`，抓不到 `rgba(`/`0xRRGGBBAA` ——
  而这几种恰是"改用系统材质"时最容易混进来的形态。现在四种一起扫，且**先剥注释**
  （注释里正当地引用旧写法不该被judged红）。
- pi 的 §5 建议也已落地：新增"版本库不得跟踪缓存/构建产物"判据（`.tmp/` 那次 554 个文件的事故判据化），
  并放行 `server/internal/static/static/placeholder.html`（go:embed 落点的有意占位，删了 Go 侧编不过）。

## 变异验证（能红，且红在对的地方）

| 变异 | 结果 |
|---|---|
| 品牌蓝 → 系统强调色 | 红 3 条 |
| 手写玻璃 `navBgLight` 回来 | 红 2 条 |
| 导航改用写死半透明色、不调 `backgroundBlurStyle` | 红 2 条 |
| 卡片上再开一层模糊 | 红 1 条（"玻璃应只出现在一处，实际 2 处"） |

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（10 个判据文件全绿：跨端 13 条、系统资源名 4 条、harmony-logic 19 条… + vitest 258/258）。
**未验**：观感（卡片间距、系统材质在导航条上的实际效果、深色模式）—— 需真机/模拟器；
模拟器要人在命令行跑一次 `harmony-emu start`。`sys.*` 名字全部对着 SDK 名表核过，且判据持续盯着。
 2026-09-14 14:04:04 +08:00
JianFeeeee
b041ea51e4 fix(harmony): 令牌收尾 —— 裸色值清零、遮罩拆两段式、权限档位配色对齐 WebUI 
接手核对时发现：「不许写死颜色」那条判据**只挡得住枚举的 8 个旧值** —— 判据全绿的
同期，pages/ 里还留着 14 处另一套写死的色（Google/Material：#E8F0FE、#E8F5E9、
#FFF3E0、#D93025、#777777×2、#555555、#444444、#cccccc、#aaaaaa、
遮罩 #80000000×2、透明 #00000000×2）。枚举挡不住漂移，只有"类"能挡。

## 改法

- 14 处全部换成令牌。新增 accentStrong / warnBg / warnFg（取值对齐 WebUI `:root`
  的 blue-700 / amber-50 / amber-700）与 `Theme.permBg/permFg` —— 权限档位徽标与
  WebUI 的 `PermissionChip.tsx` **同一映射**（plan=蓝 / workspace=绿 / full=琥珀）；
  原先写成 `full ? 绿 : 橙`（Material 色），与 WebUI **反着来**。
- 遮罩拆成 `overlayColor` + `overlayAlpha`（照 WebUI 的 `--bg-scrim` + `--bg-dim`
  两段式）：遮罩色要能随主题换向，色与透明度焊死成一个 `#AARRGGBB` 等于把枚举写回
  代码。ArkUI 只认单值，故由 `Theme.overlay()` 组装。
- 判据从"枚举旧值"改成"按类挡"：pages/ 下**一个裸色值都不许有**（含 8 位
  `#AARRGGBB`），页面清单从硬编码 7 个文件名改成**扫目录** —— 旧写法下，
  接下来要加的发件箱/授权/日历会自动逃出判据。另加一条判据：权限档位配色与
  WebUI `:root` 变量逐一比对，防"看起来差不多"。

## 验证

- 变异测试：往 `InboxPage.ets` 塞一个 `#E8F0FE` → 判据红；撤回 → 绿。
- cross-client 判据 6 → 8 条全绿；`hvigorw assembleHap` BUILD SUCCESSFUL。
- **视觉未验**（模拟器在本机文件沙箱下起不来，见 `docs/HARMONY-ALIGN-PLAN.md` 5.4），
  未写成"已完成"。
 2026-09-14 13:29:50 +08:00
JianFeeeee
5434bc9e4e feat(harmony): 对齐第一阶段 + 对齐计划文档（差距/分期/验收纪律） 
用户：「安排对齐」。

## 先量差距（不靠感觉）

鸿蒙侧的调色板与 WebUI **根本不同**：`#1A73E8`（Google 蓝）vs 品牌 `#2563EB`、
`#333333` vs slate-900 `#0F172A`、`#F5F7FA` vs `#F8FAFC`、`#FF4444` vs red-600…
共 217 处硬编码色值散在 7 个页面里。

功能面：鸿蒙是 收件箱/会话/联系人 三个 tab，**缺 发件箱 / 授权 / 日历 / 管理**，
也没有玻璃悬浮底栏、主题壁纸同步、Composer 共用组件。

## 第一阶段（已完成并可验收）

- `common/Theme.ets` 补齐文字/浅底/语义令牌，页面里的旧调色板**全量替换为令牌**
  （共 203 处），`hvigorw assembleHap` **BUILD SUCCESSFUL**。
- 判据：`cross-client-theme.test.mjs` 新增"鸿蒙页面里不得再出现旧调色板色值"
  （6 条全绿，含扰动自检）。这条防的是**新页面又随手写个"差不多"的颜色** ——
  漂移就是这么开始的，而此前没有任何判据会红。

## 计划文档：docs/HARMONY-ALIGN-PLAN.md

写清两件事，免得每轮重新猜"还差什么"：

- **差距表**（逐项，标出"缺页面/交互不同/观感不同"的性质）；
- **分期**：P2 发件箱（与收件箱同构，风险最低）→ P3 授权页（备注必须随决策送达模型
  —— WebUI 侧踩过这个坑）→ P4 主题/壁纸同步（服务端"无记录"时以本地为准）
  → P5 玻璃悬浮导航 → P6 日历（最大，单独排）。

## 如实说明

鸿蒙**视觉未验证**：本机 `hdc list targets` 为空、HAP 未签名 ⇒ 只能保证编译通过 +
令牌一致，观感需要设备或签名后由人眼确认。文档里也把这条写进"验收纪律"。
 2026-09-14 12:49:40 +08:00
JianFeeeee
f9d757b5e5 chore: directory migration - gateway→server, web→client/electron 2026-09-08 19:16:35 +08:00