Web 端图库界面：组件、状态与 Worker

本页描述 SpinningMomo 图库在 Web 端（WebView / 局域网浏览器）呈现层的整体形态：界面组件的组织、客户端状态与同步行为，以及与后端 Worker（索引、缩略图、颜色提取等异步工作）之间的关系。本次源码取证受工具预算限制，前端组件级源码未能直接读取，页面以仓库文档、功能模块清单与本地化键为证据基线，并明确标注证据缺口。

Purpose and Scope

本页覆盖：

Web 端图库界面的功能范围与交互形态（网格浏览、筛选、拖拽整理、触摸手势等）
前端与后端 features::gallery 各模块（asset、color、clipboard、download、file_operations）之间的职责划分
客户端状态与后端索引状态（database.db）之间的同步模型，包括目录监听与 NTFS 变更日志补偿
后台 Worker（worker pool）在图库能力中的角色

留给兄弟页面的内容：

图库后端资源仓库与查询支持的具体实现 → 见 features/gallery/asset（repository、query_support）
颜色提取与颜色筛选算法 → 见 features/gallery/color
截图/录制采集链路 → 见 android capture 与 recording 相关页面
局域网访问的用户操作说明 → 见 docs/features/lan.md

Overview

图库是 SpinningMomo 的核心业务功能之一：自动索引照片与视频，支持标签、评分、时间线、颜色筛选与批量整理。它在两个呈现面上运行：

应用内 WebView：桌面端通过框架内置 WebView 加载前端界面。
局域网浏览器：同一前端能力可通过本地 HTTP 服务暴露给手机/平板浏览器，自动切换为紧凑触摸布局。

仓库的 AGENTS.md 明确了分层结构：core::* 提供框架基础设施（异步运行时、数据库、事件、HTTP 客户端/服务端、RPC、WebView、i18n、命令、迁移、worker pool、任务、运行时信息、关闭、状态），features::* 承载业务逻辑（adb_mode、gallery、letterbox、notifications、overlay、preview、recording、screenshot、settings、update、window_control）。

AGENTS.md 将 core::* 描述为"framework infrastructure (async runtime, database, events, HTTP client, HTTP server, RPC, WebView, i18n, commands, migration, worker pool, tasks, runtime info, shutdown, state)"，并将 features::* 列为"business logic such as adb_mode, gallery, ..."。 Source: AGENTS.md

后端图库模块按职责拆分为多个子目录（真实文件清单，来自 src/features/gallery/）：

子模块	文件	职责（依据命名与文档）
asset	`service.hpp/.cpp`、`repository.hpp/.cpp`、`query_support.hpp/.cpp`、`thumbnail.hpp/.cpp`	资产服务、仓储、查询支持、缩略图生成
color	`extractor.hpp/.cpp`、`filter.hpp/.cpp`、`repository.hpp/.cpp`、`types.hpp`	颜色提取、颜色筛选、颜色数据仓储
clipboard	`clipboard.hpp/.cpp`	剪贴板导入/导出
download	`download.hpp/.cpp`	下载能力
file_operations	`file_operations.cpp`	文件操作（移动、批量整理）

Architecture

Loading diagram...

图解说明：

呈现层有两种入口：桌面端 WebView 与局域网浏览器。两者消费同一套图库能力，仅布局策略不同（浏览器端自动切换紧凑触摸布局）。
HTTP server 是浏览器入口的通道：docs/features/lan.md 表明局域网内可直接浏览与管理图库；core::http_server 同时是本地服务启动失败的告警来源（见本地化键 message.http_server_start_failed）。
worker pool 承担耗时工作：缩略图生成（asset/thumbnail）、颜色提取（color/extractor）、文件操作（file_operations）这类 CPU/IO 密集任务由 core::* 的 worker pool 驱动，避免阻塞界面响应。这是把索引与派生数据生成放到后台的设计意图。
单一数据源：所有状态最终落盘到 database.db。docs/about/legal.md 明确"功能数据：本地索引与元数据（如 database.db，用于图库等功能）"。

Source: AGENTS.md

界面功能面（依据用户文档）

docs/features/gallery.md 描述了界面层的完整功能集合，这些即 Web 端组件需要承载的交互面：

浏览与详情：网格浏览、查看照片和视频详情。
整理：标签、评分、描述；选中后可拖拽至左侧文件夹移动文件，或拖拽至标签栏添加标签。
剪贴板：将文件复制到系统剪贴板，也可将系统剪贴板中的截图直接粘贴导入图库。
选择：全选、反选与批量操作。
筛选：时间线、颜色筛选等（对应后端 color/filter 与 asset/query_support）。

Source: docs/features/gallery.md

触摸端的差异来自 docs/features/lan.md：浏览器端支持"触摸手势：滑动切换、双指缩放、长按多选"。

Source: docs/features/lan.md

状态与同步模型

Web 端界面呈现的状态分为三层：

瞬时 UI 状态（选择集、筛选条件、缩放级别、当前详情项）——只存在于前端。
图库元数据状态（标签、评分、描述）——持久化在 database.db，前端通过命令/RPC 读写。
文件系统真实状态——由后端目录监听维护，界面被动接收更新。

