feat: 新增 Job Worker 系統與 API 文檔全面更新

src/core/chunk/splitter.rs

@@ -20,7 +20,7 @@ impl ChunkSplitter {
 
         while current_time < duration {
             let end_time = (current_time + self.time_based_duration).min(duration);
-            chunks.push(Chunk::new(
+            chunks.push(Chunk::from_seconds(
                 0, // file_id
                 uuid.to_string(),
                 index,
@@ -45,7 +45,7 @@ impl ChunkSplitter {
         let mut chunks = Vec::new();
 
         for (index, segment) in asr_segments.iter().enumerate() {
-            chunks.push(Chunk::new(
+            chunks.push(Chunk::from_seconds(
                 0, // file_id
                 uuid.to_string(),
                 index as u32,

src/core/chunk/types.rs

@@ -1,3 +1,4 @@
+use crate::core::time::FrameTime;
 use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
@@ -46,10 +47,11 @@ pub struct Chunk {
     pub chunk_index: u32,
     pub chunk_type: ChunkType,
     pub rule: ChunkRule,
-    pub start_time: f64,
-    pub end_time: f64,
+    /// Frames per second (can be fractional, e.g., 29.97, 23.976)
     pub fps: f64,
+    /// Start frame (0-based)
     pub start_frame: i64,
+    /// End frame (exclusive)
     pub end_frame: i64,
     pub text_content: Option<String>,
     pub content: serde_json::Value,
@@ -62,6 +64,13 @@ pub struct Chunk {
 }
 
 impl Chunk {
+    /// Creates a new chunk from frame counts.
+    ///
+    /// # Arguments
+    ///
+    /// * `start_frame` - Start frame (0-based)
+    /// * `end_frame` - End frame (exclusive)
+    /// * `fps` - Frames per second (can be fractional)
     #[allow(clippy::too_many_arguments)]
     pub fn new(
         file_id: i32,
@@ -69,13 +78,11 @@ impl Chunk {
         chunk_index: u32,
         chunk_type: ChunkType,
         rule: ChunkRule,
-        start_time: f64,
-        end_time: f64,
+        start_frame: i64,
+        end_frame: i64,
         fps: f64,
         content: serde_json::Value,
     ) -> Self {
-        let start_frame = (start_time * fps) as i64;
-        let end_frame = (end_time * fps) as i64;
         let chunk_id = format!("{}_{:04}", chunk_type.as_str(), chunk_index);
         Self {
             file_id,
@@ -84,8 +91,6 @@ impl Chunk {
             chunk_index,
             chunk_type,
             rule,
-            start_time,
-            end_time,
             fps,
             start_frame,
             end_frame,
@@ -100,6 +105,95 @@ impl Chunk {
         }
     }
 
+    /// Creates a new chunk from seconds (legacy conversion).
+    ///
+    /// This is useful for migrating from older systems that store time as seconds.
+    /// The frame counts are calculated by rounding `seconds * fps`.
+    #[allow(clippy::too_many_arguments)]
+    pub fn from_seconds(
+        file_id: i32,
+        uuid: String,
+        chunk_index: u32,
+        chunk_type: ChunkType,
+        rule: ChunkRule,
+        start_time: f64,
+        end_time: f64,
+        fps: f64,
+        content: serde_json::Value,
+    ) -> Self {
+        let start_frame = (start_time * fps).round() as i64;
+        let end_frame = (end_time * fps).round() as i64;
+        Self::new(
+            file_id,
+            uuid,
+            chunk_index,
+            chunk_type,
+            rule,
+            start_frame,
+            end_frame,
+            fps,
+            content,
+        )
+    }
+
+    /// Returns the start time as a `FrameTime`.
+    pub fn start_time(&self) -> FrameTime {
+        FrameTime::from_frames(self.start_frame, self.fps)
+    }
+
+    /// Returns the end time as a `FrameTime`.
+    pub fn end_time(&self) -> FrameTime {
+        FrameTime::from_frames(self.end_frame, self.fps)
+    }
+
+    /// Returns the duration in frames.
+    pub fn duration_frames(&self) -> i64 {
+        self.end_frame - self.start_frame
+    }
+
+    /// Returns the duration in seconds.
+    pub fn duration_seconds(&self) -> f64 {
+        self.duration_frames() as f64 / self.fps
+    }
+
+    /// Formats the start time as "seconds.frame" (e.g., "123.04").
+    pub fn format_start_sec_frame(&self) -> String {
+        self.start_time().format_sec_frame()
+    }
+
+    /// Formats the end time as "seconds.frame" (e.g., "456.15").
+    pub fn format_end_sec_frame(&self) -> String {
+        self.end_time().format_sec_frame()
+    }
+
+    /// Formats the start time as "HH:MM:SS".
+    pub fn format_start_hms(&self) -> String {
+        self.start_time().format_hms()
+    }
+
+    /// Formats the end time as "HH:MM:SS".
+    pub fn format_end_hms(&self) -> String {
+        self.end_time().format_hms()
+    }
+
+    /// Formats the start time as "HH:MM:SS.FF".
+    pub fn format_start_hms_frame(&self) -> String {
+        self.start_time().format_hms_frame()
+    }
+
+    /// Formats the end time as "HH:MM:SS.FF".
+    pub fn format_end_hms_frame(&self) -> String {
+        self.end_time().format_hms_frame()
+    }
+
+    /// Returns a tuple of (start_seconds, end_seconds) for compatibility.
+    ///
+    /// This is provided for backward compatibility during migration.
+    /// Prefer using `start_time()` and `end_time()` methods.
+    pub fn time_range_seconds(&self) -> (f64, f64) {
+        (self.start_time().seconds(), self.end_time().seconds())
+    }
+
     pub fn with_metadata(mut self, metadata: serde_json::Value) -> Self {
         self.metadata = Some(metadata);
         self