feat(notes): 图片落盘三入口与删除清理（v0.15 ④）

Author: Aparencia

app/src-tauri/src/commands.rs

@@ -434,13 +434,24 @@ pub async fn update_note(
     Ok(true)
 }
 
-/// 删除笔记（REQ-004）。
+/// 删除笔记（REQ-004；v0.15 顺带清理笔记图片目录——防孤立残留）。
 #[tauri::command]
 pub async fn delete_note(state: State<'_, AppState>, id: i64) -> Result<bool, String> {
     if id <= 0 {
         return Err("无效的笔记 id".to_string());
     }
-    state.db.delete_note(id).map_err(|e| e.to_string())
+    let deleted = state.db.delete_note(id).map_err(|e| e.to_string())?;
+    if deleted {
+        // v0.15：notes-images/{nid}/ 只属于该笔记——删除笔记即清空（尽力而为：
+        // 失败不阻断（用户重试删除无意义时也允许残留，垃圾回收后续单独任务）
+        let img_dir = state.data_dir.join("notes-images").join(id.to_string());
+        if let Err(e) = std::fs::remove_dir_all(&img_dir) {
+            if e.kind() != std::io::ErrorKind::NotFound {
+                eprintln!("[notes] 清理笔记图片目录失败（{img_dir:?}）: {e}");
+            }
+        }
+    }
+    Ok(deleted)
 }
 
 /// 搜索笔记（REQ-004；关键词截断——TD-005；v0.10.0 支持按标签过滤）。

app/src-tauri/src/commands_note_images.rs

@@ -1,12 +1,21 @@
-//! 笔记图片命令（v0.10.1）——显示解析 + 本地导入。
+//! 笔记图片命令（v0.10.1）——显示解析 + 本地导入；v0.15 扩展剪贴板/外链落盘。
 //!
 //! @ai-context: 笔记 Markdown 内嵌"data_dir 相对引用"（session-images/{sid}/...、
 //!              notes-images/{nid}/...、产物裸 full/thumbs/...）。WebView 无法
 //!              直接读本地文件，resolve 在服务端校验后返回可 convert 的绝对路径；
 //!              本地图片导入必须复制进 data_dir（assetProtocol scope=$APPDATA/**）。
+//! @ai-context: v0.15 图片落盘三入口（REQ：用户插入的图片必须留副本）——① 文件
+//!              选择（历史行为，扩展名白名单）；② 剪贴板 base64（import_note_image_b64，
+//!              字节嗅探定格式）；③ 外链 URL（import_note_image_url，ureq 下载限流）。
+//!              三者共用 save_image_bytes（大小上限 + 唯一命名 + 落盘），删除笔记时
+//!              顺带清理 notes-images/{nid}/ 防孤立残留。
 
+use std::io::Read;
 use std::path::{Path, PathBuf};
+use std::time::Duration;
 
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine as _;
 use tauri::State;
 
 use crate::commands::AppState;
@@ -16,6 +25,10 @@ use crate::types::Note;
 const IMAGE_EXT_WHITELIST: &[&str] = &["png", "jpg", "jpeg", "webp", "gif"];
 /// 导入大小上限（10MB——关键帧/截图场景足够）。
 const IMAGE_MAX_BYTES: u64 = 10 * 1024 * 1024;
+/// 外链下载超时（秒）。
+const URL_FETCH_TIMEOUT_SECS: u64 = 10;
+/// 外链下载跟随重定向上限。
+const URL_FETCH_MAX_REDIRECTS: u32 = 3;
 
 /// 解析笔记图片引用 → 可 convert 的本地绝对路径（纯函数，可单测）。
 ///
@@ -90,7 +103,82 @@ pub async fn import_note_image(
     import_image_file(&source_path, &state.data_dir, note_id, IMAGE_MAX_BYTES)
 }
 
