9d40816230df4e7276022d7611b059b710c0a666
6 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
| 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✓。
|
|||
| c0ab3f57b2 |
跨端: 顶部页签条改悬浮玻璃 + 深色压暗下限（修 8 处深色可读性）+ 手势判据自搭现场
用户：「顶部的收件箱发件箱和授权为什么不做成悬浮玻璃？」
问得对，而且它当时是**整页唯一一块实心白**。
★ 顶部页签条 → 悬浮玻璃
`CommTabBar` 原来写的是 `backgroundColor(Theme.surface)`（系统卡片色＝实体）。
上一轮把列表容器、卡片、底部导航条都玻璃化了，**唯独漏了这条** ——
它既不是卡片也不是容器，是"条状 chrome"，逐处修时最容易漏的那一类。
⇒ 现在与底部浮动条**同一族**：圆角 + 左右留白 + `Theme.navMaterial`。
★ 几何常量复用底部条的（`TAB_BAR_RADIUS = NAV_BAR_RADIUS`、
`TAB_BAR_SIDE = NAV_BAR_SIDE`），不各写一份 —— 两个数一旦分叉，
"同一条轴线上的两种条"就不齐了。为什么选悬浮而不是 WebUI 的"通栏无底色"
（WebUI 页签条自己**没有**底色，靠父面板的玻璃）也记在那个常量的注释里。
新增判据：页签条必须与导航条同族（不许实体面 / 要引 TAB_BAR_* 常量），
变异验证过（改回 `Theme.surface` 即红）。
★ 深色压暗下限 —— 本轮最重要的真 bug
玻璃让壁纸**真的透进卡片**之后，"浅壁纸 + 深色文字令牌"这个组合会在
**卡片内部**发生。设备实测（深色、aurora、压暗 37）：
「角色」ink rgb(183,195,211) on bg rgb(68,95,128) = 2.57:1
「创建时间」2.27:1、「状态」2.68:1、「压暗」2.19:1（共 8 段 <3:1）
而**同一套代码在浅色下全部达标** ⇒ 差别不在"选错了色"，在"底没暗下来"。
WebUI 早就撞过并写下了必然值（`index.css:442`）：
.dark { --bg-dim-min: 92%; } /* 浅色下是 0% */
background-color: rgb(var(--bg-scrim) / max(var(--bg-dim), var(--bg-dim-min)));
我们只有 `scrimOpacity(bgDim)`、**没有下限**。补上 `DARK_DIM_MIN = 0.92`
（浅色下用户设的值照旧生效，不忽略设置）。
复扫：低对比 8 段 → 通信 0 / 日历 0 / 联系 1 / 我的 1
（剩下两条经手核是扫描器的假阳性：近黑底上把抗锯齿暗像素当成了"墨"）。
★ 手势判据"没有自己搭现场"（套件红、单独绿）
`cross-client-gesture` 只保证"在月档"、**不保证在哪一月**，而它算的是
相对最初那一月的 delta ⇒ 前面某个判据（或一次失败的手势）把日历翻到 10 月后，
期望值就差一格。修法：先点「今天」归位到本月（该按钮语义就是"回本月"）。
验证：从 9 月起步、从 10 月起步，两种脏状态都通过。
★ 顺带确认手势本体是好的：`--speed 1500` 时 1000px 要走 670ms，
紧贴 `SWIPE_MAX_DURATION_MS=700` 而被丢弃；`--speed 3000` 两个方向都翻。
★ 判据基建：修掉一个**静默失效**的 API 名（沿用上轮的教训修法）
`Surface.ets` 里两处块注释内嵌了 `/* ... */` —— 会把块注释**提前闭合**，
于是后面的代码跑到注释外面（报"Use let instead of var"/"Invalid character"）。
本仓已有这条纪律（"当 `code()` 因注释里的 `/*` 吞掉 import 时，改注释文本"），
这次又踩了两处（`Surface.ets` 与 `Appearance.ts`）。
判据：files=32 ran=32 checks=519 pass=519 fail=0 red=0；baseline 7/7✓。
|
|||
| a18014e1e3 |
判据: 管理页设备判据（到期静态判据的第一条升级）+ 修设备判据基建的三个真 bug
`run-all.mjs` 的 `STATIC_ONLY` 里登记着 6 条"只能静态验"的判据，前提是
「本工作区能装、能点设备」。设备现在可用 ⇒ 它们**到期**了（欠账当场变红）。
这一批升级第一条：`harmony-admin`（用户管理页）。
## 一、新设备判据：管理页真的能打开、列表真的渲染
上面 27 条静态判据判的都是逻辑与接线形态。它们全绿时，
"管理页能不能打开、列表能不能渲染"**一句都没验过** —— 而它最容易坏：
路由注册对了但入口没接上、接口回来了但列表没渲染。
判据自己搭现场：拉起应用 → 进「我的」→ 滚到底 → 点「管理」→
断言真的在管理页（出现「新建用户」）且**渲染出用户行**。
## 二、途中撞出三个**判据自身**的 bug（都已修，都写了教训）
1. **`tapText` 从来没成功点过任何东西**（`lib/harmony-device.mjs`）
`findByText` 返回的是**数组**，我当单个节点用了 ⇒ `node.attributes` 恒
`undefined` ⇒ 恒返回 `false`。症状极隐蔽：调用方以为"没找到那个文案"，
实际是帮手自己坏了。修：从数组里挑，且**优先挑可点的那个**
（同名文案常常一个可点、一个不可点）。
2. **判据之间互相干扰**（新增 `backToMain`）
每个设备判据都是写操作，会把前台留在它操作完的那一页。`harmony-admin`
把人留在管理页 —— 那是 `pushUrl` 出去的独立 `@Entry` 页，**没有侧栏**
⇒ 后面的 `cross-client-gesture` / `harmony-appearance` 找不到侧栏、
双双 skip（skip 原因写的是"宽屏侧栏找不到"，看起来像功能没了）。
`launchOurApp` 解决不了（`aa start` 只切前台，不弹栈）⇒ 新增 `backToMain`。
3. **"找不到元素"要先分清是功能缺失还是判据没摆好现场**
本判据连栽四种形态，每一种都伪装成"功能缺失"：
· 锚点文案错（入口是「管理」，我按「用户管理」找 —— 后者只是说明的一部分）
· 元素在滚动下方（dumpLayout 只报可见节点）
· 文字节点不可点（`.onClick` 在包住它的容器上，ArkUI 的常态）
· **滚动步长跨过了它**（诊断打印现场才发现：停在了「系统通知」那一带，
而「管理」只占 ~0.04 屏，一次 0.2 屏的滑动必然越过）
⇒ 最后改成"**先滚到底、再小步回扫**"（只管往前找在不均匀列表上必漏），
并加了 `AGENTMAIL_ADMIN_DEBUG=1` 的诊断入口把现场打出来。
## 三、判据
`run-all.mjs` → `files=32 ran=32 checks=505 pass=505 fail=0 skip=0
red=0 broken=0 unreported=0`（连跑两次稳定）。
`harmony-admin` 27 → 28 条。`hvigorw assembleHap` 成功；前端重建。
**设备实测**：管理页从「我的」页打开，显示「管理 / 用户管理 3 / 新建用户」
与三行用户（jianf 管理员 / gui-lab 用户 / test 用户）。
**仍到期未升级**：`harmony-appearance`（已加 2 条设备判据，但登记里其余部分仍静态）、
`harmony-logic`、`cross-client-theme`、`appearance-defaults`、`harmony-imageprep`
—— 按"每条缺什么设备侧验证"逐条来，不为了消数字而凑。
|
|||
| f811c9887a |
跨端: 三个真 bug（外观保存 400 / 改档位界面不动 / 内容列溢出屏幕）+ 设备判据
这一轮从「全面对齐 WebUI 和鸿蒙」开始，先做设备层判据升级，结果**判据一上线就连撞三个真 bug**
—— 它们全都是静态判据照不到的形状：**数据对、界面不动**。
## 一、外观保存从来就没成功过（PUT 400）
`payloadFromLocal` 复用了 `AppearanceResponse` 当请求体，而那个类型是 **GET 的响应**：
带着 `has_image` / `image_bytes` / `saved`。服务端的 `Decode()` 是
`DisallowUnknownFields()`（严格，**有意为之**）⇒ **每一次保存都被拒收（400）**。
症状极隐蔽：本地 `@State` 立刻变 ⇒ 肉眼看着像成功了；只有看 hilog 的 HTTP 状态码
才发现 400。修法是加 `AppearancePayload`（**恰好**服务端 `models.Appearance` 的五个字段）。
★ 这是"两端共用同一个类型"的代价：请求与响应本来就不该同形。
★ 服务端严格是**对的** —— 它帮我们抓到了这个错误。修客户端，不是放宽服务端。
## 二、改了档位，页面背景一点不变（两层原因）
**第一层**：`SettingsPage` 存进 store 了，但 `MainPage` 的 `bgPlan` 只在启动时算一次，
之后没人动 ⇒ 发布一个 `AppStorage` revision（计数器，不是布尔 —— 布尔 true→true
不发变化通知），`MainPage` 用 `@StorageProp + @Watch` 接住。
**第二层（更隐蔽）**：接上之后**还是不动**。因为 `bgPlan` 是 `@State BackgroundPlan`，
而 **ArkTS 的 `@State` 观察不到类内部字段**的变化 —— 渲染读的正是
`this.bgPlan.kind` / `.layers`。hilog 一对证据同一次启动相差 100ms：
Appearance: sync: bgKind=preset … hasImg=true ← 数据是对的
Wallpaper: kind=none layers=0 active=false ← 渲染读到的还是旧值
修法：加 `@State bgContentRev: number`，每次算完 plan 就 +1，**并在 Builder 的
条件表达式里消费它**（ArkUI 按"这个 Builder 读了哪些 @State"决定是否重渲染；
只加计数器而渲染不读，等于没加 —— 判据同时断这两半）。
★ 同一个坑本仓出现过（`AppearanceStore` 的注释里写着这句），这次换了地方发作。
## 三、「我的」页右端内容被顶出屏幕（追了很久的 `56.000000` 之谜）
真相有**两层，两层都值得记**：
1. `dumpLayout` 里 `Slider` 节点的 `text='56.000000'` 是**无障碍文本**
—— 屏幕上根本没这串字（截图可证）。**dump 的 text ≠ 看得见的字**。
2. 真正的问题是那个**看得见的** `Text('56%')` 落在 `x=3250`，而屏宽 3184
⇒ **它在屏幕外**。用户只看得到滑杆、看不到数值。
根因：`MainPage` 里"侧栏 + 内容列"是 `Row` 并排，内容列写 `.width('100%')`
—— 在 Row 里 `100%` 是**父容器全宽**，与侧栏的 60vp **相加** ⇒ 必然溢出。
实测内容列 `[229,28][3357,2204]`，右边缘超出屏幕整整 173px（= 60vp）。
修法：改 `.layoutWeight(1)`（吃剩余空间）。修完实测 `[229,28][3156,2204]`，
`Text('56%')` 落在 `[3049,1803]` —— 屏内。
★ 为什么值得一条设备判据：**同一处错误在不同 pane 上表现不同**
（日历页自己算宽度就没露出来），很容易被当成"某一页的样式问题"去调。
## 四、设备判据基建（这一轮加的能力）
- `lib/harmony-device.mjs` 新增 `launchOurApp` / `ourAppInFront` / `tapText` / `swipe`。
`swipe` 里 clamp velocity 并写明那个坑：`uitest` 的 velocity 越界**不报错**，
只回一句 "out of range, the default value will be used"，静默换成默认 600。
- 三条新设备判据（`harmony-appearance`）：壁纸档位真的切换 / 窗格内容不得超出屏幕。
- 修了一个**元问题**：设备判据在套件里**恒跳过**（要求"现场已经摆好"），
只有手动摆好才通过 ⇒ 那等于没有判据。现在它们**自己搭现场**
（拉起应用 → 导到目标页 → 操作 → 复位）。`cross-client-gesture` 与
`harmony-appearance` 都改成了这样，套件里 `skip=0`。
- 途中撞出的两个判据自身缺陷（都写了注释）：
· `root0` 用**切页前**的快照 ⇒ 套件里红、单独跑绿（通过与否取决于跑之前那一屏）
· 侧栏项筛选没排除**品牌标** ⇒ 想点「日历」却点到「通信」
## 验证
`run-all.mjs` → `files=32 ran=32 checks=503 pass=503 fail=0 skip=0
red=0 broken=0 unreported=0`（含设备判据：gesture 9、appearance 27）。
`hvigorw assembleHap` 成功；前端重建 + 重打包（`build-stamp` 7/7、`packaging` 5/5）。
设备实测（HATriple 3184×2232）：
· `PUT /me/appearance` 从 **400 → 200**（服务端访问日志），
库里 `jianf` 的记录从空变成 `bg_kind=preset / bg_dim=56 / bg_blur=3`。
· 壁纸真的透出来了：预设档缝隙 `#E0E2E4`、不设档 `#FFFFFF`（像素级对比）。
· 「我的」页 `56%` / `3px` 正常显示在屏内。
**未验**：壁纸在真机上的观感（渐变是否好看、压暗 56% 是否合适）；
这一轮只验了"数据通了、界面响应了、内容没被裁掉"。
|
|||
| 4a5318ca28 |
跨端: 手势补设备判据（真滑、标题真变）+ 修三处"设备判据假红"的典型错法
上一提交把滑动翻页做完了，但只验到"代码形态对"。**真装上跑时一次都没触发** ——
这一条补上设备实测，并把途中撞出来的三类错法记进判据注释。
## 一、为什么必须有设备判据
第一次装上跑：**代码全对、手势一次都没触发**。原因是起点 x=2600 落在
**右栏**（日程面板 `Column [2207,112][3184,2204]`）—— 事件根本没进网格列。
只有静态判据的话，结论会是"手势已实现、判据全绿"，而用户真去滑时一动不动。
所以判据断的是**界面真的翻了**（滑动前后各 dump 一次，断言月标题变一格），
不是断"日志里有 turned=true" —— 后者只证明判定通过、证明不了有人会动。
## 二、途中撞出来的三类错法（都写进注释了）
1. **`uitest` 的 velocity 越界会被静默替换**
我传 150（想表达"慢一点"），它只回一句
`The swipe velocity out of range, the default value will be used.`
—— 不报错、不改退出码，只是默默换成默认 600。于是"慢滑"变成"更慢的滑"，
看起来像手势没生效。**传合法值（200~40000）+ 读回执**才能避免。
新增 `lib/harmony-device.mjs` 的 `swipe()` 帮手（与 `tap()` 同族，
内部 clamp，并在注释里写了这个坑）。
2. **滑动是有副作用且不可撤销的写操作 ⇒ 不能盲目重试**
第一版写"不生效就再发一次（最多 3 次）"，结果实测**把日历一次翻了 3 格**
（标题跑到 2026年11月）。重试不是"再试一次"，是"再翻一页"。
只有幂等操作才允许盲目重试。改成：**只发一次 + 等足够久**（最多 8 秒轮询）。
3. **坐标不能用"到边界差一点"的比例**
取 `width * 0.68` = 2165，距网格列右边界 2207 只有 42px ⇒ **一次都不触发**；
同一台设备、同一份代码，起点改 2000 立刻生效。
起点贴边时触摸点会被判到相邻的右栏。改成取**列中段**
（`0.62` / `0.13`，两端各留几百 px 余量）。
另：本判据第一版用"滑一次 + 固定等 2500ms + dump"，**单独跑通过、接进
run-all 后失败**（设备繁忙时不够）。固定等待是设备判据最常见的假红来源 ——
改成轮询到标题变化。诊断留了 `AGENTMAIL_GESTURE_DEBUG=1` 门控，
失败时能一次看到"前台/坐标/轨迹"，不用事后手动复现。
## 三、设备实测结果（HATriple 3184×2232）
· 月档：左滑 9月 → **10月**（`dx=-556.5 dy=0 ms=624 turned=true`）；
右滑回 **9月**（`dx=+556.5`）。
· 周档：`2026年9月14–20日` → 左滑 → **`9月21–27日`**（正好 +7 天，
证明步长走的是 `stepDaysOf` 而不是写死 1）。
· 斜滑（dx=400 dy=800）：`PanGesture({direction: Horizontal})` 在系统层
就没识别 ⇒ 比鸿蒙侧的 `SWIPE_AXIS_RATIO` 更早拦住（正确行为）。
**仍未验**：56vp / 1.4× / 700ms 这三个数**手感是否合适**，只能真人滑过才知道。
我验的是"判定逻辑 + 接线 + 真能翻页"。
## 四、验证
`run-all.mjs` → `files=32 ran=32 checks=498 pass=498 fail=0 skip=0
red=0 broken=0 unreported=0`。
（含新设备判据：cross-client-gesture 9 条，其中第 9 条是真滑。
`build-stamp` 7/7、`packaging` 5/5 —— 按判据要求重建 + 重打包，没有改记录迁就。）
|
|||
| 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 从「✅（滑动翻页除外）」改为 ✅。
|