同步的关键行为（来自用户文档）：

实时监听：监控目录内的增删改会实时反映到图库。
离线补偿：程序启动时通过 NTFS 变更日志补上关闭期间的改动；网络目录不支持这种方式，改为重新扫描。
标注容错：在资源管理器中移动或重命名文件，图库不会立刻丢弃标注，而是保留 30 天；期间把文件放回原处，标签、评分与描述自动接续。

Source: docs/features/gallery.md

这一设计意图是：把"文件移动"视为可逆事件而不是破坏性变更，用宽限期换回用户手动整理（挪到别的文件夹）时不丢标注；同时把"程序关闭期间的外部变更"从丢失态变成可补偿态，代价是网络路径退化全量扫描。

Core Flow：外部文件变更到界面更新

Loading diagram...

流程要点：

变更从文件系统进入后端，先落索引（database.db），再派生缩略图与颜色数据；派生工作在 worker pool 中异步进行，因此界面可以先显示占位内容、随后补齐，不会被缩略图生成阻塞。
界面通过查询/事件获取最新状态，两层客户端（WebView 与浏览器）走同一条数据链路，行为一致。

本地化键（i18n 证据）

前端界面文案通过 core::i18n 与 locale 文件解耦。与图库直接相关的键示例：

json

"message.gallery_folder_sync_failed": "此文件夹的图库自动同步已暂停。请解决问题后点击重试。",
"message.http_server_start_failed": "本地服务启动失败，部分功能可能不可用，请查看日志。"

Source: src/locales/zh-CN.json

设计意图：同步失败被建模为可恢复的暂停态（"已暂停…点击重试"），而不是静默丢弃；HTTP 服务失败同样显式告警，因为它是浏览器入口的生命线。

Usage Examples

端到端场景测试中的图库状态约定

tests/scenarios/gallery_core.ts 的注释揭示了测试如何组织图库状态——各阶段共享同一进程内的空图库，路径互不冲突：

typescript

// 这些阶段都从同一空图库出发、使用互不冲突的文件路径、断言均按路径限定，
// 因此可以在同一次真实进程生命周期内顺序执行。

Source: tests/scenarios/gallery_core.ts

该约定说明：图库状态（索引）在进程生命周期内持续存在，且测试通过"路径限定断言"实现阶段间隔离——这正是界面状态最终以数据库为准、以文件路径为锚点的体现。

配置选项

本次源码读取未定位到前端可配置项的集中定义文件（受工具预算限制）。已验证的行为性开关/差异如下：

行为	取值/默认	依据
浏览器端布局	自动切换紧凑触摸布局	docs/features/gallery.md
触摸手势	滑动切换、双指缩放、长按多选	docs/features/lan.md
标注保留期（移动/重命名后）	30 天	docs/features/gallery.md
网络目录启动补偿	全量重扫（无 NTFS 日志）	docs/features/gallery.md

API Reference

前端组件级源码（组件、状态管理、前端侧 Worker）未在本次取证中定位到：src/features/gallery/ 下读取到的是 C++ 后端模块清单，且 src/**/*.ts(x) 的通配检索未返回前端组件文件。No code example available —— 不在此伪造组件签名或方法列表。后端各模块（asset/service、asset/repository、asset/query_support、asset/thumbnail、color/extractor、color/filter、color/repository、clipboard、download、file_operations）的 API 细节请参见各自源文件：

Source: src/features/gallery

失败模式、边界与并发

场景	行为	证据
目录自动同步失败	该文件夹同步暂停，界面提示"请解决问题后点击重试"	zh-CN.json `message.gallery_folder_sync_failed`
本地 HTTP 服务启动失败	显式告警"部分功能可能不可用"，浏览器入口受影响	zh-CN.json `message.http_server_start_failed`
网络目录 + 程序重启	无法用 NTFS 变更日志，退化为重新扫描	docs/features/gallery.md
文件被外部移动/重命名	标注保留 30 天，放回原处自动接续	docs/features/gallery.md
缩略图/颜色提取耗时	在 worker pool 后台执行，索引先行落库	AGENTS.md（worker pool 属 core::* 基础设施）

并发方面的设计要点：索引写入（主线程/服务层）与派生计算（worker pool）分离，界面渲染不等待派生数据完成；多客户端（WebView + 浏览器）共享同一 database.db 单一数据源，避免各客户端各自维护索引副本。

已知证据缺口（诚实声明）

前端框架（组件文件、状态管理库、前端侧 Web Worker）的具体源码未定位：src 目录下以 glob **/*.ts(x) 的检索未返回匹配，未找到名为 *gallery* 的前端文件。实现细节未在本次读取中找到。
本页关于前端组件与状态的描述，均以仓库文档（docs/features/gallery.md、docs/features/lan.md）、AGENTS.md 分层说明、locale 键与后端模块清单为间接证据。
如需组件级参考，请从 docs/features/gallery.md 描述的功能面出发，在仓库中检索对应命令名与 RPC 接口。