@@ -93,6 +93,54 @@ pub fn generate_group_cards(state: State<'_, AppState>, group_id: i64) -> Result
     Ok(generated)
 }
 
+/// 碎片升为闪卡（v0.12.2 收件箱动线；REQ-201 升级出口——复用多句卡生成规则）。
+///
+/// @ai-context: 幂等（可重复触发）——已为该碎片生成过卡返回 0 不重产；单句
+///              碎片诚实不出卡（card_from_fragment 内门控，返回 0）；卡绑定
+///              碎片所在组（flashcards.group_id NOT NULL）——未归组碎片无卡
+///              可挂，返回明确错误引导先归组/升笔记（碎片归属=卡分组依据）。
+#[tauri::command]
+pub fn promote_fragment_to_card(state: State<'_, AppState>, fragment_id: i64) -> Result<usize, String> {
+    crate::commands_fragments::require_feed_enabled(&state)?;
+    if fragment_id <= 0 {
+        return Err("无效的碎片 id".to_string());
+    }
+    let frag = state
+        .db
+        .get_fragment(fragment_id)
+        .map_err(|e| e.to_string())?
+        .ok_or_else(|| format!("碎片不存在: {}", fragment_id))?;
+    let Some(group_id) = frag.group_id else {
+        return Err("碎片未归组，不能升闪卡——请先移入组或升为笔记".to_string());
+    };
+    // 幂等：已升级过（同碎片已有卡）→ 0（不报错，可重复触发）
+    if state.db.card_by_fragment(fragment_id).map_err(|e| e.to_string())?.is_some() {
+        return Ok(0);
+    }
+    let Some(cand) = card_from_fragment(&frag.text) else {
+        return Ok(0); // 单句碎片无卡可出（card_generate 门控——诚实不出卡）
+    };
+    let now = now_ms();
+    let new_state = serde_json::to_string(&CardState::default()).unwrap_or_default();
+    state
+        .db
+        .create_card(&NewFlashcard {
+            group_id,
+            note_id: None,
+            fragment_id: Some(frag.id),
+            front: cand.front,
+            back: cand.back,
+            kind: cand.kind.clone(),
+            state_json: new_state,
+            due_at: now as i64,
+        })
+        .map_err(|e| e.to_string())?;
+    // 碎片升级率埋点（与 generate_group_cards 同口径——Phase 4 门控判据）
+    let payload = serde_json::json!({ "fragmentId": frag.id, "groupId": group_id }).to_string();
+    let _ = state.db.add_metric_event("fragment_upgraded", &payload);
+    Ok(1)
+}
+
 /// 到期复习队列（组过滤可选；到期最紧在前）。
 #[tauri::command]
 pub fn list_due_cards(
 
@@ -10,7 +10,7 @@ use tauri::State;
 
 use crate::commands::AppState;
 use crate::db_fragments::NewFragment;
-use crate::types::{Fragment, NewNoteGroup};
+use crate::types::{Fragment, NewNoteGroup, Note};
 use crate::video_profile_domain::{detect_domain, DomainSignals};
 
 /// 碎片文本最大长度（防超大 payload 拖垮 IPC/DB；几句话的碎片远用不到）。
@@ -186,6 +186,46 @@ pub fn delete_fragment(state: State<'_, AppState>, fragment_id: i64) -> Result<b
     state.db.delete_fragment(fragment_id).map_err(|e| e.to_string())
 }
 
+/// 碎片升为笔记（v0.12.2 收件箱动线：原料→沉淀；REQ-201 补升级出口）。
+///
+/// @ai-context: 事务在数据层（建笔记+删碎片原子——promote_fragment_to_note）；
+///              本层只做入参校验：标题必填（前端预填首句可改，后端拒绝空串）、
+///              组存在性校验、开关准入（升笔记是碎片生命周期操作，feed 能力
+///              对称纪律）。图随碎片搬运进 notes-images/（失败降级纯文本）。
+#[tauri::command]
+pub fn promote_fragment_to_note(
+    state: State<'_, AppState>,
+    fragment_id: i64,
+    title: String,
+    group_id: Option<i64>,
+) -> Result<Note, String> {
+    require_feed_enabled(&state)?;
+    if fragment_id <= 0 {
+        return Err("无效的碎片 id".to_string());
+    }
+    // 标题必填（二元论裁决：升笔记需要标题——前端预填首句，后端兜底拒绝）
+    let title_trim = title.trim();
+    if title_trim.is_empty() {
+        return Err("笔记标题不能为空".to_string());
+    }
+    let title = crate::commands::normalize_title(title, "碎片笔记");
+    if state.db.get_fragment(fragment_id).map_err(|e| e.to_string())?.is_none() {
+        return Err(format!("碎片不存在: {}", fragment_id));
+    }
+    if let Some(gid) = group_id {
+        if gid <= 0 {
+            return Err("无效的组 id".to_string());
+        }
+        if state.db.get_group(gid).map_err(|e| e.to_string())?.is_none() {
+            return Err(format!("笔记组不存在: {}", gid));
+        }
+    }
+    state
+        .db
+        .promote_fragment_to_note(&state.data_dir, fragment_id, &title, group_id)
+        .map_err(|e| e.to_string())
+}
+
 /// 碎片图片 → 本地绝对路径（前端 convertFileSrc 消费；REQ-201 缩略图）。
 ///
 /// @ai-context: resolve 先例同 resolve_note_image——WebView 不能直接读本地文件；
@@ -217,8 +257,10 @@ pub fn resolve_fragment_image(
     Ok(Some(abs.to_string_lossy().into_owned()))
 }
 
-/// feed 能力开关准入（capture/delete/移组共用——后端不信前端隐藏）。
-fn require_feed_enabled(state: &AppState) -> Result<(), String> {
+/// feed 能力开关准入（capture/delete/升笔记共用——后端不信前端隐藏）。
+/// @ai-context: pub(crate) 供 commands_flashcards::promote_fragment_to_card 复用
+///              （碎片生命周期操作对称纪律）。
+pub(crate) fn require_feed_enabled(state: &AppState) -> Result<(), String> {
     let guard = state
         .feature_flags
         .lock()
 
@@ -81,6 +81,23 @@ impl Db {
         })
     }
 
+    /// 按碎片查卡（v0.12.2 升卡幂等判据：已为碎片生成过卡即视为已升级，
+    /// 可重复触发不再产重卡）。
+    pub fn card_by_fragment(&self, fragment_id: i64) -> Result<Option<Flashcard>> {
+        self.with_conn(|conn| {
+            let mut stmt = conn.prepare(&format!(
+                "SELECT {} FROM flashcards WHERE fragment_id = ?1 LIMIT 1",
+                CARD_COLUMNS
+            ))?;
+            let mut rows = stmt.query_map(params![fragment_id], row_to_card)?;
+            match rows.next() {
+                Some(Ok(c)) => Ok(Some(c)),
+                Some(Err(e)) => Err(e.into()),
+                None => Ok(None),
+            }
+        })
+    }
+
     /// 到期复习队列（due_at ≤ now；组过滤可选；到期最紧在前——弹性承诺不追债，
     /// 只按客观到期时刻排序呈现）。
     pub fn list_due_cards(&self, group_id: Option<i64>, now_ms: i64, limit: usize) -> Result<Vec<Flashcard>> {
 
@@ -52,6 +52,30 @@ fn create_and_get_card_roundtrip() {
     assert_eq!(fetched.due_at, 1000);
 }
 
+#[test]
+fn card_by_fragment_is_idempotency_judge() {
+    // Arrange：碎片绑定卡（v0.12.2 升卡幂等判据）
+    let db = mem_db();
+    let gid = make_group(&db);
+    let f = db
+        .create_fragment(&crate::db_fragments::NewFragment {
+            text: "多句碎片：先晕染再定妆。".to_string(),
+            image_path: None,
+            domain_tag: None,
+            group_id: Some(gid),
+            source: "manual".to_string(),
+        })
+        .expect("frag");
+    let mut c = card(gid, "晕染步骤", 1000);
+    c.fragment_id = Some(f.id);
+    db.create_card(&c).expect("card");
+    // Act/Assert：命中返回卡；无卡碎片返回 None
+    let hit = db.card_by_fragment(f.id).expect("hit").expect("应命中");
+    assert_eq!(hit.front, "晕染步骤");
+    let miss = db.card_by_fragment(9999).expect("miss");
+    assert!(miss.is_none());
+}
+
 #[test]
 fn front_exists_dedup_key() {
     // Arrange：同组同 front 幂等查重（生成防重）
 
@@ -8,7 +8,7 @@ use rusqlite::params;
 
 use crate::db::{unix_seconds, Db};
 use crate::error::Result;
-use crate::types::Fragment;
+use crate::types::{Fragment, Note};
 
 /// fragments 表统一查询列（列顺序与 row_to_fragment 严格对应）。
 const FRAGMENT_COLUMNS: &str =
@@ -157,6 +157,113 @@ impl Db {
             Ok(affected > 0)
         })
     }
+
+    /// 碎片升为笔记（v0.12.2：REQ-201 补升级出口——碎片是原料，升笔记=沉淀）。
+    ///
+    /// @ai-context: 单事务（建笔记 + 删碎片）——任一步失败整链回滚，不留
+    ///              "笔记已建但碎片还在"的半态；图片搬运是事务内副作用
+    ///              （复制失败降级纯文本笔记，碎片文本不丢——与
+    ///              capture_fragment 图片降级同纪律，最坏遗留孤儿文件）。
+    /// @ai-context: 图引用写 `notes-images/{note_id}/{name}`（resolve_note_image
+    ///              规则 2 可解析）；source=manual、rule_version=None（手动沉淀
+    ///              路径诚实降级）；碎片删除后绑定卡经外键 SET NULL 自动解绑
+    ///              保留（卡是独立资产——升笔记不等于消卡）。
+    pub fn promote_fragment_to_note(
+        &self,
+        data_dir: &std::path::Path,
+        fragment_id: i64,
+        title: &str,
+        group_id: Option<i64>,
+    ) -> Result<Note> {
+        let now = unix_seconds();
+        self.with_conn(|conn| {
+            // ① 读碎片（事务内读取——存在性校验与删除同锁，防竞态双升）
+            let fragment = {
+                let mut stmt = conn.prepare(&format!(
+                    "SELECT {} FROM fragments WHERE id = ?1",
+                    FRAGMENT_COLUMNS
+                ))?;
+                let mut rows = stmt.query_map(params![fragment_id], row_to_fragment)?;
+                match rows.next() {
+                    Some(Ok(f)) => f,
+                    Some(Err(e)) => return Err(e.into()),
+                    None => {
+                        return Err(crate::error::AppError::Db(format!(
+                            "碎片不存在: {}",
+                            fragment_id
+                        )))
+                    }
+                }
+            };
+            // ② 建笔记（正文先落碎片文本；图片在 ③ 补写）
+            conn.execute(
+                "INSERT INTO notes (title, content, source, session_id, rule_version, purify_stats, tags, properties, group_id, created_at, updated_at)
+                 VALUES (?1, ?2, 'manual', NULL, NULL, NULL, '[]', NULL, ?3, ?4, ?4)",
+                params![title, fragment.text, group_id, now],
+            )?;
+            let note_id = conn.last_insert_rowid();
+            // ③ 图片搬运 fragments/ → notes-images/{note_id}/（失败降级纯文本）
+            let mut content = fragment.text.clone();
+            if let Some(rel) = fragment.image_path.as_deref() {
+                match copy_fragment_image(data_dir, note_id, rel) {
+                    Some(img_ref) => {
+                        content = format!("{}\n\n![]({})\n", content, img_ref);
+                    }
+                    None => {
+                        eprintln!(
+                            "[db_fragments] 碎片 {} 图片搬运失败（降级纯文本笔记）: {}",
+                            fragment_id, rel
+                        );
+                    }
+                }
+            }
+            if content != fragment.text {
+                conn.execute(
+                    "UPDATE notes SET content = ?1 WHERE id = ?2",
+                    params![content, note_id],
+                )?;
+            }
+            // ④ 删碎片（绑定卡自动解绑保留）
+            conn.execute("DELETE FROM fragments WHERE id = ?1", params![fragment_id])?;
+            // ⑤ 组装返回（与库内一致）
+            Ok(Note {
+                id: note_id,
+                title: title.to_string(),
+                content,
+                source: "manual".to_string(),
+                session_id: None,
+                rule_version: None,
+                purify_stats: None,
+                tags: "[]".to_string(),
+                properties: None,
+                pin: 0,
+                group_id,
+                created_at: now,
+                updated_at: now,
+            })
+        })
+    }
+}
+
+/// 搬运碎片图进笔记图目录（返回 notes-images 相对引用；失败返回 None 降级）。
+///
+/// @ai-context: 只放行 fragments/ 前缀 + 防 `..` 穿越（与 resolve_fragment_image
+///              落盘口径一致）；源文件缺失/IO 失败 → None（调用方降级纯文本）。
+fn copy_fragment_image(data_dir: &std::path::Path, note_id: i64, rel: &str) -> Option<String> {
+    let rel_trim = rel.trim_start_matches(['/', '\\']);
+    if !rel_trim.starts_with("fragments/") || rel_trim.split(['/', '\\']).any(|seg| seg == "..") {
+        return None;
+    }
+    let src = data_dir.join(rel_trim);
+    if !src.is_file() {
+        return None;
+    }
+    // 文件名沿用碎片存储名（毫秒+随机后缀已防碰撞；同笔记内无冲突）
+    let name = std::path::Path::new(rel_trim).file_name()?.to_str()?.to_string();
+    let target_dir = data_dir.join("notes-images").join(note_id.to_string());
+    std::fs::create_dir_all(&target_dir).ok()?;
+    std::fs::copy(&src, target_dir.join(&name)).ok()?;
+    Some(format!("notes-images/{}/{}", note_id, name))
 }
 
 /// 把 rusqlite 行映射为 Fragment。
 
