feat: add paged NAS photo browser with metadata filters and previews

docs/SOURCE_LIBRARIES.md

@@ -5,12 +5,20 @@
 ## 使用顺序
 
 1. 在“照片数据源”配置来源、人物、分辨率、质量、去重等选图条件。
-2. 在“图库 → 来源图库”选择来源，选入照片，保存无文字叠加的源画面。
+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 朝向。
@@ -32,6 +40,7 @@
 ## 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` 显式推送。