momentry_core_0_1/docs/RUST_DEVELOPMENT.md

Rust 開發規範 - Momentry Core

本規範定義 Momentry Core 專案的 Rust 開發標準，確保程式碼品質與一致性。

1. 專案結構

1.1 目錄架構

src/
├── main.rs              # CLI 入口點
├── lib.rs               # 函式庫導出
├── cli/
│   ├── mod.rs
│   └── commands/        # CLI 命令模組
├── core/
│   ├── mod.rs
│   ├── chunk/          # 影片分段邏輯
│   │   ├── mod.rs
│   │   ├── splitter.rs
│   │   └── types.rs
│   ├── db/             # 資料庫抽象層
│   │   ├── mod.rs
│   │   ├── postgres_db.rs
│   │   ├── mongodb_db.rs
│   │   ├── redis_db.rs
│   │   └── qdrant_db.rs
│   ├── processor/       # 影片處理器
│   │   ├── mod.rs
│   │   ├── asr.rs      # 語音識別
│   │   ├── asrx.rs     # 說話者分離
│   │   ├── ocr.rs      # 文字辨識
│   │   ├── yolo.rs     # 物件偵測
│   │   ├── face.rs     # 人臉偵測
│   │   └── pose.rs     # 姿態估計
│   ├── embedding/       # 向量嵌入
│   ├── probe/          # ffprobe 整合
│   ├── storage/        # 檔案管理
│   └── thumbnail/      # 縮圖生成
├── api/                # HTTP API
│   ├── mod.rs
│   └── routes/
├── player/             # 影片播放
└── watcher/            # 檔案監控

1.2 模組設計原則

• 單一職責: 每個模組專注於一項功能
• 介面抽象: 使用 trait 定義資料庫、操作器等介面
• 依賴注入: 透過建構函式注入依賴

pub trait VideoProcessor: Send + Sync {
    async fn process(&self, video_path: &str) -> Result<ProcessResult>;
}

2. 程式碼風格

2.1 命名規範

類型	規範	範例
結構體/列舉	PascalCase	VideoRecord, ChunkType
函式/變數	snake_case	get_video_by_uuid
Trait	PascalCase + er 尾碼	Database, ChunkStore
檔案	snake_case	postgres_db.rs
常量	SCREAMING_SNAKE_CASE	MAX_CHUNK_SIZE
模組	snake_case	chunk, processor

2.2 匯入順序

// 1. 標準庫
use std::path::Path;
use std::process::Command;

// 2. 外部庫
use anyhow::{Context, Result};
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use tokio::fs;

// 3. 內部模組
use crate::core::chunk::Chunk;
use crate::core::db::PostgresDb;

2.3 行寬與格式

• 最大行寬: 100 字元
• 使用 4 空格縮排
• 啟用 clippy 與 fmt

# 格式化
cargo fmt

# 檢查格式
cargo fmt -- --check

# Lint
cargo clippy --all-features

3. 錯誤處理

3.1 錯誤類型選擇

情境	錯誤類型	原因
應用程式	anyhow::Result<T>	提供靈活的錯誤傳播
函式庫	thiserror	定義明確的錯誤類型
API 錯誤	自定義 Error enum	提供客戶端錯誤碼

3.2 錯誤處理範例

use anyhow::{Context, Result, bail};

fn process_video(video_path: &str) -> Result<VideoMetadata> {
    // 使用 context 提供錯誤上下文
    let output = Command::new("ffprobe")
        .args(["-v", "quiet", "-print_format", "json", "-show_format", video_path])
        .output()
        .context("Failed to run ffprobe")?;

    // 使用 bail 進行早期返回
    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        bail!("ffprobe failed: {}", stderr);
    }

    // 解析輸出
    let metadata: Metadata = serde_json::from_slice(&output.stdout)
        .context("Failed to parse ffprobe output")?;

    Ok(metadata)
}

3.3 自定義錯誤 (適用於函式庫)

use thiserror::Error;

#[derive(Error, Debug)]
pub enum VideoError {
    #[error("Video not found: {0}")]
    NotFound(String),
    
    #[error("Invalid codec: {0}")]
    InvalidCodec(String),
    
    #[error("Processing failed: {0}")]
    ProcessingError(#[from] std::io::Error),
}

4. 异步編程

4.1 Tokio 配置

// Cargo.toml
tokio = { version = "1", features = ["full"] }

4.2 Async Trait

use async_trait::async_trait;

#[async_trait]
pub trait Database: Send + Sync {
    async fn init() -> Result<Self>
    where Self: Sized;

