jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
932 Commits 1 Branch 0 Tags
9d40816230df4e7276022d7611b059b710c0a666
Commit Graph

22 Commits

Author SHA1 Message Date
JianFeeeee
187609480f 跨端: 鸿蒙修收信/自动已读/发件箱点开 + 页签条通透（用户报的四个问题） 
用户报了四个问题，逐个实测复现 → 定位根因 → 修 → 设备复验：

① 「邮件点进去自动已读的能力不正常」
   根因：鸿蒙只有「标记已读」按钮（doMarkRead，对照 WebUI MailView.tsx:522
   那个手动按钮），缺 WebUI 的**自动**路径（MailView.tsx:55-65 的 useEffect：
   可见且 unread 就 markRead）。⇒ 点开邮件不变已读，必须再点按钮。
   修：MailDetailPage.loadMail 成功尾端按 `status==='unread'` 触发 doMarkRead
   （复用按钮那条路，因而天然带上「就地改 status」+「失败弹 toast」）。
   ★ 加 autoReadMailId 守卫：WebUI 靠 useEffect 依赖数组天然只跑一次，
     鸿蒙 loadMail 是显式调用的（下拉刷新会重跑），不守会重复打接口。

② 「接收邮件的能力也有点不正常」
   三个独立缺口，每个都会单独造成"收不到"：
   a) **SSE 监听寿命**：原挂在 InboxTab.aboutToAppear，而三个 tab 是
      if/else 条件挂载的 ⇒ 切到发件箱/授权时 InboxTab 被销毁、监听跟着
      移除 ⇒ 在那两栏时收不到任何新邮件。搬到 MainPage（@Entry，全程在）。
   b) **只处理 new_mail**：WebUI 监听 5 种事件（sse.ts:7-13 的 EVENTS）；
      服务端权限决策后发的是 session_update（permission.go:387）⇒
      "授权栏里处理过的申请，收件箱还是旧的样子"。补齐四种。
   c) **UTF-8 解码错**：arrayBufferToString 逐字节 String.fromCharCode
      （Latin-1 语义）⇒ 中文解成乱码。改用 util.TextDecoder + stream:true，
      且**每连接一个实例**（stream 会把半截汉字存在解码器内部，
      共享实例会把两个账号的半个字拼在一起）。

③ 「发件箱内容点不开」（第二轮；5483140 补了 onClick 仍点不开）
   根因：发件箱对单封组**既画组头又画行**——
       this.SentGroupHeader(g); if (isFlatGroup(g)) { this.SentRow(...) }
   组头那半张卡没有任何点击处理 ⇒ 点卡片上半部完全无反应。
   而 isFlatGroup 自己的注释写着「单封不成组：套一个可折叠的组头只是
   多一次点击」—— 实现与注释**直接相反**。收件箱一直是正确形状
   （if (isFlatGroup) { MailRow } else { 组头 + 子行 }）。
   修：与收件箱取同形，单封组只画 SentRow。

④ 「通信页面我觉得没有 webui 那么通透」
   这是我自己上一轮改错的：把 WebUI 的「页签条无背景」实现成了
   `backgroundColor(Theme.surface)` 实心白。WebUI 的真实层叠是
   .comm-pane 是玻璃卡、CommTabs 在它内部且**自己无背景**（透出卡的白）。
   铺实心白 = 把玻璃卡换成横条白 ⇒ 壁纸再也透不过来。
   ⇒ 改回玻璃族（Theme.navMaterial，与底部导航条同档）+ 通栏 +
      只左上圆角（右上 0，与窗格那道弧重合）+ 底边线。
   判据 harmony-nav.test.mjs:732 在我改错时当场判红，是它先抓到的。

判据（变异验证：还原 bug → 必须判红）
- 新增「单封组不许既画组头又画行」：两栏的 (header, row) 对必须在
  else/三目里二选一。
  ★ 第一版写弱了（用 isFlatGroup(g) 作锚点往后切片，组头在切片之前
    ⇒ 变异测不红）。改成以**行调用**作锚点往两边开窗后，删掉修复
    即判红（实测已验）。
- 新增「列表行必须把 onClick 挂在自己身上」（MailRow/SentRow）。
- harmony-logic 34→37、harmony-nav 22（新增后仍绿）、
  harmony-appearance 27→28、animation-audit 12→15 的登记数同步。

设备复验（全部有实测凭据，不是推断）
- 自动已读：点开前 unread → 点开 4s 后服务端 read（连验两封）。
  列表组头 4→2、侧栏徽标 4→2，三处数字一致。
- 实时收信：App 保持前台不重启，从 gateway 发信 ⇒ 8s 内自动出现
  （新卡片 + 侧栏 2→3 + 页签 2→3 + 3 组 8 封）。
- 发件箱点开：点原先点不动的卡片上半区 ⇒ 右栏出正文 + 蓝色选中态。
- 页签条：截图确认为玻璃通透（不再是实心白横条）。
 2026-09-24 16:34:44 +08:00
JianFeeeee
548314013a 鸿蒙｜修发件箱点不开（SentRow 缺 onClick）+ 补列表行判据 
用户报的三件事，逐条实测后的结论：

## ① 发件箱内容点不开 —— 真 bug，本次修复

复现：点发件箱「致 pi」那一行
  · 日志里**没有** `GET /mail/{id}`（收件箱同样操作是会发的）
  · 右栏仍是占位（「选择一封邮件查看…」）

根因：点击挂在**外层** `Column` 上，而 `SentRow` 自己**一个 `.onClick` 都没有**。
更要命的是 `isFlatGroup(g)` 那条分支（单封不成组）直接调 `SentRow`，
**外层那层点击根本不经过它** —— 而用户的数据恰好是 1 封不成组 ⇒ 完全点不动。

收件箱的 `MailRow` 是挂在行自己身上的（`.clip(true)` 之后直接 `.onClick`），
所以它两条分支都通。这是本仓反复出现的形状：同一件事两处各写一遍，然后慢慢分叉。

修法：`.onClick` 移进 `SentRow` 自身（与 `MailRow` 同形），
并删掉外层那处（留着会变成"同一行两处都能点"）。

修复后实测：发 `GET /mail/2d882e82…`，右栏渲染出详情 ✅

## ② 对话树点不开 —— 实测能点开（不是 bug）

代码里有完整的实现（`openThread()` + `bindSheet` + `tree` 图标按钮）。
点开路径：**先点详情页标题展开头部** → 出现「对话树」→ 点它
（`GET /mail/{id}/thread` 发出，弹层显示 `jianf → pi / 测试`）。

★ 折叠是**两端一致**的行为，不是鸿蒙漏做：
  WebUI `CollapsibleHeader` 的 `useState(false)` 也是默认收起。
  我实测确认了展开后才看得到该按钮。

## ③ 邮件本地缓存 —— 两端都没有（不是鸿蒙落后）

对着源码逐个数：
  WebUI `stores/` 有 persist 的：accountStore(8) / appearanceSync / backgroundStore(15)
                                / contactStore(5) / themeStore(3)
  WebUI **没有** persist 的：`mailStore`(0) / sessionStore(0) / uiStore(0) / authStore(0)
  ⇒ **邮件与会话在 WebUI 也是不缓存的**，每次打开都从服务端拉。
