diff --git a/client/electron/test/CRITERIA.md b/client/electron/test/CRITERIA.md index 64dc6da..b4a22ac 100644 --- a/client/electron/test/CRITERIA.md +++ b/client/electron/test/CRITERIA.md @@ -350,8 +350,9 @@ pi 2026-09-14 提的形状:**不是无条件 fail-closed** —— 缺字段可 它的注释写明"省略或为空 = **不受限**",因为 17 个存量清单都没有这个字段, 若把空声明当最小权限,它们会全部静默失去 IO 注入与记忆读写。 -| 字段 | 缺省语义 | 方向 | 谁批准 / 依据 | -| --- | --- | --- | --- | +| **未知的预设 id**(`layersFor`/`normalizePreset`) | **静默替换为 `aurora`** | **宽(静默)** | 产品决定:背景不该因未知 id 变成空白。**这是"静默给别人的档",不是"给一个安全的空值"** —— 用户不会看到错误,但会看到**别人的档** | +| 只写不读的字段:鸿蒙 `bgBlur` | **写进去、存下来、同步它,但没有任何消费点** | 无(当前无效果) | 核实于 2026-09-14:`Appearance.ts` clamp 存入、`AppearanceStore` 同步,**无页面读它**(材质档位是固定枚举)。⇒ 钉"px ↔ 档位映射表"会是**假判据**(钉一张不存在的表);将来开始消费时**必须**补映射判据 | +| 只写不读的字段:WebUI `LEGACY_BACKUP_KEY` | 删旧值前**另存一份**,没有任何代码读它 | 无(有意为之) | `backgroundStore.ts:200` 的注释写明目的(否则它会变成新的继承源)。**登记在此是为了审计能一次找全** | | 邮件的 `permission_mode` | **不写、不改档**(不是写默认档) | 窄(fail-closed) | 本仓 2026-09-14:缺字段被 `\|\| 'workspace'` 兜成窄档,等于"一个 bug 以正常形态活着";守卫见 `plugins/*/lib/permission-mode.js` 的 `modeForStateWrite` | | HomeAgent `plugin.json` 的 `sdk` | **内核不读**(字段只对人有效) | 无(不是语义,是文档) | 内核 `internal/plugin/manifest.go` 的结构体里没有该字段;`registry.go` 的 `loadOne` 只用 `NameZh/NameEn` | | HomeAgent `plugin.json` 的 `capabilities` | **不受限** | 宽(fail-open) | 内核注释明写理由:17 个存量清单都没有它,空声明当最小权限会让它们**静默降级** | @@ -389,3 +390,42 @@ pi 2026-09-14 提的形状:**不是无条件 fail-closed** —— 缺字段可 在 `client/electron/src/components/CalendarView.tsx:204` 是**裸字面量**, 没有任何判据引用它 ⇒ 当时写"与 WebUI 一致"是把**当下的巧合**当契约。 处理:先标"待两边对齐",再让两边各自钉住数值本身。 + +### 10.1 两类"看起来被接住了、实际没有落点"的东西必须登记在**同一处** + +上面表里最后两行是同一类形状:**值被搬运/保存,但没有落点**(一个是鸿蒙侧的 `bgBlur`, +一个是 WebUI 侧的 `LEGACY_BACKUP_KEY`)。分居两处的话,将来审计容易**只找到一处就以为找全了** +(pi 2026-09-14 指出)。所以两类都登记在这张表里: + +1. **缺省语义**:缺了意味着什么、方向是宽还是窄、谁批准; +2. **只写不读**:谁在写、为什么还留着、什么条件下必须补判据。 + +**判据形态(想做但还没做,写在这里避免当成已完成)**:凡登记为"只写不读"的字段, +写侧必须能指出"有意为之"的理由与批准人 —— 这样"搬运了但没人读"就不会以**静默**形态长期存在。 +现在这一条还只是**文档级**约束(人工核对),没有机器判据去强制它; +要变成"做错会红",得先有一张字段清册可扫。 + +### 10.2 版本偏移下的可见后果:旧客户端遇到"新档"会静默显示 aurora + +跨端耦合的常态是**两端不同时上线**:服务端/WebUI 先加了第 7 档,而鸿蒙还是旧构建 —— +旧鸿蒙的 `layersFor` 认不出新 id,按上面的缺省语义**静默显示 aurora**, +于是"用户以为自己选的是新档"。**这不是 bug,是这条缺省决策的可见后果**(已按 pi 2026-09-14 +的建议同时记进 `docs/HARMONY-ALIGN-PLAN.md` 的差异表)—— 不记,将来会被当 bug 报, +而查到最后发现"这是我们批准的"。 + +## 13. 注释里可以放**指针**,不要放**断言**(尤其是关于另一端实现状态的断言) + +**规则**:不要在 A 端的源码注释里断言 **B 端**的实现状态。写"B 端不消费这个字段"这类句子, +就是把**别处的观测**当成了**本机的契约** —— 它会在 B 端变化的那天变成**假事实**, +而且没有人会回来改(写的人不在那条链上,读的人无法判断它是否还成立)。 + +**该放在哪**: + +- **断言留在"事实所属的那一端"**:例如"鸿蒙不消费 `bg_blur`"是**鸿蒙侧**的事实, + 所以它写在鸿蒙侧(`model/Appearance.ts` / `AppearanceStore.ets` 一带)+登记进 §10; +- 另一侧如果要留痕,只放**指针**:例如"该字段的消费方状态由 <那一端的登记处> 说明"。 + 指针不会过期(它指向的地方会自己更新),断言会。 + +**同族**:这条与"两张表各缺一半时必须按 id 联接,不能按相邻关系配对"、 +"'与 X 一致'必须先确认 X 侧有判据钉住"是同一族 —— **比较/引用的一端必须是权威来源, +不是手边那份可能过期的副本。** diff --git a/docs/HARMONY-ALIGN-PLAN.md b/docs/HARMONY-ALIGN-PLAN.md index a3e6654..dfb999e 100644 --- a/docs/HARMONY-ALIGN-PLAN.md +++ b/docs/HARMONY-ALIGN-PLAN.md @@ -575,6 +575,7 @@ deb 也不必从 targets 里摘。已写进 `client/electron/BUILD.md`(含排 |---|---|---|---| | 圆角 | 自声明 `--radius-card: 0.875rem` | 系统 `sys.float.ohos_id_corner_radius_card/button` | 系统圆角会随设备/主题/无障碍设置变;跟着系统才是"系统方案" | | 材质(玻璃) | 自声明 `--nav-bg: 255 255 255 / 0.72` + `backdrop-filter` | 系统 `backgroundBlurStyle(BlurStyle.COMPONENT_THICK)` | 系统材质自带深浅两套颜色与模糊半径,手写 alpha 跟不了深色 | +| **未知预设 id(版本偏移)** | WebUI/服务端先加第 7 档、鸿蒙还是旧构建 ⇒ 旧端认不出新 id | 按缺省语义**静默替换为 aurora**(`normalizePreset`) | **这不是 bug,是批准的缺省语义的可见后果**:用户以为选的是新档,实际看到的是 aurora。方向是"宽(静默)"——不会看到错误,但会看到**别人的档**。行为判据用"不存在的 id 当哨兵"正好钉住这条(`harmony-presets.test.mjs`) | | **壁纸模糊度** | 用户的 `bg_blur`(**像素半径**,初值 4px)作用在壁纸图层上 | **没有被消费**:栏上的系统**材质档位**(`BlurStyle.COMPONENT_THICK`)是唯一一次模糊,壁纸层不糊 | **不是同一个物理量,而且这边根本没有映射表**。2026-09-14 核实:`bg_blur` 在鸿蒙侧只有"搬运"没有"消费" —— `Appearance.ts` 把它 clamp 到 0~40 存进 `bgBlur`、`AppearanceStore` 同步它,但**没有任何页面/组件读它**(材质档位是固定枚举)。所以不存在"px ↔ 档位"的值映射可钉,也就**没有可判的性质**(pi 问的"映射表有没有判据":没有,且当前不该有 —— 钉一张不存在的表是假判据)。**改一端的含义**:改 WebUI 的 `bg_blur` 语义**不影响鸿蒙**;若将来鸿蒙开始消费它(例如按 px 选不同 `BlurStyle`),**那时**必须补一条映射判据,并更新本行 —— 这是"人工约定、当前无判据"的登记处(CRITERIA.md §12 的同一族)。 | | 动效 | 自定义 transition/时长 | `animateTo` + 系统 `curves` | 动效曲线应跟随系统设置(含"减弱动效") | | 遮罩 | 自声明 `--bg-scrim` + `--bg-dim` 两段式 | 系统 `sys.color.ohos_id_color_mask_regular` | 遮罩要随主题换向(浅色洗白/深色压黑),这件事系统已经做了 |