测试与验收清单

自动化测试文件

壁纸引擎包当前有 10 个 Node 单元测试文件，共 112 个测试：

AstroBox-NG web 侧另有 3 个集成测试文件，覆盖产品侧逻辑：

执行命令

在 /Volumes/Lexar/项目/Code/AstroBox-Wallpaper-Engine 目录执行：

pnpm test
pnpm typecheck

发布构建（prepublishOnly 会先跑测试、类型检查再构建）：

pnpm build

项目使用 pnpm@10.33.0。依赖安装必须使用 pnpm。

当前测试断言

配置

• 严格保留 JSON 图层顺序。
• 相对素材地址以 GitHub 配置 URL 所在目录解析。
• shared 预设深合并，设备模板只覆盖指定字段。
• 旧 LayoutTemplate composition 展开照片、玻璃和边框。
• 旧显式图层保留，brightness 转换为相邻 tint。
• 无效 asset、数值范围和 blend default 返回精确字段路径。
• 文字图层解析可变字体轴，fontWeight 与 wght 轴联动。
• 无 wght 轴时锁定字重；缺失轴默认值补中点；轴标签保留大小写。

渲染

• 支持模式归一化，拒绝 destructive composite。
• 多个 wallpaper 副本按 JSON 顺序绘制并共享同一取景。
• 未蒙版 wallpaper 独立铺满自己的层。
• 蒙版 destination-in 只出现在离屏层，不在主 Canvas。
• 普通 blur、backdropBlur 和负 tint 是分离的合成操作。
• 像素模糊真实改变输出数据，不依赖只检查 Canvas filter 属性。
• 透明边缘模糊后保持原色，不产生透明黑色污染。
• 均匀不透明表面模糊后保持原色。
• 初始文字状态携带可变字体轴值（不含 wght），静态字体锁定字重。
• 可变字体通过 outline 路径绘制并响应 wght 变化；缺字走 fillText 回退。

变换

• 旋转后实际最小 cover 会提高。
• 平移在旋转图片局部坐标中限制。
• 缩放锚点保持稳定。
• 旋转、缩放和位置一次性共同约束。

字体与文字排版

• fvar 轴按字体声明顺序提取，静态字体非可变。
• WOFF 通过内置 pako 解压解析。
• WOFF2/CFF2/no-outline/parse-error 返回明确回退原因。
• HVAR advance 与字体自身 shape 一致，GPOS/legacy kern 与 GSUB liga 生效。
• 轴插值对 wght/GRAD 轮廓生效；outline 路径按基线缩放并翻转 y。
• outline 缓存按字体对象弱引用，可定向清理。

玻璃

• RenderPlan 把玻璃前后普通层分组为栅格段，每个玻璃前插入隐藏 blur 节点。
• 依赖分析：下方层变更只影响后续玻璃，上方不 dirty。
• 交互暂停期间不重渲染，结束只渲染一次；material 滑块只重跑 pass 复用 capture。
• 软件渲染的恒等合成、backdrop 采样、kawase 模糊、SDF 折射与层级 blur 行为正确。
• 光学 LUT 与解析公式一致，折射位移有界且无爆炸。

设备与蒙版

• 硬件型号通过 AstroBox 官方资源设备表解析为资源设备 ID。
• 已知旧简写代号和完整 IoT 型号会转成资源设备 ID。
• 未知、有歧义的代号以及硬件型号、产品名不会被模糊匹配。
• 路由地址命中当前设备时保留全局权威连接状态。
• 非当前设备命中已连接设备列表时明确视为已连接。
• 选择非匹配模板时应用被阻止。
• 模板尺寸不同于表盘清单时应用被阻止。
• 蒙版最终 alpha 等于亮度与原 alpha 的乘积。

配置发布验收

配置加载

• configUrl 在 Raw 和目标官方源下都能加载。
• 配置是合法 JSON，不含注释和尾逗号。
• 每个模板与图层 ID 唯一。
• Version 1 明确写出 version: 1。
• 所有可调控制对象范围完整且合法。
• 页面没有配置校验错误。

