feat(knowledge): 模型卡卡面纯函数与数据层

Author: Aparencia

app/src-tauri/src/db_flashcards.rs

@@ -209,6 +209,65 @@ impl Db {
             Ok(count)
         })
     }
+
+    /// 列组内卡片（kind 过滤可选；ORDER BY id ASC）。
+    ///
+    /// @ai-context: 组仍是唯一容器（spec §一）——model 卡在组内，本方法是组卡列表
+    ///              与"模型卡列表"两处的数据源（kind=Some("model")）。排序按 id 升序
+    ///              稳定（创建序，避免依赖插入顺序）。
+    /// @ai-context: kind 为补值级增量（kind TEXT 无 CHECK；'model' 新增补值，命令层
+    ///              透传）：过滤时传 None 取全组卡，传 Some 按 kind 过滤。
+    pub fn list_cards_by_group(&self, group_id: i64, kind: Option<&str>) -> Result<Vec<Flashcard>> {
+        self.with_conn(|conn| {
+            let mut sql =
+                format!("SELECT {} FROM flashcards WHERE group_id = ?1", CARD_COLUMNS);
+            if kind.is_some() {
+                sql.push_str(" AND kind = ?2");
+            }
+            sql.push_str(" ORDER BY id ASC");
+            let mut stmt = conn.prepare(&sql)?;
+            let rows = match kind {
+                Some(k) => stmt.query_map(params![group_id, k], row_to_card)?,
+                None => stmt.query_map(params![group_id], row_to_card)?,
+            };
+            rows.collect::<rusqlite::Result<Vec<_>>>().map_err(Into::into)
+        })
+    }
+
+    /// 同组同 front 幂等取卡（已有 card_front_exists 是 bool；本方法取全卡用于升格）。
+    ///
+    /// @ai-context: 升格/免重复判据要拿到既有卡本体（front/kind/back 等）而不是布尔：
+    ///              create_model_card 幂等（同组同 front 已有则复用）依赖本方法取整卡。
+    /// @ai-context: 同组同 front 理论上唯一（生成幂等键），故 `LIMIT 1`；未命中 → None。
+    pub fn find_card_by_front(&self, group_id: i64, front: &str) -> Result<Option<Flashcard>> {
+        self.with_conn(|conn| {
+            let mut stmt = conn.prepare(&format!(
+                "SELECT {} FROM flashcards WHERE group_id = ?1 AND front = ?2 LIMIT 1",
+                CARD_COLUMNS
+            ))?;
+            let mut rows = stmt.query_map(params![group_id, front], row_to_card)?;
+            match rows.next() {
+                Some(Ok(c)) => Ok(Some(c)),
+                Some(Err(e)) => Err(e.into()),
+                None => Ok(None),
+            }
+        })
+    }
+
+    /// 更新卡背面 back（升格锚点追加写回）。
+    ///
+    /// @ai-context: 升格在 Create/Merge 分支把"→ 概念「name」"独立锚点行追加到 back
+    ///              （以 back_has_anchor 幂等判定先查后写）——本方法只写 back，不回填
+    ///              其他列，保持零 schema/零破坏。无该 id → false。
+    pub fn update_card_back(&self, id: i64, back: &str) -> Result<bool> {
+        self.with_conn(|conn| {
+            let affected = conn.execute(
+                "UPDATE flashcards SET back = ?1 WHERE id = ?2",
+                params![back, id],
+            )?;
+            Ok(affected > 0)
+        })
+    }
 }
 
 /// 把 rusqlite 行映射为 Flashcard。

app/src-tauri/src/db_flashcards_tests.rs

@@ -156,3 +156,71 @@ fn metric_events_record_and_count() {
     assert_eq!(db.count_metric_events("fragment_upgraded").expect("f"), 1);
     assert_eq!(db.count_metric_events("group_settled").expect("s"), 0);
 }
