jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
938 Commits 1 Branch 0 Tags
519bdf70938ee9417a5a9a3b939bc13906271e67
Commit Graph

30 Commits

Author SHA1 Message Date
JianFeeeee
18b148e476 跨端: fix(客户端) 换身份必须清全部账号数据 ＋ 鸿蒙管理台门禁改三态 
两份审查报告（`docs/reviews/electron-gui-review.md` /
`harmony-client-review.md`）里两条**数据隔离**缺陷。

## ① 换身份不清数据 ⇒ 在新账号的界面下显示旧账号的邮件

`setActive` 之后 `api/config` 单例里的 API_BASE 与 bearer 就翻到了新账号，
于是此后每个请求都带**新账号**的凭证。而各 store 里还留着**旧**账号的：
  · mailStore.sent / currentMail
  · sessionStore.sessions / currentSession / currentSessionMails
  · contactStore.contacts / archivedContacts

⇒ 肉眼完全看不出来（不报错、不空屏），而**从旧视图发出的写操作**
（归档 / 转发 / 批准权限）改的是**新账号**。

新增 `src/lib/resetAccountData.ts` —— **一处实现，三个入口都调它**：

    ① 主动切账号（AccountSwitcher.pick）
    ② 登出（authStore.logout）
    ③ 任意接口 401（api/client.ts 的 unauthorized 回调 → markAnonymous）

只在 ① 里清是最容易漏的那种做法：② 和 ③ 各自还会重新泄露一次，
而它们都不在切换账号的代码路径上，grep 也找不到。
**身份变化有三条路径，清空也该有三条。**

★ 只碰**数据** store；`uiStore` 的 reset 仍由 App.tsx 负责
  （它还要复位窄屏分栏、写信态那些纯界面状态）。

判据：`test/stores/resetAccountData.test.ts`（4 格）。

## ② 鸿蒙管理台门禁**失败开放**（fail-open）

`AdminUsersPage.ets` 原来的条件是 `roleKnown && !this.isAdmin`，
于是 `roleKnown === false`（loadRole() 失败、**身份还没读到**）
落进 else 分支 ⇒ **把完整管理台整个渲染出来**。
一次网络抖动 = 管理入口对所有人可见。

讽刺的是该文件自己的头注释写的就是正确规则
（「不能把读不到当成是管理员」）—— 代码做的正是这条注释禁止的事。

⇒ 改三态：`!roleKnown` 显示「正在确认身份…」、`!isAdmin` 显示墙、
  否则管理台。

服务端 `middleware/user.go` 的 `AdminOnly` 仍在，所以**不是越权**；
但非管理员会看到完整用户列表、建号表单、改密入口 ——
属于客户端信息泄露 + 无意义的失败请求风暴。
 2026-09-28 08:46:01 +08:00
JianFeeeee
65de1c3884 跨端对齐：授权栏 navigator_only + 组件按页拆分 + 服务器补 permission_options 
用户两项裁定落地（均为 ask_user 明确选择）：

① 授权栏口径 = navigator_only（照 WebUI 架构）
   · 新建 pages/PermissionPanel.ets —— 详情页的决策面板，
     对应 MailView.tsx:693 的 PermissionPanel（审批型 / 主动提问 / 已处理 三态）
   · 决策入口从授权栏移到 MailDetailPage；MailDetailPage 原来只显示一个
     「权限请求」小标签、根本没有决策入口（比 WebUI 少一整块，且反了：
     栏里能决策、点进详情反而不能）
   · PermissionTab 删掉内联「同意/拒绝」+ 备注框 + decide()：
     整卡可点 → onOpenMail（对齐 WebUI PermissionList.tsx:81 的 pick()）
   · PermissionRequest 补 source_account_id（客户端侧记来源，跳详情要定位网关）

② 服务器补 permission_options —— 修一条真实的、跨端共有的缺口
   · mails.permission_options 从 INSERT 起就写进去，但**从来没有任何读路径
     选过它** ⇒ 详情端点永远返回空。WebUI 的决策面板读 mail.permission_options，
     所以提问型的预设选项**两端全部落空**（审批型靠 ['同意','拒绝'] 兜底蒙混）
   · GetMailByID 补选该列 + JSON 反序列化（与 cc_list 同款）

③ 组件按页封装（用户要求「以便与 WebUI 一一对应」）
   MainPage.ets 4592 → 3192 行
   · pages/PermissionTab.ets    720 行  ↔ PermissionList.tsx
   · pages/ContactsTab.ets      796 行  ↔ ContactPanel.tsx
   · pages/NavDestinations.ets  181 行  ↔ Navigation 壳
   · pages/NavShared.ets         65 行  ↔ 跨栏共用件

④ 判据跟着组件搬家（否则静默失效，不是红）
   harmony-logic 的 pageCode / harmony-nav 的 navSrc 改为显式文件名单；
   harmony-appearance 的 PANE_SOURCES 补 ContactsTab；harmony-contacts 三个
   test 并入 ContactsTab；harmony-logic 的决策断言改指 PermissionPanel，
   并新增「授权栏不许再有内联决策」两条（navigator_only 的正形状）。

   animation-audit：共享元素转场判据从「同文件共址」改为「按 id 找驱动」。
   旧形状把 in/out 端必须在同一文件当成代理，而两端**天然在两处**；
   抽出写信页（NavDestinations 持有 in 端）后误报。新判据仍要求每个 id
   都有 Motion.morph 驱动 —— 变异实测：把驱动换成裸 animateTo 仍判红。

判据：files=34 checks=556 red=1（仅 build-stamp，产物待重构建）
 2026-09-24 10:10:32 +08:00
JianFeeeee
e6a4070a95 跨端: 把可读性那批深色语义底**登记进清册**（判据抓到了，它报得对） 
上一提交（`cbb1e1e`）给 `dangerBg`/`approveBg`/`warnBg`/`chipSpentBg`/
`chipWarnBg`/`chipNeutralBg` 补的深色变体，**忘了登记**。
`cross-client-theme` 当场报红：

    Theme.ets 里出现未登记的手写色：dangerBgDark、approveBgDark、warnBgDark、
    chipSpentBgDark、chipWarnBgDark、chipNeutralBgDark、chipNeutralFgDark、
    chipSpentFgDark、chipWarnFgDark
    —— 属于品牌/业务语义色就登记进 SELF_OWNED_COLORS 并在 Theme.ets 的
    登记表里写一行理由，否则该走 $r('sys.*')

**这条判据报得对**，不是误报：
  · 这 9 个色是**跨端身份**（逐字取自 WebUI `.dark` 段 `index.css:486-520`），
    系统语义色里没有\"淡底\"这一档，更没有深浅两套淡底 ⇒ 必须自己写；
  · 但\"必须自己写\"恰恰是要登记的理由 —— 不登记的话，
    下一个人看到 `#2E1F25` 只会当成随手挑的深红。

修（两处，判据要求两处都有）：
  1. `SELF_OWNED_COLORS` 补 9 个名字 + 一段理由（含 tailwind 档位对照）；
  2. `Theme.ets` 的色清册注释里补 9 行值 + 来源，并说明\"原来只有浅色档\"
     这个**共同的病根**（不是九个孤立遗漏）。

★ 教训：\"补了深色变体\"是一个**新 token**，不是\"改了个值\"。
  `cbb1e1e` 提交信息里我把它们写成\"Added dark variants\"——
  但在判据眼里它们就是 9 个没登记的手写色，跟\"随便写死的颜色\"无法区分。
  **判据不认识意图，只认识清册。**

验证：`cross-client-theme` 21/21 绿（原 20 pass / 2 fail）。
 2026-09-21 20:53:10 +08:00
JianFeeeee
cbb1e1ee62 跨端: 修「深色下玻璃变灰纸板」+「主题选了不生效」（两个真 bug） 
用户问「你的玻璃效果呢？」。我上手先取像素，结果是**两个一直存在的真 bug**，
不是观感偏好问题。两个都有实测数据。

## ① 深色下玻璃 alpha 没跟着翻 →「像深色卡片浮在灰纸板上」

### 实测

深色主题 + aurora 壁纸，同一行交替采样（`/tmp/g1.raw`，1008×2232）：

    y=670   卡片缝隙 rgb(199,199,199)   卡片内 rgb(27,37,50)
    y=880   卡片缝隙 rgb(201,203,201)   卡片内 rgb(27,36,53)

缝隙是**浅灰 199**、比卡片还亮。而 199 恰好 = `0.78 × 255`
（壁纸层实测 x=4..24 为 rgb(0,1,3)，近黑）—— 就是 `glassCardWall` 那层白纱。

### 根因：我把 WebUI 的一句话读漏了后半句

`Theme.glassCard` / `glassCardWall` 是**单一值、不分深浅**。我当初写的理由是
「基色恒为白，主题之间只差 alpha」——但 WebUI 原话是
「**基材恒为白**，主题之间**只差 alpha**」（`index.css:406`、`:1546`）。
我只抄了前半句，把「只差 alpha」误读成「alpha 也不用变」。

WebUI `.dark` 的实际取值：

    --glass-card-a:      0.06     ← 浅色 0.92
    --glass-card-wall-a: 0.04     ← 浅色 0.78

**深浅差 15 倍**：深色下白纱要几乎撤掉让深壁纸透上来，浅色下才用厚白纱盖亮壁纸。
我用同一个 0.92 配两套主题 ⇒ 深色下壁纸被糊成浅灰，**玻璃感与深色同时消失**。

### 修法

`Theme.glassCardFor(wall, dark?)` —— 与 `accentFor`/`textSubtleFor` 同一范式，
深浅从 `Theme.isDarkNow()`（`AppStorage` 那个发布键）读，不靠调用方自觉传。
新增 `glassCardDark #0FFFFFFF` / `glassCardWallDark #0AFFFFFF`。

改后同处实测：缝隙 rgb(3..16)，壁纸透上来了；浅色档回归检查未变（244/239，厚白纱仍在）。

## ② 用户选的主题被无条件覆盖 →「选了深色但界面还是浅的」

### 实测

「我的」页选「深色」后：
· 按钮显示选中、服务端也记下 `theme:'dark'`（`GET /me/appearance` 确认）；
· 但界面仍浅色，且文字浅色压浅底 —— 实测背景 `rgb(243,243,243)` /
  文字 `rgb(243,243,243)`，**对比度 ≈1.0:1，完全不可读**。

### 根因（两处叠加）

① `EntryAbility.onCreate` 有一句**无条件**的
   `setColorMode(COLOR_MODE_NOT_SET)`（= 跟随系统）—— 每次冷启都把用户的选择重置掉。
   它是目录迁移时抄进来的（`git log -S` 指向 `f9d757b chore: directory migration`），
   **没有注释说明为什么，也没有谁在用**。已删除（连带上游 import）。

② `MainPage.applyAppearance()` 算出了 `isDarkNow`、发布了 `AppStorage`，
   但**从来没调用过 `store.applyTheme(...)`** ⇒ 系统色彩模式根本没被设过。

### 修法

· 删掉 EntryAbility 那句无条件覆盖（附长注释说明为什么由页面负责）；
· `applyAppearance()` 补上 `store.applyTheme(ctx, snap.theme)`。

