feat(cards): FSRS 调度器与组到闪卡生成纯函数

Author: Aparencia

app/src-tauri/src/card_generate.rs

@@ -0,0 +1,100 @@
+//! 组→闪卡生成纯函数（v0.11.2；本地规则版先行，AI 生成为可选增强）。
+//!
+//! @ai-context: 两个直供源（v4 路线图 Step 4）：
+//!              ① 笔记词汇表块（structure_note.rs ## 词汇表 行）——术语卡；
+//!              ② 碎片文本（多句拆分——首句线索，全文验证，提取优先）。
+//! @ai-context: 提取优先纪律——front 是回忆线索不是答案展示；back 是验证材料；
+//!              单句碎片无回忆结构 → 诚实不出卡（防"假燃料"微观形态）。
+//! @ai-context: 纯函数无 IO；幂等去重在数据层（同组同 front 查重）。
+
+/// 生成的卡片候选（front/back；kind 恒 fact——内容分型预埋 N13）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CardCandidate {
+    pub front: String,
+    pub back: String,
+}
+
+/// 从笔记正文提取卡片候选（词汇表块术语 → front；术语上下文句 → back）。
+///
+/// @ai-context: 词汇表行格式（structure_note.rs 产出）：
+///              `- [03:21] 术语（画面 ×3 / 语音 ×2）` 或 `- 术语（...）`；
+///              back 取正文中含术语的首个非标题行（上下文即释义）；
+///              正文无命中 → 词汇表行自身兜底（有卡总比无卡强，但诚实简陋）。
+pub fn cards_from_note(content: &str) -> Vec<CardCandidate> {
+    let mut out = Vec::new();
+    let mut in_glossary = false;
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if trimmed.starts_with("## ") {
+            in_glossary = trimmed == "## 词汇表";
+            continue;
+        }
+        if !in_glossary || !trimmed.starts_with("- ") {
+            continue;
+        }
+        let Some(term) = parse_glossary_term(trimmed) else { continue };
+        if term.is_empty() {
+            continue;
+        }
+        let back = find_term_context(content, &term).unwrap_or_else(|| trimmed.to_string());
+        out.push(CardCandidate { front: term, back });
+    }
+    out
+}
+
+/// 解析词汇表行的术语（剥时间戳锚点与频次统计尾注）。
+fn parse_glossary_term(line: &str) -> Option<String> {
+    let body = line.strip_prefix("- ")?.trim();
+    // 剥时间戳锚点 "[03:21] "
+    let body = if body.starts_with('[') {
+        body.find(']').map(|i| body[i + 1..].trim()).unwrap_or(body)
+    } else {
+        body
+    };
+    // 截断频次尾注 "（画面 ×N / 语音 ×N）"（中文括号口径，structure_note 产出）
+    let term = match body.find('（') {
+        Some(i) => &body[..i],
+        None => body,
+    };
+    Some(term.trim().to_string())
+}
+
+/// 正文中术语的首个上下文行（跳过标题/词汇表块/空行）。
+fn find_term_context(content: &str, term: &str) -> Option<String> {
+    let mut in_glossary = false;
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if trimmed.starts_with("## ") {
+            in_glossary = trimmed == "## 词汇表";
+            continue;
+        }
+        if in_glossary || trimmed.is_empty() || trimmed.starts_with('#') {
+            continue;
+        }
+        if trimmed.contains(term) {
+            return Some(trimmed.to_string());
+        }
+    }
+    None
+}
+
+/// 从碎片文本提取卡片候选（多句才有回忆结构；单句 → None 诚实不出卡）。
+///
+/// @ai-context: front=首句（线索），back=全文（验证）——碎片卡质量上限受
+///              碎片本身约束（v4 契约一：碎片身份诚实，不冒充课程）。
+pub fn card_from_fragment(text: &str) -> Option<CardCandidate> {
+    let sentences: Vec<&str> = text
+        .split(|c| "。！？；\n".contains(c))
+        .map(|s| s.trim())
+        .filter(|s| !s.is_empty())
+        .collect();
+    if sentences.len() < 2 {
+        return None;
+    }
+    let front = sentences[0].chars().take(60).collect::<String>();
+    Some(CardCandidate { front, back: text.trim().to_string() })
+}
+
+#[cfg(test)]
+#[path = "card_generate_tests.rs"]
+mod tests;

