feat(goal): v0.18.1 M2 后端——毕业报告快照/回顾流/毕业与放弃命令（REQ-255~257）

- goal_graduation_reports 快照表（FK SET NULL——目标删除后报告仍可读；goal_name 冗余）
- goal_retro 纯函数：毕业报告组装（里程碑/子组结算/复习统计/成果物清单）+
  回顾流时间线（四源现算：skipped 无发生时刻不造假事件）+ 纯文本摘要兜底
- goal_settle 守卫链：状态机（仅 active 可毕业）+ 判据（未全达标拒绝，明细回显）
  → 快照先行/状态归档/埋点 goal_graduated
- goal_abandon：active/paused→abandoned（终态拒绝）+ 可选原因（200 字，埋点审计）
- goal_retro / list_goal_graduations：时间线现算 + 毕业档案（已删目标仍可读）
- 修复：goal_settlements_snapshot 锁嵌套死锁（with_conn 内再调 self.*——禁重入先例）
- 测试：纯函数 golden 6 + 守卫矩阵/快照保留/埋点 7（34+19 全绿）

Author: Aparencia

app/src-tauri/src/commands_goals.rs

@@ -602,14 +602,14 @@ fn goal_card_metrics(db: &Db, goal: &Goal) -> Result<(String, f64, usize, usize,
     ))
 }
 
