feat(settlement): 结算双触发判据与重复合并纯函数

Author: Aparencia

app/src-tauri/src/settlement.rs

@@ -0,0 +1,126 @@
+//! 组结算纯函数（v0.11.3；L3 骨折层的组级版——防沼泽仪式）。
+//!
+//! @ai-context: 组沼泽化 ★★★★★ 死法防御——阈值/周期双触发器 + 重复合并判据；
+//!              结算必须是用户可见的仪式（command/UI 层保证），本层只提供判据。
+//! @ai-context: 纯逻辑无 IO；golden 用例覆盖阈值/周期边界与合并判据。
+
+/// 阈值触发：组内条目数上限（超过即该结算）。
+pub const ITEM_THRESHOLD: usize = 50;
+/// 周期触发最小条目数（条目太少不值得结算仪式）。
+pub const CYCLE_ITEM_MIN: usize = 20;
+/// 周期触发天数（距上次结算超过此天数）。
+pub const CYCLE_DAYS: i64 = 90;
+/// 重复判定相似度阈值（字符 bigram 包含度系数）。
+pub const MERGE_SIMILARITY: f32 = 0.7;
+/// 归档候选老化天数（无卡绑定且超过此天数未更新）。
+pub const ARCHIVE_AGE_DAYS: i64 = 180;
+
+/// 结算触发信号。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SettlementSignals {
+    /// 组内活跃条目数（碎片+笔记）
+    pub item_count: usize,
+    /// 上次结算时刻（Unix 秒；None=从未结算——按建组时刻由调用方折算）
+    pub last_settled_at: Option<i64>,
+    /// 组创建时刻（Unix 秒——从未结算时的周期基准）
+    pub created_at: i64,
+    /// 当前时刻（Unix 秒）
+    pub now_secs: i64,
+}
+
+/// 结算触发判定（阈值 OR 周期；双触发器防"永远不结算"与"频繁打扰"两极）。
+///
+/// @ai-context: 阈值：item_count ≥ 50 立即该结算（沼泽化前兆）；
+///              周期：≥20 条且 ≥90 天未结算（低膨胀也定期对账）；
+///              条目 <20 且未过阈值 → 不打扰（仪式有成本）。
+pub fn settlement_due(s: &SettlementSignals) -> bool {
+    if s.item_count >= ITEM_THRESHOLD {
+        return true;
+    }
+    if s.item_count < CYCLE_ITEM_MIN {
+        return false;
+    }
+    let baseline = s.last_settled_at.unwrap_or(s.created_at);
+    let days = (s.now_secs - baseline) / 86_400;
+    days >= CYCLE_DAYS
+}
+
+/// 文本规范化（相似度前置：小写 + 去空白/标点——口径与 asr_dedupe 同源哲学）。
+fn normalize_for_sim(text: &str) -> String {
+    text.to_lowercase()
+        .chars()
+        .filter(|c| c.is_alphanumeric())
+        .collect()
+}
+
+/// 字符 bigram 集合（长度 <2 退化为单字符集）。
+fn bigrams(norm: &str) -> std::collections::HashSet<String> {
+    let chars: Vec<char> = norm.chars().collect();
+    let mut set = std::collections::HashSet::new();
+    if chars.len() < 2 {
+        for c in &chars {
+            set.insert(c.to_string());
+        }
+        return set;
+    }
+    for w in chars.windows(2) {
+        set.insert(w.iter().collect());
+    }
+    set
+}
+
+/// 文本相似度（字符 bigram 包含度系数 inter/min，0..1；空文本 → 0 诚实）。
+///
+/// @ai-context: 用包含度而非 Jaccard（inter/union）——重复碎片常长短不一
+///              （短句是长句的子集），Jaccard 被长度差稀释会漏判；包含度
+///              对"短句完全含于长句"给高分，与重复的真实形态对齐。
+pub fn text_similarity(a: &str, b: &str) -> f32 {
+    let (na, nb) = (normalize_for_sim(a), normalize_for_sim(b));
+    if na.is_empty() || nb.is_empty() {
+        return 0.0;
+    }
+    let (sa, sb) = (bigrams(&na), bigrams(&nb));
+    let inter = sa.intersection(&sb).count() as f32;
+    let min_size = sa.len().min(sb.len()) as f32;
+    if min_size == 0.0 {
+        0.0
+    } else {
+        inter / min_size
+    }
+}
+
+/// 重复合并对（id, 文本）列表 → (保留 id, 丢弃 id) 对列表。
+///
+/// @ai-context: 贪心一对一（每条最多进一对，防链式合并丢内容）；保留项取
+///              文本较长者（信息量下界），丢弃项由结算执行归档（不删除——可恢复）。
+pub fn find_merge_pairs(items: &[(i64, String)]) -> Vec<(i64, i64)> {
+    let mut used = std::collections::HashSet::new();
+    let mut pairs = Vec::new();
+    for i in 0..items.len() {
+        if used.contains(&items[i].0) {
+            continue;
+        }
+        for j in (i + 1)..items.len() {
+            if used.contains(&items[j].0) {
+                continue;
+            }
+            if text_similarity(&items[i].1, &items[j].1) >= MERGE_SIMILARITY {
+                // 保留较长文本（信息量下界）
+                let (keep, drop) = if items[i].1.chars().count() >= items[j].1.chars().count() {
+                    (items[i].0, items[j].0)
+                } else {
+                    (items[j].0, items[i].0)
+                };
+                pairs.push((keep, drop));
+                used.insert(items[i].0);
+                used.insert(items[j].0);
+                break;
+            }
+        }
+    }
+    pairs
+}
+
+#[cfg(test)]
+#[path = "settlement_tests.rs"]
+mod tests;

