update at 2026-03-15 14:54:51

dash/docs/layered-clock-plan.zh.md

@@ -13,6 +13,11 @@
 - 节点：`6:2`
 - 链接：`https://www.figma.com/design/3bXFNM5nM6mCq0TpL3nPYK/calendar?node-id=6-2&m=dev`
 
+指针与表盘素材的拆分约束来自 Figma annotation：
+
+- 节点：`23:418`
+- 链接：`https://www.figma.com/design/3bXFNM5nM6mCq0TpL3nPYK/calendar?node-id=23-418&m=dev`
+
 该节点 annotation 已明确：
 
 - `阳历当天`
@@ -123,9 +128,64 @@
 - 分针每分钟一个角度，共 `60` 张
 - 时针如果要做到真正随分钟连续移动，需要 `12 * 60 = 720` 张
 - 这些都是小尺寸 patch，不是整屏图，体积可控
+- 所有素材统一放在 Kindle 本地 `assets/` 目录下
+
+推荐目录：
+
+```text
+/mnt/us/dashboard/assets/clock-face.png
+/mnt/us/dashboard/assets/hour-hand/000.png ... 719.png
+/mnt/us/dashboard/assets/minute-hand/00.png ... 59.png
+```
 
 如果后续确认 Kindle 端存在稳定的本地绘线工具，再考虑把指针改成算法绘制；当前版本不依赖这个前提。
 
+### 3.4 指针锚点与缩放规则
+
+这部分是 Kindle 端渲染能否正确对齐的关键约束，不能省略。
+
+根据 Figma 节点 `23:418` 的 annotation 与素材结构：
+
+- `hour-hand` 与 `minute-hand` 的中心位置不是素材端点
+- 指针的旋转中心是素材内部的圆点中心
+- Kindle 端贴图时，不能把图片底边、顶边或几何中心当作对齐基准
+
+因此，运行时必须遵守下面的规则：
+
+1. 每类指针素材都要记录自己的 `pivot`
+2. 渲染时以 `pivot` 对齐表盘中心，而不是以素材端点对齐
+3. 指针长度不能写死为某个绝对像素值，而是要随表盘大小同比例缩放
+4. `pivot` 偏移量也必须和指针长度一起同比例缩放
+
+也就是说，如果表盘从设计稿尺寸缩到 Kindle 运行时尺寸：
+
+- 时针长度随表盘直径同比例缩放
+- 分针长度随表盘直径同比例缩放
+- 时针的 `pivot.x / pivot.y` 也按同一比例缩放
+- 分针的 `pivot.x / pivot.y` 也按同一比例缩放
+
+推荐缩放公式：
+
+```text
+scale = min(runtime_clock_width / design_clock_width, runtime_clock_height / design_clock_height)
+
+rendered_hand_width = source_hand_width * scale
+rendered_hand_height = source_hand_height * scale
+rendered_pivot_x = source_pivot_x * scale
+rendered_pivot_y = source_pivot_y * scale
+```
+
+其中：
+
+- `design_clock_width / design_clock_height` 指 Figma 导出该套素材时所对应的基准表盘尺寸
+- `runtime_clock_width / runtime_clock_height` 指 Kindle 端最终时钟区域尺寸
+
+这意味着：
+
+- 表盘主体和指针素材必须来自同一套基准设计尺寸
+- 不能单独替换某一类不同倍率的指针图，否则时针、分针与刻度会失配
+- 如果未来切换到别的机型或别的表盘尺寸，只需要换 `clockRegion` 与 `scale`，不需要重做对齐逻辑
+
 ## 4. 为什么不能只把表盘放进整页背景
 
 这个问题必须单独说明。
@@ -275,14 +335,28 @@ kindle local:
     "height": 220
   },
   "clockFace": {
-    "path": "clock-face.png",
-    "managedOnKindle": true
+    "path": "assets/clock-face.png",
+    "managedOnKindle": true,
+    "designWidth": 220,
+    "designHeight": 220
   },
   "clockHands": {
     "hourPattern": "assets/hour-hand/%03d.png",
     "minutePattern": "assets/minute-hand/%02d.png",
     "refreshIntervalMinutes": 1,
-    "networkRequired": false
+    "networkRequired": false,
+    "anchorMode": "pivot",
+    "scaleWithClockFace": true,
+    "hourHand": {
+      "sourceDesignWidth": 220,
+      "sourceDesignHeight": 220,
+      "pivotSource": "figma-annotation-center-dot"
+    },
+    "minuteHand": {
+      "sourceDesignWidth": 220,
+      "sourceDesignHeight": 220,
+      "pivotSource": "figma-annotation-center-dot"
+    }
   }
 }
 ```
@@ -291,6 +365,8 @@ kindle local:
 
 - `x/y/width/height` 先按设计稿记录
 - 真正接入 Kindle 时，要换算成最终截图分辨率下的实际像素值
+- `pivotSource` 表示指针锚点来自 Figma 素材内部圆点中心，而不是素材端点
+- `scaleWithClockFace=true` 表示运行时必须按表盘尺寸同步缩放指针长度与 `pivot`
 
 ## 8. Kindle 侧刷新策略
 
@@ -332,12 +408,13 @@ MobileRead Wiki 明确写了：
    - `hour_index = ((hour % 12) * 60 + minute) = 000..719`
 3. 在固定坐标先画：
    - `clock-face.png`
-4. 再画：
+4. 根据当前 `clockRegion` 与素材基准尺寸计算统一缩放比例
+5. 以素材内部 `pivot` 对齐表盘中心，先画：
    - `hour-hand/<hour_index>.png`
-5. 再画：
+6. 再以素材内部 `pivot` 对齐表盘中心，画：
    - `minute-hand/<minute_index>.png`
-6. 默认做局部/普通刷新
-7. 每 `10` 到 `15` 分钟对时钟区域补一次全刷，清理残影
+7. 默认做局部/普通刷新
+8. 每 `10` 到 `15` 分钟对时钟区域补一次全刷，清理残影
 
 ### 8.3 功耗模型
 
@@ -412,6 +489,8 @@ export CLOCK_FULL_REFRESH_INTERVAL_MINUTES=15
 
 - 产出 `clock-face.png`
 - 产出 `hour-hand` 与 `minute-hand` 素材库
+- 明确每类指针素材的 `pivot` 与基准表盘尺寸
+- 确保时针、分针长度能随表盘尺寸同比例缩放适配
 
 输出：
 
@@ -443,7 +522,7 @@ export CLOCK_FULL_REFRESH_INTERVAL_MINUTES=15
    - 本地 `minute-hand/*.png`
 4. 分钟刷新时：
    - 先重画表盘
-   - 再重画时针
-   - 再重画分针
+   - 再按 `pivot + scale` 规则重画时针
+   - 再按 `pivot + scale` 规则重画分针
 
 也就是说，**背景是远端低频资源，时钟是本地高频资源，二者不要混在同一个刷新链路里**。