# 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