鸿蒙侧：AppearanceStore / AccountManager 有 preferences 持久化，MailStore 没有
  —— 与 WebUI 对齐，不是缺口。

## 判据

`harmony-logic` +1（35 条）：**列表行必须把 onClick 挂在自己身上**。
钉的是不变式（"行自带点击"），不是某个函数的写法：
`MailRow` / `SentRow` 的属性链里必须有自己的 `.onClick` 且调到 `openMail`。

变异：删掉 `SentRow` 的 `.onClick`（重演原 bug）→ 判据红；还原 → 绿。

套件：harmony-logic 35/35、harmony-nav 22/22、harmony-appearance 28/28、
harmony-contacts 5/5、animation-audit 15/15。
 2026-09-24 14:35:07 +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
25e7d8f3bf 跨端: 补附件区（两端一直都有这个功能，我上次误判成"死代码"）+ 修两个真 bug 
══ ① 更正我 2026-09-19 的一个**错误结论**（已写进 docs/DEBTS.json 留档）

那天我审计后写下：`GET /me/mail/inbox` 的回包**既没有 `attachments` 也没有
`has_attachments`** ⇒ `MailList.tsx:261` 的 `mail.attachments?.length ?? 0`
恒为 0、WebUI 那个 📎 是**死代码**。并据此在鸿蒙侧**有意不抄**这个标记。

**这个结论是错的**，错在取证方法：我**只看了一封没有附件的邮件**，
看到 key 不在，就断言服务端从不返回它。事实：
· 服务端 `GetInbox`（`mail.go:586`）**明确调了 `fillAttachments`**，注释还写着
  理由：「Agent 靠收件箱列表得知有哪些附件可下载，否则它不知道该调 attachment_id」
· `Mail.Attachments` 的 tag 带 **`omitempty`** ⇒ **没有附件的邮件根本不输出这个 key**

实测 `limit=200`（96 封）：带 `attachments` 的 **2 封**，正是真有附件那两封。

★ 教训：**`omitempty` 字段的"缺失"不等于"服务端不返回"**。
  判「某字段有没有」必须拿**确实有值的那条**去验，而不是拿一条恰好为空的数据。
  这与同一天那个白屏崩溃（`session_workspace` 缺失 → `undefined` → 抛）
  是**同一个坑的两面** —— 那天是"缺失 → 客户端崩"，今天是"缺失 → 我误判成不返回"。

══ ② 补附件区（鸿蒙原来完全没有）

· `model/Attachment.ts`（新）—— `formatSize` / `attachmentLabel`，纯逻辑无 SDK 依赖，
  逐字对齐 WebUI `api/client.ts:390`（三档 + 保留一位小数）。
· `MailApi.downloadAttachment` —— 走 `getBytes`（不是 `get<T>`：后者假定 JSON，
  取二进制会炸；壁纸当初踩过）。
· `IcsFile.saveBinaryFile` —— 与既有 `saveIcsText` 同一套流程，只是写 `ArrayBuffer`。
· `MailDetailPage` 正文之后渲染附件清单（回形针 + 文件名 + 大小 + 下载），
  位置/形态对齐 WebUI `Attachments.tsx`（无附件时**整块不渲染**）。
· 列表行的 📎 + 数字（`attach_count`，与 `cc_count` 同形状派生）。

══ ③ 顺带撞出并修掉两个**真 bug**

**bug A（差一点就是 94/96 必崩）**：我第一版写 `mail.attachments.length` ——
而 `Attachments` 带 `omitempty`，96 封里只有 2 封有这个 key ⇒ 其余 94 封是
`undefined` ⇒ `.length` 抛。**与当天早些时候那个白屏崩溃是同一个坑，
我刚修过、还在 `Models.ets` 里写了一大段注释，然后加新字段时照踩。**
⇒ 说明"记住别这么写"不管用，要在每个真正读的地方把 `?? []` 写出来。

**bug B（潜在白屏）**：`PermissionTab` 读 `req.session_alias` ——
而服务端 `PermissionRequest` struct **根本没有这个字段**（`models.go:239-255`），
`ListPendingPermissionsFor` 的 SELECT 也没查它，WebUI 的类型里同样没有。
它是我照"授权卡总得显示会话名"的直觉加出来的。⇒ 恒 `undefined`，
一旦有待办就抛。**一直没暴露只因为当前待办数一直是 0**（实测 `{"requests":[]}`）。
⇒ 改成服务端确实有的 `agent_name`，并**删掉那个字段声明**：
让误用变成**编译错**，而不是运行时白屏。

同样是 `body_preview`（`omitempty`，值是 `Body` 的截断）——
空正文 ⇒ 空串 ⇒ 服务端省略 key ⇒ `undefined.length` 抛。那批 96 封恰好都有正文，
所以"看起来没问题"——那正是这个坑的形态。已加 `?? ''`。

══ ④ 新判据：`omitempty` 字段的读法（形状，不是实例）

从 `server/internal/models` **算出**"只以 omitempty 形式出现过"的字段名
（不在判据里手抄名单），再扫鸿蒙侧对它们的裸成员调用。
★ 关键：**不能按字段名一刀切** —— 我第一版就是这么写的，报了 6 处、4 处误报：
  `session_alias` 在服务端有**两个**声明（`Mail` 上带 omitempty、`repo.Contact` 上不带），
  鸿蒙那 4 处读的全是 `Contact` ⇒ 恒有值、不是 bug。
  ⇒ 只扫"从未不带 omitempty 出现过"的名字，那 4 处自动排除。
已逐个核实 4 处豁免（每条都写了取证理由，不是"看着像就放过"）。
变异验证：把 `?? []` 去掉 → 判据转红，且**正是**报 `MailStore.ets: mail.attach_count = mail.attachments.length`。

══ ⑤ 数据路径已实测（模拟器）

临时把 `INBOX_PAGE_SIZE` 提到 200（因为有附件那两封在下标 51/52，
默认 limit=50 **根本取不到** —— 这也解释了为什么之前一直没发现），
加临时 hilog 后拿到：
    AttProbe: mail=531a1629-… attach=1
    AttProbe: mail=b68cbbe8-… attach=1
正好是那两封。验完已撤掉探针、`INBOX_PAGE_SIZE` 恢复 50。

══ ⚠️ 本轮**未能**完成设备端视觉验收

模拟器已卡死（`hdc` 能连上但 `shell` 超时；进程 152% CPU、已跑 32 小时），
导致套件里的设备判据各跑 836 秒后失败（"要能拉起应用"）。
主机可用内存只剩 ~3.7GB。附件区的**渲染**（清单外观、下载落盘）
尚未在设备上看过 —— 待模拟器恢复后补。
 2026-09-20 21:14:20 +08:00
JianFeeeee
f604badf86 判据: 三条判据锚在"实现位置"上，A 步搬家后假红 —— 改成锚不变量 
用户裁定做 A（harmony 补 store 层）之后，`harmony-logic.test.mjs` 红了 4 条。
**一条都不是 bug**：它们读 `pageCode`（`MainPage.ets`）找那些调用，
而调用已经搬进 `common/MailStore.ets`。