app/src-tauri/src/card_generate_tests.rs

@@ -0,0 +1,78 @@
+//! card_generate 单测（AAA 模式；golden 用例覆盖两类卡源）。
+
+use crate::card_generate::{card_from_fragment, cards_from_note};
+
+/// 真实笔记形态（structure_note 产出口径：章节 + 正文 + 词汇表块）。
+const NOTE_WITH_GLOSSARY: &str = "# 微积分精讲\n\n## 第一章 极限 [00:00]\n\n\
+极限是微积分的基础概念，描述函数的趋近行为。\n\n\
+## 词汇表\n\n\
+- [01:23] 极限（画面 ×3 / 语音 ×5）\n\
+- [05:10] 导数（画面 ×2 / 语音 ×4）\n\
+- 孤立术语（画面 ×1 / 语音 ×1）\n";
+
+#[test]
+fn note_glossary_terms_become_cards() {
+    // Act
+    let cards = cards_from_note(NOTE_WITH_GLOSSARY);
+    // Assert：三术语各一卡，front=术语
+    assert_eq!(cards.len(), 3);
+    assert_eq!(cards[0].front, "极限");
+    assert_eq!(cards[1].front, "导数");
+    assert_eq!(cards[2].front, "孤立术语");
+}
+
+#[test]
+fn back_uses_context_sentence_when_present() {
+    // Act
+    let cards = cards_from_note(NOTE_WITH_GLOSSARY);
+    // Assert：back=正文含术语的上下文句（不是词汇表行本身）
+    assert!(cards[0].back.contains("趋近行为"), "应取正文上下文: {}", cards[0].back);
+    assert!(!cards[0].back.starts_with("- "));
+}
+
+#[test]
+fn back_falls_back_to_glossary_line_without_context() {
+    // Act：孤立术语正文无命中
+    let cards = cards_from_note(NOTE_WITH_GLOSSARY);
+    // Assert：兜底为词汇表行（诚实简陋但有卡）
+    assert!(cards[2].back.starts_with("- 孤立术语"));
+}
+
+#[test]
+fn note_without_glossary_yields_no_cards() {
+    // Arrange：无词汇表块的笔记（口播类）
+    let content = "# 闲聊\n\n今天聊点轻松的，没有结构。";
+    // Act/Assert：诚实零卡
+    assert!(cards_from_note(content).is_empty());
+}
+
+#[test]
+fn multi_sentence_fragment_becomes_card() {
+    // Arrange：两句话的碎片
+    let text = "眼影晕染要用松软的刷子。少量多次才不会显脏。";
+    // Act
+    let card = card_from_fragment(text);
+    // Assert：首句线索 + 全文验证
+    let card = card.expect("多句碎片应出卡");
+    assert_eq!(card.front, "眼影晕染要用松软的刷子");
+    assert!(card.back.contains("少量多次"));
+}
+
+#[test]
+fn single_sentence_fragment_no_card() {
+    // Arrange/Act：单句碎片无回忆结构
+    let card = card_from_fragment("只有一句话的碎片");
+    // Assert：诚实不出卡（防假燃料）
+    assert!(card.is_none());
+}
+
+#[test]
+fn fragment_front_truncated_to_limit() {
+    // Arrange：超长首句
+    let long = "长".repeat(100);
+    let text = format!("{}。第二句验证材料。", long);
+    // Act
+    let card = card_from_fragment(&text).expect("出卡");
+    // Assert：front 上限 60 字符（UI 可读性）
+    assert!(card.front.chars().count() <= 60);
+}

app/src-tauri/src/scheduler.rs

