This commit is contained in:
zhongluofeng committed 2026-10-10 14:29:48 +08:00
1 parent ad987111a3
commit c9e61f38c5
89 files changed
+11775 -3155

No files matched your search

+365
View File
@@ -0,0 +1,365 @@
//! 笔记库的文件系统层:路径安全解析、扫描、读写、增删改移。
//!
//! # 真相在文件,不在数据库
//!
//! 笔记就是库根下的 `.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<PathBuf, String> {
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<String, String> {
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<Vec<LibraryEntry>, 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<LibraryEntry>, 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<NoteDoc, String> {
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<NoteDoc, String> {
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<NoteDoc, String> {
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<NoteDoc, String> {
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<String, String> {
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<String, String> {
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(())
}