这正是本仓反复出现的形状：**判据锚在实现位置上，而不是它声称的东西上**。
一处实现搬家（哪怕搬得更对）就假红 —— 而假红比漏报更坏，
它会让人去改本来对的代码。

★ 修法：引入 `compositionCode`（页面 + store 合起来看），按**归属**拆断言
  · **取数/组装**（谁调 `sumUnreadTotals` / `partialLoadNotice` /
    `groupMailsBySession`）→ 读 `compositionCode`
  · **渲染**（用户看到什么：单封平铺、多封按展开态、组头可点、卡片视图）→ 仍钉 `pageCode`
    （那是页面该管的事，不该被搬走）
  不变量是"这条纯逻辑真的被用上了"——**用它的人搬去哪一层不该让判据红**。

★ 顺带修掉一条**自己骗自己**的断言（变异测试抓出来的）
  「先分家再折叠」原本写成 `splitAt < groupAt` 两个 `indexOf` 比大小，
  并断言两个都 `>= 0`。我把顺序反过来做变异 —— **它没红**：
  因为反过来之后第二个字面量变了、`indexOf` 返回 -1，红的是"两个都 >=0"
  那条，而不是顺序那条。也就是说：**顺序这条判据从来没在判顺序**。
  改成直接断言**数据流形状** `groupMailsBySession(split.normal)` ——
  它同时表达"折叠的是筛过的那批"与"必须先分家"。再变异（换成 `mergedMails`）
  ⇒ fail=2，这次真的咬住了。

★ 判据 14 也从一条拆成两条（取数侧 / 渲染侧），名字改成
  「折叠逻辑真正接上了（不是"逻辑写好了没人用"）—— 取数侧 + 渲染侧都要在」。

harmony-logic 32/32 绿。注册数不变（拆一条加一条，净持平 32）。
 2026-09-20 11:34:44 +08:00
JianFeeeee
6ca0113fd2 跨端: 统一顶栏组件 + 按压反馈（真跑通）+ 滑动判定从"时长门"改"速度门" 
用户四条意见，逐条都是真问题，且**两条是我写完没生效**：
  ① 「所有的顶栏都应该应用玻璃圆框效果」② 「抽象一个统一的顶栏组件出来吧」
  ③ 「你不觉得发件箱太大了吗」④ 「各个组件带响应点击、滑动等的动画了吗」
  ⑤ 「还有转场动画呢？」⑥ 「还有其他行为都要一一对齐，例如邮件展示页面」

★ ① ② 统一顶栏 `AppHeader`
  改造前**六处各写各的**：`AdminUsersPage`(40×40 返回键+16 号标题)、
  `SettingsPage`(20 号标题+40×40「＋」+**实心 Theme.surface**)、
  `MailDetailPage`(36×36 + 14 号标题，行高只有 14px 被裁过)、
  `MainPage.SentTab`/`PermissionTab`(通栏、无圆角)、`CommTabBar`。
  尺寸(36/40、14/16/20)、底色(实心白/透明/无)、返回键(有/无)三类都不一致；
  且四处用 `Text('‹')` 当返回键 —— **用字符当图标**（本仓明令禁止，字形随字体变、
  基线对不齐），而 `ICON_PATHS` 里**早就有** `chevronLeft`。
  ⇒ 抽成 `AppHeader`（返回键 + 标题 + `@BuilderParam` 右侧动作区），
    几何复用底部条常量，材质走 `Theme.navMaterial`。已接入 5 处。
  ★ `topInsetPx` 由调用方传：状态栏避让是**窗口级**事实（属页面），
    组件自己读会变成"每层各加一次"（平板侧栏 83+83 双计就是这么来的）。

★ ③ 发件箱"太大"—— 我的理由错了
  我第一版让 `HEADER_HEIGHT = NAV_BAR_HEIGHT`(56)，理由是"顶栏与底栏同在一根
  竖轴上，高度不同会一眼看出来"。**那个理由不成立**：
  底栏是**两行**（图标+文字标签）⇒ 需要 56；顶栏只有**一行标题** ⇒ 56 里一半是空白。
  实测 `Row [277,315,1105,476]` = 161px = 56vp，标题那行只占 54px。
  "两根轴上的条要一样高"是把**对齐**理解成了**等高**。真正要对齐的是**左右留白与圆角**。
  ⇒ `HEADER_HEIGHT = 44`（= 可点区下限，返回键装得下）。

★ ④ 按压反馈 —— 两次失败才跑通，两个坑都记进注释
  · **坑一**：`.attributeModifier()` **一个组件只能挂一个**，链两个是**后者覆盖前者**。
    会话组头卡同时挂了玻璃与按压反馈 ⇒ 只生效一个，**编译器不报错、运行不提示**。
    WebUI 是 CSS，类名天然叠加；ArkUI 是单一插槽，"叠加"必须显式做
    ⇒ 新增 `CompositeModifier`。
  · **坑二**：`applyPressedAttribute` **只对自带按压状态机的组件**（`Button`）回调。
    实测：挂 `Button` 上 → hilog 有输出；挂只有 `.onClick` 的 `Row`/`Column` 上
    → **一次都不回调**（按下与常态逐像素相同 `239,244,255`）。而全仓 117 处
    `onClick` 的主体正是纯 `Row`/`Column` ⇒ 那条路对本仓没用。
    改用 `onTouch` + `animateTo`。
  · 底色用**系统点击效果色** `ohos_id_color_click_effect`（不是我自己挑的）：
    第一版用 `Theme.surfaceMuted`，实测只差 `3/3/3`，肉眼看不出 ——
    因为"一块面的颜色"与"按下时叠的提示色"在系统色板里是**两个不同语义**。
  设备验证：`onTouch type=0`(Down) → `type=1`(Up) 成对到达，像素确有位移。

★ ④ 滑动判定：从「时长门」改成「速度门」（**设计错误，不是调参**）
  旧门 `SWIPE_MAX_DURATION_MS = 700`（"整个手势超 700ms 就拒"）。
  而**时长 = 距离 ÷ 速度** —— 它把两个量混成一个 ⇒ 同样的手速下
  **滑得越远越容易被拒**，屏幕越大越严重（平板同一手势像素更多）。
  设备实测（3184×2232，位移恒 542.6vp）：
      600px/s→5909ms | 1200→3161ms | 1800→2006ms | 2500→1429ms | 5000→616ms | 15000→123ms
  ⇒ 旧门意味着**只有 ≥5000px/s 才过**，而那一档重复测试也只有 2/4 成功
    —— 用户报的"滑不动/时灵时不灵"就是这个。
  改 `SWIPE_MIN_SPEED = 0.25`（vp/ms，取自上表两档中间）后实测：
      1200px/s → 0/3（正确拒绝：那是拖动）    2500px/s → **0/4 → 3/3**
      5000px/s → **2/4 → 3/3**
  两条判据跟着改形态（**语义不变**：都是"够快才翻页"）：
  · `cross-client-gesture` 断言"算的是 dx/ms"——只断言"有个门"会漏掉这次的错
    （旧的时长门**存在**、常量**有名字**、数值**是正数**，三条全过，而真机拒掉正常滑动）；
  · `harmony-logic` 的行为判据加了两条**回归钉**：
    `542.6vp/1429ms`（实测的正常甩动）必须过；
    `1200vp/3000ms`（同速度、更远）也必须过 —— 旧门正是在这里误拒。

