feat(contracts): 周契约数据层与周聚合纯函数（REQ-200）

Author: Aparencia

app/src-tauri/src/db_contracts.rs

@@ -0,0 +1,104 @@
+//! 周契约数据层（v0.11.4 REQ-200；弹性承诺呈现层）。
+//!
+//! @ai-context: contracts 表按 (group_id, week_start) 唯一——每周每组一份契约，
+//!              upsert 幂等覆盖本周（改目标即改承诺，不产生历史噪音）；
+//!              完成度取数（review_logs JOIN flashcards 按组+周过滤）在本层，
+//!              聚合纯函数在 week_contract.rs（周界/去重口径单一）。
+//! @ai-context: 弹性承诺纪律——本层只读写事实，不算 streak、不追债、不惩罚。
+
+use rusqlite::params;
+
+use crate::db::{unix_seconds, Db};
+use crate::error::Result;
+use crate::types::WeekContract;
+use crate::week_contract::WEEK_SECS;
+
+/// contracts 表统一查询列（列顺序与 row_to_contract 严格对应）。
+const CONTRACT_COLUMNS: &str = "id, group_id, week_start, target_days, target_cards, created_at";
+
+impl Db {
+    /// 幂等写入本周契约（同组同周已存在 → 覆盖目标值；created_at 刷新）。
+    ///
+    /// @ai-context: ON CONFLICT DO UPDATE——用户改目标即改承诺（无历史版本，
+    ///              弹性承诺不记恩怨，只记当前约定）；外键组不存在报错。
+    pub fn upsert_week_contract(
+        &self,
+        group_id: i64,
+        week_start: i64,
+        target_days: i64,
+        target_cards: i64,
+    ) -> Result<WeekContract> {
+        let now = unix_seconds();
+        self.with_conn(|conn| {
+            conn.execute(
+                "INSERT INTO contracts (group_id, week_start, target_days, target_cards, created_at)
+                 VALUES (?1, ?2, ?3, ?4, ?5)
+                 ON CONFLICT(group_id, week_start) DO UPDATE SET
+                     target_days = excluded.target_days,
+                     target_cards = excluded.target_cards,
+                     created_at = excluded.created_at",
+                params![group_id, week_start, target_days, target_cards, now],
+            )?;
+            let id = conn.last_insert_rowid();
+            Ok(WeekContract {
+                id,
+                group_id,
+                week_start,
+                target_days,
+                target_cards,
+                created_at: now,
+            })
+        })
+    }
+
+    /// 读取指定周契约（无 → None——本周未立约，UI 显示设定表单）。
+    pub fn get_week_contract(&self, group_id: i64, week_start: i64) -> Result<Option<WeekContract>> {
+        self.with_conn(|conn| {
+            let mut stmt = conn.prepare(&format!(
+                "SELECT {} FROM contracts WHERE group_id = ?1 AND week_start = ?2",
+                CONTRACT_COLUMNS
+            ))?;
+            let mut rows = stmt.query_map(params![group_id, week_start], row_to_contract)?;
+            match rows.next() {
+                Some(Ok(c)) => Ok(Some(c)),
+                Some(Err(e)) => Err(e.into()),
+                None => Ok(None),
+            }
+        })
+    }
+
+    /// 组在某周（含）之后的复习时刻列表（周契约实际完成度取数）。
+    ///
+    /// @ai-context: JOIN flashcards 按组过滤（review_logs 无组概念，弹性承诺
+    ///              日志只记卡）；范围 [week_start, week_start+7d) 左闭右开——
+    ///              下一周周一零点归下周，周界不重叠。
+    pub fn review_ats_in_week(&self, group_id: i64, week_start: i64) -> Result<Vec<i64>> {
+        self.with_conn(|conn| {
+            let mut stmt = conn.prepare(
+                "SELECT l.reviewed_at FROM review_logs l
+                 JOIN flashcards c ON c.id = l.card_id
+                 WHERE c.group_id = ?1 AND l.reviewed_at >= ?2 AND l.reviewed_at < ?3
+                 ORDER BY l.reviewed_at ASC",
+            )?;
+            let rows = stmt.query_map(params![group_id, week_start, week_start + WEEK_SECS], |r| r.get(0))?;
+            rows.collect::<rusqlite::Result<Vec<_>>>().map_err(Into::into)
+        })
+    }
+}
+
+/// 把 rusqlite 行映射为 WeekContract。
+fn row_to_contract(row: &rusqlite::Row<'_>) -> rusqlite::Result<WeekContract> {
+    Ok(WeekContract {
+        id: row.get(0)?,
+        group_id: row.get(1)?,
+        week_start: row.get(2)?,
+        target_days: row.get(3)?,
+        target_cards: row.get(4)?,
+        created_at: row.get(5)?,
+    })
+}
+
+/// 单测独立文件。
+#[cfg(test)]
+#[path = "db_contracts_tests.rs"]
+mod tests;