@@ -0,0 +1,116 @@
+//! 间隔重复调度器（v0.11.2；FSRS-6 主实现，ADR-018）。
+//!
+//! @ai-context: fsrs crate（Anki 23.10+ 默认调度器算法）——DSR 三变量模型，
+//!              按目标留存率（0.9）反解间隔；纯算法零网络，契合本地优先。
+//!              裁决记录：SM-2 手写兜底的条件（依赖引入受限）未触发——crate
+//!              引入成功，不保留双实现（YAGNI；接口稳定可后补）。
+//! @ai-context: 弹性承诺纪律（v4 路线图裁决 4）：调度纯函数无 streak 概念，
+//!              欠账卡仅按 due_at 排序呈现——不追债不清零（N10 归零暴政防御）。
+//! @ai-context: 纯逻辑层（输入状态+评分→输出新状态+到期时刻），DB/UI 无关；
+//!              CardState 以 JSON 落 flashcards.state_json（版本演进容忍缺字段）。
+
+use fsrs::{MemoryState, FSRS};
+use serde::{Deserialize, Serialize};
+
+/// 目标留存率（FSRS 默认推荐值；个性化调参为复习数据积累后的远期扩展）。
+pub const DESIRED_RETENTION: f32 = 0.9;
+/// 一天的毫秒数。
+const DAY_MS: u64 = 86_400_000;
+
+/// 复习评分（四档——提取优先：先回忆再看后评分）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Rating {
+    Again,
+    Hard,
+    Good,
+    Easy,
+}
+
+impl Rating {
+    /// 解析前端评分字符串（非法值 → None，诚实不猜）。
+    pub fn parse(s: &str) -> Option<Rating> {
+        match s {
+            "again" => Some(Rating::Again),
+            "hard" => Some(Rating::Hard),
+            "good" => Some(Rating::Good),
+            "easy" => Some(Rating::Easy),
+            _ => None,
+        }
+    }
+}
+
+/// 卡片记忆状态（序列化落库；serde(default) 容忍旧格式演进）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub struct CardState {
+    /// FSRS 稳定性（天——记忆可维持时长的度量）
+    pub stability: f32,
+    /// FSRS 难度（1-10）
+    pub difficulty: f32,
+    /// 累计复习次数
+    pub reps: u32,
+    /// 遗忘次数（Again 计数——弹性承诺下仅统计不惩罚）
+    pub lapses: u32,
+    /// 上次复习时刻（Unix 毫秒；新卡 0）
+    pub last_review_ms: u64,
+}
+
+impl Default for CardState {
+    fn default() -> Self {
+        Self { stability: 0.0, difficulty: 0.0, reps: 0, lapses: 0, last_review_ms: 0 }
+    }
+}
+
+/// 调度输出（新状态 + 间隔天数 + 到期时刻）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ScheduleOutcome {
+    pub next: CardState,
+    pub interval_days: f32,
+    pub due_at_ms: u64,
+}
+
+/// 调度主入口（纯函数）：新卡 state=None，复习卡 Some。
+///
+/// @ai-context: fsrs.next_states 对四个评分一次算全（Again/Hard/Good/Easy），
+///              取本次评分分支；days_elapsed=距上次复习天数（新卡 0）——
+///              欠账卡按真实过期天数演化状态（FSRS 正确处理延迟复习）。
+pub fn schedule(state: Option<&CardState>, rating: Rating, now_ms: u64) -> ScheduleOutcome {
+    // 默认参数恒有效（FSRS::default 同款 expect 口径）
+    let fsrs = FSRS::new(&[]).expect("FSRS-6 默认参数恒有效");
+    let (mem, days_elapsed) = match state {
+        Some(s) if s.reps > 0 => (
+            Some(MemoryState { stability: s.stability, difficulty: s.difficulty }),
+            (now_ms.saturating_sub(s.last_review_ms) / DAY_MS) as u32,
+        ),
+        _ => (None, 0),
+    };
+    let states = fsrs
+        .next_states(mem, DESIRED_RETENTION, days_elapsed)
+        .expect("有限状态输入恒有效（fsrs 内部 validate）");
+    let item = match rating {
+        Rating::Again => states.again,
+        Rating::Hard => states.hard,
+        Rating::Good => states.good,
+        Rating::Easy => states.easy,
+    };
+    let base = state.cloned().unwrap_or_default();
+    // 间隔下限 1 天（无学习步设计——当日重学靠 Again 后次日再现，简化 UI）
+    let interval_days = item.interval.max(1.0);
+    let due_at_ms = now_ms + (interval_days.round() as u64).max(1) * DAY_MS;
+    ScheduleOutcome {
+        next: CardState {
+            stability: item.memory.stability,
+            difficulty: item.memory.difficulty,
+            reps: base.reps + 1,
+            lapses: base.lapses + if rating == Rating::Again { 1 } else { 0 },
+            last_review_ms: now_ms,
+        },
+        interval_days,
+        due_at_ms,
+    }
+}
+
+#[cfg(test)]
+#[path = "scheduler_tests.rs"]
+mod tests;