    async fn get_video(&self, uuid: &str) -> Result<Option<VideoRecord>>;

    async fn store_chunk(&self, chunk: &Chunk) -> Result<()>;
}

4.3 避免常見陷阱

// ❌ 錯誤: 在同步上下文中調用 async 函式
fn bad_example() {
    let result = db.get_video("xxx"); // 編譯錯誤
}

// ✅ 正確: 使用 #[tokio::main]
#[tokio::main]
async fn main() {
    let result = db.get_video("xxx").await;
}

// ❌ 錯誤: 阻塞執行緒池
async fn bad_practice() {
    let data = std::fs::read_to_string("file.txt").unwrap(); // 阻塞
}

// ✅ 正確: 使用 tokio::fs
async fn good_practice() {
    let data = tokio::fs::read_to_string("file.txt").await.unwrap();
}

5. 外部程序整合

5.1 Python 腳本呼叫

當需要使用 Python 生態系工具 (如 faster-whisper, YOLO) 時：

pub async fn process_asr(video_path: &str, output_path: &str) -> Result<AsrResult> {
    let script_path = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("scripts")
        .join("asr_processor.py");

    // 使用 venv 中的 Python，確保版本隔離
    let venv_python = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("venv")
        .join("bin")
        .join("python");

    // 執行腳本
    let output = Command::new(venv_python)
        .arg(script_path)
        .arg(video_path)
        .arg(output_path)
        .output()
        .context("Failed to run ASR processor")?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        bail!("ASR failed: {}", stderr);
    }

    // 讀取輸出
    let json_str = std::fs::read_to_string(output_path)
        .context("Failed to read ASR output")?;

    let result: AsrResult = serde_json::from_str(&json_str)
        .context("Failed to parse ASR output")?;

    Ok(result)
}

5.2 進度回報

透過 stderr 回報進度，供 Rust 端解析：

# Python 腳本
import sys

print(f"ASR_START", file=sys.stderr)
print(f"ASR_LANGUAGE:{detected_lang}", file=sys.stderr)
print(f"ASR_PROGRESS:{count}", file=sys.stderr)
print(f"ASR_COMPLETE:{total}", file=sys.stderr)

// Rust 端解析
let stderr = String::from_utf8_lossy(&output.stderr);
for line in stderr.lines() {
    if line.starts_with("ASR_PROGRESS:") {
        let count = line.trim_start_matches("ASR_PROGRESS:");
        println!("[ASR] Processed {} segments...", count);
    }
}

6. 測試策略

6.1 單元測試

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_chunk_creation() {
        let chunk = Chunk::new(
            "test-uuid".to_string(),
            0,
            ChunkType::Sentence,
            0.0,
            10.0,
            serde_json::json!({"text": "Hello"}),
        );
        
        assert_eq!(chunk.uuid, "test-uuid");
        assert_eq!(chunk.chunk_type, ChunkType::Sentence);
    }
}

6.2 整合測試

#[cfg(test)]
mod integration {
    use super::*;
    
    #[tokio::test]
    async fn test_database_connection() {
        let db = PostgresDb::init().await.unwrap();
        let videos = db.list_videos().await.unwrap();
        assert!(videos.len() >= 0);
    }
}

6.3 測試資料

• 使用測試資料庫隔離測試環境
• 避免在測試中使用真實敏感資料
• 使用 mock 物件模擬外部依賴

#[cfg(test)]
mod mocks {
    pub struct MockVideoProcessor {
        pub result: AsrResult,
    }
    
    impl VideoProcessor for MockVideoProcessor {
        async fn process(&self, _video_path: &str) -> Result<AsrResult> {
            Ok(self.result.clone())
        }
    }
}

7. 日誌與監控

7.1 日誌規範

• 使用 tracing: 不要使用 println!
• 結構化日誌: 使用訊息 + 欄位

use tracing::{info, warn, error};

fn process_video(uuid: &str) -> Result<()> {
    info!(uuid = uuid, "Starting video processing");
    
    match do_processing(uuid) {
        Ok(_) => info!(uuid = uuid, "Processing completed"),
        Err(e) => {
            error!(uuid = uuid, error = %e, "Processing failed");
            return Err(e);
        }
    }
}

7.2 初始化日誌

use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

fn init_logging() {
    tracing_subscriber::registry()
        .with(
            tracing_subscriber::EnvFilter::try_from_default_env()
                .unwrap_or_else(|_| "momentry_core=info,tokio=warn".into()),
        )
        .with(tracing_subscriber::fmt::layer())
        .init();
}

