feat(ocr): 屏卡体系——屏聚合纯函数+bbox落库+在线屏分配

Author: Aparencia

app/src-tauri/src/ai_judge_tests.rs

@@ -13,6 +13,8 @@ fn ocr_block(ts: u64, text: &str, score: f32, region_kind: Option<&str>) -> Sess
         score,
         region: "full".into(),
         region_kind: region_kind.map(String::from),
+        bbox: None,
+        screen_id: None,
     }
 }
 

app/src-tauri/src/analysis_tests.rs

@@ -42,9 +42,11 @@ fn detail(segments: Vec<(&str, u64, u64)>, ocr: Vec<(&str, u64)>) -> SessionDeta
             score: 0.9,
             region: "full".into(),
             region_kind: None,
+            bbox: None,
+            screen_id: None,
         })
         .collect();
-    SessionDetail { session, segments, ocr_blocks, events: Vec::new() }
+    SessionDetail { session, segments, ocr_blocks, events: Vec::new(), screens: Vec::new() }
 }
 
 /// 构造带事件的会话详情（REQ-108：真实信号消费测试）。
@@ -166,8 +168,8 @@ fn build_chapter_signals_detects_frame_switch_approximation() {
             speaker: None, confidence: None },
     ];
     let ocr = vec![
-        SessionOcrBlock { id: 0, session_id: 1, timestamp_ms: 100, text: "PPT-第一章".into(), score: 0.9, region: "full".into(), region_kind: None },
-        SessionOcrBlock { id: 1, session_id: 1, timestamp_ms: 40100, text: "PPT-第二章".into(), score: 0.9, region: "full".into(), region_kind: None },
+        SessionOcrBlock { id: 0, session_id: 1, timestamp_ms: 100, text: "PPT-第一章".into(), score: 0.9, region: "full".into(), region_kind: None, bbox: None, screen_id: None },
+        SessionOcrBlock { id: 1, session_id: 1, timestamp_ms: 40100, text: "PPT-第二章".into(), score: 0.9, region: "full".into(), region_kind: None, bbox: None, screen_id: None },
     ];
     // Act
     let signals = build_chapter_signals(&segments, &ocr);

app/src-tauri/src/artifact_templates_tests.rs

@@ -45,9 +45,11 @@ fn detail(segments: Vec<(&str, u64, u64)>, ocr: Vec<(&str, u64)>) -> SessionDeta
             score: 0.9,
             region: "full".into(),
             region_kind: None,
+            bbox: None,
+            screen_id: None,
         })
         .collect();
