482 lines
13 KiB
Markdown
482 lines
13 KiB
Markdown
# Kindle Dashboard 多主题方案
|
||
|
||
## 1. 背景
|
||
|
||
当前链路已经稳定分成两部分：
|
||
|
||
- `calendar/` 负责渲染网页和导出背景图
|
||
- `dash/` 运行在 Kindle 上，负责拉取背景图并在本地重画时钟
|
||
|
||
这里先明确一个约束，后续方案都基于它展开：
|
||
|
||
- Kindle 端仍然保持“拉背景图片 + 绘制时钟”的职责
|
||
- 不把整页日历渲染放回 Kindle
|
||
- 主题的名称、路径、时钟占位信息都由 `calendar/` 提供
|
||
|
||
这次多主题方案要同时满足两类需求：
|
||
|
||
1. 访问 `calendar` 网站时，可以在页面上切换主题预览效果
|
||
2. 后续 Kindle 端如果需要切换主题，也只依赖 `calendar` 提供的主题配置，不自己猜路径或布局
|
||
|
||
## 2. 目标
|
||
|
||
本方案的目标是：
|
||
|
||
1. 访问网站时，可以通过顶部可选菜单切换主题样式
|
||
2. 网站预览效果应尽量与 Kindle 最终显示效果一致
|
||
3. 当前背景生成流程继续可用，不因主题预览被破坏
|
||
4. `calendar/` 提供统一的主题清单 JSON，作为主题的单一真相源
|
||
5. Kindle 只需要读取固定位置的主题清单和主题配置 JSON
|
||
6. Kindle 切换主题后，应立即拉取该主题背景和主题级配置并刷新
|
||
7. 时钟的位置、尺寸和绘制参数由 `calendar` 的主题配置决定，Kindle 不自行决定
|
||
|
||
非目标：
|
||
|
||
- 不在 Kindle 上重新渲染整张页面
|
||
- 不让 Kindle 维护主题路径规则
|
||
- 不要求第一阶段就把现有导出脚本改成强制批量导出
|
||
- 不要求第一阶段就做“本地表盘素材包”体系
|
||
|
||
## 3. 设计原则
|
||
|
||
### 3.1 `calendar/` 是主题真相源
|
||
|
||
主题系统的单一真相源放在 `calendar/` 侧。
|
||
|
||
建议由 `calendar/` 产出：
|
||
|
||
- 一个主题清单文件，例如 `themes.json`
|
||
- 每个主题自己的配置文件，例如 `default.json`、`paper.json`
|
||
- 每个主题自己的背景图
|
||
|
||
其中 `themes.json` 至少描述：
|
||
|
||
- 有哪些主题
|
||
- 每个主题叫什么名字
|
||
- 每个主题的配置 JSON 在哪里
|
||
- 默认主题是谁
|
||
|
||
这样做的好处是：
|
||
|
||
- 主题路径由 `calendar` 管理，不在 Kindle 端写死
|
||
- 新增主题时，Kindle 无需改代码里的路径规则
|
||
- 网站预览和 Kindle 切换都依赖同一套主题元数据
|
||
|
||
这里再明确一下边界。
|
||
|
||
远端主题配置只有两类：
|
||
|
||
- `themes.json`
|
||
- 每个主题自己的 JSON，例如 `themes/default.json`
|
||
|
||
除此之外：
|
||
|
||
- 背景图属于资源文件，不属于主题配置
|
||
- Kindle 本地缓存属于运行时状态，不属于主题配置
|
||
|
||
### 3.2 网站预览与导出解耦
|
||
|
||
主题预览只是网站访问时的交互能力，不应破坏当前导出主流程。
|
||
|
||
建议明确两条链路：
|
||
|
||
- 预览链路：用户访问 `/?mode=full&theme=<id>`，通过页面菜单切换主题
|
||
- 导出链路：现有脚本继续生成默认背景图，保持兼容
|
||
|
||
也就是说：
|
||
|
||
- 预览能力先落地
|
||
- 当前 `kindlebg.png` 导出链路先不强制变化
|
||
- 多主题导出作为后续增量能力接入
|
||
|
||
### 3.3 Kindle 侧最简化
|
||
|
||
Kindle 侧只保留最小能力：
|
||
|
||
- 拉取背景图
|
||
- 读取主题 JSON
|
||
- 按 JSON 提供的时钟参数绘制时钟
|
||
|
||
Kindle 不负责：
|
||
|
||
- 推导主题路径
|
||
- 决定时钟区域坐标
|
||
- 维护主题布局规则
|
||
|
||
推荐让 Kindle 只认识一个固定入口，例如：
|
||
|
||
```text
|
||
https://shell.biboer.cn:20001/themes.json
|
||
```
|
||
|
||
然后从这个 JSON 中知道：
|
||
|
||
- 当前有哪些主题
|
||
- 每个主题的配置 JSON 在哪里
|
||
- 切换到该主题时该去拉哪个背景图
|
||
|
||
### 3.4 当前时钟实现已经足够轻量
|
||
|
||
当前 Kindle 侧时钟是本地几何绘制，不依赖外部表盘或指针素材文件。
|
||
|
||
这意味着第一阶段主题切换只需要关注：
|
||
|
||
- 背景图 URL
|
||
- 时钟区域位置和尺寸
|
||
- 本地绘制时钟所需的参数
|
||
|
||
不需要先引入复杂的“主题素材包”机制。
|
||
|
||
## 4. 数据约定
|
||
|
||
### 4.1 主题清单 `themes.json`
|
||
|
||
建议由 `calendar/` 在固定位置提供主题清单，例如：
|
||
|
||
```json
|
||
{
|
||
"updatedAt": "2026-03-16T10:00:00+08:00",
|
||
"defaultThemeId": "default",
|
||
"themes": [
|
||
{
|
||
"id": "default",
|
||
"label": "Default",
|
||
"configUrl": "https://shell.biboer.cn:20001/themes/default.json",
|
||
"previewQuery": "?mode=full&theme=default"
|
||
},
|
||
{
|
||
"id": "paper",
|
||
"label": "Paper",
|
||
"configUrl": "https://shell.biboer.cn:20001/themes/paper.json",
|
||
"previewQuery": "?mode=full&theme=paper"
|
||
},
|
||
{
|
||
"id": "classic",
|
||
"label": "Classic",
|
||
"configUrl": "https://shell.biboer.cn:20001/themes/classic.json",
|
||
"previewQuery": "?mode=full&theme=classic"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
第一阶段建议先保留当前主题并命名为 `default`，然后新增：
|
||
|
||
- `paper`
|
||
- `classic`
|
||
|
||
### 4.2 主题配置 `<theme-id>.json`
|
||
|
||
每个主题再提供一份主题级配置，例如：
|
||
|
||
```json
|
||
{
|
||
"id": "default",
|
||
"label": "Default",
|
||
"background": {
|
||
"url": "https://shell.biboer.cn:20001/themes/default/kindlebg.png",
|
||
"refreshIntervalMinutes": 120
|
||
},
|
||
"clock": {
|
||
"x": 262,
|
||
"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
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 背景图真实路径由主题配置提供，不在 Kindle 端拼接猜测
|
||
- 时钟坐标和大小来自 `calendar` 中该主题的时钟占位，不允许 Kindle 任意改
|
||
- 后续如果某个主题需要不同的时钟绘制参数，也由该 JSON 一起提供
|
||
|
||
### 4.3 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/background-updated-at
|
||
```
|
||
|
||
其中：
|
||
|
||
- `theme.env` 只记录当前主题 ID
|
||
- `themes.json` 是最近一次同步到本地的主题清单缓存
|
||
- `current-theme.json` 是当前主题配置缓存
|
||
|
||
这几项是 Kindle 本地运行状态，不属于远端主题配置。
|
||
|
||
## 5. `calendar/` 侧方案
|
||
|
||
### 5.1 网站访问时增加主题预览菜单
|
||
|
||
主题预览菜单只出现在网站访问场景，不出现在背景截图结果里。
|
||
|
||
建议行为：
|
||
|
||
1. 用户访问 `/?mode=full` 时，在页面顶部显示一个可选主题菜单
|
||
2. 切换菜单时更新当前页面的 `theme` 参数
|
||
3. 菜单位置放在顶部任意不影响截图的位置即可
|
||
4. 在 `mode=background` 下不显示该菜单，避免影响截图导出
|
||
|
||
建议 URL 形态如下：
|
||
|
||
- `/?mode=full&theme=default`
|
||
- `/?mode=full&theme=paper`
|
||
- `/?mode=full&theme=classic`
|
||
|
||
### 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`
|
||
- 现有 `export:background` 的行为保持不变
|
||
- 先不强制要求所有主题都参与默认导出
|
||
|
||
这样可以保证：
|
||
|
||
- 网站预览菜单先落地
|
||
- 当前生产链路不被打断
|
||
- Kindle 当前单主题使用方式继续可用
|
||
|
||
### 5.4 多主题导出作为附加能力
|
||
|
||
当需要支持 Kindle 端多主题切换时，再增加多主题导出，例如：
|
||
|
||
```text
|
||
calendar/dist/themes.json
|
||
calendar/dist/themes/default.json
|
||
calendar/dist/themes/default/kindlebg.png
|
||
calendar/dist/themes/paper.json
|
||
calendar/dist/themes/paper/kindlebg.png
|
||
calendar/dist/themes/classic.json
|
||
calendar/dist/themes/classic/kindlebg.png
|
||
```
|
||
|
||
这里的关键点是：
|
||
|
||
- 原有 `calendar/dist/kindlebg.png` 继续保留
|
||
- 多主题目录和 `themes.json` 是新增能力，不是替换能力
|
||
- 主题路径管理由 `calendar` 决定，不在 Kindle 侧固化为固定模式
|
||
|
||
## 6. Kindle 侧方案
|
||
|
||
### 6.1 主题发现方式
|
||
|
||
Kindle 只需要知道一个固定地址：
|
||
|
||
```text
|
||
themes.json 的 URL
|
||
```
|
||
|
||
推荐两种同步方式并存：
|
||
|
||
- 被动同步：Kindle 每天拉取一次 `themes.json`
|
||
- 主动同步：用户进入主题切换流程时，先即时拉取最新 `themes.json`
|
||
|
||
这样能兼顾：
|
||
|
||
- 平时低频更新
|
||
- 切换主题时拿到最新主题清单
|
||
|
||
### 6.2 主题切换流程
|
||
|
||
主题切换时建议执行以下流程：
|
||
|
||
1. 拉取最新 `themes.json`
|
||
2. 根据用户选择的主题 ID 找到对应 `configUrl`
|
||
3. 拉取该主题对应的 `<theme-id>.json`
|
||
4. 将 `THEME_ID` 写入本地 `theme.env`
|
||
5. 将主题 JSON 缓存在本地
|
||
6. 立即拉取该主题背景图
|
||
7. 立即执行一次全屏刷新
|
||
8. 之后继续按当前分钟级时钟刷新逻辑运行
|
||
|
||
这里有一个关键要求：
|
||
|
||
- 主题切换后，不等待下一个两小时周期
|
||
- 而是立即拉取一次新主题背景
|
||
|
||
### 6.3 时钟绘制保持现有模型
|
||
|
||
当前 Kindle 时钟是本地几何绘制，已经满足主题切换第一阶段需求。
|
||
|
||
因此 Kindle 侧仍然保持：
|
||
|
||
- 拉背景图片
|
||
- 读取主题 JSON
|
||
- 用本地 `lua + fbink` 画时钟
|
||
|
||
不需要在第一阶段增加：
|
||
|
||
- 表盘图片素材同步
|
||
- 指针图片素材同步
|
||
- 复杂的本地主题资源目录
|
||
|
||
如果未来某个主题确实需要独立表盘素材，再在第二阶段扩展。
|
||
|
||
### 6.4 主题切换入口
|
||
|
||
入口建议做成“统一主题入口”，而不是在 KUAL 里硬编码每个主题项。
|
||
|
||
目标交互是：
|
||
|
||
1. 用户点击“Theme”
|
||
2. 设备根据 `themes.json` 获取当前可用主题清单
|
||
3. 用户点击具体主题
|
||
4. 立即切换到该主题
|
||
|
||
实现上可以接受两种方式：
|
||
|
||
- KUAL 能直接承载该交互，则由脚本在入口内完成
|
||
- 如果 KUAL 不能直接动态展示，则由脚本先读取 `themes.json`，再生成或更新对应菜单
|
||
|
||
不管具体 UI 形态如何，数据契约都应保持一致：
|
||
|
||
- 主题列表来自 `themes.json`
|
||
- 切换行为来自所选主题对应的 `<theme-id>.json`
|
||
|
||
## 7. 分阶段落地
|
||
|
||
### 第一阶段：网站主题预览
|
||
|
||
目标：
|
||
|
||
- 新增 `theme` 参数
|
||
- 增加顶部主题预览菜单
|
||
- 默认主题命名为 `default`
|
||
- 新增 `paper` 和 `classic`
|
||
|
||
结果：
|
||
|
||
- 用户可以在网站上预览三套主题
|
||
- 现有截图导出流程保持不变
|
||
|
||
### 第二阶段：主题元数据发布
|
||
|
||
目标：
|
||
|
||
- `calendar/` 产出 `themes.json`
|
||
- 每个主题产出自己的 `<theme-id>.json`
|
||
- 每个主题有独立背景图 URL
|
||
|
||
结果：
|
||
|
||
- 主题列表、主题路径、时钟配置都由 `calendar/` 统一提供
|
||
- Kindle 侧可以开始按 JSON 理解主题系统
|
||
|
||
### 第三阶段：Kindle 端主题切换
|
||
|
||
目标：
|
||
|
||
- Kindle 能拉取 `themes.json`
|
||
- Kindle 能按选择主题拉取对应的 `<theme-id>.json`
|
||
- 切换后立即拉取新背景并全屏刷新
|
||
|
||
结果：
|
||
|
||
- Kindle 端正式具备多主题切换能力
|
||
- Kindle 侧仍保持最小职责
|
||
|
||
### 第四阶段：按需扩展主题能力
|
||
|
||
只有在未来确实出现需求时，再考虑：
|
||
|
||
- 为某些主题提供独立表盘素材
|
||
- 增加主题级本地资源同步
|
||
- 增加更复杂的主题切换交互
|
||
|
||
这一步不是当前必需项。
|
||
|
||
## 8. 风险与约束
|
||
|
||
### 8.1 预览和实机效果偏差
|
||
|
||
如果预览和导出用的不是同一套主题配置，最终会出现：
|
||
|
||
- 网页看起来正确
|
||
- Kindle 上时钟错位或背景不一致
|
||
|
||
因此必须保证：
|
||
|
||
- 预览
|
||
- 导出
|
||
- Kindle 时钟绘制
|
||
|
||
都依赖同一套主题元数据。
|
||
|
||
### 8.2 主题切换后的缓存问题
|
||
|
||
如果主题切换后没有立即拉取新背景，Kindle 可能继续显示旧缓存。
|
||
|
||
因此切换主题时必须同时处理：
|
||
|
||
- 更新 `THEME_ID`
|
||
- 拉取新的 `<theme-id>.json`
|
||
- 拉取新的背景图
|
||
- 重置背景更新时间戳或直接覆盖缓存背景
|
||
|
||
### 8.3 主题清单缓存过旧
|
||
|
||
如果 Kindle 长时间只读本地缓存，可能看不到新主题。
|
||
|
||
因此建议：
|
||
|
||
- 日常低频同步一次 `themes.json`
|
||
- 用户进入主题切换时再主动刷新一次
|
||
|
||
## 9. 推荐结论
|
||
|
||
推荐采用下面这条路线：
|
||
|
||
1. 先在 `calendar` 网站上增加顶部主题预览菜单
|
||
2. 维持当前默认背景导出链路不变
|
||
3. 由 `calendar` 增量提供 `themes.json` 和主题级 `<theme-id>.json`
|
||
4. Kindle 只读取固定位置的 `themes.json`
|
||
5. 切换主题时立即拉取该主题配置和背景图，并继续使用现有本地时钟绘制
|
||
|
||
这条路线的优点是：
|
||
|
||
- 不打断现有 `kindlebg.png` 生成流程
|
||
- 主题路径和布局都由 `calendar` 统一管理
|
||
- Kindle 侧实现最简化
|
||
- 预览和实机显示可以基于同一套配置对齐
|
||
- 当前时钟实现不依赖表盘和指针素材，第一阶段改造成本低
|