app/src-tauri/src/scheduler_tests.rs

@@ -0,0 +1,95 @@
+//! scheduler 单测（AAA 模式；FSRS-6 行为契约）。
+
+use crate::scheduler::{schedule, CardState, Rating};
+
+/// 基准时刻（固定，单测可重现）。
+const NOW_MS: u64 = 1_755_900_000_000;
+
+#[test]
+fn new_card_good_produces_positive_interval() {
+    // Arrange/Act：新卡首次 Good
+    let out = schedule(None, Rating::Good, NOW_MS);
+    // Assert：状态初始化合理，到期在未来
+    assert!(out.next.stability > 0.0, "新卡 Good 应有正稳定性");
+    assert!(out.next.difficulty > 0.0);
+    assert_eq!(out.next.reps, 1);
+    assert_eq!(out.next.lapses, 0);
+    assert!(out.interval_days >= 1.0, "间隔下限 1 天");
+    assert!(out.due_at_ms > NOW_MS);
+}
+
+#[test]
+fn rating_monotonicity_easy_over_good_over_again() {
+    // Arrange/Act：同一新卡四种评分
+    let again = schedule(None, Rating::Again, NOW_MS);
+    let good = schedule(None, Rating::Good, NOW_MS);
+    let easy = schedule(None, Rating::Easy, NOW_MS);
+    // Assert：评分越高间隔越长（Again 最短——FSRS 核心契约）
+    assert!(easy.interval_days > good.interval_days, "Easy 间隔应长于 Good");
+    assert!(good.interval_days >= again.interval_days, "Good 间隔不短于 Again");
+}
+
+#[test]
+fn again_increments_lapses() {
+    // Arrange：复习过的卡
+    let first = schedule(None, Rating::Good, NOW_MS);
+    // Act：遗忘一次
+    let out = schedule(Some(&first.next), Rating::Again, NOW_MS + 86_400_000);
+    // Assert：lapses+1，reps 累计
+    assert_eq!(out.next.lapses, 1);
+    assert_eq!(out.next.reps, 2);
+}
+
+#[test]
+fn successful_review_grows_stability() {
+    // Arrange：首次 Good 后按时复习再 Good
+    let first = schedule(None, Rating::Good, NOW_MS);
+    // Act：到期时刻复习
+    let second = schedule(Some(&first.next), Rating::Good, first.due_at_ms);
+    // Assert：稳定性增长（间隔效应——FSRS 核心收益）
+    assert!(
+        second.next.stability > first.next.stability,
+        "成功复习应增长稳定性: {} → {}",
+        first.next.stability,
+        second.next.stability
+    );
+    assert!(second.interval_days >= first.interval_days);
+}
+
+#[test]
+fn overdue_card_uses_real_elapsed_days() {
+    // Arrange：欠账 30 天的卡（弹性承诺——不追债不清零，按真实间隔演化）
+    let first = schedule(None, Rating::Good, NOW_MS);
+    let overdue_at = first.due_at_ms + 30 * 86_400_000;
+    // Act
+    let out = schedule(Some(&first.next), Rating::Good, overdue_at);
+    // Assert：状态仍演化成功（不 panic 不清零），last_review 更新为当前
+    assert!(out.next.stability > 0.0);
+    assert_eq!(out.next.last_review_ms, overdue_at);
+    assert_eq!(out.next.lapses, 0, "按时评分 Good 不计遗忘");
+}
+
+#[test]
+fn card_state_json_roundtrip() {
+    // Arrange：落库格式（flashcards.state_json）序列化往返
+    let state = CardState {
+        stability: 12.5,
+        difficulty: 5.2,
+        reps: 3,
+        lapses: 1,
+        last_review_ms: NOW_MS,
+    };
+    // Act
+    let json = serde_json::to_string(&state).expect("serialize");
+    let back: CardState = serde_json::from_str(&json).expect("deserialize");
+    // Assert
+    assert_eq!(back, state);
+}
+
+#[test]
+fn rating_parse_accepts_contract_values() {
+    // Arrange/Act/Assert：四档契约值 + 非法值诚实 None
+    assert_eq!(Rating::parse("again"), Some(Rating::Again));
+    assert_eq!(Rating::parse("easy"), Some(Rating::Easy));
+    assert_eq!(Rating::parse("unknown"), None);
+}