update at 2026-03-16 09:00:35

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

@@ -53,6 +53,35 @@
 - 降低全屏刷新频率
 - 减少墨水屏闪烁与残影
 
+### 2.1 当前导出基线
+
+基于 Kindle Voyage 系统自带屏保 `bg_default.png` 的实机验证，当前背景导出链路应遵守这几个固定约束：
+
+- 网页成品页尺寸直接使用 `1072 x 1448`
+- Kindle 主背景图直接导出为同尺寸，不再做额外旋转、补边或缩放
+- 导出格式固定为 `8-bit grayscale PNG`
+- 页面视觉尽量保持纯白底、纯黑文字与图标，避免大面积灰阶装饰
+
+这部分不是临时调试参数，而是后续继续微调版式时的默认基准。
+
+当前设备端时钟实现也已经切换为：
+
+- Kindle 本机 `lua` 生成时钟区位图
+- 通过 `fbink` 刷新指定矩形
+
+在 Kindle Voyage 5.13.6 的当前环境里，还需要额外注意一点：
+
+- `fbink` 叠加图片时必须带 `-V` / `--noviewport`
+- 否则会因为 viewport 修正导致时钟区域纵向偏移
+- 并且会在同一帧缓冲里出现两个重叠时钟
+
+也就是说，Voyage 上本地时钟叠加的稳定命令形态应当是：
+
+```sh
+fbink -q -V -g "file=/mnt/us/dashboard/local/state/clock-render.pgm,x=$CLOCK_REGION_X,y=$CLOCK_REGION_Y"
+```
+- 不再依赖 `eips + 透明 PNG patch` 叠图
+
 ## 3. 分层边界
 
 ### 3.1 全屏背景层
@@ -465,8 +494,22 @@ export CLOCK_REGION_Y=0
 export CLOCK_REGION_WIDTH=220
 export CLOCK_REGION_HEIGHT=220
 export CLOCK_FULL_REFRESH_INTERVAL_MINUTES=15
+export PRE_SLEEP_GRACE_SECONDS=10
 ```
 
+补充两条运行期约束：
+
+- `clock-index.sh` 取当前时间时必须沿用 `TIMEZONE`，不能直接读系统默认时区
+- `PRE_SLEEP_GRACE_SECONDS` 这类“进入休眠前的可中断窗口”必须从实际休眠时长里扣掉，否则分钟刷新会长期落后一个节拍
+
+当前实现里，时钟区域的适配已经分成两层：
+
+- `CLOCK_REGION_X/Y/WIDTH/HEIGHT` 负责位置与尺寸
+- `CLOCK_*` 外观参数负责指针长度、粗细、刻度长度和圆心点大小
+
+因此，页面板式变化导致时钟区域变大变小时，一般不需要重画任何静态素材，也不需要改 Lua 代码；
+只要重新导出网页拿到新的 `clock-region.json`，同步到 Kindle 后，本机时钟就会按新尺寸重画。
+
 ## 10. 实施顺序
 
 建议按下面顺序落地，避免一次改太多导致链路难排查。