676 lines
20 KiB
Markdown
676 lines
20 KiB
Markdown
# Kindle Dashboard 多主题与方向方案
|
||
|
||
## 0. 当前实现状态（2026-03-16）
|
||
|
||
以下能力已经落地，不再只是设计目标：
|
||
|
||
- `calendar/` 网站已支持 `theme + orientation` 两维预览
|
||
- `mode=background` 下不会显示预览菜单，避免污染截图
|
||
- `calendar/` 已产出：
|
||
- `dist/themes.json`
|
||
- `dist/themes/<theme-id>.json`
|
||
- `dist/themes/<theme-id>/<orientation>/kindlebg.png`
|
||
- 兼容输出仍保留：
|
||
- `dist/kindlebg.png`
|
||
- `dist/clock-region.json`
|
||
- Kindle 已支持：
|
||
- 拉取 `themes.json` 和主题级 JSON
|
||
- 通过 `/mnt/us/dashboard/switch-theme.sh <theme-id> [orientation]` 立即切换
|
||
- 优先使用本地已同步的主题背景图
|
||
- 优先使用本地已同步的主题索引和主题 JSON
|
||
- 本地没有对应背景图时，再回退到远端 `background.url`
|
||
- 同步脚本 `scripts/sync-layered-clock-to-kindle.sh` 会先批量导出全部主题背景，再把 `/mnt/us/dashboard/themes/` 同步到设备
|
||
|
||
### 0.1 横向主题的抓屏评审约定
|
||
|
||
`fbgrab` 抓到的是 Kindle 的原始 framebuffer 图，尺寸始终是纵向的 `1072 x 1448`。
|
||
|
||
这意味着：
|
||
|
||
- `portrait` 主题下，`physical.png` 与 `raw.png` 相同
|
||
- `landscape` + `logo_right` 主题下，日常评审应优先看 `physical.png`
|
||
- `raw.png` 只用于排查原始 framebuffer 坐标
|
||
- `physical.png` 等于把 raw 图按设备实际摆放方向逆时针旋转 90 度后的结果
|
||
|
||
仓库里已经补了一个辅助脚本：
|
||
|
||
```sh
|
||
sh scripts/capture-kindle-screen.sh kindle landscape-check
|
||
```
|
||
|
||
它会同时输出两张图：
|
||
|
||
- `tmp/landscape-check-raw.png`
|
||
- `tmp/landscape-check-physical.png`
|
||
|
||
其中：
|
||
|
||
- `raw.png` 用于排查 framebuffer 原始坐标
|
||
- `physical.png` 用于按 Kindle 实际摆放方向评审横向主题
|
||
|
||
## 1. 背景
|
||
|
||
当前链路已经稳定分成两部分：
|
||
|
||
- `calendar/` 负责渲染网页和导出背景图
|
||
- `dash/` 运行在 Kindle 上，负责拉取背景图并在本地重画时钟
|
||
|
||
这次方案先明确两个概念：
|
||
|
||
- `theme`：视觉主题，例如 `default`、`paper`、`classic`
|
||
- `orientation`：显示方向，例如 `portrait`、`landscape`
|
||
|
||
其中方向不是主题名的一部分，而是每个主题都必须包含的两套样式：
|
||
|
||
- `portrait`
|
||
- Kindle 竖向摆放
|
||
- 设备外部面板上的 `kindle` logo 在下方
|
||
- `landscape`
|
||
- Kindle 横向摆放
|
||
- 设备外部面板上的 `kindle` logo 在右侧
|
||
|
||
也就是说，后续系统模型应当是：
|
||
|
||
- 每个主题都包含纵向和横向两套显示样式
|
||
- Kindle 端仍然保持“拉背景图片 + 绘制时钟”的职责
|
||
- 时钟的位置、尺寸和绘制参数都由 `calendar/` 提供
|
||
|
||
## 2. 目标
|
||
|
||
本方案的目标是：
|
||
|
||
1. 访问网站时，可以切换主题和方向进行预览
|
||
2. 网站预览效果应尽量与 Kindle 最终显示效果一致
|
||
3. 当前背景生成流程继续可用，不因预览能力被破坏
|
||
4. `calendar/` 提供统一的主题清单 JSON，作为主题与方向配置的单一真相源
|
||
5. Kindle 只需要读取固定位置的主题清单和主题配置 JSON
|
||
6. Kindle 切换主题或方向后，应立即拉取对应背景并刷新
|
||
7. 时钟的位置、尺寸和绘制参数由 `calendar` 的主题配置决定，Kindle 不自行决定
|
||
|
||
非目标：
|
||
|
||
- 不在 Kindle 上重新渲染整张页面
|
||
- 不让 Kindle 维护主题路径规则
|
||
- 不让 Kindle 自行推导时钟区域布局
|
||
- 不要求第一阶段就做“本地表盘素材包”体系
|
||
|
||
## 3. 设计原则
|
||
|
||
### 3.1 `calendar/` 是单一真相源
|
||
|
||
主题系统的单一真相源放在 `calendar/` 侧。
|
||
|
||
建议由 `calendar/` 产出：
|
||
|
||
- 一个主题清单文件，例如 `themes.json`
|
||
- 每个主题自己的配置文件，例如 `default.json`、`paper.json`
|
||
- 每个主题在不同方向下的背景图资源
|
||
|
||
其中 `themes.json` 至少描述：
|
||
|
||
- 有哪些主题
|
||
- 每个主题叫什么名字
|
||
- 每个主题的配置 JSON 在哪里
|
||
- 默认主题是谁
|
||
- 默认方向是谁
|
||
|
||
这样做的好处是：
|
||
|
||
- 主题路径由 `calendar` 管理，不在 Kindle 端写死
|
||
- 新增主题时，Kindle 无需改代码里的路径规则
|
||
- 网站预览和 Kindle 切换都依赖同一套主题元数据
|
||
|
||
### 3.2 `theme` 和 `orientation` 分开建模
|
||
|
||
不建议把“横向主题”“纵向主题”作为主题名本身。
|
||
|
||
推荐模型是：
|
||
|
||
- `theme`
|
||
- `orientation`
|
||
|
||
例如：
|
||
|
||
- `theme=default` + `orientation=portrait`
|
||
- `theme=default` + `orientation=landscape`
|
||
- `theme=paper` + `orientation=portrait`
|
||
|
||
这样更符合实际含义：
|
||
|
||
- `theme` 代表视觉风格
|
||
- `orientation` 代表设备摆放方向与对应布局
|
||
|
||
### 3.3 网站预览与导出解耦
|
||
|
||
主题和方向预览只是网站访问时的交互能力，不应破坏当前导出主流程。
|
||
|
||
当前已明确三条链路：
|
||
|
||
- 预览链路：用户访问 `/?mode=full&theme=<id>&orientation=<orientation>`，通过页面菜单切换主题和方向
|
||
- 兼容导出链路：`export:background` 继续生成默认背景图，保持兼容
|
||
- 批量导出链路：`export:themes` 一次性生成全部主题和方向背景
|
||
|
||
也就是说：
|
||
|
||
- 预览能力已经落地
|
||
- 当前 `kindlebg.png` 导出链路继续保留
|
||
- 多主题多方向导出已经接入
|
||
|
||
### 3.4 Kindle 侧最简化
|
||
|
||
Kindle 侧只保留最小能力：
|
||
|
||
- 拉取背景图
|
||
- 读取主题 JSON
|
||
- 根据当前方向读取对应 variant
|
||
- 按 JSON 提供的时钟参数绘制时钟
|
||
|
||
Kindle 不负责：
|
||
|
||
- 推导主题路径
|
||
- 决定时钟区域坐标
|
||
- 维护布局规则
|
||
|
||
推荐让 Kindle 只认识一个固定入口，例如：
|
||
|
||
```text
|
||
https://shell.biboer.cn:20001/themes.json
|
||
```
|
||
|
||
然后从这个 JSON 中知道：
|
||
|
||
- 当前有哪些主题
|
||
- 默认主题和默认方向是什么
|
||
- 每个主题的配置 JSON 在哪里
|
||
|
||
### 3.5 当前时钟实现已经足够轻量
|
||
|
||
当前 Kindle 侧时钟是本地几何绘制，不依赖外部表盘或指针素材文件。
|
||
|
||
这意味着第一阶段主题与方向切换只需要关注：
|
||
|
||
- 背景图 URL
|
||
- 时钟区域位置和尺寸
|
||
- 本地绘制时钟所需的参数
|
||
|
||
不需要先引入复杂的“主题素材包”机制。
|
||
|
||
## 4. 数据约定
|
||
|
||
### 4.1 主题清单 `themes.json`
|
||
|
||
建议由 `calendar/` 在固定位置提供主题清单，例如：
|
||
|
||
```json
|
||
{
|
||
"updatedAt": "2026-03-16T10:00:00+08:00",
|
||
"defaultThemeId": "default",
|
||
"defaultOrientation": "portrait",
|
||
"themes": [
|
||
{
|
||
"id": "default",
|
||
"label": "Default",
|
||
"configUrl": "https://shell.biboer.cn:20001/themes/default.json",
|
||
"orientations": ["portrait", "landscape"]
|
||
},
|
||
{
|
||
"id": "paper",
|
||
"label": "Paper",
|
||
"configUrl": "https://shell.biboer.cn:20001/themes/paper.json",
|
||
"orientations": ["portrait", "landscape"]
|
||
},
|
||
{
|
||
"id": "classic",
|
||
"label": "Classic",
|
||
"configUrl": "https://shell.biboer.cn:20001/themes/classic.json",
|
||
"orientations": ["portrait", "landscape"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
第一阶段建议先保留当前主题并命名为 `default`，然后新增：
|
||
|
||
- `paper`
|
||
- `classic`
|
||
|
||
### 4.2 主题配置 `<theme-id>.json`
|
||
|
||
每个主题提供一份主题级配置，内部包含两个方向的 variant，例如：
|
||
|
||
```json
|
||
{
|
||
"id": "default",
|
||
"label": "Default",
|
||
"variants": {
|
||
"portrait": {
|
||
"devicePlacement": "logo_bottom",
|
||
"background": {
|
||
"path": "themes/default/portrait/kindlebg.png",
|
||
"url": "https://shell.biboer.cn:20001/themes/default/portrait/kindlebg.png",
|
||
"refreshIntervalMinutes": 120
|
||
},
|
||
"clock": {
|
||
"x": 347,
|
||
"y": 55,
|
||
"width": 220,
|
||
"height": 220,
|
||
"faceRadiusRatio": 0.47,
|
||
"faceStroke": 3,
|
||
"tickOuterInset": 6,
|
||
"majorTickLength": 14,
|
||
"minorTickLength": 7,
|
||
"majorTickThickness": 4,
|
||
"minorTickThickness": 2,
|
||
"hourLengthRatio": 0.48,
|
||
"minuteLengthRatio": 0.72,
|
||
"hourThickness": 9,
|
||
"minuteThickness": 5,
|
||
"centerRadius": 7
|
||
}
|
||
},
|
||
"landscape": {
|
||
"devicePlacement": "logo_right",
|
||
"background": {
|
||
"path": "themes/default/landscape/kindlebg.png",
|
||
"url": "https://shell.biboer.cn:20001/themes/default/landscape/kindlebg.png",
|
||
"refreshIntervalMinutes": 120
|
||
},
|
||
"clock": {
|
||
"x": 795,
|
||
"y": 659,
|
||
"width": 220,
|
||
"height": 220,
|
||
"faceRadiusRatio": 0.47,
|
||
"faceStroke": 3,
|
||
"tickOuterInset": 6,
|
||
"majorTickLength": 14,
|
||
"minorTickLength": 7,
|
||
"majorTickThickness": 4,
|
||
"minorTickThickness": 2,
|
||
"hourLengthRatio": 0.48,
|
||
"minuteLengthRatio": 0.72,
|
||
"hourThickness": 9,
|
||
"minuteThickness": 5,
|
||
"centerRadius": 7,
|
||
"rotationDegrees": 90
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 背景图真实路径由主题配置提供，不在 Kindle 端拼接猜测
|
||
- `background.path` 是设备本地相对路径，用于优先读取已同步的本地背景
|
||
- 每个方向都有自己的背景图和时钟区域
|
||
- `landscape` 的 `clock` 已经是 Kindle 设备坐标，不再是网页坐标
|
||
- `landscape` 的 `rotationDegrees=90` 表示 Kindle 本地绘制时钟时，表盘和指针再顺时针旋转 90 度
|
||
- 时钟坐标和大小来自 `calendar` 中该主题该方向下的时钟占位，不允许 Kindle 任意改
|
||
- 后续如果某个主题在不同方向下需要不同绘制参数，也由该 JSON 一起提供
|
||
|
||
### 4.3 远端配置边界
|
||
|
||
远端主题配置只有两类：
|
||
|
||
- `themes.json`
|
||
- 每个主题自己的 JSON，例如 `themes/default.json`
|
||
|
||
除此之外：
|
||
|
||
- 背景图属于资源文件，不属于主题配置
|
||
- Kindle 本地缓存属于运行时状态，不属于主题配置
|
||
|
||
### 4.4 Kindle 本地状态
|
||
|
||
Kindle 本地只需要保存少量状态：
|
||
|
||
```text
|
||
/mnt/us/dashboard/local/theme.env
|
||
/mnt/us/dashboard/local/state/themes.json
|
||
/mnt/us/dashboard/local/state/current-theme.json
|
||
/mnt/us/dashboard/local/state/theme-runtime.env
|
||
/mnt/us/dashboard/local/state/background-updated-at
|
||
```
|
||
|
||
其中：
|
||
|
||
- `theme.env` 记录当前 `THEME_ID` 和 `ORIENTATION`
|
||
- `themes.json` 是最近一次同步到本地的主题清单缓存
|
||
- `current-theme.json` 是当前主题配置缓存
|
||
- `theme-runtime.env` 是 Kindle 实际消费的运行时快照，包含背景路径和时钟参数
|
||
|
||
例如：
|
||
|
||
```sh
|
||
export THEME_ID=default
|
||
export ORIENTATION=portrait
|
||
```
|
||
|
||
### 4.5 Kindle 本地主题资源
|
||
|
||
当前实现中，主题背景图会随部署一起同步到 Kindle：
|
||
|
||
```text
|
||
/mnt/us/dashboard/themes/default/portrait/kindlebg.png
|
||
/mnt/us/dashboard/themes/default/landscape/kindlebg.png
|
||
/mnt/us/dashboard/themes/paper/portrait/kindlebg.png
|
||
/mnt/us/dashboard/themes/paper/landscape/kindlebg.png
|
||
/mnt/us/dashboard/themes/classic/portrait/kindlebg.png
|
||
/mnt/us/dashboard/themes/classic/landscape/kindlebg.png
|
||
```
|
||
|
||
Kindle 拉背景时的规则是：
|
||
|
||
1. 先读 `theme-runtime.env` 中的 `BACKGROUND_PATH`
|
||
2. 如果本地对应文件存在，直接从 `/mnt/us/dashboard/themes/...` 拷贝
|
||
3. 如果本地不存在，再回退到 `BACKGROUND_URL`
|
||
|
||
主题元数据同步的规则是：
|
||
|
||
1. 先读本地 `/mnt/us/dashboard/themes.json`
|
||
2. 再读本地 `/mnt/us/dashboard/themes/<theme-id>.json`
|
||
3. 本地 bundle 不存在时，才回退到远端 URL
|
||
|
||
## 5. `calendar/` 侧方案
|
||
|
||
### 5.1 网站访问时增加主题与方向预览菜单
|
||
|
||
预览菜单只出现在网站访问场景，不出现在背景截图结果里。
|
||
|
||
建议行为：
|
||
|
||
1. 用户访问 `/?mode=full` 时，在页面顶部显示两个可选菜单
|
||
2. 一个菜单切换 `theme`
|
||
3. 一个菜单切换 `orientation`
|
||
4. 在 `mode=background` 下不显示这些菜单，避免影响截图导出
|
||
|
||
建议 URL 形态如下：
|
||
|
||
- `/?mode=full&theme=default&orientation=portrait`
|
||
- `/?mode=full&theme=default&orientation=landscape`
|
||
- `/?mode=full&theme=paper&orientation=portrait`
|
||
|
||
### 5.2 预览效果与 Kindle 效果对齐
|
||
|
||
主题预览不能只是“网页版好看”，还需要尽量接近 Kindle 最终效果。
|
||
|
||
建议做到：
|
||
|
||
- 预览和导出使用同一套主题配置
|
||
- 预览和导出使用同一套方向布局配置
|
||
- Kindle 侧按主题 JSON 中当前方向的参数绘制，避免预览和实机错位
|
||
|
||
这样评审主题时，看到的页面效果和 Kindle 最终效果才是一致的。
|
||
|
||
### 5.3 现有导出流程保持兼容
|
||
|
||
当前默认导出链路继续保留：
|
||
|
||
```text
|
||
calendar/dist/kindlebg.png
|
||
calendar/dist/dashboard-manifest.json
|
||
calendar/dist/clock-region.json
|
||
```
|
||
|
||
兼容规则建议如下：
|
||
|
||
- 如果导出脚本没有显式传入 `theme`，默认导出 `default`
|
||
- 如果导出脚本没有显式传入 `orientation`，默认导出 `portrait`
|
||
- 现有 `export:background` 的行为保持不变
|
||
- 默认导出继续只产出 `default + portrait`
|
||
|
||
这样可以保证：
|
||
|
||
- 网站预览菜单先落地
|
||
- 当前生产链路不被打断
|
||
- Kindle 当前单主题纵向使用方式继续可用
|
||
|
||
### 5.4 多主题多方向导出已作为附加能力落地
|
||
|
||
当前 `export:themes` 会生成如下产物：
|
||
|
||
```text
|
||
calendar/dist/themes.json
|
||
calendar/dist/themes/default.json
|
||
calendar/dist/themes/default/portrait/kindlebg.png
|
||
calendar/dist/themes/default/landscape/kindlebg.png
|
||
calendar/dist/themes/paper.json
|
||
calendar/dist/themes/paper/portrait/kindlebg.png
|
||
calendar/dist/themes/paper/landscape/kindlebg.png
|
||
calendar/dist/themes/classic.json
|
||
calendar/dist/themes/classic/portrait/kindlebg.png
|
||
calendar/dist/themes/classic/landscape/kindlebg.png
|
||
```
|
||
|
||
这里的关键点是：
|
||
|
||
- 原有 `calendar/dist/kindlebg.png` 继续保留
|
||
- 多主题多方向目录和 `themes.json` 是新增能力，不是替换能力
|
||
- 主题和方向的路径管理由 `calendar` 决定，不在 Kindle 侧固化为固定模式
|
||
- 同步到 Kindle 时，会把整个 `calendar/dist/themes/` 目录一起带上
|
||
- `landscape` 的网页先按 `1448x1072` 渲染，再顺时针旋转 90 度，写成 `1072x1448` 的 Kindle 设备图
|
||
- 因此 `landscape` 的 `kindlebg.png` 是设备向产物，不是给桌面直接平铺预览的横图
|
||
|
||
## 6. Kindle 侧方案
|
||
|
||
### 6.1 主题发现方式
|
||
|
||
Kindle 只需要知道一个固定地址：
|
||
|
||
```text
|
||
themes.json 的 URL
|
||
```
|
||
|
||
推荐两种同步方式并存：
|
||
|
||
- 被动同步：Kindle 每天拉取一次 `themes.json`
|
||
- 主动同步：用户进入主题切换流程时，先即时拉取最新 `themes.json`
|
||
- 如果设备上已经有本地同步的 `themes.json` 和主题 JSON，本地 bundle 优先
|
||
|
||
这样能兼顾：
|
||
|
||
- 平时低频更新
|
||
- 切换主题时拿到最新主题清单
|
||
|
||
### 6.2 主题与方向切换流程
|
||
|
||
主题切换时建议执行以下流程：
|
||
|
||
1. 拉取最新 `themes.json`
|
||
2. 根据用户选择的主题 ID 找到对应 `configUrl`
|
||
3. 拉取该主题对应的 `<theme-id>.json`
|
||
4. 确定当前要使用的 `orientation`
|
||
5. 从 `variants[orientation]` 里取出背景和时钟配置
|
||
6. 将 `THEME_ID` 和 `ORIENTATION` 写入本地 `theme.env`
|
||
7. 将主题 JSON 缓存在本地
|
||
8. 优先读取本地 `themes/<theme>/<orientation>/kindlebg.png`
|
||
9. 如果本地没有对应背景，再回退拉取 `background.url`
|
||
10. 立即执行一次全屏刷新
|
||
11. 之后继续按当前分钟级时钟刷新逻辑运行
|
||
|
||
这里有两个关键要求：
|
||
|
||
- 主题或方向切换后，不等待下一个两小时周期
|
||
- 而是立即拉取一次对应的新背景
|
||
|
||
### 6.3 时钟绘制保持现有模型
|
||
|
||
当前 Kindle 时钟是本地几何绘制，已经满足主题切换第一阶段需求。
|
||
|
||
因此 Kindle 侧仍然保持：
|
||
|
||
- 拉背景图片
|
||
- 读取主题 JSON
|
||
- 读取当前方向的 variant
|
||
- 用本地 `lua + fbink` 画时钟
|
||
|
||
不需要在第一阶段增加：
|
||
|
||
- 表盘图片素材同步
|
||
- 指针图片素材同步
|
||
- 复杂的本地主题资源目录
|
||
|
||
如果未来某个主题确实需要独立表盘素材，再在第二阶段扩展。
|
||
|
||
### 6.4 切换入口
|
||
|
||
当前已经有一个可直接 SSH 调用的入口：
|
||
|
||
```sh
|
||
/mnt/us/dashboard/switch-theme.sh <theme-id> [orientation]
|
||
```
|
||
|
||
例如：
|
||
|
||
```sh
|
||
ssh kindle '/mnt/us/dashboard/switch-theme.sh default landscape'
|
||
ssh kindle '/mnt/us/dashboard/switch-theme.sh paper portrait'
|
||
```
|
||
|
||
如果本地刚改过页面样式，推荐先同步一次：
|
||
|
||
```sh
|
||
sh scripts/sync-layered-clock-to-kindle.sh kindle
|
||
```
|
||
|
||
KUAL 动态主题入口仍然是后续可选项，不是当前必需项。
|
||
|
||
如果后续要补 KUAL，目标交互仍然可以保持：
|
||
|
||
1. 用户点击“Theme”
|
||
2. 设备根据 `themes.json` 获取当前可用主题清单
|
||
3. 用户选择具体主题
|
||
4. 用户选择 `portrait` 或 `landscape`
|
||
5. 立即切换到该主题该方向
|
||
|
||
不管具体 UI 形态如何，数据契约都应保持一致：
|
||
|
||
- 主题列表来自 `themes.json`
|
||
- 具体切换行为来自所选主题对应的 `<theme-id>.json`
|
||
- 最终生效资源来自该主题该方向下的 variant
|
||
|
||
## 7. 分阶段落地与当前进度
|
||
|
||
### 第一阶段：网站主题与方向预览（已完成）
|
||
|
||
目标：
|
||
|
||
- 新增 `theme` 参数
|
||
- 新增 `orientation` 参数
|
||
- 增加顶部预览菜单
|
||
- 默认主题命名为 `default`
|
||
- 新增 `paper` 和 `classic`
|
||
- 每个主题都支持 `portrait` 和 `landscape`
|
||
|
||
结果：
|
||
|
||
- 用户可以在网站上预览三套主题的两种方向
|
||
- `mode=background` 不显示预览控件
|
||
- 现有截图导出流程保持不变
|
||
|
||
### 第二阶段：主题元数据发布（已完成）
|
||
|
||
目标：
|
||
|
||
- `calendar/` 产出 `themes.json`
|
||
- 每个主题产出自己的 `<theme-id>.json`
|
||
- 每个主题在两个方向下都有独立背景图 URL
|
||
|
||
结果：
|
||
|
||
- 主题列表、方向列表、时钟配置都由 `calendar/` 统一提供
|
||
- 主题配置里已同时提供 `background.path` 和 `background.url`
|
||
|
||
### 第三阶段：Kindle 端主题与方向切换（已完成）
|
||
|
||
目标：
|
||
|
||
- Kindle 能拉取 `themes.json`
|
||
- Kindle 能按选择主题拉取对应的 `<theme-id>.json`
|
||
- Kindle 能切换 `portrait` 和 `landscape`
|
||
- 切换后立即拉取新背景并全屏刷新
|
||
|
||
结果：
|
||
|
||
- Kindle 端已具备多主题多方向切换能力
|
||
- 切换后会立即刷新
|
||
- SSH 命令切换已实机验证通过
|
||
|
||
### 第四阶段：按需扩展主题能力（未开始）
|
||
|
||
只有在未来确实出现需求时，再考虑：
|
||
|
||
- 为某些主题提供独立表盘素材
|
||
- 增加主题级本地资源同步
|
||
- 增加更复杂的切换交互
|
||
|
||
这一步不是当前必需项。
|
||
|
||
## 8. 风险与约束
|
||
|
||
### 8.1 预览和实机效果偏差
|
||
|
||
如果预览和导出用的不是同一套主题和方向配置，最终会出现：
|
||
|
||
- 网页看起来正确
|
||
- Kindle 上时钟错位或背景不一致
|
||
|
||
因此必须保证：
|
||
|
||
- 预览
|
||
- 导出
|
||
- Kindle 时钟绘制
|
||
|
||
都依赖同一套主题元数据和方向配置。
|
||
|
||
### 8.2 方向切换后的缓存问题
|
||
|
||
如果主题或方向切换后没有立即拉取新背景，Kindle 可能继续显示旧缓存。
|
||
|
||
因此切换时必须同时处理：
|
||
|
||
- 更新 `THEME_ID`
|
||
- 更新 `ORIENTATION`
|
||
- 拉取新的 `<theme-id>.json`
|
||
- 拉取或读取当前方向对应的新背景图
|
||
- 重置背景更新时间戳或直接覆盖缓存背景
|
||
|
||
如果设备本地没有同步主题背景，而远端对应 PNG 也还没发布完成，Kindle 可能拉到 HTML 或错误页而不是图片。
|
||
|
||
因此当前推荐做法是：
|
||
|
||
- 同步到 Kindle 时总是一起同步 `/mnt/us/dashboard/themes/`
|
||
- 设备优先使用本地主题背景
|
||
- 远端 `background.url` 只作为回退
|
||
|
||
### 8.3 主题清单缓存过旧
|
||
|
||
如果 Kindle 长时间只读本地缓存，可能看不到新主题或新方向配置。
|
||
|
||
因此建议：
|
||
|
||
- 日常低频同步一次 `themes.json`
|
||
- 用户进入切换流程时再主动刷新一次
|
||
|
||
## 9. 当前推荐结论
|
||
|
||
推荐采用下面这条路线：
|
||
|
||
1. 继续保留默认 `kindlebg.png` 导出链路，默认仍是 `default + portrait`
|
||
2. 同时保留 `export:themes` 批量导出，作为多主题切换的资源来源
|
||
3. 由 `calendar` 继续维护 `themes.json` 和主题级 `<theme-id>.json`
|
||
4. 每个主题配置里同时提供 `portrait` 和 `landscape` 两套 variant
|
||
5. Kindle 继续读取固定位置的 `themes.json`
|
||
6. 切换主题或方向时优先使用本地同步的主题背景，并继续使用现有本地时钟绘制
|
||
|
||
这条路线的优点是：
|
||
|
||
- 不打断现有 `kindlebg.png` 生成流程
|
||
- 主题和方向都由 `calendar` 统一管理
|
||
- Kindle 侧实现最简化
|
||
- 预览和实机显示可以基于同一套配置对齐
|
||
- 即使远端主题图片还没发布完整，SSH 主题切换也能工作
|
||
- 当前时钟实现不依赖表盘和指针素材，第一阶段改造成本低
|