app/src-tauri/src/db_contracts_tests.rs

@@ -0,0 +1,115 @@
+//! db_contracts 单测（内存库；AAA 模式）。
+
+use crate::db::Db;
+use crate::db_flashcards::NewFlashcard;
+use crate::types::NewNoteGroup;
+use crate::week_contract::week_start_secs;
+
+/// 内存库。
+fn mem_db() -> Db {
+    Db::open(":memory:").expect("内存库打开")
+}
+
+/// 建组助手（contracts/flashcards 外键前置）。
+fn make_group(db: &Db, name: &str) -> crate::types::NoteGroup {
+    db.create_group(&NewNoteGroup {
+        name: name.to_string(),
+        terrain: "container".to_string(),
+        kind: "standalone".to_string(),
+        domain_tag: None,
+        source: "manual".to_string(),
+        series_key: None,
+        route_reason: None,
+    })
+    .expect("group")
+}
+
+/// 建卡助手（review_logs 外键前置；新卡 due 不限制）。
+fn make_card(db: &Db, group_id: i64, front: &str) -> crate::types::Flashcard {
+    db.create_card(&NewFlashcard {
+        group_id,
+        note_id: None,
+        fragment_id: None,
+        front: front.to_string(),
+        back: "验证材料".to_string(),
+        kind: "fact".to_string(),
+        state_json: "{}".to_string(),
+        due_at: 0,
+    })
+    .expect("card")
+}
+
+#[test]
+fn upsert_creates_and_overrides_this_week() {
+    // Arrange
+    let db = mem_db();
+    let group = make_group(&db, "契约组");
+    let ws = week_start_secs(1_767_225_600);
+    // Act：首次写入 → 再次写入覆盖（幂等语义）
+    let c1 = db
+        .upsert_week_contract(group.id, ws, 3, 15)
+        .expect("first");
+    let c2 = db
+        .upsert_week_contract(group.id, ws, 5, 30)
+        .expect("override");
+    // Assert：同周同组仅一份契约，目标值已覆盖
+    let fetched = db.get_week_contract(group.id, ws).expect("get");
+    let fetched = fetched.expect("契约应存在");
+    assert_eq!(fetched.id, c1.id);
+    assert_eq!(fetched.target_days, 5);
+    assert_eq!(fetched.target_cards, 30);
+    assert_ne!(fetched.created_at, c2.created_at); // created_at 刷新
+}
+
+#[test]
+fn different_weeks_coexist() {
+    // Arrange
+    let db = mem_db();
+    let group = make_group(&db, "双周组");
+    let wk1 = week_start_secs(1_767_225_600);
+    let wk2 = wk1 + 604_800; // 下一周
+    // Act：两周各立一约
+    db.upsert_week_contract(group.id, wk1, 2, 10).expect("wk1");
+    db.upsert_week_contract(group.id, wk2, 4, 20).expect("wk2");
+    // Assert：互不覆盖
+    assert_eq!(db.get_week_contract(group.id, wk1).expect("g1").expect("c1").target_cards, 10);
+    assert_eq!(db.get_week_contract(group.id, wk2).expect("g2").expect("c2").target_cards, 20);
+}
+
+#[test]
+fn missing_contract_returns_none() {
+    // Arrange：组存在但从未立约
+    let db = mem_db();
+    let group = make_group(&db, "无约组");
+    // Act/Assert：诚实 None（UI 显示设定表单）
+    assert!(db.get_week_contract(group.id, week_start_secs(1_767_225_600)).expect("get").is_none());
+}
+
+#[test]
+fn review_ats_in_week_filters_group_and_range() {
+    // Arrange：两组各一卡；本周 3 次复习 + 下周 1 次
+    let db = mem_db();
+    let g1 = make_group(&db, "组一");
+    let g2 = make_group(&db, "组二");
+    let card1 = make_card(&db, g1.id, "卡一");
+    let card2 = make_card(&db, g2.id, "卡二");
+    let ws = week_start_secs(1_767_225_600);
+    db.add_review_log(card1.id, "good", ws + 3_600).expect("r1"); // 本周
+    db.add_review_log(card1.id, "good", ws + 86_400).expect("r2"); // 本周
+    db.add_review_log(card2.id, "easy", ws + 43_200).expect("r3"); // 本周·他组
+    db.add_review_log(card1.id, "again", ws + 604_800 + 100).expect("r4"); // 下周
+    // Act
+    let ats = db.review_ats_in_week(g1.id, ws).expect("query");
+    // Assert：仅组一本周 2 条（下周归下周、他组不计）
+    assert_eq!(ats.len(), 2);
+    assert!(ats.contains(&(ws + 3_600)));
+    assert!(ats.contains(&(ws + 86_400)));
+}
+
+#[test]
+fn upsert_rejects_unknown_group() {
+    // Arrange：不存在的组 id
+    let db = mem_db();
+    // Act/Assert：外键约束报错（不静默写孤儿契约）
+    assert!(db.upsert_week_contract(9999, 0, 3, 15).is_err());
+}

