feat(ai): v0.8.0 M4 笔记版本管理+成本完整——快照链/回滚/diff/时间线/落库 (REQ-144+143)

Author: Aparencia

CHANGELOG.md

@@ -3,7 +3,20 @@
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与 [SemVer](https://semver.org/lang/zh-CN/)。
 各版本的深度版本文档见 [docs/versions/](docs/versions/)。
 
-## [0.8.0] - 2026-08（AI 接入，M1/M2/M3 开发中）
+## [0.8.0] - 2026-08（AI 接入，M1/M2/M3/M4 开发中）
+
+### 新增（M4 版本管理与成本完整，REQ-144 + REQ-143 完整）
+
+- **notes_versions 快照链（REQ-144）**：`(id, note_id, content, source: rule|ai-refine|ai-enrich|user-edit, parent_id, created_at, meta{成本/模型/切片/合并摘要})`；旧数据迁移兼容（旧笔记首快照=当前内容，惰性创建）；**统一 versioned 写路径**——转笔记（首快照）/精修采纳/补充采纳/手动保存（update_note）/回滚全部走 versioned_save（事务：更新 notes + 插入快照 + 上限合并）
+- **50 版上限**：超限合并最旧两版（删最旧 + 次旧 meta 追加 merged_from 摘要——meta 不丢）
+- **回滚不破坏历史链**：回滚=新版本（content=目标版本，source=user-edit，parent=最新版本——线性链语义，规划"parent=目标版本"会制造分叉故取线性，见 v0.8.0.md M4 注记）
+- **任意两版段级 diff**：`note_versions_diff` 复用 note_diff 内核（版本对比视图高亮）
+- **成本落库（REQ-143 完整）**：`note_ai_usage` 表（操作类型/token 输入输出/费用/模型/切片数）——精修/补充采纳时自动落库（token 估算与预估同口径，校准单价表数据源）
+- **版本时间线 UI**：笔记详情页「🕘 版本时间线」面板——版本列表（时间/source 徽标/费用/合并摘要）+ 回滚到此处 + 两版 diff 对比（下拉选择）+ AI 成本记录
+
+### 测试
+
+- 单测 +11（全量 1264 通过）：来源标记 serde/label · meta 合并摘要（含/不含 AI 元信息）· 惰性首快照（旧数据兼容）· versioned 写链（rule 基快照 + ai-refine 新版本 + parent 链）· 回滚不破坏历史链（3 条）· 50 版上限合并（merged_from 摘要）· 成本记录 roundtrip/互不干扰 · 缺失笔记拒绝
 
 ### 新增（M3 知识补充，REQ-142）
 

app/src-tauri/src/ai_cost.rs

@@ -57,6 +57,12 @@ pub fn estimate_for_content(chars: usize) -> CostEstimate {
     }
 }
 
+/// 成本记录费用（纯函数：输入+输出 token × 当前单价——与预估同口径，
+/// M4 落库 note_ai_usage 用）。
+pub fn usage_cost(tokens_in: usize, tokens_out: usize) -> f64 {
+    estimate_cost(tokens_in.saturating_add(tokens_out), price_per_1m())
+}
+
 /// 单测独立文件（保持本文件 ≤300 行，AGENTS.md §3）。
 #[cfg(test)]
 #[path = "ai_cost_tests.rs"]

app/src-tauri/src/commands.rs

@@ -300,6 +300,8 @@ pub async fn get_note(state: State<'_, AppState>, id: i64) -> Result<Option<Note
 }
 
 /// 更新笔记（REQ-004；标题/正文截断防超大 payload——TD-005）。