@@ -191,3 +191,92 @@ fn delete_missing_fragment_returns_false() {
     let db = mem_db();
     assert!(!db.delete_fragment(9999).expect("delete"));
 }
+
+#[test]
+fn promote_fragment_to_note_creates_note_and_deletes_fragment() {
+    // Arrange
+    let db = mem_db();
+    let f = db.create_fragment(&frag("碎片文本：眼影要晕染", None, None)).expect("f");
+    // Act：升为未归组笔记
+    let note = db.promote_fragment_to_note(std::path::Path::new("."), f.id, "眼影晕染", None).expect("promote");
+    // Assert：笔记成立（正文=碎片文本、source=manual、未归组）；碎片已删
+    assert_eq!(note.content, "碎片文本：眼影要晕染");
+    assert_eq!(note.source, "manual");
+    assert_eq!(note.group_id, None);
+    assert!(db.get_fragment(f.id).expect("get").is_none());
+    let fetched = db.get_note(note.id).expect("get").expect("note 应存在");
+    assert_eq!(fetched.content, "碎片文本：眼影要晕染");
+}
+
+#[test]
+fn promote_fragment_copies_image_and_embeds_ref() {
+    // Arrange：临时目录伪造碎片图（promote 只做 fs::copy，字节内容无关）
+    let dir = std::env::temp_dir().join(format!("dsh_promote_img_{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(dir.join("fragments")).expect("dir");
+    std::fs::write(dir.join("fragments").join("1-abc.png"), b"fake").expect("img");
+    let db = mem_db();
+    let group = db
+        .create_group(&NewNoteGroup {
+            name: "目标组".to_string(),
+            terrain: "container".to_string(),
+            kind: "topic".to_string(),
+            domain_tag: Some("beauty".to_string()),
+            source: "route".to_string(),
+            series_key: None,
+            route_reason: None,
+        })
+        .expect("group");
+    let f = db
+        .create_fragment(&NewFragment {
+            text: "带图碎片".to_string(),
+            image_path: Some("fragments/1-abc.png".to_string()),
+            domain_tag: None,
+            group_id: Some(group.id),
+            source: "manual".to_string(),
+        })
+        .expect("f");
+    // Act：升入指定组
+    let note = db
+        .promote_fragment_to_note(&dir, f.id, "带图笔记", Some(group.id))
+        .expect("promote");
+    // Assert：图片已搬运入 notes-images/{nid}/ 且正文含引用；碎片已删；归组生效
+    let img_ref = format!("![](notes-images/{}/1-abc.png)", note.id);
+    assert!(note.content.contains(&img_ref), "正文应含图片引用: {}", note.content);
+    assert!(dir.join("notes-images").join(note.id.to_string()).join("1-abc.png").is_file());
+    assert_eq!(note.group_id, Some(group.id));
+    assert!(db.get_fragment(f.id).expect("get").is_none());
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
+#[test]
+fn promote_fragment_image_missing_degrades_to_text() {
+    // Arrange：碎片记录引用不存在图片（外部清理等）
+    let db = mem_db();
+    let f = db
+        .create_fragment(&NewFragment {
+            text: "图丢了也要升".to_string(),
+            image_path: Some("fragments/ghost.png".to_string()),
+            domain_tag: None,
+            group_id: None,
+            source: "manual".to_string(),
+        })
+        .expect("f");
+    // Act：升笔记（临时目录无 fragments/ghost.png）
+    let note = db
+        .promote_fragment_to_note(&std::env::temp_dir(), f.id, "降级笔记", None)
+        .expect("promote");
+    // Assert：图片缺失降级纯文本（碎片文本不丢——诚实降级纪律）
+    assert_eq!(note.content, "图丢了也要升");
+    assert!(db.get_fragment(f.id).expect("get").is_none());
+}
+
+#[test]
+fn promote_fragment_missing_returns_error() {
+    // Arrange/Act/Assert：升不存在的碎片返回明确错误（不 panic 不静默）
+    let db = mem_db();
+    let err = db
+        .promote_fragment_to_note(std::path::Path::new("."), 99999, "标题", None)
+        .expect_err("应报错");
+    assert!(err.to_string().contains("碎片不存在"));
+}