From e11ee429f19bc3792d68843d7a4cc8c6f90d7fae Mon Sep 17 00:00:00 2001 From: Momentry Studio Date: Sun, 11 Oct 2026 16:41:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20Tauri=20GUI=20?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=88=86=E6=9E=90=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 内容: - 四大模块总览（Search, File Prep, Admin, File Mgmt） - 每个模块的详细分析（组件、API、数据流、数据库） - 模块间交互关系和依赖关系 - 已知问题和改进建议 - API 调用链示例 - 技术栈总结 四大模块: 1. Search - 多模式搜索 + 历史管理 2. File Prep/Processing - Pipeline 处理 + 状态追踪 3. Admin - 系统监控 + 配置管理 4. File Management - 文件上传/下载/移动 关键问题: - 双 API 架构复杂度 - 状态同步不一致 - 缩略图缓存无淘汰策略 - Pipeline 进度轮询效率低 - Admin 配置无验证 改进建议: - 短期: WebSocket 状态推送、LRU Cache、批量查询 - 中期: 统一 API Gateway、Resumable Upload - 长期: IndexedDB、离线模式、插件系统 --- docs/ARCHITECTURE.md | 441 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 441 insertions(+) create mode 100644 docs/ARCHITECTURE.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..975979d --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,441 @@ +# Momentry Studio Tauri GUI 架构文档 + +**生成时间:** 2026-10-10 +**版本:** v1.0.0 + +--- + +## 1. 四大模块总览 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Momentry Studio GUI │ +│ (Vue 3 + TypeScript + Vite) │ +└────────────────────────────┬────────────────────────────────────────┘ + │ + ┌────────────────────┼────────────────────┐ + │ │ │ + ▼ ▼ ▼ +┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐ +│ Search Module │ │ File Prep/ │ │ Admin Module │ │ File Mgmt │ +│ │ │ Processing │ │ │ │ Module │ +│ SearchView │ │ LibraryView │ │ AdminView │ │ ClientView │ +└───────┬───────┘ └───────┬───────┘ └───────┬───────┘ └──────┬───────┘ + │ │ │ │ + └──────────────────┼──────────────────┼──────────────────┘ + │ │ + ┌──────────┴──────────┐ │ + │ │ │ + ▼ ▼ ▼ + ┌───────────────┐ ┌──────────────┐ ┌──────────────┐ + │ Core API │ │ MarkBase API │ │ Local SQLite │ + │ (localhost: │ │ (localhost: │ │ (demo.sqlite)│ + │ 3002) │ │ 11438) │ │ │ + └───────┬───────┘ └───────┬──────┘ └──────────────┘ + │ │ + │ /api/v1/* │ /api/v2/* + │ (Momentry Core) │ (MarkBase Core) + │ │ + └────────────────────┼────────────────────┐ + │ │ + ┌──────────┴──────────┐ │ + │ Studio Proxy │ │ + │ (localhost:8888) │ │ + │ - v1/v2 gateway │ │ + │ - API key inject │ │ + │ - Face thumbnail │ │ + │ - Search history │ │ + │ - Bookmarks │ │ + └─────────────────────┘ │ + │ + ┌──────────────────────────────┘ + │ + ┌───────────┴────────────┐ + │ Tauri IPC Commands │ + │ (19 Rust commands) │ + │ - search_llm_smart │ + │ - get_files │ + │ - get_people │ + │ - register_file │ + │ - process_file │ + │ - update_identity │ + │ - get_thumbnail │ + │ - etc. │ + └────────────────────────┘ +``` + +--- + +## 2. 模块详解 + +### 2.1 Search 模块 + +**职责:** 提供多模式搜索功能（Keyword, Semantic, Visual, Agent, People） + +**前端组件:** +- `SearchView.vue` - 主搜索界面 +- `VideoPlayer.vue` - 搜索结果播放 +- `useSearchHistory.ts` - 搜索历史管理 +- `useBookmarks.ts` - 书签管理 + +**API 端点:** +```typescript +// v1 端点 (Momentry Core API) +/api/v1/search/keyword // 关键字搜索 +/api/v1/search/semantic // 语义搜索 +/api/v1/search/llm-smart // LLM 智能搜索 +/api/v1/search/people // 人物搜索 +/api/v1/agents/search // Agent 搜索 +/api/v1/search/vlm/scenes // Scene VLM 搜索 +/api/v1/search/vlm/traces // Trace VLM 搜索 + +// v1 端点 (本地处理) +/api/v1/search-history // 搜索历史 +/api/v1/bookmarks // 书签 +``` + +**数据流:** +``` +用户输入 → SearchView → apiCall() → Core API + ↓ +返回结果 → mergeResults() → 结果卡片 + ↓ +History/Bookmarks → SQLite (demo.sqlite) +``` + +**数据库:** +- `search_history` (SQLite) - 搜索历史 +- `bookmarks` (SQLite) - 书签 + +**关键特性:** +1. **多模式搜索:** Keyword, Semantic, Visual, Agent, People 五种模式 +2. **OCR 合并:** 相似文本自动合并，减少重复 +3. **搜索历史:** SQLite 持久化，支持 Pin/Rename/Delete +4. **书签系统:** 快速访问常用搜索 + +--- + +### 2.2 文件准备/处理模块 + +**职责:** 管理原始档案的处理流程，从注册到完成 + +**前端组件:** +- `LibraryView.vue` - 文件列表和处理控制 +- `PeopleView.vue` - 人物管理 +- `PersonDetailView.vue` - 人物详情 + +**API 端点:** +```typescript +// v1 端点 +/api/v1/files/register // 注册文件 +/api/v1/file/{uuid}/process // 处理文件 +/api/v1/unregister // 注销文件 +/api/v1/file/{uuid}/sync-status // 同步状态 +/api/v1/progress/{uuid} // 处理进度 +/api/v1/stats/pipeline/{uuid} // Pipeline 统计 +/api/v1/stats/file/{uuid} // 文件统计 +/api/v1/file/{uuid}/processor-counts // 处理器统计 +/api/v1/re-scan // 重新扫描 +``` + +**处理 Pipeline:** +``` +Rule 1 Ingestion → Face Tracing → Face Dedup → +TKG Nodes → TKG Edges → Rule 2 Ingestion → +VLM Summary → Scene VLM +``` + +**状态机:** +``` +registered → scanning → keyword_ready → +semantic_ready → face_mgmt_ready → agent_ready +``` + +**数据库:** +- `videos` (PostgreSQL) - 文件注册表 +- `monitor_jobs` (PostgreSQL) - 处理任务 +- `processor_status` (PostgreSQL) - 处理器状态 + +**关键特性:** +1. **状态追踪:** 6 个状态，实时更新 +2. **进度监控:** Pipeline 进度 + 系统资源 +3. **批量操作:** 批量注册、扫描、注销 +4. **处理器控制:** 单独重跑 ASR/OCR/Face 等 + +--- + +### 2.3 Admin 监控及参数模块 + +**职责:** 系统监控、配置管理、服务控制 + +**前端组件:** +- `AdminView.vue` - 管理界面 + +**API 端点:** +```typescript +// v1 端点 +/api/v1/health // 健康检查 +/api/v1/system-stats/validate // 系统验证 +/api/v1/admin/config // 系统配置 + +// v2 端点 +/api/v2/admin/system-stats // 系统统计 +/api/v2/admin/users // 用户列表 +/api/v2/admin/shares // 共享列表 +/api/v2/service/start // 启动服务 +/api/v2/service/stop // 停止服务 +``` + +**配置文件:** +```json +// admin_config.json +{ + "vlm_prompts": {...}, + "llm_config": {...}, + "processor_config": {...}, + "filter_config": {...}, + "search": {...} +} +``` + +**关键特性:** +1. **系统监控:** CPU、内存、GPU、ANE 实时监控 +2. **服务管理:** Core API、MarkBase、MBE、Proxy 启停 +3. **配置编辑:** VLM Prompts、LLM、Processor、Filter 配置 +4. **语言包管理:** 多语言支持 + +--- + +### 2.4 File Management 模块 + +**职责:** 原始档案的上传、下载、移动、删除 + +**前端组件:** +- `ClientView.vue` - 文件浏览器 + +**API 端点:** +```typescript +// v2 端点 +/api/v2/myfiles/{user}/folders // 文件夹列表 +/api/v2/myfiles/{user}/files // 文件列表 +/api/v2/upload-unlimited/{user} // 上传文件 +/api/v2/myfiles/{user}/preview/{filename} // 文件预览 +/api/v2/myfiles/{user}/move // 移动文件 +/api/v2/myfiles/{user}/tags // 标签管理 +``` + +**数据库:** +- `files` (MarkBase PostgreSQL) - 文件元数据 +- `folders` (MarkBase PostgreSQL) - 文件夹结构 + +**关键特性:** +1. **文件浏览器:** 文件夹导航、搜索、排序 +2. **上传管理:** 多文件上传、进度显示 +3. **文件操作:** 重命名、移动、删除 +4. **预览功能:** 多格式预览 +5. **拖拽支持:** 文件拖拽移动 + +--- + +## 3. 数据流图 + +### 3.1 搜索数据流 +``` +User Query → SearchView → apiCall() + ↓ +Core API (PostgreSQL + Qdrant + MongoDB) + ↓ +Results → VideoPlayer + ↓ +History/Bookmarks → SQLite +``` + +### 3.2 文件处理数据流 +``` +File Selection → register_file() + ↓ +videos (PostgreSQL) → Pipeline + ↓ +Processor Output (*.json) → Ingestion + ↓ +Status Update → LibraryView +``` + +### 3.3 Admin 配置数据流 +``` +Admin Edit → admin_config.json + ↓ +Service Control (MarkBase API) +Config Reload (Core API) +``` + +--- + +## 4. 模块间交互 + +### 4.1 依赖关系 +``` +Search Module + ├──> File Management (缩略图、视频流) + ├──> Admin Module (VLM 配置) + └──> Core API (搜索数据) + +File Prep/Processing + ├──> File Management (原始文件) + ├──> Admin Module (处理器配置) + └──> Core API (Pipeline) + +Admin Module + ├──> Core API (配置) + ├──> MarkBase API (服务控制) + └──> File Management (上传路径) + +File Management + ├──> Admin Module (用户权限) + └──> MarkBase API (文件存储) +``` + +### 4.2 数据共享 +- **全局 Store:** `store.ts` + - `filesCache` - 文件列表 + - `thumbnailsCache` - 缩略图 + - `profilesCache` - 人物头像 + - `pipelineStatsCache` - 处理进度 + +- **SQLite 共享:** + - `search_history` - Search 模块 + - `bookmarks` - Search 模块 + - `app_users` - Admin + File Management + +--- + +## 5. 技术栈 + +| 层次 | 技术 | 用途 | +|-----|------|------| +| **前端框架** | Vue 3 + TypeScript + Vite | 响应式 UI | +| **桌面框架** | Tauri 2 | 原生桌面应用 | +| **路由** | Vue Router | SPA 路由 | +| **状态管理** | Pinia-like (store.ts) | 全局状态 | +| **API 层** | Dual-mode (IPC + HTTP) | 桌面/浏览器双模式 | +| **代理层** | Axum (Rust) | API Gateway | +| **数据库** | PostgreSQL + Qdrant + MongoDB | Core 数据存储 | +| **缓存** | Redis | 任务队列 | +| **本地存储** | SQLite (rusqlite) | 历史和书签 | + +--- + +## 6. 已知问题 + +### 6.1 双 API 架构复杂度 +- **问题:** `/api/v1/*` → Core API, `/api/v2/*` → MarkBase API，易混淆 +- **影响:** 文档维护成本高，开发者需要记住命名空间 +- **优先级:** 中 + +### 6.2 状态同步不一致 +- **问题:** `fileStatusCache` 前端和 Core API 状态不同步 +- **影响:** 用户看到的处理状态滞后 +- **优先级:** 高 + +### 6.3 缩略图缓存无淘汰策略 +- **问题:** 缩略图缓存无 LRU 淘汰，内存占用持续增长 +- **影响:** 长时间使用后内存占用过高 +- **优先级:** 中 + +### 6.4 Pipeline 进度轮询效率低 +- **问题:** 每个文件独立轮询，并发处理时 API 压力大 +- **影响:** 系统负载高 +- **优先级:** 高 + +### 6.5 搜索历史功能受限 +- **问题:** 限制 30 条，无全文搜索 +- **影响:** 用户无法按时间/模式过滤历史 +- **优先级:** 低 + +### 6.6 VideoPlayer 性能问题 +- **问题:** 大视频加载慢，Seek 卡顿 +- **影响:** 用户体验差 +- **优先级:** 中 + +### 6.7 Admin 配置无验证 +- **问题:** `admin_config.json` 编辑无前端验证 +- **影响:** 可能保存错误配置导致服务崩溃 +- **优先级:** 高 + +### 6.8 文件上传无断点续传 +- **问题:** 大文件上传失败需重头开始 +- **影响:** 网络不稳定时体验极差 +- **优先级:** 中 + +--- + +## 7. 改进建议 + +### 7.1 短期（1-2 周） +1. ✅ 实现 WebSocket 状态推送，替代轮询 +2. ✅ 增加 LRU Cache 用于缩略图 +3. ✅ 增加批量状态查询 API +4. ✅ 实现 Admin 配置前端验证 + +### 7.2 中期（1-2 月） +1. 统一 API Gateway，简化双 API +2. 实现 Resumable Upload +3. 增强搜索历史功能 +4. VideoPlayer 性能优化 + +### 7.3 长期（3-6 月） +1. 迁移到 IndexedDB 持久化 +2. 实现离线模式 +3. 增加插件系统 +4. 实现多租户架构 + +--- + +## 8. API 调用链示例 + +### 8.1 搜索场景 +```typescript +用户输入 "find red car" + ↓ +apiCall('search_llm_smart', {query: 'find red car'}) + ↓ +[Tauri] invoke('search_llm_smart') +[Browser] httpCall → Proxy :8888 → Core API :3002 + ↓ +Core API 查询 PostgreSQL + Qdrant + ↓ +返回 20 条结果 + ↓ +前端加载缩略图 → 显示卡片 +``` + +### 8.2 文件处理场景 +```typescript +用户选择文件 → register_file() + ↓ +Core API 创建 videos 记录 + monitor_job + ↓ +process_file() → 触发 Pipeline + ↓ +pollPipelineProgress() → 显示进度条 + ↓ +Pipeline 完成 → 状态更新为 'agent_ready' +``` + +--- + +## 9. 总结 + +Momentry Studio 是一个复杂的 Tauri GUI 应用，集成了四大核心模块： + +1. **Search** - 多模式搜索 + 历史管理 +2. **File Prep/Processing** - Pipeline 处理 + 状态追踪 +3. **Admin** - 系统监控 + 配置管理 +4. **File Management** - 文件上传/下载/移动 + +通过双 API 架构（Core API + MarkBase API）实现了功能解耦，但也增加了维护成本。当前主要问题集中在状态同步、性能优化和用户体验改进。 + +--- + +**最后更新:** 2026-10-10 +**维护者:** Momentry Studio Team \ No newline at end of file