feat(ocr): 消费端屏卡——笔记屏段落+大纲/检索按屏+配图attach

Author: Aparencia

app/src-tauri/src/commands_session.rs

@@ -83,7 +83,7 @@ pub async fn get_session_detail(state: State<'_, AppState>, id: i64) -> Result<S
     // 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);
+    let screens = crate::screens::build_screens(&ocr_blocks, Some(&images_dir));
     Ok(SessionDetail { session, segments, ocr_blocks, events, screens })
 }
 
@@ -183,10 +183,13 @@ fn load_note_material(
 ///              ai_decisions（REQ-085）可选叠加——前端把预览中已确认的 AI
 ///              判定结果回传，落库与预览输出保持一致（默认 None=纯规则）。
 /// @ai-context: 只允许 finished/failed 会话转换；source 沿用 classroom；
-///              v0.7.1 起落库携带 session_id（列表 has_note/查看笔记跳转的数据源）。
+///              v0.7.1 起落库携带 session_id（列表 has_note/查看笔记跳转的数据源）；
+///              v0.7.3（REQ-160）：data_dir 供画面要点屏 attach 归档图
+///              （配图行随 image_ref 进入笔记 markdown）。
 fn convert_to_note(
     db: &Db,
     ui_junk: &UiJunkList,
+    data_dir: &std::path::Path,
     id: i64,
     title: Option<String>,
     ai_decisions: Option<Vec<TextFilterDecision>>,
@@ -198,6 +201,10 @@ fn convert_to_note(
     if let Some(decisions) = ai_decisions {
         result = apply_ai_decisions(result, &decisions);
     }
+    // v0.7.3（REQ-160）：画面要点配图（归档 full 图匹配；目录缺失/无图 → 纯文本降级）
+    let images_dir = data_dir.join("session-images").join(id.to_string());
+    crate::screens::attach_images(&mut result.ocr_screens, &images_dir);
+    crate::note_filter::refresh_screen_points(&mut result);
     let new = NewNote {
         title: result.title.clone(),
         content: result.markdown.clone(),
@@ -215,7 +222,7 @@ pub async fn session_to_note(
     title: Option<String>,
     ai_decisions: Option<Vec<TextFilterDecision>>,
 ) -> Result<Note, String> {
-    convert_to_note(&state.db, &state.ui_junk, id, title, ai_decisions)
+    convert_to_note(&state.db, &state.ui_junk, &state.data_dir, id, title, ai_decisions)
 }
 
 /// 批量转笔记核心编排（v0.7.1：部分成功语义——单条失败不阻塞其他）。
@@ -226,6 +233,7 @@ pub async fn session_to_note(
 pub fn run_batch_conversion(
     db: &Db,
     ui_junk: &UiJunkList,
+    data_dir: &std::path::Path,
     ids: Vec<i64>,
 ) -> Result<BatchNoteResult, String> {
     if ids.len() > 50 {
@@ -258,7 +266,7 @@ pub fn run_batch_conversion(
                     });
                     continue;
                 }
-                match convert_to_note(db, ui_junk, id, None, None) {
+                match convert_to_note(db, ui_junk, data_dir, id, None, None) {
                     Ok(note) => converted.push(ConvertedNote { session_id: id, note_id: note.id }),
                     Err(reason) => skipped.push(SkippedNote { session_id: id, reason }),
                 }
@@ -280,21 +288,27 @@ pub async fn batch_session_to_note(
     state: State<'_, AppState>,
     ids: Vec<i64>,
 ) -> Result<BatchNoteResult, String> {
-    run_batch_conversion(&state.db, &state.ui_junk, ids)
+    run_batch_conversion(&state.db, &state.ui_junk, &state.data_dir, ids)
 }
 
 /// 会话笔记预览（REQ-081）：过滤后只读预览——不落库、不改库。
 ///
 /// @ai-context: 与 session_to_note 同一过滤管线（输出一致性由构造保证）；
 ///              返回 NoteFilterResult（markdown + 过滤统计 + 被过滤对照 +
 ///              kept 段），前端展示过滤统计卡/对照复查/一键落库。
+/// @ai-context: v0.7.3（REQ-160）：ocr_screens attach 归档图（预览屏卡配图；
+///              目录缺失/无图 → 纯文本降级）。
 #[tauri::command]
 pub async fn preview_session_note(
     state: State<'_, AppState>,
     id: i64,
 ) -> Result<NoteFilterResult, String> {
     let (session, segments, ocr_blocks) = load_note_material(&state.db, id)?;
-    Ok(filter_note(&session.title, &segments, &ocr_blocks, &state.ui_junk))
+    let mut result = filter_note(&session.title, &segments, &ocr_blocks, &state.ui_junk);
+    let images_dir = state.data_dir.join("session-images").join(id.to_string());
+    crate::screens::attach_images(&mut result.ocr_screens, &images_dir);
+    crate::note_filter::refresh_screen_points(&mut result);
+    Ok(result)
 }
 
 /// 归一化转写段来源标识（asr | subtitle | fused，其余回退 asr）。
@@ -326,6 +340,7 @@ pub async fn session_quality_report(
 }
 
 /// 会话大纲（REQ-077）：OCR 全帧块 → 大纲条目（产物视图侧边导航，点击跳转）。
+/// @ai-context: v0.7.3（REQ-160）：屏标题优先（版面角色分类），无屏回退文本启发式。
 #[tauri::command]
 pub async fn session_outline(
     state: State<'_, AppState>,
@@ -335,7 +350,12 @@ pub async fn session_outline(
         return Err("无效的会话 id".to_string());
     }
     let ocr_blocks = state.db.list_ocr_blocks(id).map_err(|e| e.to_string())?;
-    Ok(crate::outline::detect_outline(&ocr_blocks, &crate::outline::OutlineConfig::default()))
+    let screens = crate::screens::build_screens(&ocr_blocks, None);
+    Ok(crate::outline::detect_outline_smart(
+        &ocr_blocks,
+        &screens,
+        &crate::outline::OutlineConfig::default(),
+    ))
 }
 
 /// 课程分组（REQ-078）：课程键 = 标题章节前缀（"第3章"等）；无前缀 → 标题本身。

app/src-tauri/src/commands_session_batch_tests.rs

@@ -57,7 +57,7 @@ fn batch_converts_all_eligible_sessions() {
     let a = finished_session(&db, "A课");
     let b = finished_session(&db, "B课");
     // Act
-    let result = run_batch_conversion(&db, &UiJunkList::defaults(), vec![a, b]).expect("batch");
+    let result = run_batch_conversion(&db, &UiJunkList::defaults(), std::path::Path::new("."), vec![a, b]).expect("batch");
     // Assert：全部转换成功；关联已建立（find_note_by_session 可见）
     assert_eq!(result.converted.len(), 2);
     assert!(result.skipped.is_empty());
@@ -74,7 +74,7 @@ fn batch_skips_recording_and_duplicate_and_invalid() {
     let ok = finished_session(&db, "正常课");
     // Act
     let result =
-        run_batch_conversion(&db, &UiJunkList::defaults(), vec![live, ok, ok, 0, -3]).expect("batch");
+        run_batch_conversion(&db, &UiJunkList::defaults(), std::path::Path::new("."), vec![live, ok, ok, 0, -3]).expect("batch");
     // Assert：只转换 1 条；跳过 3 条（重复 id 静默去重，不计入跳过）
     assert_eq!(result.converted.len(), 1);
     assert_eq!(result.converted[0].session_id, ok);
@@ -99,7 +99,7 @@ fn batch_skips_already_converted_session() {
     })
     .expect("create note");
     // Act
-    let result = run_batch_conversion(&db, &UiJunkList::defaults(), vec![id]).expect("batch");
+    let result = run_batch_conversion(&db, &UiJunkList::defaults(), std::path::Path::new("."), vec![id]).expect("batch");
     // Assert：不重复生成，原因显式
     assert!(result.converted.is_empty());
     assert_eq!(result.skipped.len(), 1);
@@ -111,7 +111,7 @@ fn batch_skips_missing_session() {
     // Arrange
     let db = mem_db();
     // Act：不存在的会话 id
-    let result = run_batch_conversion(&db, &UiJunkList::defaults(), vec![9999]).expect("batch");
+    let result = run_batch_conversion(&db, &UiJunkList::defaults(), std::path::Path::new("."), vec![9999]).expect("batch");
     // Assert
     assert!(result.converted.is_empty());
     assert_eq!(result.skipped.len(), 1);
@@ -124,7 +124,7 @@ fn batch_rejects_over_limit() {
     let db = mem_db();
     let ids: Vec<i64> = (1..=51).collect();
     // Act
-    let result = run_batch_conversion(&db, &UiJunkList::defaults(), ids);
+    let result = run_batch_conversion(&db, &UiJunkList::defaults(), std::path::Path::new("."), ids);
     // Assert
     assert!(result.is_err());
     assert!(result.unwrap_err().contains("上限 50"));
@@ -138,7 +138,7 @@ fn batch_partial_failure_does_not_block_others() {
     let ok = finished_session(&db, "正常课");
     // Act
     let result =
-        run_batch_conversion(&db, &UiJunkList::defaults(), vec![live, ok]).expect("batch");
+        run_batch_conversion(&db, &UiJunkList::defaults(), std::path::Path::new("."), vec![live, ok]).expect("batch");
     // Assert：后续会话仍成功转换
     assert_eq!(result.converted.len(), 1);
     assert_eq!(result.converted[0].session_id, ok);

app/src-tauri/src/db_ocr_search.rs

@@ -25,12 +25,22 @@ pub struct OcrBlockHit {
     pub region: String,
     /// 命中图相对路径（full/xxx.webp；无图 None——纯 OCR 块无归档）
     pub image_path: Option<String>,
+    /// v0.7.3（REQ-160）：命中块所属屏（None=旧数据无屏）
+    #[serde(default)]
+    pub screen_id: Option<i64>,
+    /// 屏时间区间（first/last_seen；屏定位基准）
+    #[serde(default)]
+    pub screen_first_ms: Option<u64>,
+    #[serde(default)]
+    pub screen_last_ms: Option<u64>,
 }
 
-/// 检索会话 OCR 块（REQ-133）：关键词 → 命中块 + 会话标题 + 图路径。
+/// 检索会话 OCR 块（REQ-133）：关键词 → 命中块 + 会话标题 + 图路径 + 屏区间。
 ///
 /// @ai-context: 只搜画面要点（region=full——字幕区是转写冗余，搜字幕用段搜索）；
 ///              大小写不敏感；结果有界（100 条防超大 payload）。
+/// @ai-context: v0.7.3（REQ-160）：命中块带屏信息（同屏块 min/max 时间戳——
+///              前端"命中→跳屏"定位；旧数据无 screen_id → None 降级）。
 pub fn search_ocr_blocks(db: &Db, keyword: &str, limit: usize) -> Result<Vec<OcrBlockHit>> {
     let kw = keyword.trim().to_lowercase();
     if kw.is_empty() {
@@ -40,21 +50,40 @@ pub fn search_ocr_blocks(db: &Db, keyword: &str, limit: usize) -> Result<Vec<Ocr
     let mut hits = Vec::new();
     for item in db.list_sessions(None, 500, 0)? {
         let session = &item.session;
-        for block in db.list_ocr_blocks(session.id)? {
+        let blocks = db.list_ocr_blocks(session.id)?;
+        // 屏区间映射（命中定位到屏：min/max 时间戳）
+        let mut screen_ranges: std::collections::HashMap<i64, (u64, u64)> =
+            std::collections::HashMap::new();
+        for b in &blocks {
+            if let Some(sid) = b.screen_id {
+                let e = screen_ranges.entry(sid).or_insert((b.timestamp_ms, b.timestamp_ms));
+                e.0 = e.0.min(b.timestamp_ms);
+                e.1 = e.1.max(b.timestamp_ms);
+            }
+        }
+        for block in &blocks {
             if block.region != "full" {
                 continue; // 字幕区不参与图内检索（与段搜索分工）
             }
             if block.text.to_lowercase().contains(&kw) {
+                let (sf, sl) = block
+                    .screen_id
+                    .and_then(|sid| screen_ranges.get(&sid).copied())
+                    .map(|(a, b)| (Some(a), Some(b)))
+                    .unwrap_or((None, None));
                 hits.push(OcrBlockHit {
                     session_id: session.id,
                     session_title: session.title.clone(),
                     ocr_block_id: block.id,
                     timestamp_ms: block.timestamp_ms,
-                    text: block.text,
-                    region: block.region,
+                    text: block.text.clone(),
+                    region: block.region.clone(),
                     // 图路径推断：full/<ts>.webp（与 image_store 命名约定一致；
                     // 文件不存在 → None——OCR 块可能无归档图）
                     image_path: image_path_for(db, session.id, block.timestamp_ms),
+                    screen_id: block.screen_id,
+                    screen_first_ms: sf,
+                    screen_last_ms: sl,
                 });
                 if hits.len() >= limit {
                     return Ok(hits);

app/src-tauri/src/note_filter.rs

@@ -16,21 +16,16 @@
 //!              的短文本不是"纯符号"碎片）；confidence=None（字幕段）跳过
 //!              低置信规则。
 
-use std::collections::HashSet;
-
 use crate::ai_protocol::{TextFilterAction, TextFilterDecision};
-use crate::types::{SessionOcrBlock, SessionSegment, TranscriptSegment};
+use crate::types::{SessionOcrBlock, SessionScreen, SessionSegment, TranscriptSegment};
 use crate::ui_junk::UiJunkList;
-use crate::watermark_filter::{detect_watermarks, WatermarkConfig, WatermarkInput};
 
 /// 碎片段最大字符数（≤2 字丢弃）。
 pub const FRAGMENT_MAX_CHARS: usize = 2;
 /// 碎片段最小时长（<500ms 丢弃）。
 pub const FRAGMENT_MIN_DURATION_MS: u64 = 500;
 /// 低置信丢弃阈值（confidence <0.6 丢弃）。
 pub const LOW_CONFIDENCE_THRESHOLD: f32 = 0.6;
-/// OCR 画面要点最低分数（沿用 concat 口径）。
-const OCR_MIN_SCORE: f32 = 0.5;
 
 /// 被过滤原因。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
@@ -84,8 +79,12 @@ pub struct NoteFilterResult {
     pub markdown: String,
     /// 保留段（合并段已延伸 end_ms；AI merge 已拼接文本——仅产物层）
     pub kept: Vec<SessionSegment>,
-    /// 画面要点（水印/UI 垃圾/低分已排除）
+    /// 画面要点（屏段落行：区间+标题+正文+标签+配图；水印/UI 垃圾/低分已排除）
     pub ocr_points: Vec<String>,
+    /// v0.7.3（REQ-160）：画面要点屏（结构化——前端预览渲染屏卡；
+    /// 命令层 attach 图后 image_ref 填充，markdown 配图行随之可渲染）
+    #[serde(default)]
+    pub ocr_screens: Vec<SessionScreen>,
     pub stats: FilterStats,
     pub filtered: Vec<FilteredItem>,
     pub merged: Vec<MergedItem>,
@@ -171,10 +170,13 @@ pub fn filter_note(
         }
         kept.push(seg);
     }
-    // ② 画面要点（水印 + UI 垃圾 + 低分 + 去重）
-    let ocr_points = build_ocr_points(ocr_blocks, ui_junk);
+    // ② 画面要点（v0.7.3 REQ-160：可消费块过滤 → 屏构建 → 屏段落渲染；
+    //    水印 + UI 垃圾 + 低分在 filter_usable_blocks 排除——与原料口径解耦）
+    let usable = crate::screens::filter_usable_blocks(ocr_blocks, ui_junk);
+    let ocr_screens = crate::screens::build_screens(&usable, None);
+    let ocr_points = render_screen_points(&ocr_screens);
     let markdown = rebuild_markdown(title, &kept, &ocr_points);
-    NoteFilterResult { title: title.to_string(), markdown, kept, ocr_points, stats, filtered, merged }
+    NoteFilterResult { title: title.to_string(), markdown, kept, ocr_points, ocr_screens, stats, filtered, merged }
 }
 
 /// 碎片段判定（纯函数）：≤2 字 / 时长 <500ms / 纯符号。
@@ -188,39 +190,57 @@ fn is_fragment(seg: &SessionSegment) -> bool {
         || text.chars().all(|c| !c.is_alphanumeric() && !is_cjk(c))
 }
 
-/// 画面要点构建（纯函数）：水印排除 + UI 垃圾 + 低分过滤 + 精确去重。
-fn build_ocr_points(ocr_blocks: &[SessionOcrBlock], ui_junk: &UiJunkList) -> Vec<String> {
-    // 水印检测（REQ-059）：全帧块（字幕区文本已在讲述内容中，不重复进要点）
-    let inputs: Vec<WatermarkInput> = ocr_blocks
-        .iter()
-        .filter(|b| b.region == "full")
-        .map(|b| WatermarkInput {
-            text: b.text.clone(),
-            timestamp_ms: b.timestamp_ms,
-            region_key: None,
-        })
-        .collect();
-    let watermarks = detect_watermarks(&inputs, &WatermarkConfig::default());
-    let mut sorted: Vec<&SessionOcrBlock> = ocr_blocks
+/// 画面要点屏段落渲染（纯函数）：屏卡 → 笔记画面要点行（Markdown 列表项）。
+///
+/// @ai-context: 每屏一段：`- **[MM:SS–MM:SS] 标题**` + 正文行（二级列表）+
+///              标签行 + 配图行（image_ref 有值时；src 为相对 data_dir 路径
+///              `session-images/{sid}/full/{ts}.webp`——前端渲染拼 baseUrl）。
+/// @ai-context: 无标题屏（旧数据无 bbox 降级）用"画面 N"占位——不丢内容。
+pub fn render_screen_points(screens: &[SessionScreen]) -> Vec<String> {
+    let mut lines = Vec::new();
+    for (i, s) in screens.iter().enumerate() {
+        let range = format!(
+            "[{}–{}]",
+            crate::concat::format_timestamp(s.first_seen_ms),
+            crate::concat::format_timestamp(s.last_seen_ms)
+        );
+        let title = s.title.clone().unwrap_or_else(|| format!("画面 {}", i + 1));
+        lines.push(format!("- **{} {}**", range, title));
+        for b in &s.body {
+            lines.push(format!("  - {}", b));
+        }
+        if !s.labels.is_empty() {
+            lines.push(format!("  - 标签：{}", s.labels.join(" · ")));
+        }
+        if let Some(rel) = &s.image_ref {
+            lines.push(format!("  - ![画面 {}](session-images/{}/{}", i + 1, s.session_id, rel));
+        }
+    }
+    lines
+}
+
+/// 刷新画面要点段落（纯函数）：ocr_screens 重新渲染 + 重建 markdown。
+///
+/// @ai-context: 命令层 attach_images 填充 image_ref 后调用——配图行随
+///              image_ref 出现/消失，保持 markdown 与 ocr_screens 一致
+///              （单管线双出口原则的图版本）。
+pub fn refresh_screen_points(result: &mut NoteFilterResult) {
+    result.ocr_points = render_screen_points(&result.ocr_screens);
+    let transcript: Vec<TranscriptSegment> = result
+        .kept
         .iter()
-        .filter(|b| {
-            b.region == "full"
-                && b.score >= OCR_MIN_SCORE
-                && !b.text.trim().is_empty()
-                && !ui_junk.is_junk(&b.text)
-                && !watermarks.texts.iter().any(|w| b.text.trim() == w)
+        .map(|s| TranscriptSegment {
+            start_ms: s.start_ms,
+            end_ms: s.end_ms,
+            text: s.text.clone(),
+            word_timestamps: None,
+            confidence: None,
+            volume: None,
         })
         .collect();
-    sorted.sort_by_key(|b| b.timestamp_ms);
-    let mut seen = HashSet::new();
-    let mut points = Vec::new();
-    for b in sorted {
-        let text = b.text.trim().to_string();
-        if seen.insert(text.clone()) {
-            points.push(format!("[{}] {}", crate::concat::format_timestamp(b.timestamp_ms), text));
-        }
-    }
-    points
+    let paragraphs = crate::concat::split_transcript_paragraphs(&transcript);
+    result.markdown =
+        crate::concat::assemble_markdown(&result.title, &paragraphs, &result.ocr_points);
 }
 
 /// 组装 Markdown（标题 + 讲述内容 + 画面要点；段落切分复用 concat 口径）。