+
+/// 指定 kind 的卡（kind 过滤/模型卡数据源测试用；区别于默认 fact 的 card()）。
+fn card_kind(group_id: i64, front: &str, kind: &str) -> NewFlashcard {
+    NewFlashcard {
+        group_id,
+        note_id: None,
+        fragment_id: None,
+        front: front.to_string(),
+        back: format!("{} 的释义", front),
+        kind: kind.to_string(),
+        state_json: "{}".to_string(),
+        due_at: 1000,
+    }
+}
+
+#[test]
+fn list_cards_by_group_filters_by_kind() {
+    // Arrange：同组建 fact + model 两卡；按创建序（id 升序）应稳定排
+    let db = mem_db();
+    let gid = make_group(&db);
+    db.create_card(&card(gid, "极限", 1000)).expect("fact");
+    db.create_card(&card_kind(gid, "安全边际", "model")).expect("model");
+    db.create_card(&card_kind(gid, "复利", "model")).expect("model2");
+    // Act：无 kind 过滤 / model 过滤 / fact 过滤 / 不存在 kind
+    let all = db.list_cards_by_group(gid, None).expect("all");
+    let models = db.list_cards_by_group(gid, Some("model")).expect("model");
+    let facts = db.list_cards_by_group(gid, Some("fact")).expect("fact");
+    // Assert：ORDER BY id 升序；kind 过滤正确；他组不受影响
+    assert_eq!(all.len(), 3);
+    assert_eq!(all[0].front, "极限");
+    assert_eq!(all[1].front, "安全边际");
+    assert_eq!(all[2].front, "复利");
+    assert_eq!(models.len(), 2);
+    assert!(models.iter().all(|c| c.kind == "model"));
+    assert_eq!(facts.len(), 1);
+    assert_eq!(facts[0].front, "极限");
+    assert_eq!(facts[0].kind, "fact");
+    assert_eq!(db.list_cards_by_group(9999, None).expect("other").len(), 0);
+}
+
+#[test]
+fn find_card_by_front_hit_and_miss() {
+    // Arrange：同组建一卡（同组同 front 幂等取卡——升格判据）
+    let db = mem_db();
+    let gid = make_group(&db);
+    db.create_card(&card_kind(gid, "安全边际", "model")).expect("create");
+    // Act/Assert：命中返回整卡；未命中返回 None
+    let hit = db.find_card_by_front(gid, "安全边际").expect("hit").expect("应命中");
+    assert_eq!(hit.front, "安全边际");
+    assert_eq!(hit.kind, "model");
+    assert!(db.find_card_by_front(gid, "不存在").expect("miss").is_none());
+}
+
+#[test]
+fn update_card_back_roundtrip() {
+    // Arrange：建卡后升格追加锚点再写回
+    let db = mem_db();
+    let gid = make_group(&db);
+    let c = db.create_card(&card(gid, "极限", 1000)).expect("create");
+    // Act：把锚点独立行追加到 back 并写回
+    let new_back = format!("{}\n→ 概念「安全边际」", c.back);
+    let updated = db.update_card_back(c.id, &new_back).expect("update");
+    // Assert：往返命中；不存在的 id 返回 false（无该行可更新）
+    assert!(updated);
+    let fetched = db.get_card(c.id).expect("get").expect("exists");
+    assert_eq!(fetched.back, new_back);
+    assert!(!db.update_card_back(9999, "x").expect("miss"));
+}

app/src-tauri/src/knowledge_card.rs