★ ⑤ 转场动画：查清了，"不做页面级"是**决定**而不是漏做
  WebUI `index.css:1230` 写明：页面级淡入会让**已在那儿的框架**也一起暗一下
  （"观感还是闪"），且用户 2026-09-14 **亲口否掉过**"整屏一起淡"，
  所以那一档整体删掉，只保留**局部**动效。鸿蒙侧当前是：
  · `pushUrl` 推页 → **系统自带的滑动转场**（连拍 8 帧验证：第 3 帧能看到
    写信页正在覆盖发件箱，是真实的横向滑入，不是硬切）；
  · 局部入场 → `paneRiseIn` / `menuIn` / `calendarSlide`（已接 12 处）。
  所以"加 pageTransition"反而会与用户当时的否决冲突 —— 这一条**不做**，
  理由记在这里，免得下次又当成遗漏。

判据：files=32 ran=32 checks=519 pass=519 fail=0 red=0；baseline 7/7✓。
 2026-09-20 10:51:28 +08:00
JianFeeeee
ac62dafde1 跨端: 往返预算编辑上线（详情页缺的第三块）+ 修折叠头部点不中的真 bug 
审计发现详情页缺三块功能之三：**往返预算**（WebUI `BudgetEditor`）。
`MailApi.setBudget` 早就有了，缺的是 `getBudget` 与 UI。

## 一、预算条（对齐 WebUI，两态）

显示态是徽标（`已用/上限 来回` / 不限时「预算不限」/ 用尽时标红），
点它进入编辑态：输入框 + 保存 + 重置 + 取消。

★ 「用尽」的判定**走服务端的 `remaining`**，不自己拿 `used >= max` 算：
不限时服务端给 `remaining: -1`，那个式子在那种情形下会算出"已用尽"。
两端都得用服务端的口径。

★ 「保存」与「重置计数」走**同一条 PUT**（服务端支持两者同时给，
它的注释原话：「加到 20 并从头算」是一次很自然的操作，
拆成两个请求只会让前端多一次往返）。

**契约实测**（不是形态检查）：
    GET  → {"max_rounds":0,"used_rounds":1,"remaining":-1,"unlimited":true}
    PUT {"max_rounds":7,"reset":false} → {"max_rounds":7,"remaining":6,"unlimited":false}
    PUT {"max_rounds":0,"reset":false} → {"remaining":-1,"unlimited":true}      ← 0 = 不限

## 二、真 bug：折叠头部的展开区只有 **14px** 高

设备实测 dump：`Row [1277,112][3122,126]` —— 可点区高度 = 文字高度（14px 字号）。
而全屏之后**状态栏也在 y=112 那个区间** ⇒ 点它反复触发**系统手势（下拉通知）**
而不是展开头部。我为此试了七八次，每次都回到桌面。

而收起态头部里藏着**这个会话的全部旋钮**（收件人/时间/抄送/权限档/预算）——
点不中就等于那些都看不到。

修：给那一行 `height(36)`（与左边返回键同高）。实测可点区
**14px → 43px**（`[1277,112][3122,155]`）。

★ 判据 + **变异验证**：去掉 `.height(36)` ⇒ 判红；还原 ⇒ 绿。

## 三、判据

`harmony-logic` 新增「折叠头部展开区高度 ≥32vp」一条（含变异自检）。
`run-all.mjs` → `checks=511 pass=511 fail=0 skip=0 red=0 broken=0 unreported=0`。

**未验**：预算条在设备上的**观感与点击**（模拟器顶部 155px 是系统手势区，
而头部恰在其中 —— 坐标式点击在那里会被系统抢走；真机上头部在状态栏之下）。
预算条的**数据链路**已用 curl 逐条实测（见上），但"点保存按钮后徽标变化"
这一步没在设备上走通。
 2026-09-19 17:41:09 +08:00
JianFeeeee
e79a86ab79 跨端: 改名建议条接到详情页（端到端实测：点「接受」别名真的改了） 
上一批做完了接口层，这批接 UI —— 详情页现在真的显示建议条并能操作。

## 做了什么

提示条放在正文之前（与 WebUI 同位置）：Agent 给的理由 + **后果说明**
（「改名后需用 name@path.xxx 寻址；旧别名立即失效……」）+ 「接受」/「忽略」。
蓝底（`accentSoft`）而不是警告色：它不是故障，是一个**待决定**；
深色下走 `accentSoftFor`（就是前一批修的那个主题感知浅底）。

`doAcceptRename` 走 `PUT /sessions/{id}/alias`（与"人手改别名"同一端点），
`doDismissRename` 走专用 dismiss 端点 —— 服务端记下被驳回的别名，
否则每次打开会话都要重新点一次「忽略」。

## 途中三处**我自己的**错误（都值得记）

1. **写错了请求体字段名**：我按记忆写成 `session_alias`，而服务端
   `updateAliasRequest` 的 tag 是 **`alias`**（`sessions.go:95-97`），
   WebUI 也是 `{ alias }`（`client.ts:537`）。而它的 `Decode()` 是
   `DisallowUnknownFields()` ⇒ 传错名字**直接 400**（不是"被忽略"）。
   这是今天第三次同源错误（`AppearancePayload` / `ForwardMailRequest` / 这次）——
   **请求体字段名必须去服务端 struct tag 里读，不能凭记忆写**。

2. **判据跟着实现一起错**：我把判据也写成"断言 `session_alias: alias`" ——
   等于把这处错误**锁进两处**。判据已改成断言 `this.alias = alias`，
   并加了一条反向断言"不许出现 `session_alias: alias`"。
   ★ 这是"判据引自己的实现当依据"的又一次实证。

3. **UI 写完忘了接数据**：提示条的 UI 做完、编译过，但**没有调用
   `getRenameProposal`** ⇒ 页面上永远不显示（服务端明明有建议）。
   —— 正是本仓反复出现的"写好了但没人调用"：静态判据查得出"代码里有这个方法"，
   查不出"页面从没调过它"。
   ⇒ 补上 `loadRenameProposal()`，并**单独一个 try**（建议条是附加信息，
   它失败不该把正文也变成错误态）。

## 端到端验证（真数据）

造一封带标记的真邮件投进一个真会话 → 服务端识别（`rename_proposed: "rename-verify"`）
→ 详情页出现建议条（dump 读到理由 + 后果说明 + 两个按钮）
→ 点「接受」→ 库里别名真的变了：

    处理四桥冒烟测试邮件  →  rename-verify

## 判据

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

**未验**：「忽略」按钮的端到端（服务端记下驳回、不再重复弹）——
接口层已有判据钉住路径，但没在设备上真点过。
 2026-09-19 17:23:23 +08:00
JianFeeeee
c2f35d1023 跨端: 会话改名建议的接口层（详情页缺的第二块，服务端三个端点齐） 
审计发现详情页缺三块功能之二：**Agent 的改名建议条**（WebUI `MailView.tsx:324`
的 `RenameProposalBar`）。这一批做**接口层**，UI 接线下一批。

## 为什么这件事不只是"少个提示条"

WebUI 那段的注释写得很清楚：