-    SessionDetail { session, segments, ocr_blocks, events: Vec::new() }
+    SessionDetail { session, segments, ocr_blocks, events: Vec::new(), screens: Vec::new() }
 }
 
 fn keyframes() -> Vec<KeyFrameCandidate> {

app/src-tauri/src/commands_analysis.rs

@@ -39,7 +39,7 @@ pub async fn analyze_session_command(
         .map(|p| ProfileKind::parse(&p))
         .or_else(|| session.profile.as_deref().map(ProfileKind::parse))
         .unwrap_or(ProfileKind::Lecture);
-    let detail = crate::types::SessionDetail { session, segments, ocr_blocks, events };
+    let detail = crate::types::SessionDetail { session, segments, ocr_blocks, events, screens: Vec::new() };
     // REQ-060：口语符号映射表（AppState 加载；JSON 校准生效）
     Ok(analyze_session_opt(&detail, kind, &state.symbol_normalize))
 }

app/src-tauri/src/commands_artifacts.rs

@@ -41,7 +41,7 @@ pub async fn build_session_artifact(
         .unwrap_or(ProfileKind::Lecture);
     // 关键图候选（M6 投票输出；当前从图片库取时间戳近似——产物不阻断）
     let keyframes = crate::commands_images::keyframes_from_store(&state, session_id).unwrap_or_default();
-    let detail = crate::types::SessionDetail { session, segments, ocr_blocks, events };
+    let detail = crate::types::SessionDetail { session, segments, ocr_blocks, events, screens: Vec::new() };
     let artifact = build_artifact(kind, &detail, &keyframes);
     state
         .db

app/src-tauri/src/commands_session.rs

@@ -65,7 +65,7 @@ pub async fn list_sessions(
         .map_err(|e| e.to_string())
 }
 
-/// 会话详情：会话 + 转写段 + OCR 块 + 信号事件（时间轴对齐，一次取全）。
+/// 会话详情：会话 + 转写段 + OCR 块 + 信号事件 + 画面要点屏（时间轴对齐，一次取全）。
 #[tauri::command]
 pub async fn get_session_detail(state: State<'_, AppState>, id: i64) -> Result<SessionDetail, String> {
     if id <= 0 {
@@ -80,7 +80,11 @@ pub async fn get_session_detail(state: State<'_, AppState>, id: i64) -> Result<S
     let ocr_blocks = state.db.list_ocr_blocks(id).map_err(|e| e.to_string())?;
     // REQ-108（v0.7.0 M1.5）：信号事件随详情取全（章节检测真实信号消费）
     let events = state.db.list_events(id).map_err(|e| e.to_string())?;
-    Ok(SessionDetail { session, segments, ocr_blocks, events })
+    // v0.7.3（REQ-160，ADR-015）：画面要点屏卡（新数据按 screen_id 分组、
+    // 旧数据聚类兜底；图匹配失败/目录缺失不阻断——前端无缩略图降级）
+    let images_dir = state.data_dir.join("session-images").join(id.to_string());
+    let screens = crate::screens::build_screens(id, &ocr_blocks, &images_dir);
+    Ok(SessionDetail { session, segments, ocr_blocks, events, screens })
 }
 
 /// 删除会话（级联清理转写段与 OCR 块）。
@@ -143,6 +147,9 @@ pub async fn add_session_ocr_block(
         region: if region == "subtitle" { "subtitle" } else { "full" }.to_string(),
         // 外部追加无版面上下文，区域标注留空
         region_kind: None,
+        // v0.7.3：外部追加无位置/屏上下文（None=旧口径，聚类兜底）
+        bbox: None,
+        screen_id: None,
     };
     state.db.add_ocr_block(&new).map(|b| b.id).map_err(|e| e.to_string())
 }

app/src-tauri/src/db.rs

@@ -105,6 +105,21 @@ impl Db {
             "region_kind",
             "ALTER TABLE session_ocr_blocks ADD COLUMN region_kind TEXT",
         )?;
+        // v0.7.3（REQ-156，ADR-015）：旧库迁移——ocr_blocks 表补屏卡体系两列：
+        // bbox=检测框 JSON {x,y,w,h}（帧坐标系）、screen_id=采集时分配的屏号
+        // （NULL=旧数据无屏，视图层聚类兜底——ADR-015 决策 1/2）
+        ensure_column(
+            &conn,
+            "session_ocr_blocks",
+            "bbox",
+            "ALTER TABLE session_ocr_blocks ADD COLUMN bbox TEXT",
+        )?;
+        ensure_column(
+            &conn,
+            "session_ocr_blocks",
+            "screen_id",
+            "ALTER TABLE session_ocr_blocks ADD COLUMN screen_id INTEGER",
+        )?;
         // v0.7.0 M1（REQ-103）：旧库迁移——segments 表补 volume 列
         // （段内平均音量，重点标注音量骤变信号输入；旧数据 None=未知）
         ensure_column(

app/src-tauri/src/db_ocr_search.rs

@@ -94,10 +94,12 @@ mod tests {
         db.add_ocr_block(&NewSessionOcrBlock {
             session_id: s.id, timestamp_ms: 1000, text: "梯度下降算法详解".into(),
             score: 0.9, region: "full".into(), region_kind: None,
+            bbox: None, screen_id: None,
         }).unwrap();
         db.add_ocr_block(&NewSessionOcrBlock {
             session_id: s.id, timestamp_ms: 2000, text: "梯度下降（字幕）".into(),
             score: 0.9, region: "subtitle".into(), region_kind: None,
+            bbox: None, screen_id: None,
         }).unwrap();
         // Act
         let hits = search_ocr_blocks(&db, "梯度", 10).unwrap();
@@ -124,6 +126,7 @@ mod tests {
         db.add_ocr_block(&NewSessionOcrBlock {
             session_id: s.id, timestamp_ms: 500, text: "Python 教程".into(),
             score: 0.9, region: "full".into(), region_kind: None,
+            bbox: None, screen_id: None,
         }).unwrap();
         // Act & Assert
         assert_eq!(search_ocr_blocks(&db, "python", 10).unwrap().len(), 1);
@@ -141,6 +144,7 @@ mod tests {
             db.add_ocr_block(&NewSessionOcrBlock {
                 session_id: s.id, timestamp_ms: i * 100, text: format!("关键词{}", i),
                 score: 0.9, region: "full".into(), region_kind: None,
+            bbox: None, screen_id: None,
             }).unwrap();
         }
         // Act & Assert：limit=3

app/src-tauri/src/db_sessions.rs

@@ -185,13 +185,17 @@ impl Db {
         .map_err(Into::into)
     }
 
-    /// 追加一条 OCR 块（实时落库）。
+    /// 追加一条 OCR 块（实时落库；v0.7.3 起双写 bbox/screen_id——REQ-156）。
     pub fn add_ocr_block(&self, new: &NewSessionOcrBlock) -> Result<SessionOcrBlock> {
         let conn = self.conn.lock().expect("db lock poisoned");
+        // bbox 序列化为 JSON {x,y,w,h}（帧坐标系；None → NULL=旧口径）
+        let bbox_json = new.bbox.map(|b| {
+            serde_json::json!({ "x": b.x, "y": b.y, "w": b.w, "h": b.h }).to_string()
+        });
         conn.execute(
-            "INSERT INTO session_ocr_blocks (session_id, timestamp_ms, text, score, region, region_kind)
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-            params![new.session_id, new.timestamp_ms, new.text, new.score, new.region, new.region_kind],
+            "INSERT INTO session_ocr_blocks (session_id, timestamp_ms, text, score, region, region_kind, bbox, screen_id)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+            params![new.session_id, new.timestamp_ms, new.text, new.score, new.region, new.region_kind, bbox_json, new.screen_id],
         )?;
         Ok(SessionOcrBlock {
             id: conn.last_insert_rowid(),
@@ -201,6 +205,8 @@ impl Db {
             score: new.score,
             region: new.region.clone(),
             region_kind: new.region_kind.clone(),
+            bbox: new.bbox,
+            screen_id: new.screen_id,
         })
     }
 
@@ -275,11 +281,11 @@ impl Db {
         Ok(affected > 0)
     }
 
-    /// 列出会话全部 OCR 块（按时间轴升序）。
+    /// 列出会话全部 OCR 块（按时间轴升序；v0.7.3 起含 bbox/screen_id 列）。
     pub fn list_ocr_blocks(&self, session_id: i64) -> Result<Vec<SessionOcrBlock>> {
         let conn = self.conn.lock().expect("db lock poisoned");
         let mut stmt = conn.prepare(
-            "SELECT id, session_id, timestamp_ms, text, score, region, region_kind
+            "SELECT id, session_id, timestamp_ms, text, score, region, region_kind, bbox, screen_id
              FROM session_ocr_blocks WHERE session_id = ?1 ORDER BY timestamp_ms ASC",
         )?;
         let rows = stmt.query_map(params![session_id], row_to_ocr_block)?;

app/src-tauri/src/db_sessions_rows.rs

@@ -66,8 +66,16 @@ pub fn row_to_segment(row: &Row<'_>) -> rusqlite::Result<SessionSegment> {
     })
 }
 
-/// 把 rusqlite 行映射为 SessionOcrBlock。
+/// 把 rusqlite 行映射为 SessionOcrBlock（9 列：原 7 列 + bbox JSON + screen_id）。
+///
+/// @ai-context: v0.7.3（REQ-156）：bbox 为 JSON {x,y,w,h}（帧坐标系，null=旧数据）；
+///              screen_id 为屏号（null=旧数据无屏——视图层聚类兜底）。
 pub fn row_to_ocr_block(row: &Row<'_>) -> rusqlite::Result<SessionOcrBlock> {
+    let bbox_json: Option<String> = row.get(7)?;
+    let bbox = match bbox_json.as_deref() {
+        Some(json) => serde_json::from_str(json).unwrap_or(None), // 解析失败诚实降级 None
+        None => None,
+    };
     Ok(SessionOcrBlock {
         id: row.get(0)?,
         session_id: row.get(1)?,
@@ -76,6 +84,8 @@ pub fn row_to_ocr_block(row: &Row<'_>) -> rusqlite::Result<SessionOcrBlock> {
         score: row.get(4)?,
         region: row.get(5)?,
         region_kind: row.get(6)?,
+        bbox,
+        screen_id: row.get(8)?,
     })
 }