@@ -0,0 +1,147 @@
+//! 概念双面体——模型卡卡面纯函数（v0.13.2 REQ-206）。
+//!
+//! @ai-context: 概念双面体（记忆面×思辨面）单向升格——组内 model 卡（front=概念名、
+//!              back=三问）经升格成为体系内概念。本文件定义卡背三问的纯函数契约：
+//!              format（compose）与 parse 互为逆；back_has_anchor 判定是否已写回链锚点。
+//! @ai-context: 锚点＝独立行 `→ 概念「name」`，整行前缀判定（行首匹配）——防字段值
+//!              中部出现"→ 概念「…」"被误判为已锚定（规范 §三），也防升格重复回链。
+//! @ai-context: M1 原子层 API 供 M2 command 层接入用（机制先行）；v0.13.2 升格命令
+//!              已接线（commands_knowledge_cards*），无 dead_code 残留。
+
+/// 卡背三问（概念双面体：本质 / 边界 / 联系）。
+///
+/// @ai-context: 三问对应概念三问一用卡片的三个思辨面——本质（它是什么）、
+///              边界（适用范围/限制）、联系（与之关联的概念/体系）。任一问缺省
+///              表示该卡尚未填写（不代表"无此问"），故用 Option。
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct ModelCardBack {
+    /// 本质（What——它是什么）。
+    pub essence: Option<String>,
+    /// 边界（Where——适用范围/限制）。
+    pub boundary: Option<String>,
+    /// 联系（How——与之关联的概念/体系）。
+    pub relation: Option<String>,
+}
+
+/// 卡背字段标签（内部枚举，无公开语义）。
+#[derive(Clone, Copy)]
+enum Field {
+    Essence,
+    Boundary,
+    Relation,
+}
+
+/// 行首标签判定。
+///
+/// @ai-context: full-width `：` 为主，半角 `:` 容错——但只在行首（trim 后）匹配，
+///              字段值中部出现同名词（如先写"本质"再展开）不误判为标签行。
+///              返回 (字段, 标签后内容)。
+fn split_label(line: &str) -> Option<(Field, &str)> {
+    let t = line.trim_start();
+    for (full, half, field) in [
+        ("本质：", "本质:", Field::Essence),
+        ("边界：", "边界:", Field::Boundary),
+        ("联系：", "联系:", Field::Relation),
+    ] {
+        if let Some(rest) = t.strip_prefix(full) {
+            return Some((field, rest));
+        }
+        if let Some(rest) = t.strip_prefix(half) {
+            return Some((field, rest));
+        }
+    }
+    None
+}
+
+/// 把字段行拼回值：保留内部换行，trim 首尾空白；空值 → None。
+///
+/// @ai-context: 契约约定"缺标签/缺字段/空字段 → None"——空问不是"有但为空"，而是
+///              信息缺失（缺这一问），落库后前端按 None 渲染占位而非空串。
+fn join_trim(lines: &[String]) -> Option<String> {
+    let joined = lines.join("\n");
+    let trimmed = joined.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+/// 解析卡背文本为三问（三问契约的 parse 侧）。
+///
+/// @ai-context: 标签行（行首 `本质：`/`边界：`/`联系：`）是字段值起点，标签后内容为
+///              该字段首行；后续非标签行并入当前字段直到下一标签（保留内部换行）。
+/// @ai-context: 同名标签后出现者覆盖（后来者胜——重写卡面时旧值作废）；首尾空白经
+///              join_trim 折叠。与 format 互为逆（解析后再格式化幂等）。
+pub fn parse_model_card_back(back_text: &str) -> ModelCardBack {
+    let mut essence: Vec<String> = Vec::new();
+    let mut boundary: Vec<String> = Vec::new();
+    let mut relation: Vec<String> = Vec::new();
+    let mut current: Option<Field> = None;
+
+    for line in back_text.lines() {
+        match split_label(line) {
+            Some((field, rest)) => {
+                let target: &mut Vec<String> = match field {
+                    Field::Essence => {
+                        essence.clear();
+                        &mut essence
+                    }
+                    Field::Boundary => {
+                        boundary.clear();
+                        &mut boundary
+                    }
+                    Field::Relation => {
+                        relation.clear();
+                        &mut relation
+                    }
+                };
+                target.push(rest.to_string());
+                current = Some(field);
+            }
+            None => match current {
+                Some(Field::Essence) => essence.push(line.to_string()),
+                Some(Field::Boundary) => boundary.push(line.to_string()),
+                Some(Field::Relation) => relation.push(line.to_string()),
+                None => {}
+            },
+        }
+    }
+
+    ModelCardBack {
+        essence: join_trim(&essence),
+        boundary: join_trim(&boundary),
+        relation: join_trim(&relation),
+    }
+}
+
+/// 组合三问为卡背文本（三问契约的 compose 侧）。
+///
+/// @ai-context: 空字段留 `标签：` 空行（占位不省略）——保证三行契约稳定，parse 可幂等
+///              往返；与 create_model_card（M2）的卡面契约一致。
+pub fn format_model_card_back(
+    essence: Option<&str>,
+    boundary: Option<&str>,
+    relation: Option<&str>,
+) -> String {
+    format!(
+        "本质：{}\n边界：{}\n联系：{}",
+        essence.unwrap_or(""),
+        boundary.unwrap_or(""),
+        relation.unwrap_or("")
+    )
+}
+
+/// 判定卡背是否已写回链锚点（升格锚点＝独立行前缀 `→ 概念「`）。
+///
+/// @ai-context: 整行前缀判定——只有 trim 后整行以 `→ 概念「` 开头才算已锚定；字段值
+///              中部出现该标记（如联系里提"→ 概念「凯利」"）不算，防误判为已回链。
+///              升格追加锚点时以此幂等（已锚定则不二次追加，见 spec §三）。
+pub fn back_has_anchor(back_text: &str) -> bool {
+    back_text.lines().any(|l| l.trim().starts_with("→ 概念「"))
+}
+
+/// 单测独立文件（保持本文件 ≤300 行，AGENTS.md §3；golden 先行 TDD）。
+#[cfg(test)]
+#[path = "knowledge_card_tests.rs"]
+mod tests;