6.1 KiB
6.1 KiB
Kindle 市级位置方案
背景
当前仓库里的天气位置来源仍在 calendar/ 前端：
- calendar/src/lib/weather.ts 会优先尝试
navigator.geolocation - 失败时回退到固定默认值
杭州
这条路径不适合当前 Kindle 运行架构，原因有两个：
- Kindle 实机显示的不是一个在设备上实时运行的天气网页，而是先在别处渲染，再同步为背景图。
- 如果由 Web 服务器代查 IP 位置，拿到的是服务器公网 IP，对应的是服务器所在城市，不是 Kindle 所在城市。
本方案的目标是：
- 位置精度只要求到“市”颗粒度
- 位置来源应尽量接近 Kindle 当前网络出口
- 在 SSH 暂时不可用的情况下，先把方案文档明确下来，后续恢复 SSH 后再实现
结论
浏览器网页定位不应继续作为主路径。
推荐改成：
- Kindle 侧自己请求 GeoIP 接口，获取当前公网 IP 对应的城市、经纬度和时区
- 把结果缓存到本地
- 天气与相关展示统一读取这份缓存
- 当 GeoIP 不可用或结果异常时，回退到 Kindle 侧固定配置的
city/lat/lon/timezone
这是一个“市级近似定位”方案，不是 GPS 精确定位方案。
为什么 Kindle 侧 GeoIP 可行
GeoIP 的前提是“由目标设备自己发请求”。
对当前项目，正确的请求路径应该是：
Kindle -> GeoIP 服务 -> 返回 city / lat / lon / timezone
而不是：
Kindle -> 你的 Web 服务 -> Web 服务代查 GeoIP
后一种方式只会得到 Web 服务所在机房或服务器出口的位置。
如果 Kindle 走家庭 Wi-Fi，且只要求“市级”颗粒度，GeoIP 通常够用。 如果 Kindle 走手机热点、VPN、代理、企业网络或运营商 NAT，结果可能偏到邻近城市，必须接受这种误差。
目标能力
实现后需要具备以下能力：
- Kindle 联网后，能够自己获取当前网络出口对应的城市信息
- 获取结果会写入本地缓存
- 断网时仍可继续使用上次缓存
- GeoIP 失败时可回退到固定配置
- 只需要市级位置，不追求街道级精度
推荐数据模型
建议在 Kindle 侧维护一份位置缓存文件。
路径建议：
/mnt/us/dashboard/local/state/location.env
字段建议：
LOCATION_SOURCE=geoip
LOCATION_CITY=杭州
LOCATION_LAT=30.274084
LOCATION_LON=120.155070
LOCATION_TIMEZONE=Asia/Shanghai
LOCATION_UPDATED_AT=2026-03-17T10:00:00+08:00
同时保留一份固定兜底配置，例如：
LOCATION_FALLBACK_CITY=杭州
LOCATION_FALLBACK_LAT=30.274084
LOCATION_FALLBACK_LON=120.155070
LOCATION_FALLBACK_TIMEZONE=Asia/Shanghai
运行时脚本设计
建议新增 Kindle 侧脚本：
dash/src/local/location-sync.sh
职责：
- 检查网络是否可用
- 由 Kindle 自己请求 GeoIP 接口
- 解析响应中的城市、经纬度、时区
- 校验字段是否完整
- 写入本地缓存
- 失败时保留旧缓存，不要清空已有结果
建议同时新增一个只负责读取并导出环境变量的脚本，例如：
dash/src/local/location-env.sh
职责：
- 优先读取新鲜的 GeoIP 缓存
- 没有新鲜缓存时读取旧缓存
- 缓存不存在或无效时回退到固定配置
- 对外输出统一的
LOCATION_CITY/LAT/LON/TIMEZONE
刷新策略
位置不需要高频刷新。
建议策略：
- 启动 dashboard 且确认联网后，首次同步一次位置
- 每 12 小时或 24 小时刷新一次
- 手动切换主题时不强制刷新位置
- 天气刷新与位置刷新解耦
- 位置同步失败时继续使用现有缓存
与现有架构的衔接方式
当前项目是“背景图 + Kindle 本地时钟覆盖”的架构，不是“Kindle 上实时跑完整天气网页”的架构。
因此接入位置数据时，有两条可选路径。
路径 A：最小改动路径
保留当前背景图生成方式，但让背景图生成时显式读取 Kindle 侧缓存导出的城市与经纬度。
优点：
- 改动面相对小
- 仍可复用现有天气卡片布局与导出流程
缺点：
- 需要重新梳理“背景图生成端”如何拿到 Kindle 缓存
- 如果背景仍在 Mac 侧导出，就必须把 Kindle 缓存同步回 Mac 或转成请求参数
路径 B：更符合现状的运行时路径
把“城市文本、天气数据”也逐步下沉到 Kindle 运行时，和本地时钟一样由设备端控制。
优点：
- 位置与天气都由 Kindle 自己决定
- 不会再混入 Mac 浏览器位置或服务器 IP 位置
缺点：
- 改动更大
- 需要重新设计天气卡的本地渲染方式
当前推荐
短期推荐先做：
- Kindle 侧 GeoIP 获取
- 本地缓存
- 固定配置兜底
等 SSH 恢复后，再决定位置数据如何喂给天气展示层。
也就是说，先把“位置来源”稳定下来，再改“展示方式”。
实施顺序
建议按下面顺序落地：
- 新增
location-sync.sh - 新增
location-env.sh - 在 Kindle 运行时目录中引入固定兜底配置
- 在主循环启动阶段接入位置缓存刷新
- 让天气读取逻辑改为优先使用 Kindle 侧位置缓存
- 最后补文档和手动刷新命令
验收标准
实现完成后，至少应满足以下验收条件：
- Kindle 联网后可生成位置缓存文件
- 缓存中至少包含
city/lat/lon/timezone - 断网后仍能继续使用旧缓存
- GeoIP 失败时会稳定回退到固定城市
- 显示出的城市与 Kindle 当前所在城市大体一致
注意事项
- GeoIP 只能提供近似位置，不要当作精确定位
- 手机热点、VPN、代理、企业网络都会降低城市准确率
- 城市级结果可以用于天气展示，但不适合做严格地理判断
- 任何实现都必须保证“失败不影响 dashboard 主循环”
现阶段状态
当前仅完成方案设计，尚未开始代码实现。
直接原因是：
- 目前 SSH 还未恢复
- 设备侧脚本还不能方便地下发、调试和验证
后续等 SSH 恢复后，再按本方案分步实施。