feat(settlement): 结算数据层与计划执行命令

Author: Aparencia

app/src-tauri/src/commands_flashcards.rs

@@ -194,3 +194,25 @@ impl Rating {
         .to_string()
     }
 }
+
+/// 学习循环指标读数（v4 §8 过程指标可见化——防测量层过度建设的前提是先有读数）。
+#[derive(Debug, Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct LearningMetrics {
+    pub card_reviewed: i64,
+    pub fragment_upgraded: i64,
+    pub group_settled: i64,
+}
+
+/// 学习循环指标（北极星过程读数：复习次数/碎片升级数/组结算数）。
+#[tauri::command]
+pub fn learning_metrics(state: State<'_, AppState>) -> Result<LearningMetrics, String> {
+    Ok(LearningMetrics {
+        card_reviewed: state.db.count_metric_events("card_reviewed").map_err(|e| e.to_string())?,
+        fragment_upgraded: state
+            .db
+            .count_metric_events("fragment_upgraded")
+            .map_err(|e| e.to_string())?,
+        group_settled: state.db.count_metric_events("group_settled").map_err(|e| e.to_string())?,
+    })
+}

app/src-tauri/src/commands_settlement.rs

@@ -0,0 +1,197 @@
+//! 组结算 commands（v0.11.3；防沼泽仪式系统层）。
+//!
+//! @ai-context: 结算必须是用户可见的仪式而非静默后台（v4 路线图 Step 6）：
+//!              settlement_plan 先呈现候选（重复合并对 + 归档候选），用户
+//!              确认后 execute_settlement 执行；核心提炼为本地规则版组核心笔记。
+//! @ai-context: 归档不删除（fragments.status=archived 可恢复）；合并=保留长文本
+//!              归档短重复项；结算记录落 settlements + metrics(group_settled)
+//!              （北极星组成③）。
+//! @ai-context: 本层只做参数校验、编排数据层/纯函数、错误映射（AGENTS.md §6）。
+
+use serde::Serialize;
+use tauri::State;
+
+use crate::commands::AppState;
+use crate::settlement::{find_merge_pairs, settlement_due, SettlementSignals, ARCHIVE_AGE_DAYS};
+use crate::types::NewNote;
+
+/// 合并对呈现（前端展示由用户确认）。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MergePairView {
+    pub keep_id: i64,
+    pub drop_id: i64,
+    pub keep_text: String,
+    pub drop_text: String,
+}
+
+/// 归档候选呈现。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ArchiveCandidateView {
+    pub id: i64,
+    pub text: String,
+}
+
+/// 结算计划（仪式第一步：呈现——用户看见沼泽全貌）。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SettlementPlan {
+    pub item_count: usize,
+    pub due: bool,
+    pub last_settled_at: Option<i64>,
+    pub merge_pairs: Vec<MergePairView>,
+    pub archive_candidates: Vec<ArchiveCandidateView>,
+}
+
+/// 结算结果（仪式收尾：留痕可溯）。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SettlementResult {
+    pub merged: usize,
+    pub archived: usize,
+    pub core_note_id: Option<i64>,
+}
+
+/// 生成结算计划（阈值/周期判定 + 重复合并对 + 归档候选）。
+#[tauri::command]
+pub fn settlement_plan(state: State<'_, AppState>, group_id: i64) -> Result<SettlementPlan, String> {
+    if group_id <= 0 {
+        return Err("无效的组 id".to_string());
+    }
+    settlement_plan_inner(&state, group_id)
+}
+
+/// 执行结算（仪式第二步：按用户选择应用合并/归档 + 核心提炼 + 留痕）。
+///
+/// @ai-context: 计划在执行时重算（防陈旧计划误伤——呈现与执行间的窗口内
+///              可能有新碎片进组）；核心提炼为本地规则版（组核心笔记：笔记
+///              目录 + 活跃碎片摘要），AI 精修可选增强留 V1.0。
+#[tauri::command]
+pub fn execute_settlement(
+    state: State<'_, AppState>,
+    group_id: i64,
+    apply_merges: bool,
+    apply_archives: bool,
+) -> Result<SettlementResult, String> {
+    if group_id <= 0 {
+        return Err("无效的组 id".to_string());
+    }
+    // 重算计划（新鲜口径）
+    let state_clone: AppState = (*state).clone();
+    let plan = settlement_plan_inner(&state_clone, group_id)?;
+    let mut merged = 0usize;
+    let mut archived = 0usize;
+    if apply_merges {
+        for pair in &plan.merge_pairs {
+            if state.db.set_fragment_status(pair.drop_id, "archived").map_err(|e| e.to_string())? {
+                merged += 1;
+            }
+        }
+    }
+    if apply_archives {
+        for cand in &plan.archive_candidates {
+            if state.db.set_fragment_status(cand.id, "archived").map_err(|e| e.to_string())? {
+                archived += 1;
+            }
+        }
+    }
+    // 核心提炼：组核心笔记（本地规则——笔记目录 + 碎片摘要，落组内）
+    let core_note_id = create_core_note(&state_clone, group_id)?;
+    // 留痕：结算记录 + 北极星埋点（组成③经历过结算）
+    let stats = serde_json::json!({
+        "merged": merged, "archived": archived, "coreNoteId": core_note_id,
+        "itemCountBefore": plan.item_count,
+    })
+    .to_string();
+    state.db.create_settlement(group_id, &stats).map_err(|e| e.to_string())?;
+    let payload = serde_json::json!({ "groupId": group_id, "merged": merged, "archived": archived }).to_string();
+    let _ = state.db.add_metric_event("group_settled", &payload);
+    Ok(SettlementResult { merged, archived, core_note_id })
+}
+
+/// settlement_plan 的内部实现（command 与 execute 复用，避免 State 二次借用）。
+fn settlement_plan_inner(state: &AppState, group_id: i64) -> Result<SettlementPlan, String> {
+    let group = state
+        .db
+        .get_group(group_id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| format!("笔记组不存在: {}", group_id))?;
+    let fragments = state.db.list_fragments_by_group(group_id).map_err(|e| e.to_string())?;
+    let notes = state.db.list_notes_by_group(group_id).map_err(|e| e.to_string())?;
+    let now_secs = crate::db::unix_seconds();
+    let last_settled_at = state.db.latest_settlement_at(group_id).map_err(|e| e.to_string())?;
+    let item_count = fragments.len() + notes.len();
+    let due = settlement_due(&SettlementSignals {
+        item_count,
+        last_settled_at,
+        created_at: group.created_at,
+        now_secs,
+    });
+    let items: Vec<(i64, String)> =
+        fragments.iter().take(200).map(|f| (f.id, f.text.clone())).collect();
+    let texts: std::collections::HashMap<i64, &str> =
+        fragments.iter().map(|f| (f.id, f.text.as_str())).collect();
+    let merge_pairs = find_merge_pairs(&items)
+        .into_iter()
+        .filter_map(|(keep, drop)| {
+            Some(MergePairView {
+                keep_id: keep,
+                drop_id: drop,
+                keep_text: texts.get(&keep)?.to_string(),
+                drop_text: texts.get(&drop)?.to_string(),
+            })
+        })
+        .collect();
+    let age_cutoff = now_secs - ARCHIVE_AGE_DAYS * 86_400;
+    let mut archive_candidates = Vec::new();
+    for f in &fragments {
+        if f.created_at < age_cutoff && !state.db.fragment_has_card(f.id).map_err(|e| e.to_string())? {
+            archive_candidates.push(ArchiveCandidateView { id: f.id, text: f.text.clone() });
+        }
+    }
+    Ok(SettlementPlan { item_count, due, last_settled_at, merge_pairs, archive_candidates })
+}
+
+/// 组核心笔记（本地规则提炼：笔记目录 + 活跃碎片摘要）。
+fn create_core_note(state: &AppState, group_id: i64) -> Result<Option<i64>, String> {
+    let group = match state.db.get_group(group_id).map_err(|e| e.to_string())? {
+        Some(g) => g,
+        None => return Ok(None),
+    };
+    let notes = state.db.list_notes_by_group(group_id).map_err(|e| e.to_string())?;
+    let fragments = state.db.list_fragments_by_group(group_id).map_err(|e| e.to_string())?;
+    if notes.is_empty() && fragments.is_empty() {
+        return Ok(None); // 空组无核心可提炼（诚实不造假燃料）
+    }
+    let mut md = format!("# {} · 结算提炼\n\n", group.name);
+    if !notes.is_empty() {
+        md.push_str("## 组内笔记\n\n");
+        for n in &notes {
+            md.push_str(&format!("- {}\n", n.title));
+        }
+        md.push('\n');
+    }
+    if !fragments.is_empty() {
+        md.push_str("## 活跃碎片摘要\n\n");
+        for f in fragments.iter().take(30) {
+            let excerpt: String = f.text.chars().take(50).collect();
+            md.push_str(&format!("- {}\n", excerpt));
+        }
+    }
+    let note = state
+        .db
+        .create_note(&NewNote {
+            title: format!("{} · 结算提炼", group.name),
+            content: md,
+            source: "manual".to_string(),
+            session_id: None,
+            rule_version: None,
+            purify_stats: None,
+            tags: None,
+            properties: None,
+            group_id: Some(group_id),
+        })
+        .map_err(|e| e.to_string())?;
+    Ok(Some(note.id))
+}