8. 性能優化

8.1 避免拷貝

// ❌ 拷貝
let data = record.clone();

// ✅ 引用
fn process(data: &Data) { }

// ✅ 或使用 Arc 共用
use std::sync::Arc;
let shared = Arc::new(data);

8.2 批量操作

// ❌ 逐筆插入
for item in items {
    db.insert(&item).await?;
}

// ✅ 批量插入
db.insert_batch(&items).await?;

8.3 連線池

// 使用 sqlx 連線池
let pool = SqlxPool::connect(&DATABASE_URL).await?;
let db = PostgresDb::new(pool);

9. 安全考量

9.1 敏感資訊

• 不要將密碼、API Key 寫入程式碼
• 使用環境變數或設定檔
• .env 檔案加入 .gitignore

// ❌ 硬編碼密碼
let password = "secret123";

// ✅ 使用環境變數
let password = std::env::var("DATABASE_PASSWORD")
    .context("DATABASE_PASSWORD must be set")?;

9.2 命令注入

// ❌ 危險: 直接使用使用者輸入
let cmd = format!("ffprobe {}", user_input);

// ✅ 安全: 使用參數化
Command::new("ffprobe")
    .arg(user_input) // 自動轉義
    .output();

10. 文件編寫

10.1 結構體/函式文件

/// 代表一個影片記錄
///
/// # Fields
/// * `id` - 資料庫 ID
/// * `uuid` - 唯一識別碼
/// * `duration` - 影片時長 (秒)
///
/// # Example
/// ```
/// let video = VideoRecord {
///     id: 1,
///     uuid: "abc123".to_string(),
///     duration: 120.5,
/// };
/// ```
pub struct VideoRecord {
    pub id: i64,
    pub uuid: String,
    pub duration: f64,
}

10.2 API 文件

/// 取得影片記錄
///
/// # Arguments
/// * `uuid` - 影片的 UUID
///
/// # Returns
/// * `Ok(Some(VideoRecord))` - 找到影片
/// * `Ok(None)` - 影片不存在
/// * `Err` - 資料庫錯誤
///
/// # Errors
/// 如果資料庫連線失敗，返回資料庫錯誤
pub async fn get_video(&self, uuid: &str) -> Result<Option<VideoRecord>>;

11. CLI 命令設計

11.1 命令結構

使用 clap derive：

use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(name = "momentry")]
#[command(about = "Digital asset management system")]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    /// Register a video file
    Register {
        /// Path to video file
        path: String,
    },
    /// Process video
    Process {
        /// UUID or path
        target: String,
    },
    /// Generate chunks
    Chunk {
        /// Video UUID
        uuid: String,
    },
}

11.2 錯誤處理

match &cli.command {
    Commands::Register { path } => {
        if !Path::new(path).exists() {
            eprintln!("Error: File not found: {}", path);
            std::process::exit(1);
        }
        // ...
    }
}

12. 依賴管理

12.1 版本約束

# Cargo.toml
[dependencies]
anyhow = "1.0"           # 精確版本
tokio = { version = "1", features = ["full"] }  # 範圍版本
serde = "1.0"           # 精確版本

12.2 避免依賴地獄

• 審查依賴數量
• 優先使用標準庫
• 選擇維護良好的套件

13. 建構與部署

13.1 建構命令

# 開發建構
cargo build

# 發布建構
cargo build --release

# 單一二進制
cargo build --bin momentry

13.2 檢查清單

# 格式化
cargo fmt -- --check

# Lint
cargo clippy --all-features -- -D warnings

# 類型檢查
cargo check --all-features

# 測試
cargo test

14. 版本控制

14.1 提交訊息規範

<type>(<scope>): <subject>

<body>

<footer>

類型:

• feat: 新功能
• fix: 錯誤修復
• docs: 文件變更
• style: 格式調整
• refactor: 重構
• test: 測試變更
• chore: 建構/工具變更

範例:

feat(processor): Add ASR progress reporting

- Add stderr parsing for progress updates
- Support ASR_START, ASR_PROGRESS, ASR_COMPLETE markers

Closes #123

14.2 分支策略

• main: 穩定版本
• feature/*: 新功能開發
• fix/*: 錯誤修復
• refactor/*: 重構

---

附錄: 快速參考

建構

cargo build --release
cargo run -- --help

品質檢查

cargo fmt -- --check
cargo clippy --all-features
cargo check --all-features
cargo test

依賴

cargo add <package>
cargo tree
cargo outdated