> Agent 干到一半自己改掉，人上一秒记住的地址下一秒就失效。
> 提议 + 人确认，既让 Agent 表达意图，又保证寻址稳定性由人掌握。

也就是**寻址稳定性**的设计 —— 别名是人的寻址入口，Agent 只能**提议**。

## 做了什么

1. `model/SessionRename.ets` —— `RenameProposal`（`alias` / `reason`，
   字段名与服务端 json tag **逐字对齐**）
2. `api/SessionApi.ets` —— 三个动作：
   · `getRenameProposal(sessionId)` → `{"proposal": {...}}` 或 `{"proposal": null}`
   · `acceptRename(id, alias)` → **`PUT /sessions/{id}/alias`**
   · `dismissRename(id)` → `POST /sessions/{id}/rename-proposal/dismiss`
3. 判据（`harmony-logic`，+1 条）：字段名、响应外壳容忍 `null`、
   接受走别名端点、驳回走专用端点、方法名与 WebUI store 同名、+ 变异自检。

★ **接受为什么不另开端点**（服务端注释原话）：
「那条路径已经有唯一性校验与 409 处理，复制一遍只会多一个出错的地方」。
所以"接受建议"与"人手改别名"是**同一条路**，而"驳回"是另一条
（它不是改别名，是"别再问了"——服务端记下被驳回的别名，
否则每次打开会话都要重新点一次「忽略」）。

## 端到端验证（真数据，不是形态检查）

造了一封带标记的真邮件投进一个真会话：

    POST /mail/send {reply_to: …,
      body: "内容正文。<!-- agentmail:rename-session alias=\"rename-verify\" reason=\"验证改名建议链路\" -->"}

    → 200 {"rename_proposed":"rename-verify", …}

然后：

    GET /sessions/{id}/rename-proposal
    → {"proposal":{"alias":"rename-verify","reason":"验证改名建议链路"}}   ✓ 形状与我的一致
    SELECT body FROM mails …
    → "内容正文。"                                                        ✓ 标记被剥掉

两件事都验到了：**服务端识别建议**，且**标记从人读的正文里剥离**
（HTML 注释在 Markdown 渲染器里会变成可见文本，所以必须剥，不能指望渲染器吞掉）。

## 判据

`run-all.mjs` → `checks=510 pass=510 fail=0 skip=0 red=0 broken=0 unreported=0`。
`harmony-logic` 30 → 31。`hvigorw assembleHap` 成功；前端重建 + 重打包。

**未做**：UI 接线（详情页的提示条）。接口层已完成并验证，
但"页面上真的显示建议条并能点接受/驳回"要下一批。
 2026-09-19 17:12:40 +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
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
2e53871a22 fix(harmony): 底栏真正浮起 + 内容穿过 + 加回文字标签 
用户（2026-09-17）：「底栏不是玻璃质感，滑动内容无法穿过底栏」，
随后「还是在导航栏加上文字吧，没有文字还是不好看」。

── ① 底栏没浮起：`width('100%') + margin` 在 ArkUI 里不缩宽 ──
NavBar 原来是 `Row().width('100%').margin({left:16,right:16,bottom:12})`。
ArkUI 的 margin 加在宽度**外面**：100% 再配左右 margin 不会缩到
「100% − margin」，而是整个顶出父容器、两侧被裁。
实测底栏左缘 x=0、右缘贴满 1256（应各留 16vp=56px）⇒ 看起来是贴边通栏，
不是浮在壁纸上的胶囊。这与收件箱头卡片修过的是同一个坑。
改法：外层 Column 带 padding（与 WebUI `.narrow-nav` 的 margin 同一几何）。
实测修复后左缘 x=56 = **16.1vp**（期望 16）。

── ② 内容穿不过去：让位加错了层 ──
原来把 `NAV_CONTENT_RESERVE` 加在**窗格的 `padding({bottom})`** 上。
那不只"让最后一行滚得出来"，还**缩短了窗格本身** ⇒ 内容永远到不了条底下
⇒ 玻璃条背后只剩一张已经被壁纸层模糊过的壁纸 ⇒ 系统材质无东西可糊
⇒ 看起来就是一块普通浅色面板。**这就是"不是玻璃质感"的真正原因**。
改法：窗格满高（内容滑得到条底下，真正穿过），让位改到各滚动容器的
**内容末尾** `contentEndOffset(this.navReserve)`（5 个 List + 日历日程），
与 WebUI 同构（`.narrow-shell` 是 flex-col，列表满高、`.narrow-nav` 叠在上面）。
实测：条内高频细节 0.21 vs 条外正文 6.04 ⇒ **28.8×** 衰减，模糊确实生效。
连带修：FAB / 回复球原来靠窗格 padding 躲开条，现在自己按 navReserve 抬
（否则压在条上），实测 FAB 底距条顶 24.4vp。

── ③ 加回文字：并纠正一处**事实错误** ──
代码注释里写着「WebUI 的底部导航是**纯图标**」，并据此去掉了文字。
那句是**错的**：`NarrowNav.tsx:83-86` 每个导航项是
`flex flex-col items-center justify-center gap-0.5`，里面先 `<Icon />`
再 `<span className="text-3xs leading-none">{short}</span>`
—— WebUI **一直有文字**（通信 / 日历 / 联系人 / 我的）。
那条判据把一个假事实固化成了规则，还反过来挡住了正确做法。
现在按真实契约钉：图标（24vp，与 WebUI 24×24 同几何）+ 文字，
两者过**同一个**选中三元式（只换颜色，不加背景/指示条）。

判据（全部含变异自检）：
· ⑤ 重写：两处选中三元式（图标+文字各一）、必须有 Text(item.label)、
  图标 24vp；变异自检覆盖"缺文字 / 文字不换色 / 图标不上色"。
· ④ 改：留白走外层 padding（并反向禁止 margin 做留白）；
  让位改为 ≥5 处 `contentEndOffset`，并禁止退回窗格 padding 让位。
· 连带更新 ②/⑤ 与 appearance/logic/widescreen 的组件签名断言
  （组件多接一个 navReserve）。
· 删掉一段会假红的"从内容层 `}` 往后扫"的窗口式断言：它靠数花括号定界，
  而注释里就有大量 `.padding({` 字面量，切片能长到 1700+ 字符，
  一路扫进 `onAreaChange`（那里合法地出现 NAV_CONTENT_RESERVE）——
  正是本仓库反复记的窗口式判据，故改为纯负向断言。

测试：212 passed / 0 failed；`devecocli build` 通过；
模拟器截图与像素测量逐项核对。
 2026-09-17 18:44:36 +08:00
JianFeeeee
ff75339baa fix(harmony): 图标按 px→vp 正确缩放 + 底栏四入口 + 卡片 10vp 缩进 
图标过小的根因（实图硬证）：`Path.commands` 的坐标按 **px** 解释，不是 vp。
- `Shape.viewPort` 只裁剪不缩放（官方样例"缩放成立"是因为它用 Rect/Circle
  自带 vp 宽高，不是裸 Path.commands）；
- 改动前的 `Path.scale({iconSize/24})` 对 iconSize=24 等于 1.0，同样没缩放。
  症状：FAB 内 compose 只画 24px（应 24vp=84px），且偏在盒子左上角。