★ **顺序**：`KEY_IS_DARK` 发布必须在 `applyTheme` **之前** ——
  因为 `glassCardFor()` 是从那个键读深浅的，反过来会让卡片用上一轮的深浅画一帧。
  `applyThemeNow()` 里同一处顺序也一并修正。

## 判据

`cross-client-theme` 的两条原本把 `Theme.glassCard`/`glassCardWall` 两个**字面量**钉死，
被我这次正确的改动撞红 —— 我没有放宽它们，而是改成钉**行为**：
· 卡片必须经 `glassCardFor(...)` 取色（入口存在）；
· 四个令牌都要在 Theme 里存在；
· **深色档不得与浅色档同值**（同值 = 主题感知是假的）。

变异验证：① 深色档改回与浅色同值 → 3 条红；② 卡片改回不分深浅 → 5 条红；还原 → 21/21 绿。

## 验证状态

✓ 两个修复都在设备上取**像素**验证（不是看截图说"像了"）
✓ `cross-client-theme` 21/21、全量套件 545 pass（3 红均为改动前既有：
  `harmony-admin` 两处 = 我上一轮 `SecuritySection` 拆分遗留、`build-stamp` = 产物戳过期）
✓ 编译通过、进程存活、无新 jscrash
 2026-09-21 18:46:19 +08:00
JianFeeeee
125aec1191 跨端: 2in1 键盘可达（Ctrl+N 写信 / ↑↓ 换补全 / Enter 选中）+ 三处判据被实测改判 
用户 2026-09-21：「接下来做一下 2in1 上的快捷键，比如快捷键打开发信页面」
「上下键切换发信目标」「回车展开输入框等」

## ① 打开发信页：Ctrl+N，用官方 `keyboardShortcut`

先查了官方文档再动手，避开两条静默失败的坑：

  · `keyboardShortcut`（组件快捷键事件，API 10+）「**无论组件是否获焦** ——
    只要窗口获焦，快捷键就会响应」。而 `onKeyEvent` 要求**组件先获焦**，
    邮件列表里焦点落在哪是不确定的（点一下就换）⇒ 用它做全局快捷键会时灵时不灵。
  · 「多个不同组件设置相同组合键 ⇒ 只响应节点树**深度最浅**的那个」。
    ⇒ 再给别处的"写信"按钮补一个 Ctrl+N 不是"多一个入口"，而是**让后来那处永久失效**。
    判据因此钉"全仓只许绑一处"。

绑定位置在 `MainPage` 的**根 Stack**（窗口组件树的根）—— 绑在 FAB 上不行，
它在 `if` 分支里、窄屏/宽屏位置也不同，会随分支挂卸。

键位 `Ctrl+N` 避开了官方列出的五个**禁止绑定**组合（Alt+F4/Alt+Tab/Ctrl+Shift+Esc…）。
判据直接解析调用参数校验这三点。

## ② 根够不着 `openCompose()` ⇒ 照 `PushService` 的"两半"形状

`openCompose()` 住在**条件挂载**的 `CommPage` 上（`if (currentIndex === 0)`），
根组件拿不到它。新建 `common/ComposeIntent.ets`：

  · **格子**（`pending`）—— 用户此刻在别的页、`CommPage` 还没实例化；
  · **回调**（`listener`）—— 用户此刻就在通信页、页面早挂载完了。

缺任何一半都是**按键静默失效**：只有格子 ⇒ `aboutToAppear` 不重跑；
只有回调 ⇒ 没有监听者。这形状与 `api/PushService.ets` 处理"点通知跳转"时
踩的是同一个坑，那边注释里已写过解法 —— 这次是照着抄，不是重新踩。

## ③ 收件人三段式补全（↑↓ 切换、Enter/Tab 选中、Esc 收起）

WebUI 的逻辑原先**散在组件闭包里**（`parseParts` 没 export、`apply`/`onKeyDown`
直接改 React state）⇒ 判据根本 import 不到。先把它抽成一对纯逻辑：
`client/electron/src/lib/addressSuggest.ts` ↔ `model/AddressSuggest.ts`，
**抽的时候行为一字不改**（抽出来顺手"改进"会让判据比新行为、线上跑旧行为，两边都错）。
`AddressInput.tsx` 改接这份 lib。

`cross-client-logic` 新增 `AddressSuggest` 一对，22 个用例两边逐例比。
其中 `nextActiveIndex(0,3,-1)` 是**负下标陷阱**：JS 的 `%` 对负数返回负数
（`-1 % 5 === -1`），而负下标在数组访问里**不报错**（返回 `undefined`），
只表现为"按上键后没有任何一项高亮"。直接写 `(i-1) % n` 就会这样静默坏掉。

候选走**内联渲染**而不是 `bindPopup`/`bindMenu`：那两者各有焦点体系，
会先吃掉按键 ⇒ "↑↓ 换候选"落不到 `onToKey` 上。

## ④ 另修一个真 bug：`AddressSuggestion` 字段名整套写错

模型声明 `value`/`kind`，而服务端（`contacts.go:206`）给的是 `alias`/`title`/`source`
—— **从来没返回过** `value`/`kind`。按本仓纪律「声明了服务端从不返回的字段 ⇒ 删掉声明」改正。

顺带守住 `title` 的 `omitempty`：缺键时裸 cast 给 `undefined`（**不是**类里那个 `= ''`），
直接读会 `Cannot read property of undefined` —— 本仓在 `MailDetail.normalize()` 上
踩过同一形状（整页白屏）。判据钉住那句 `typeof … === 'string'` 的守。

## ⑤ 三处判据被**实测**改判（不是我挑一边，是拿数字定的）

### a. 卡片不该有模糊 —— 反转原断言
原判据断言「玻璃卡要走参数化 `backgroundEffect`」。那是**记录旧实现的副作用**
（重言式）。逐字读 WebUI 的 CSS：全仓 `backdrop-filter` **只有两处**
（`.glass-control` 8px/1.1、`.narrow-nav` 18px/1.5），而 `.glass-card`（`index.css:1629`）
**完全没有** —— 它的玻璃感是 `rgb(255 255 255 / 0.92)` 这个 alpha。
留着旧断言更坏：下次谁把卡片改成正确的"白 + alpha"会被判红，然后去**把模糊加回来**。

### b. 我试了"把模糊移到导航条"，被实测否掉
推断「真归属是底栏」，于是把底栏改成 `backgroundEffect({radius:18, saturation:1.5})`。
实测（模拟器窄屏 1008×2232，底栏中心列 x=504）：

    y      backgroundEffect        backgroundBlurStyle
    1960   rgb(191,199,209)        rgb(234,235,239)      ← 差 -36 亮度
    2060   rgb(206,211,219)        rgb(234,235,239)      ← 差 -24

⇒ `backgroundEffect` **只给模糊、不给底色**，壁纸原样透上来，底栏暗了 24~36 级。
WebUI 的 `.narrow-nav` 是**两条声明**组合的（`background-color` + `backdrop-filter`），
我只搬了后者。系统材质**同时含色调 + 模糊 + 深浅两套** ⇒ 在这里它才是正解
（§7.12 把它判成"有意差异"是对的，我的"改进"是退步）。
判据改成**反向钉住** `backgroundEffect`，并把这段实测数字留在 Theme.ets 里。

### c. 页签条判据记录的是被否掉的"胶囊"
原判据钉 `TAB_BAR_RADIUS`/`TAB_BAR_SIDE`/`TAB_BAR_TOP` —— 那正是用户否掉的形状
（「你又在内部套了一个胶囊」）。CDP 读 WebUI 的实测几何：

    .comm-pane   x=80 w=320 radius=14px overflow=hidden   ← 窗格，裁圆的是它
    tabstrip     x=80 w=320 radius=0px                    ← 条自己无圆角

设备实测（`uitest dumpLayout`）：页签条 `[28,140][980,267]`、窗格 `[28,140][980,1957]`
⇒ 左右边缘逐像素相同。判据改为钉"与窗格齐平 + 只有左上角圆角"这两条**不变式**，
`TAB_BAR_RADIUS`/`TAB_BAR_SIDE` 一并**删除**（留着就是孤儿，会邀请人把胶囊拼回来）。

## ⑥ 顺带修两条判据自己的正则
`{6}` 看不见 8 位色 ⇒ 把 `glassCard`/`glassCardWall` 报成"清册过期"，
**病因报错了**。改成 `{6}(?:[0-9A-Fa-f]{2})?`（不能写 `{6,8}`，那会连 7 位也放进来）。
半透明禁令改为**枚举白名单**（不是放宽：遮罩那个真实约束原样保留，
`overlay` 写成 8 位单色照样红）。

新增判据 `harmony-2in1.test.mjs` 12 条；`files=34 checks=543 pass=540 fail=2`（收尾前）。
 2026-09-21 13:29:24 +08:00
JianFeeeee
d9bb4f766b 跨端: 三条判据转绿（登记新令牌 + 把一条断言错实现的判据改成断言真不变式） 
上一步（写邮件右栏）之后整套跑红 3 条，逐个查清：

══ ① cross-client-theme —— 判据是对的，我漏登记

新加的 `accentEdge` / `accentEdgeDark` 是**手写色**，而这个仓有一条硬规矩：
`Theme.ets` 里每个 `static readonly X: string = '#……'` 都必须在
`SELF_OWNED_COLORS` 名单里 + 在文件内的「手写色登记表」注释里写一行理由。
（这条规矩本身就是为防"新写死一个色悄悄溜过去"而立的 —— 第二处断言
 会检查名单里没有化石名，所以名单不能只加不改。）

按规矩补两处：
· 名单里登记，并写清它对齐的是 WebUI 的哪个 token
  （`MailList.tsx:280` 的 `border-blue-200`，与 `bg-blue-50` 成对）
· `Theme.ets` 登记表里写一行理由 —— 重点记下**为什么"选中"必须两个 token**：
  选中与未读的底色相同（都是 `accentSoft`），只靠底色的话
  "选中一封未读邮件"看不出任何变化，那圈边才是信息。
  并把表头计数 24 → 26 同步改掉。

══ ② harmony-widescreen —— 判据错了，它断言的是一个 WebUI 明令禁止的实现

