//! 笔记库的文件系统层:路径安全解析、扫描、读写、增删改移。 //! //! # 真相在文件,不在数据库 //! //! 笔记就是库根下的 `.md` 文件树。本文件的每个函数都以「相对库根的路径」为 //! 输入/输出,**所有路径都先过 [`safe_join`]**:拒绝绝对路径、盘符与 `..`, //! 保证任何操作都无法越出库根(前端传来的路径一律不可信)。 use std::path::{Path, PathBuf}; use std::time::UNIX_EPOCH; use super::types::{LibraryEntry, NoteDoc, EditorSettings}; /// 默认库根相对模块目录的名字:`{app_data_dir}/editor/library` pub const DEFAULT_LIBRARY_DIR: &str = "library"; /// 附件(粘贴图片等)目录名,位于库根下 pub const ASSETS_DIR: &str = "assets"; /// 库内私有目录名(索引 + 同步基线),**永不参与同步 / 导出 / 快照**。 pub const PRIVATE_DIR: &str = ".editor"; /// v1「笔记模块」的私有目录名;首次打开时惰性迁移到 [`PRIVATE_DIR`]。 const LEGACY_PRIVATE_DIR: &str = ".notes"; /// 扫描深度上限(防御性:软链接成环时不会无限递归)。 /// 对 `index.rs` 公开:两处扫描(侧栏树 / 索引)必须用同一个深度口径, /// 否则会出现「树里看不到、搜索却搜得到」这种自相矛盾的状态。 pub const MAX_DEPTH: usize = 24; /// 新建笔记的正文模板(front-matter + 一级标题)。 fn note_template(title: &str) -> String { let now = chrono::Local::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true); format!( "---\ntitle: {title}\ncreated: {now}\nupdated: {now}\ntags: []\n---\n\n# {title}\n\n" ) } /// 默认库根路径(未配置自定义库根时使用)。 pub fn default_library_root(module_dir: &Path) -> PathBuf { module_dir.join(DEFAULT_LIBRARY_DIR) } /// 由设置解析出当前生效的库根。 pub fn resolve_library_root(module_dir: &Path, settings: &EditorSettings) -> PathBuf { match &settings.library_root { Some(root) if !root.trim().is_empty() => PathBuf::from(root.trim()), _ => default_library_root(module_dir), } } /// 惰性迁移旧私有目录 `.notes/` → `.editor/`(幂等)。 /// /// 索引可重建,但迁移能保住同步基线(`sync.json`),因此优先整目录重命名。 /// 迁移后残留的旧索引文件(`notes.db*`)直接删除 —— 下次打开会按新库根重建。 pub fn migrate_private_dir(root: &Path) { let old = root.join(LEGACY_PRIVATE_DIR); let new = root.join(PRIVATE_DIR); if !old.is_dir() || new.exists() { return; } match std::fs::rename(&old, &new) { Ok(()) => { for stale in ["notes.db", "notes.db-wal", "notes.db-shm"] { let _ = std::fs::remove_file(new.join(stale)); } crate::logger::log_info( "editor", &format!("已迁移库内私有目录 {LEGACY_PRIVATE_DIR}/ → {PRIVATE_DIR}/"), ); } Err(e) => crate::logger::log_warn( "editor", &format!("迁移库内私有目录失败(将按新目录重建): {e}"), ), } } /// 确保库根与其 `assets/` 子目录存在(顺带惰性迁移旧私有目录)。 pub fn ensure_library(root: &Path) -> Result<(), String> { migrate_private_dir(root); std::fs::create_dir_all(root).map_err(|e| format!("创建笔记库目录失败: {e}"))?; std::fs::create_dir_all(root.join(ASSETS_DIR)) .map_err(|e| format!("创建附件目录失败: {e}"))?; Ok(()) } /// 把「相对库根的路径」解析为绝对路径,并拒绝任何逃逸。 /// /// 空串表示库根本身。统一接受 `/` 与 `\` 两种分隔符输入,输出用系统分隔符。 pub fn safe_join(root: &Path, rel: &str) -> Result { let normalized = rel.trim().replace('\\', "/"); if normalized.starts_with('/') || normalized.contains(':') { return Err("仅支持库内相对路径".to_string()); } let mut out = root.to_path_buf(); for part in normalized.split('/') { if part.is_empty() || part == "." { continue; } if part == ".." { return Err("路径不能包含上级目录(..)".to_string()); } out.push(part); } Ok(out) } /// 绝对路径 → 相对库根的路径(统一 `/` 分隔)。 pub fn rel_string(root: &Path, path: &Path) -> String { path.strip_prefix(root) .map(|p| p.to_string_lossy().replace('\\', "/")) .unwrap_or_default() } /// 校验用户输入的条目名(新建/重命名)。 /// /// 拒绝路径分隔符、Windows 保留字符与控制字符 —— 名称只应是「一个名字」, /// 不含任何路径语义。 pub fn validate_name(name: &str) -> Result { let name = name.trim(); if name.is_empty() { return Err("名称不能为空".to_string()); } if name == "." || name == ".." { return Err("名称不合法".to_string()); } if name.chars().count() > 120 { return Err("名称过长".to_string()); } if name .chars() .any(|c| c.is_control() || matches!(c, '<' | '>' | ':' | '"' | '/' | '\\' | '|' | '?' | '*')) { return Err("名称不能包含 < > : \" / \\ | ? * 等字符".to_string()); } Ok(name.to_string()) } fn is_note_file(name: &str) -> bool { name.to_ascii_lowercase().ends_with(".md") } fn modified_ms(meta: &std::fs::Metadata) -> u64 { meta.modified() .ok() .and_then(|t| t.duration_since(UNIX_EPOCH).ok()) .map(|d| d.as_millis() as u64) .unwrap_or(0) } /// 扫描整个库,返回扁平条目列表(目录在前、各自按名称排序;前端自行组树)。 pub fn scan(root: &Path) -> Result, String> { let mut out = Vec::new(); if !root.is_dir() { return Ok(out); } walk(root, root, &mut out, 0); Ok(out) } fn walk(root: &Path, dir: &Path, out: &mut Vec, depth: usize) { if depth > MAX_DEPTH { return; } let read = match std::fs::read_dir(dir) { Ok(r) => r, Err(_) => return, }; let mut dirs: Vec<(String, PathBuf)> = Vec::new(); let mut files: Vec<(String, PathBuf)> = Vec::new(); for entry in read.flatten() { let name = entry.file_name().to_string_lossy().to_string(); // 隐藏项(含 `.editor` 之类的私有目录)一律不进库树 if name.starts_with('.') { continue; } let file_type = match entry.file_type() { Ok(t) => t, Err(_) => continue, }; let path = entry.path(); if file_type.is_dir() { // 根级 assets 是图片仓库,不作为笔记目录展示,避免噪声 if depth == 0 && name == ASSETS_DIR { continue; } dirs.push((name, path)); } else if file_type.is_file() && is_note_file(&name) { files.push((name, path)); } } dirs.sort_by(|a, b| a.0.cmp(&b.0)); files.sort_by(|a, b| a.0.cmp(&b.0)); for (name, path) in dirs { let meta = std::fs::metadata(&path).ok(); out.push(LibraryEntry { name, rel_path: rel_string(root, &path), parent_rel: rel_string(root, dir), is_dir: true, modified: meta.as_ref().map(modified_ms).unwrap_or(0), size: 0, }); walk(root, &path, out, depth + 1); } for (name, path) in files { let meta = std::fs::metadata(&path).ok(); out.push(LibraryEntry { name, rel_path: rel_string(root, &path), parent_rel: rel_string(root, dir), is_dir: false, modified: meta.as_ref().map(modified_ms).unwrap_or(0), size: meta.as_ref().map(|m| m.len()).unwrap_or(0), }); } } /// 统计库内 `.md` 文件数量。 pub fn count_notes(entries: &[LibraryEntry]) -> u32 { entries.iter().filter(|e| !e.is_dir).count() as u32 } /// 构造一篇文档的返回结构。 fn to_doc(root: &Path, path: &Path, content: String) -> NoteDoc { let modified = std::fs::metadata(path).map(|m| modified_ms(&m)).unwrap_or(0); NoteDoc { rel_path: rel_string(root, path), name: path .file_name() .map(|n| n.to_string_lossy().to_string()) .unwrap_or_default(), content, modified, } } /// 读取一篇笔记(相对库根路径)。非 UTF-8 字节按 lossy 处理,不报错。 pub fn read_note(root: &Path, rel: &str) -> Result { let path = safe_join(root, rel)?; if !path.is_file() { return Err(format!("笔记不存在:{rel}")); } let bytes = std::fs::read(&path).map_err(|e| format!("读取笔记失败: {e}"))?; Ok(to_doc(root, &path, String::from_utf8_lossy(&bytes).into_owned())) } /// 写入一篇笔记(已存在的文件才允许写;不自动创建目录,由 create_note 负责)。 pub fn write_note(root: &Path, rel: &str, content: &str) -> Result { let path = safe_join(root, rel)?; if !path.is_file() { return Err(format!("笔记不存在:{rel}")); } std::fs::write(&path, content).map_err(|e| format!("保存笔记失败: {e}"))?; Ok(to_doc(root, &path, content.to_string())) } /// 在指定目录下新建笔记:自动补 `.md`、重名自动加序号。 /// /// 用**内置**的 front-matter 模板(不读 `templates/`)。保留这个无模板参数的入口是 /// 为了「模板目录被删/损坏时仍然能新建笔记」这条底线,单测也走它。 pub fn create_note(root: &Path, dir_rel: &str, name: &str) -> Result { create_note_with_template(root, dir_rel, name, "") } /// 在指定目录下新建笔记,正文由模板渲染(`template_id` 为空 = 用内置默认模板)。 /// /// 模板渲染失败(模板文件被删、权限不足)时回退到内置模板而不是报错: /// 「新建笔记」这个动作不该因为一个辅助文件的问题而不可用。 pub fn create_note_with_template( root: &Path, dir_rel: &str, name: &str, template_id: &str, ) -> Result { let dir = safe_join(root, dir_rel)?; std::fs::create_dir_all(&dir).map_err(|e| format!("创建目录失败: {e}"))?; let mut file_name = validate_name(name)?; if !is_note_file(&file_name) { file_name.push_str(".md"); } let title = file_name.trim_end_matches(".md").to_string(); // 重名自动加序号,避免「新建即报错」 let mut candidate = file_name.clone(); let mut index = 1; while dir.join(&candidate).exists() { candidate = format!("{title} {index}.md"); index += 1; if index > 999 { return Err("同名文件过多,请换一个名称".to_string()); } } // 模板渲染:模板 ID 无效时 `render_for_new_note` 自己会回退到内置空白模板 let content = if template_id.trim().is_empty() { note_template(&title) } else { super::templates::render_for_new_note(root, template_id, &title, dir_rel) }; let path = dir.join(&candidate); std::fs::write(&path, content).map_err(|e| format!("新建笔记失败: {e}"))?; read_note(root, &rel_string(root, &path)) } /// 在指定目录下新建文件夹。 pub fn create_folder(root: &Path, dir_rel: &str, name: &str) -> Result { let dir = safe_join(root, dir_rel)?; std::fs::create_dir_all(&dir).map_err(|e| format!("创建目录失败: {e}"))?; let folder_name = validate_name(name)?; let path = dir.join(&folder_name); if path.exists() { return Err(format!("「{folder_name}」已存在")); } std::fs::create_dir_all(&path).map_err(|e| format!("新建文件夹失败: {e}"))?; Ok(rel_string(root, &path)) } /// 重命名库内条目;返回新的相对路径。 /// /// 文件若未带扩展名,沿用原扩展名(避免 `a.md` 改成 `a` 变成无扩展名文件)。 pub fn rename_entry(root: &Path, rel: &str, new_name: &str) -> Result { let path = safe_join(root, rel)?; if !path.exists() { return Err("条目不存在".to_string()); } let mut name = validate_name(new_name)?; if path.is_file() { let old_ext = path.extension().map(|e| e.to_string_lossy().to_string()); if let Some(ext) = old_ext { if !name.to_ascii_lowercase().ends_with(&format!(".{}", ext.to_ascii_lowercase())) { name.push('.'); name.push_str(&ext); } } } let parent = path .parent() .ok_or_else(|| "无法解析父目录".to_string())?; let target = parent.join(&name); if target.exists() { return Err(format!("「{name}」已存在")); } std::fs::rename(&path, &target).map_err(|e| format!("重命名失败: {e}"))?; Ok(rel_string(root, &target)) } /// 删除库内条目(目录递归删除)。 pub fn delete_entry(root: &Path, rel: &str) -> Result<(), String> { if rel.trim().is_empty() { return Err("不能删除库根".to_string()); } let path = safe_join(root, rel)?; if !path.exists() { return Err("条目不存在".to_string()); } if path.is_dir() { std::fs::remove_dir_all(&path).map_err(|e| format!("删除目录失败: {e}"))?; } else { std::fs::remove_file(&path).map_err(|e| format!("删除文件失败: {e}"))?; } Ok(()) }