AstroBox 安装关联、入口与应用流程

Manifest 声明

表盘资源通过以下扩展字段声明壁纸配置：

{
  "ext": {
    "wallpaperGenerator": {
      "configUrl": "https://github.com/owner/repo/blob/main/wallpaper/wallpaper.json"
    }
  }
}

运行时只接受非空字符串 configUrl，并去除首尾空白。其他 wallpaperGenerator 内容不会参与当前壁纸生成器。

下载与安装任务传递

普通资源下载和试用直链下载都会从 manifest 读取 configUrl，并把它保存到下载任务与后续安装任务的 wallpaperConfigUrl 字段。

安装真正执行时，使用任务当前最新的 wallpaperConfigUrl。这允许队列中的任务更新保持一致，而不是只读创建任务时的旧闭包值。

成功安装后的本地关联

表盘安装成功且有实际 watchfaceId 时：

• 有 wallpaperConfigUrl：写入壁纸安装关联；
• 没有 wallpaperConfigUrl：删除同设备、同表盘 ID 的旧关联，避免重装普通表盘后保留错误入口。

本地存储键为：

astrobox.watchface.wallpaper-installations.v1

其中每条记录的键为：

设备地址|表盘 ID

记录结构：

{
  configUrl: string,
  resourceId?: string,
  resourceName?: string,
  installedAt: number
}

当前安装流程至少写入 configUrl 和当前毫秒时间戳 installedAt。本地存储读取或写入失败会被安全吞掉，因此无可用 localStorage 的环境不会产生入口关联。

关联清理

以下路径会删除对应记录：

• 安装新表盘前强制卸载旧表盘成功；
• 已安装表盘列表中手动卸载成功；
• 同 ID 表盘重新安装成功但新资源没有壁纸配置。

清理以实际设备地址和表盘 ID 为范围，不会删除其他设备或其他表盘的记录。

编辑器路由

壁纸编辑页路由为：

/device/watchface/wallpaper

路由参数：

{
  addr?: string,
  faceId?: string,
  configUrl?: string
}

页面优先使用目标设备和表盘的已安装关联 URL，只有关联值不存在时才考虑路由 configUrl。但页面加载配置本身要求安装关联存在，因此路由参数不能伪造一个未安装表盘的可用编辑会话。

移动端底部导航在该路由隐藏，为编辑器释放空间。

三个入口

设备主页小组件

设备主页布局支持 kind: "wallpaper"：

• 支持 1x1、2x1、full；
• 新默认布局包含 2x1 小组件；
• 旧布局迁移会补入 full 小组件；
• 编辑布局菜单可添加，已存在时禁止重复添加；
• 布局规范化会保留该类型和合法尺寸。

主页查询当前表盘并读取其安装关联。关联存在时点击进入编辑器，并传入设备地址、当前表盘 ID 与配置 URL。

没有关联时小组件仍可显示，但文案为“当前表盘不支持更改壁纸”，点击给出不可用提示。设备未连接时点击给出设备未连接提示。

设备卡片菜单

设备卡片根据该设备当前表盘读取安装关联。只有关联存在时才显示“壁纸”菜单项，点击进入对应编辑器。

已安装表盘列表

每个表盘菜单按设备地址和该表盘 ID 查询关联。只有关联存在时才显示“壁纸”菜单项。

此入口可以打开非当前表盘的配置用于预览和导出，但应用阶段会要求该表盘是设备当前表盘。

编辑页启动查询

编辑页会读取：

• 目标设备连接状态；
• 已安装表盘列表和当前表盘；
• 壁纸安装关联；
• 表盘编辑能力和当前表盘编辑数据；
• 设备型号信息；
• 当前官方源设置。

目标设备地址匹配会去除首尾空白并忽略大小写。如果路由地址指向当前全局设备，页面优先使用全局设备的权威连接状态。只有目标不是当前设备时，才从 device_get_connected_devices 列表解析；该列表中的项按接口语义视为已连接，不依赖列表项是否重复携带 connected: true。

配置在 configUrl、官方源或安装记录 installedAt 变化时重新加载。

应用校验顺序

应用阻断按固定优先级返回第一项：

1. 渲染尚不可导出：请先完成壁纸图片与素材加载。
2. 设备未连接：当前设备未连接。
3. 安装关联不存在：表盘安装关联已失效。
4. 目标表盘不是当前表盘：当前设备使用的不是此表盘。
5. 设备仍在识别：正在通过 AstroBox 资源设备表识别当前设备。
6. 资源设备表识别失败：无法通过 AstroBox 资源设备表识别当前设备。
7. 没有匹配设备模板：配置中没有匹配当前设备的模板。
8. 选中模板不是匹配模板：所选模板与当前设备不匹配。
9. 缺少表盘编辑能力：当前表盘不支持壁纸编辑。
10. 表盘明确不允许编辑：当前表盘不允许编辑。
11. 模板尺寸与表盘清单不一致：模板输出尺寸与当前表盘不一致。

导出只受第 1 项相关条件限制，不受设备连接、设备匹配或当前表盘限制。

应用数据

应用时先用统一渲染器生成 PNG Blob，再转为 base64，作为唯一照片传入表盘编辑流程：

{
  photos: [base64],
  album: true,
  deleteAllImages: false,
  width: template.canvas.width,
  height: template.canvas.height,
  imageFormat: deviceItem.supportImageFormat ?? 6,
  setCurrent: true
}

同时保留当前表盘已有的：

• 背景色与前景色；
• 样式与样式颜色索引；
• 数据项；
• 槽位项；
• 图片组支持标记。

应用过程显示传输进度，成功后提示“壁纸已应用到表盘”。