修法：`scale({vp2px(iconSize)/24})` 把 24 单位路径放大到 iconSize vp；
`scale` 会连带放大描边，故 `strokeWidth = strokeWeight / vp2px(1)` 抵消，
否则 1.8vp 描边会变成 ~7.3vp 的"实心块"（实图已验证）。
用 `this.getUIContext().vp2px()` 而非全局 `vp2px`——后者已废弃，
`harmony-system-api` 判据对全局调用默认判红。

验收（模拟器实图，密度 3.489）：
- FAB 内 compose 图标 84px = 24vp ✓（原 24px）
- 底栏图标描边 7-8px ≈ 1.8/24×28vp=7.3px ✓（原为实心块）
- 四个图标均为清晰描边，与 WebUI icons.tsx 同几何

底栏四入口：新增"我的"（person → pages/SettingsPage），对齐 WebUI
通信/日历/联系人/我的；NAV_CONTENT_ITEMS 保持宽屏侧栏三项，
避免宽屏出现重复 person 图标。

卡片缩进：`width('100%') + margin({left:10,right:10})` 在 ArkUI 里不会
缩到 90%——margin 加在宽度外面，卡片顶出父容器（实测左缘只留 ~1px，
列表卡才有正确 10vp）。改为外层容器加 padding。验收：页头卡与邮件卡
左缘同为 x=35（10.0vp）、右缘 x=1219。

推送：reportToken 先申请通知权限再取 token（部分设备权限未开时
getToken 返回空 / 报 1600004），并补两条文件形状判据钉住
client_id 配置与调用顺序。

测试：198 passed / 0 failed。
 2026-09-17 16:27:27 +08:00
pi
94ba4b9c58 跨端: 鸿蒙端功能同步第一步——日历（只读月视图）上架，入口进底部导航 
用户：「要给鸿蒙端做功能同步」。按 API 面盘点（WebUI 62 个 API 函数 vs 鸿蒙 38 个），
最大的用户面缺口是**日历**：纯逻辑（model/Calendar.ts）与判据早就在，一直没页面。

新增：
- api/CalendarApi.ets：GET /calendar/events?from=&to=（与 WebUI 同参；区间按**网格**取，
  不是月首月末 —— 首尾格子会显示邻月，只查当月会让那些格子永远空着）
- pages/CalendarPage.ets：月网格（翻月/回今天）、点某天看当天日程、事件点、今天/选中两态、
  加载失败说出来。**没做**：写侧（增删改）、农历重复、.ics、滑动翻页 —— 逐条写在文件头
- model/Calendar.ts：补 localIsoOf / hhmmAtOffset / deviceOffsetMinutes（偏移是入参 ⇒ 三时区可真跑）
- model/Models.ets：CalendarEvent / CalendarListResponse（字段对齐服务端 JSON）
- NavItems：加「日历」，底部成为 通信/日历/联系人 三项（与 WebUI 同序）
- MainPage：日历是**常驻 pane**（visibility 控制），首次可见才拉数据；today 走
  @Prop @Watch(visible) 在 pane 变可见时重算 ⇒ 结算欠账 calendar-today-recompute
  （DEBTS 15 笔 → 14 笔，余额里不再计这一笔）

判据：harmony-calendar 新增 6 条（网格/表头同源、事件归日走 localIsoOf、三时区钟点、
today 重算路径、翻月走 addMonths、变异自检）；harmony-nav ② 分派与 ④ 让位跟着改成结构性判据
（④ 原来那个 400 字符窗口一加 pane 就红 —— 窗口式判据的又一次现身）；harmony-logic 两处
「只剩两个平级页签」跟着改成三项。

真机实测（harmony-emu + hvigorw assembleHap + hdc install + uitest click + dumpLayout）：
9 月网格星期对齐（周一起始，2026-09-01 落在「二」列）、事件点恰好在有日程的那 6 天
（11/17/18/24/25/30）、点 09-17 列出当天两条日程且钟点是本地时间（DB 里 02:20Z/08:30Z
→ 界面 10:20/16:30）。
 2026-09-14 18:38:51 +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
962df62801 feat(harmony): P4b 预设档画法 + 壁纸真的渲染出来（并更正我上一轮"未验渲染"的说法） 
pi 复核时问了一个比上传入口更基础的问题：WebUI 的背景有**预设渐变**，
鸿蒙拿到 preset 名画得出来吗？只支持 image/none 的话，"换账号后外观跟随"
对预设档就是**不成立**的（用户设了预设，在鸿蒙看到的是没有背景）—— 信息对等缺口。

查下来比他说的更糟：**P4 第一版没有任何东西去画背景** —— `AppearanceStore` 取回了
`PixelMap`、算好了快照，但没有组件渲染它（预设更是完全没实现）。
上一轮我在文档里写的是"壁纸在真机上的**渲染**效果未验"，听着像"已经画出来了只是没上真机看"——
那是**说得比证据强**。取回像素这件事是真的（提交信息没写错），但"渲染未验"把"没做"说成了"没验"。
已在 §7.16 更正，并把这条记进文档以免后来人当成回归。

## 改了什么

- `model/Wallpaper.ts`（纯逻辑，判据直接跑）：6 个预设（id/中文标签/归一化）、色板、
  每个预设由哪些层叠出来、`resolveBackground()` 决定画什么（`image` 档但图没取回来 → 什么都不画）。
- `MainPage`：`WallpaperLayer` —— 预设用**系统原语** `radialGradient`/`linearGradient`；
  **网格档**（CSS 的 `repeating-linear-gradient`）系统没有对应原语 → 用系统 `Canvas` 画线
  （线色/间隔照抄 CSS），理由写在模块注释里；图片档 `Image(pixelMap)` + 系统遮罩色按服务端浓度压暗。
- **页面底让出**（这条不做，"画出来了"就是假的）：每个页面自己会刷一层**不透明**的系统页面底，
  壁纸会被全盖住。WebUI 侧的原话是「页面底 → 完全透明，让出背景；不改 27 个组件的 class，
  逐个加 class 必然漏（漏掉的那块就是一张不透明卡片浮在背景上）」。
  现在 `bgActive` 从主界面 → 通信页 + 联系人页 → 三个 pane，五个页面底全部让出。

## 判据（harmony-appearance 11 → 18 条）

预设 id/顺序/标签与 WebUI `PRESETS` 逐字一致；**预设色值与 CSS 调色板变量逐个对照**；
色板反向检查（登记了没用 → 红）；透明用关键字而非 8 位色值；三档 resolve 行为；
页面真的画了（三种系统原语 + 图片 + 压暗 + 铺在内容之下）；**页面底没有一处还在用不透明底**
+ 开关必须真的传到每个页面；模糊归属的互斥形式（壁纸层零模糊 / 导航条必须有系统材质）。

变异：预设少一档 → 红 2 条；preset 档不画东西 → 红；image 档图没取回来照样画 → 红；
色值写错两位 → 红；壁纸层加模糊 → 红；**五个页面里只漏一个没让出页面底 → 红**；
联系人页没收到开关 → 红。

## 判据抓到的真 bug

`--c-blue-200`（CSS：191 219 254 = `#BFDBFE`）我写成了 `#BFDCFE` —— 两位字母顺序反了。
"照 CSS 读出来比"才拦得住这类错。另外判据自己有两处切片毛病（用 `indexOf('build() {')`
两头夹会跨到别的成员上 / 断"注释里写了理由"却读了剥注释的源码），已改。