原断言：`assert.match(code_, /clip\(this\.isWide\)/, '面板内容要被圆角裁剪')`
—— 它把"圆角"和"裁切"当成**同一件事**。而 WebUI `index.css:968`
在**同一个规则块**里就写明了这条教训：

    .app-shell > * {
      border-radius: var(--radius-card);
      // ★ 这里**不能**写 overflow: hidden（2026-09-14 用户：
      //   「通信页面完全无法上下滑动」）。
      // 面板自己就是滚动容器，而这条规则的特异性比 Tailwind 的 .overflow-y-auto
      // 高 ⇒ 滚动被静默干掉：实测当时**一个可滚动容器都不存在**（scrollerCount=0）。
      // 圆角仍然生效（border-radius 不影响滚动）

鸿蒙这边同一个形状：那层是内容列的根、`Navigation` 的 `List` 在它里面，
写了 `.clip(this.isWide)` 就是 `List` 节点还在（高 1750px）但**滚不动**
（实测 fling 后第一封仍在 y=526）——这正是用户当时报的"列表没法滚动"。

⇒ 判据改成断言**真正的不变式**：宽屏「圆角开（14）+ 面来自设计令牌 +
**不写** `.clip(this.isWide)`」。原来那句测的是"某句实现写着没写着"，
而且那个实现是错的 —— 判据跟着错误实现一起钉住了 bug。

══ ③ build-stamp —— 判据要求重构建，照做（**没有**去改 BUILD_INFO.json）

产物记的是 `c0ab3f5`，HEAD 已是新提交。这条判据自己的文本写得很清楚：
> **别去改 BUILD_INFO.json 里的 gitRev / srcHash 了事** —— 那是把这条判据废掉。
> 正确修法只有一个：重跑构建。

所以 `npm run build` 重跑（rev 0）。注意 srcHash 本来就没变
（`6d1195a4008ebca7`）—— 因为 TRACKED 只扫 electron 侧（`src`/`index.html`/
`vite.config.ts`/…），我这几步改的全是 harmony；**变的只有 gitRev**。
这正说明这条判据在比对"产物来自哪个提交"，而不是"文件内容有没有动"。

★ 三条各自的性质不同，值得分开记：① 是判据对、我漏登记（补）；
② 是判据错、钉住了一个反向实现（改判据）；③ 是判据对且给了唯一正确修法（照办）。
 2026-09-20 13:05:59 +08:00
JianFeeeee
eb4e413c67 跨端: 玻璃走基础组件（透明度/磨砂/投影）+ 判据去芜存菁（修 4 个判据自身缺陷） 
用户两条：「玻璃不透明/不够磨砂炫酷，要更基础组件化」＋「判据去掉无意义的、保留有用的」。

★ 玻璃的透明度与质感（逐层调出来的，不是拍的）
  · 透明度：`BlurStyle` 是固定档、没有 saturate 旋钮 ⇒ 观感偏灰。
    改用参数化 `backgroundEffect({ radius, saturation })`，字段与 CSS `backdrop-filter`
    一一对应，于是可以**照抄 WebUI 的数**：`blur(18px) saturate(1.5)`
    （WebUI `.narrow-nav`，那里最"玻璃"的一档）。**saturate 才是玻璃感的主要来源**。
  · 质感：只模糊+饱和仍然"像一块平的白方块" —— 玻璃板之所以像板靠的是**边缘**。
    WebUI 的完整配方是 `box-shadow: 0 8px 28px rgb(0 0 0 / 0.16)` + 发丝描边。
    只有模糊没有投影 ⇒ 一片雾；加上投影 ⇒ 一块板。**这是"不够炫酷"的主因**
    （我先前两个方向都调了模糊与饱和，方向就偏了）。
  · 投影用**系统预置档** `ShadowStyle.OUTER_FLOATING_SM`（"浮起的小面板"），
    不是手写 `{radius, color, offsetY}` —— 手写色要么是 `#AARRGGBB`、
    要么是 `rgba()`，两者都被判据明令禁止，而那条禁令**是对的**：
    手写阴影色在深色下看不见（深底叠深影 = 无变化），WebUI 在 `.dark` 里
    要把同一处从 0.16 加重到 0.55 —— 那正是"替系统猜深浅"。

★ 基础组件（用户：「定义一个基础玻璃容器给各个组件引用」）
  · `GlassCardModifier` / `PaneModifier`（`AttributeModifier<CommonAttribute>`）：
    **一处定义、处处引用**。页面里的玻璃从 15 处内联三连收敛成
    `.attributeModifier(...of(this.bgActive))`。
    ★ 为什么不是 `@Styles`：全局 `@Styles` 读不到 `this`（而玻璃要知道 `bgActive`）；
      成员级 `@Styles` 能读 `this` 但**每个 struct 各一份**，MainPage 有 7 个 struct
      ⇒ 只是把"每处抄 3 行"换成"每 struct 抄 1 份"，没解决问题。
  · `Motion.dur()`：接系统「减弱动态效果」（`isAnimationReduceEnabledSync()`，API 23）。
    WebUI 有 `prefers-reduced-motion` 硬约束，鸿蒙这边**改造前一次都没调过**。

★ 途中撞出并修掉的**真 bug**（都是我自己的）
  · 把 `@Styles glassCard()` 里也替换成 `attributeModifier` ⇒
    「我的」页 ProfileSection/AppearanceSection/PushSection **整块不渲染**
    （设备实测：Scroll 直接跳到「客户端连接密钥」）。删掉那个死 `@Styles` 即恢复。
  · `Theme.shadowColor/hairline` 用了 `rgba()` + `#AARRGGBB` ⇒ 违反本仓两条既有禁令
    （"鸿蒙侧不写 CSS 颜色函数"、"半透明属于系统材质/职责"）。改用系统阴影档。

★ 判据去芜存菁：修了 4 个**判据自身的缺陷**（都是它声称在管、实际漏判/误判）
  · 材质来源只扫 `backgroundBlurStyle` —— 玻璃改成 `backgroundEffect` 后**整类漏判**。
    实测：往 Modifier 里塞 `backgroundEffect({radius:99,saturation:9.9})` 照样全绿。
    ⇒ 补上这一类，并加"参数必须引 Theme 令牌"（否则只是换个旋钮写死）。
  · 参数抽取用 `[^)]*` —— 对 `this.materialOf()` 与 `{...}` 对象字面量都提前截断，
    **误伤合法写法**（本次被它误红两次）。改成配对括号 + 去外层花括号。
  · 嵌套判定**没比文件**：拿 A 文件的字符偏移去比 B 文件 ⇒ 判出
    "MainPage 内含 SettingsPage 的玻璃"这种物理上不可能的红。
    假红比漏报更坏 —— 会让人去改本来对的代码（本次差一点）。
  · `harmony-appearance` 数的是**内联字面量**（"三元出现 ≥5 次"），
    收敛成组件后写法变了、行为没变却变红 ⇒ 改成判不变式
    （让位只有一条路径 + 每个窗格都收到开关）。
  · 顺带：设备判据找「背景」时只在首屏可见节点里找（而 dumpLayout 只给可见节点），
    且我的第一版只朝一个方向滑（越滑越远）⇒ 改成"先回顶、再逐屏向下扫"。

判据：files=32 ran=32 checks=518 pass=518 fail=0 red=0；baseline 7/7✓（第 7 次，逐个取证）。
 2026-09-20 08:16:10 +08:00
JianFeeeee
5103e0aee3 跨端: 抽出基础面/玻璃组件（Motion + Surface）+ 三处硬弹的弹层补过渡 
用户两条要求，各自都指向"决策被复制到各处"这个病根：
  ① 「应该定义一个基础玻璃容器给各个组件引用」
  ② 「很多页面还是不够精致……封装为基础组件供所有页面使用。基础组件包含动画」

★ 玻璃不透明的真根因（前几轮都没找到，这次是像素证据定的）
  实测模拟器 3184×2232、壁纸 aurora + 压暗 37：
      Navigation [229,140,3156,2204]   ← 255,255,255（整块内容区）
      y=2210（Navigation 之外那条缝）    ← 226,225,235（壁纸清楚可见）
  那条缝是决定性的：**壁纸层本身是好的**，白是因为上面盖了不透明的壳。
  链路上一共三层，逐层修：
    · `Navigation` 外壳：不设背景 ⇒ 系统默认不透明白，把里面已透明的窗格整片盖住；
    · navBar 内容层（列表栏根容器）：同样没有背景；
    · **卡片**：铺的是 `Theme.surface`（实体系统色）。
  修后：缝隙 203,213,228 / 卡片 191,204,220 —— 壁纸透得出来。

★ 新增基础组件（common/）
  · `Surface.ets`  —— `GlassPane`（正文面）/ `GlassCard`（嵌套面）/ `PageHeader` / `Pressable`
  · `Motion.ets`   —— `Motion.dur()`：接系统「减弱动态效果」
    （`accessibility.isAnimationReduceEnabledSync()`，API 23 正好够用）。
    WebUI 侧有 `prefers-reduced-motion` 硬约束（index.css:1266），
    鸿蒙这边**改造前一次都没调过** —— 系统里关了动画，我们照样动。这是无障碍义务。
  · `Theme.cardMaterial` —— 卡片材质令牌。不是拍脑袋选的：
    `COMPONENT_THIN` 实测卡片 252,254,254（吃掉 94% 壁纸，就是用户看到的"白卡"）；
    `BACKGROUND_THIN` → 185,190,201，壁纸透得出来且文字对比度仍够。

★ 判定形状按"玻璃从例外变成默认"重写（判据 C 条）
  原来是"允许出现玻璃的位置"白名单，逐处登记。那个形状在"玻璃是少数例外"时成立，
  但用户要的是**全部玻璃化** ⇒ 白名单退化成"把每处抄一遍"，且挡不住新写的裸枚举。
  改成**规则**：材质档次只能来自 `Theme.navMaterial` / `Theme.cardMaterial`
  （或 `BlurStyle.NONE`），页面里出现裸 `BlurStyle.XXX` 即红；
  辅助方法（`this.materialOf()`）体内也查，否则等于开了后门。两条变异都验证咬得住。

★ 判据 C 条自身的两个 bug（都被本次触发）
  · 嵌套判定**没比文件**：`c.at`/`o.at` 是各文件自己的字符下标，直接比大小
    于是判出"MainPage 内含 SettingsPage 的玻璃"这种物理上不可能的红。
    假红比漏报更坏 —— 会让人去改本来对的代码（本次差一点）。
  · 参数抽取用 `[^)]*`：`this.materialOf()` 里含一层 `()`，在内层括号处截断，
    把合法写法读成 `this.materialOf(` 判红。改成配对括号抽取。

★ 出现/消失动画：用户点名的三处硬弹
  这些挂在 `if (cond)` 上，条件一变整块出现/消失，原来一帧过渡都没有 ——
  而代码上"看着像挂了动画"（外层页面有 transition），所以最容易漏。
  · `MainPage` 账号选择器下拉 → `menuIn()`（从上往下落的浮层档）
  · `AdminUsersPage` 新建用户表单 → `paneRiseIn()`（就地展开档）
    ★ 过渡必须挂在**调用点的 Column**：`@Builder` 返回 void，链不上修饰符。
      第一版写进了 `CreateForm()` 内部，是新判据抓出来的。
  · `SettingsPage` 新增账号弹层 → `paneRiseIn()`（与回复/转发弹层同一挂法）
  新增判据「出现/消失的那类元素真的挂了过渡」：**枚举所有条件挂载的浮层/展开块**
  （不是数数 —— 数数挡不住"新增第四处又漏了"），变异验证过。

★ 顺手修的两处真嵌套玻璃
  `SettingsPage` 的账号列表与密钥列表都是"卡里面的一段列表"，两层都铺材质 =
  WebUI 用 `.bg-white .bg-white { backdrop-filter: none }` 明确禁止的嵌套
  （alpha 相乘 0.82×0.82=0.97 把壁纸吃光）。去掉内层材质，玻璃只留一层。

★ 判据放宽一处（不是放水）
  `harmony-contacts` 那句写死 `pushUrl`，判的是"tryRestore 有没有跳转"，
  与用哪个原语无关。修 LoginPage 返回栈时改成 `replaceUrl` 后它误报了；
  改成 `(pushUrl|replaceUrl)`，原语该用哪个由 `harmony-nav` 那条专门判。

判据：files=32 ran=32 checks=518 pass=518 fail=0 red=0；
baseline 7/7✓（第 6 次重算，两个文件逐个 `git diff --quiet HEAD` 取证为有意编辑）。
 2026-09-20 07:37:16 +08:00
JianFeeeee
110de79401 跨端: 三级文字**浅色也一样不够**（12 处 2.85:1）+ 判据不再只验一半 
## 一、这是"我自己推的理由"被实测推翻

上一条我把 `textSubtleFor()` 写成**只改深色**，理由是：

> 「浅色下这些令牌本来就是为浅底配的，量它们没有信息量」

**那个理由是错的。** 切到浅色主题复扫，立刻抓到 12 处：

```
"用户名 / 显示名 / 角色 / 状态 / 创建时间 / 最后登录"  2.85:1
"已同步" / "37%" / "3px"（外观区）                    2.85:1
"这一天没有日程"                                      2.85:1
```
`ink rgb(153,153,153)` 压白底 —— 全是 `textSubtle`。

对照 WebUI 浅色（`index.css` `:root`）：
- `gray-400` = `107 114 128` = **4.83:1**
- `gray-500` = `90 98 112`  = **6.15:1**

⇒ 系统三级色**两个主题下都不够**。它的语义只是"比二级更淡"，
**不保证任何可读性下限**；WebUI 那边两套主题都做过适配，这边一档都没有。

修：`textSubtleFor()` 两个主题都返回 `textMuted`
（系统二级色，语义就是"次要文字"，且**跟随主题** ——
不必再维护两个手写常量、不必登记）。

## 二、判据从"只验深色"改成"两个主题都验"

原来那条设备判据**在浅色下直接 skip**，skip 的理由正是上面那句错话。
现在两个主题都扫，断言消息里带上主题名（`深色主题下…` / `浅色主题下…`）。

★ 纪律：**色令牌的可读性是两个主题各自的事，不能只验一半。**
  "另一半没问题"若没量过，就只是推测。

**变异验证**：把 `textSubtleFor()` 改回"两主题都用 textSubtle"
（此时设备正在浅色主题）⇒ **判红**；还原 ⇒ 绿。

## 三、设备复扫（浅色主题）

```
[通信]   扫 41 段，低对比 0
[日历]   扫 84 段，低对比 0
[联系人] 扫 50 段，低对比 0
[我的]   扫 40 段，低对比 0
```
**215 段文字全部 ≥3:1。**

两个主题合起来：深色 219 段 + 浅色 215 段，全绿。

## 四、顺手改掉的

测试名从「深色下短文本必须都读得动」改成「**当前主题**下…」
—— 名字得跟着它实际判的东西走（否则下一个人会以为它只管深色）。

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

**当前设备主题**：浅色（本轮为验另一半切过去的；服务端 `theme=light`）。
 2026-09-19 20:58:59 +08:00
JianFeeeee
1da4e15a7b 跨端: 补齐「我的」页深色可读性（4 页 219 段全 ≥3:1）+ 判据自己漏报的那一类 
上一条把通信/日历/联系扫干净了，但**「我的」页没扫到**
（扫描脚本按文案点不到它 —— 那是侧栏**底部的头像按钮**，不是导航项）。
补上后立刻又抓出问题，并把判据自身的**漏报形状**一并修了。

## 一、「我的」页两处真 bug

1. **主题分段按钮 `SettingsPage.ets:834`**：
   `.fontColor(... ? Theme.surface : Theme.textPrimary)` —— `surface` 是
   **会翻转的面色**，压在 `Theme.accent` 蓝底上，深色下变成近黑。
   设备读数：`深色 2.93:1  ink rgb(32,34,36) bg rgb(34,96,228)`。
2. **权限档徽标 `MailDetailPage.ets:391`**：同一个错法（第 13 处）。
3. **账号名 `SettingsPage.ets:1179`**：三元里的裸 `Theme.accent`
   压在 `accentSoftFor()` 底上 ⇒ `jianf 2.83:1`。
   `AdminUsersPage.ets:386` 同形状（角色徽标）。

## 二、判据自己的漏报形状（比 bug 本身更值得记）

静态防线（`C｜会翻转的 Resource 不得当前景色`）**在 bug 存在时是绿的**。
原因是它的提取正则：

    /\.fontColor\(Theme\.([A-Za-z0-9_]+)\)/      ← 要求令牌是**唯一实参**

于是**三元里的令牌全被漏掉**：

    .fontColor(this.appearanceTheme === t ? Theme.surface : Theme.textPrimary)

改成"在 `fontColor(` 之后的整段实参里找所有 `Theme.X`"之后，
它**立刻报出上面第 1、2 两处**（此前一直绿）。

★ **判据漏报的常见形状是它自己的正则太窄，而不是被测代码太隐蔽。**
  这条写成注释留在判据里了。

## 三、我自己犯的批量替换错误（已加判据钉住）

把裸 `Theme.accent` 换成 `accentFor()` 时，**误把 6 处 `backgroundColor` 也换了**。
`accentFor()` 深色给浅蓝 `#80AFF9`，而搭档前景是白色 `accentFg`
⇒ 白字压浅蓝 ≈ **1.4:1**，主按钮文字会彻底看不见。

- 6 处已逐处还原（复核：`grep -c "backgroundColor(Theme.accentFor())"` = 0）。
- 新增判据 **`C2`**：`accentFor / dangerFor / approveFor / warnFgFor / textSubtleFor`
  **只能用于前景**，`backgroundColor(Theme.XFor(...))` 直接判红。
  （`accentSoftFor` 是例外 —— 它本来就是"面"。）
  ★ 修法不是"下次小心点"：批量替换一定会再犯，**一行判据把它变成不可能**。

## 四、设备复扫（修后）

```
[通信]      扫 42 段，低对比 0
[日历]      扫 85 段，低对比 0
[联系人]    扫 51 段，低对比 0
[我的]      扫 41 段，低对比 0      ← 新增
```
**219 段文字全部 ≥3:1**（本轮全部针对深色）。

## 五、底本

`baseline.sha` 第 5 次重算。重算前**专门复核**了"那 6 处误改有没有残留"
（不只看 `git diff` 非空就放行）：`backgroundColor(accentFor)` 计数为 0、
`git diff HEAD~1` 里 backgroundColor 只有 calendar 那一处（有意改动）。

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

**未验**：浅色主题下的对比度没扫（本轮全部针对深色）。
 2026-09-19 20:43:59 +08:00
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
3123d83979 判据: 把「面当字」的防线从死名单改成判矛盾（三次迭代都记下来了） 
上一版加的静态防线只 grep `fontColor(Theme.surface)` —— **一个名字**。
那是死名单：以后加了新令牌它不会跟上（本仓已记录过多次这类错法）。

改成从源码推：
  **条件 A**：值是 `Resource` 且指向 `sys.color.*` ⇒ **跟随系统主题翻转**
  **条件 B**：既当 `backgroundColor` 又当 `fontColor/iconColor` ⇒ **被当成「面」也被当成「字」**

判决 = **A ∩ B**，不需要维护任何名单。

## 三次迭代（每次错得很典型，所以都写进注释了）

- **① 死名单**（只盯 `surface`）：新增令牌不会跟上。
- **② 只要 A**（"是翻转的 Resource 就不许当前景色"）：**太宽** —— 实测立刻
  报出 20+ 处"违规"，全是 `textMuted` / `textSubtle` / `textPrimary`。
  那些**本来就该**当前景色（语义就是文字色，跟随主题翻转是对的）⇒ 假红一片。
- **④ 只要 B**（"矛盾就报"）：**也宽** —— `accent` / `danger` / `approve` / `warnFg`
  两边都用是正常设计（蓝底白字主按钮 + 白底蓝字返回箭头）。
  和 `surface` 的**关键区别**：那些是**饱和的字符串常量**（不翻转、语义是"色"），
  而 `surface` 是**中性面 + 跟随主题翻转**（当字色 = 把底板当墨水，深色下必然看不见）。
- **最终 = A ∩ B**：恰好命中 `surface` 这一类，且**不随新增令牌失效**。

允许清单现在是**空表**（修完 `surface` 后没有例外），
并写明「已审过、不需要进这张表的」那几个令牌与理由。

## 变异验证（两个都做了，第二个是关键）

1. 把一处 `.accentFg` 改回 `.surface` ⇒ **判红**；还原 ⇒ 绿。
2. **造一个判据从没见过的新令牌**（`surfaceAlt`，同样 `Resource` + `sys.color.*`），
   让它同时当背景与前景 ⇒ **判红**（报文里点名 `Theme.surfaceAlt`）；还原 ⇒ 绿。
   —— 这条比 ① 重要：它证明判据**不是靠记住 `surface` 这个名字**在工作。

## 顺带确认

`pageBg` / `surfaceMuted` / `wallpaperScrim` / `border` / `overlay` 这五个
同类"会翻转的面"**一处都没被当字色用过** —— 这一类现在全清了。

`run-all.mjs` → `checks=513 pass=513 fail=0 skip=0 red=0 broken=0 unreported=0`。
 2026-09-19 19:39:02 +08:00
JianFeeeee
21132647bc 跨端: 12 处「深色下字看不见」的真 bug + 判据基建补上「看像素」这一层 
## 一、判据基建：本目录终于能**看像素**了

此前只能靠 `dumpLayout` —— 那是**结构化描述**，报的是"组件声明了什么"，
不是"屏幕上画成什么样"。两者会分叉，而观感类结论只能在像素上得出来。

新增 `lib/harmony-device.mjs`：`screenshot()` / `pixelAt()` /
`hexToRgb()` / `closeColor()`（用 ffmpeg 转 1×1 原始 RGB，不引依赖）。

**它当场证明了它的价值**：`cross-client-theme` 新增的设备判据
用真实像素抓到下面这个 bug —— 静态判据全绿时它藏得好好的。

## 二、真 bug：**12 处**把 `Theme.surface` 当前景色用

`Theme.surface` 是 `sys.color.ohos_id_color_list_card_bg` ——
一个**跟随系统主题翻转**的 Resource：浅色近白、**深色近黑**。

- 浅色下当白字用**碰巧对**（白字压蓝底）
- **深色下字变成黑的**，压在品牌蓝 / danger 红 / warn 琥珀上**几乎看不见**

设备现场：写邮件悬浮球是品牌蓝 `#2563EB`，截图里那个铅笔图标**几乎是隐形的**；
读圆心像素得到 `rgb(32,34,36)`。往左偏 50px 读到底色才见 `rgb(36,99,235)`。

`Theme.accentFg`（`#FFFFFF`）的注释原话就是「品牌底上的文字」—— 为这个场景存在，
却**一处都没用**。

修：12 处 `fontColor/iconColor(Theme.surface)` → `Theme.accentFg`
（`MainPage` 10 + `InboxPage` 1 + `SessionsPage` 1）。改完全仓 0 处残留。
另在 `Theme.ets` 给 `surface` / `accentFg` 都补上"能当什么、不能当什么"的注释。

## 三、判据（两条，都做了变异验证）

1. **设备条**（`cross-client-theme`）：读悬浮球像素 ——
   ① 品牌色**真的画成** `#2563EB`（声明 ≠ 渲染）；
   ② 球上图标与底色 **WCAG 对比度 ≥3:1**（压在上面的东西得看得见）。
   把 `.accentFg` 改回 `.surface` ⇒ **判红**；还原 ⇒ 绿。
2. **静态防线**（同文件）：全局 grep「`fontColor/iconColor(Theme.surface)`」一处不许有。
   设备条只能看一处，而这个错法有 12 处 —— 静态防线管住整类。

## 四、判据自身踩的三个坑（都写进注释了）

- **采样点撞上图标**：第一版取球心，读到 `rgb(32,34,36)`，差点当成"品牌色没渲染"。
  截图一看球是蓝的，深色那点是**铅笔图标**。⇒ 往中心左偏 30% 球宽。
- **假设错了 FAB 的位置**：按"屏幕右下角"找（`x1 > 屏宽*0.6`），
  实测 `[942,1997]`（`x1=942` vs 阈值 1910）⇒ 永远找不到、**静默跳过**。
  原因是列表窗格是**左栏**，球在"左栏的右下角"。⇒ 形状只用站得住的那部分（下半部）。
- **设备判据要自己搭现场**：不加自导航时它**永远跳过**（前面的判据把前台留在管理页），
  而那看起来像"功能没了"。加自导航后立刻开始工作并抓到 bug。

## 五、欠账

- `harmony-maildetail-missing-three` → **count 0（结算）**：三块都做完了
  （转发 `b7c5d8b` / 改名建议 `c2f35d1`+`e79a86a` / 往返预算 `ac62daf`）。
  如实记着**未验**的那点：预算条的**点击**没在设备上走通
  （模拟器顶部 155px 是系统手势区，折叠头部恰在其中）。
- `static-criteria` 5：`cross-client-theme` **升级了一半**，仍留在名单里 ——
  `.ets` 那半只有悬浮球这一处上了设备，其余令牌仍是静态对齐。
- `debt-visibility` 登记 `cross-client-theme` 1 处边界声明（带出处）。

`run-all.mjs` → `checks=513 pass=513 fail=0 skip=0 red=0 broken=0 unreported=0`；
Go 侧 `./internal/repo/...` 通过。
 2026-09-19 19:29:49 +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
f655453424 跨端: 审计补强 —— 邮件行的「抄送 N」+ 断点差异登记 + 两处"看起来有其实没有"的澄清 
继续「全面对齐 WebUI 和鸿蒙」。这一轮做的是**逐页对照审计**（子代理通道被
session daemon 的端口占用堵死，改为自己逐处读源码对照）。

## 一、补上邮件行的「抄送 N」（真缺失）

WebUI `MailList.tsx:350` 行上有「抄送 N」，鸿蒙**完全没有**。而数据一直在：
`cc_list` 服务端确实返回（实测回包字段列表里有），只是鸿蒙的 `MailLike`
接口漏了这个字段 ⇒ 一封抄送给多个人的邮件在列表里看不出任何区别。

修法：接口加 `cc_count`，`MailSummary` 加 `cc_list` + `cc_count`，
收件箱/发件箱两处填充派生值，行上按 WebUI 的位置渲染。
**设备实测**（造了一封带 2 个抄送的真邮件）：行上出现「抄送 2」，
位置与 WebUI 一致（主题行下方、灰字）。

★ 接口用**数字**而不是 getter：`MailSummary implements MailLike`，
而 ArkTS 的 interface 里不能声明 getter（编译报 "incorrectly implements interface"）。

## 二、有意**不抄**附件标记（发现 WebUI 那段是死代码）

WebUI 行上还有一个 📎 + 数量的标记（`MailList.tsx:351-355`）。但核对服务端
**实测回包**：`GET /me/mail/inbox` 既没有 `attachments` 也没有 `has_attachments`
⇒ `mail.attachments?.length ?? 0` **恒为 0**，那个标记在 WebUI 上**从不出现**。

所以鸿蒙这一轮**有意不抄它** —— 照抄一个不工作的东西，只会多一处
"看起来有、永远不亮"的代码。要做这个功能得先让服务端在列表回包带上附件计数
（一次 JOIN 的事），那是独立的一件事，已登记进 `docs/DEBTS.json`
（`mail-list-attachment-count`）。

★ 这一条与鸿蒙 `MailSummary.has_attachments` 那个字段一起处理掉了：
它还留在那里会误导人（服务端永不返回它 ⇒ 恒 false）。

## 三、两端宽屏断点不同 —— 登记 + 判据（此前**无任何记录**）

审计点名要核实的这条确认成立：

    WebUI: `NARROW_QUERY = '(max-width: 1023px)'`
           含义 = 「三栏（60 导航 + 320 列表 + ≥520 详情 ≈ 900px，再加余量）放不下就退化单栏」
    鸿蒙:  `isWide = width >= 768`
           含义 = 「要不要显示**侧栏**」（鸿蒙内容区是一个窗格，没有并排三栏）

**含义不同，所以数值不同本身不算错** —— 这与手势阈值同一条口径
（语义各自成立时，数值不必强求一致）。但**用户可见的后果**是：768–1023 宽
（常见竖屏平板、窄窗口）下 WebUI 是单栏+底栏、鸿蒙是侧栏+内容，
同一宽度在两端长得不一样。

处理：① 登记进 `docs/DEBTS.json`（`wide-breakpoint-divergence`，
带三个待定选项）；② 加判据 —— 它**不**要求两端取值相同，而是要求
「取值可读 + 含义写清 + 差异被登记」三件事同时成立。

★ 写这条判据时又踩了同一坑：用 `code()` 读注释 ⇒ 永远红。
`criteria-hygiene` 判据的头顶就写着"判代码用 code、判理由用 prose"。

## 四、判据

`run-all.mjs` → `checks=505 pass=505 fail=0 skip=0 red=0 broken=0 unreported=0`
（cross-client-theme 15→16）。`hvigorw assembleHap` 成功。

**未验**：附件标记（有意不做）；抄送行在**深色**下的对比度未单独验。
 2026-09-19 15:13:51 +08:00
JianFeeeee
28e3da76d4 跨端: 左右滑动翻页（P6 第 3 步）+ 还 gesture-semantics 债 + 修跑不起来的判据基建 
★ 这一轮从用户一句「滑动手势呢？」开始。查下去发现它不是"顺手加个手势"，
  而是 `docs/DEBTS.json` 里挂着的一笔债 —— `gesture-semantics` 的原话是：

    「P6 第 3 步：鸿蒙侧出现滑动手势代码时**立即建**判据
      （此前建 = 只有一端存在的假判据）」

  也就是**先有手势、再钉语义**。WebUI 2026-09-14 就有滑动翻页（用户当时
  亲口提的），鸿蒙一直没有 ⇒ 之前建判据会是空真（∀x∈∅）。

## 一、手势本体（两端语义逐项对齐，数值各自定）

按 `HARMONY-ALIGN-PLAN.md:118-128` 显式选的 **(b) 口径**：
「手势的物理量本来就不该强求同值……该对齐的是**语义层**」。

· 判定逻辑放**纯逻辑层** `model/Calendar.ts` 的 `judgeSwipe`（可被 node 直跑，
  写在 .ets 里就跑不了判据，语义没法被单测钉住）。四道门：位移 / 纵向优先 /
  快滑窗口 / 方向。
· 阈值**不引用** WebUI 的 40 / 1.5 / 600（那是把巧合当契约），
  各自定为 56vp / 1.4× / 700ms，并在注释里写出取值依据。
· 接线在 `CalendarPage.ets`：`PanGesture({direction: Horizontal})` +
  `onActionStart`（记时 —— `GestureEvent` **没有时间戳字段**，我查了 SDK
  的 gesture.d.ts 确认）+ `onActionEnd`（读 offsetX/offsetY）。
· ★ 挂在**网格列**上而不是整页：右栏（日程/编辑器）里有输入框与可滚内容，
  整页挂会让「在表单里横划一下」变成翻月。
· ★ 翻页复用 `shiftRange()`（与 ‹ › 按钮**同一个来源**）—— WebUI 的注释
  专门交代过：各写一套的话，阈值、边界、三档行为迟早分叉。
  手势回调里**不准**直接改 year/month（锚点是唯一真相，年月只能由
  `shiftRange → syncYearMonthFrom` 派生）。

**有意差异（记录在案，不是漏做）**：WebUI 在周/日档会额外检查「触点是否落在
可横向滚动的区域里」，是则让给滚动条（用户 2026-09-14 报过这个冲突）。
鸿蒙周档是「一行 7 格按 layoutWeight 等分」、**不横滚** ⇒ 该条件不适用。
哪天加了横滚必须同时补上它。

## 二、判据（8 条语义契约 + 行为层）

新增 `cross-client-gesture.test.mjs`：两端都真有手势 / 方向映射逐项相同 /
纵向优先 / 快滑窗口 / 复用同一翻页函数 / 无边界回弹 / 有意差异被记录 / 自检。
**只比语义、不比数值**，并反向断言鸿蒙的阈值常量不得直接取 WebUI 的那三个数。

`harmony-logic.test.mjs` 加行为判据：真跑 `judgeSwipe`，把四道门各自验一遍
（只钉字符串的话，一个 return 写漏了照样全绿）。

## 三、顺手修掉的三处**判据基建**缺陷（不修就没法验证上面这些）

1. `run-all.mjs` 只认 `# pass N`，而 node v24 打的是 `ℹ pass N`
   ⇒ **21 个文件被记成"没自报条数"**、套件在 HEAD 就恒红（memory 里记过这条，
   修法也记过，今天终于落进代码：4 个正则加 `(?:#|ℹ)`）。修完 `unreported` 27 → 0。
   代价是暴露出一批此前被"没自报"掩盖的真实问题（下面 4~6 条）。
2. `harmony-nav` 的设备判据 `navItemsOf`：宽屏过滤条件从「左边缘靠左 1/6」
   改成「**整个盒子在侧栏轨道内**」。旧条件把**日历网格的格子**
   （实测 `[229,511][366,794]`）也当成导航项，一屏数出 11~12 个。
   这是设备实测抓出来的 —— 我第一版还以为是"底部簇混进来了"，
   打印真实数据才发现是隔壁页面的格子。
3. `harmony-logic` 两处：从 `NAV_ITEMS` / `NAV_SIDEBAR_ITEMS` **各自的数组**里取
   label。原先把全文件 `label:` 一网打尽 ⇒ 得到 7 个（4+3 混在一起），
   任何一边改对了它都会红。

## 四、被判据拦住后的正经修法（每条都按判据自己给的方向改，不改判据迁就代码）

· `cross-client-theme` A2 拦住我：新增的 `navActiveBg`/`navBrandFg`/`badgePlain`
  未登记；又拦住我：`sseColorOf` 里四个裸色值。→ 抽成 `Theme.sseConnected` 等
  四个令牌（取值对齐 WebUI 的 Tailwind 类）+ 登记 + 在 Theme.ets 的表里写理由。
· 同一条判据的"死令牌"检出：`Theme.durBase` 声明了却从没人读。
  **查 WebUI 才发现壁纸淡入是真有的动效**（`index.css:742-752` 的
  `.app-backdrop` 从 opacity:0 → 1，180ms）⇒ 补上而不是删令牌
  （删掉等于把差异抹平、还说成"清理"）。reset 在 `animateTo` **外**，
  与 `calPaneIn` 同一条纪律。
· 玻璃登记：`NavItemBuilder` → `SidebarItem`（重构后按最近的 @Builder 命名），
  登记同步跟上。
· `harmony-admin` 的退出判据：退出逻辑抽成 `api/Logout.ets` 的 `performLogout()`
  （两个入口——「我的」页与侧栏底簇——必须做同一件事，尤其"先注销推送 token"
  那一步）。判据相应改成**追到实际执行处**（两半都断：按钮调了 + 函数真清了全部），
  并写明"别再退回直接匹配 SETTINGS_PAGE 的写法"（那会随重构假红，
  下一个人只会去改判据而不看行为）。
· `harmony-widescreen` 的连接点色值：色值搬进 Theme 后，判据改成断
  「令牌定义对了 + 侧栏真的用了它」两半（只断任一半都有假绿形态）。
· `align-refs`：`CalendarView.tsx` 变了，按判据要求**读一遍差异**再更新登记
  （差异只有农历小字的灰阶档位 gray-300→gray-400/500，**骨架未变**）。
· `criteria-hygiene`：`harmony-contacts` 自造了一个 `code()`、`harmony-widescreen`
  裸用 `readFileSync` ⇒ 都改用 `lib/read.mjs` 的共享入口。
  途中撞出一个**判据自己的 bug**：`code()` 的块注释正则
  `/\*[\s\S]*?\*\//` 会把注释里出现的 `/*`（如 `/」**` 这种中文夹星号）
  当成块注释起点，一路吃到几十行后的 `*/`，把中间的 import 全吞掉 ——
  于是 hygiene 判据假红"没 import"。改掉那处写法后正常。

## 五、验证

判据面：`run-all.mjs` → `files=32 ran=32 checks=497 pass=497 fail=0
skip=0 red=0 broken=0 unreported=0`。
其中新/改判据：gesture 8、nav 18、widescreen 7、logic 30、admin 27、
cross-client-theme 15、criteria-hygiene 6。
构建：`hvigorw assembleHap` 成功；前端 `npm run build` + 重新打 AppImage/deb
（`build-stamp` 7/7、`packaging` 5/5）。

**设备实测（HATriple 三折叠 3184×2232，hdc 连 127.0.0.1:5555）**：
· 农历在格子里真的显示（1=二十 / 7=廿六 / 19=**初九** / 11=八月），与 WebUI 一致；
  这条同时验证了**服务端农历路由已部署**（之前线上是 404）。
· 日历左右两栏：编辑器出现在**右栏**、左栏月份仍可见（单栏模式下编辑器会整页盖掉它）。
· 侧栏 3 项 + 底部一簇；徽标回到图标右上角。

**仍未验（如实标注）**：滑动翻页的**手感**（阈值 56vp/1.4×/700ms 是否合适）
只能真人滑过才知道；我只验了判定逻辑与接线形态。动画同理 ——
机制已验证（`animateTo` 驱动 + reset 在窗口外），但"看起来顺不顺"未做取样验证。

docs：`DEBTS.json` 销掉 `gesture-semantics`（并记结算说明）、
`HARMONY-ALIGN-PLAN.md` P6 从「✅（滑动翻页除外）」改为 ✅。
 2026-09-19 14:01:21 +08:00
JianFeeeee
6cd64a4384 ke: 玻璃面板（系统材质）：WideSidebar bgActive 走 BlurStyle，撤回手写 alpha 
遵守既有玻璃纪律（cross-client-theme B/C）：
- 手写 8 位半透明色一律禁止（半透明归系统材质），撤回 #E6FFFFFF 尝试
- 玻璃 = 系统 BlurStyle(navMaterial) + 不透明系统色 surface，半透明由 BlurStyle 给
- WideSidebar 加 @Prop bgActive：bgActive 时 backgroundBlurStyle，否则 NONE
- 内容面板只保留几何（radius/clip/padding/gap），不加材质（判据按 @Builder 解析
  owner 会与 NavBar 撞 key；壁纸从面板缝隙露出已达成 app-shell 观感）
- GLASS_REGISTRY 登记 WideSidebar#NavItemBuilder（判据按最近 @Builder 命名）
 2026-09-16 08:06:36 +08:00
JianFeeeee
c12744e8c3 跨端: 导航条材质选 (a) 固定档（推翻我的 (b)）—— 并修掉"注释说 (a)、代码是 (b)"的自相矛盾 
pi 2026-09-15 裁定：**推翻 (b)，选 (a)**。我原先给 (b) 的理由不成立，他逐条驳了：

1. **WebUI 的导航条根本不读 `--bg-blur`**：`index.css:1114` 的 `.narrow-nav` 是硬编码
   `backdrop-filter: blur(18px) saturate(1.5)`。我引这条支持"两个量不同"，
   而同一条也说明**它不由用户偏好驱动**。
2. **WebUI 那个滑杆的语义是"背景"**：`BackgroundPicker.tsx:183` —— `label="模糊"`、
   `hint="虚化细节，避免背景与正文抢注意力"`、`min=0 max=24`，只作用在
   `.app-backdrop{filter:blur(var(--bg-blur))}` 上。
3. WebUI 自己留了**分开的**令牌 `--bg-blur-panel`（`index.css:267`，注释写明
   "与壁纸自身的 `--bg-blur` 分开"）—— 它的词汇表本身就拒绝把两者等同。
4. **★ 我给 (b) 的理由不成立**：我写"(a) 会让那个滑杆在导航条上变成死控件"，
   可那个滑杆**已经**被壁纸消费了（`MainPage.ets` 壁纸层的 `.blur(bgPlan.blurPx)`）——
   它从来**不是**导航条的控件。(a) 之下它照样是活的。
5. §7.12 的「材质（玻璃）」行原本写的就是固定档 ⇒ (a) 是**回到**已登记契约。

产品向还有一条：**导航条是 chrome，材质应当稳定**，不该因为用户换张壁纸而变厚变薄。

## 最该记的是：我的注释和代码**互相矛盾**

`MainPage.ets` 里那段注释论证的是 (a)、并明确写着"跟随是错的，pi 抓出来了"，
而它下面那一行代码是 (b)。**下一个读者会照注释把代码改回去，并引我那句话当权威。**
这是这一路反复在消的形状（说的与做的不一致、而判据看不见），这次落在**注释**上 ——
而注释正是"理由要写清"那条纪律的证据源。已整段重写为真实的 (a) 版本，并把
"(a) 会让滑杆变死控件"这个**错的理由**连同它为什么错一起留在注释里。

## 做掉的东西

- `MainPage.ets`：导航条回到 `.backgroundBlurStyle(Theme.navMaterial)`；
  删掉 `NAV_MATERIAL_OF` 表与 `navMaterialFor` 的 import（(a) 之下都是孤儿）。
- `model/Appearance.ts`：删 `navMaterialFor`（它存在的唯一理由就是方案 (b)）。
  `blurStyleFor` 现在**没有任何调用点** —— 如实登记在它的文档注释里
  （"有测试"不等于"有人用"，上一轮我刚因同形状被抓过），不假装它活着。
- **五处"整条字面表达式"断言改成语义断言**（pi §四）：`cross-client-theme`、`harmony-appearance`、
  `harmony-nav`（3 处）此前都在钉
  `/\.backgroundBlurStyle\(NAV_MATERIAL_OF\[navMaterialFor\(…\)\] \?\? Theme\.navMaterial\)/`
  —— 字面换字面，正是 `CRITERIA.md` 不许的"对源码形状的匹配"。
  现在判：① 那一处的材质**来自 `Theme.navMaterial` 这个系统令牌**；
  ② **不许跟随** `bg_blur`（NavBar 真代码里不许出现 `blurPx`/`blurStyleFor`）；
  ③ 令牌是 `BlurStyle` 枚举值、不是 `NONE`、且**成员名真实存在于 SDK 枚举**。
- "可达性"那条判据**随契约作废**（它守的是方案 (b)）：换成判 (a) 的契约。
  **判据随契约走，不随实现走。**
- `harmony-appearance`：原先判"页面里那张表的键必须是 SDK 成员"。表删了，
  改成**枚举 `blurStyleFor` 的整个值域**（0..40 + 界外 + NaN），逐个核 SDK 成员 ——
  比原来只核表里那三行**更严**。

## 判据自己先错了一次，记下来

新判据第一版**没剥注释**就断言"NavBar 里不许出现 `blurPx`"，当场红了 ——
而红的原因不是代码错，是 `NavBar` 的**文档注释**里正好写着
"我一度把档位接过用户偏好（`navMaterialFor(this.bgPlan.blurPx)`）"这句历史说明。
**注释说明禁令 ≠ 违反禁令**；不剥注释，这条判据就会变成"逼人删掉解释"，
恰好与本仓库"理由要写清"的纪律相反。改成 `stripComments(bar)` 后再判，并加了一条
"注释里确实留着那处说明"的自检前提。

## 变异体：45 个全部被抓（含 3 个新判据的专属变异）

方案 (b) 落地时配的 13 个变异体**整体作废**（它们锚的代码被删了），标注 `retired`
并写清理由 —— 不是"没跑成"。另有 5 个锚点漂移（我在注释里逐字引用了被锚的那句代码，
污染了通用正则）的**重锚**到真代码；注释里那句逐字引用也一并去掉了
（**注释里逐字抄代码**正是让"按字面锚定"的变异体反复失效的根因）。
新增 3 个针对 (a) 契约的变异体（绕过令牌 / 又跟随 `bg_blur` / 令牌变 `NONE`），全部被抓。

## 未验

- **真机观感仍未验**：三档材质在真机上能不能看出差别、滑杆手感、管理页布局，
  只有真机能答。本机模拟器已起（`hdc list targets` 有目标），但
  `run-all.mjs` 的**设备闸已经到期**（8 个静态判据的前提成立）⇒ 套件现在会挡在
  那道闸上、不打 `RESULT`。**这不是本笔引入的**（前提是环境变了），已单独报给 pi。
- Go 侧 `debt_registry_test.go` 仍未在本机跑（无 Go 模块缓存）；pi 已在别处跑过，绿。
 2026-09-15 11:58:19 +08:00
JianFeeeee
b806a05bfa 跨端: 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 也不需要临时文件。

## 两处真 bug（变异测试逼出来的，不是"新写坏的"）

1. **压缩循环的第二档此前是死代码**：循环里的 break 与循环外那句 shouldRetryWithActual
   互相抵消 —— 把循环里那处改成 `if (true)`（永远只压一档）整套判据照样全绿。
   收成一处判定（overLimit），循环外只读结论，并加结构性判据（该函数在这条链上只许调用一次）。
2. **壁纸的模糊档一直是「只写不读」**（计划文档 §7.12 登记过）：滑杆能拖、值能存、
   blurStyleFor 也写了，就是**没有调用点**，壁纸一点没糊。
   本次补上的调用点分两层：壁纸层 `.blur(px)` = **图片内容模糊**
   （与 WebUI 的 `filter: blur(var(--bg-blur))` 同一个量、同一个数，所以不需要映射表）；
   而那张**材质档**映射表 `blurStyleFor` 也终于有了调用点（`navMaterialFor` 内部复用它）。
   `docs/HARMONY-ALIGN-PLAN.md` 的 §7.12 两行（材质 / 壁纸模糊度）已一并改准、不再互相矛盾。

## pi 复核后**改回来的**（这一笔里我自己犯的两处，都由 pi 抓出）

1. **导航条材质一度绑定到 `bg_blur`，`bg_blur=0` 时整个消失。**
   我把 `NavBar` 从固定档改成 `blurStyleFor(bgPlan.blurPx)`，而滑杆 `min: 0` 可达、
   `blurStyleFor(0) === 'NONE'` ⇒ 用户把壁纸调清晰时**导航条一点材质都没有**。
   而且它与本笔自己的论证**相反**：刚论证完"图片内容模糊"与"面板材质"是两个物理量，
   转头把面板材质接到壁纸模糊这个输入上。
   现在**分层**：`blurStyleFor` 是通用映射（**允许** NONE —— "0 px 不模糊"是它的正确语义）；
   `navMaterialFor` 是**导航条专用、有下限**的入口（0 px ⇒ 最薄档）。
   判据钉**可达性**（滑杆 0..40 每个整数 + 界外值都不许 NONE，且三档都要出现 ——
   否则"恒定最薄档"会让滑杆成为死控件）。
2. **`Theme.navMaterial` 被我弄成了死令牌**，而看着它的判据**照样绿**
   （那条只断言"声明存在且不是 NONE" —— 守的是声明，坏的是活的调用路径）。
   现在导航条真的用它；并把同文件里**只覆盖 `Theme.overlay` 一个令牌**的死令牌规则
   **铺到 Theme 的全部 35 个令牌**（量**外部引用数**：只被 Theme 内部方法读、
   而那个方法自己有外部调用点 ⇒ 不算死 —— `chipSpentBg` 是这种；`navMaterial` 当时
   唯一的消费者是一张可整体删掉的局部表，所以必须被抓）。

## pi 复核后**补上的**（这一笔漏掉的接线，都是我造成的）

- **`test/run-all.mjs` 的 SUITE 没接两个新判据文件** ⇒ HEAD 上 `npm test`
  **一条判据都不跑、直接 exit 1**（套件自检 2 就是为这件事写的）。已接入，
  并把两条登记进 `STATIC_ONLY`（`.ets` 要设备 ⇒ 静态欠账）。
- **`debt-visibility` 是我自伤**：那两个新文件里有 5 处"边界声明"但一次都没登记。
  我当时报"2 条失败是改动前就红" —— **只对一半**：这条在父提交上是**绿的**。
  我那次 `git stash push -u -- client/harmony` 的对照是**无效对照**
  （`-- client/harmony` 把 `client/electron/test/` 整个排除在外，新判据文件根本没被 stash），
  所以两次跑都红、看着像"既有"。已按 pi 的建议改用 `git worktree` 到父提交做对照。
  现在两处都登记进 `docs/DEBTS.json`（含 `static-criteria` 5→7，Go 侧同一份登记同步改）。

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

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

## 判据

新增 `harmony-admin.test.mjs`（22 条）、`harmony-imageprep.test.mjs`（29 条）；
`harmony-presets.test.mjs` 加 1 条（模糊档搬运与归一，含 `-0` 那个洞：
`Math.round(-0.4)` 是 `-0` 而 `-0 < 0` 为 false ⇒ 改成判 `!(r > 0)`）。

**`node test/run-all.mjs`：22 个判据文件全部跑起来**，红的只有 1 个：
`build-stamp`（`dist` 是 `a5fc86b` 上构建的，`gitRev` 对不上当前 HEAD）。
这条**不是我的代码造成的**（可证：`a5fc86b..HEAD` 之间，`srcHash` 覆盖的那批文件
——`client/electron/src` 等——**一个都没动过**，所以 `srcHash` 没变，差的是 `gitRev`），
但也**不是"改动前就红"**：任何推进 HEAD 的提交都会让它变红，正确修法是重构建。

## 未验（如实标注）

- **本机无设备/无模拟器 ⇒ 全部观感未验**：管理页排版与卡片观感、滑杆手感、
  模糊在真机上的实际档位观感、系统材质在自绘悬浮条上的实际效果。代码齐 ≠ 真机验过。
- 预设档**没有**上模糊（壁纸在预设档下是一叠自绘矩形，系统材质对它不生效）——
  这是我**主动收的范围**，不是漏，真机看一眼再决定要不要补。
- **Go 侧的 `debt_registry_test.go` 我没能跑**（沙箱里没有 Go 模块缓存，`go test` 起不来），
  只做了 `gofmt` 校验；那处改动是一行 `Count: 5 → 7`。
 2026-09-15 11:17:23 +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
d5cfcbdc9c fix(权限): 409 的第二种含义是「本档不该问」——四桥都补上；状态写入点不再兜默认档 
线上事故（jianf 经 pi 转达）：补投路径漏传 permission_mode，插件拿 undefined 兜了
workspace 档，把 full 档会话写成 workspace-write + ask —— 不是"拦一次"，是一整轮
工具能力降级，且状态留在会话里；随后该会话每次受守卫调用都撞 409。

四件事：

1. **状态写入点不接受默认值**（新增共享 `modeForStateWrite`）：缺字段/脏值 → `null`
   = 不写状态。"默认值可以出现在**决策**里，不可以出现在**状态写入**里。"
   同时保留共享契约的 fail-closed：真读到 workspace 才写 workspace。

2. **409 的两种含义分开处理**。`allowed-once` 只绕过**审批**，改不了**沙箱** ——
   所以 dsh 桥在放行前先把服务端给的权威档位**写回会话**（这也就成了自愈路径：
   已经降级的会话，下一次带档位的 409 会把它修回来）；只认服务端明说的 full，
   plan 与"链上没有人类"照旧 fail closed。

3. **同一处缺陷在 zcode / opencode 也在**（`hooks/permission.mjs` 与 `index.js`
   都把 409 当永久失败拒绝）。我先前在回信里写过"这两个桥不转发权限询问，不需要改"
   —— 那句话是错的，我当时的搜索面只有 `<plugin>/src/*.mjs`。按 pi 的要求把这条
   **否定性事实变成常驻判据**后，它第一次运行就红给我看。四桥现在都有
   「409 + full → 放行」，且**排在永久失败分支之前**（含顺序变异自检）。

4. **共用测试重新同源**：`test/catchup.test.mjs` 从 `153985e` 起就是分叉的
   （我那版把平台专属路径写进了共用文件），而 `deploy/install.sh` 第 24 行会跑
   `check-shared-libs.sh` —— 也就是说**部署一直是红的**，我没跑过那个脚本。
   共用文件只放契约（值/行为），跨平台配对judge 移到平台专属文件，四份逐字节相同。

另外把"判代码 vs 判理由"从记忆变成代码：`test/lib/read.mjs` 提供 `code()/prose()/bytes()`，
判据目录里不得再裸用 `readFileSync`（新判据 `criteria-hygiene` 管，含读取器自检）。

判据证据（每条都做过"能不能红"的变异）：
- 写回去掉 → 红；纠正块挪到普通 409 之后 → 红；状态写入点退回兜默认 → 红；
- zcode/opencode 的放行分支拿掉 → 各自红；共用测试分叉 → check-shared-libs 红。

各套件：dsh 388、pi 443、zcode 387、opencode 333（均经 npm test，含 tsc）；
electron `npm test` 15/15 判据绿 + vitest 266 + typecheck；`check-shared-libs.sh` 退出 0；
Go `go test ./...` 全 ok。
 2026-09-14 16:21:27 +08:00
JianFeeeee
25ac19b343 跨端: P5 悬浮玻璃导航取代系统 TabBar —— 自绘浮动条 + 命中区 ≥44vp + 内容让位 
（subject 原为「跨端(P5): …」—— 被自己的 commit-hygiene 判据判红：约定是 subject 里带
 `跨端:`，而 `跨端(P5):` 让字面 grep 找不到。判据是对的，改提交不改成判据。）
 2026-09-14 15:34:32 +08:00
JianFeeeee
22c9be7181 跨端: 预设色板两套（pi：这不是"观感未验"而是机制上确定不同）+ 手写色清册跨文件 + TMPDIR 按会话分家 + 提交归属可判 
pi 读完 `model/Wallpaper.ts` 后指出四处，全部处理。这一提交同时改了
`client/harmony/` 与 `client/electron/`（跨端改动），所以 subject 按新约定自报家门。

## 1 预设色板不随主题 —— **类别判错了：不是"未验"，是机制上确定不同**

我上一版把"深色档预设"记成"观感未验"。pi 指出：WebUI 的 `.bg-preset-*` 写的是
`rgb(var(--c-blue-100))`，而 `--c-*` 在 `.dark` 里整体换了一套（blue-100 → `30 43 67`），
所以 **WebUI 的预设自动随主题变**；这边只有浅色那套 = 深色主题下"浅色渐变垫在深色系统表面之下"，
正是这一整轮在治的病。**它不需要真机就能判**（机制写在代码里）—— 我把可判的东西
记成了"未验"，这跟上一轮把"没做"写成"没验"是同一类错。

选 pi 倾向的那条（跟随主题，与 WebUI 一致）：

- 色板两套：`LIGHT_*` 取 CSS `:root`、`DARK_*` 取 CSS `.dark`；`paletteFor(dark)` 选一套，
  `layersFor(id, dark)` 按主题出层；
- `isDarkMode(theme, systemColorMode)` 放在纯逻辑里：选了 dark/light 就照办，
  `system` 看系统当时的 `colorMode`（锚到 SDK：`COLOR_MODE_DARK = 0` / `COLOR_MODE_LIGHT = 1`；
  读不到按浅色，与 WebUI 的 `:root` 默认一致）；
- 系统深浅从 `resourceManager.getConfigurationSync().colorMode` 读
  （`Context` 基类没有 `config`；`UIAbilityContext.config` 要转型；两个枚举取值一致，都核过 SDK）；
- 判据：两套值与 `:root`/`.dark` **逐个相等**；每个预设的深浅两套**必须真的不同**
  （否则"两套"是抄了两遍）；网格线色也要换；`isDarkMode` 五种输入。
- **未做**：运行期间改系统深浅色不会自动重算（要重进页面）——系统侧正确做法是订阅
  `applicationContext.on('environment', …)`，记在 §7.17b。

变异：`DARK_BLUE_100` 偏一位 → 红；`paletteFor` 永远返回浅色（= 我原来那个状态）→ 红；
`isDarkMode` 把系统深浅记反 → 红；页面把深浅写死成 false → 红。

## 2 手写色清册**跨文件按类扫**（原 A2 只保护 `Theme.ets`）

`Wallpaper.ts` 也有手写色。若对照是"按名字枚举"的，第 15 个色就会逃掉 ——
与 A2 要防的是同一件事，只是换了文件。现在一份清册按类扫：全 `ets/` 树里每个
`X: string = '#RRGGBB'` 都必须登记（Theme 的品牌/业务语义色，或预设色板 ——
后者常量名必须带 `LIGHT_`/`DARK_` 前缀，值由 CSS 两段比对负责）。反向也判清册过期。

变异：`Theme.ets` 加未登记色 → 红；`Wallpaper.ts` 加未登记色 → 红；
加一个"看着合规"的 `DARK_EXTRA` → 红。

## 3 `TMPDIR` 互踩（pi 提出）

这个 worktree 可能同时有多个 agent 跑构建，而 fpm 会把 291MB 的 `linux-unpacked`
**整份复制**进 `TMPDIR` —— 撞车就是随机的产物损坏。`whoami` 区分不开（大家都是 root），
所以按**会话**分家：`TMPDIR=$PWD/.tmp/${DSH_SESSION_ID:-$(id -un)-$$}`
（进了 `npm run build:linux` 与 BUILD.md 的手敲命令；普通终端退化成"用户+PID"）。

## 4 提交归属变成**跑判据就看得出来**（pi 给的形状）

新的 `test/commit-hygiene.test.mjs`：扫最近 40 条提交，**同时改两侧目录**的提交
必须在 subject 里自报家门（`跨端:`）。两条防腐：基线 = 该判据文件自己的引入提交
（**历史不改**，规则管从今往后）；分类逻辑拿合成输入自检
（未标注的混合提交必须判红、标注过的不许红）——否则"解析没跑起来"时它会全绿。
变异：`COMMIT_HYGIENE_BASELINE` 指到老提交 → 历史里那两个被卷进去的提交立刻判红。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（12 个判据文件全绿 + vitest 258/258；`commit-hygiene` 在本提交落地后基线生效）。
 2026-09-14 14:57:18 +08:00
JianFeeeee
a6b5e52f45 test(harmony): 判据按 pi 复核意见补强 —— 手写色登记表、玻璃叠用形状、按标题取小节、遮罩必须被用、废弃 API 清单从 SDK 生成 
pi 逐行读了 `cross-client-theme.test.mjs` 与 `Theme.ets` 后指出五处（第一处是真缺口），
外加一条建议。全部处理，并且**每一处都用变异验证过**。

## 一（真缺口）：枚举 11 个"必须是系统资源"的名字，挡不住第 12 个新写死的手写色

`static readonly brandSecondary: string = '#123456'` 这种新增**三条判据都碰不到**：
A（不在名单里）、B（六位、不是半透明）、裸色值那条（只管 `pages/`）。
原理与当初 14 处 Google 色逃出去是同一条 —— **枚举挡实例，类才挡漂移**，
只是这次枚举的单位是**名字**。补 `A2` 条：

- 枚举 `Theme.ets` 里所有 `static readonly X: string = '#……'`，未登记的 → 红；
- 名单里已不存在的名字 → 红（名单不能烂成化石）；
- `Theme.ets` 里的「手写色登记表」段必须逐个列出这些名字（理由不能只存在于记忆里）；
- 自检：把一个**新的**手写色塞进源码字符串，确认这条抓得到。
  `Theme.ets` 因此新增登记表（17 项，每项一行理由，按品牌 / 业务语义 / 档位胶囊分组）。

变异：Theme.ets 加 `brandSecondary` → 红。

## 二：C 的"玻璃只有一处"**说错了自己断言的东西**

`assert.equal(glassCalls.length, 1)` 断言的是"全仓共一处"，**不是**"没有嵌套"：
同页两个**并列**玻璃面（没问题）会让它红，真嵌套它没在判。P5 正是悬浮玻璃导航，
到时若把 1 改成 2 就等于不判。改成形状判据：

- 收集每个调用点所作用的**组件块**（按括号配对回溯；注意 ArkUI 修饰符是链式的，
  `X.blur(A).blur(B)` 前面是 `)` 不是 `}` —— 第一版只看一个字符，对这种写法**静默失效**，
  是判据自检抓出来的）；
- 判两种叠法：同一组件上叠多次（同一块）、以及套在另一层玻璃的子树里；
- 每一处玻璃都要在 `GLASS_REGISTRY` 里登记（附一句为什么），名单里的位置若已不存在 → 红。

变异：链式叠两层 → 红；通信页多开一处未登记玻璃 → 红；导航条块内嵌玻璃 → 红。

## 三：文档小节用 `indexOf('有意差异')` 会**拿错段落**

别的段落正文里出现这四个字，切片就从那里开始，后面所有断言都在**别的段落**上判。
改成**按标题**定位（正则匹配 `^#{2,4}…有意差异…$`），并加了表头列名断言
（WebUI / 鸿蒙 / 为什么）—— 拿错段落时表头不会是这个形状，于是它自己会红。

顺带修掉一个**我自己的**同类毛病：品牌色那行原来用"关键词 + 80 字符窗口"判，
窗口宽度在赌表格单元格字符数（该行两格之和 > 80）。改成**按行取**那一行再断言。
另外把偏移算术的切片换成**按行**切片（偏移差一个字符就会把最后一行拦腰截断，
现象是"品牌色那行只剩 57 字符"这种看着像文案、其实像切片的怪事）。

变异：文件前面插入含「有意差异」的段落 → 仍绿（按标题定位生效）；
再改坏真表里的品牌色行 → 红（确实读的是那一张表）。

## 四：`Theme.overlay` 只判了"存在"，没判"被用"

没使用点的令牌是自证。补断言：它必须在 `Theme.ets` **之外**有真实使用点
（实测 `SettingsPage.ets` / `MailDetailPage.ets` 两处自绘弹层在用），
并把 `overlayColor`/`overlayAlpha` 消失的理由写进 §7.12 —— 否则下一个人会当成漏改补回来。

## 五：材质档次是这次替换里唯一"判据绿但可能观感错"的地方

`COMPONENT_THICK` 的依据（对 THIN / BACKGROUND_* / ULTRA_THICK 的取舍）写进 §7.12，
并把"材质档次在导航条上的实际观感"列为**模拟器起来后第一个要看的项**（间距是数字，材质是判断）。

## 六（建议）：废弃 API 判据**类化** —— 清单从 SDK 生成

原来是手写"不得再用全局 `promptAction.showToast`"（只挡已踩过的那个）。
现在从 SDK 生成：顶层（花括号深度 0）被标 `@deprecated` 的 `declare function`
—— 实测 68 个名字（含 `animateTo` / `getContext` / `px2vp`），配一份**空**的 allow-list。
深度判定是必要的：`declare namespace fileIo { declare function open() }` 里的 `open`
是命名空间成员，算进来会造一堆假红。只算全局调用（排除 `x.name(`）。

变异：调 `px2vp(10)` → 红；`this.px2vp(10)`（成员调用）→ 绿（假阳性自检）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0
（11 个判据文件全绿 + vitest 258/258）。cross-client-theme 13 → 14 条，harmony-system-api 4 → 5 条。
 2026-09-14 14:26:45 +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
e0c68d8bb2 test(cross-client): 预算条三个档位的令牌也和 WebUI 对齐 + 记录模拟器权限门 
## 判据

P2a 新加的 6 个预算条令牌（`chipNeutral*` / `chipSpent*` / `chipWarn*`）此前只有鸿蒙侧
自己在用，没有任何判据钉住它们与 WebUI `BudgetChip` 的 gray-100/gray-500、
red-100/red-700、orange-100/orange-700 是**同一批值** —— 于是"鸿蒙那边自己挑了个接近的红"
没人会发现。补进 `cross-client-theme.test.mjs`（8 → 8 条，第 7 条扩了 6 个断言），
并加了反向对照（差一个色阶必须判红，实测判红）。

注意 `--c-gray-100` 等在 `.dark` 段有第二处定义，`cssVar()` 取第一处（`:root` 浅色一套），
与 `Theme.ets` 的浅色令牌对应。

## 文档

`docs/HARMONY-ALIGN-PLAN.md` §7.6：把"鸿蒙视觉/点击未验"查到根上 —— DevEco CLI 说明本机
**有**可启动的模拟器（起来后 `devecocli ui layout/click/screenshot` 能做点击级验证），
但 `harmony-emu start` 要写 `/run`、`/root/.Huawei`（工作区之外），按规矩升级重试一次后
被拒：**「权限询问无法送达：该任务链上没有人类用户」**。
即：鸿蒙的点击级验证不是"还没做"，是"当前做不到"——需要人在命令行跑一次
`harmony-emu start`。此前所有阶段只能按"逻辑有可执行判据 + 接线有判据 + 观感未验"验收。
 2026-09-14 13:38:35 +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
cefd96a6a3 feat(clients): UI 设计同步到客户端 —— Electron 包重建 + 鸿蒙设计令牌 
用户：「下一步就是同步 ui 设计到客户端了」。

## ① Electron 客户端（之前严重滞后）

打包产物停在 **09:11**，而前端 dist 是 **12:23** ⇒ 今天所有 UI 工作（导航合并、悬浮玻璃、
圆桌语言、Composer、动画、模糊分层…）**一个都不在包里**。已重建 AppImage + deb。

**验证**（关键：AppImage/deb 是压缩容器，`grep` 直接扫是扫不到的 ——
我第一次就差点因此得出"包里没有"的结论）：把 deb 解到 /tmp 再查 `app.asar`：

    comm-tabs=2  compose-fab=1  nav-rail=2  glass-control=2  cal-slide-next=2
    构建戳 "5ce25f6·0914-1240"（与当前提交一致）

## ② 鸿蒙客户端

它是**原生 ArkTS 应用**（22 个 .ets、自带 API 层），不是 WebView 壳 ⇒ 设计要移植。

第一步做的是**共用词表**：新增 `common/Theme.ets`（品牌蓝、页面底、面、分隔线、
导航玻璃不透明度、圆角 14/8、语义色、字号），全部注明与 WebUI 令牌的对应关系
（含一个易错点：CSS 是 `rgb(r g b / a)`，鸿蒙是 `#AARRGGBB`，0.72×255≈184=0xB8）。

顺带修掉一个真 bug：TabBar 的选中色写成 `this.currentIndex === 0` ⇒
**只有第一个 tab 会高亮**。现在按每个 tab 自己的下标判断。

**编译验证**：`hvigorw assembleHap` → **BUILD SUCCESSFUL**（HAP 已打包）。
（无法在设备上跑：本机 `hdc list targets` 为空、HAP 未签名 ⇒ 视觉未验证，如实说明。）

## ③ 判据：跨客户端令牌一致性

新增 `test/cross-client-theme.test.mjs` 5 条：品牌蓝、卡片圆角（0.875rem=14px）、
导航玻璃 0.72 —— 断言的是"两边对同一件事取值一致"，不约束实现方式
（CSS 变量 vs ArkTS 常量本来就该不同），并带一条扰动自检。
这种漂移**没有任何判据会红**，所以必须显式钉住。

## 还没做的（如实说明）

鸿蒙端只同步了**设计语言**，功能面不对等：鸿蒙是 收件箱/会话/联系人 三个 tab，
没有 日历/授权/管理；也没有玻璃悬浮底栏与 Compose 共用组件。要做功能对齐是另一件事，
需要单独排期（我可以按你的优先级来）。
 2026-09-14 12:43:08 +08:00