b54c2def30
- Add database migrations (006-028) for face recognition, identity, file_uuid - Add test scripts for ASR, face, search, processing - Add portal frontend (Tauri) - Add config, benchmark, and monitoring utilities - Add model checkpoints and pretrained model references
223 lines
5.1 KiB
Markdown
223 lines
5.1 KiB
Markdown
# Momentry Core & Portal 分析與改進建議
|
|
|
|
## 執行摘要
|
|
|
|
**分析日期**: 2026-04-26
|
|
**分析範圍**: Momentry Core v0.1 + Portal
|
|
**主要發現**: 架構技術債、代碼質量問題、文檔管理混亂
|
|
**優先建議**: 模塊化重構、安全性改進、文檔規範化
|
|
|
|
---
|
|
|
|
## 一、系統現狀分析
|
|
|
|
### 1.1 技術架構
|
|
- **Momentry Core**: Rust + Axum + 多數據庫 (PostgreSQL, MongoDB, Redis, Qdrant)
|
|
- **Portal**: Vue 3 + TypeScript + Tauri (雙模式)
|
|
- **代碼規模**: 核心 3,343 行 (`main.rs`), Portal 405 行 (`FilesView.vue`)
|
|
|
|
### 1.2 關鍵問題
|
|
#### 架構層面
|
|
1. **模塊化不足**: `main.rs` 過長 (3,343 行)
|
|
2. **錯誤處理不一致**: 混合 `anyhow` 和 `thiserror`
|
|
3. **數據庫模式混亂**: `public.videos` 與 `dev.videos` 並存
|
|
|
|
#### 代碼質量
|
|
1. **類型安全缺失**: API 返回 `any` 類型
|
|
2. **組件過大**: `FilesView.vue` 包含過多邏輯
|
|
3. **安全風險**: 客戶端硬編碼 API 密鑰
|
|
|
|
#### 文檔管理
|
|
1. **文件重複**: `docs_v1.0/` 中大量 `ROOT_*` 副本
|
|
2. **規範不一致**: 未完全遵循 `DOCS_STANDARD.md`
|
|
|
|
---
|
|
|
|
## 二、Momentry Core 改進建議
|
|
|
|
### 2.1 架構重構 (P0)
|
|
```rust
|
|
// 建議結構
|
|
src/
|
|
├── cli/ # CLI 命令
|
|
├── processing/ # 處理邏輯
|
|
├── api/ # HTTP 接口
|
|
└── main.rs # 精簡入口 (<500 行)
|
|
```
|
|
|
|
### 2.2 錯誤處理統一
|
|
```rust
|
|
// core/error.rs
|
|
#[derive(Debug, thiserror::Error)]
|
|
pub enum CoreError {
|
|
#[error("Database error: {0}")]
|
|
Database(#[from] sqlx::Error),
|
|
// ...
|
|
}
|
|
pub type Result<T> = std::result::Result<T, CoreError>;
|
|
```
|
|
|
|
### 2.3 配置管理集中化
|
|
```rust
|
|
// core/config.rs
|
|
pub struct Config {
|
|
pub database_url: String,
|
|
pub redis_url: String,
|
|
pub output_dir: PathBuf,
|
|
// 統一管理環境變數
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 三、Portal 改進建議
|
|
|
|
### 3.1 已完成修正 (P0)
|
|
✅ **文件註冊狀態管理**:
|
|
- 已註冊文件: 按鈕灰化，顯示「已註冊」
|
|
- 未註冊文件: 藍色「立即註冊」按鈕
|
|
- 時間顯示: ✓ 已註冊時間 / ⚠️ 未註冊時間
|
|
|
|
### 3.2 架構優化 (P1)
|
|
#### 組件拆分
|
|
```
|
|
src/views/FilesView/
|
|
├── FilesView.vue # 主組件
|
|
├── FileTable.vue # 表格
|
|
├── FileFilters.vue # 過濾器
|
|
└── FileActions.vue # 操作按鈕
|
|
```
|
|
|
|
#### 狀態管理
|
|
```typescript
|
|
// stores/fileStore.ts
|
|
export const useFileStore = defineStore('files', {
|
|
state: () => ({
|
|
files: [] as FileItem[],
|
|
loading: false,
|
|
}),
|
|
actions: {
|
|
async fetchFiles() { /* ... */ }
|
|
}
|
|
})
|
|
```
|
|
|
|
### 3.3 安全性改進 (P1)
|
|
```typescript
|
|
// ❌ 當前: 硬編碼
|
|
api_key: 'muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69'
|
|
|
|
// ✅ 建議: 環境變數
|
|
const API_KEY = import.meta.env.VITE_API_KEY
|
|
```
|
|
|
|
---
|
|
|
|
## 四、文檔與規範改進
|
|
|
|
### 4.1 文件結構優化
|
|
```
|
|
docs/
|
|
├── guides/ # 使用指南
|
|
├── reference/ # 參考文檔
|
|
├── standards/ # 規範標準
|
|
└── templates/ # 模板文件
|
|
```
|
|
|
|
### 4.2 AI Agent 友好化
|
|
```yaml
|
|
---
|
|
document_type: "api_reference"
|
|
service: "MOMENTRY_CORE"
|
|
title: "Video Registration API"
|
|
ai_query_hints:
|
|
- "如何註冊視頻文件？"
|
|
- "/api/v1/register 端點參數"
|
|
---
|
|
```
|
|
|
|
---
|
|
|
|
## 五、實施路線圖
|
|
|
|
### 階段 1: 基礎穩定性 (1-2 周)
|
|
- ✅ Portal 註冊按鈕狀態修正
|
|
- 🔄 拆分 `main.rs` 文件
|
|
- 🔄 統一錯誤處理
|
|
- 🔄 修復安全問題
|
|
|
|
### 階段 2: 架構優化 (2-4 周)
|
|
- 🔄 數據庫模式統一
|
|
- 🔄 API 設計規範化
|
|
- 🔄 配置管理集中化
|
|
- 🔄 清理重複文檔
|
|
|
|
### 階段 3: 高級功能 (4-8 周)
|
|
- 🔄 性能優化
|
|
- 🔄 實時狀態更新
|
|
- 🔄 多語言支持
|
|
- 🔄 監控系統添加
|
|
|
|
---
|
|
|
|
## 六、風險評估
|
|
|
|
| 風險 | 影響 | 概率 | 緩解措施 |
|
|
|------|------|------|----------|
|
|
| 數據庫遷移風險 | 高 | 中 | 完整備份 + 逐步遷移 |
|
|
| API 兼容性問題 | 中 | 高 | 版本控制 + 兼容層 |
|
|
| 開發時間超支 | 中 | 中 | 分階段實施 + MVP 優先 |
|
|
|
|
---
|
|
|
|
## 七、成功指標
|
|
|
|
### 技術指標
|
|
- 單文件行數 < 1000 行
|
|
- 測試覆蓋率 > 80%
|
|
- API 響應時間 < 200ms (P95)
|
|
|
|
### 業務指標
|
|
- 新功能開發時間減少 30%
|
|
- Bug 修復時間減少 50%
|
|
- 文檔查找時間減少 70%
|
|
|
|
---
|
|
|
|
## 八、結論與建議
|
|
|
|
### 立即行動 (本週)
|
|
1. **驗證 Portal 修正**: 確認註冊按鈕狀態正確
|
|
2. **啟動架構重構**: 制定 `main.rs` 拆分計劃
|
|
3. **安全漏洞修復**: 移除硬編碼 API 密鑰
|
|
|
|
### 短期規劃 (1個月)
|
|
1. **完成模塊化重構**
|
|
2. **實施統一錯誤處理**
|
|
3. **規範化文檔管理**
|
|
|
|
### 長期願景 (3-6個月)
|
|
1. **平台成熟**: 完整 API 生態系統
|
|
2. **企業級運維**: 監控、日誌、備份
|
|
3. **社區發展**: 開發者文檔、示例項目
|
|
|
|
---
|
|
|
|
## 附錄
|
|
|
|
### 相關文件
|
|
1. `AGENTS.md` - 開發指南與規範
|
|
2. `docs_v1.0/STANDARDS/DOCS_STANDARD.md` - 文檔標準
|
|
3. `portal/src/views/FilesView.vue` - 核心 UI 組件
|
|
|
|
### 技術規範
|
|
- Rust 2021 Edition
|
|
- TypeScript 嚴格模式
|
|
- Markdown 文檔標準
|
|
- API RESTful 設計
|
|
|
|
---
|
|
|
|
**最後更新**: 2026-04-26
|
|
**分析者**: OpenCode
|
|
**狀態**: 草案 - 待審查 |