核心概念

• 磁盘中存在文件 ≠ 已入库；只有人工执行「收录」后才创建 Item 与 Asset 记录。
• 收录只登记原文件相对路径，不复制、不移动原文件。
• 每个正式（active）Item 必须有 Cover；没有 Cover 可暂存为 draft，不进入默认瀑布流（草稿可在「系统配置」中激活或归档）。
• SQLite 保存结构化元数据；二进制文件始终保存在 OMV SMB。
• 未收录的 SMB 文件永远不会出现在瀑布流中。

资源类型（7 种）

收录流程

1. 在右侧边栏点击「收录 SMB 文件」，打开文件浏览器。
2. 进入目标文件夹勾选文件，或直接点击「上传文件」从本地上传（支持一次多选图片 / 视频）。
3. 勾选一个或多个文件（它们将属于同一个 Item）。
4. 选择 Item 类型、填写标题、选择主分类和 Cover。
5. 确认后创建 Item 与 Asset，校验路径与 Cover，Item 置为 active 进入瀑布流。
6. 没有合适 Cover 时可先「存为草稿」，之后在系统配置中补设 Cover 激活。

Cover 规则

• 图片：图片本身；商品包：商品主图；文章 / 图文包 / 网页：用户指定代表性图片。
• 视频 / 视频包：第一版从文件夹现有图片选择 Cover；视频截帧将在后续版本提供。
• Cover 必须关联有效图片 Asset，否则 Item 无法激活。

浏览与筛选

• 类型与分类联动：选中类型后只显示该类型的分类；返回「全部」恢复所有类型。
• 瀑布流等宽、保留原始宽高比、每列独立堆叠，支持 2 / 3 / 4 列切换（默认 3 列并记住选择）。
• 排序：最新收录 / 最近更新；类型或分类变化后自动重置分页游标。
• 分页采用稳定游标（keyset）按需加载；已加载内容滚动到尽头时循环复用，不会刷到顶或到底。
• 详情在主画布打开；返回画廊时恢复滚动位置、筛选、排序与列数。
• 沉浸模式：画廊信息条 / 详情页 / 边栏均可进入，全黑背景按当前筛选逐张播放 Cover；边栏「沉浸模式」区设置自动切换间隔（可关闭），左滑 / 右滑或 ← / → 键切换，空格播放暂停，Esc 退出；控制条闲置数秒后自动隐藏，点击画面唤醒。
• 旧设备兼容入口 /lite/：只提供沉浸播放的独立精简页面（与主站 UI 无关，仅共享资源数据），用于 iOS 10.3.3 等不支持现代特性的浏览器；主线检测到不支持的环境会自动跳转到该入口，加 ?main=1 可强制留在主线。两页共用同一份自动切换间隔设置。

API 与 Token

• 外部系统一律通过 /api/v1/ 访问，不直接读写 SQLite；接口文档见 /api/docs。
• 设置环境变量 API_TOKEN 后，所有写操作需要请求头 X-API-Token；可在「系统配置」中保存 Token 供本页使用。
• 视频通过 /api/v1/files/raw 提供 HTTP Range 流式播放。

草稿 Item（不进入默认瀑布流）

危险操作