多设备

• 每个目标设备都有独立的官方资源设备 ID。
• 真实 model/productDevice 能通过 devices_v2.json 解析成预期 ID。
• 解析后的 ID 能命中 deviceKey 或 aliases。
• 历史配置中的已知旧代号能转换并命中相同 ID。
• 自动选中正确模板。
• Canvas 尺寸与该设备的表盘图片要求一致。
• 切换模板再返回时，原模板编辑状态保留。

图片和取景

• 只显示一个用户图片输入。
• 所有 wallpaper 副本内容完全对齐。
• 鼠标拖动正常。
• 单指拖动正常。
• 双指缩放围绕中点稳定。
• 最小缩放不露底。
• 旋转到 min/max 均不露底。
• 缩放或旋转后平移立即重新受限。
• 居中、适配、单项重置和全部重置正确。

图层结构

• 图层顺序与 JSON 完全相同。
• 编辑器没有添加、删除、复制或排序入口。
• JSON 未声明的玻璃、边框、tint 和壁纸副本没有出现。
• 固定参数不显示控件但渲染生效。
• 可调参数只显示配置允许的范围或选项。

文字

• 文本在文本框内换行，水平/垂直对齐正确。
• 可变字体轴（wght/GRAD 等）改变字形轮廓。
• 缺字 grapheme 正常回退，不出现缺字方块或错位。
• 文字颜色、字距、行高、字号、字重可调且一致生效。
• 文本长度超过 maxLength 时被截断。

玻璃

• 玻璃几何（圆角矩形/圆形）与配置一致。
• 玻璃模糊只作用在玻璃形状内。
• 折射、色散、饱和度、对比度、着色按材质参数生效。
• 高光和阴影混合模式生效。
• 交互拖动时玻璃不闪烁、结束交互后正确重渲染。
• 导出 PNG 与预览中的玻璃效果一致。

蒙版

• 白色显示、黑色隐藏、灰色半透明。
• 蒙版本身 alpha 继续生效。
• 蒙版固定在 Canvas，不跟随用户图片变换。
• 每个 mask 只裁切所属图层。
• JPG 边缘压缩效果在可接受范围，硬边界优先使用 PNG/SVG。

效果

• blur 只影响当前层。
• backdropBlur 只作用于期望区域和下方已合成内容。
• tint 正值使用 lightColor，负值使用 darkColor。
• opacity 和 blendMode 按层独立生效。
• asset 整体着色保留透明边缘。
• recolor 命中目标源色且不填实透明像素。

资源与 CORS

• 每个 asset 和 mask 最终 URL 可访问。
• 所有图片响应允许 anonymous CORS。
• SVG 内部引用资源同样可用。
• 切换官方源后配置和素材能重新加载。
• 断开一个必需素材时，页面显示明确错误并阻止输出。

入口与生命周期

• 安装带 configUrl 的表盘后主页小组件可用。
• 设备卡片菜单出现壁纸入口。
• 表盘列表对应项目出现壁纸入口。
• 切换到无关联表盘后主页小组件显示不可用。
• 卸载表盘后关联入口消失。
• 同 ID 重装无 configUrl 表盘后旧关联被清除。

输出一致性

• 舞台预览和导出 PNG 像素效果一致。
• 导出 PNG 尺寸等于模板 Canvas。
• 导出文件名正确。
• 应用到表盘的图片与导出 PNG 一致。
• 应用保留原表盘样式、颜色、数据项和槽位数据。
• 应用期间进度可见，成功和失败有明确提示。

回归标准

以下任一情况视为阻断发布：

• 声明图层被静默跳过；
• JSON 未声明图层被自动加入；
• wallpaper 副本取景不一致；
• 蒙版裁切主 Canvas 已有内容；
• 旋转或拖动出现露底；
• 预览、导出和应用使用不同渲染路径；
• 非匹配设备模板可以应用；
• 卸载或重装后留下错误入口关联；
• 文字图层在预览和导出中出现字体、换行或对齐差异；
• 玻璃图层在交互、预览和导出中出现明显不一致。