## 另外两件

- pi 撤回了他"模糊只由壁纸层负责"那句（那是 WebUI 的架构结论），按他给的两条性质
  （同一张底只糊一次 / 模糊该出现在背后是可变内容的层）写成互斥形式判据，记在 §7.18；
  并写明 WebUI 的"壁纸模糊度(px)"与鸿蒙的"材质档次"**不是同一个物理量**（§7.18 末）。
- **重打包**：pi 的 WebUI 补丁（c9717da / 2e42aac）重建了 `dist`（14:30），
  而安装包是 13:49 的 —— `packaging` 判据正确地判红。已按 BUILD.md 的写法重打 deb
  （`-c.electronDownload.isVerifyChecksum=false`；第一次不带这个参数时 electron-builder
  卡在下载校验上超时，失败原因如实记在这里）。

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（11 个判据文件全绿 + vitest 258/258）。
**未验**：预设渐变与图片壁纸在真机上的观感（尤其**深色模式**下预设的表现 ——
色板取的是 CSS 浅色档，深色档要不要另给一套，等真机看过再定）；
卡片面（系统 `surface`，不透明）盖在壁纸上是否该半透明 —— 也留到真机看，
但它不影响"背景可见"这条（页面底已让出）。
**未做**：P4c 壁纸上传入口（pi 定：算 P4 范围、不阻塞别的阶段，
做时按 WebUI 三条约束：先压缩再上传 / 失败必须给原因 / 上传后仍以服务端为权威）。
 2026-09-14 14:48:30 +08:00
JianFeeeee
73f886aea5 feat(harmony): P2b+P3 —— 「收件箱」改成「通信」（内部三栏 + 徽标 + 悬浮加号），发件箱与授权栏落地 
用户：「收件发件授权改为一个导航项，通过内部导航区分，然后新建作为他们内部的一个悬浮的圆形加号」。
所以这一期不是"再加两个页面"，而是对齐信息架构。

## 鸿蒙侧

- 底部第一项 **收件箱 → 通信**（`CommPage`），内部三栏 收件箱 / 发件箱 / 授权；
  页签下划线式（不是浮动白胶囊 —— WebUI 侧用户原话「通信页面的二级页面与其他位置极其割裂」）。
- **徽标**：收件箱红（未读）、授权橙（**待决策**）、发件箱无；0 不显示，>99 写 `99+`。
  合并成一个导航项后，底部看不到"授权有 3 个在等我"，这个信息不能丢 —— 它比未读更急。
- **悬浮圆形加号**挂到通信页这一层（三个栏都要能新建）；`⚙` 也搬上来（否则切栏就够不到设置）。
- **收件箱不再混权限邮件**（`splitByPermission`），未读按筛后算 ——
  WebUI 实测过"一个会话 17 封权限邮件挤掉另外两个会话"。
- **发件箱**：`GET /me/mail/sent`，与收件箱同构（同一套折叠/行），行上主角是**收件人**；
  空态有说明（主句与 WebUI 逐字一致「暂无邮件」+ 一句"这里放什么"）。
- **授权栏**（P3 主体）：`GET /permission/pending`（不从收件箱筛）+ `POST /permission/decide`。
  拒绝**可填备注且备注真的送出**；请求**过期**时当场说清「审批不会让那次调用继续」。
- 顺手删掉死代码：收件箱里「写邮件」的 `bindSheet`（`composeVisible` 从未置 true，谁也打不开）。

## 判据（harmony-logic 19 → 28 条）

页签键/顺序从 WebUI 源码抽取比对（`uiStore.ts` 的 `CommTab` + `CommTabs.tsx` 的 `TABS`）；
页签状态机（键↔下标往返、脏键/越界/非整数 → 回收件箱）；徽标规则（数字来源、0 不显示、
99+ 上限、红/橙与 WebUI 类名对应）；分家语义（决策过的不再算待决策、空串与 null 同义）；
三栏空态互不相同且主句与 WebUI 一致；接线（三个 pane 真的渲染、加号是圆形且在通信页、
"先分家再折叠"、接口路径与决策体三字段、拒绝传备注、过期分支）。

判据抓到一个**真 bug**：`commTabFromIndex` 只判范围，`1.5` → `COMM_TABS[1.5]` = `undefined`
（表现"点哪都不亮"）。已加 `Number.isInteger`。

变异验证（六种）：授权徽标看未读 / 权限邮件不分出去 / 类型名拼错 / 决策过仍算待决策 /
收件箱不分家 / 发件箱空态去掉说明 —— 全部判红。

## 排序说明

**日历暂时没有入口**：P6 的内容（网格 + 事件读写 + 滑动翻页）还没做，
先放一个点进去空着的入口比暂时没有更糟 —— 有意排序，记在 §7.15 以免被当成漏做。

## 验证 / 未验

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 退出码 0（10 个判据文件全绿 + vitest 258/258）。
**未验**：页签/徽标/悬浮加号在真机上的观感与点击 —— 需设备或模拟器（模拟器要人在命令行启动）。
 2026-09-14 14:13:45 +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
b3f404838b feat(harmony): P2a 收尾 —— 撤掉平级「会话」tab + 权限"强制力"上界面，判据 14→19 
## 撤 tab（按 pi 的顺序：先补视图与折叠，再撤入口）

底部只剩 **收件箱 / 联系人**。「会话」不是第三个地方，而是同一批数据的两种看法：
收件箱那栏按会话折叠（组头就是会话），联系人那栏的卡片视图是会话的进度视角。
依据是"信息没丢"，并且把它做成了判据：**卡片字段集与 WebUI `WorkCard` 完全相等**
（多一个少一个都红）—— 其中 `status`(active/archived) 与 `from_agent` 参考实现也不显示；
哪天 WebUI 补上，这条会红，提醒跟着补，而不是悄悄少一块。

## 权限"强制力"上界面（WebUI 有、鸿蒙原先没有）

只显示档位会让人以为 plan 档真的管住了对方。WebUI 把说明放在 `title`（悬停提示），
**手指没有悬停** —— 所以鸿蒙拆两步：标记形状当场可辨（● 平台强制 / ◉ 覆盖不完整 /
○ 仅提示），点徽标用 toast 说完整那句话。三条纪律落进判据：

1. 档位/强制力标签与 WebUI 的 `MODE_LABEL` / `ENFORCEMENT_LABEL` **逐字一致**；
2. **说明文案从 WebUI 源码抽出字符串逐字比对**（3 档 × 3 强制力全覆盖）——
   两个客户端对同一个任务不能给两种保证；
3. 认不出的强制力归一到 `advisory`（保守方向），空/未知必须说"仅提示"。

收件箱每封邮件里没有 `permission_enforcement`（会话级字段），故那里只写中文档位 ——
凭空画一个强制力标记等于编一个"平台做到了什么"。

## 判据自己不可信的两个坑（变异测试逼出来的，各修一次）

- **断言一律读剥掉注释的源码**：把 `showToast` 注释掉，正则照样匹配 ——
  注释里有某个调用证明不了它存在。