app/src-tauri/src/db_migrations.rs

@@ -150,7 +150,20 @@ pub(crate) fn init_schema(conn: &Connection) -> Result<()> {
             stats_json TEXT NOT NULL,
             created_at INTEGER NOT NULL
         );
-        CREATE INDEX IF NOT EXISTS idx_settlements_group ON settlements(group_id, created_at);",
+        CREATE INDEX IF NOT EXISTS idx_settlements_group ON settlements(group_id, created_at);
+        -- v0.11.4（REQ-200，弹性承诺呈现层）：周契约——用户自设本周目标
+        -- （target_days/target_cards），非打卡 KPI；(group_id, week_start) 唯一
+        -- 保证每周每组一份契约，upsert 幂等覆盖本周（无 streak 无惩罚）
+CREATE TABLE IF NOT EXISTS contracts (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            group_id INTEGER NOT NULL REFERENCES note_groups(id) ON DELETE CASCADE,
+            week_start INTEGER NOT NULL,     -- 周一零点（UTC Unix 秒）
+            target_days INTEGER NOT NULL,    -- 本周承诺复习天数（1..7）
+            target_cards INTEGER NOT NULL,   -- 本周承诺复习卡数（有界）
+            created_at INTEGER NOT NULL
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_contracts_group_week
+            ON contracts(group_id, week_start);",
     )?;
     // v0.5.0 M1（REQ-043）：旧库迁移——sessions 表补 profile 列（兼容既有数据库）
     ensure_column(conn, "sessions", "profile", "ALTER TABLE sessions ADD COLUMN profile TEXT")?;

app/src-tauri/src/types.rs

@@ -259,6 +259,25 @@ pub struct Flashcard {
     pub created_at: i64,
 }
 