-/// 判据 JSON 解析（损坏 → 错误——调用方降级 ready=false；不静默空白）。
-fn parse_criteria(goal: &Goal) -> Result<SuccessCriteria, String> {
-    serde_json::from_str(&goal.success_criteria_json).map_err(|e| e.to_string())
+/// 进度信号收集（详情/列表共用——口径单一；lifecycle 命令组复用）。
+pub(crate) fn collect_signals(db: &Db, goal_id: i64) -> Result<GoalSignals, String> {
+    db.goal_progress_signals(goal_id, unix_seconds()).map_err(|e| e.to_string())
 }
 
-/// 进度信号收集（详情/列表共用——口径单一）。
-fn collect_signals(db: &Db, goal_id: i64) -> Result<GoalSignals, String> {
-    db.goal_progress_signals(goal_id, unix_seconds()).map_err(|e| e.to_string())
+/// 判据 JSON 解析（损坏 → 错误——调用方降级 ready=false；不静默空白）。
+pub(crate) fn parse_criteria(goal: &Goal) -> Result<SuccessCriteria, String> {
+    serde_json::from_str(&goal.success_criteria_json).map_err(|e| e.to_string())
 }
 
 /// ReadinessCheck → 客户端视图。

app/src-tauri/src/commands_goals_lifecycle.rs

@@ -0,0 +1,160 @@
+//! 学习目标生命周期 commands（v0.18.1 REQ-255~257；毕业仪式/回顾流/放弃/档案）。
+//!
+//! @ai-context: 拆自 commands_goals.rs（该文件逼近 600 硬限——M2 四命令组独立成域：
+//!              毕业仪式/回顾流/放弃/毕业档案）。毕业＝用户确认仪式：本层只做
+//!              守卫（判据未达标/重复毕业/终态拒绝）+ 组装报告快照 + 状态归档 +
+//!              埋点——纯函数组装在 goal_retro.rs，取数在 db_goals.rs。
+//! @ai-context: 报告快照独立于 goals 行（目标删除后仍可读——毕业档案区；
+//!              FK SET NULL 保历史，同 notes_versions「回滚不破坏历史」哲学）。
+
+use serde::Serialize;
+use tauri::State;
+
+use crate::commands::AppState;
+use crate::db::{unix_seconds, Db};
+use crate::goal_progress::{build_report, GoalProgressReport};
+use crate::goal_retro::{
+    assemble_report, assemble_retro, GraduationReport, MilestoneSnapshot, ReportSignals, RetroEntry,
+};
+use crate::goal_rules::{can_transition, graduation_readiness};
+use crate::goal_schema::{Goal, GOAL_ABANDONED, GOAL_GRADUATED};
+
+/// 放弃原因文本上限（可选原因——防超大 payload）。
+const ABANDON_REASON_MAX: usize = 200;
+
+/// 回顾流视图（时间线现算 + 毕业报告（如已毕业——快照永久保留））。
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GoalRetroView {
+    pub status: String,
+    pub entries: Vec<RetroEntry>,
+    pub graduation: Option<GraduationReport>,
+}
+
+/// 毕业仪式（goal_settle——信号达标 + 用户确认后执行）。
+#[tauri::command]
+pub fn goal_settle(state: State<'_, AppState>, id: i64) -> Result<GraduationReport, String> {
+    goal_settle_inner(&state.db, id)
+}
+
+/// 回顾流（创建→里程碑→组结算→毕业；全现算零双写）。
+#[tauri::command]
+pub fn goal_retro(state: State<'_, AppState>, id: i64) -> Result<GoalRetroView, String> {
+    goal_retro_inner(&state.db, id)
+}
+
+/// 放弃（显式动作 + 可选原因——无惩罚文案；终态拒绝）。
+#[tauri::command]
+pub fn goal_abandon(state: State<'_, AppState>, id: i64, reason: Option<String>) -> Result<bool, String> {
+    goal_abandon_inner(&state.db, id, reason.as_deref())
+}
+
+/// 毕业档案（全部报告——已删目标的报告仍在此处可读）。
+#[tauri::command]
+pub fn list_goal_graduations(state: State<'_, AppState>) -> Result<Vec<GraduationReport>, String> {
+    list_goal_graduations_inner(&state.db)
+}
+
+pub(crate) fn goal_settle_inner(db: &Db, id: i64) -> Result<GraduationReport, String> {
+    crate::commands_goals::require_goal(db, id)?;
+    let goal = db
+        .get_goal(id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| format!("目标不存在: {}", id))?;
+    // 守卫①：状态机——毕业仅从 active 发起（已毕业/放弃/暂停均拒绝）
+    if !can_transition(&goal.status, GOAL_GRADUATED) {
+        return Err(format!("非法毕业状态转移: {}（毕业仅从进行中发起）", goal.status));
+    }
+    // 守卫②：判据——未达标不可毕业（毕业确认仪式不豁免信号）
+    let progress: GoalProgressReport =
+        build_report(&crate::commands_goals::collect_signals(db, id)?);
+    let criteria = crate::commands_goals::parse_criteria(&goal)?;
+    let ready = graduation_readiness(&goal.status, &progress, &criteria);
+    if !ready.ready {
+        let missing: Vec<String> = ready
+            .checks
+            .iter()
+            .filter(|c| !c.met)
+            .map(|c| format!("{}（{}）", c.label, c.detail))
+            .collect();
+        return Err(format!("毕业判据未全部满足：{}", missing.join("；")));
+    }
+    // 组装报告快照（毕业后冻结）
+    let milestones: Vec<MilestoneSnapshot> = db
+        .list_milestones(id)
+        .map_err(|e| e.to_string())?
+        .into_iter()
+        .map(|m| MilestoneSnapshot { title: m.title, status: m.status, completed_at: m.completed_at })
+        .collect();
+    let report = assemble_report(ReportSignals {
+        goal_id: goal.id,
+        goal_name: goal.name.clone(),
+        graduated_at: unix_seconds(),
+        milestones,
+        group_settlements: db.goal_settlements_snapshot(id).map_err(|e| e.to_string())?,
+        review_stats: db.goal_review_stats(id, unix_seconds()).map_err(|e| e.to_string())?,
+        artifacts: db.goal_artifacts(id).map_err(|e| e.to_string())?,
+        criteria_statement: criteria.statement,
+    });
+    // 落库：快照（独立保留）→ 状态归档 → 埋点
+    let json = serde_json::to_string(&report).map_err(|e| e.to_string())?;
+    db.create_graduation_report(goal.id, &goal.name, &json).map_err(|e| e.to_string())?;
+    db.set_goal_status(goal.id, GOAL_GRADUATED).map_err(|e| e.to_string())?;
+    let payload = serde_json::json!({ "goalId": goal.id, "name": goal.name }).to_string();
+    let _ = db.add_metric_event("goal_graduated", &payload);
+    Ok(report)
+}
+
+pub(crate) fn goal_retro_inner(db: &Db, id: i64) -> Result<GoalRetroView, String> {
+    crate::commands_goals::require_goal(db, id)?;
+    let goal: Goal = db
+        .get_goal(id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| format!("目标不存在: {}", id))?;
+    let milestones: Vec<MilestoneSnapshot> = db
+        .list_milestones(id)
+        .map_err(|e| e.to_string())?
+        .into_iter()
+        .map(|m| MilestoneSnapshot { title: m.title, status: m.status, completed_at: m.completed_at })
+        .collect();
+    let settlements = db.goal_settlements_snapshot(id).map_err(|e| e.to_string())?;
+    let graduation = db
+        .get_graduation_report_json(id)
+        .map_err(|e| e.to_string())?
+        .map(|json| serde_json::from_str::<GraduationReport>(&json).map_err(|e| e.to_string()))
+        .transpose()?;
+    let entries = assemble_retro(goal.created_at, &milestones, &settlements, graduation.as_ref());
+    Ok(GoalRetroView { status: goal.status, entries, graduation })
+}
+
+pub(crate) fn goal_abandon_inner(db: &Db, id: i64, reason: Option<&str>) -> Result<bool, String> {
+    crate::commands_goals::require_goal(db, id)?;
+    let goal: Goal = db
+        .get_goal(id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| format!("目标不存在: {}", id))?;
+    // 守卫：active/paused → abandoned（终态拒绝——毕业/已放弃不可再放弃）
+    if !can_transition(&goal.status, GOAL_ABANDONED) {
+        return Err(format!("非法放弃状态转移: {}（进行中/已暂停可放弃；毕业/已放弃为终态）", goal.status));
+    }
+    let reason = reason.map(str::trim).filter(|r| !r.is_empty()).map(|r| {
+        r.chars().take(ABANDON_REASON_MAX).collect::<String>()
+    });
+    db.set_goal_status(goal.id, GOAL_ABANDONED).map_err(|e| e.to_string())?;
+    // 埋点：原因入 payload（可选；审计可查——无惩罚性状态，仅留痕）
+    let payload = serde_json::json!({ "goalId": goal.id, "reason": reason }).to_string();
+    let _ = db.add_metric_event("goal_abandoned", &payload);
+    Ok(true)
+}
+
+pub(crate) fn list_goal_graduations_inner(db: &Db) -> Result<Vec<GraduationReport>, String> {
+    let jsons = db.list_graduation_reports_json().map_err(|e| e.to_string())?;
+    jsons
+        .into_iter()
+        .map(|json| serde_json::from_str::<GraduationReport>(&json).map_err(|e| e.to_string()))
+        .collect()
+}
+
+#[cfg(test)]
+#[path = "commands_goals_lifecycle_tests.rs"]
+mod tests;

app/src-tauri/src/commands_goals_lifecycle_tests.rs

@@ -0,0 +1,163 @@
+//! commands_goals_lifecycle 单测（毕业仪式守卫矩阵/回顾流/放弃/档案——内存库）。
+
+use crate::commands_goals::{create_goal_inner, set_goal_milestone_status_inner, GoalCreateInput, GoalMilestoneInput};
+use crate::commands_goals_lifecycle::{
+    goal_abandon_inner, goal_retro_inner, goal_settle_inner, list_goal_graduations_inner,
+};
+use crate::db::Db;
+use crate::goal_schema::TIER_HANDS_ON;
+use crate::types::NewNoteGroup;
+
+fn mem_db() -> Db {
+    Db::open(":memory:").expect("内存库打开")
+}
+
+fn group(db: &Db, name: &str) -> i64 {
+    db.create_group(&NewNoteGroup {
+        name: name.to_string(),
+        terrain: "container".to_string(),
+        kind: "standalone".to_string(),
+        domain_tag: None,
+        source: "route".to_string(),
+        series_key: None,
+        route_reason: None,
+    })
+    .expect("建组")
+    .id
+}
+
+fn input(tier: Option<&str>, scenario: Option<&str>, group_ids: Vec<i64>) -> GoalCreateInput {
+    GoalCreateInput {
+        name: "学会 Python".to_string(),
+        domain_tag: Some("programming".to_string()),
+        horizon: Some("3m".to_string()),
+        tier: tier.map(str::to_string),
+        scenario: scenario.map(str::to_string),
+        level: Some("zero".to_string()),
+        driver: Some("work".to_string()),
+        criteria_statement: Some("能独立完成实例".to_string()),
+        non_scope: Some("不做 Web 框架".to_string()),
+        weekly_commitment: Some("5h+".to_string()),
+        obstacles: None,
+        group_ids,
+        milestones: vec![
+            GoalMilestoneInput { title: "基础".to_string(), due_weeks: 4 },
+            GoalMilestoneInput { title: "应用".to_string(), due_weeks: 8 },
+        ],
+    }
+}
+
+/// 达成毕业判据所需状态（hands_on：里程碑全 done + 组结算 1 次）。
+fn make_ready(db: &Db, goal_id: i64, gid: i64) {
+    db.create_settlement(gid, r#"{}"#).expect("结算");
+    for m in db.list_milestones(goal_id).expect("里程碑") {
+        set_goal_milestone_status_inner(db, m.id, "done").expect("完成");
+    }
+}
+
+#[test]
+fn settle_rejects_when_criteria_not_met() {
+    let db = mem_db();
+    let gid = group(&db, "组");
+    let goal = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景"), vec![gid])).expect("建");
+    // 未达标（里程碑 0/2）
+    let err = goal_settle_inner(&db, goal.id).expect_err("判据不足");
+    assert!(err.contains("毕业判据未全部满足"));
+    assert!(err.contains("里程碑"));
+    // 状态未被改动
+    assert_eq!(db.get_goal(goal.id).expect("读").unwrap().status, "active");
+}
+
+#[test]
+fn settle_guards_terminated_statuses() {
+    let db = mem_db();
+    let gid = group(&db, "组");
+    let goal = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景"), vec![gid])).expect("建");
+    make_ready(&db, goal.id, gid);
+    assert!(goal_settle_inner(&db, goal.id).expect("毕业").graduated_at > 0);
+    // 重复毕业：已毕业终态拒绝
+    let err = goal_settle_inner(&db, goal.id).expect_err("重复毕业");
+    assert!(err.contains("非法毕业状态转移"));
+    // 已放弃亦然
+    let g2 = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景2"), vec![])).expect("建2");
+    goal_abandon_inner(&db, g2.id, Some("没时间")).expect("放弃");
+    let err2 = goal_settle_inner(&db, g2.id).expect_err("放弃后毕业");
+    assert!(err2.contains("非法毕业状态转移"));
+}
+
+#[test]
+fn settle_writes_snapshot_and_graduated_status() {
+    let db = mem_db();
+    let gid = group(&db, "Python 组");
+    let goal = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景"), vec![gid])).expect("建");
+    db.create_settlement(gid, r#"{"merged":2}"#).expect("结算");
+    for m in db.list_milestones(goal.id).expect("里程碑") {
+        set_goal_milestone_status_inner(&db, m.id, "done").expect("完成");
+    }
+    let report = goal_settle_inner(&db, goal.id).expect("毕业");
+    assert_eq!(report.goal_name, "学会 Python");
+    assert_eq!(report.milestones.len(), 2);
+    assert_eq!(report.group_settlements[0].settlement_count, 1);
+    assert!(report.criteria_statement.contains("结算 1 次"), "配方语句：{}", report.criteria_statement);
+    let g = db.get_goal(goal.id).expect("读").unwrap();
+    assert_eq!(g.status, "graduated");
+    assert!(g.completed_at.is_some());
+    assert_eq!(db.count_metric_events("goal_graduated").expect("埋点"), 1);
+}
+
+#[test]
+fn graduation_report_survives_goal_delete() {
+    // 验收 5：毕业报告在目标删除后仍可读（快照独立于 goals 行——FK SET NULL）
+    let db = mem_db();
+    let gid = group(&db, "组");
+    let goal = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景"), vec![gid])).expect("建");
+    make_ready(&db, goal.id, gid);
+    goal_settle_inner(&db, goal.id).expect("毕业");
+    crate::commands_goals::delete_goal_inner(&db, goal.id).expect("删目标");
+    let archives = list_goal_graduations_inner(&db).expect("档案");
+    assert_eq!(archives.len(), 1, "目标删除后报告保留");
+    assert_eq!(archives[0].goal_id, goal.id, "快照保留原 goal_id（行链接 SET NULL）");
+    assert_eq!(archives[0].goal_name, "学会 Python");
+}
+
+#[test]
+fn retro_shows_timeline_with_graduation() {
+    let db = mem_db();
+    let gid = group(&db, "组");
+    let goal = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景"), vec![gid])).expect("建");
+    make_ready(&db, goal.id, gid);
+    goal_settle_inner(&db, goal.id).expect("毕业");
+    let view = goal_retro_inner(&db, goal.id).expect("回顾流");
+    assert!(view.graduation.is_some());
+    let kinds: Vec<&str> = view.entries.iter().map(|e| e.kind.as_str()).collect();
+    assert!(kinds.contains(&"created"));
+    assert!(kinds.contains(&"milestone"));
+    assert!(kinds.contains(&"settlement"));
+    assert!(kinds.contains(&"graduated"));
+    assert_eq!(view.status, "graduated");
+    // 未毕业目标：无 graduation 时间线节点
+    let g2 = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景2"), vec![])).expect("建2");
+    let v2 = goal_retro_inner(&db, g2.id).expect("回顾流2");
+    assert!(v2.graduation.is_none());
+    assert!(v2.entries.iter().all(|e| e.kind != "graduated"));
+}
+
+#[test]
+fn abandon_records_reason_and_guards() {
+    let db = mem_db();
+    let goal = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景"), vec![])).expect("建");
+    assert!(goal_abandon_inner(&db, goal.id, Some(" 转行，不学了 ")).expect("放弃"));
+    let g = db.get_goal(goal.id).expect("读").unwrap();
+    assert_eq!(g.status, "abandoned");
+    assert!(g.completed_at.is_some());
+    // 原因入埋点（审计可查）+ 超长截断 200
+    assert_eq!(db.count_metric_events("goal_abandoned").expect("埋点"), 1);
+    // 终态拒绝重复放弃
+    let err = goal_abandon_inner(&db, goal.id, None).expect_err("重复放弃");
+    assert!(err.contains("非法放弃状态转移"));
+    // 超长原因截断
+    let g2 = create_goal_inner(&db, &input(Some(TIER_HANDS_ON), Some("场景2"), vec![])).expect("建2");
+    let long = "长".repeat(300);
+    goal_abandon_inner(&db, g2.id, Some(&long)).expect("放弃2");
+    assert_eq!(db.count_metric_events("goal_abandoned").expect("埋点2"), 2);
+}