app/src-tauri/src/settlement_tests.rs

@@ -0,0 +1,101 @@
+//! settlement 单测（AAA 模式；阈值/周期边界 + 合并判据 golden 用例）。
+
+use crate::settlement::{
+    find_merge_pairs, settlement_due, text_similarity, SettlementSignals,
+};
+
+/// 基准：30 条、建组 100 天前、从未结算、当前时刻。
+fn base_signals() -> SettlementSignals {
+    SettlementSignals {
+        item_count: 30,
+        last_settled_at: None,
+        created_at: 1_000_000,
+        now_secs: 1_000_000 + 100 * 86_400,
+    }
+}
+
+#[test]
+fn threshold_triggers_regardless_of_time() {
+    // Arrange：刚建组但已 50 条（重度膨胀）
+    let s = SettlementSignals {
+        item_count: 50,
+        last_settled_at: None,
+        created_at: 1_000_000,
+        now_secs: 1_000_001,
+    };
+    // Act/Assert：阈值触发（沼泽化前兆不等周期）
+    assert!(settlement_due(&s));
+}
+
+#[test]
+fn cycle_triggers_after_ninety_days() {
+    // Arrange：30 条、建组 100 天从未结算
+    let s = base_signals();
+    // Act/Assert：周期触发（≥20 条且 ≥90 天）
+    assert!(settlement_due(&s));
+}
+
+#[test]
+fn recently_settled_not_due() {
+    // Arrange：30 条、10 天前刚结算
+    let s = SettlementSignals {
+        last_settled_at: Some(1_000_000 + 90 * 86_400),
+        ..base_signals()
+    };
+    // Act/Assert：周期重置不打扰
+    assert!(!settlement_due(&s));
+}
+
+#[test]
+fn small_group_never_bothered() {
+    // Arrange：10 条老组（仪式有成本，条目太少不值得）
+    let s = SettlementSignals { item_count: 10, ..base_signals() };
+    // Act/Assert
+    assert!(!settlement_due(&s));
+}
+
+#[test]
+fn similarity_identical_and_disjoint() {
+    // Arrange/Act/Assert：全同=1，无关≈0
+    assert!(text_similarity("眼影晕染技巧", "眼影晕染技巧") > 0.99);
+    assert!(text_similarity("眼影晕染技巧", "Python 装饰器原理") < 0.2);
+    assert_eq!(text_similarity("", "任何文本"), 0.0);
+}
+
+#[test]
+fn similarity_near_duplicate_above_threshold() {
+    // Arrange：轻微改写的重复碎片（典型重复形态）
+    let a = "眼影晕染要用松软的刷子少量多次";
+    let b = "眼影晕染要用松软的刷子，少量多次！";
+    // Act/Assert：标点差异不影响重复判定
+    assert!(text_similarity(a, b) >= 0.7, "sim={}", text_similarity(a, b));
+}
+
+#[test]
+fn merge_pairs_keep_longer_and_greedy() {
+    // Arrange：三条——前两条重复，第三条独立
+    let items = vec![
+        (1, "眼影晕染要用松软的刷子".to_string()),
+        (2, "眼影晕染要用松软的刷子少量多次才不会脏".to_string()),
+        (3, "Python 装饰器的执行时机".to_string()),
+    ];
+    // Act
+    let pairs = find_merge_pairs(&items);
+    // Assert：一对（保留较长的 id=2，丢弃 id=1）；独立项不配对
+    assert_eq!(pairs.len(), 1);
+    assert_eq!(pairs[0], (2, 1));
+}
+
+#[test]
+fn merge_pairs_each_item_at_most_once() {
+    // Arrange：三条互相近似（防链式合并丢内容）
+    let items = vec![
+        (1, "化妆前要做好保湿打底".to_string()),
+        (2, "化妆前要做好保湿打底工作".to_string()),
+        (3, "化妆前要做好保湿打底步骤".to_string()),
+    ];
+    // Act
+    let pairs = find_merge_pairs(&items);
+    // Assert：贪心一对一——最多一对，第三条留待下轮结算
+    assert_eq!(pairs.len(), 1);
+}