app/src-tauri/src/db_flashcards.rs

@@ -154,6 +154,8 @@ impl Db {
     }
 
     /// 组是否有复习记录（北极星组成①；经 flashcards.group_id 关联）。
+    /// 登记豁免 dead_code：按组北极星展示接线在 V1.0 周报面（v4 §7.5）。
+    #[allow(dead_code)]
     pub fn group_has_reviews(&self, group_id: i64) -> Result<bool> {
         self.with_conn(|conn| {
             let count: i64 = conn.query_row(

app/src-tauri/src/db_fragments.rs

@@ -85,6 +85,9 @@ impl Db {
     }
 
     /// 碎片计数（组结算触发信号；按组+status 统计）。
+    /// 登记豁免 dead_code：结算触发器当前用 list 长度折算，计数接口留
+    /// 给 v0.11.3+ 阈值埋点面板消费。
+    #[allow(dead_code)]
     pub fn count_fragments(&self, group_id: Option<i64>, status: Option<&str>) -> Result<i64> {
         self.with_conn(|conn| {
             let mut sql = "SELECT COUNT(*) FROM fragments WHERE 1=1".to_string();
@@ -106,6 +109,8 @@ impl Db {
     }
 
     /// 移动碎片到组（None=移出；用户纠错/结算归组共用）。
+    /// 登记豁免 dead_code：碎片移动 UI 随 v0.11.3+ 结算面建设接线。
+    #[allow(dead_code)]
     pub fn update_fragment_group(&self, id: i64, group_id: Option<i64>) -> Result<bool> {
         self.with_conn(|conn| {
             let affected = conn.execute(

app/src-tauri/src/db_migrations.rs

@@ -142,7 +142,15 @@ pub(crate) fn init_schema(conn: &Connection) -> Result<()> {
             payload_json TEXT NOT NULL DEFAULT '{}',
             created_at INTEGER NOT NULL
         );
-        CREATE INDEX IF NOT EXISTS idx_metrics_kind ON metrics_events(kind);",
+        CREATE INDEX IF NOT EXISTS idx_metrics_kind ON metrics_events(kind);
+        -- v0.11.3（组结算机制；防沼泽仪式记录——结算历史可追溯）
+        CREATE TABLE IF NOT EXISTS settlements (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            group_id INTEGER NOT NULL REFERENCES note_groups(id) ON DELETE CASCADE,
+            stats_json TEXT NOT NULL,
+            created_at INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_settlements_group ON settlements(group_id, created_at);",
     )?;
     // v0.5.0 M1（REQ-043）：旧库迁移——sessions 表补 profile 列（兼容既有数据库）
     ensure_column(conn, "sessions", "profile", "ALTER TABLE sessions ADD COLUMN profile TEXT")?;

app/src-tauri/src/db_settlements.rs

@@ -0,0 +1,56 @@
+//! 结算数据层（v0.11.3；settlements 记录 + 归档候选查询）。
+//!
+//! @ai-context: 结算历史是周期触发器的判据源（last_settled_at）与北极星
+//!              组成③（经历过结算）；归档不删除——fragments.status 翻转可恢复。
+
+use rusqlite::params;
+
+use crate::db::{unix_seconds, Db};
+use crate::error::Result;
+
+impl Db {
+    /// 记一次结算（stats_json=提炼/合并/归档统计）。
+    pub fn create_settlement(&self, group_id: i64, stats_json: &str) -> Result<i64> {
+        let now = unix_seconds();
+        self.with_conn(|conn| {
+            conn.execute(
+                "INSERT INTO settlements (group_id, stats_json, created_at) VALUES (?1, ?2, ?3)",
+                params![group_id, stats_json, now],
+            )?;
+            Ok(conn.last_insert_rowid() as i64)
+        })
+    }
+
+    /// 组最近一次结算时刻（None=从未结算——周期判定回退建组时刻）。
+    pub fn latest_settlement_at(&self, group_id: i64) -> Result<Option<i64>> {
+        self.with_conn(|conn| {
+            let mut stmt = conn.prepare(
+                "SELECT created_at FROM settlements WHERE group_id = ?1
+                 ORDER BY created_at DESC LIMIT 1",
+            )?;
+            let mut rows = stmt.query_map(params![group_id], |r| r.get::<_, i64>(0))?;
+            match rows.next() {
+                Some(Ok(t)) => Ok(Some(t)),
+                Some(Err(e)) => Err(e.into()),
+                None => Ok(None),
+            }
+        })
+    }
+
+    /// 碎片是否有闪卡绑定（归档候选判据：有卡碎片不进归档——学习循环资产）。
+    pub fn fragment_has_card(&self, fragment_id: i64) -> Result<bool> {
+        self.with_conn(|conn| {
+            let count: i64 = conn.query_row(
+                "SELECT COUNT(*) FROM flashcards WHERE fragment_id = ?1",
+                params![fragment_id],
+                |r| r.get(0),
+            )?;
+            Ok(count > 0)
+        })
+    }
+}
+
+/// 单测独立文件。
+#[cfg(test)]
+#[path = "db_settlements_tests.rs"]
+mod tests;

app/src-tauri/src/db_settlements_tests.rs

@@ -0,0 +1,73 @@
+//! db_settlements 单测（内存库；AAA 模式）。
+
+use crate::db::Db;
+use crate::db_flashcards::NewFlashcard;
+use crate::db_fragments::NewFragment;
+use crate::types::NewNoteGroup;
+
+/// 内存库。
+fn mem_db() -> Db {
+    Db::open(":memory:").expect("内存库打开")
+}
+
+/// 建组助手。
+fn make_group(db: &Db) -> i64 {
+    db.create_group(&NewNoteGroup {
+        name: "结算组".to_string(),
+        terrain: "feed".to_string(),
+        kind: "topic".to_string(),
+        domain_tag: Some("beauty".to_string()),
+        source: "route".to_string(),
+        series_key: None,
+        route_reason: None,
+    })
+    .expect("group")
+    .id
+}
+
+/// 碎片入参助手。
+fn frag(group_id: i64, text: &str) -> NewFragment {
+    NewFragment {
+        text: text.to_string(),
+        image_path: None,
+        domain_tag: None,
+        group_id: Some(group_id),
+        source: "manual".to_string(),
+    }
+}
+
+#[test]
+fn settlement_record_and_latest_lookup() {
+    // Arrange
+    let db = mem_db();
+    let g = make_group(&db);
+    assert_eq!(db.latest_settlement_at(g).expect("none"), None);
+    // Act：两次结算取最新
+    db.create_settlement(g, r#"{"merged":1}"#).expect("s1");
+    db.create_settlement(g, r#"{"merged":2}"#).expect("s2");
+    // Assert：最近结算时刻可读（周期触发器判据源）
+    assert!(db.latest_settlement_at(g).expect("some").is_some());
+}
+
+#[test]
+fn fragment_card_binding_blocks_archive() {
+    // Arrange：两碎片——一有卡绑定一没有
+    let db = mem_db();
+    let g = make_group(&db);
+    let with_card = db.create_fragment(&frag(g, "有卡碎片")).expect("f1");
+    let bare = db.create_fragment(&frag(g, "裸碎片")).expect("f2");
+    db.create_card(&NewFlashcard {
+        group_id: g,
+        note_id: None,
+        fragment_id: Some(with_card.id),
+        front: "有卡碎片".to_string(),
+        back: "back".to_string(),
+        kind: "fact".to_string(),
+        state_json: "{}".to_string(),
+        due_at: 0,
+    })
+    .expect("card");
+    // Act/Assert：绑定判定正确（有卡碎片不进归档——学习循环资产）
+    assert!(db.fragment_has_card(with_card.id).expect("q1"));
+    assert!(!db.fragment_has_card(bare.id).expect("q2"));
+}