51 lines
6.9 KiB
Markdown
51 lines
6.9 KiB
Markdown
# 来源图库、生成方案与终端
|
|
|
|
平台图库分为两类：来源图库与终端图库。照片数据源的每条配置对应一个来源图库，可以建立多个。每个来源图库拥有自己的生成方案，方案不能跨来源移动。每个终端最多绑定一个来源图库及其中一个方案；同一来源、同一方案允许多个终端共用。未完成绑定的终端不参与来源统一输出。
|
|
|
|
## 使用顺序
|
|
|
|
1. 在“照片数据源”配置来源、人物、分辨率、质量、去重等选图条件。
|
|
2. 在侧栏“来源图库”选择来源，选入照片，保存无文字叠加的源画面。
|
|
3. 新增该来源内的生成方案，可使用相框横版、竖版、手表预设，或自定义尺寸、适配方式、裁切位置、质量、色彩与说明叠加。也可将旧版小图方案参数复制到所选来源下。
|
|
4. 来源图库标签为“源画面”和该来源的生成方案；未生成的版本明确显示未生成，生成后可预览、下载、查看参数快照、删除。归档方案仍可查看已有版本。
|
|
5. 在“终端图库”对每个终端单选来源和方案。切换来源后必须重新选择方案，服务端检查归属和屏幕尺寸。绑定同一方案的终端共用生成文件。
|
|
6. 需要自动化时，为照片任务勾选“按来源图库统一生成并推送”。新建照片任务默认使用该模式；旧任务不在启动时自动改写，确认绑定后可在编辑任务时切换。唯一明确的单来源、单照片任务也可使用 `scripts/migrate-source-libraries.py` 预检，再加 `--apply` 迁移；脚本保留启用状态、调度配置和下次执行时间，不推送设备。若当前设备有可靠的照片来源回执，会选入该画面并仅在本地生成两个版本。生成模式不再额外选择旧版小图方案。
|
|
|
|
## 从来源选入照片
|
|
|
|
“从来源选入照片”打开独立选图页面，使用照片卡片、按需预览和前后翻页。Synology Photos 每批显示最多 36 张照片，直接按偏移量读取 NAS 元数据，不再先遍历整个目录。一次请求最多检查四批；筛选较少见的照片时，当前批可能不足 36 张或为空，仍可继续下一页检索。页码表示当前扫描位置，不提供未经全库扫描的虚假总数；NAS 内容变动时可重置筛选重新浏览。
|
|
|
|
可按文件名、文件夹关键字、文件大小、像素宽高、日期范围及识别人物组合筛选。保留来源本身的目录、递归、人物、方向、最小分辨率等限制。日期使用系统时区：入库日期取 NAS `indexed_time`，照片日期取 `time`，不将入库时间冒充原文件创建时间。人物数据使用 NAS 现有识别结果，不执行新的人脸识别。
|
|
|
|
预览懒加载 NAS 中图（`m`），选入时才下载用于本地生成的 XL 画面。已浏览的选择记录缓存最多 2048 条、有效期 30 分钟，并绑定来源配置和 NAS 会话；来源范围或登录账号改变后不能复用旧预览。选入会使用已校验的页面记录，避免再次全库读取和遍历所有人物相册。其他云盘继续使用现有目录接口，高级筛选与快速分页仅支持 Synology Photos。
|
|
|
|
## 一次选图，多种版本
|
|
|
|
任务先选定一次源画面并保存到本地，再按来源的终端绑定生成版本。默认等比裁切铺满，不拉伸、不补黑边。主动选择完整画面时必要处补白；说明叠加使用来源提供的日期、标题、地点等元数据。源画面本身始终不加文字。Synology Photos 当前取得的是可用源预览，不称为原图；本地存储按画面原尺寸归一化为 JPEG 并处理 EXIF 朝向。
|
|
|
|
每份成品关联源画面、方案 ID 和生成时的完整参数快照。相同源画面和相同参数复用已有版本；修改方案后重新生成产生新版本，不覆盖历史图片。任务持久保存选图和方案快照，进程中断后继续处理该画面，不重新随机选图或重复提交同一终端输出。
|
|
|
|
相框通过现有上传队列和设备确认流程传输；“已生成”“待推送”“等待设备确认”“已确认显示”分别记录。来源任务完成代表生成和提交完成，不代表所有终端已显示；具体结果看终端图库的独立操作。手表当前只生成 410×502 成品，传输尚未接入。某个方案生成失败不撤销其他输出，源画面保留，可以单独重新生成或重新推送失败目标。
|
|
|
|
在来源图库手动点击“随机选入并按绑定生成”只生成，不自动推送。终端图库的相框推送需要明确点击并确认，受全局设备写入开关约束。更换终端绑定后，尚未执行的旧版本推送会在设备写入前重新校验，不符合当前绑定时停止。
|
|
|
|
## 保留与删除
|
|
|
|
来源文件放在 `data/source-images/`，版本放在 `data/renditions/`，不进入旧的临时缓存自动清理范围。来源图库的星标与不再选用沿用照片来源偏好，二者互斥；不再选用只影响后续自动选图。
|
|
|
|
删除本地源画面会同时删除其本地生成版本，执行前检查任务、模板和待处理操作的引用；不会删除上游照片或设备已接收的副本。删除方案采用归档，历史版本保留快照；被终端绑定的方案必须先解除或更换绑定。包含绑定、活动方案或本地源画面的来源配置禁止直接删除。
|
|
|
|
旧本地成品、旧小图及现有云端图片均保留，通过“历史本地成品”“旧版小图图库”“设备已有云端图片”查看。不会凭文件名或尺寸将旧成品猜测为源画面，不自动覆盖旧任务或推断终端绑定。
|
|
|
|
## API 与存储
|
|
|
|
- `/api/v1/source-libraries`：来源图库；`/{id}/images`、`/import`、`/run` 用于列表、选入与统一生成。
|
|
- `/api/v1/source-libraries/{id}/browse`：按批浏览 NAS 元数据；`/browse/{item_id}/preview` 读取已浏览照片的小预览。
|
|
- `/api/v1/generation-plans`：按 `source_id` 查询与创建方案；`/{id}` 修改或归档。
|
|
- `/api/v1/source-images/{id}`：源画面删除；`/generate`、`/preview`、`/star`、`/exclusion` 用于版本生成、预览和来源偏好。
|
|
- `/api/v1/library-terminals`：终端；`/{id}/binding` 管理单一绑定，`/{id}/images` 查询成品，`/{id}/images/{asset_id}/send` 显式推送。
|
|
- `/api/v1/library-versions/{asset_id}`：删除本地成品版本。
|
|
- `PUT /api/v1/jobs/{job_id}/library-mode`：使用 `jobs:write` 切换模式，保留下次执行时间和启用状态。
|
|
|
|
新增 `library_plans`、`source_images`、`library_versions`、`terminal_bindings`、`terminal_deliveries` 表，复用现有 SQLite、资源鉴权、Pillow 渲染及任务队列。`terminal_bindings.terminal_id` 是主键，保证终端仅有一个绑定；服务端同步校验来源、方案、版本归属以及屏幕尺寸。读取需要 `images:read`，管理需要 `admin`，本地删除需要 `images:delete`，终端推送需要 `display:write`。旧 API 保留兼容。
|