+/// v0.8.0 M4（REQ-144）：手动保存 = 新版本（versioned_save 统一写路径——
+/// 正文版本化，标题只更新不建版本；"重新生成"从覆盖变为新版本）。
 #[tauri::command]
 pub async fn update_note(
     state: State<'_, AppState>,
@@ -310,14 +312,22 @@ pub async fn update_note(
     if id <= 0 {
         return Err("无效的笔记 id".to_string());
     }
+    let title = truncate_chars(title, TITLE_MAX_CHARS);
+    let content = truncate_chars(content, CONTENT_MAX_CHARS);
     state
         .db
-        .update_note(
+        .versioned_save(
             id,
-            &truncate_chars(title, TITLE_MAX_CHARS),
-            &truncate_chars(content, CONTENT_MAX_CHARS),
+            &content,
+            crate::note_version::NoteVersionSource::UserEdit,
+            &crate::note_version::VersionMeta::default(),
         )
-        .map_err(|e| e.to_string())
+        .map_err(|e| e.to_string())?;
+    state
+        .db
+        .update_note(id, &title, &content)
+        .map_err(|e| e.to_string())?;
+    Ok(true)
 }
 
 /// 删除笔记（REQ-004）。

app/src-tauri/src/commands_ai_enrich.rs

@@ -43,6 +43,8 @@ pub struct AiEnrichResult {
     pub blocks: usize,
     pub depth_blocks: usize,
     pub breadth_blocks: usize,
+    /// 切片数（长笔记任务执行时的切片数——成本记录用）
+    pub slices: usize,
     /// 实际返回的子项（kebab-case）
     pub kinds: Vec<String>,
     pub model: String,
@@ -110,32 +112,68 @@ pub fn ai_enrich_result(state: State<'_, AppState>, task_id: u64) -> Result<AiEn
     }
 }
 
-/// 采纳落库（update_note 覆盖内容——M4 版本管理统一 versioned 写路径）。
+/// 采纳落库（v0.8.0 M4 版本化写路径：新版本 ai-enrich + 成本 meta +
+/// note_ai_usage 落库——"重新生成"从覆盖变为新版本）。
 #[tauri::command]
 pub fn ai_enrich_apply(
     state: State<'_, AppState>,
     note_id: i64,
-    enriched_markdown: String,
+    result: AiEnrichResult,
 ) -> Result<Note, String> {
-    let note = get_note(state.inner(), note_id)?;
+    // 存在性校验（versioned_save 内部也会校验——提前失败给明确错误）
+    get_note(state.inner(), note_id)?;
+    let cost = crate::ai_cost::usage_cost(
+        result.base_markdown.chars().count(),
+        result.enriched_markdown.chars().count(),
+    );
+    let meta = crate::note_version::VersionMeta {
+        cost_yuan: Some(cost),
+        model: Some(result.model.clone()),
+        slices: Some(result.slices),
+        merged_from: None,
+    };
+    state
+        .db
+        .versioned_save(
+            note_id,
+            &result.enriched_markdown,
+            crate::note_version::NoteVersionSource::AiEnrich,
+            &meta,
+        )
+        .map_err(|e| e.to_string())?;
     state
         .db
-        .update_note(note_id, &note.title, &enriched_markdown)
+        .record_ai_usage(
+            note_id,
+            &crate::db_ai_usage::AiUsageInput {
+                op_type: "enrich",
+                tokens_in: result.base_markdown.chars().count(),
+                tokens_out: result.enriched_markdown.chars().count(),
+                cost_yuan: cost,
+                model: result.model.clone(),
+                slices: result.slices,
+            },
+        )
         .map_err(|e| e.to_string())?;
     get_note(state.inner(), note_id)
 }
 
-/// 撤销补充（删除无残留——内容还原补充前 base）。
+/// 撤销补充（删除无残留——内容还原补充前 base；v0.8.0 M4：= 新版本 user_edit）。
 #[tauri::command]
 pub fn ai_enrich_revert(
     state: State<'_, AppState>,
     note_id: i64,
     base_markdown: String,
 ) -> Result<Note, String> {
-    let note = get_note(state.inner(), note_id)?;
+    get_note(state.inner(), note_id)?;
     state
         .db
-        .update_note(note_id, &note.title, &base_markdown)
+        .versioned_save(
+            note_id,
+            &base_markdown,
+            crate::note_version::NoteVersionSource::UserEdit,
+            &crate::note_version::VersionMeta::default(),
+        )
         .map_err(|e| e.to_string())?;
     get_note(state.inner(), note_id)
 }
@@ -204,6 +242,7 @@ fn run_enrich_task(st: AppState, task_id: u64, note_id: i64, selected: Vec<AiEnr
             blocks: resp.blocks.len(),
             depth_blocks: depth,
             breadth_blocks: breadth,
+            slices: total,
             kinds,
             model: client.config.model,
         })

app/src-tauri/src/commands_ai_refine.rs

@@ -52,6 +52,8 @@ pub struct AiTaskEntry {
 #[serde(rename_all = "camelCase")]
 pub struct AiRefineResult {
     pub title: String,
+    /// 规则基线（本地规则版——采纳落库时作为首快照，版本链 [rule, ai-refine]）
+    pub base_markdown: String,
     pub refined_markdown: String,
     /// 与规则版的段级 diff（本地版为基线，AI 变化点高亮）
     pub diff: Vec<DiffOp>,
@@ -161,14 +163,14 @@ pub fn ai_refine_result(state: State<'_, AppState>, task_id: u64) -> Result<AiRe
     }
 }
 
-/// 采纳落库（REQ-141：diff 预览后用户采纳 → 新笔记，source=classroom；
-/// M4 版本管理上线后统一 versioned 写路径）。
+/// 采纳落库（REQ-141：diff 预览后用户采纳；v0.8.0 M4 版本化写路径——
+/// ① 以规则基线建笔记（首快照）→ ② 精修版 = 新版本（ai-refine，含成本
+/// meta）→ ③ 成本落库 note_ai_usage）。
 #[tauri::command]
 pub fn ai_refine_apply(
     state: State<'_, AppState>,
     session_id: i64,
-    refined_markdown: String,
-    title: String,
+    result: AiRefineResult,
 ) -> Result<Note, String> {
     if session_id <= 0 {
         return Err("无效的会话 id".to_string());
@@ -179,16 +181,57 @@ pub fn ai_refine_apply(
         .map_err(|e| e.to_string())?
         .ok_or_else(|| format!("会话不存在: {}", session_id))?;
     let fallback = format!("{}（AI 精修）", session.title);
-    let title = crate::commands::normalize_title(title, &fallback);
+    let title = crate::commands::normalize_title(result.title.clone(), &fallback);
+    // ① 规则基线建笔记（版本链首快照原料——可回溯精修前内容）
     let new = NewNote {
-        title,
-        content: refined_markdown,
+        title: title.clone(),
+        content: result.base_markdown.clone(),
         source: "classroom".to_string(),
         session_id: Some(session_id),
-        rule_version: Some("ai-refine".to_string()),
+        rule_version: Some("rule".to_string()),
         purify_stats: None,
     };
-    state.db.create_note(&new).map_err(|e| e.to_string())
+    let note = state.db.create_note(&new).map_err(|e| e.to_string())?;
+    // ② 精修版落库（新版本 ai-refine + 成本 meta）
+    let cost = crate::ai_cost::usage_cost(
+        result.base_markdown.chars().count(),
+        result.refined_markdown.chars().count(),
+    );
+    let meta = crate::note_version::VersionMeta {
+        cost_yuan: Some(cost),
+        model: Some(result.model.clone()),
+        slices: Some(result.slices),
+        merged_from: None,
+    };
+    state
+        .db
+        .versioned_save(
+            note.id,
+            &result.refined_markdown,
+            crate::note_version::NoteVersionSource::AiRefine,
+            &meta,
+        )
+        .map_err(|e| e.to_string())?;
+    // ③ 成本落库（token 估算与预估同口径——校准单价表数据源）
+    state
+        .db
+        .record_ai_usage(
+            note.id,
+            &crate::db_ai_usage::AiUsageInput {
+                op_type: "refine",
+                tokens_in: result.base_markdown.chars().count(),
+                tokens_out: result.refined_markdown.chars().count(),
+                cost_yuan: cost,
+                model: result.model.clone(),
+                slices: result.slices,
+            },
+        )
+        .map_err(|e| e.to_string())?;
+    state
+        .db
+        .get_note(note.id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| "笔记不存在".to_string())
 }
 
 // ────────────────────────────────────────────────────────────
@@ -275,6 +318,7 @@ fn run_refine_task(st: AppState, task_id: u64, session_id: i64, mock: bool) {
         let (added, removed, _) = diff_stats(&diff);
         Ok(AiRefineResult {
             title: draft.title.clone(),
+            base_markdown: draft.markdown.clone(),
             refined_markdown: refined,
             diff,
             added_lines: added,

app/src-tauri/src/commands_notes_version.rs

@@ -0,0 +1,80 @@
+//! 笔记版本管理 commands（REQ-144 + REQ-143 成本展示，v0.8.0 M4）。
+//!
+//! @ai-context: 版本时间线数据源（list/diff/rollback）+ 成本记录展示；
+//!              写路径统一走 versioned_save（转笔记首快照惰性/精修采纳/
+//!              补充采纳/手动保存/回滚=新版本——见 db_notes_versions.rs）。
+//! @ai-context: 段级 diff 复用 note_diff.rs（M2 预览内核——任意两版对比）；
+//!              回滚不破坏历史链（新版本 parent=目标版本）。
+
+use tauri::State;
+
+use crate::commands::AppState;
+use crate::db_ai_usage::AiUsageRecord;
+use crate::db_notes_versions::NoteVersion;
+use crate::note_diff::{diff_markdown, DiffOp};
+use crate::types::Note;
+
+/// 版本列表（旧→新；含惰性首快照——旧数据迁移兼容）。
+#[tauri::command]
+pub fn note_versions_list(state: State<'_, AppState>, note_id: i64) -> Result<Vec<NoteVersion>, String> {
+    if note_id <= 0 {
+        return Err("无效的笔记 id".to_string());
+    }
+    state.db.list_versions(note_id).map_err(|e| e.to_string())
+}
+
+/// 任意两版段级 diff（版本对比视图数据源——note_diff 内核）。
+#[tauri::command]
+pub fn note_versions_diff(
+    state: State<'_, AppState>,
+    note_id: i64,
+    v1_id: i64,
+    v2_id: i64,
+) -> Result<Vec<DiffOp>, String> {
+    let v1 = get_version_for_note(&state, note_id, v1_id)?;
+    let v2 = get_version_for_note(&state, note_id, v2_id)?;
+    Ok(diff_markdown(&v1.content, &v2.content))
+}
+
+/// 回滚到目标版本（新版本 user_edit，parent=目标版本——历史链不破坏）。
+#[tauri::command]
+pub fn note_versions_rollback(
+    state: State<'_, AppState>,
+    note_id: i64,
+    target_version_id: i64,
+) -> Result<Note, String> {
+    if note_id <= 0 || target_version_id <= 0 {
+        return Err("无效的参数".to_string());
+    }
+    state
+        .db
+        .rollback_to(note_id, target_version_id)
+        .map_err(|e| e.to_string())?;
+    state
+        .db
+        .get_note(note_id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| "笔记不存在".to_string())
+}
+
+/// 笔记成本记录（版本时间线"费用"列数据源）。
+#[tauri::command]
+pub fn note_versions_usage(state: State<'_, AppState>, note_id: i64) -> Result<Vec<AiUsageRecord>, String> {
+    if note_id <= 0 {
+        return Err("无效的笔记 id".to_string());
+    }
+    state.db.list_ai_usage(note_id).map_err(|e| e.to_string())
+}
+
+/// 读版本并校验归属（diff 输入防御）。
+fn get_version_for_note(state: &AppState, note_id: i64, version_id: i64) -> Result<NoteVersion, String> {
+    let v = state
+        .db
+        .get_version(version_id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| format!("版本不存在: {}", version_id))?;
+    if v.note_id != note_id {
+        return Err("版本与笔记不匹配".to_string());
+    }
+    Ok(v)
+}

app/src-tauri/src/db.rs

@@ -175,6 +175,9 @@ impl Db {
         conn.execute_batch("CREATE INDEX IF NOT EXISTS idx_notes_session ON notes(session_id)")?;
         // v0.7.7（REQ-183）：结构图记录表（建表幂等——新库建表/旧库补表）
         crate::db_structures::init(&conn)?;
+        // v0.8.0 M4（REQ-144）：笔记版本快照链 + AI 成本记录（幂等建表）
+        crate::db_notes_versions::init(&conn)?;
+        crate::db_ai_usage::init(&conn)?;
         Ok(Self { conn: Arc::new(Mutex::new(conn)) })
     }