-/// 复制图片进笔记图片目录并返回相对引用（纯逻辑，命令层复用——可单测）。
+/// 剪贴板图片导入笔记（v0.15：base64 IPC——同 capture_fragment 先例）。
+///
+/// @ai-context: 编辑态粘贴图片入口：前端把 ClipboardEvent 的 image blob 转 base64
+///              上送，本命令字节嗅探定格式（不信任 MIME——浏览器可能给错 type），
+///              解码验证 + 大小上限后落盘。失败即 Err——前端提示不落脏内容。
+#[tauri::command]
+pub async fn import_note_image_b64(
+    state: State<'_, AppState>,
+    note_id: i64,
+    image_b64: String,
+) -> Result<String, String> {
+    if note_id <= 0 {
+        return Err("无效的笔记 id".to_string());
+    }
+    if state.db.get_note(note_id).map_err(|e| e.to_string())?.is_none() {
+        return Err("笔记不存在".to_string());
+    }
+    let bytes = BASE64
+        .decode(image_b64.trim())
+        .map_err(|_| "图片数据解码失败（非法 base64）".to_string())?;
+    import_image_bytes(&bytes, &state.data_dir, note_id, IMAGE_MAX_BYTES)
+}
+
+/// 外链图片下载导入笔记（v0.15：🌐 链接图自动复制——防源站删除导致资源丢失）。
+///
+/// @ai-context: 下载经 ureq（TLS 全栈已有依赖），超时 + 限流 10MB + 跟随重定向；
+///              内容类型双保险（Content-Type 前缀 image/ 或字节嗅探命中白名单）。
+///              失败返回 Err——前端降级插入原 URL 并提示（能力降级不失效）。
+#[tauri::command]
+pub async fn import_note_image_url(
+    state: State<'_, AppState>,
+    note_id: i64,
+    url: String,
+) -> Result<String, String> {
+    if note_id <= 0 {
+        return Err("无效的笔记 id".to_string());
+    }
+    if state.db.get_note(note_id).map_err(|e| e.to_string())?.is_none() {
+        return Err("笔记不存在".to_string());
+    }
+    let bytes = download_image_limited(&url, IMAGE_MAX_BYTES)?;
+    import_image_bytes(&bytes, &state.data_dir, note_id, IMAGE_MAX_BYTES)
+}
+
+/// 下载并限流读取图片字节（纯逻辑：非 http/https 直接拒绝——可单测）。
+///
+/// @ai-context: ureq 2 的 read_to_string 无长度上限（恶意站点可无限流），
+///              经 into_reader().take(max+1) 截断读取——超限即 Err 不落盘。
+fn download_image_limited(url: &str, max_bytes: u64) -> Result<Vec<u8>, String> {
+    if !(url.starts_with("http://") || url.starts_with("https://")) {
+        return Err("仅支持 http/https 链接".to_string());
+    }
+    let resp = ureq::AgentBuilder::new()
+        .timeout(Duration::from_secs(URL_FETCH_TIMEOUT_SECS))
+        .redirects(URL_FETCH_MAX_REDIRECTS)
+        .build()
+        .get(url)
+        .call()
+        .map_err(|e| format!("图片下载失败: {e}"))?;
+    if !resp.content_type().starts_with("image/") {
+        return Err(format!("目标不是图片资源（Content-Type: {}）", resp.content_type()));
+    }
+    let mut reader = resp.into_reader();
+    let mut buf = Vec::with_capacity(64 * 1024);
+    reader
+        .by_ref()
+        .take(max_bytes + 1)
+        .read_to_end(&mut buf)
+        .map_err(|e| format!("图片读取失败: {e}"))?;
+    if buf.len() as u64 > max_bytes {
+        return Err(format!("图片超过大小上限（{} 字节）", max_bytes));
+    }
+    Ok(buf)
+}
+
+/// 复制图片进笔记图片目录并返回相对引用（文件入口；扩展名白名单——v0.10.1 契约）。
 fn import_image_file(
     source_path: &str,
     data_dir: &Path,
@@ -109,9 +197,43 @@ fn import_image_file(
     if !IMAGE_EXT_WHITELIST.contains(&ext.as_str()) {
         return Err(format!("不支持的图片格式: {}（支持 png/jpg/jpeg/webp/gif）", ext));
     }
-    let len = std::fs::metadata(src).map_err(|e| e.to_string())?.len();
-    if len > max_bytes {
-        return Err(format!("图片超过大小上限（{} 字节）", len));
+    let bytes = std::fs::read(src).map_err(|e| e.to_string())?;
+    write_image_bytes(data_dir, note_id, &bytes, &ext, max_bytes)
+}
+
+/// 字节入口（剪贴板/外链共用）：字节嗅探定格式 + 校验 + 落盘。
+///
+/// @ai-context: 与文件入口不同——机器来源的数据不信任扩展名/MIME，用
+///              image::guess_format 嗅探魔数（不完整解码，快且拒垃圾数据）。
+fn import_image_bytes(
+    bytes: &[u8],
+    data_dir: &Path,
+    note_id: i64,
+    max_bytes: u64,
+) -> Result<String, String> {
+    let ext = match image::guess_format(bytes) {
+        Ok(fmt) => match fmt {
+            image::ImageFormat::Png => "png",
+            image::ImageFormat::Jpeg => "jpg",
+            image::ImageFormat::Gif => "gif",
+            image::ImageFormat::WebP => "webp",
+            _ => return Err("不支持的图片格式（支持 png/jpg/jpeg/webp/gif）".to_string()),
+        },
+        Err(_) => return Err("图片数据损坏或不是图片（嗅探失败）".to_string()),
+    };
+    write_image_bytes(data_dir, note_id, bytes, ext, max_bytes)
+}
+
+/// 落盘核心（纯逻辑，可单测）：大小上限 → 建目录 → 唯一命名 → 写文件。
+fn write_image_bytes(
+    data_dir: &Path,
+    note_id: i64,
+    bytes: &[u8],
+    ext: &str,
+    max_bytes: u64,
+) -> Result<String, String> {
+    if bytes.len() as u64 > max_bytes {
+        return Err(format!("图片超过大小上限（{} 字节）", max_bytes));
     }
     let dir = data_dir.join("notes-images").join(note_id.to_string());
     std::fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
@@ -122,7 +244,7 @@ fn import_image_file(
         seq += 1;
         name = format!("{}_{}.{}", ts, seq, ext);
     }
-    std::fs::copy(src, dir.join(&name)).map_err(|e| e.to_string())?;
+    std::fs::write(dir.join(&name), bytes).map_err(|e| e.to_string())?;
     Ok(format!("notes-images/{}/{}", note_id, name))
 }
 

app/src-tauri/src/commands_note_images_tests.rs

@@ -2,10 +2,20 @@
 
 use std::fs;
 
-use crate::commands_note_images::{import_image_file, resolve_note_image_path};
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine as _;
+
+use crate::commands_note_images::{
+    download_image_limited, import_image_bytes, import_image_file, resolve_note_image_path,
+    write_image_bytes,
+};
 use crate::db::Db;
 use crate::types::{NewNote, Note};
 
+/// 1×1 透明 PNG（合法魔数 + 数据——字节嗅探用例用）。
+const TINY_PNG_B64: &str =
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+
 /// 构造带指定来源会话的笔记（内存库；会话外键需先存在）。
 fn make_note(session_id: Option<i64>) -> Note {
     let db = Db::open(":memory:").expect("in-memory db");
@@ -131,3 +141,47 @@ fn import_rejects_bad_source() {
     fs::write(&big, vec![0u8; 200]).unwrap();
     assert!(import_image_file(big.to_str().unwrap(), dir.path(), 9, 100).is_err());
 }
+
+#[test]
+fn import_bytes_sniffs_png_and_writes() {
+    // Arrange：合法 1×1 PNG 字节（模拟剪贴板/下载来源）
+    let png = BASE64.decode(TINY_PNG_B64).unwrap();
+    let dir = tempfile::tempdir().unwrap();
+    // Act
+    let rel = import_image_bytes(&png, dir.path(), 9, 1024 * 1024).unwrap();
+    // Assert：嗅探定格式 → .png 落盘且字节一致
+    assert!(rel.starts_with("notes-images/9/") && rel.ends_with(".png"));
+    let abs = dir.path().join(rel.replace('/', std::path::MAIN_SEPARATOR_STR));
+    assert_eq!(fs::read(&abs).unwrap(), png);
+}
+
+#[test]
+fn import_bytes_rejects_garbage_and_oversize() {
+    // Arrange
+    let dir = tempfile::tempdir().unwrap();
+    let png = BASE64.decode(TINY_PNG_B64).unwrap();
+    // Act & Assert：垃圾数据嗅探失败；合法图超过 max_bytes 拒绝
+    assert!(import_image_bytes(b"fake-png-bytes", dir.path(), 9, 1024).is_err());
+    assert!(import_image_bytes(&png, dir.path(), 9, 10).is_err());
+}
+
+#[test]
+fn write_bytes_unique_name_on_conflict() {
+    // Arrange
+    let dir = tempfile::tempdir().unwrap();
+    // Act：同秒重名 → 序列后缀（文件入口同契约）
+    let rel1 = write_image_bytes(dir.path(), 9, b"a", "png", 1024).unwrap();
+    let rel2 = write_image_bytes(dir.path(), 9, b"a", "png", 1024).unwrap();
+    // Assert
+    assert_ne!(rel1, rel2);
+    assert!(rel2.contains('_'));
+}
+
+#[test]
+fn download_rejects_non_http_scheme() {
+    // Arrange & Act：非 http/https 直接拒绝（不触网——纯前缀校验路径）
+    // Assert
+    assert!(download_image_limited("ftp://host/a.png", 1024).is_err());
+    assert!(download_image_limited("file:///C:/x/a.png", 1024).is_err());
+    assert!(download_image_limited("C:/x/a.png", 1024).is_err());
+}

app/src-tauri/src/lib.rs

@@ -662,8 +662,11 @@ pub fn run() {
             commands_images::save_user_screenshot,
             commands_images::session_images_base_url,
             // v0.10.1：笔记图片——Markdown 引用解析 / 本地导入 / data_dir 基准
+            // v0.15：剪贴板 base64 导入 + 外链 URL 下载导入（图片落盘三入口）
             commands_note_images::resolve_note_image,
             commands_note_images::import_note_image,
+            commands_note_images::import_note_image_b64,
+            commands_note_images::import_note_image_url,
             commands_note_images::app_data_dir,
             // 结构图（REQ-182/183/184，v0.7.7：非线性结构图像捕获持久化 + 图库）
             commands_structures::capture_session_structures,