- **"在回调里"不能靠正则窗口**：`onClick` 体掏空、或把 toast 挪到相邻的 `onHover`，
  窗口式正则都会放过。改成**括号配对**取那个 `onClick` 的 `{...}` 体，只在里面找。
  两次变异现在都判红。

`harmony-logic.test.mjs` 19 条（原 14）；变异验证：改文案 / 改档位标签 / 页签改回「会话」/
注释掉 toast / toast 挪出 onClick / toast 写死文案 → 各判红。

## 文档

§7.9 记本轮；§7.10 记 jianf 追加的「鸿蒙要求用系统方案」：同意该理解，并补上**可离线校验**的
做法 —— SDK 自带系统资源名表 `sdk/default/openharmony/toolchains/id_defined.json`（7826 条），
其中正好有 `ohos_id_color_list_card_bg`（每项一张卡的底色）、`_list_separator`、
`_text_primary/secondary/tertiary`、`_emphasize`、`_warning`、`_alert`、`_mask_*`、
`ohos_id_blur_style_component_*_color`。**没有设备**，`$r('sys.*')` 写错在运行前发现不了，
所以先立一条判据：源码里的每个 `sys.*` 名字都必须在该表里查得到，再逐处替换。
`cross-client-theme` 的三个取值钉改"意图相同"**先与 pi 对齐、两侧一起改**（他已明确要求）。

## 验证

`hvigorw assembleHap` BUILD SUCCESSFUL；`npm test` 9 个判据文件（background 42 /
cross-client 8 / harmony-logic 19 / nav-merge 8 / build-stamp 4 / packaging 3 …）+ vitest 258。
视觉与点击仍未验（无设备，模拟器需人在命令行启动）。
 2026-09-14 13:51:35 +08:00
JianFeeeee
bb855b1518 fix(webui): 日历补上圆角 —— 外层面板圆了、里面的格子还是直角 
用户：「日历页面怎么没有圆角」。

原因与列表那次同源：**外层面板一直是圆的**（`.app-shell > *` 给了 14px），
但里面的日格/列写的是 `border-b border-r`（直角 + 细边框），而我早前为了修滚动
去掉了面板的 `overflow: hidden` ⇒ 里面的直角就戳在圆角外面，看起来"整页没有圆角"。

改法：日格、周视图列、以及日历的两个大面板都改用 `.glass-card`
（圆角 14px + 白色玻璃 + 细边框），与列表项、顶部气泡同一套语言。
顺手去掉日格上的 `overflow-hidden`（它会把事件条裁掉，而"裁掉"正是这几轮的老毛病）。

实测（自有浏览器，壁纸开）：日历里 **42 个 `.glass-card`**（月视图 42 格 + 面板），
格子 `border-radius: 14px`、底色 `rgba(255,255,255,0.78)`。

（这条同样是"外层圆角 + 内层直角"这一类问题 —— 我已经在列表、顶部、日历上
各修了一次。要找根因的话：**面板圆角不能靠 `overflow: hidden` 裁**（它会杀滚动），
所以每一层自己都要圆角。这是这套"浮动面板"设计的固有代价，写在这里备查。）
 2026-09-14 13:47:58 +08:00
JianFeeeee
3729afd96f feat(harmony): P2a —— 收件箱按会话折叠 + 联系人页卡片视图（判据直接跑同一份逻辑） 
按 pi 的结论落地 P2a 的前一半：**先补视图与折叠，再删平级「会话」tab**（tab 本轮保留）。

## 判据怎么"点用户真正会点的那一层"

鸿蒙侧没有设备（`hdc list targets` 为空、模拟器在本机沙箱下起不来），"点一下"暂时
无法自动验。应对不是编个能过的新判据，而是把会点的那一层的内核抽成纯逻辑：
`entry/src/main/ets/model/MailGrouping.ts`（无 UI 依赖），判据用 node 的
`--experimental-strip-types` **执行同一份代码**（`test/harmony-logic.test.mjs`，14 条），
断言的是行为而不是"源码里出现过某个字符串"：

- 折叠后组头是不是**最新一封**、组内是否时间倒序、组间排序、同一时刻用 `mail_id` 倒序兜底；
- 时间解析失败**不能让顺序依赖入参**（WebUI 侧踩过的 NaN 比较坑）；
- 多账号合并下同名 `session_id` 不能被错并成一组；`session_id` 缺失时各自成组；
- 预算档位与 WebUI `BudgetChip` 完全一致（剩 0 用尽 / ≤1 将尽 / 上限 0 不显示）；
- 视图切换与卡片上"最新一封是人还是 Agent"的判据。

页面那一层另用源码判据钉"确实调了这些函数"，两层合起来覆盖「逻辑对」+「页面接上了」。
**变异验证 4 处全部判红**：去掉组内排序（2 条红）、预算阈值 `<=1` 改 `<1`、
分组键去掉账号前缀、页面不再区分单封组。

## 收件箱折叠

- 组头取组内最新一封的别名与主题，带未读数徽标与「N 封」，点它展开/收起；
- **单封不成组、平铺**（与 WebUI `isFlatGroup` 同结论：给孤立一封信套组头只是多一次点击）；
- 多账号是鸿蒙特有：分组键带账号前缀；`session_id` 缺失按 `mail:<id>` 各自成组。

## 顺带修掉一个"看起来是总数、其实是未读数"的显示

`/me/mail/inbox` 的 `total` 是 **`CountUnread`（未读总数）**，不是总封数
（`server/internal/handler/me.go`）。鸿蒙底部原写「共 N 封」⇒ 同一屏出现
「共 7 封」和「未读 7」两行自相矛盾的字。改成：未读数用服务端 `total`（权威，
原来数这一页会少报）；「共 N 封」→「已加载 N 封」；**这一页取满时如实提示
「已加载 50 封（本页上限 50，可能还有更多）」** —— 客户端没有可信总封数，
就不能把 50 封说成全部（pi 提醒的"别让只取 50 封伪装成只有这么多会话"）。
WebUI 侧不读这个字段，故只影响鸿蒙。

## 联系人页补卡片视图（撤 tab 的前置）

- 右上角切列表/卡片，标题「联系人」/「工作列表」（与 WebUI 同词），切换规则在
  `nextContactView()`；
- 卡片对应 WebUI 的 `WorkCard`：Agent 名 + 工作目录 + 未读徽标、会话别名、
  **主题当主角**、最新摘要 + 人/Agent 标记、`N 封 · 时间`、权限档位徽标、
  **往返预算条**（同一档位判据）。
- 平级「会话」tab 暂留：撤 tab 按 pi 的顺序排在后面单独一步（撤早了预算/status/from_agent 没处看）。

## 验证

- `hvigorw assembleHap` **BUILD SUCCESSFUL**（`.ts` 纯逻辑模块被 `.ets` 引用，实测可行）。
- `npm test` **退出码 0**：窄屏布局全通过、主题 30、背景 34、cross-client 8、
  harmony-logic 14、packaging 3、vitest 258/258；新判据已接进 `npm test`。
- **视觉与点击仍未验**（无设备）：展开手感、卡片间距、组头命中区没有任何自动判据
  能代替人眼 —— 交付按"结构/逻辑已验证、观感未验"写，未写成已完成。
 2026-09-14 13:36:05 +08:00