feat: manage saved thumbnail plans and select plans for tasks

2026-10-23 14:47:27 +08:00
parent d94031eb50
commit 7178235022
17 changed files with 1736 additions and 37 deletions
@@ -1,9 +1,15 @@
-# 手表小图
+# 小图方案

-照片数据源图片成功上传到本地图库或画框云端后，生成当前手表屏幕尺寸的 410×502 RGB JPEG。默认等比缩放、居中裁切铺满屏幕，不拉伸、不补边、不叠加日期、文字或边框；源文件不变。自定义裁切尚未实现。
+平台侧边栏的“小图方案”提供方案新增、查看、修改与删除。每个方案可保存名称、输出宽高（16–2048 像素）、JPEG 质量（40–95）、适配方式及水平/垂直裁切位置（0–1）。默认 410×502、质量 85、居中等比裁切铺满，不拉伸、不补黑边。也可主动选择完整画面，此时必要处补白；裁切位置仅用于铺满模式。

-小图使用添加画框说明前的源画面；Synology Photos 当前只能提供源预览，结果中的 `source_rendition` 标记为 `preview`，不称为原图。没有可验证源画面的模板和旧图库成品暂不生成。
+选择照片数据源及源图片后，可以使用当前参数预览或“生成并保存到图库”。预览不保存文件，正式生成沿用同一渲染器，结果在本地图库按既有方式查看、下载与删除。修改参数后须重新预览；保存方案与保存生成图片是独立操作。

-成功操作结果的 `wrist_thumbnail` 包含鉴权资源 URL、尺寸、字节数、SHA-256、生成时间、服务器配置时区及当地日期。`app_config` 的 `wrist-thumbnail:<device_id>` 保存该设备最后一次成功生成的记录；日期用于判断是否属于当天，跨日不将旧图冒充当天图片。资源沿用 `/api/v1/assets/{asset_id}` 的鉴权规则，不开放公开下载或手表传输接口。
+自动化任务提供“生成小图”勾选，默认关闭。勾选后必须单选一个已保存方案，仅支持照片数据源任务。画框上传成功后，按所选方案生成小图；计划执行时使用该方案最新保存的参数。正在被任务或待处理操作引用的方案不能删除，请先取消任务勾选或更换方案。已有任务默认保持不生成小图；手动照片上传沿用原有默认小图行为。

-上传失败不更新小图。辅助小图生成失败保留已有记录并记录日志，不重放已经成功的画框上传。最新小图受现有本地清理策略保护；更早小图作为 cache 沿用现有清理策略。本阶段未接入 BLE、手表端下载或实机显示验证。
+小图始终使用添加画框说明前的源画面，不叠加日期、文字或边框，不修改源文件。Synology Photos 当前只能提供源预览，不称为原图。没有可验证源画面的模板和旧图库成品不生成。
+
+成功操作结果的 `wrist_thumbnail` 包含鉴权资源 URL、方案 ID 及参数、尺寸、字节数、SHA-256、生成时间、服务器配置时区及当地日期。`app_config` 的 `wrist-thumbnail:<device_id>` 保存该设备最后一次成功生成的记录；跨日不将旧图冒充当天图片。资源沿用 `/api/v1/assets/{asset_id}` 的鉴权规则。
+
+方案接口为 `/api/v1/thumbnail-plans` 和 `/{plan_id}`；预览及生成分别使用 `/api/v1/thumbnails/preview` 与 `/generate`。读取和预览需要 `images:read`，写入需要 `admin`。参数由服务端校验，任务提交也校验方案存在性与来源类型。
+
+上传失败不更新小图。辅助小图生成失败保留已有记录并记录日志，不重放已成功的画框上传。最新小图受现有本地清理策略保护，较早小图沿用 cache 清理策略。本阶段未接入 BLE、手表端下载或实机显示验证。