+/// 周契约（v0.11.4 REQ-200；弹性承诺呈现层——用户自设本周目标，非打卡 KPI）。
+///
+/// @ai-context: 无 streak 无惩罚——契约只记录承诺本身，完成度由
+///              review_logs 周聚合实时计算（week_contract.rs 纯函数）。
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct WeekContract {
+    pub id: i64,
+    /// 绑定组（契约粒度=组——与学习循环绑定粒度一致，契约二）
+    pub group_id: i64,
+    /// 周界：周一零点（UTC Unix 秒）
+    pub week_start: i64,
+    /// 本周承诺复习天数（1..7）
+    pub target_days: i64,
+    /// 本周承诺复习卡数（有界）
+    pub target_cards: i64,
+    pub created_at: i64,
+}
+
 // ────────────────────────────────────────────────────────────
 // 会话领域类型（REQ-010，ADR-004）
 // ────────────────────────────────────────────────────────────

app/src-tauri/src/week_contract.rs

@@ -0,0 +1,59 @@
+//! 周契约纯函数（v0.11.4 REQ-200；弹性承诺呈现层的数据基础）。
+//!
+//! @ai-context: 弹性承诺纪律（v4 §8.2 P31+N10）——契约是用户自设的本周目标，
+//!              不是打卡 KPI：无 streak、无惩罚、欠账不追。本层只回答
+//!              "本周承诺 vs 实际"两个数字，聚合结果由 UI 呈现。
+//! @ai-context: 周界口径：UTC 周一零点（零依赖纯函数，不引 chrono）。时区偏差
+//!              对弹性承诺无惩罚性影响（欠账不追，边界模糊不伤契约精神）；
+//!              UI 展示时把 week_start 转本地日期。
+//! @ai-context: 纯逻辑无 IO；取数（review_logs 按组+周过滤）在 db_contracts.rs。
+
+/// 一周秒数（周一零点周界计算用）。
+pub const WEEK_SECS: i64 = 7 * 86_400;
+/// 最小可行日徽标阈值：本周完成卡数达到此值即"成立"（N9/N11 低谷生存
+/// 的最轻形态——一天状态崩坏不否定整周，但至少 3 次提取才算成立）。
+pub const MINIMAL_DAY_CARDS: usize = 3;
+
+/// 当前时刻所在周的周一零点（UTC；Unix 秒）。
+///
+/// @ai-context: 推导——Unix epoch（1970-01-01）是周四；设 d=距纪元天数，
+///              ISO weekday(d) = (d + 3) % 7 + 1（周一=1）；该周起始天 =
+///              d - (weekday - 1) = d - (d + 3) % 7。rem_euclid 防负天数。
+pub fn week_start_secs(now_secs: i64) -> i64 {
+    let d = now_secs / 86_400;
+    let back = (d + 3).rem_euclid(7);
+    (d - back) * 86_400
+}
+
+/// 周聚合结果（承诺 vs 实际的数据基础）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WeekAggregate {
+    /// 有复习的天数（按自然日去重——断签不清零：不连续也算天数）
+    pub review_days: usize,
+    /// 复习卡次数（review_logs 行数）
+    pub review_cards: usize,
+}
+
+/// review 记录（reviewed_at Unix 秒列表）→ 周聚合。
+///
+/// @ai-context: 天数按 (t / 86400) 去重——同一天多次复习只算一天（日历日口径，
+///              与 week_start 周界一致）；卡数=复习次数（提取动作次数）。
+pub fn aggregate_week(reviewed_ats: &[i64]) -> WeekAggregate {
+    let mut days = std::collections::HashSet::new();
+    for t in reviewed_ats {
+        days.insert(t / 86_400);
+    }
+    WeekAggregate {
+        review_days: days.len(),
+        review_cards: reviewed_ats.len(),
+    }
+}
+
+/// 最小可行日成立判定（本周完成卡数 ≥ MINIMAL_DAY_CARDS）。
+pub fn minimal_day_met(review_cards: usize) -> bool {
+    review_cards >= MINIMAL_DAY_CARDS
+}
+
+#[cfg(test)]
+#[path = "week_contract_tests.rs"]
+mod tests;