mnote/rust/crates/mnote-web/src/routes/local_folder_source.rs

use crate::context::RequestContext;
use crate::error::WebError;
use crate::page_aggregate::{
    PageAggregate, PageAggregateSource, PageBody, PageHead, PageIdentity, PageLayout, PageOptions,
    PagePermissions, PageStats, PageTree,
};
use crate::routes::local_markdown_parser::{
    file_stem_title, parse_markdown_page, split_frontmatter,
};
use crate::routes::local_search_index;
use crate::routes::snapshot_support::ProjectionSnapshot;
use axum::extract::{Extension, Multipart, Path as AxumPath, Query};
use axum::http::{header, HeaderMap, HeaderValue, StatusCode};
use axum::Json;
use bridge_runtime::project_legacy_content_to_block_document;
use core_protocol::{
    KernelObjectIdentity, KernelObjectKind, ObjectWorkspacePath, WorkspaceSourceKind,
};
use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use std::cmp::Ordering;
use std::collections::hash_map::DefaultHasher;
use std::collections::BTreeMap;
use std::fs;
use std::hash::{Hash, Hasher};
use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};

#[derive(Debug, Clone)]
struct LocalFolderEntry {
    path: PathBuf,
    relative_path: String,
    file_name: String,
    is_dir: bool,
    is_symlink: bool,
    is_readonly: bool,
}

#[derive(Debug, Clone, Default)]
struct LocalFolderMetadata {
    page_ids: BTreeMap<String, String>,
    page_options: BTreeMap<String, Value>,
    trash_entries: BTreeMap<String, LocalTrashEntry>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct LocalWorkspaceManifest {
    #[serde(default, alias = "workspace_id")]
    workspace_id: String,
    #[serde(default, alias = "owner_id")]
    owner_id: String,
    #[serde(default, alias = "created_at")]
    created_at: String,
    #[serde(default, alias = "capabilities")]
    capabilities: Vec<String>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct LocalAccessPolicy {
    #[serde(default)]
    admins: Vec<String>,
    #[serde(default)]
    grants: Vec<LocalAccessGrant>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct LocalAccessGrant {
    #[serde(default)]
    id: String,
    #[serde(default, alias = "user_id")]
    user_id: String,
    #[serde(default, alias = "root_uri")]
    root_uri: String,
    #[serde(default, alias = "root_path")]
    root_path: String,
    #[serde(default, alias = "access")]
    permission: String,
    #[serde(default = "default_true")]
    recursive: bool,
    #[serde(default)]
    capabilities: Vec<String>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct LocalShareGrantsStore {
    #[serde(default)]
    grants: Vec<LocalShareGrant>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct LocalShareGrant {
    #[serde(default)]
    id: String,
    #[serde(default, alias = "share_id")]
    share_id: String,
    #[serde(default, alias = "owner_user_id")]
    owner_user_id: String,
    #[serde(default, alias = "target_user_id")]
    target_user_id: String,
    #[serde(default, alias = "root_uri")]
    root_uri: String,
    #[serde(default, alias = "root_path")]
    root_path: String,
    #[serde(default, alias = "documentId")]
    document_id: String,
    #[serde(default, alias = "allowedResourceIds")]
    allowed_resource_ids: Vec<String>,
    #[serde(default, alias = "access")]
    permission: String,
    #[serde(default)]
    capabilities: Vec<String>,
    #[serde(default, alias = "createdAt")]
    created_at: String,
    #[serde(default, alias = "revokedAt")]
    revoked_at: Option<String>,
    #[serde(default = "default_true")]
    active: bool,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum LocalAccessMode {
    Read,
    Write,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct LocalTrashEntry {
    #[serde(default, alias = "documentId")]
    document_id: String,
    #[serde(default, alias = "resourceKind")]
    resource_kind: String,
    #[serde(default, alias = "resourceScope")]
    resource_scope: String,
    #[serde(default, alias = "originalFilePath")]
    original_file_path: String,
    #[serde(default, alias = "trashedFilePath")]
    trashed_file_path: String,
    #[serde(default, alias = "trashEntryId")]
    trash_entry_id: String,
    #[serde(default, alias = "originalRelativePath")]
    original_relative_path: String,
    #[serde(default, alias = "trashRelativePath")]
    trash_relative_path: String,
    #[serde(default, alias = "deletedAtMs")]
    deleted_at_ms: u128,
    #[serde(default, alias = "archivedAt")]
    archived_at: u128,
    #[serde(default, alias = "purgedAt")]
    purged_at: Option<u128>,
}

#[derive(Debug, Clone)]
struct LocalFolderRow {
    node_id: String,
    row_id: String,
    parent_node_id: Option<String>,
    title: String,
    depth: u32,
    position: u32,
    row_kind: String,
    icon_hint: String,
    relative_path: String,
    source_uri: String,
    child_count: u32,
    expandable: bool,
    expanded_by_default: bool,
    document_id: Option<String>,
    capabilities: Vec<String>,
    workspace_id: String,
    root_source_uri: String,
}

#[derive(Debug, Clone)]
pub(crate) struct LocalUploadFile {
    name: String,
    content_type: String,
    bytes: Vec<u8>,
}

#[derive(Debug, Clone)]
struct LocalAssetUploadFields {
    file: LocalUploadFile,
    root_uri: String,
    document_id: String,
    kind: String,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LocalFileOpenQuery {
    pub root_uri: String,
    pub path: String,
    #[serde(default)]
    pub download: Option<bool>,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LocalAccessValidateRootRequest {
    #[serde(default, alias = "root_uri")]
    pub root_uri: String,
    #[serde(default, alias = "root_path")]
    pub root_path: String,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LocalAccessGrantRequest {
    #[serde(default)]
    pub id: String,
    #[serde(default, alias = "user_id")]
    pub user_id: String,
    #[serde(default, alias = "root_uri")]
    pub root_uri: String,
    #[serde(default, alias = "root_path")]
    pub root_path: String,
    #[serde(default, alias = "access")]
    pub permission: String,
    #[serde(default = "default_true")]
    pub recursive: bool,
    #[serde(default)]
    pub capabilities: Vec<String>,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct LocalShareGrantRequest {
    #[serde(default)]
    pub id: String,
    #[serde(default, alias = "share_id")]
    pub share_id: String,
    #[serde(default, alias = "owner_user_id")]
    pub owner_user_id: String,
    #[serde(default, alias = "target_user_id")]
    pub target_user_id: String,
    #[serde(default, alias = "root_uri")]
    pub root_uri: String,
    #[serde(default, alias = "root_path")]
    pub root_path: String,
    #[serde(default, alias = "documentId")]
    pub document_id: String,
    #[serde(default, alias = "allowedResourceIds")]
    pub allowed_resource_ids: Vec<String>,
    #[serde(default, alias = "access")]
    pub permission: String,
    #[serde(default)]
    pub capabilities: Vec<String>,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SharedCacheRecordRequest {
    pub root_uri: String,
    pub share_id: String,
    pub permission: String,
    #[serde(default)]
    pub remote_version: String,
    #[serde(default)]
    pub base_version: String,
    #[serde(default)]
    pub source_actor: String,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SyncPendingChangeRequest {
    pub root_uri: String,
    pub share_id: String,
    pub resource_id: String,
    #[serde(default)]
    pub local_version: String,
    #[serde(default)]
    pub base_version: String,
    #[serde(default)]
    pub remote_version: String,
    #[serde(default)]
    pub change_summary: String,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SyncConflictReportRequest {
    pub root_uri: String,
    pub share_id: String,
    pub resource_id: String,
    #[serde(default)]
    pub local_version: String,
    #[serde(default)]
    pub remote_version: String,
    #[serde(default)]
    pub base_version: String,
    #[serde(default)]
    pub actor_id: String,
    #[serde(default)]
    pub summary: String,
}

const DEFAULT_LOCAL_WORKSPACE_BASE_DIR: &str = "/mnt/Data1T/Mnote_data";
const DEFAULT_LOCAL_WORKSPACE_SLUG: &str = "my-space";
const ENV_LOCAL_ADMIN_USER_IDS: &str = "MNOTE_ADMIN_USER_IDS";
const ENV_LOCAL_ACCESS_POLICY_FILE: &str = "MNOTE_LOCAL_ACCESS_POLICY_FILE";
const ENV_SHARE_GRANTS_FILE: &str = "MNOTE_SHARE_GRANTS_FILE";

fn default_true() -> bool {
    true
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct LocalFolderWatchRevision {
    pub root_uri: String,
    pub revision: String,
    pub entry_count: usize,
    pub latest_modified_ms: u128,
}

pub(crate) fn ensure_local_workspace_access_for_actor(
    actor_id: &str,
    actor_type: &str,
    root_uri: &str,
) -> Result<PathBuf, WebError> {
    ensure_local_workspace_access_for_actor_with_mode(
        actor_id,
        actor_type,
        root_uri,
        LocalAccessMode::Write,
    )
}

pub(crate) fn ensure_local_workspace_read_access_for_actor(
    actor_id: &str,
    actor_type: &str,
    root_uri: &str,
) -> Result<PathBuf, WebError> {
    ensure_local_workspace_access_for_actor_with_mode(
        actor_id,
        actor_type,
        root_uri,
        LocalAccessMode::Read,
    )
}

fn ensure_local_workspace_access_for_actor_with_mode(
    actor_id: &str,
    actor_type: &str,
    root_uri: &str,
    mode: LocalAccessMode,
) -> Result<PathBuf, WebError> {
    let actor_id = actor_id.trim();
    let actor_type = actor_type.trim();
    if actor_id.is_empty()
        || actor_id == "anonymous"
        || actor_type.is_empty()
        || actor_type == "anonymous"
    {
        return Err(WebError::new(
            StatusCode::UNAUTHORIZED,
            "local_workspace_auth_required",
            "本地工作区访问需要先登录",
        ));
    }

    let policy = load_local_access_policy().unwrap_or_default();
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    if !canonical_root.is_dir() {
        return Err(WebError::bad_request_code(
            "local_folder_not_directory",
            "本地 rootUri 必须指向目录",
        ));
    }

    if is_local_admin(actor_id, actor_type, &policy) {
        return Ok(canonical_root);
    }
    if local_access_policy_allows(&policy, actor_id, &canonical_root, mode) {
        return Ok(canonical_root);
    }
    if let Ok(manifest) = load_local_workspace_manifest(&canonical_root) {
        if manifest.owner_id.trim() == actor_id {
            return Ok(canonical_root);
        }
    }

    Err(WebError::new(
        StatusCode::FORBIDDEN,
        "local_workspace_access_denied",
        "当前用户无权访问该本地工作区",
    ))
}

pub(crate) fn ensure_local_workspace_read_access(
    context: &RequestContext,
    root_uri: &str,
) -> Result<PathBuf, WebError> {
    ensure_local_workspace_read_access_for_actor(
        &context.auth.actor_id,
        &context.auth.actor_type,
        root_uri,
    )
}

pub(crate) fn ensure_local_path_read_access(
    context: &RequestContext,
    root_uri: &str,
    candidate_path: &str,
) -> Result<PathBuf, WebError> {
    let canonical_root = ensure_local_workspace_read_access(context, root_uri)?;
    let candidate_path = candidate_path.trim();
    if candidate_path.is_empty() {
        return Err(WebError::bad_request_code(
            "local_file_path_required",
            "本地文件读取缺少文件路径",
        ));
    }
    let raw_path = candidate_path
        .strip_prefix("file://")
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from(candidate_path));
    let target_path = if raw_path.is_absolute() {
        raw_path
    } else {
        canonical_root.join(raw_path)
    };
    let canonical_target = target_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_file_unavailable",
            format!("无法访问本地文件: {error}"),
        )
    })?;
    if !canonical_target.starts_with(&canonical_root) {
        return Err(WebError::bad_request_code(
            "local_file_root_escape",
            "本地文件读取不能越过授权目录",
        ));
    }
    if !canonical_target.is_file() {
        return Err(WebError::bad_request_code(
            "local_file_not_file",
            "本地文件读取目标必须是文件",
        ));
    }
    Ok(canonical_target)
}

pub(crate) fn ensure_local_workspace_access(
    context: &RequestContext,
    root_uri: &str,
) -> Result<PathBuf, WebError> {
    ensure_local_workspace_access_for_actor(
        &context.auth.actor_id,
        &context.auth.actor_type,
        root_uri,
    )
}

fn local_access_policy_path() -> PathBuf {
    std::env::var(ENV_LOCAL_ACCESS_POLICY_FILE)
        .ok()
        .map(|value| value.trim().to_string())
        .filter(|value| !value.is_empty())
        .map(PathBuf::from)
        .unwrap_or_else(|| {
            default_local_workspace_base_dir()
                .join("control-plane")
                .join("access-policy.json")
        })
}

pub(crate) fn local_access_policy_path_display() -> String {
    local_access_policy_path().display().to_string()
}

fn local_share_grants_path() -> PathBuf {
    std::env::var(ENV_SHARE_GRANTS_FILE)
        .ok()
        .map(|value| value.trim().to_string())
        .filter(|value| !value.is_empty())
        .map(PathBuf::from)
        .unwrap_or_else(|| {
            default_local_workspace_base_dir()
                .join("control-plane")
                .join("share-grants.json")
        })
}

fn load_local_access_policy() -> Result<LocalAccessPolicy, WebError> {
    let path = local_access_policy_path();
    if !path.exists() {
        return Ok(LocalAccessPolicy::default());
    }
    let content = fs::read_to_string(&path).map_err(|error| {
        WebError::bad_request_code(
            "local_access_policy_read_failed",
            format!("无法读取本地目录授权策略 {}: {error}", path.display()),
        )
    })?;
    serde_json::from_str::<LocalAccessPolicy>(&content).map_err(|error| {
        WebError::bad_request_code(
            "local_access_policy_invalid",
            format!("本地目录授权策略格式非法: {error}"),
        )
    })
}

fn load_local_share_grants_store() -> Result<LocalShareGrantsStore, WebError> {
    let path = local_share_grants_path();
    if !path.exists() {
        return Ok(LocalShareGrantsStore::default());
    }
    let content = fs::read_to_string(&path).map_err(|error| {
        WebError::bad_request_code(
            "local_share_grants_read_failed",
            format!("无法读取分享授权控制面 {}: {error}", path.display()),
        )
    })?;
    serde_json::from_str::<LocalShareGrantsStore>(&content).map_err(|error| {
        WebError::bad_request_code(
            "local_share_grants_invalid",
            format!("分享授权控制面格式非法: {error}"),
        )
    })
}

fn write_local_access_policy(policy: &LocalAccessPolicy) -> Result<(), WebError> {
    let path = local_access_policy_path();
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent).map_err(|error| {
            WebError::bad_request_code(
                "local_access_policy_dir_create_failed",
                format!("无法创建本地目录授权策略目录 {}: {error}", parent.display()),
            )
        })?;
    }
    let content = serde_json::to_string_pretty(policy)
        .map_err(|error| WebError::internal(format!("无法序列化本地目录授权策略: {error}")))?;
    fs::write(&path, format!("{content}\n")).map_err(|error| {
        WebError::bad_request_code(
            "local_access_policy_write_failed",
            format!("无法写入本地目录授权策略 {}: {error}", path.display()),
        )
    })
}

fn write_local_share_grants_store(store: &LocalShareGrantsStore) -> Result<(), WebError> {
    let path = local_share_grants_path();
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent).map_err(|error| {
            WebError::bad_request_code(
                "local_share_grants_dir_create_failed",
                format!("无法创建分享授权目录 {}: {error}", parent.display()),
            )
        })?;
    }
    let content = serde_json::to_string_pretty(store)
        .map_err(|error| WebError::internal(format!("无法序列化分享授权控制面: {error}")))?;
    fs::write(&path, format!("{content}\n")).map_err(|error| {
        WebError::bad_request_code(
            "local_share_grants_write_failed",
            format!("无法写入分享授权控制面 {}: {error}", path.display()),
        )
    })
}

fn require_local_access_policy_admin(
    context: &RequestContext,
) -> Result<LocalAccessPolicy, WebError> {
    let policy = load_local_access_policy()?;
    let actor_id = context.auth.actor_id.trim();
    let actor_type = context.auth.actor_type.trim();
    if actor_id.is_empty()
        || actor_id == "anonymous"
        || actor_type.is_empty()
        || actor_type == "anonymous"
    {
        return Err(WebError::new(
            StatusCode::UNAUTHORIZED,
            "local_access_policy_auth_required",
            "管理本地目录授权需要先登录",
        ));
    }
    if !is_local_admin(actor_id, actor_type, &policy) {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_access_policy_admin_required",
            "只有管理员可以管理本地目录授权",
        ));
    }
    Ok(policy)
}

fn require_share_grants_admin(context: &RequestContext) -> Result<(), WebError> {
    let policy = load_local_access_policy()?;
    let actor_id = context.auth.actor_id.trim();
    let actor_type = context.auth.actor_type.trim();
    if actor_id.is_empty()
        || actor_id == "anonymous"
        || actor_type.is_empty()
        || actor_type == "anonymous"
    {
        return Err(WebError::new(
            StatusCode::UNAUTHORIZED,
            "local_share_grants_auth_required",
            "管理分享授权需要先登录",
        ));
    }
    if !is_local_admin(actor_id, actor_type, &policy) {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_share_grants_admin_required",
            "只有管理员可以管理分享授权",
        ));
    }
    Ok(())
}

pub(crate) fn is_local_access_policy_admin_context(context: &RequestContext) -> bool {
    let actor_id = context.auth.actor_id.trim();
    let actor_type = context.auth.actor_type.trim();
    if actor_id.is_empty()
        || actor_id == "anonymous"
        || actor_type.is_empty()
        || actor_type == "anonymous"
    {
        return false;
    }
    let policy = load_local_access_policy().unwrap_or_default();
    is_local_admin(actor_id, actor_type, &policy)
}

fn env_local_admin_ids() -> Vec<String> {
    std::env::var(ENV_LOCAL_ADMIN_USER_IDS)
        .ok()
        .map(|value| {
            value
                .split([',', ';', '\n', ' '])
                .map(str::trim)
                .filter(|item| !item.is_empty())
                .map(ToOwned::to_owned)
                .collect::<Vec<_>>()
        })
        .unwrap_or_default()
}

fn canonical_root_from_admin_request(root_uri: &str, root_path: &str) -> Result<PathBuf, WebError> {
    let path = if !root_uri.trim().is_empty() {
        parse_file_root_uri(root_uri.trim())?
    } else if !root_path.trim().is_empty() {
        PathBuf::from(root_path.trim())
    } else {
        return Err(WebError::bad_request_code(
            "local_access_policy_root_required",
            "必须提供 rootUri 或 rootPath",
        ));
    };
    let canonical = path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_access_policy_root_unavailable",
            format!("无法访问授权目录: {error}"),
        )
    })?;
    if !canonical.is_dir() {
        return Err(WebError::bad_request_code(
            "local_access_policy_root_not_directory",
            "授权目标必须是目录",
        ));
    }
    Ok(canonical)
}

fn normalize_local_access_permission(permission: &str) -> Result<String, WebError> {
    let permission = permission.trim();
    match permission {
        "read" | "write" => Ok(permission.to_string()),
        _ => Err(WebError::bad_request_code(
            "local_access_policy_permission_invalid",
            "授权 permission 只能是 read 或 write",
        )),
    }
}

fn normalize_local_access_capabilities(capabilities: &[String]) -> Result<Vec<String>, WebError> {
    let mut normalized = Vec::new();
    for capability in capabilities {
        let capability = capability.trim();
        if capability.is_empty() {
            continue;
        }
        match capability {
            "ai" | "share" => {
                if !normalized.iter().any(|item| item == capability) {
                    normalized.push(capability.to_string());
                }
            }
            _ => {
                return Err(WebError::bad_request_code(
                    "local_access_policy_capability_invalid",
                    "授权 capability 只能是 ai 或 share",
                ));
            }
        }
    }
    normalized.sort();
    Ok(normalized)
}

fn generate_local_access_grant_id(user_id: &str, canonical_root: &Path) -> String {
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_millis();
    let mut hasher = DefaultHasher::new();
    user_id.hash(&mut hasher);
    canonical_root.display().to_string().hash(&mut hasher);
    format!("grant_{now}_{:x}", hasher.finish())
}

fn normalize_share_grant_permission(permission: &str) -> Result<String, WebError> {
    let permission = permission.trim();
    match permission {
        "read" | "write" => Ok(permission.to_string()),
        _ => Err(WebError::bad_request_code(
            "local_share_grant_permission_invalid",
            "分享授权 permission 只能是 read 或 write",
        )),
    }
}

fn normalize_share_grant_capabilities(capabilities: &[String]) -> Result<Vec<String>, WebError> {
    let mut normalized = Vec::new();
    for capability in capabilities {
        let capability = capability.trim();
        if capability.is_empty() {
            continue;
        }
        match capability {
            "ai" | "share" => {
                if !normalized.iter().any(|item| item == capability) {
                    normalized.push(capability.to_string());
                }
            }
            _ => {
                return Err(WebError::bad_request_code(
                    "local_share_grant_capability_invalid",
                    "分享授权 capability 只能是 ai 或 share",
                ));
            }
        }
    }
    normalized.sort();
    Ok(normalized)
}

fn generate_local_share_grant_id(share_id: &str, target_user_id: &str, root: &Path) -> String {
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_millis();
    let mut hasher = DefaultHasher::new();
    share_id.hash(&mut hasher);
    target_user_id.hash(&mut hasher);
    root.display().to_string().hash(&mut hasher);
    format!("share_grant_{now}_{:x}", hasher.finish())
}

fn share_grant_payload(grant: &LocalShareGrant) -> Value {
    json!({
        "id": grant.id,
        "shareId": grant.share_id,
        "ownerUserId": grant.owner_user_id,
        "targetUserId": grant.target_user_id,
        "rootUri": grant.root_uri,
        "rootPath": grant.root_path,
        "documentId": grant.document_id,
        "allowedResourceIds": grant.allowed_resource_ids,
        "permission": grant.permission,
        "capabilities": grant.capabilities,
        "createdAt": grant.created_at,
        "revokedAt": grant.revoked_at,
        "active": grant.active,
    })
}

fn list_local_share_grants_for_context(context: &RequestContext) -> Result<Value, WebError> {
    require_share_grants_admin(context)?;
    let store = load_local_share_grants_store()?;
    let grants = store
        .grants
        .iter()
        .map(share_grant_payload)
        .collect::<Vec<_>>();
    Ok(json!({
        "ok": true,
        "grantsPath": local_share_grants_path().display().to_string(),
        "grants": grants,
        "store": {
            "grants": grants,
        }
    }))
}

fn add_local_share_grant_for_context(
    context: &RequestContext,
    request: LocalShareGrantRequest,
) -> Result<Value, WebError> {
    require_share_grants_admin(context)?;
    let mut store = load_local_share_grants_store()?;
    let share_id = request.share_id.trim();
    let owner_user_id = request.owner_user_id.trim();
    let target_user_id = request.target_user_id.trim();
    if share_id.is_empty() {
        return Err(WebError::bad_request_code(
            "local_share_grant_share_id_required",
            "必须提供 shareId",
        ));
    }
    if owner_user_id.is_empty() || owner_user_id == "anonymous" {
        return Err(WebError::bad_request_code(
            "local_share_grant_owner_required",
            "必须提供有效 ownerUserId",
        ));
    }
    if target_user_id.is_empty() || target_user_id == "anonymous" {
        return Err(WebError::bad_request_code(
            "local_share_grant_target_required",
            "必须提供有效 targetUserId",
        ));
    }
    let canonical = canonical_root_from_admin_request(&request.root_uri, &request.root_path)?;
    let permission = normalize_share_grant_permission(&request.permission)?;
    let capabilities = normalize_share_grant_capabilities(&request.capabilities)?;
    let root_uri = file_uri_for_path(&canonical);
    let allowed_resource_ids = request
        .allowed_resource_ids
        .iter()
        .map(|item| item.trim().to_string())
        .filter(|item| !item.is_empty())
        .collect::<Vec<_>>();
    let grant_id = request.id.trim();
    let grant_id = if grant_id.is_empty() {
        generate_local_share_grant_id(share_id, target_user_id, &canonical)
    } else {
        grant_id.to_string()
    };
    if store
        .grants
        .iter()
        .any(|grant| grant.id.trim() == grant_id || grant.share_id.trim() == share_id)
    {
        return Err(WebError::bad_request_code(
            "local_share_grant_exists",
            "分享授权已存在",
        ));
    }
    let grant = LocalShareGrant {
        id: grant_id,
        share_id: share_id.to_string(),
        owner_user_id: owner_user_id.to_string(),
        target_user_id: target_user_id.to_string(),
        root_uri,
        root_path: canonical.display().to_string(),
        document_id: request.document_id.trim().to_string(),
        allowed_resource_ids,
        permission,
        capabilities,
        created_at: now_ms().to_string(),
        revoked_at: None,
        active: true,
    };
    store.grants.push(grant.clone());
    write_local_share_grants_store(&store)?;
    Ok(json!({
        "ok": true,
        "grantsPath": local_share_grants_path().display().to_string(),
        "grant": share_grant_payload(&grant),
        "store": store,
    }))
}

fn revoke_local_share_grant_for_context(
    context: &RequestContext,
    share_id: &str,
) -> Result<Value, WebError> {
    require_share_grants_admin(context)?;
    let mut store = load_local_share_grants_store()?;
    let share_id = share_id.trim();
    if share_id.is_empty() {
        return Err(WebError::bad_request_code(
            "local_share_grant_share_id_required",
            "必须提供 shareId",
        ));
    }
    let now = now_ms().to_string();
    let mut updated = None;
    for grant in &mut store.grants {
        if grant.share_id.trim() == share_id || grant.id.trim() == share_id {
            grant.active = false;
            grant.revoked_at = Some(now.clone());
            updated = Some(grant.clone());
            break;
        }
    }
    let grant = updated.ok_or_else(|| {
        WebError::new(
            StatusCode::NOT_FOUND,
            "local_share_grant_not_found",
            "未找到要撤销的分享授权",
        )
    })?;
    write_local_share_grants_store(&store)?;
    Ok(json!({
        "ok": true,
        "grantsPath": local_share_grants_path().display().to_string(),
        "revokedShareId": share_id,
        "grant": share_grant_payload(&grant),
        "store": store,
    }))
}

fn require_active_share_grant_for_actor(
    context: &RequestContext,
    root_uri: &str,
    share_id: &str,
) -> Result<LocalShareGrant, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_shared_cache_root_unavailable",
            format!("无法访问共享缓存 root: {error}"),
        )
    })?;
    let actor_id = context.auth.actor_id.trim();
    if actor_id.is_empty() || actor_id == "anonymous" {
        return Err(WebError::new(
            StatusCode::UNAUTHORIZED,
            "local_share_grant_auth_required",
            "访问共享缓存需要先登录",
        ));
    }
    let store = load_local_share_grants_store()?;
    let share_id = share_id.trim();
    let grant = store
        .grants
        .into_iter()
        .find(|grant| grant.share_id.trim() == share_id || grant.id.trim() == share_id)
        .ok_or_else(|| {
            WebError::new(
                StatusCode::FORBIDDEN,
                "local_share_grant_not_found",
                "未找到共享授权",
            )
        })?;
    if !grant.active || grant.revoked_at.as_deref().unwrap_or("").trim().len() > 0 {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_share_grant_revoked",
            "共享授权已撤销",
        ));
    }
    if grant.target_user_id.trim() != actor_id && grant.owner_user_id.trim() != actor_id {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_share_grant_actor_mismatch",
            "当前用户不在该共享授权范围内",
        ));
    }
    let Some(grant_root) = local_share_grant_root(&grant) else {
        return Err(WebError::bad_request_code(
            "local_share_grant_root_invalid",
            "共享授权 root 无效",
        ));
    };
    if grant_root != canonical_root {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_share_grant_root_mismatch",
            "共享授权 root 与请求 root 不一致",
        ));
    }
    Ok(grant)
}

fn local_share_grant_root(grant: &LocalShareGrant) -> Option<PathBuf> {
    let root = grant.root_uri.trim();
    let path = if !root.is_empty() {
        parse_file_root_uri(root).ok()?
    } else {
        let root_path = grant.root_path.trim();
        if root_path.is_empty() {
            return None;
        }
        PathBuf::from(root_path)
    };
    path.canonicalize().ok()
}

fn shared_cache_json_path(root: &Path) -> PathBuf {
    root.join(".mnote").join("share-cache.json")
}

fn sync_state_json_path(root: &Path) -> PathBuf {
    root.join(".mnote").join("sync-state.json")
}

fn sync_report_dir(root: &Path) -> PathBuf {
    root.join(".mnote").join("sync-reports")
}

fn read_json_or_default(path: &Path, default_value: Value) -> Value {
    fs::read_to_string(path)
        .ok()
        .and_then(|content| serde_json::from_str::<Value>(&content).ok())
        .unwrap_or(default_value)
}

fn write_json_file(path: &Path, value: &Value) -> Result<(), WebError> {
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent).map_err(|error| {
            WebError::bad_request_code(
                "local_sidecar_dir_create_failed",
                format!("无法创建本地 sidecar 目录 {}: {error}", parent.display()),
            )
        })?;
    }
    let content = serde_json::to_string_pretty(value)
        .map_err(|error| WebError::internal(format!("无法序列化本地 sidecar JSON: {error}")))?;
    fs::write(path, format!("{content}\n")).map_err(|error| {
        WebError::bad_request_code(
            "local_sidecar_write_failed",
            format!("无法写入本地 sidecar 文件 {}: {error}", path.display()),
        )
    })
}

fn record_shared_cache_for_context(
    context: &RequestContext,
    request: SharedCacheRecordRequest,
) -> Result<Value, WebError> {
    let grant =
        require_active_share_grant_for_actor(context, &request.root_uri, &request.share_id)?;
    let root = parse_file_root_uri(&request.root_uri)?
        .canonicalize()
        .map_err(|error| {
            WebError::bad_request_code(
                "local_shared_cache_root_unavailable",
                format!("无法访问共享缓存 root: {error}"),
            )
        })?;
    let permission = normalize_share_grant_permission(&request.permission)?;
    if permission != grant.permission.trim() {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_shared_cache_permission_mismatch",
            "共享缓存权限必须来自 canonical share grant",
        ));
    }
    let cache_entry = json!({
        "schema": "mnote.share_cache.v1",
        "shareId": grant.share_id,
        "permission": permission,
        "rootUri": grant.root_uri,
        "allowedResourceIds": grant.allowed_resource_ids,
        "remoteVersion": request.remote_version,
        "baseVersion": request.base_version,
        "sourceActor": request.source_actor,
        "syncedAt": now_ms(),
    });
    let path = shared_cache_json_path(&root);
    let mut cache = read_json_or_default(
        &path,
        json!({"schema": "mnote.share_cache.v1", "shares": {}}),
    );
    cache["shares"][grant.share_id.clone()] = cache_entry.clone();
    write_json_file(&path, &cache)?;
    Ok(json!({
        "ok": true,
        "path": path.display().to_string(),
        "share": cache_entry,
    }))
}

fn record_sync_pending_change_for_context(
    context: &RequestContext,
    request: SyncPendingChangeRequest,
) -> Result<Value, WebError> {
    let grant =
        require_active_share_grant_for_actor(context, &request.root_uri, &request.share_id)?;
    if normalize_share_grant_permission(&grant.permission)? != "write" {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_sync_shared_read_write_forbidden",
            "shared_read 不能记录待同步写入",
        ));
    }
    if !grant
        .allowed_resource_ids
        .iter()
        .any(|resource_id| resource_id == &request.resource_id)
    {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_sync_resource_not_shared",
            "待同步资源不在 share grant 授权范围内",
        ));
    }
    if !request.remote_version.trim().is_empty()
        && !request.base_version.trim().is_empty()
        && request.remote_version.trim() != request.base_version.trim()
    {
        return Err(WebError::new(
            StatusCode::CONFLICT,
            "local_sync_base_version_conflict",
            "同步前远端版本已变化，需要生成冲突报告",
        ));
    }
    let root = parse_file_root_uri(&request.root_uri)?
        .canonicalize()
        .map_err(|error| {
            WebError::bad_request_code(
                "local_sync_root_unavailable",
                format!("无法访问同步 root: {error}"),
            )
        })?;
    let path = sync_state_json_path(&root);
    let mut state = read_json_or_default(
        &path,
        json!({"schema": "mnote.sync_state.v1", "pendingChanges": []}),
    );
    let pending = json!({
        "shareId": grant.share_id,
        "resourceId": request.resource_id,
        "localVersion": request.local_version,
        "baseVersion": request.base_version,
        "remoteVersion": request.remote_version,
        "actorId": context.auth.actor_id,
        "changeSummary": request.change_summary,
        "createdAt": now_ms(),
    });
    state["pendingChanges"]
        .as_array_mut()
        .ok_or_else(|| {
            WebError::bad_request_code(
                "local_sync_state_invalid",
                "sync-state pendingChanges 非数组",
            )
        })?
        .push(pending.clone());
    write_json_file(&path, &state)?;
    Ok(json!({
        "ok": true,
        "path": path.display().to_string(),
        "pendingChange": pending,
    }))
}

fn write_sync_conflict_report_for_context(
    context: &RequestContext,
    request: SyncConflictReportRequest,
) -> Result<Value, WebError> {
    let grant =
        require_active_share_grant_for_actor(context, &request.root_uri, &request.share_id)?;
    if !grant
        .allowed_resource_ids
        .iter()
        .any(|resource_id| resource_id == &request.resource_id)
    {
        return Err(WebError::new(
            StatusCode::FORBIDDEN,
            "local_sync_report_resource_not_shared",
            "冲突报告资源不在 share grant 授权范围内",
        ));
    }
    let root = parse_file_root_uri(&request.root_uri)?
        .canonicalize()
        .map_err(|error| {
            WebError::bad_request_code(
                "local_sync_report_root_unavailable",
                format!("无法访问同步报告 root: {error}"),
            )
        })?;
    let report = json!({
        "schema": "mnote.sync_conflict_report.v1",
        "source": "shared_sync",
        "shareId": grant.share_id,
        "resourceId": request.resource_id,
        "localVersion": request.local_version,
        "remoteVersion": request.remote_version,
        "baseVersion": request.base_version,
        "actorId": if request.actor_id.trim().is_empty() { context.auth.actor_id.clone() } else { request.actor_id },
        "summary": request.summary,
        "createdAt": now_ms(),
        "suggestedActions": ["accept_local", "accept_remote", "open_diff_merge"],
    });
    let dir = sync_report_dir(&root);
    fs::create_dir_all(&dir).map_err(|error| {
        WebError::bad_request_code(
            "local_sync_report_dir_create_failed",
            format!("无法创建同步报告目录 {}: {error}", dir.display()),
        )
    })?;
    let path = dir.join(format!(
        "sync-conflict-{}-{}.json",
        sanitize_file_name(&grant.share_id, "share"),
        now_ms()
    ));
    write_json_file(&path, &report)?;
    Ok(json!({
        "ok": true,
        "path": path.display().to_string(),
        "report": report,
    }))
}

fn local_access_policy_payload(policy: &LocalAccessPolicy) -> Value {
    json!({
        "ok": true,
        "policyPath": local_access_policy_path().display().to_string(),
        "policy": policy,
        "effectiveAdmins": {
            "policy": &policy.admins,
            "env": env_local_admin_ids(),
        }
    })
}

fn validate_local_access_root_for_context(
    context: &RequestContext,
    request: LocalAccessValidateRootRequest,
) -> Result<Value, WebError> {
    let policy = require_local_access_policy_admin(context)?;
    let canonical = canonical_root_from_admin_request(&request.root_uri, &request.root_path)?;
    Ok(json!({
        "ok": true,
        "policyPath": local_access_policy_path().display().to_string(),
        "rootPath": canonical.display().to_string(),
        "rootUri": file_uri_for_path(&canonical),
        "admin": is_local_admin(&context.auth.actor_id, &context.auth.actor_type, &policy),
    }))
}

fn add_local_access_grant_for_context(
    context: &RequestContext,
    request: LocalAccessGrantRequest,
) -> Result<Value, WebError> {
    let mut policy = require_local_access_policy_admin(context)?;
    let user_id = request.user_id.trim();
    if user_id.is_empty() || user_id == "anonymous" {
        return Err(WebError::bad_request_code(
            "local_access_policy_user_required",
            "必须提供有效 userId",
        ));
    }
    let canonical = canonical_root_from_admin_request(&request.root_uri, &request.root_path)?;
    let permission = normalize_local_access_permission(&request.permission)?;
    let capabilities = normalize_local_access_capabilities(&request.capabilities)?;
    let root_uri = file_uri_for_path(&canonical);
    let grant_id = request.id.trim();
    let grant_id = if grant_id.is_empty() {
        generate_local_access_grant_id(user_id, &canonical)
    } else {
        grant_id.to_string()
    };
    if policy
        .grants
        .iter()
        .any(|grant| grant.id.trim() == grant_id)
    {
        return Err(WebError::bad_request_code(
            "local_access_policy_grant_id_exists",
            "授权 grantId 已存在",
        ));
    }
    if policy.grants.iter().any(|grant| {
        grant.user_id.trim() == user_id
            && grant.root_uri.trim() == root_uri
            && grant.permission.trim() == permission
            && grant.recursive == request.recursive
            && {
                let existing =
                    normalize_local_access_capabilities(&grant.capabilities).unwrap_or_default();
                existing == capabilities
            }
    }) {
        return Err(WebError::bad_request_code(
            "local_access_policy_grant_duplicate",
            "相同目录授权已存在",
        ));
    }
    let grant = LocalAccessGrant {
        id: grant_id,
        user_id: user_id.to_string(),
        root_uri,
        root_path: canonical.display().to_string(),
        permission,
        recursive: request.recursive,
        capabilities,
    };
    policy.grants.push(grant.clone());
    write_local_access_policy(&policy)?;
    Ok(json!({
        "ok": true,
        "policyPath": local_access_policy_path().display().to_string(),
        "grant": grant,
        "policy": policy,
    }))
}

fn delete_local_access_grant_for_context(
    context: &RequestContext,
    grant_id: &str,
) -> Result<Value, WebError> {
    let mut policy = require_local_access_policy_admin(context)?;
    let grant_id = grant_id.trim();
    if grant_id.is_empty() {
        return Err(WebError::bad_request_code(
            "local_access_policy_grant_id_required",
            "必须提供 grantId",
        ));
    }
    let before = policy.grants.len();
    policy.grants.retain(|grant| grant.id.trim() != grant_id);
    if policy.grants.len() == before {
        return Err(WebError::new(
            StatusCode::NOT_FOUND,
            "local_access_policy_grant_not_found",
            "未找到要删除的目录授权",
        ));
    }
    write_local_access_policy(&policy)?;
    Ok(json!({
        "ok": true,
        "policyPath": local_access_policy_path().display().to_string(),
        "deletedGrantId": grant_id,
        "policy": policy,
    }))
}

fn is_local_admin(actor_id: &str, actor_type: &str, policy: &LocalAccessPolicy) -> bool {
    if actor_type.trim() == "admin" {
        return true;
    }
    let actor_id = actor_id.trim();
    if actor_id.is_empty() {
        return false;
    }
    if policy.admins.iter().any(|admin| admin.trim() == actor_id) {
        return true;
    }
    std::env::var(ENV_LOCAL_ADMIN_USER_IDS)
        .ok()
        .map(|value| {
            value
                .split([',', ';', '\n', ' '])
                .map(str::trim)
                .filter(|item| !item.is_empty())
                .any(|item| item == actor_id)
        })
        .unwrap_or(false)
}

fn local_access_policy_allows(
    policy: &LocalAccessPolicy,
    actor_id: &str,
    canonical_root: &Path,
    mode: LocalAccessMode,
) -> bool {
    let actor_id = actor_id.trim();
    if actor_id.is_empty() {
        return false;
    }
    policy.grants.iter().any(|grant| {
        if grant.user_id.trim() != actor_id {
            return false;
        }
        if !local_access_permission_allows(grant.permission.as_str(), mode) {
            return false;
        }
        let Some(grant_root) = local_access_grant_root(grant) else {
            return false;
        };
        if grant.recursive {
            canonical_root.starts_with(&grant_root)
        } else {
            canonical_root == grant_root
        }
    })
}

fn local_access_permission_allows(permission: &str, mode: LocalAccessMode) -> bool {
    let permission = permission.trim();
    if permission == "admin" {
        return true;
    }
    match mode {
        LocalAccessMode::Read => permission == "read" || permission == "write",
        LocalAccessMode::Write => permission == "write",
    }
}

fn local_access_grant_root(grant: &LocalAccessGrant) -> Option<PathBuf> {
    let root = grant.root_uri.trim();
    let path = if !root.is_empty() {
        parse_file_root_uri(root).ok()?
    } else {
        let root_path = grant.root_path.trim();
        if root_path.is_empty() {
            return None;
        }
        PathBuf::from(root_path)
    };
    path.canonicalize().ok()
}

pub(crate) fn create_default_local_workspace_for_actor(
    actor_id: &str,
    actor_type: &str,
) -> Result<Value, WebError> {
    create_default_local_workspace_for_actor_at_base(
        actor_id,
        actor_type,
        &default_local_workspace_base_dir(),
    )
}

fn create_default_local_workspace_for_actor_at_base(
    actor_id: &str,
    actor_type: &str,
    base_dir: &Path,
) -> Result<Value, WebError> {
    let actor_id = actor_id.trim();
    let actor_type = actor_type.trim();
    if actor_id.is_empty()
        || actor_id == "anonymous"
        || actor_type.is_empty()
        || actor_type == "anonymous"
    {
        return Err(WebError::new(
            StatusCode::UNAUTHORIZED,
            "local_workspace_auth_required",
            "创建本地工作区需要先登录",
        ));
    }

    fs::create_dir_all(base_dir).map_err(|error| {
        WebError::bad_request_code(
            "local_workspace_base_create_failed",
            format!(
                "无法创建本地工作区数据根目录 {}: {error}",
                base_dir.display()
            ),
        )
    })?;
    let canonical_base = base_dir.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_workspace_base_unavailable",
            format!("无法访问本地工作区数据根目录: {error}"),
        )
    })?;
    let actor_segment = encode_local_id_segment(actor_id);
    let workspace_root = canonical_base
        .join("users")
        .join(&actor_segment)
        .join("workspaces")
        .join(DEFAULT_LOCAL_WORKSPACE_SLUG);
    fs::create_dir_all(&workspace_root).map_err(|error| {
        WebError::bad_request_code(
            "local_workspace_create_failed",
            format!(
                "无法创建默认本地工作区 {}: {error}",
                workspace_root.display()
            ),
        )
    })?;
    let canonical_root = workspace_root.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_workspace_unavailable",
            format!("无法访问默认本地工作区: {error}"),
        )
    })?;
    if !canonical_root.starts_with(&canonical_base) {
        return Err(WebError::bad_request_code(
            "local_workspace_root_escape",
            "默认本地工作区不能越过受管数据根目录",
        ));
    }

    let manifest = ensure_default_workspace_manifest(actor_id, &canonical_root)?;
    ensure_default_workspace_directories(&canonical_root)?;
    ensure_default_workspace_home_page(&canonical_root)?;
    Ok(json!({
        "ok": true,
        "workspace": {
            "rootUri": file_uri_for_path(&canonical_root),
            "rootPath": canonical_root.display().to_string(),
            "baseDir": canonical_base.display().to_string(),
            "manifest": local_workspace_manifest_json(&manifest),
        }
    }))
}

pub async fn create_default_local_workspace(
    Extension(context): Extension<RequestContext>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload =
        create_default_local_workspace_for_actor(&context.auth.actor_id, &context.auth.actor_type)
            .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn get_local_access_policy(
    Extension(context): Extension<RequestContext>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let policy = require_local_access_policy_admin(&context)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(local_access_policy_payload(&policy))))
}

pub async fn validate_local_access_root(
    Extension(context): Extension<RequestContext>,
    Json(request): Json<LocalAccessValidateRootRequest>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = validate_local_access_root_for_context(&context, request)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn create_local_access_grant(
    Extension(context): Extension<RequestContext>,
    Json(request): Json<LocalAccessGrantRequest>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = add_local_access_grant_for_context(&context, request)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn delete_local_access_grant(
    Extension(context): Extension<RequestContext>,
    AxumPath(grant_id): AxumPath<String>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = delete_local_access_grant_for_context(&context, &grant_id)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn get_share_grants(
    Extension(context): Extension<RequestContext>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = list_local_share_grants_for_context(&context)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn create_share_grant(
    Extension(context): Extension<RequestContext>,
    Json(request): Json<LocalShareGrantRequest>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = add_local_share_grant_for_context(&context, request)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn delete_share_grant(
    Extension(context): Extension<RequestContext>,
    AxumPath(share_id): AxumPath<String>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = revoke_local_share_grant_for_context(&context, &share_id)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn record_shared_cache(
    Extension(context): Extension<RequestContext>,
    Json(request): Json<SharedCacheRecordRequest>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = record_shared_cache_for_context(&context, request)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn record_sync_pending_change(
    Extension(context): Extension<RequestContext>,
    Json(request): Json<SyncPendingChangeRequest>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = record_sync_pending_change_for_context(&context, request)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

pub async fn write_sync_conflict_report(
    Extension(context): Extension<RequestContext>,
    Json(request): Json<SyncConflictReportRequest>,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let payload = write_sync_conflict_report_for_context(&context, request)
        .map_err(|error| error.with_context(&context))?;
    Ok((StatusCode::OK, Json(payload)))
}

#[cfg(test)]
pub(crate) fn initialize_local_workspace_for_actor(
    actor_id: &str,
    root_uri: &str,
) -> Result<Value, WebError> {
    let actor_id = actor_id.trim();
    if actor_id.is_empty() || actor_id == "anonymous" {
        return Err(WebError::new(
            StatusCode::UNAUTHORIZED,
            "local_workspace_auth_required",
            "创建本地工作区需要先登录",
        ));
    }
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    if !canonical_root.is_dir() {
        return Err(WebError::bad_request_code(
            "local_folder_not_directory",
            "本地 rootUri 必须指向目录",
        ));
    }
    let manifest_path = local_workspace_manifest_path(&canonical_root);
    if manifest_path.exists() {
        let manifest = load_local_workspace_manifest(&canonical_root)?;
        if manifest.owner_id.trim() != actor_id {
            return Err(WebError::new(
                StatusCode::FORBIDDEN,
                "local_workspace_access_denied",
                "当前用户无权接管该本地工作区",
            ));
        }
        return Ok(local_workspace_manifest_json(&manifest));
    }
    let manifest = LocalWorkspaceManifest {
        workspace_id: format!(
            "local-ws:{}",
            encode_local_id_segment(&format!("{}:{}", actor_id, canonical_root.display()))
        ),
        owner_id: actor_id.to_string(),
        created_at: now_ms().to_string(),
        capabilities: vec![
            "local_files".to_string(),
            "tree_commands".to_string(),
            "markdown_edit".to_string(),
            "asset_upload".to_string(),
        ],
    };
    write_local_workspace_manifest(&canonical_root, &manifest)?;
    Ok(local_workspace_manifest_json(&manifest))
}

fn default_local_workspace_base_dir() -> PathBuf {
    std::env::var("MNOTE_LOCAL_WORKSPACE_BASE_DIR")
        .ok()
        .map(|value| value.trim().to_string())
        .filter(|value| !value.is_empty())
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from(DEFAULT_LOCAL_WORKSPACE_BASE_DIR))
}

fn ensure_default_workspace_manifest(
    actor_id: &str,
    root: &Path,
) -> Result<LocalWorkspaceManifest, WebError> {
    let manifest_path = local_workspace_manifest_path(root);
    if manifest_path.exists() {
        let manifest = load_local_workspace_manifest(root)?;
        if manifest.owner_id.trim() != actor_id {
            return Err(WebError::new(
                StatusCode::FORBIDDEN,
                "local_workspace_access_denied",
                "当前用户无权接管该本地工作区",
            ));
        }
        return Ok(manifest);
    }
    let manifest = LocalWorkspaceManifest {
        workspace_id: format!(
            "local-ws:{}:{}",
            encode_local_id_segment(actor_id),
            DEFAULT_LOCAL_WORKSPACE_SLUG
        ),
        owner_id: actor_id.to_string(),
        created_at: now_ms().to_string(),
        capabilities: vec![
            "local_files".to_string(),
            "tree_commands".to_string(),
            "markdown_edit".to_string(),
            "asset_upload".to_string(),
        ],
    };
    write_local_workspace_manifest(root, &manifest)?;
    Ok(manifest)
}

fn ensure_default_workspace_directories(root: &Path) -> Result<(), WebError> {
    for relative in [
        "pages",
        "assets/shared",
        "assets/imports",
        "mindmaps",
        "ai-sessions/private",
        "ai-sessions/shared",
        ".mnote/trash",
    ] {
        let path = root.join(relative);
        if !path.starts_with(root) {
            return Err(WebError::bad_request_code(
                "local_workspace_root_escape",
                "默认本地工作区目录不能越过 root",
            ));
        }
        fs::create_dir_all(&path).map_err(|error| {
            WebError::bad_request_code(
                "local_workspace_create_failed",
                format!("无法创建默认本地工作区目录 {}: {error}", path.display()),
            )
        })?;
    }
    Ok(())
}

fn ensure_default_workspace_home_page(root: &Path) -> Result<(), WebError> {
    let page = root.join("pages").join("我的空间.md");
    if page.exists() {
        return Ok(());
    }
    if !page.starts_with(root) {
        return Err(WebError::bad_request_code(
            "local_workspace_root_escape",
            "默认本地工作区首页不能越过 root",
        ));
    }
    let content = "---\ntitle: 我的空间\nmnote_id: my-space-home\n---\n# 我的空间\n\n";
    fs::write(&page, content).map_err(|error| {
        WebError::bad_request_code(
            "local_workspace_create_failed",
            format!("无法创建默认本地工作区首页 {}: {error}", page.display()),
        )
    })
}

fn local_workspace_manifest_path(root: &Path) -> PathBuf {
    root.join(".mnote").join("workspace.json")
}

fn load_local_workspace_manifest(root: &Path) -> Result<LocalWorkspaceManifest, WebError> {
    let manifest_path = local_workspace_manifest_path(root);
    let content = fs::read_to_string(&manifest_path).map_err(|error| {
        WebError::new(
            StatusCode::FORBIDDEN,
            "local_workspace_manifest_missing",
            format!("缺少本地工作区清单 {}: {error}", manifest_path.display()),
        )
    })?;
    let manifest = serde_json::from_str::<LocalWorkspaceManifest>(&content).map_err(|error| {
        WebError::bad_request_code(
            "local_workspace_manifest_invalid",
            format!("本地工作区清单格式非法: {error}"),
        )
    })?;
    if manifest.workspace_id.trim().is_empty() || manifest.owner_id.trim().is_empty() {
        return Err(WebError::bad_request_code(
            "local_workspace_manifest_invalid",
            "本地工作区清单缺少 workspaceId / ownerId",
        ));
    }
    Ok(manifest)
}

fn write_local_workspace_manifest(
    root: &Path,
    manifest: &LocalWorkspaceManifest,
) -> Result<(), WebError> {
    let metadata_dir = root.join(".mnote");
    fs::create_dir_all(&metadata_dir).map_err(|error| {
        WebError::bad_request_code(
            "local_workspace_manifest_write_failed",
            format!(
                "无法创建本地工作区元数据目录 {}: {error}",
                metadata_dir.display()
            ),
        )
    })?;
    let manifest_path = local_workspace_manifest_path(root);
    let content = serde_json::to_string_pretty(manifest)
        .map_err(|error| WebError::internal(format!("本地工作区清单序列化失败: {error}")))?;
    fs::write(&manifest_path, content).map_err(|error| {
        WebError::bad_request_code(
            "local_workspace_manifest_write_failed",
            format!(
                "无法写入本地工作区清单 {}: {error}",
                manifest_path.display()
            ),
        )
    })
}

fn local_workspace_manifest_json(manifest: &LocalWorkspaceManifest) -> Value {
    json!({
        "workspaceId": manifest.workspace_id,
        "ownerId": manifest.owner_id,
        "createdAt": manifest.created_at,
        "capabilities": manifest.capabilities,
    })
}

pub fn load_local_folder_file_tree_snapshot(
    root_uri: &str,
) -> Result<ProjectionSnapshot, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    if !canonical_root.is_dir() {
        return Err(WebError::bad_request_code(
            "local_folder_not_directory",
            "本地 rootUri 必须指向目录",
        ));
    }

    let workspace_id = local_workspace_id(&canonical_root);
    let root_source_uri = file_uri_for_path(&canonical_root);
    let metadata = load_local_folder_metadata(&canonical_root)?;
    let mut rows = Vec::new();
    scan_directory(
        &canonical_root,
        &canonical_root,
        None,
        0,
        &root_source_uri,
        &workspace_id,
        &metadata,
        &mut rows,
    )?;

    let items = rows
        .iter()
        .map(local_folder_row_to_projection_item)
        .collect::<Vec<_>>();
    let watch_revision = local_folder_watch_revision_for_root(&canonical_root, &root_source_uri)?;
    let dataset = json!({
        "workspace": {
            "id": &workspace_id,
            "sourceKind": "local_folder",
            "rootUri": root_source_uri,
        },
        "nodes": [],
        "edges": [],
        "documents": [],
        "media_assets": [],
        "mindmap_assets": [],
        "table_assets": [],
        "mindmap_asset_children": {},
    });
    let projection = json!({
        "projection": "file_tree",
        "sourceKind": "local_folder",
        "rootUri": root_source_uri,
        "watchRevision": watch_revision,
        "items": items,
    });

    Ok(ProjectionSnapshot {
        dataset,
        projection,
    })
}

pub fn load_local_folder_page_tree_snapshot(
    root_uri: &str,
) -> Result<ProjectionSnapshot, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    if !canonical_root.is_dir() {
        return Err(WebError::bad_request_code(
            "local_folder_not_directory",
            "本地 rootUri 必须指向目录",
        ));
    }

    let workspace_id = local_workspace_id(&canonical_root);
    let root_source_uri = file_uri_for_path(&canonical_root);
    let metadata = load_local_folder_metadata(&canonical_root)?;
    let mut rows = Vec::new();
    scan_markdown_page_tree(
        &canonical_root,
        &canonical_root,
        None,
        0,
        &metadata,
        &mut rows,
        &workspace_id,
        &root_source_uri,
    )?;
    let child_counts = rows
        .iter()
        .filter_map(|row| row.parent_node_id.as_ref())
        .fold(
            std::collections::BTreeMap::<String, u32>::new(),
            |mut acc, parent| {
                *acc.entry(parent.clone()).or_default() += 1;
                acc
            },
        );
    for row in &mut rows {
        row.child_count = child_counts.get(&row.node_id).copied().unwrap_or(0);
        row.expandable = row.child_count > 0;
        row.expanded_by_default = row.expandable && row.depth < 2;
    }

    let items = rows
        .iter()
        .map(local_folder_row_to_projection_item)
        .collect::<Vec<_>>();
    let watch_revision = local_folder_watch_revision_for_root(&canonical_root, &root_source_uri)?;
    Ok(ProjectionSnapshot {
        dataset: json!({
            "workspace": {
                "id": local_workspace_id(&canonical_root),
                "sourceKind": "local_folder",
                "rootUri": root_source_uri,
            },
            "documents": rows
                .iter()
                .filter_map(|row| {
                    row.document_id.as_ref().map(|document_id| {
                        json!({
                            "id": document_id,
                            "workspace_id": local_workspace_id(&canonical_root),
                            "title": row.title,
                            "parent_id": row.parent_node_id,
                            "sort_order": row.position,
                        })
                    })
                })
                .collect::<Vec<_>>(),
        }),
        projection: json!({
            "projection": "page_tree",
            "sourceKind": "local_folder",
            "rootUri": root_source_uri,
            "watchRevision": watch_revision,
            "items": items,
        }),
    })
}

pub fn local_folder_watch_revision(root_uri: &str) -> Result<LocalFolderWatchRevision, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    if !canonical_root.is_dir() {
        return Err(WebError::bad_request_code(
            "local_folder_not_directory",
            "本地 rootUri 必须指向目录",
        ));
    }
    let root_source_uri = file_uri_for_path(&canonical_root);
    local_folder_watch_revision_for_root(&canonical_root, &root_source_uri)
}

pub fn resolve_local_markdown_page_aggregate(
    root_uri: &str,
    document_id: &str,
) -> Result<PageAggregate, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    if !canonical_root.is_dir() {
        return Err(WebError::bad_request_code(
            "local_folder_not_directory",
            "本地 rootUri 必须指向目录",
        ));
    }
    let metadata = load_local_folder_metadata(&canonical_root)?;
    let markdown_file = find_markdown_by_page_id(&canonical_root, &metadata, document_id)?
        .ok_or_else(|| {
            WebError::bad_request_code(
                "local_markdown_not_found",
                "找不到本地 Markdown 页面对应的文件",
            )
        })?;
    let markdown = fs::read_to_string(&markdown_file.path).map_err(|error| {
        WebError::bad_request_code(
            "local_markdown_read_failed",
            format!(
                "无法读取本地 Markdown 文件 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    let parsed = parse_markdown_page(&markdown, &markdown_file.file_name);
    let title = parsed.title;
    let content = crate::routes::local_markdown_parser::markdown_to_blocks(&parsed.body);
    let block_count = content.as_array().map(|blocks| blocks.len()).unwrap_or(0) as u64;
    let page_subtree = markdown_page_subtree(document_id, &title, &content);
    let workspace_id = local_workspace_id(&canonical_root);
    let page_options = metadata
        .page_options
        .get(document_id)
        .or_else(|| metadata.page_options.get(&markdown_file.relative_path))
        .map(page_options_from_metadata)
        .unwrap_or_default();
    let character_count = parsed.body.chars().count() as u64;
    let word_count = parsed
        .body
        .split_whitespace()
        .filter(|word| !word.trim().is_empty())
        .count() as u64;
    let read_only = markdown_file.is_readonly;

    let block_document =
        project_legacy_content_to_block_document(document_id, &content, &Value::Number(0.into()))
            .map_err(|error| WebError::internal(format!("{error:?}")))?;

    let conflict_detection_key =
        local_markdown_conflict_detection_key(document_id, &markdown_file.path)?;

    Ok(PageAggregate {
        schema: PageAggregate::SCHEMA.into(),
        projection_version: PageAggregate::VERSION,
        source: PageAggregateSource::KernelProjection,
        page_id: document_id.to_string(),
        parent_id: None,
        title: title.clone(),
        path: vec![document_id.to_string()],
        sidebar_tree_membership: vec!["page-tree".into(), "file-tree".into()],
        body_ref: Some(format!("local-md:{document_id}")),
        layout_options: serde_json::to_value(&page_options).unwrap_or_else(|_| json!({})),
        updated_at: None,
        identity: PageIdentity {
            document_id: document_id.to_string(),
            workspace_id,
        },
        head: PageHead {
            title,
            updated_at: Value::Null,
            permissions: PagePermissions {
                read_only,
                disable_download: false,
                disable_copy: false,
            },
        },
        layout: PageLayout { page_options },
        body: PageBody {
            content,
            revision: Value::Number(0.into()),
            conflict_detection_key: Value::String(conflict_detection_key.clone()),
            file_version: Value::String(conflict_detection_key),
            block_document,
            block_projection_version: 1,
            projection_source: "local_markdown.content".into(),
        },
        tree: PageTree { page_subtree },
        stats: PageStats {
            word_count,
            character_count,
            block_count,
            todo_total: 0,
            todo_done: 0,
        },
    })
}

pub fn save_local_markdown_page(
    root_uri: &str,
    document_id: &str,
    expected_conflict_detection_key: Option<&str>,
    content: &Value,
) -> Result<Value, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    let metadata = load_local_folder_metadata(&canonical_root)?;
    let markdown_file = find_markdown_by_page_id(&canonical_root, &metadata, document_id)?
        .ok_or_else(|| {
            WebError::bad_request_code(
                "local_markdown_not_found",
                "找不到要保存的本地 Markdown 页面",
            )
        })?;
    let current = fs::read_to_string(&markdown_file.path).map_err(|error| {
        WebError::bad_request_code(
            "local_markdown_read_failed",
            format!(
                "无法读取本地 Markdown 文件 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    let current_conflict_key =
        local_markdown_conflict_detection_key(document_id, &markdown_file.path)?;
    if let Some(expected_key) = expected_conflict_detection_key
        .map(str::trim)
        .filter(|value| !value.is_empty())
    {
        if expected_key != current_conflict_key {
            return Err(local_markdown_conflict_error(
                root_uri,
                document_id,
                expected_key,
                &current_conflict_key,
            ));
        }
    }
    let (frontmatter, _) = split_frontmatter(&current);
    let body = editor_blocks_to_markdown(content);
    let next_markdown = if let Some(frontmatter) = frontmatter {
        format!("---\n{frontmatter}\n---\n{body}")
    } else {
        body
    };
    fs::write(&markdown_file.path, next_markdown).map_err(|error| {
        WebError::bad_request_code(
            "local_markdown_write_failed",
            format!(
                "无法保存本地 Markdown 文件 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    let workspace_id = local_workspace_id(&canonical_root);
    refresh_local_search_index_best_effort(&canonical_root, root_uri, &workspace_id);
    let next_conflict_key =
        local_markdown_conflict_detection_key(document_id, &markdown_file.path)?;
    Ok(json!({
        "ok": true,
        "documentId": document_id,
        "revision": now_ms(),
        "conflict_detection_key": next_conflict_key,
        "fileVersion": next_conflict_key,
        "executedCommand": "page.body.save",
        "canonicalCommand": "page.body.save",
        "sourceKind": "local_folder",
    }))
}

fn refresh_local_search_index_best_effort(root: &Path, root_uri: &str, workspace_id: &str) {
    let _ = local_search_index::refresh_local_search_index(root, root_uri, workspace_id);
}

fn local_markdown_conflict_error(
    root_uri: &str,
    document_id: &str,
    editor_base_version: &str,
    current_disk_version: &str,
) -> WebError {
    WebError::new(
        StatusCode::CONFLICT,
        "local_markdown_external_change",
        "本地 Markdown 文件已被外部修改，请刷新后再保存",
    )
    .with_details(json!({
        "conflict": {
            "code": "local_markdown_external_change",
            "documentId": document_id,
            "rootUri": root_uri,
            "currentDiskVersion": current_disk_version,
            "editorBaseVersion": editor_base_version,
            "suggestedActions": [
                "accept_disk",
                "keep_editor",
                "open_diff",
                "merge"
            ]
        }
    }))
}

pub fn write_local_markdown_page_body(
    request: &core_protocol::PageBodyWriteRequest,
) -> Result<Value, WebError> {
    if request.source_kind != core_protocol::WorkspaceSourceKind::LocalFolder {
        return Err(WebError::bad_request_code(
            "page_body_write_source_unsupported",
            "page.body.write 当前只支持 local_folder 本地写入",
        ));
    }
    if request.content_format.trim() != "editorBlocks" {
        return Err(WebError::bad_request_code(
            "page_body_write_content_format_unsupported",
            "page.body.write 当前只支持 editorBlocks 内容格式",
        ));
    }

    let mut result = save_local_markdown_page(
        &request.root_uri,
        &request.document_id,
        request.expected_file_version.as_deref(),
        &request.content,
    )?;
    if let Value::Object(map) = &mut result {
        map.insert("canonicalCommand".into(), json!("page.body.write"));
        map.insert("compatCommand".into(), json!("page.body.save"));
        map.insert("contentFormat".into(), json!(request.content_format));
        map.insert(
            "editorSource".into(),
            request
                .editor_source
                .as_deref()
                .map(Value::from)
                .unwrap_or(Value::Null),
        );
        map.insert(
            "baseContentHash".into(),
            request
                .base_content_hash
                .as_deref()
                .map(Value::from)
                .unwrap_or(Value::Null),
        );
    }
    Ok(result)
}

pub async fn upload_local_markdown_asset(
    Extension(context): Extension<RequestContext>,
    multipart: Multipart,
) -> Result<(StatusCode, Json<Value>), WebError> {
    let fields = read_local_asset_upload_multipart(multipart).await?;
    ensure_local_workspace_access(&context, &fields.root_uri)
        .map_err(|error| error.with_context(&context))?;
    let asset = write_local_markdown_asset(
        &fields.root_uri,
        &fields.document_id,
        &fields.kind,
        fields.file,
    )?;
    Ok((StatusCode::OK, Json(json!({ "ok": true, "asset": asset }))))
}

pub async fn open_local_file(
    Extension(context): Extension<RequestContext>,
    Query(query): Query<LocalFileOpenQuery>,
) -> Result<(StatusCode, HeaderMap, Vec<u8>), WebError> {
    ensure_local_workspace_read_access(&context, &query.root_uri)
        .map_err(|error| error.with_context(&context))?;
    let target = resolve_local_file_open_path(&query.root_uri, &query.path)?;
    let bytes = fs::read(&target).map_err(|error| {
        WebError::bad_request_code(
            "local_file_open_read_failed",
            format!("无法读取本地文件 {}: {error}", target.display()),
        )
        .with_context(&context)
    })?;
    let mut headers = HeaderMap::new();
    headers.insert(
        header::CONTENT_TYPE,
        HeaderValue::from_static("application/octet-stream"),
    );
    if query.download.unwrap_or(false) {
        headers.insert(
            header::CONTENT_DISPOSITION,
            HeaderValue::from_static("attachment"),
        );
    }
    Ok((StatusCode::OK, headers, bytes))
}

fn resolve_local_file_open_path(root_uri: &str, relative_path: &str) -> Result<PathBuf, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    let requested = Path::new(relative_path);
    if requested.is_absolute()
        || requested
            .components()
            .any(|component| matches!(component, std::path::Component::ParentDir))
    {
        return Err(WebError::bad_request_code(
            "local_file_open_root_escape",
            "本地文件路径不能越过 root",
        ));
    }
    let target = canonical_root
        .join(requested)
        .canonicalize()
        .map_err(|error| {
            WebError::bad_request_code(
                "local_file_open_not_found",
                format!("找不到本地文件: {error}"),
            )
        })?;
    if !target.starts_with(&canonical_root) {
        return Err(WebError::bad_request_code(
            "local_file_open_root_escape",
            "本地文件路径不能越过 root",
        ));
    }
    if target.is_dir() {
        return Err(WebError::bad_request_code(
            "local_file_open_is_directory",
            "不能直接读取本地目录",
        ));
    }
    Ok(target)
}

async fn read_local_asset_upload_multipart(
    mut multipart: Multipart,
) -> Result<LocalAssetUploadFields, WebError> {
    let mut file: Option<LocalUploadFile> = None;
    let mut root_uri = String::new();
    let mut document_id = String::new();
    let mut kind = String::new();

    while let Some(field) = multipart.next_field().await.map_err(|error| {
        WebError::bad_request_code(
            "local_asset_upload_bad_multipart",
            format!("上传表单解析失败: {error}"),
        )
    })? {
        let name = field.name().unwrap_or_default().to_string();
        if name == "file" {
            let file_name = field
                .file_name()
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .unwrap_or("附件")
                .to_string();
            let content_type = field
                .content_type()
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .unwrap_or("application/octet-stream")
                .to_string();
            let bytes = field
                .bytes()
                .await
                .map_err(|error| {
                    WebError::bad_request_code(
                        "local_asset_upload_file_read_failed",
                        format!("读取上传文件失败: {error}"),
                    )
                })?
                .to_vec();
            file = Some(LocalUploadFile {
                name: file_name,
                content_type,
                bytes,
            });
            continue;
        }

        let value = field.text().await.map_err(|error| {
            WebError::bad_request_code(
                "local_asset_upload_field_read_failed",
                format!("读取上传字段失败: {error}"),
            )
        })?;
        match name.as_str() {
            "rootUri" => root_uri = value.trim().to_string(),
            "documentId" => document_id = value.trim().to_string(),
            "kind" => kind = value.trim().to_string(),
            _ => {}
        }
    }

    let file = file.ok_or_else(|| {
        WebError::bad_request_code("local_asset_upload_file_missing", "缺少 file")
    })?;
    if file.bytes.is_empty() || root_uri.is_empty() || document_id.is_empty() {
        return Err(WebError::bad_request_code(
            "local_asset_upload_required_missing",
            "缺少必要参数",
        ));
    }
    Ok(LocalAssetUploadFields {
        file,
        root_uri,
        document_id,
        kind,
    })
}

pub(crate) fn write_local_markdown_asset(
    root_uri: &str,
    document_id: &str,
    kind: &str,
    file: LocalUploadFile,
) -> Result<Value, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    if !canonical_root.is_dir() {
        return Err(WebError::bad_request_code(
            "local_folder_not_directory",
            "本地 rootUri 必须指向目录",
        ));
    }

    let metadata = load_local_folder_metadata(&canonical_root)?;
    let markdown_file = find_markdown_by_page_id(&canonical_root, &metadata, document_id)?
        .ok_or_else(|| {
            WebError::bad_request_code(
                "local_markdown_not_found",
                "找不到本地 Markdown 页面对应的文件",
            )
        })?;
    let markdown_dir = markdown_file.path.parent().ok_or_else(|| {
        WebError::bad_request_code(
            "local_asset_upload_bad_markdown_path",
            "本地 Markdown 文件路径无父目录",
        )
    })?;
    if !markdown_dir.starts_with(&canonical_root) {
        return Err(WebError::bad_request_code(
            "local_folder_root_escape",
            "本地 Markdown 文件路径不在 root 内",
        ));
    }

    let markdown_stem = Path::new(&markdown_file.file_name)
        .file_stem()
        .and_then(|value| value.to_str())
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .unwrap_or("page");
    let asset_dir_name = format!("{}.assets", sanitize_file_name(markdown_stem, "page"));
    let asset_dir = markdown_dir.join(asset_dir_name);
    if !asset_dir.starts_with(&canonical_root) {
        return Err(WebError::bad_request_code(
            "local_folder_root_escape",
            "本地资源目录不能越过 root",
        ));
    }
    fs::create_dir_all(&asset_dir).map_err(|error| {
        WebError::bad_request_code(
            "local_asset_upload_create_dir_failed",
            format!("无法创建本地资源目录 {}: {error}", asset_dir.display()),
        )
    })?;

    let sanitized_name = sanitize_file_name(&file.name, "附件");
    let target = next_available_asset_path(&asset_dir, &sanitized_name);
    if !target.starts_with(&canonical_root) {
        return Err(WebError::bad_request_code(
            "local_folder_root_escape",
            "本地资源文件不能越过 root",
        ));
    }
    fs::write(&target, &file.bytes).map_err(|error| {
        WebError::bad_request_code(
            "local_asset_upload_write_failed",
            format!("无法写入本地资源文件 {}: {error}", target.display()),
        )
    })?;

    let root_relative_path = normalize_relative_path(&canonical_root, &target)?;
    let markdown_relative_path = normalize_markdown_relative_asset_path(markdown_dir, &target)?;
    let asset_type = local_upload_asset_type(kind, &file.content_type);
    Ok(json!({
        "id": format!("local:asset:{root_relative_path}"),
        "asset_type": asset_type,
        "file_name": target.file_name().and_then(|value| value.to_str()).unwrap_or(&sanitized_name),
        "mime_type": file.content_type,
        "file_size": file.bytes.len(),
        "file_url": markdown_relative_path,
        "sourcePath": markdown_relative_path,
        "document_id": document_id,
        "documentId": document_id,
        "sourceKind": "local_folder",
        "rootUri": file_uri_for_path(&canonical_root),
        "rootRelativePath": root_relative_path,
    }))
}

pub fn update_local_markdown_title(
    root_uri: &str,
    document_id: &str,
    title: &str,
) -> Result<Value, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    let metadata = load_local_folder_metadata(&canonical_root)?;
    let markdown_file = find_markdown_by_page_id(&canonical_root, &metadata, document_id)?
        .ok_or_else(|| {
            WebError::bad_request_code(
                "local_markdown_not_found",
                "找不到要更新标题的本地 Markdown 页面",
            )
        })?;
    let current = fs::read_to_string(&markdown_file.path).map_err(|error| {
        WebError::bad_request_code(
            "local_markdown_read_failed",
            format!(
                "无法读取本地 Markdown 文件 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    fs::write(
        &markdown_file.path,
        markdown_with_frontmatter_fields(&current, &[("title", title.trim())]),
    )
    .map_err(|error| {
        WebError::bad_request_code(
            "local_markdown_write_failed",
            format!(
                "无法写入本地 Markdown 标题 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    let workspace_id = local_workspace_id(&canonical_root);
    refresh_local_search_index_best_effort(&canonical_root, root_uri, &workspace_id);
    Ok(json!({
        "ok": true,
        "documentId": document_id,
        "title": title.trim(),
        "updated_at": Value::Null,
        "sourceKind": "local_folder",
    }))
}

pub fn update_local_page_options(
    root_uri: &str,
    document_id: &str,
    options: &Value,
) -> Result<Value, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    let mut metadata = load_local_folder_metadata(&canonical_root)?;
    metadata
        .page_options
        .insert(document_id.to_string(), options.clone());
    write_page_options_metadata(&canonical_root, &metadata.page_options)?;
    Ok(json!({
        "ok": true,
        "documentId": document_id,
        "options": options,
        "updated_at": Value::Null,
        "sourceKind": "local_folder",
    }))
}

pub fn execute_local_tree_command(
    root_uri: &str,
    action: &str,
    document_id: &str,
    parent_id: Option<&str>,
    title: Option<&str>,
) -> Result<Value, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    let result = match action {
        "create" => {
            create_local_markdown_page(&canonical_root, parent_id, title.unwrap_or("新页面"))
        }
        "createFolder" | "create_folder" | "folder.create" => {
            create_local_folder(&canonical_root, parent_id, title.unwrap_or("新建文件夹"))
        }
        "rename" => rename_local_entry(&canonical_root, document_id, title.unwrap_or("无标题")),
        "copy" => {
            copy_local_markdown_page(&canonical_root, document_id, parent_id, title.unwrap_or(""))
        }
        "dropFiles" | "drop_files" => drop_external_files_into_local_folder(
            &canonical_root,
            parent_id,
            title.unwrap_or("外部文件"),
        ),
        "move" => move_local_entry(&canonical_root, document_id, parent_id),
        "delete" | "trash" => trash_local_entry(&canonical_root, document_id),
        "restore" => restore_local_entry(&canonical_root, document_id),
        "purge" => purge_local_entry(&canonical_root, document_id),
        other => Err(WebError::bad_request_code(
            "local_tree_command_unsupported",
            format!("local_folder 暂不支持 tree action: {other}"),
        )),
    }?;
    let workspace_id = local_workspace_id(&canonical_root);
    refresh_local_search_index_best_effort(&canonical_root, root_uri, &workspace_id);
    Ok(result)
}

fn create_local_markdown_page(
    root: &Path,
    parent_id: Option<&str>,
    title: &str,
) -> Result<Value, WebError> {
    let metadata = load_local_folder_metadata(root)?;
    let parent_directory = resolve_local_parent_directory(root, &metadata, parent_id)?;
    let safe_title = sanitize_file_stem(title, "新页面");
    let target = next_available_path(&parent_directory, &safe_title, "md");
    let relative_path = normalize_relative_path(root, &target)?;
    let page_id = normalize_metadata_page_id(&format!(
        "local-mdid:{}",
        encode_local_id_segment(&format!("{}:{relative_path}", local_workspace_id(root)))
    ));
    let markdown = markdown_with_frontmatter_fields(
        &format!("# {}\n", title.trim()),
        &[("mnote_id", page_id.as_str()), ("title", title.trim())],
    );
    fs::write(&target, markdown).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法创建本地 Markdown 文件 {}: {error}", target.display()),
        )
    })?;
    let mut page_ids = metadata.page_ids;
    page_ids.insert(relative_path.clone(), page_id.clone());
    write_page_ids_metadata(root, &page_ids)?;
    Ok(json!({
        "ok": true,
        "id": page_id,
        "documentId": page_id,
        "relativePath": relative_path,
        "action": "create",
        "sourceKind": "local_folder",
    }))
}

fn create_local_folder(
    root: &Path,
    parent_id: Option<&str>,
    title: &str,
) -> Result<Value, WebError> {
    let metadata = load_local_folder_metadata(root)?;
    let parent_directory = resolve_local_parent_directory(root, &metadata, parent_id)?;
    let target =
        next_available_directory_path(&parent_directory, &sanitize_file_stem(title, "新建文件夹"));
    fs::create_dir_all(&target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法创建本地文件夹 {}: {error}", target.display()),
        )
    })?;
    Ok(json!({
        "ok": true,
        "id": local_directory_group_id(&normalize_relative_path(root, &target)?),
        "relativePath": normalize_relative_path(root, &target)?,
        "action": "createFolder",
        "sourceKind": "local_folder",
    }))
}

fn rename_local_entry(root: &Path, document_id: &str, title: &str) -> Result<Value, WebError> {
    if let Some(directory) = resolve_local_directory_id(root, document_id)? {
        return rename_local_directory(root, &directory, title);
    }
    if let Some(file) = resolve_local_raw_file_id(root, document_id)? {
        return rename_local_raw_file(root, &file, title);
    }
    rename_local_markdown_page(root, document_id, title)
}

fn rename_local_raw_file(root: &Path, file: &Path, title: &str) -> Result<Value, WebError> {
    let parent = file.parent().ok_or_else(|| {
        WebError::bad_request_code("local_tree_command_failed", "无法解析文件父目录")
    })?;
    let original_extension = file
        .extension()
        .and_then(|value| value.to_str())
        .unwrap_or("");
    let requested_name = sanitize_file_name(title, "文件");
    let requested_has_extension = Path::new(&requested_name).extension().is_some();
    let target_name = if requested_has_extension || original_extension.is_empty() {
        requested_name
    } else {
        format!(
            "{}.{}",
            sanitize_file_stem(&requested_name, "文件"),
            original_extension
        )
    };
    let target = next_available_raw_path(parent, &target_name);
    fs::rename(file, &target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法重命名本地文件 {}: {error}", file.display()),
        )
    })?;
    Ok(json!({
        "ok": true,
        "id": local_node_id(&normalize_relative_path(root, &target)?),
        "relativePath": normalize_relative_path(root, &target)?,
        "action": "rename",
        "sourceKind": "local_folder",
    }))
}

fn rename_local_markdown_page(
    root: &Path,
    document_id: &str,
    title: &str,
) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    let markdown_file =
        find_markdown_by_page_id(root, &metadata, document_id)?.ok_or_else(|| {
            WebError::bad_request_code(
                "local_markdown_not_found",
                "找不到要重命名的本地 Markdown 页面",
            )
        })?;
    let parent = markdown_file.path.parent().ok_or_else(|| {
        WebError::bad_request_code("local_tree_command_failed", "无法解析 Markdown 父目录")
    })?;
    let target = next_available_path(parent, &sanitize_file_stem(title, "无标题"), "md");
    let old_relative_path = markdown_file.relative_path;
    fs::rename(&markdown_file.path, &target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!(
                "无法重命名本地 Markdown 文件 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    let new_relative_path = normalize_relative_path(root, &target)?;
    metadata.page_ids.remove(&old_relative_path);
    metadata
        .page_ids
        .insert(new_relative_path.clone(), document_id.to_string());
    write_page_ids_metadata(root, &metadata.page_ids)?;
    Ok(json!({
        "ok": true,
        "id": document_id,
        "documentId": document_id,
        "relativePath": new_relative_path,
        "action": "rename",
        "sourceKind": "local_folder",
    }))
}

fn rename_local_directory(root: &Path, directory: &Path, title: &str) -> Result<Value, WebError> {
    if directory == root {
        return Err(WebError::bad_request_code(
            "local_tree_command_failed",
            "不能重命名本地 workspace root",
        ));
    }
    let mut metadata = load_local_folder_metadata(root)?;
    let parent = directory.parent().ok_or_else(|| {
        WebError::bad_request_code("local_tree_command_failed", "无法解析文件夹父目录")
    })?;
    let target = next_available_directory_path(parent, &sanitize_file_stem(title, "文件夹"));
    let old_relative_path = normalize_relative_path(root, directory)?;
    fs::rename(directory, &target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法重命名本地文件夹 {}: {error}", directory.display()),
        )
    })?;
    let new_relative_path = normalize_relative_path(root, &target)?;
    rewrite_page_ids_prefix(
        &mut metadata.page_ids,
        &old_relative_path,
        &new_relative_path,
    );
    write_page_ids_metadata(root, &metadata.page_ids)?;
    Ok(json!({
        "ok": true,
        "id": local_directory_group_id(&new_relative_path),
        "relativePath": new_relative_path,
        "action": "rename",
        "sourceKind": "local_folder",
    }))
}

fn copy_local_markdown_page(
    root: &Path,
    document_id: &str,
    parent_id: Option<&str>,
    title: &str,
) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    let markdown_file =
        find_markdown_by_page_id(root, &metadata, document_id)?.ok_or_else(|| {
            WebError::bad_request_code(
                "local_markdown_not_found",
                "找不到要复制的本地 Markdown 页面",
            )
        })?;
    let target_directory = resolve_local_parent_directory(root, &metadata, parent_id)?;
    let source_stem = markdown_file
        .path
        .file_stem()
        .and_then(|stem| stem.to_str())
        .unwrap_or("页面");
    let copy_stem = if title.trim().is_empty() {
        source_stem
    } else {
        title.trim()
    };
    let target = next_available_path(
        &target_directory,
        &sanitize_file_stem(copy_stem, "页面"),
        "md",
    );
    let new_relative_path = normalize_relative_path(root, &target)?;
    let new_page_id = normalize_metadata_page_id(&format!(
        "local-mdid:{}",
        encode_local_id_segment(&format!("{}:{new_relative_path}", local_workspace_id(root)))
    ));
    let source_markdown = fs::read_to_string(&markdown_file.path).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!(
                "无法读取待复制 Markdown 文件 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    fs::write(
        &target,
        markdown_with_frontmatter_fields(&source_markdown, &[("mnote_id", new_page_id.as_str())]),
    )
    .map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法复制本地 Markdown 文件到 {}: {error}", target.display()),
        )
    })?;
    metadata
        .page_ids
        .insert(new_relative_path.clone(), new_page_id.clone());
    write_page_ids_metadata(root, &metadata.page_ids)?;
    Ok(json!({
        "ok": true,
        "id": new_page_id,
        "documentId": new_page_id,
        "relativePath": new_relative_path,
        "action": "copy",
        "sourceKind": "local_folder",
    }))
}

fn move_local_entry(
    root: &Path,
    document_id: &str,
    parent_id: Option<&str>,
) -> Result<Value, WebError> {
    if let Some(directory) = resolve_local_directory_id(root, document_id)? {
        return move_local_directory(root, &directory, parent_id);
    }
    move_local_markdown_page(root, document_id, parent_id)
}

fn move_local_markdown_page(
    root: &Path,
    document_id: &str,
    parent_id: Option<&str>,
) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    let markdown_file =
        find_markdown_by_page_id(root, &metadata, document_id)?.ok_or_else(|| {
            WebError::bad_request_code(
                "local_markdown_not_found",
                "找不到要移动的本地 Markdown 页面",
            )
        })?;
    let target_directory = resolve_local_parent_directory(root, &metadata, parent_id)?;
    if markdown_file.path.parent() == Some(target_directory.as_path()) {
        return Ok(json!({
            "ok": true,
            "id": document_id,
            "documentId": document_id,
            "relativePath": markdown_file.relative_path,
            "action": "move",
            "sourceKind": "local_folder",
        }));
    }
    let file_name = markdown_file
        .path
        .file_stem()
        .and_then(|stem| stem.to_str())
        .map(|stem| sanitize_file_stem(stem, "页面"))
        .unwrap_or_else(|| "页面".to_string());
    let target = next_available_path(&target_directory, &file_name, "md");
    if target == markdown_file.path {
        return Ok(json!({
            "ok": true,
            "id": document_id,
            "documentId": document_id,
            "relativePath": markdown_file.relative_path,
            "action": "move",
            "sourceKind": "local_folder",
        }));
    }
    if target.starts_with(&markdown_file.path) {
        return Err(WebError::bad_request_code(
            "local_tree_command_failed",
            "禁止把本地页面移动到自身或后代",
        ));
    }
    let old_relative_path = markdown_file.relative_path;
    fs::rename(&markdown_file.path, &target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!(
                "无法移动本地 Markdown 文件 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    let new_relative_path = normalize_relative_path(root, &target)?;
    metadata.page_ids.remove(&old_relative_path);
    metadata
        .page_ids
        .insert(new_relative_path.clone(), document_id.to_string());
    write_page_ids_metadata(root, &metadata.page_ids)?;
    Ok(json!({
        "ok": true,
        "id": document_id,
        "documentId": document_id,
        "relativePath": new_relative_path,
        "action": "move",
        "sourceKind": "local_folder",
    }))
}

fn move_local_directory(
    root: &Path,
    directory: &Path,
    parent_id: Option<&str>,
) -> Result<Value, WebError> {
    if directory == root {
        return Err(WebError::bad_request_code(
            "local_tree_command_failed",
            "不能移动本地 workspace root",
        ));
    }
    let mut metadata = load_local_folder_metadata(root)?;
    let target_directory = resolve_local_parent_directory(root, &metadata, parent_id)?;
    if target_directory == directory || target_directory.starts_with(directory) {
        return Err(WebError::bad_request_code(
            "local_tree_command_failed",
            "禁止把本地文件夹移动到自身或后代",
        ));
    }
    if directory.parent() == Some(target_directory.as_path()) {
        return Ok(json!({
            "ok": true,
            "id": local_directory_group_id(&normalize_relative_path(root, directory)?),
            "relativePath": normalize_relative_path(root, directory)?,
            "action": "move",
            "sourceKind": "local_folder",
        }));
    }
    let stem = directory
        .file_name()
        .and_then(|name| name.to_str())
        .map(|name| sanitize_file_stem(name, "文件夹"))
        .unwrap_or_else(|| "文件夹".to_string());
    let target = next_available_directory_path(&target_directory, &stem);
    let old_relative_path = normalize_relative_path(root, directory)?;
    fs::rename(directory, &target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法移动本地文件夹 {}: {error}", directory.display()),
        )
    })?;
    let new_relative_path = normalize_relative_path(root, &target)?;
    rewrite_page_ids_prefix(
        &mut metadata.page_ids,
        &old_relative_path,
        &new_relative_path,
    );
    write_page_ids_metadata(root, &metadata.page_ids)?;
    Ok(json!({
        "ok": true,
        "id": local_directory_group_id(&new_relative_path),
        "relativePath": new_relative_path,
        "action": "move",
        "sourceKind": "local_folder",
    }))
}

fn trash_local_entry(root: &Path, entry_id: &str) -> Result<Value, WebError> {
    if let Some(file) = resolve_local_raw_file_id(root, entry_id)? {
        return trash_local_raw_file(root, entry_id, &file);
    }
    trash_local_markdown_page(root, entry_id)
}

fn restore_local_entry(root: &Path, entry_id: &str) -> Result<Value, WebError> {
    let metadata = load_local_folder_metadata(root)?;
    if find_local_file_trash_entry_key(&metadata, entry_id).is_some() {
        return restore_local_raw_file(root, entry_id);
    }
    restore_local_markdown_page(root, entry_id)
}

fn purge_local_entry(root: &Path, entry_id: &str) -> Result<Value, WebError> {
    let metadata = load_local_folder_metadata(root)?;
    if find_local_file_trash_entry_key(&metadata, entry_id).is_some() {
        return purge_local_raw_file(root, entry_id);
    }
    if entry_id.starts_with("local:asset:") || entry_id.starts_with("local:node:") {
        return Err(WebError::bad_request_code(
            "local_trash_entry_not_found",
            "本地资源必须先进入回收站后才能永久删除",
        ));
    }
    purge_local_markdown_page(root, entry_id)
}

fn trash_local_markdown_page(root: &Path, document_id: &str) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    let markdown_file =
        find_markdown_by_page_id(root, &metadata, document_id)?.ok_or_else(|| {
            WebError::bad_request_code(
                "local_markdown_not_found",
                "找不到要删除的本地 Markdown 页面",
            )
        })?;
    let trash_dir = root.join(".mnote").join("trash");
    fs::create_dir_all(&trash_dir).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法创建本地回收站 {}: {error}", trash_dir.display()),
        )
    })?;
    let file_name = markdown_file
        .path
        .file_name()
        .and_then(|name| name.to_str())
        .unwrap_or("page.md");
    let target = next_available_path(&trash_dir, &file_stem_title(file_name), "md");
    fs::rename(&markdown_file.path, &target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!(
                "无法移动到本地回收站 {}: {error}",
                markdown_file.path.display()
            ),
        )
    })?;
    let trash_relative_path = normalize_relative_path(root, &target)?;
    metadata.page_ids.remove(&markdown_file.relative_path);
    metadata.trash_entries.insert(
        document_id.to_string(),
        LocalTrashEntry {
            document_id: document_id.to_string(),
            resource_kind: "markdown".to_string(),
            resource_scope: "local_folder".to_string(),
            original_file_path: markdown_file.relative_path.clone(),
            trashed_file_path: trash_relative_path.clone(),
            trash_entry_id: document_id.to_string(),
            original_relative_path: markdown_file.relative_path,
            trash_relative_path: trash_relative_path.clone(),
            deleted_at_ms: now_ms(),
            archived_at: now_ms(),
            purged_at: None,
        },
    );
    write_page_ids_metadata(root, &metadata.page_ids)?;
    write_trash_index_metadata(root, &metadata.trash_entries)?;
    Ok(json!({
        "ok": true,
        "id": document_id,
        "documentId": document_id,
        "trashPath": trash_relative_path,
        "action": "delete",
        "sourceKind": "local_folder",
    }))
}

fn trash_local_raw_file(root: &Path, entry_id: &str, file: &Path) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    let relative_path = normalize_relative_path(root, file)?;
    if is_markdown_file(&relative_path) {
        return Err(WebError::bad_request_code(
            "local_file_resource_not_supported",
            "Markdown 文件必须走页面生命周期，不能走 local_file 资源回收站",
        ));
    }
    let trash_dir = root.join(".mnote").join("trash");
    fs::create_dir_all(&trash_dir).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法创建本地回收站 {}: {error}", trash_dir.display()),
        )
    })?;
    let file_name = file
        .file_name()
        .and_then(|name| name.to_str())
        .unwrap_or("local-file");
    let target = next_available_raw_path(&trash_dir, file_name);
    fs::rename(file, &target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法移动本地资源到回收站 {}: {error}", file.display()),
        )
    })?;
    let trash_relative_path = normalize_relative_path(root, &target)?;
    let trash_entry_id = local_file_trash_entry_id(&relative_path);
    let now = now_ms();
    metadata.trash_entries.insert(
        trash_entry_id.clone(),
        LocalTrashEntry {
            document_id: entry_id.to_string(),
            resource_kind: "local_file".to_string(),
            resource_scope: "local_folder".to_string(),
            original_file_path: relative_path.clone(),
            trashed_file_path: trash_relative_path.clone(),
            trash_entry_id: trash_entry_id.clone(),
            original_relative_path: relative_path.clone(),
            trash_relative_path: trash_relative_path.clone(),
            deleted_at_ms: now,
            archived_at: now,
            purged_at: None,
        },
    );
    write_trash_index_metadata(root, &metadata.trash_entries)?;
    Ok(json!({
        "ok": true,
        "id": entry_id,
        "documentId": entry_id,
        "resourceKind": "local_file",
        "resourceScope": "local_folder",
        "originalFilePath": relative_path,
        "trashEntryId": trash_entry_id,
        "trashPath": trash_relative_path,
        "action": "delete",
        "canonicalCommand": "tree.resource.archive",
        "sourceKind": "local_folder",
    }))
}

fn restore_local_markdown_page(root: &Path, document_id: &str) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    let trash_entry = metadata
        .trash_entries
        .get(document_id)
        .cloned()
        .ok_or_else(|| {
            WebError::bad_request_code(
                "local_trash_entry_not_found",
                "找不到要恢复的本地回收站记录",
            )
        })?;
    let trash_path = resolve_metadata_relative_path(root, &trash_entry.trash_relative_path)?;
    if !trash_path.is_file() {
        return Err(WebError::bad_request_code(
            "local_trash_entry_not_found",
            "本地回收站文件不存在，无法恢复",
        ));
    }
    let original_path = resolve_metadata_relative_path(root, &trash_entry.original_relative_path)?;
    let parent = original_path.parent().ok_or_else(|| {
        WebError::bad_request_code("local_tree_command_failed", "无法解析恢复目标目录")
    })?;
    fs::create_dir_all(parent).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法创建恢复目标目录 {}: {error}", parent.display()),
        )
    })?;
    let stem = original_path
        .file_stem()
        .and_then(|stem| stem.to_str())
        .map(|stem| sanitize_file_stem(stem, "页面"))
        .unwrap_or_else(|| "页面".to_string());
    let target = if original_path.exists() {
        next_available_path(parent, &stem, "md")
    } else {
        original_path
    };
    fs::rename(&trash_path, &target).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法从本地回收站恢复 {}: {error}", trash_path.display()),
        )
    })?;
    let restored_relative_path = normalize_relative_path(root, &target)?;
    metadata
        .page_ids
        .insert(restored_relative_path.clone(), document_id.to_string());
    metadata.trash_entries.remove(document_id);
    write_page_ids_metadata(root, &metadata.page_ids)?;
    write_trash_index_metadata(root, &metadata.trash_entries)?;
    Ok(json!({
        "ok": true,
        "id": document_id,
        "documentId": document_id,
        "relativePath": restored_relative_path,
        "action": "restore",
        "sourceKind": "local_folder",
    }))
}

fn restore_local_raw_file(root: &Path, entry_id: &str) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    let trash_key = find_local_file_trash_entry_key(&metadata, entry_id).ok_or_else(|| {
        WebError::bad_request_code(
            "local_trash_entry_not_found",
            "找不到要恢复的本地资源回收站记录",
        )
    })?;
    let trash_entry = metadata
        .trash_entries
        .get(&trash_key)
        .cloned()
        .ok_or_else(|| {
            WebError::bad_request_code(
                "local_trash_entry_not_found",
                "找不到要恢复的本地资源回收站记录",
            )
        })?;
    let original_relative_path = local_trash_original_path(&trash_entry);
    let trash_relative_path = local_trash_file_path(&trash_entry);
    let trash_path = resolve_metadata_relative_path(root, &trash_relative_path)?;
    if !trash_path.is_file() {
        return Err(WebError::bad_request_code(
            "local_trash_entry_not_found",
            "本地资源回收站文件不存在，无法恢复",
        ));
    }
    let original_path = resolve_metadata_relative_path(root, &original_relative_path)?;
    if original_path.exists() {
        return Err(WebError::new(
            StatusCode::CONFLICT,
            "local_file_restore_conflict",
            "本地资源原路径已存在，恢复会覆盖用户文件",
        ));
    }
    let parent = original_path.parent().ok_or_else(|| {
        WebError::bad_request_code("local_tree_command_failed", "无法解析资源恢复目标目录")
    })?;
    fs::create_dir_all(parent).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法创建资源恢复目标目录 {}: {error}", parent.display()),
        )
    })?;
    fs::rename(&trash_path, &original_path).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("无法从本地回收站恢复资源 {}: {error}", trash_path.display()),
        )
    })?;
    metadata.trash_entries.remove(&trash_key);
    write_trash_index_metadata(root, &metadata.trash_entries)?;
    Ok(json!({
        "ok": true,
        "id": entry_id,
        "documentId": entry_id,
        "resourceKind": "local_file",
        "resourceScope": "local_folder",
        "originalFilePath": original_relative_path,
        "relativePath": normalize_relative_path(root, &original_path)?,
        "trashEntryId": trash_key,
        "action": "restore",
        "canonicalCommand": "tree.resource.restore",
        "sourceKind": "local_folder",
    }))
}

fn purge_local_markdown_page(root: &Path, document_id: &str) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    if let Some(markdown_file) = find_markdown_by_page_id(root, &metadata, document_id)? {
        fs::remove_file(&markdown_file.path).map_err(|error| {
            WebError::bad_request_code(
                "local_tree_command_failed",
                format!(
                    "无法永久删除本地 Markdown 文件 {}: {error}",
                    markdown_file.path.display()
                ),
            )
        })?;
        metadata.page_ids.remove(&markdown_file.relative_path);
        write_page_ids_metadata(root, &metadata.page_ids)?;
        return Ok(json!({
            "ok": true,
            "id": document_id,
            "documentId": document_id,
            "action": "purge",
            "sourceKind": "local_folder",
        }));
    }
    let trash_entry = metadata.trash_entries.remove(document_id).ok_or_else(|| {
        WebError::bad_request_code(
            "local_markdown_not_found",
            "找不到要永久删除的本地 Markdown 页面",
        )
    })?;
    let trash_path = resolve_metadata_relative_path(root, &trash_entry.trash_relative_path)?;
    if trash_path.exists() {
        fs::remove_file(&trash_path).map_err(|error| {
            WebError::bad_request_code(
                "local_tree_command_failed",
                format!(
                    "无法永久删除本地回收站文件 {}: {error}",
                    trash_path.display()
                ),
            )
        })?;
    }
    write_trash_index_metadata(root, &metadata.trash_entries)?;
    Ok(json!({
        "ok": true,
        "id": document_id,
        "documentId": document_id,
        "action": "purge",
        "sourceKind": "local_folder",
    }))
}

fn purge_local_raw_file(root: &Path, entry_id: &str) -> Result<Value, WebError> {
    let mut metadata = load_local_folder_metadata(root)?;
    let trash_key = find_local_file_trash_entry_key(&metadata, entry_id).ok_or_else(|| {
        WebError::bad_request_code(
            "local_trash_entry_not_found",
            "找不到要永久删除的本地资源回收站记录",
        )
    })?;
    let trash_entry = metadata.trash_entries.remove(&trash_key).ok_or_else(|| {
        WebError::bad_request_code(
            "local_trash_entry_not_found",
            "找不到要永久删除的本地资源回收站记录",
        )
    })?;
    let trash_relative_path = local_trash_file_path(&trash_entry);
    let trash_path = resolve_metadata_relative_path(root, &trash_relative_path)?;
    if trash_path.exists() {
        fs::remove_file(&trash_path).map_err(|error| {
            WebError::bad_request_code(
                "local_tree_command_failed",
                format!(
                    "无法永久删除本地资源回收站文件 {}: {error}",
                    trash_path.display()
                ),
            )
        })?;
    }
    write_trash_index_metadata(root, &metadata.trash_entries)?;
    Ok(json!({
        "ok": true,
        "id": entry_id,
        "documentId": entry_id,
        "resourceKind": "local_file",
        "resourceScope": "local_folder",
        "trashEntryId": trash_key,
        "action": "purge",
        "canonicalCommand": "tree.resource.purge",
        "sourceKind": "local_folder",
    }))
}

fn resolve_local_parent_directory(
    root: &Path,
    metadata: &LocalFolderMetadata,
    parent_id: Option<&str>,
) -> Result<PathBuf, WebError> {
    let Some(parent_id) = parent_id.map(str::trim).filter(|value| !value.is_empty()) else {
        return Ok(root.to_path_buf());
    };
    if let Some(encoded) = parent_id.strip_prefix("local-dir:") {
        let relative_path = decode_local_id_segment(encoded)?;
        let directory = root.join(relative_path);
        if directory.starts_with(root) && directory.is_dir() {
            return Ok(directory);
        }
    }
    if let Some(relative_path) = parent_id.strip_prefix("local:node:") {
        let directory = resolve_metadata_relative_path(root, relative_path)?;
        if directory.is_dir() {
            return Ok(directory);
        }
    }
    if let Some(relative_path) = parent_id.strip_prefix("local:folder:") {
        let directory = resolve_metadata_relative_path(root, relative_path)?;
        if directory.is_dir() {
            return Ok(directory);
        }
    }
    if let Some(markdown_file) = find_markdown_by_page_id(root, metadata, parent_id)? {
        if let Some(parent) = markdown_file.path.parent() {
            return Ok(parent.to_path_buf());
        }
    }
    Err(WebError::bad_request_code(
        "local_tree_command_failed",
        "无法解析本地新建目标目录",
    ))
}

fn drop_external_files_into_local_folder(
    root: &Path,
    parent_id: Option<&str>,
    files_json: &str,
) -> Result<Value, WebError> {
    let metadata = load_local_folder_metadata(root)?;
    let target_directory = resolve_local_parent_directory(root, &metadata, parent_id)?;
    let files = serde_json::from_str::<Vec<LocalDropFilePayload>>(files_json).map_err(|error| {
        WebError::bad_request_code(
            "local_tree_command_failed",
            format!("外部拖入文件 payload 非法: {error}"),
        )
    })?;
    if files.is_empty() {
        return Err(WebError::bad_request_code(
            "local_tree_command_failed",
            "外部拖入文件不能为空",
        ));
    }
    let mut written = Vec::new();
    for file in files {
        let name = sanitize_file_name(&file.name, "dropped-file");
        let path = next_available_raw_path(&target_directory, &name);
        fs::write(&path, file.text.unwrap_or_default()).map_err(|error| {
            WebError::bad_request_code(
                "local_tree_command_failed",
                format!("无法写入外部拖入文件 {}: {error}", path.display()),
            )
        })?;
        written.push(json!({
            "name": name,
            "relativePath": normalize_relative_path(root, &path)?,
        }));
    }
    Ok(json!({
        "ok": true,
        "action": "dropFiles",
        "files": written,
        "sourceKind": "local_folder",
    }))
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct LocalDropFilePayload {
    name: String,
    text: Option<String>,
}

fn resolve_local_directory_id(root: &Path, entry_id: &str) -> Result<Option<PathBuf>, WebError> {
    let trimmed = entry_id.trim();
    if let Some(relative_path) = trimmed
        .strip_prefix("local:node:")
        .or_else(|| trimmed.strip_prefix("local:folder:"))
    {
        let directory = resolve_metadata_relative_path(root, relative_path)?;
        if directory.is_dir() {
            return Ok(Some(directory));
        }
        if directory.is_file() {
            return Ok(None);
        }
        return Err(WebError::bad_request_code(
            "local_tree_command_failed",
            "本地文件夹不存在",
        ));
    }
    let Some(encoded) = trimmed.strip_prefix("local-dir:") else {
        return Ok(None);
    };
    let relative_path = decode_local_id_segment(encoded)?;
    let directory = resolve_metadata_relative_path(root, &relative_path)?;
    if directory.is_dir() {
        Ok(Some(directory))
    } else {
        Err(WebError::bad_request_code(
            "local_tree_command_failed",
            "本地文件夹不存在",
        ))
    }
}

fn resolve_local_raw_file_id(root: &Path, entry_id: &str) -> Result<Option<PathBuf>, WebError> {
    let trimmed = entry_id.trim();
    let Some(relative_path) = trimmed
        .strip_prefix("local:node:")
        .or_else(|| trimmed.strip_prefix("local:asset:"))
    else {
        return Ok(None);
    };
    let file = resolve_metadata_relative_path(root, relative_path)?;
    if file.is_file() {
        Ok(Some(file))
    } else {
        Err(WebError::bad_request_code(
            "local_tree_command_failed",
            "本地文件不存在",
        ))
    }
}

fn local_file_trash_entry_id(relative_path: &str) -> String {
    format!("local-file:{relative_path}")
}

fn is_local_file_trash_entry(entry: &LocalTrashEntry) -> bool {
    entry.resource_kind == "local_file" || entry.trash_entry_id.starts_with("local-file:")
}

fn local_trash_original_path(entry: &LocalTrashEntry) -> String {
    if !entry.original_file_path.trim().is_empty() {
        entry.original_file_path.clone()
    } else {
        entry.original_relative_path.clone()
    }
}

fn local_trash_file_path(entry: &LocalTrashEntry) -> String {
    if !entry.trashed_file_path.trim().is_empty() {
        entry.trashed_file_path.clone()
    } else {
        entry.trash_relative_path.clone()
    }
}

fn find_local_file_trash_entry_key(
    metadata: &LocalFolderMetadata,
    entry_id: &str,
) -> Option<String> {
    let trimmed = entry_id.trim();
    if metadata
        .trash_entries
        .get(trimmed)
        .map(is_local_file_trash_entry)
        .unwrap_or(false)
    {
        return Some(trimmed.to_string());
    }
    let relative_path = trimmed
        .strip_prefix("local:asset:")
        .or_else(|| trimmed.strip_prefix("local:node:"))
        .unwrap_or(trimmed);
    let expected_key = local_file_trash_entry_id(relative_path);
    if metadata
        .trash_entries
        .get(&expected_key)
        .map(is_local_file_trash_entry)
        .unwrap_or(false)
    {
        return Some(expected_key);
    }
    metadata
        .trash_entries
        .iter()
        .find(|(_, entry)| {
            is_local_file_trash_entry(entry) && local_trash_original_path(entry) == relative_path
        })
        .map(|(key, _)| key.clone())
}

pub fn local_workspace_id_from_root_uri(root_uri: &str) -> Result<String, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    Ok(local_workspace_id(&canonical_root))
}

fn parse_file_root_uri(root_uri: &str) -> Result<PathBuf, WebError> {
    let trimmed = root_uri.trim();
    if trimmed.is_empty() {
        return Err(WebError::bad_request_code(
            "local_folder_root_required",
            "缺少本地文件夹 rootUri",
        ));
    }
    let Some(path) = trimmed.strip_prefix("file://") else {
        return Err(WebError::bad_request_code(
            "local_folder_root_invalid",
            "本地文件夹 rootUri 必须使用 file://",
        ));
    };
    if path.trim().is_empty() {
        return Err(WebError::bad_request_code(
            "local_folder_root_invalid",
            "本地文件夹 rootUri 不能为空",
        ));
    }
    Ok(PathBuf::from(percent_decode_file_uri_path(path)?))
}

fn percent_decode_file_uri_path(value: &str) -> Result<String, WebError> {
    let bytes = value.as_bytes();
    let mut decoded = Vec::with_capacity(bytes.len());
    let mut index = 0;
    while index < bytes.len() {
        if bytes[index] == b'%' {
            if index + 2 >= bytes.len() {
                return Err(WebError::bad_request_code(
                    "local_folder_root_invalid",
                    "file:// rootUri 包含不完整的百分号编码",
                ));
            }
            let hex = &value[index + 1..index + 3];
            let byte = u8::from_str_radix(hex, 16).map_err(|_| {
                WebError::bad_request_code(
                    "local_folder_root_invalid",
                    "file:// rootUri 包含无效的百分号编码",
                )
            })?;
            decoded.push(byte);
            index += 3;
        } else {
            decoded.push(bytes[index]);
            index += 1;
        }
    }
    String::from_utf8(decoded).map_err(|_| {
        WebError::bad_request_code(
            "local_folder_root_invalid",
            "file:// rootUri 不是 UTF-8 路径",
        )
    })
}

fn load_local_folder_metadata(root: &Path) -> Result<LocalFolderMetadata, WebError> {
    Ok(LocalFolderMetadata {
        page_ids: load_metadata_string_map(&root.join(".mnote").join("page-ids.json"))?,
        page_options: load_metadata_value_map(&root.join(".mnote").join("page-options.json"))?,
        trash_entries: load_trash_index_map(&root.join(".mnote").join("trash-index.json"))?,
    })
}

fn load_metadata_string_map(path: &Path) -> Result<BTreeMap<String, String>, WebError> {
    if !path.exists() {
        return Ok(BTreeMap::new());
    }
    let value = read_metadata_json(path)?;
    let source = value
        .get("pages")
        .or_else(|| value.get("pageIds"))
        .unwrap_or(&value);
    let Some(map) = source.as_object() else {
        return Err(metadata_invalid(path, "元数据必须是对象"));
    };
    let mut result = BTreeMap::new();
    for (key, value) in map {
        let Some(page_id) = value
            .as_str()
            .map(str::trim)
            .filter(|item| !item.is_empty())
        else {
            return Err(metadata_invalid(path, "page id 必须是非空字符串"));
        };
        result.insert(key.clone(), page_id.to_string());
    }
    Ok(result)
}

fn load_metadata_value_map(path: &Path) -> Result<BTreeMap<String, Value>, WebError> {
    if !path.exists() {
        return Ok(BTreeMap::new());
    }
    let value = read_metadata_json(path)?;
    let source = value
        .get("pages")
        .or_else(|| value.get("options"))
        .unwrap_or(&value);
    let Some(map) = source.as_object() else {
        return Err(metadata_invalid(path, "页面选项元数据必须是对象"));
    };
    Ok(map
        .iter()
        .map(|(key, value)| (key.clone(), value.clone()))
        .collect())
}

fn read_metadata_json(path: &Path) -> Result<Value, WebError> {
    let raw = fs::read_to_string(path).map_err(|error| {
        WebError::bad_request_code(
            "local_metadata_read_failed",
            format!("无法读取本地元数据 {}: {error}", path.display()),
        )
    })?;
    serde_json::from_str(&raw)
        .map_err(|error| metadata_invalid(path, format!("元数据 JSON 损坏: {error}")))
}

fn load_trash_index_map(path: &Path) -> Result<BTreeMap<String, LocalTrashEntry>, WebError> {
    if !path.exists() {
        return Ok(BTreeMap::new());
    }
    let value = read_metadata_json(path)?;
    let source = value.get("entries").unwrap_or(&value);
    let entries: BTreeMap<String, LocalTrashEntry> = serde_json::from_value(source.clone())
        .map_err(|error| metadata_invalid(path, format!("回收站索引损坏: {error}")))?;
    Ok(entries)
}

fn metadata_invalid(path: &Path, message: impl Into<String>) -> WebError {
    WebError::bad_request_code(
        "local_metadata_invalid",
        format!("{}；请修复或移走 {} 后重试", message.into(), path.display()),
    )
}

#[allow(dead_code)]
pub fn initialize_local_page_id(root_uri: &str, relative_path: &str) -> Result<String, WebError> {
    let root_path = parse_file_root_uri(root_uri)?;
    let canonical_root = root_path.canonicalize().map_err(|error| {
        WebError::bad_request_code(
            "local_folder_unavailable",
            format!("无法访问本地文件夹: {error}"),
        )
    })?;
    let target = canonical_root
        .join(relative_path)
        .canonicalize()
        .map_err(|error| {
            WebError::bad_request_code(
                "local_page_id_target_invalid",
                format!("无法解析本地 Markdown 文件: {error}"),
            )
        })?;
    if !target.starts_with(&canonical_root) || !target.is_file() || !is_markdown_file(relative_path)
    {
        return Err(WebError::bad_request_code(
            "local_page_id_target_invalid",
            "只能为 root 内的 Markdown 文件初始化 page id",
        ));
    }
    let mut metadata = load_local_folder_metadata(&canonical_root)?;
    if let Some(existing) = metadata.page_ids.get(relative_path) {
        return Ok(normalize_metadata_page_id(existing));
    }
    let page_id = format!(
        "local-mdid:{}",
        encode_local_id_segment(&format!(
            "{}:{relative_path}",
            local_workspace_id(&canonical_root)
        ))
    );
    metadata
        .page_ids
        .insert(relative_path.to_string(), page_id.clone());
    write_page_ids_metadata(&canonical_root, &metadata.page_ids)?;
    Ok(page_id)
}

#[allow(dead_code)]
fn write_page_ids_metadata(
    root: &Path,
    page_ids: &BTreeMap<String, String>,
) -> Result<(), WebError> {
    let mnote_dir = root.join(".mnote");
    fs::create_dir_all(&mnote_dir).map_err(|error| {
        WebError::bad_request_code(
            "local_metadata_write_failed",
            format!("无法创建本地元数据目录 {}: {error}", mnote_dir.display()),
        )
    })?;
    let path = mnote_dir.join("page-ids.json");
    let value = json!({
        "version": 1,
        "pages": page_ids,
    });
    write_json_atomic(&path, &value)
}

fn write_trash_index_metadata(
    root: &Path,
    entries: &BTreeMap<String, LocalTrashEntry>,
) -> Result<(), WebError> {
    let mnote_dir = root.join(".mnote");
    fs::create_dir_all(&mnote_dir).map_err(|error| {
        WebError::bad_request_code(
            "local_metadata_write_failed",
            format!("无法创建本地元数据目录 {}: {error}", mnote_dir.display()),
        )
    })?;
    let path = mnote_dir.join("trash-index.json");
    let value = json!({
        "version": 1,
        "entries": entries,
    });
    write_json_atomic(&path, &value)
}

fn write_page_options_metadata(
    root: &Path,
    page_options: &BTreeMap<String, Value>,
) -> Result<(), WebError> {
    let mnote_dir = root.join(".mnote");
    fs::create_dir_all(&mnote_dir).map_err(|error| {
        WebError::bad_request_code(
            "local_metadata_write_failed",
            format!("无法创建本地元数据目录 {}: {error}", mnote_dir.display()),
        )
    })?;
    let path = mnote_dir.join("page-options.json");
    let value = json!({
        "version": 1,
        "pages": page_options,
    });
    write_json_atomic(&path, &value)
}

#[allow(dead_code)]
fn write_json_atomic(path: &Path, value: &Value) -> Result<(), WebError> {
    let tmp_path = path.with_extension("json.tmp");
    let bytes = serde_json::to_vec_pretty(value)
        .map_err(|error| WebError::internal(format!("本地元数据序列化失败: {error}")))?;
    fs::write(&tmp_path, bytes).map_err(|error| {
        WebError::bad_request_code(
            "local_metadata_write_failed",
            format!("无法写入临时元数据 {}: {error}", tmp_path.display()),
        )
    })?;
    fs::rename(&tmp_path, path).map_err(|error| {
        let _ = fs::remove_file(&tmp_path);
        WebError::bad_request_code(
            "local_metadata_write_failed",
            format!("无法替换本地元数据 {}: {error}", path.display()),
        )
    })
}

fn scan_directory(
    root: &Path,
    directory: &Path,
    parent_node_id: Option<String>,
    depth: u32,
    root_source_uri: &str,
    workspace_id: &str,
    metadata: &LocalFolderMetadata,
    rows: &mut Vec<LocalFolderRow>,
) -> Result<(), WebError> {
    let entries = read_sorted_entries(directory, root)?;
    let entry_count = entries.len();
    for (position, entry) in entries.into_iter().enumerate() {
        let node_id = local_node_id(if entry.relative_path.is_empty() {
            "."
        } else {
            &entry.relative_path
        });
        let child_count = if entry.is_dir && !entry.is_symlink {
            count_visible_children(&entry.path, root)?
        } else {
            0
        };
        let row_kind = if entry.is_dir {
            "folder".to_string()
        } else if is_markdown_file(&entry.file_name) {
            "markdown".to_string()
        } else {
            "asset".to_string()
        };
        let icon_hint = icon_hint_for_entry(&entry);
        rows.push(LocalFolderRow {
            node_id: node_id.clone(),
            row_id: format!("local:{row_kind}:{}", entry.relative_path),
            parent_node_id: parent_node_id.clone(),
            title: entry.file_name.clone(),
            depth,
            position: position as u32,
            row_kind,
            icon_hint,
            relative_path: entry.relative_path.clone(),
            source_uri: file_uri_for_path(&entry.path),
            child_count,
            expandable: entry.is_dir && child_count > 0,
            expanded_by_default: depth < 1 && entry.is_dir && entry_count <= 80,
            document_id: if is_markdown_file(&entry.file_name) {
                Some(local_markdown_page_id(&entry.relative_path, None, metadata))
            } else {
                None
            },
            capabilities: local_entry_capabilities(&entry),
            workspace_id: workspace_id.to_string(),
            root_source_uri: root_source_uri.to_string(),
        });
        if entry.is_dir && !entry.is_symlink {
            scan_directory(
                root,
                &entry.path,
                Some(node_id),
                depth + 1,
                root_source_uri,
                workspace_id,
                metadata,
                rows,
            )?;
        }
    }

    if rows.is_empty() && directory == root {
        rows.push(LocalFolderRow {
            node_id: local_node_id("."),
            row_id: "local:folder:.".to_string(),
            parent_node_id: None,
            title: root
                .file_name()
                .and_then(|name| name.to_str())
                .unwrap_or("local folder")
                .to_string(),
            depth: 0,
            position: 0,
            row_kind: "folder".to_string(),
            icon_hint: "folder".to_string(),
            relative_path: ".".to_string(),
            source_uri: root_source_uri.to_string(),
            child_count: 0,
            expandable: false,
            expanded_by_default: false,
            document_id: None,
            capabilities: local_path_capabilities(root),
            workspace_id: workspace_id.to_string(),
            root_source_uri: root_source_uri.to_string(),
        });
    }

    Ok(())
}

fn read_sorted_entries(directory: &Path, root: &Path) -> Result<Vec<LocalFolderEntry>, WebError> {
    let read_dir = fs::read_dir(directory).map_err(|error| {
        WebError::bad_request_code(
            "local_folder_scan_failed",
            format!("无法读取本地目录 {}: {error}", directory.display()),
        )
    })?;
    let mut entries = Vec::new();
    for entry in read_dir {
        let entry = entry.map_err(|error| {
            WebError::bad_request_code(
                "local_folder_scan_failed",
                format!("读取目录项失败: {error}"),
            )
        })?;
        let path = entry.path();
        let metadata = fs::symlink_metadata(&path).map_err(|error| {
            WebError::bad_request_code(
                "local_folder_scan_failed",
                format!("无法读取目录项元数据 {}: {error}", path.display()),
            )
        })?;
        let file_name = entry.file_name().to_string_lossy().to_string();
        let relative_path = normalize_relative_path(root, &path)?;
        if should_ignore_entry(&relative_path, &file_name) {
            continue;
        }
        let is_symlink = metadata.file_type().is_symlink();
        let is_dir = if is_symlink { false } else { metadata.is_dir() };
        let is_readonly = metadata.permissions().readonly();
        entries.push(LocalFolderEntry {
            path,
            relative_path,
            file_name,
            is_dir,
            is_symlink,
            is_readonly,
        });
    }
    entries.sort_by(compare_local_entries);
    Ok(entries)
}

fn count_visible_children(directory: &Path, root: &Path) -> Result<u32, WebError> {
    Ok(read_sorted_entries(directory, root)?.len() as u32)
}

fn local_entry_capabilities(entry: &LocalFolderEntry) -> Vec<String> {
    let mut capabilities = Vec::new();
    if entry.is_readonly {
        capabilities.push("readonly".to_string());
    }
    if entry.is_symlink {
        capabilities.push("symlink".to_string());
    }
    capabilities
}

fn local_path_capabilities(path: &Path) -> Vec<String> {
    match fs::symlink_metadata(path) {
        Ok(metadata) if metadata.permissions().readonly() => vec!["readonly".to_string()],
        _ => Vec::new(),
    }
}

fn normalize_relative_path(root: &Path, path: &Path) -> Result<String, WebError> {
    if !path.starts_with(root) {
        return Err(WebError::bad_request_code(
            "local_folder_root_escape",
            "本地文件夹扫描不能越过 root",
        ));
    }
    let relative = path.strip_prefix(root).map_err(|_| {
        WebError::bad_request_code("local_folder_root_escape", "本地路径不在 root 内")
    })?;
    Ok(relative
        .components()
        .map(|component| component.as_os_str().to_string_lossy().to_string())
        .collect::<Vec<_>>()
        .join("/"))
}

fn resolve_metadata_relative_path(root: &Path, relative_path: &str) -> Result<PathBuf, WebError> {
    let relative = Path::new(relative_path);
    if relative.is_absolute()
        || relative
            .components()
            .any(|component| matches!(component, std::path::Component::ParentDir))
    {
        return Err(WebError::bad_request_code(
            "local_folder_root_escape",
            "本地元数据路径不能越过 root",
        ));
    }
    let target = root.join(relative);
    if !target.starts_with(root) {
        return Err(WebError::bad_request_code(
            "local_folder_root_escape",
            "本地元数据路径不在 root 内",
        ));
    }
    Ok(target)
}

fn should_ignore_entry(relative_path: &str, file_name: &str) -> bool {
    if matches!(file_name, ".git" | "node_modules" | ".mnote") {
        return true;
    }
    relative_path == ".mnote/trash" || relative_path.starts_with(".mnote/trash/")
}

fn compare_local_entries(a: &LocalFolderEntry, b: &LocalFolderEntry) -> Ordering {
    match (a.is_dir, b.is_dir) {
        (true, false) => Ordering::Less,
        (false, true) => Ordering::Greater,
        _ => a
            .file_name
            .to_ascii_lowercase()
            .cmp(&b.file_name.to_ascii_lowercase())
            .then_with(|| a.file_name.cmp(&b.file_name)),
    }
}

fn scan_markdown_page_tree(
    root: &Path,
    directory: &Path,
    parent_node_id: Option<String>,
    depth: u32,
    metadata: &LocalFolderMetadata,
    rows: &mut Vec<LocalFolderRow>,
    workspace_id: &str,
    root_source_uri: &str,
) -> Result<bool, WebError> {
    let entries = read_sorted_entries(directory, root)?;
    let mut directory_rows = Vec::<LocalFolderRow>::new();
    let mut contains_markdown = false;
    for (position, entry) in entries.into_iter().enumerate() {
        if entry.is_dir && !entry.is_symlink {
            let node_id = local_directory_group_id(&entry.relative_path);
            let mut child_rows = Vec::new();
            let child_contains_markdown = scan_markdown_page_tree(
                root,
                &entry.path,
                Some(node_id.clone()),
                depth + 1,
                metadata,
                &mut child_rows,
                workspace_id,
                root_source_uri,
            )?;
            if child_contains_markdown {
                directory_rows.push(LocalFolderRow {
                    node_id,
                    row_id: format!("local:page-group:{}", entry.relative_path),
                    parent_node_id: parent_node_id.clone(),
                    title: entry.file_name.clone(),
                    depth,
                    position: position as u32,
                    row_kind: "document".to_string(),
                    icon_hint: "folder".to_string(),
                    relative_path: entry.relative_path.clone(),
                    source_uri: file_uri_for_path(&entry.path),
                    child_count: 0,
                    expandable: true,
                    expanded_by_default: depth < 2,
                    document_id: None,
                    capabilities: local_entry_capabilities(&entry),
                    workspace_id: workspace_id.to_string(),
                    root_source_uri: root_source_uri.to_string(),
                });
                directory_rows.extend(child_rows);
                contains_markdown = true;
            }
            continue;
        }
        if is_markdown_file(&entry.file_name) {
            let markdown = fs::read_to_string(&entry.path).unwrap_or_default();
            let parsed = parse_markdown_page(&markdown, &entry.file_name);
            let page_id =
                local_markdown_page_id(&entry.relative_path, parsed.mnote_id.as_deref(), metadata);
            directory_rows.push(LocalFolderRow {
                node_id: page_id.clone(),
                row_id: format!("local:page:{}", entry.relative_path),
                parent_node_id: parent_node_id.clone(),
                title: parsed.title,
                depth,
                position: position as u32,
                row_kind: "document".to_string(),
                icon_hint: "markdown".to_string(),
                relative_path: entry.relative_path.clone(),
                source_uri: file_uri_for_path(&entry.path),
                child_count: 0,
                expandable: false,
                expanded_by_default: false,
                document_id: Some(page_id),
                capabilities: local_entry_capabilities(&entry),
                workspace_id: workspace_id.to_string(),
                root_source_uri: root_source_uri.to_string(),
            });
            contains_markdown = true;
        }
    }
    rows.extend(directory_rows);
    Ok(contains_markdown)
}

fn find_markdown_by_page_id(
    root: &Path,
    metadata: &LocalFolderMetadata,
    document_id: &str,
) -> Result<Option<LocalFolderEntry>, WebError> {
    fn walk(
        root: &Path,
        directory: &Path,
        metadata: &LocalFolderMetadata,
        document_id: &str,
    ) -> Result<Option<LocalFolderEntry>, WebError> {
        for entry in read_sorted_entries(directory, root)? {
            if entry.is_dir && !entry.is_symlink {
                if let Some(found) = walk(root, &entry.path, metadata, document_id)? {
                    return Ok(Some(found));
                }
                continue;
            }
            if !is_markdown_file(&entry.file_name) {
                continue;
            }
            let markdown = fs::read_to_string(&entry.path).unwrap_or_default();
            let parsed = parse_markdown_page(&markdown, &entry.file_name);
            let page_id =
                local_markdown_page_id(&entry.relative_path, parsed.mnote_id.as_deref(), metadata);
            if page_id == document_id {
                return Ok(Some(entry));
            }
        }
        Ok(None)
    }

    walk(root, root, metadata, document_id)
}

fn local_folder_row_to_projection_item(row: &LocalFolderRow) -> Value {
    let mut item = json!({
        "rowId": row.row_id,
        "rowKind": row.row_kind,
        "nodeId": row.node_id,
        "parentNodeId": row.parent_node_id,
        "title": row.title,
        "depth": row.depth,
        "position": row.position,
        "childCount": row.child_count,
        "expandable": row.expandable,
        "expandedByDefault": row.expanded_by_default,
        "capabilities": row.capabilities.clone(),
        "iconHint": row.icon_hint,
        "resourceMeta": {
            "resourceKind": row.row_kind,
            "iconHint": row.icon_hint,
            "extra": {
                "source": {
                    "sourceKind": "local_folder",
                    "sourceUri": row.source_uri,
                    "relativePath": row.relative_path,
                    "storageIdentity": {
                        "kind": "file_path",
                        "path": row.relative_path,
                    },
                    "operationProfile": "local_readonly",
                }
            }
        }
    });
    if let Some(document_id) = row.document_id.as_ref() {
        item["resourceMeta"]["documentId"] = Value::String(document_id.clone());
    }
    if row.row_kind == "asset" && !row.relative_path.trim().is_empty() {
        let asset_id = format!("local-file:{}", row.relative_path);
        item["assetId"] = Value::String(asset_id.clone());
        item["resourceMeta"]["assetId"] = Value::String(asset_id);
    }

    // Phase A1: 为 File/Page/Resource tree 输出统一 workspacePath
    let object_kind = match row.row_kind.as_str() {
        "markdown" | "document" => KernelObjectKind::Page,
        "folder" | "index" => KernelObjectKind::Index,
        "asset" => match row.icon_hint.as_str() {
            "mindmap" => KernelObjectKind::Mindmap,
            "onlyoffice" | "office" => KernelObjectKind::OnlyOffice,
            _ => KernelObjectKind::Attachment,
        },
        _ => KernelObjectKind::Attachment,
    };
    let workspace_path = ObjectWorkspacePath {
        workspace_id: row.workspace_id.clone(),
        source_kind: WorkspaceSourceKind::LocalFolder,
        root_uri: row.root_source_uri.clone(),
        relative_path: row.relative_path.clone(),
        object_identity: KernelObjectIdentity {
            object_kind,
            document_id: row.document_id.clone(),
            block_id: None,
            asset_id: None,
        },
        resource_kind: Some(row.row_kind.clone()),
    };
    if let Ok(path_value) = serde_json::to_value(&workspace_path) {
        item["resourceMeta"]["workspacePath"] = path_value;
    }
    item
}

fn local_node_id(relative_path: &str) -> String {
    format!("local:node:{relative_path}")
}

fn local_directory_group_id(relative_path: &str) -> String {
    format!("local-dir:{}", encode_local_id_segment(relative_path))
}

fn local_markdown_page_id(
    relative_path: &str,
    mnote_id: Option<&str>,
    metadata: &LocalFolderMetadata,
) -> String {
    if let Some(mnote_id) = mnote_id.map(str::trim).filter(|value| !value.is_empty()) {
        if mnote_id.starts_with("local-mdid:") || mnote_id.starts_with("local-md:") {
            return mnote_id.to_string();
        }
        return format!("local-mdid:{}", encode_local_id_segment(mnote_id));
    }
    if let Some(page_id) = metadata
        .page_ids
        .get(relative_path)
        .map(String::as_str)
        .map(str::trim)
        .filter(|value| !value.is_empty())
    {
        return normalize_metadata_page_id(page_id);
    }
    format!("local-md:{}", encode_local_id_segment(relative_path))
}

fn normalize_metadata_page_id(page_id: &str) -> String {
    let trimmed = page_id.trim();
    if trimmed.starts_with("local-md:") || trimmed.starts_with("local-mdid:") {
        trimmed.to_string()
    } else {
        format!("local-mdid:{}", encode_local_id_segment(trimmed))
    }
}

fn page_options_from_metadata(value: &Value) -> PageOptions {
    let mut options = PageOptions::default();
    if let Some(wide_layout) = value
        .get("wideLayout")
        .or_else(|| value.get("wide_layout"))
        .and_then(Value::as_bool)
    {
        options.wide_layout = wide_layout;
    }
    if let Some(small_text) = value
        .get("smallText")
        .or_else(|| value.get("small_text"))
        .and_then(Value::as_bool)
    {
        options.small_text = small_text;
    }
    if let Some(layout_density) = value
        .get("layoutDensity")
        .or_else(|| value.get("layout_density"))
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|item| !item.is_empty())
    {
        options.layout_density = layout_density.to_string();
    }
    if let Some(show_toc) = value
        .get("showToc")
        .or_else(|| value.get("show_toc"))
        .and_then(Value::as_bool)
    {
        options.show_toc = show_toc;
    }
    if let Some(show_structure) = value
        .get("showStructure")
        .or_else(|| value.get("show_structure"))
        .and_then(Value::as_bool)
    {
        options.show_structure = show_structure;
    }
    if let Some(show_heading_numbers) = value
        .get("showHeadingNumbers")
        .or_else(|| value.get("show_heading_numbers"))
        .and_then(Value::as_bool)
    {
        options.show_heading_numbers = show_heading_numbers;
    }
    if let Some(protect_editing) = value
        .get("protectEditing")
        .or_else(|| value.get("protect_editing"))
        .and_then(Value::as_bool)
    {
        options.protect_editing = protect_editing;
    }
    options
}

fn local_workspace_id(root: &Path) -> String {
    if let Ok(manifest) = load_local_workspace_manifest(root) {
        if !manifest.workspace_id.trim().is_empty() {
            return manifest.workspace_id;
        }
    }
    format!(
        "local:{}",
        root.to_string_lossy()
            .chars()
            .map(|character| match character {
                '/' | '\\' | ':' | ' ' => '_',
                value if value.is_ascii_alphanumeric() || matches!(value, '_' | '-' | '.') => value,
                _ => '_',
            })
            .collect::<String>()
    )
}

fn local_folder_watch_revision_for_root(
    root: &Path,
    root_source_uri: &str,
) -> Result<LocalFolderWatchRevision, WebError> {
    let mut hasher = DefaultHasher::new();
    let mut entry_count = 0usize;
    let mut latest_modified_ms = 0u128;

    fn visit(
        root: &Path,
        directory: &Path,
        hasher: &mut DefaultHasher,
        entry_count: &mut usize,
        latest_modified_ms: &mut u128,
    ) -> Result<(), WebError> {
        for entry in read_sorted_entries(directory, root)? {
            entry.relative_path.hash(hasher);
            entry.file_name.hash(hasher);
            entry.is_dir.hash(hasher);
            entry.is_symlink.hash(hasher);
            entry.is_readonly.hash(hasher);
            if let Ok(meta) = fs::symlink_metadata(&entry.path) {
                meta.len().hash(hasher);
                if let Ok(modified) = meta.modified() {
                    if let Ok(delta) = modified.duration_since(UNIX_EPOCH) {
                        let modified_ms = delta.as_millis();
                        modified_ms.hash(hasher);
                        if modified_ms > *latest_modified_ms {
                            *latest_modified_ms = modified_ms;
                        }
                    }
                }
            }
            *entry_count += 1;
            if entry.is_dir && !entry.is_symlink {
                visit(root, &entry.path, hasher, entry_count, latest_modified_ms)?;
            }
        }
        Ok(())
    }

    visit(
        root,
        root,
        &mut hasher,
        &mut entry_count,
        &mut latest_modified_ms,
    )?;
    Ok(LocalFolderWatchRevision {
        root_uri: root_source_uri.to_string(),
        revision: format!("{:016x}", hasher.finish()),
        entry_count,
        latest_modified_ms,
    })
}

fn file_uri_for_path(path: &Path) -> String {
    format!("file://{}", path.display())
}

fn is_markdown_file(file_name: &str) -> bool {
    file_name.to_ascii_lowercase().ends_with(".md")
}

fn icon_hint_for_entry(entry: &LocalFolderEntry) -> String {
    if entry.is_dir {
        return "folder".to_string();
    }
    if entry.is_symlink {
        return "symlink".to_string();
    }
    let lower = entry.file_name.to_ascii_lowercase();
    if lower.ends_with(".md") || lower.ends_with(".markdown") {
        "markdown"
    } else if matches!(
        extension(&lower).as_deref(),
        Some("png" | "jpg" | "jpeg" | "gif" | "webp" | "svg" | "bmp")
    ) {
        "image"
    } else if matches!(
        extension(&lower).as_deref(),
        Some("mp4" | "webm" | "mov" | "mkv")
    ) {
        "video"
    } else if matches!(
        extension(&lower).as_deref(),
        Some("mp3" | "wav" | "flac" | "ogg")
    ) {
        "audio"
    } else if lower.ends_with(".pdf") {
        "pdf"
    } else if matches!(extension(&lower).as_deref(), Some("epub" | "mobi")) {
        "book"
    } else if matches!(
        extension(&lower).as_deref(),
        Some("csv" | "tsv" | "xlsx" | "xls")
    ) {
        "table"
    } else {
        "unknown"
    }
    .to_string()
}

fn extension(file_name: &str) -> Option<String> {
    Path::new(file_name)
        .extension()
        .and_then(|extension| extension.to_str())
        .map(ToOwned::to_owned)
}

fn encode_local_id_segment(value: &str) -> String {
    let mut encoded = String::with_capacity(value.len());
    for byte in value.as_bytes() {
        let character = *byte as char;
        if character.is_ascii_alphanumeric() || matches!(character, '.' | '_' | '-') {
            encoded.push(character);
        } else {
            encoded.push('~');
            encoded.push_str(&format!("{byte:02X}"));
        }
    }
    encoded
}

pub(crate) fn decode_local_id_segment(value: &str) -> Result<String, WebError> {
    let bytes = value.as_bytes();
    let mut decoded = Vec::with_capacity(bytes.len());
    let mut index = 0;
    while index < bytes.len() {
        if bytes[index] == b'~' {
            if index + 2 >= bytes.len() {
                return Err(WebError::bad_request_code(
                    "local_id_invalid",
                    "本地 page id 编码不完整",
                ));
            }
            let hex = &value[index + 1..index + 3];
            let byte = u8::from_str_radix(hex, 16).map_err(|_| {
                WebError::bad_request_code("local_id_invalid", "本地 page id 编码非法")
            })?;
            decoded.push(byte);
            index += 3;
        } else {
            decoded.push(bytes[index]);
            index += 1;
        }
    }
    String::from_utf8(decoded)
        .map_err(|_| WebError::bad_request_code("local_id_invalid", "本地 page id 不是 UTF-8"))
}

fn rewrite_page_ids_prefix(
    page_ids: &mut BTreeMap<String, String>,
    old_relative_path: &str,
    new_relative_path: &str,
) {
    let old_prefix = format!("{old_relative_path}/");
    let replacements = page_ids
        .iter()
        .filter_map(|(relative_path, page_id)| {
            if relative_path == old_relative_path {
                Some((
                    relative_path.clone(),
                    new_relative_path.to_string(),
                    page_id.clone(),
                ))
            } else if let Some(rest) = relative_path.strip_prefix(&old_prefix) {
                Some((
                    relative_path.clone(),
                    format!("{new_relative_path}/{rest}"),
                    page_id.clone(),
                ))
            } else {
                None
            }
        })
        .collect::<Vec<_>>();
    for (old_key, new_key, page_id) in replacements {
        page_ids.remove(&old_key);
        page_ids.insert(new_key, page_id);
    }
}

fn sanitize_file_stem(value: &str, fallback: &str) -> String {
    let sanitized = value
        .trim()
        .chars()
        .map(|character| {
            if matches!(
                character,
                '/' | '\\' | ':' | '*' | '?' | '"' | '<' | '>' | '|'
            ) {
                '_'
            } else {
                character
            }
        })
        .collect::<String>();
    let trimmed = sanitized.trim().trim_matches('.').trim();
    if trimmed.is_empty() {
        fallback.to_string()
    } else {
        trimmed.to_string()
    }
}

fn sanitize_file_name(value: &str, fallback: &str) -> String {
    let sanitized = value
        .trim()
        .chars()
        .map(|character| {
            if matches!(
                character,
                '/' | '\\' | ':' | '*' | '?' | '"' | '<' | '>' | '|'
            ) {
                '_'
            } else {
                character
            }
        })
        .collect::<String>();
    let trimmed = sanitized.trim().trim_matches('.').trim();
    if trimmed.is_empty() {
        fallback.to_string()
    } else {
        trimmed.to_string()
    }
}

fn next_available_path(directory: &Path, stem: &str, extension: &str) -> PathBuf {
    let first = directory.join(format!("{stem}.{extension}"));
    if !first.exists() {
        return first;
    }
    for index in 2..10_000 {
        let candidate = directory.join(format!("{stem} {index}.{extension}"));
        if !candidate.exists() {
            return candidate;
        }
    }
    directory.join(format!("{stem}-{}.{}", std::process::id(), extension))
}

fn next_available_raw_path(directory: &Path, file_name: &str) -> PathBuf {
    let first = directory.join(file_name);
    if !first.exists() {
        return first;
    }
    let path = Path::new(file_name);
    let stem = path
        .file_stem()
        .and_then(|value| value.to_str())
        .unwrap_or(file_name);
    let extension = path.extension().and_then(|value| value.to_str());
    for index in 2..10_000 {
        let candidate_name = if let Some(extension) = extension {
            format!("{stem} {index}.{extension}")
        } else {
            format!("{stem} {index}")
        };
        let candidate = directory.join(candidate_name);
        if !candidate.exists() {
            return candidate;
        }
    }
    directory.join(format!("{stem}-{}", std::process::id()))
}

fn next_available_asset_path(directory: &Path, file_name: &str) -> PathBuf {
    let first = directory.join(file_name);
    if !first.exists() {
        return first;
    }
    let path = Path::new(file_name);
    let stem = path
        .file_stem()
        .and_then(|value| value.to_str())
        .unwrap_or(file_name);
    let extension = path.extension().and_then(|value| value.to_str());
    for index in 1..10_000 {
        let candidate_name = if let Some(extension) = extension {
            format!("{stem}-{index}.{extension}")
        } else {
            format!("{stem}-{index}")
        };
        let candidate = directory.join(candidate_name);
        if !candidate.exists() {
            return candidate;
        }
    }
    directory.join(format!("{stem}-{}", std::process::id()))
}

fn normalize_markdown_relative_asset_path(
    markdown_dir: &Path,
    asset_path: &Path,
) -> Result<String, WebError> {
    let relative = asset_path.strip_prefix(markdown_dir).map_err(|_| {
        WebError::bad_request_code(
            "local_asset_upload_relative_path_failed",
            "本地资源文件不在 Markdown 文件目录内",
        )
    })?;
    Ok(relative
        .components()
        .map(|component| component.as_os_str().to_string_lossy().to_string())
        .collect::<Vec<_>>()
        .join("/"))
}

fn local_upload_asset_type(kind: &str, mime_type: &str) -> &'static str {
    let normalized_kind = kind.trim().to_ascii_lowercase();
    if normalized_kind == "image" || mime_type.trim().to_ascii_lowercase().starts_with("image/") {
        "image"
    } else {
        "file"
    }
}

fn next_available_directory_path(directory: &Path, stem: &str) -> PathBuf {
    let first = directory.join(stem);
    if !first.exists() {
        return first;
    }
    for index in 2..10_000 {
        let candidate = directory.join(format!("{stem} {index}"));
        if !candidate.exists() {
            return candidate;
        }
    }
    directory.join(format!("{stem}-{}", std::process::id()))
}

fn markdown_with_frontmatter_fields(markdown: &str, fields: &[(&str, &str)]) -> String {
    let (frontmatter, body) = split_frontmatter(markdown);
    let mut lines = frontmatter
        .unwrap_or_default()
        .lines()
        .map(ToOwned::to_owned)
        .collect::<Vec<_>>();
    for (key, value) in fields {
        let replacement = format!("{key}: {}", value.trim());
        if let Some(existing) = lines.iter_mut().find(|line| {
            line.split_once(':')
                .map(|(candidate, _)| candidate.trim() == *key)
                .unwrap_or(false)
        }) {
            *existing = replacement;
        } else {
            lines.push(replacement);
        }
    }
    format!("---\n{}\n---\n{}", lines.join("\n"), body)
}

fn editor_blocks_to_markdown(content: &Value) -> String {
    let blocks = if let Some(array) = content.as_array() {
        array.clone()
    } else {
        content
            .get("blocks")
            .and_then(Value::as_array)
            .cloned()
            .unwrap_or_default()
    };
    let mut lines = Vec::new();
    for block in blocks {
        let block_type = block
            .get("type")
            .or_else(|| block.get("blockType"))
            .and_then(Value::as_str)
            .unwrap_or("paragraph");
        let inline_markdown = block_content_value(&block)
            .map(inline_nodes_to_markdown)
            .unwrap_or_default()
            .trim()
            .to_string();
        let text = if inline_markdown.is_empty() {
            extract_block_text(&block).trim().to_string()
        } else {
            inline_markdown
        };
        if text.is_empty() && !matches!(block_type, "divider" | "media" | "image" | "table") {
            lines.push(String::new());
            continue;
        }
        match block_type {
            "image" => {
                let props = block.get("props").and_then(Value::as_object);
                let src = props
                    .and_then(|props| props.get("src").or_else(|| props.get("sourcePath")))
                    .and_then(Value::as_str)
                    .unwrap_or("")
                    .trim();
                let alt = props
                    .and_then(|props| props.get("alt").or_else(|| props.get("title")))
                    .and_then(Value::as_str)
                    .unwrap_or(text.as_str())
                    .trim();
                if src.is_empty() {
                    lines.push(text);
                } else {
                    lines.push(format!("![{}]({src})", alt.replace(']', r"\]")));
                }
            }
            "media" => {
                let props = block.get("props").and_then(Value::as_object);
                let url = props
                    .and_then(|props| {
                        props
                            .get("sourcePath")
                            .or_else(|| props.get("url"))
                            .or_else(|| props.get("src"))
                    })
                    .and_then(Value::as_str)
                    .unwrap_or("")
                    .trim();
                let name = props
                    .and_then(|props| props.get("name").or_else(|| props.get("fileName")))
                    .and_then(Value::as_str)
                    .unwrap_or(text.as_str())
                    .trim();
                if url.is_empty() {
                    lines.push(text);
                } else {
                    lines.push(format!(
                        "[{}]({url})",
                        if name.is_empty() { url } else { name }
                    ));
                }
            }
            "heading" => {
                let level = block
                    .get("props")
                    .and_then(|props| props.get("level"))
                    .and_then(Value::as_u64)
                    .unwrap_or(1)
                    .clamp(1, 6);
                lines.push(format!("{} {text}", "#".repeat(level as usize)));
            }
            "bulletListItem" | "bullet_list_item" | "list_item" => {
                lines.push(format!("- {text}"));
            }
            "numberedListItem" | "numbered_list_item" => {
                lines.push(format!("1. {text}"));
            }
            "todo" | "checkListItem" | "advancedTodo" => {
                let checked = block
                    .get("props")
                    .and_then(|props| props.get("checked"))
                    .and_then(Value::as_bool)
                    .unwrap_or(false);
                let checkbox = if checked { "[x]" } else { "[ ]" };
                lines.push(format!("- {checkbox} {text}"));
            }
            "quote" | "blockquote" => {
                lines.push(format!("> {text}"));
            }
            "codeBlock" | "code_block" | "code" => {
                lines.push(format!("```\n{text}\n```"));
            }
            "divider" => {
                lines.push("---".to_string());
            }
            "table" => {
                let table_markdown = editor_block_table_to_markdown(&block);
                if table_markdown.is_empty() {
                    lines.push(text);
                } else {
                    lines.extend(table_markdown.lines().map(ToOwned::to_owned));
                }
            }
            _ => lines.push(text),
        }
        lines.push(String::new());
    }
    let markdown = lines.join("\n").trim_end().to_string();
    if markdown.is_empty() {
        "\n".to_string()
    } else {
        format!("{markdown}\n")
    }
}

fn editor_block_table_to_markdown(block: &Value) -> String {
    let table = block
        .get("props")
        .and_then(|props| props.get("tiptapTable"))
        .or_else(|| block.get("tiptapTable"));
    let rows = table
        .and_then(|value| value.get("content"))
        .and_then(Value::as_array);
    let Some(rows) = rows else {
        return String::new();
    };
    let mut parsed_rows = Vec::<Vec<(String, bool)>>::new();
    let mut max_columns = 0usize;
    for row in rows {
        let cells = row
            .get("content")
            .and_then(Value::as_array)
            .map(|cells| {
                cells
                    .iter()
                    .map(|cell| {
                        let cell_text = cell
                            .get("content")
                            .map(inline_nodes_to_markdown)
                            .unwrap_or_default()
                            .replace('\n', " ")
                            .replace('|', r"\|")
                            .trim()
                            .to_string();
                        let is_header =
                            cell.get("type").and_then(Value::as_str) == Some("tableHeader");
                        (cell_text, is_header)
                    })
                    .collect::<Vec<_>>()
            })
            .unwrap_or_default();
        max_columns = max_columns.max(cells.len());
        parsed_rows.push(cells);
    }
    if parsed_rows.is_empty() || max_columns == 0 {
        return String::new();
    }
    let alignments = alignments_from_table(block);
    let mut lines = Vec::<String>::new();
    for (index, row) in parsed_rows.iter().enumerate() {
        let mut cells = row.iter().map(|(text, _)| text.clone()).collect::<Vec<_>>();
        while cells.len() < max_columns {
            cells.push(String::new());
        }
        lines.push(format!("| {} |", cells.join(" | ")));
        if index == 0 {
            let align_row = (0..max_columns)
                .map(
                    |column_index| match table_cell_alignment(&alignments, column_index) {
                        "left" => ":---",
                        "center" => ":---:",
                        "right" => "---:",
                        _ => "---",
                    },
                )
                .collect::<Vec<_>>()
                .join(" | ");
            lines.push(format!("| {} |", align_row));
        }
    }
    if lines.len() < 2 {
        String::new()
    } else {
        lines.join("\n")
    }
}

fn alignments_from_table(block: &Value) -> Vec<String> {
    block
        .get("props")
        .and_then(|props| props.get("tiptapTable"))
        .or_else(|| block.get("tiptapTable"))
        .and_then(|value| value.get("content"))
        .and_then(Value::as_array)
        .and_then(|rows| rows.get(0))
        .and_then(|row| row.get("content"))
        .and_then(Value::as_array)
        .map(|cells| {
            cells
                .iter()
                .map(|cell| {
                    cell.get("attrs")
                        .and_then(|attrs| attrs.get("textAlign"))
                        .and_then(Value::as_str)
                        .unwrap_or("")
                        .to_string()
                })
                .collect::<Vec<_>>()
        })
        .unwrap_or_default()
}

fn table_cell_alignment(alignments: &[String], index: usize) -> &str {
    alignments.get(index).map(String::as_str).unwrap_or("")
}

fn extract_block_text(value: &Value) -> String {
    if let Some(text) = value.as_str() {
        return text.to_string();
    }
    if let Some(array) = value.as_array() {
        return array
            .iter()
            .map(extract_block_text)
            .collect::<Vec<_>>()
            .join("");
    }
    if let Some(object) = value.as_object() {
        if let Some(text) = object.get("text").and_then(Value::as_str) {
            return text.to_string();
        }
        if let Some(content) = object.get("content") {
            return extract_block_text(content);
        }
        if let Some(children) = object.get("children") {
            return extract_block_text(children);
        }
    }
    String::new()
}

fn block_content_value(block: &Value) -> Option<&Value> {
    block.get("content").or_else(|| block.get("contentNodes"))
}

fn inline_nodes_to_markdown(value: &Value) -> String {
    if let Some(text) = value.as_str() {
        return escape_markdown_inline_text(text);
    }
    if let Some(array) = value.as_array() {
        return array
            .iter()
            .map(inline_node_to_markdown)
            .collect::<Vec<_>>()
            .join("");
    }
    if let Some(object) = value.as_object() {
        if let Some(text) = object.get("text").and_then(Value::as_str) {
            return markdown_text_with_styles(text, &inline_styles_from_object(object));
        }
        if let Some(content) = object.get("content").or_else(|| object.get("contentNodes")) {
            return inline_nodes_to_markdown(content);
        }
    }
    String::new()
}

fn inline_node_to_markdown(node: &Value) -> String {
    if let Some(text) = node.as_str() {
        return escape_markdown_inline_text(text);
    }
    if let Some(object) = node.as_object() {
        let text = object
            .get("text")
            .and_then(Value::as_str)
            .unwrap_or_default();
        if !text.is_empty() {
            return markdown_text_with_styles(text, &inline_styles_from_object(object));
        }
        if let Some(content) = object.get("content").or_else(|| object.get("contentNodes")) {
            return inline_nodes_to_markdown(content);
        }
    }
    String::new()
}

fn inline_styles_from_object(object: &Map<String, Value>) -> Value {
    let mut styles = object
        .get("styles")
        .and_then(Value::as_object)
        .cloned()
        .unwrap_or_default();
    for mark in object
        .get("marks")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let mark_type = mark.get("type").and_then(Value::as_str).unwrap_or_default();
        match mark_type {
            "bold" | "strong" => {
                styles.insert("bold".to_string(), Value::Bool(true));
            }
            "italic" | "em" => {
                styles.insert("italic".to_string(), Value::Bool(true));
            }
            "underline" => {
                styles.insert("underline".to_string(), Value::Bool(true));
            }
            "strike" | "strikethrough" => {
                styles.insert("strike".to_string(), Value::Bool(true));
            }
            "code" => {
                styles.insert("code".to_string(), Value::Bool(true));
            }
            "link" => {
                if let Some(href) = mark
                    .get("attrs")
                    .and_then(|attrs| attrs.get("href"))
                    .and_then(Value::as_str)
                    .map(str::trim)
                    .filter(|href| !href.is_empty())
                {
                    styles.insert("link".to_string(), Value::String(href.to_string()));
                }
            }
            _ => {}
        }
    }
    Value::Object(styles)
}

fn markdown_text_with_styles(text: &str, styles: &Value) -> String {
    let mut value = escape_markdown_inline_text(text);
    let link = styles
        .get("link")
        .or_else(|| styles.get("href"))
        .and_then(Value::as_str)
        .map(str::trim)
        .filter(|href| !href.is_empty())
        .map(ToOwned::to_owned);
    if styles
        .get("code")
        .or_else(|| styles.get("inlineCode"))
        .and_then(Value::as_bool)
        .unwrap_or(false)
    {
        value = format!("`{}`", text.replace('`', r"\`"));
    }
    if styles.get("bold").and_then(Value::as_bool).unwrap_or(false) {
        value = format!("**{value}**");
    }
    if styles
        .get("italic")
        .and_then(Value::as_bool)
        .unwrap_or(false)
    {
        value = format!("*{value}*");
    }
    if styles
        .get("strike")
        .or_else(|| styles.get("strikethrough"))
        .and_then(Value::as_bool)
        .unwrap_or(false)
    {
        value = format!("~~{value}~~");
    }
    if let Some(href) = link {
        value = format!("[{}]({href})", value.replace(']', r"\]"));
    }
    value
}

fn escape_markdown_inline_text(text: &str) -> String {
    text.replace('\\', r"\\")
}

fn now_ms() -> u128 {
    system_time_ms(SystemTime::now())
}

fn system_time_ms(time: SystemTime) -> u128 {
    time.duration_since(UNIX_EPOCH)
        .map(|duration| duration.as_millis())
        .unwrap_or(0)
}

fn local_markdown_conflict_detection_key(
    document_id: &str,
    markdown_path: &Path,
) -> Result<String, WebError> {
    let content = fs::read(markdown_path).map_err(|error| {
        WebError::bad_request_code(
            "local_markdown_read_failed",
            format!(
                "无法读取本地 Markdown 文件 {}: {error}",
                markdown_path.display()
            ),
        )
    })?;
    let meta = fs::metadata(markdown_path).map_err(|error| {
        WebError::bad_request_code(
            "local_markdown_stat_failed",
            format!(
                "无法读取本地 Markdown 文件状态 {}: {error}",
                markdown_path.display()
            ),
        )
    })?;
    let modified_ms = system_time_ms(meta.modified().unwrap_or(SystemTime::UNIX_EPOCH));
    let mut hasher = DefaultHasher::new();
    content.hash(&mut hasher);
    let content_hash = hasher.finish();
    Ok(format!(
        "local-md:{document_id}:{modified_ms}:{}:{content_hash:016x}",
        meta.len()
    ))
}

fn markdown_page_subtree(document_id: &str, title: &str, content: &Value) -> Value {
    let outline = content
        .as_array()
        .unwrap_or(&Vec::new())
        .iter()
        .filter(|block| block.get("type").and_then(Value::as_str) == Some("heading"))
        .enumerate()
        .map(|(index, block)| {
            json!({
                "id": format!("outline-{index}"),
                "nodeId": document_id,
                "blockId": block.get("id").and_then(Value::as_str).unwrap_or_default(),
                "title": block
                    .get("content")
                    .and_then(Value::as_array)
                    .and_then(|items| items.first())
                    .and_then(|item| item.get("text"))
                    .and_then(Value::as_str)
                    .unwrap_or(title),
                "depth": block
                    .get("props")
                    .and_then(|props| props.get("level"))
                    .and_then(Value::as_u64)
                    .unwrap_or(1),
            })
        })
        .collect::<Vec<_>>();
    json!({
        "projectionId": format!("page-subtree:{document_id}"),
        "projection": "page_tree",
        "rootNodeId": document_id,
        "rootNode": {
            "id": document_id,
            "title": title,
            "nodeType": "page",
            "depth": 0,
        },
        "subtree": {
            "rootNodeId": document_id,
            "nodes": [{
                "id": document_id,
                "title": title,
                "nodeType": "page",
                "depth": 0,
            }],
        },
        "outline": outline,
        "evidence": [{
            "id": format!("evidence:{document_id}"),
            "nodeId": document_id,
            "kind": "page",
            "snippet": title,
        }],
        "stats": {
            "blockCount": content.as_array().map(|blocks| blocks.len()).unwrap_or(0),
            "headingCount": outline.len(),
            "evidenceCount": 1,
            "maxDepth": 1,
        },
    })
}

#[cfg(test)]
mod tests {
    use super::{
        add_local_access_grant_for_context, create_default_local_workspace_for_actor_at_base,
        create_local_access_grant, create_share_grant, ensure_local_path_read_access,
        ensure_local_workspace_access_for_actor, ensure_local_workspace_read_access_for_actor,
        execute_local_tree_command, get_local_access_policy, get_share_grants,
        initialize_local_page_id, initialize_local_workspace_for_actor,
        load_local_folder_page_tree_snapshot, local_folder_watch_revision, open_local_file,
        record_shared_cache, record_sync_pending_change, resolve_local_markdown_page_aggregate,
        save_local_markdown_page, validate_local_access_root, write_local_markdown_asset,
        write_local_markdown_page_body, write_sync_conflict_report, LocalAccessGrantRequest,
        LocalAccessValidateRootRequest, LocalFileOpenQuery, LocalShareGrantRequest,
        LocalUploadFile, SharedCacheRecordRequest, SyncConflictReportRequest,
        SyncPendingChangeRequest,
    };
    use crate::context::RequestContext;
    use axum::extract::{Extension, Path as AxumPath, Query};
    use axum::http::{HeaderMap, Method, StatusCode};
    use axum::Json;
    use serde_json::Value;
    use std::sync::Mutex;

    fn env_lock() -> &'static Mutex<()> {
        crate::test_support::hermes_env_lock()
    }

    fn temp_root(name: &str) -> std::path::PathBuf {
        let root = std::env::temp_dir().join(format!("{name}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&root);
        std::fs::create_dir_all(&root).expect("create temp root");
        root
    }

    fn request_context(actor_id: &str, actor_type: &str) -> RequestContext {
        let mut headers = HeaderMap::new();
        headers.insert("x-mnote-actor-id", actor_id.parse().unwrap());
        headers.insert("x-mnote-actor-type", actor_type.parse().unwrap());
        RequestContext::from_http_parts(
            &Method::POST,
            &"/api/admin/access-policy".parse().expect("uri"),
            &headers,
        )
    }

    fn init_workspace(root: &std::path::Path) {
        initialize_local_workspace_for_actor("user_test", &format!("file://{}", root.display()))
            .expect("init local workspace");
    }

    #[test]
    fn local_frontmatter_mnote_id_survives_rename_and_move() {
        let root = temp_root("mnote-local-frontmatter-id");
        init_workspace(&root);
        std::fs::write(
            root.join("page.md"),
            "---\nmnote_id: stable-frontmatter-id\ntitle: Stable\n---\n正文\n",
        )
        .expect("write md");
        let root_uri = format!("file://{}", root.display());

        let first = load_local_folder_page_tree_snapshot(&root_uri).expect("first snapshot");
        assert!(first
            .projection
            .to_string()
            .contains("local-mdid:stable-frontmatter-id"));

        std::fs::create_dir_all(root.join("docs")).expect("create docs");
        std::fs::rename(root.join("page.md"), root.join("docs").join("renamed.md"))
            .expect("move md");
        let second = load_local_folder_page_tree_snapshot(&root_uri).expect("second snapshot");
        let second_json = second.projection.to_string();
        assert!(second_json.contains("local-mdid:stable-frontmatter-id"));
        assert!(second_json.contains("renamed.md"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_page_ids_metadata_overrides_path_derived_id_and_hides_mnote() {
        let root = temp_root("mnote-local-page-ids");
        init_workspace(&root);
        std::fs::create_dir_all(root.join(".mnote")).expect("create metadata dir");
        std::fs::create_dir_all(root.join("docs")).expect("create docs");
        std::fs::write(root.join("docs").join("page.md"), "# Metadata Page\n").expect("write md");
        std::fs::write(
            root.join(".mnote").join("page-ids.json"),
            r#"{"version":1,"pages":{"docs/page.md":"stable-from-page-ids"}}"#,
        )
        .expect("write page ids");
        let root_uri = format!("file://{}", root.display());

        let snapshot = load_local_folder_page_tree_snapshot(&root_uri).expect("snapshot");
        let html_json = snapshot.projection.to_string();
        assert!(html_json.contains("local-mdid:stable-from-page-ids"));
        assert!(!html_json.contains("page-ids.json"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_page_id_initialization_writes_page_ids_atomically() {
        let root = temp_root("mnote-local-page-id-init");
        init_workspace(&root);
        std::fs::write(root.join("draft.md"), "# Draft\n").expect("write md");
        let root_uri = format!("file://{}", root.display());

        let page_id = initialize_local_page_id(&root_uri, "draft.md").expect("init page id");
        assert!(page_id.starts_with("local-mdid:"));
        let metadata = std::fs::read_to_string(root.join(".mnote").join("page-ids.json"))
            .expect("read page ids");
        let parsed: Value = serde_json::from_str(&metadata).expect("json");
        assert_eq!(parsed["pages"]["draft.md"], page_id);
        assert!(!root.join(".mnote").join("page-ids.json.tmp").exists());

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_metadata_damage_returns_explainable_error() {
        let root = temp_root("mnote-local-bad-metadata");
        std::fs::create_dir_all(root.join(".mnote")).expect("create metadata");
        std::fs::write(root.join("README.md"), "# Broken Metadata\n").expect("write md");
        std::fs::write(root.join(".mnote").join("page-ids.json"), "{not-json")
            .expect("write bad metadata");
        let root_uri = format!("file://{}", root.display());

        let error = load_local_folder_page_tree_snapshot(&root_uri).expect_err("metadata error");
        assert!(error.message().contains("元数据 JSON 损坏"));
        assert!(error.message().contains("请修复或移走"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_page_options_metadata_flows_into_page_aggregate() {
        let root = temp_root("mnote-local-page-options");
        std::fs::create_dir_all(root.join(".mnote")).expect("create metadata");
        std::fs::write(root.join("README.md"), "# Local Options\n").expect("write md");
        std::fs::write(
            root.join(".mnote").join("page-options.json"),
            r#"{"version":1,"pages":{"local-md:README.md":{"wideLayout":true,"showToc":true,"showHeadingNumbers":true}}}"#,
        )
        .expect("write options");
        let root_uri = format!("file://{}", root.display());

        let aggregate = resolve_local_markdown_page_aggregate(&root_uri, "local-md:README.md")
            .expect("aggregate");
        assert!(aggregate.layout.page_options.wide_layout);
        assert!(aggregate.layout.page_options.show_toc);
        assert!(aggregate.layout.page_options.show_heading_numbers);

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_parser_preserves_pipe_table_as_table_block() {
        let blocks = crate::routes::local_markdown_parser::markdown_to_blocks(
            "| 左 | 右 |\n| --- | --- |\n| `A` | **B** |\n",
        );
        let array = blocks.as_array().expect("blocks");
        let table = array
            .iter()
            .find(|block| block["type"].as_str() == Some("table"))
            .expect("pipe table 应保留为 table block");
        assert_eq!(table["props"]["tiptapTable"]["type"], "table");
        assert_eq!(
            table["props"]["tiptapTable"]["content"][0]["content"][0]["type"],
            "tableHeader"
        );
        assert_eq!(
            table["props"]["tiptapTable"]["content"][1]["content"][0]["type"],
            "tableCell"
        );
        assert_eq!(
            table["props"]["tiptapTable"]["content"][0]["content"][0]["content"][0]["content"][0]
                ["text"],
            "左"
        );
        assert_eq!(
            table["props"]["tiptapTable"]["content"][1]["content"][0]["content"][0]["content"][0]
                ["text"],
            "A"
        );
        assert_eq!(
            table["props"]["tiptapTable"]["content"][1]["content"][0]["content"][0]["content"][0]
                ["marks"][0]["type"],
            "code"
        );
        assert_eq!(
            table["props"]["tiptapTable"]["content"][1]["content"][1]["content"][0]["content"][0]
                ["text"],
            "B"
        );
        assert_eq!(
            table["props"]["tiptapTable"]["content"][1]["content"][1]["content"][0]["content"][0]
                ["marks"][0]["type"],
            "bold"
        );
    }

    #[test]
    fn local_markdown_parser_preserves_task_list_and_inline_marks() {
        let blocks = crate::routes::local_markdown_parser::markdown_to_blocks(
            "- [x] `3000` 默认由 **mnote-web** 监听。\n- [ ] *待办* ~~删除~~ [链接](https://example.com)\n",
        );
        let array = blocks.as_array().expect("blocks");
        assert_eq!(array[0]["type"], "todo");
        assert_eq!(array[0]["props"]["checked"], true);
        assert_eq!(array[1]["type"], "todo");
        assert_eq!(array[1]["props"]["checked"], false);

        let first_content = array[0]["content"].as_array().expect("first content");
        assert!(first_content.iter().any(|node| {
            node["text"].as_str() == Some("3000") && node["styles"]["code"].as_bool() == Some(true)
        }));
        assert!(first_content.iter().any(|node| {
            node["text"].as_str() == Some("mnote-web")
                && node["styles"]["bold"].as_bool() == Some(true)
        }));

        let second_content = array[1]["content"].as_array().expect("second content");
        assert!(second_content.iter().any(|node| {
            node["text"].as_str() == Some("待办")
                && node["styles"]["italic"].as_bool() == Some(true)
        }));
        assert!(second_content.iter().any(|node| {
            node["text"].as_str() == Some("删除")
                && node["styles"]["strike"].as_bool() == Some(true)
        }));
        assert!(second_content.iter().any(|node| {
            node["text"].as_str() == Some("链接")
                && node["styles"]["link"].as_str() == Some("https://example.com")
        }));
    }

    #[test]
    fn local_markdown_aggregate_follows_file_permissions_for_editability() {
        let root = temp_root("mnote-local-readonly-permission");
        std::fs::write(root.join("README.md"), "# Editable?\n").expect("write md");
        let root_uri = format!("file://{}", root.display());

        let aggregate = resolve_local_markdown_page_aggregate(&root_uri, "local-md:README.md")
            .expect("aggregate");
        assert!(!aggregate.head.permissions.read_only);

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_folder_watch_revision_changes_for_visible_files_only() {
        let root = temp_root("mnote-local-watch-revision");
        std::fs::create_dir_all(root.join(".mnote")).expect("create metadata");
        std::fs::create_dir_all(root.join("docs")).expect("create docs");
        std::fs::write(root.join("docs").join("page.md"), "# Watch\n").expect("write md");
        let root_uri = format!("file://{}", root.display());

        let initial = local_folder_watch_revision(&root_uri).expect("initial revision");
        std::fs::write(root.join(".mnote").join("ignored.txt"), "ignored").expect("write ignored");
        let ignored = local_folder_watch_revision(&root_uri).expect("ignored revision");
        assert_eq!(initial.revision, ignored.revision);
        std::fs::write(root.join("docs").join("page.md"), "# Watch Again\n").expect("update md");
        let updated = local_folder_watch_revision(&root_uri).expect("updated revision");
        assert_ne!(initial.revision, updated.revision);
        assert!(updated.entry_count >= 1);

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_conflict_detection_key_changes_when_content_changes_with_same_size() {
        let root = temp_root("mnote-local-conflict-key-content");
        let file = root.join("README.md");
        std::fs::write(&file, "aaaa\n").expect("write first content");

        let first = super::local_markdown_conflict_detection_key("local-md:README.md", &file)
            .expect("first conflict key");

        std::fs::write(&file, "bbbb\n").expect("write second content");

        let second = super::local_markdown_conflict_detection_key("local-md:README.md", &file)
            .expect("second conflict key");

        assert_ne!(first, second);

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_aggregate_exposes_file_version_alias() {
        let root = temp_root("mnote-local-file-version-aggregate");
        std::fs::write(root.join("README.md"), "# Versioned\n").expect("write md");
        let root_uri = format!("file://{}", root.display());

        let aggregate = resolve_local_markdown_page_aggregate(&root_uri, "local-md:README.md")
            .expect("aggregate");
        let body = serde_json::to_value(&aggregate.body).expect("body json");

        assert_eq!(body["fileVersion"], body["conflictDetectionKey"]);
        assert!(body["fileVersion"]
            .as_str()
            .expect("file version")
            .starts_with("local-md:local-md:README.md:"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_save_returns_file_version_alias() {
        let root = temp_root("mnote-local-file-version-save");
        std::fs::write(root.join("README.md"), "# Old\n").expect("write md");
        let root_uri = format!("file://{}", root.display());

        let result = save_local_markdown_page(
            &root_uri,
            "local-md:README.md",
            None,
            &serde_json::json!([
                {"type":"heading","props":{"level":1},"content":[{"type":"text","text":"New"}]}
            ]),
        )
        .expect("save");

        assert_eq!(result["fileVersion"], result["conflict_detection_key"]);
        assert!(result["fileVersion"]
            .as_str()
            .expect("file version")
            .starts_with("local-md:local-md:README.md:"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_write_contract_returns_page_body_write_command() {
        let root = temp_root("mnote-local-page-body-write-contract");
        std::fs::write(root.join("README.md"), "---\ntitle: Contract\n---\n# Old\n")
            .expect("write md");
        let root_uri = format!("file://{}", root.display());
        let aggregate = resolve_local_markdown_page_aggregate(&root_uri, "local-md:README.md")
            .expect("aggregate");
        let request = core_protocol::PageBodyWriteRequest {
            document_id: "local-md:README.md".into(),
            workspace_id: "local-ws:test".into(),
            source_kind: core_protocol::WorkspaceSourceKind::LocalFolder,
            root_uri: root_uri.clone(),
            expected_file_version: aggregate.body.file_version.as_str().map(ToOwned::to_owned),
            base_content_hash: Some("sha256:test-base".into()),
            content_format: "editorBlocks".into(),
            content: serde_json::json!([
                {"type":"heading","props":{"level":1},"content":[{"type":"text","text":"Written"}]}
            ]),
            editor_source: Some("unit-test".into()),
        };

        let result = write_local_markdown_page_body(&request).expect("write");

        assert_eq!(result["canonicalCommand"], "page.body.write");
        assert_eq!(result["compatCommand"], "page.body.save");
        assert_eq!(result["contentFormat"], "editorBlocks");
        assert_eq!(result["editorSource"], "unit-test");
        assert_eq!(result["fileVersion"], result["conflict_detection_key"]);
        let saved = std::fs::read_to_string(root.join("README.md")).expect("read md");
        assert!(saved.contains("# Written"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_parser_covers_basic_blocks_and_attachment_refs() {
        let blocks = crate::routes::local_markdown_parser::markdown_to_blocks(
            r#"# Title

paragraph

## Section
- bullet
1. numbered
> quote
```rust
fn main() {}
```
---
[Spec](attachments/spec.pdf)
| unsupported | table |
"#,
        );
        let block_types = blocks
            .as_array()
            .expect("blocks")
            .iter()
            .map(|block| block["type"].as_str().unwrap_or_default().to_string())
            .collect::<Vec<_>>();
        assert!(block_types.contains(&"heading".to_string()));
        assert!(block_types.contains(&"paragraph".to_string()));
        assert!(block_types.contains(&"bulletListItem".to_string()));
        assert!(block_types.contains(&"numberedListItem".to_string()));
        assert!(block_types.contains(&"quote".to_string()));
        assert!(block_types.contains(&"codeBlock".to_string()));
        assert!(block_types.contains(&"divider".to_string()));
        assert!(block_types.contains(&"media".to_string()));
        assert!(blocks.to_string().contains("attachments/spec.pdf"));
        assert!(blocks.to_string().contains("unsupported"));
    }

    #[test]
    fn local_markdown_parser_preserves_attachment_media_block() {
        let blocks = crate::routes::local_markdown_parser::markdown_to_blocks(
            "[Spec](attachments/spec.pdf)\n",
        );
        let array = blocks.as_array().expect("blocks");
        let media = array
            .iter()
            .find(|block| block["type"].as_str() == Some("media"))
            .expect("media block");
        assert_eq!(media["props"]["name"], "Spec");
        assert_eq!(media["props"]["sourcePath"], "attachments/spec.pdf");
    }

    #[test]
    fn local_markdown_save_preserves_frontmatter_and_writes_basic_blocks() {
        let root = temp_root("mnote-local-markdown-save-basic-blocks");
        std::fs::write(
            root.join("README.md"),
            "---\ntitle: Preserved\nmnote_id: stable\n---\n# Old\n",
        )
        .expect("write md");
        let root_uri = format!("file://{}", root.display());
        save_local_markdown_page(
            &root_uri,
            "local-mdid:stable",
            None,
            &serde_json::json!([
                {"type":"heading","props":{"level":2},"content":[{"type":"text","text":"Heading"}]},
                {"type":"bulletListItem","content":[{"type":"text","text":"Bullet"}]},
                {"type":"numberedListItem","content":[{"type":"text","text":"Numbered"}]},
                {"type":"quote","content":[{"type":"text","text":"Quoted"}]},
                {"type":"codeBlock","content":[{"type":"text","text":"let x = 1;"}]},
                {"type":"divider"},
                {"type":"media","props":{"name":"Spec","sourcePath":"attachments/spec.pdf"}},
                {"type":"table","props":{"tiptapTable":{"type":"table","content":[
                    {"type":"tableRow","content":[
                        {"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":null},"content":[{"type":"paragraph","content":[{"type":"text","text":"左","styles":{}}]}]},
                        {"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":null},"content":[{"type":"paragraph","content":[{"type":"text","text":"右","styles":{}}]}]}
                    ]},
                    {"type":"tableRow","content":[
                        {"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":null},"content":[{"type":"paragraph","content":[{"type":"text","text":"A","styles":{}}]}]},
                        {"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":null},"content":[{"type":"paragraph","content":[{"type":"text","text":"B","styles":{}}]}]}
                    ]}
                ]}}}
            ]),
        )
        .expect("save");

        let saved = std::fs::read_to_string(root.join("README.md")).expect("read md");
        assert!(saved.starts_with("---\ntitle: Preserved\nmnote_id: stable\n---\n"));
        assert!(saved.contains("## Heading"));
        assert!(saved.contains("- Bullet"));
        assert!(saved.contains("1. Numbered"));
        assert!(saved.contains("> Quoted"));
        assert!(saved.contains("```\nlet x = 1;\n```"));
        assert!(saved.contains("[Spec](attachments/spec.pdf)"));
        assert!(saved.contains("| 左 | 右 |"));
        assert!(saved.contains("| --- | --- |"));
        assert!(saved.contains("| A | B |"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_save_writes_task_list_and_inline_marks() {
        let root = temp_root("mnote-local-markdown-save-inline-marks");
        std::fs::write(root.join("README.md"), "---\ntitle: Inline\n---\n# Old\n")
            .expect("write md");
        let root_uri = format!("file://{}", root.display());
        save_local_markdown_page(
            &root_uri,
            "local-md:README.md",
            None,
            &serde_json::json!([
                {
                    "type":"todo",
                    "props":{"checked":true},
                    "content":[
                        {"type":"text","text":"3000","styles":{"code":true}},
                        {"type":"text","text":" 默认由 "},
                        {"type":"text","text":"mnote-web","styles":{"bold":true}},
                        {"type":"text","text":" 监听"}
                    ]
                },
                {
                    "type":"todo",
                    "props":{"checked":false},
                    "content":[
                        {"type":"text","text":"待办","styles":{"italic":true}},
                        {"type":"text","text":" "},
                        {"type":"text","text":"删除","styles":{"strike":true}},
                        {"type":"text","text":" "},
                        {"type":"text","text":"链接","styles":{"link":"https://example.com"}}
                    ]
                }
            ]),
        )
        .expect("save");

        let saved = std::fs::read_to_string(root.join("README.md")).expect("read md");
        assert!(saved.contains("- [x] `3000` 默认由 **mnote-web** 监听"));
        assert!(saved.contains("- [ ] *待办* ~~删除~~ [链接](https://example.com)"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_save_rejects_stale_external_file_change() {
        let root = temp_root("mnote-local-markdown-save-stale-conflict");
        std::fs::write(root.join("README.md"), "---\ntitle: Stale\n---\n# Old\n")
            .expect("write md");
        let root_uri = format!("file://{}", root.display());
        let aggregate = resolve_local_markdown_page_aggregate(&root_uri, "local-md:README.md")
            .expect("aggregate");
        let stale_key = aggregate
            .body
            .conflict_detection_key
            .as_str()
            .expect("conflict key")
            .to_string();

        std::thread::sleep(std::time::Duration::from_millis(5));
        std::fs::write(
            root.join("README.md"),
            "---\ntitle: Stale\n---\n# External\n",
        )
        .expect("external write");

        let error = save_local_markdown_page(
            &root_uri,
            "local-md:README.md",
            Some(&stale_key),
            &serde_json::json!([
                {"type":"heading","props":{"level":1},"content":[{"type":"text","text":"Editor"}]}
            ]),
        )
        .expect_err("stale save should fail");
        assert!(error.message().contains("本地 Markdown 文件已被外部修改"));

        let saved = std::fs::read_to_string(root.join("README.md")).expect("read md");
        assert!(saved.contains("# External"));
        assert!(!saved.contains("# Editor"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_save_writes_table_inline_marks() {
        let root = temp_root("mnote-local-markdown-save-table-inline-marks");
        std::fs::write(root.join("README.md"), "---\ntitle: Table\n---\n# Old\n")
            .expect("write md");
        let root_uri = format!("file://{}", root.display());
        save_local_markdown_page(
            &root_uri,
            "local-md:README.md",
            None,
            &serde_json::json!([
                {"type":"table","props":{"tiptapTable":{"type":"table","content":[
                    {"type":"tableRow","content":[
                        {"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":null},"content":[{"type":"paragraph","content":[{"type":"text","text":"左","styles":{}}]}]},
                        {"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":null},"content":[{"type":"paragraph","content":[{"type":"text","text":"右","styles":{}}]}]}
                    ]},
                    {"type":"tableRow","content":[
                        {"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":null},"content":[{"type":"paragraph","content":[{"type":"text","text":"A","styles":{"code":true}}]}]},
                        {"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":null},"content":[{"type":"paragraph","content":[{"type":"text","text":"B","styles":{"bold":true}}]}]}
                    ]}
                ]}}}
            ]),
        )
        .expect("save");

        let saved = std::fs::read_to_string(root.join("README.md")).expect("read md");
        assert!(saved.contains("| `A` | **B** |"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_save_round_trips_tiptap_table_marks() {
        let root = temp_root("mnote-local-markdown-save-table-marks-roundtrip");
        std::fs::write(
            root.join("README.md"),
            "---\ntitle: Table Marks\n---\n# Old\n",
        )
        .expect("write md");
        let root_uri = format!("file://{}", root.display());
        let parsed = crate::routes::local_markdown_parser::markdown_to_blocks(
            "| 左 | 右 |\n| --- | --- |\n| `A` | **B** |\n",
        );
        save_local_markdown_page(&root_uri, "local-md:README.md", None, &parsed).expect("save");

        let saved = std::fs::read_to_string(root.join("README.md")).expect("read md");
        assert!(saved.contains("| `A` | **B** |"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_save_writes_table_alignment_markers() {
        let root = temp_root("mnote-local-markdown-save-table-alignments");
        std::fs::write(
            root.join("README.md"),
            "---\ntitle: Table Align\n---\n# Old\n",
        )
        .expect("write md");
        let root_uri = format!("file://{}", root.display());
        save_local_markdown_page(
            &root_uri,
            "local-md:README.md",
            None,
            &serde_json::json!([
                {"type":"table","props":{"tiptapTable":{"type":"table","content":[
                    {"type":"tableRow","content":[
                        {"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"textAlign":"left"},"content":[{"type":"paragraph","content":[{"type":"text","text":"左","styles":{}}]}]},
                        {"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"textAlign":"center"},"content":[{"type":"paragraph","content":[{"type":"text","text":"中","styles":{}}]}]},
                        {"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"textAlign":"right"},"content":[{"type":"paragraph","content":[{"type":"text","text":"右","styles":{}}]}]}
                    ]},
                    {"type":"tableRow","content":[
                        {"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"textAlign":"left"},"content":[{"type":"paragraph","content":[{"type":"text","text":"A","styles":{}}]}]},
                        {"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"textAlign":"center"},"content":[{"type":"paragraph","content":[{"type":"text","text":"B","styles":{}}]}]},
                        {"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"textAlign":"right"},"content":[{"type":"paragraph","content":[{"type":"text","text":"C","styles":{}}]}]}
                    ]}
                ]}}}
            ]),
        )
        .expect("save");

        let saved = std::fs::read_to_string(root.join("README.md")).expect("read md");
        assert!(saved.contains("| :--- | :---: | ---: |"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_save_writes_image_blocks_as_markdown_images() {
        let root = temp_root("mnote-local-markdown-save-image-block");
        std::fs::write(root.join("README.md"), "---\ntitle: Image\n---\n# Old\n")
            .expect("write md");
        let root_uri = format!("file://{}", root.display());

        save_local_markdown_page(
            &root_uri,
            "local-md:README.md",
            None,
            &serde_json::json!([
                {
                    "type": "image",
                    "props": {
                        "src": "README.assets/photo.png",
                        "alt": "示例图片",
                        "title": "示例图片"
                    }
                }
            ]),
        )
        .expect("save");

        let saved = std::fs::read_to_string(root.join("README.md")).expect("read md");
        assert!(saved.contains("![示例图片](README.assets/photo.png)"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_workspace_access_rejects_owner_mismatch() {
        let root = temp_root("mnote-local-workspace-owner-mismatch");
        std::fs::create_dir_all(root.join(".mnote")).expect("create metadata dir");
        std::fs::write(
            root.join(".mnote").join("workspace.json"),
            r#"{"workspaceId":"local-ws-demo","ownerId":"user_a","createdAt":"2026-05-18T00:00:00Z","capabilities":["local_files"]}"#,
        )
        .expect("write workspace manifest");
        let root_uri = format!("file://{}", root.display());

        let error = ensure_local_workspace_access_for_actor("user_b", "user", &root_uri)
            .expect_err("owner mismatch must be rejected");

        assert_eq!(error.status(), axum::http::StatusCode::FORBIDDEN);
        assert!(error.message().contains("无权"));
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_workspace_access_allows_admin_without_manifest() {
        let _guard = env_lock().lock().expect("env lock");
        let root = temp_root("mnote-local-workspace-admin-any-root");
        let root_uri = format!("file://{}", root.display());
        std::env::set_var("MNOTE_ADMIN_USER_IDS", "user_admin");

        let allowed = ensure_local_workspace_access_for_actor("user_admin", "user", &root_uri)
            .expect("admin can write any local directory");

        assert_eq!(allowed, root.canonicalize().expect("canonical root"));
        std::env::remove_var("MNOTE_ADMIN_USER_IDS");
        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_workspace_access_policy_grants_read_and_write_separately() {
        let _guard = env_lock().lock().expect("env lock");
        let root = temp_root("mnote-local-workspace-policy-root");
        let policy_root = temp_root("mnote-local-workspace-policy-config");
        let policy_file = policy_root.join("access-policy.json");
        let root_uri = format!("file://{}", root.display());
        std::env::set_var("MNOTE_LOCAL_ACCESS_POLICY_FILE", &policy_file);
        std::fs::write(
            &policy_file,
            serde_json::json!({
                "grants": [
                    {
                        "userId": "user_reader",
                        "rootUri": root_uri,
                        "permission": "read",
                        "recursive": true
                    }
                ]
            })
            .to_string(),
        )
        .expect("write policy");

        ensure_local_workspace_read_access_for_actor("user_reader", "user", &root_uri)
            .expect("read grant can read local directory");
        let write_error = ensure_local_workspace_access_for_actor("user_reader", "user", &root_uri)
            .expect_err("read grant must not write");
        assert_eq!(write_error.status(), axum::http::StatusCode::FORBIDDEN);

        std::fs::write(
            &policy_file,
            serde_json::json!({
                "grants": [
                    {
                        "userId": "user_writer",
                        "rootUri": root_uri,
                        "permission": "write",
                        "recursive": true
                    }
                ]
            })
            .to_string(),
        )
        .expect("write policy");
        ensure_local_workspace_access_for_actor("user_writer", "user", &root_uri)
            .expect("write grant can write local directory");

        std::env::remove_var("MNOTE_LOCAL_ACCESS_POLICY_FILE");
        let _ = std::fs::remove_dir_all(&root);
        let _ = std::fs::remove_dir_all(&policy_root);
    }

    #[test]
    fn local_path_read_access_rejects_root_escape() {
        let _guard = env_lock().lock().expect("env lock");
        let root = temp_root("mnote-local-path-read-root");
        let outside = temp_root("mnote-local-path-read-outside");
        init_workspace(&root);
        std::fs::write(root.join("inside.md"), "inside").expect("write inside");
        std::fs::write(outside.join("outside.md"), "outside").expect("write outside");
        let context = request_context("user_test", "user");
        let root_uri = format!("file://{}", root.display());

        let inside = ensure_local_path_read_access(&context, &root_uri, "inside.md")
            .expect("relative file inside root can be read");
        assert_eq!(
            inside,
            root.join("inside.md").canonicalize().expect("inside")
        );

        let escape_error = ensure_local_path_read_access(
            &context,
            &root_uri,
            &outside.join("outside.md").display().to_string(),
        )
        .expect_err("absolute path outside root must be rejected");
        assert_eq!(escape_error.status(), StatusCode::BAD_REQUEST);

        let _ = std::fs::remove_dir_all(&root);
        let _ = std::fs::remove_dir_all(&outside);
    }

    #[tokio::test]
    async fn local_access_policy_admin_api_rejects_non_admin_and_validates_root() {
        let _guard = env_lock().lock().expect("env lock");
        let root = temp_root("mnote-local-access-policy-validate-root");
        let policy_root = temp_root("mnote-local-access-policy-validate-config");
        let policy_file = policy_root.join("access-policy.json");
        std::env::set_var("MNOTE_LOCAL_ACCESS_POLICY_FILE", &policy_file);

        let non_admin_error = get_local_access_policy(Extension(request_context("user_1", "user")))
            .await
            .expect_err("non-admin cannot read access policy");
        assert_eq!(non_admin_error.status(), StatusCode::FORBIDDEN);

        std::env::set_var("MNOTE_ADMIN_USER_IDS", "admin_1");
        let (_, Json(payload)) = validate_local_access_root(
            Extension(request_context("admin_1", "user")),
            Json(LocalAccessValidateRootRequest {
                root_uri: format!("file://{}", root.display()),
                root_path: String::new(),
            }),
        )
        .await
        .expect("admin can validate root");
        assert_eq!(payload["ok"], true);
        assert_eq!(
            payload["rootPath"],
            root.canonicalize()
                .expect("canonical root")
                .display()
                .to_string()
        );

        let invalid_error = validate_local_access_root(
            Extension(request_context("admin_1", "user")),
            Json(LocalAccessValidateRootRequest {
                root_uri: format!("file://{}", root.join("missing").display()),
                root_path: String::new(),
            }),
        )
        .await
        .expect_err("missing root should be rejected");
        assert_eq!(invalid_error.status(), StatusCode::BAD_REQUEST);

        std::env::remove_var("MNOTE_ADMIN_USER_IDS");
        std::env::remove_var("MNOTE_LOCAL_ACCESS_POLICY_FILE");
        let _ = std::fs::remove_dir_all(&root);
        let _ = std::fs::remove_dir_all(&policy_root);
    }

    #[tokio::test]
    async fn local_access_policy_admin_api_creates_and_deletes_grant() {
        let _guard = env_lock().lock().expect("env lock");
        let root = temp_root("mnote-local-access-policy-grant-root");
        let policy_root = temp_root("mnote-local-access-policy-grant-config");
        let policy_file = policy_root.join("access-policy.json");
        let root_uri = format!("file://{}", root.display());
        std::env::set_var("MNOTE_LOCAL_ACCESS_POLICY_FILE", &policy_file);
        std::env::set_var("MNOTE_ADMIN_USER_IDS", "admin_1");

        let (_, Json(created)) = create_local_access_grant(
            Extension(request_context("admin_1", "user")),
            Json(LocalAccessGrantRequest {
                id: "grant_reader".into(),
                user_id: "user_reader".into(),
                root_uri: root_uri.clone(),
                root_path: String::new(),
                permission: "read".into(),
                recursive: true,
                capabilities: vec!["ai".into(), "share".into()],
            }),
        )
        .await
        .expect("admin can create read grant");
        assert_eq!(created["grant"]["id"], "grant_reader");
        assert_eq!(created["grant"]["permission"], "read");
        ensure_local_workspace_read_access_for_actor("user_reader", "user", &root_uri)
            .expect("created read grant can read");
        let write_error = ensure_local_workspace_access_for_actor("user_reader", "user", &root_uri)
            .expect_err("created read grant cannot write");
        assert_eq!(write_error.status(), StatusCode::FORBIDDEN);

        let duplicate_error = add_local_access_grant_for_context(
            &request_context("admin_1", "user"),
            LocalAccessGrantRequest {
                id: "grant_reader".into(),
                user_id: "user_reader".into(),
                root_uri: root_uri.clone(),
                root_path: String::new(),
                permission: "read".into(),
                recursive: true,
                capabilities: vec!["ai".into(), "share".into()],
            },
        )
        .expect_err("duplicate grant id should be rejected");
        assert_eq!(duplicate_error.status(), StatusCode::BAD_REQUEST);

        let (_, Json(deleted)) = super::delete_local_access_grant(
            Extension(request_context("admin_1", "user")),
            AxumPath("grant_reader".into()),
        )
        .await
        .expect("admin can delete grant");
        assert_eq!(deleted["deletedGrantId"], "grant_reader");
        let read_error =
            ensure_local_workspace_read_access_for_actor("user_reader", "user", &root_uri)
                .expect_err("deleted grant should remove read access");
        assert_eq!(read_error.status(), StatusCode::FORBIDDEN);

        std::env::remove_var("MNOTE_ADMIN_USER_IDS");
        std::env::remove_var("MNOTE_LOCAL_ACCESS_POLICY_FILE");
        let _ = std::fs::remove_dir_all(&root);
        let _ = std::fs::remove_dir_all(&policy_root);
    }

    #[tokio::test]
    async fn share_grant_admin_api_creates_reads_and_revokes_without_local_access() {
        let _guard = env_lock().lock().expect("env lock");
        let root = temp_root("mnote-share-grant-workspace-root");
        let config_root = temp_root("mnote-share-grant-config-root");
        let access_policy_file = config_root.join("access-policy.json");
        let share_grants_file = config_root.join("share-grants.json");
        let root_uri = format!("file://{}", root.display());
        std::env::set_var("MNOTE_LOCAL_ACCESS_POLICY_FILE", &access_policy_file);
        std::env::set_var("MNOTE_SHARE_GRANTS_FILE", &share_grants_file);
        std::env::set_var("MNOTE_ADMIN_USER_IDS", "admin_1");

        let non_admin_error = get_share_grants(Extension(request_context("user_1", "user")))
            .await
            .expect_err("non-admin cannot read share grants");
        assert_eq!(non_admin_error.status(), StatusCode::FORBIDDEN);

        let (_, Json(created)) = create_share_grant(
            Extension(request_context("admin_1", "user")),
            Json(LocalShareGrantRequest {
                id: "share_grant_1".into(),
                share_id: "share_1".into(),
                owner_user_id: "owner_1".into(),
                target_user_id: "target_1".into(),
                root_uri: root_uri.clone(),
                root_path: String::new(),
                document_id: "doc_1".into(),
                allowed_resource_ids: vec!["doc_1".into()],
                permission: "read".into(),
                capabilities: vec!["ai".into(), "share".into()],
            }),
        )
        .await
        .expect("admin can create share grant");
        assert_eq!(created["grant"]["id"], "share_grant_1");
        assert_eq!(created["grant"]["shareId"], "share_1");
        assert_eq!(created["grant"]["active"], true);

        let read_error =
            ensure_local_workspace_read_access_for_actor("target_1", "user", &root_uri)
                .expect_err("share grant must not grant local filesystem read access");
        assert_eq!(read_error.status(), StatusCode::FORBIDDEN);
        let write_error = ensure_local_workspace_access_for_actor("target_1", "user", &root_uri)
            .expect_err("share grant must not grant local filesystem write access");
        assert_eq!(write_error.status(), StatusCode::FORBIDDEN);

        let (_, Json(listed)) = get_share_grants(Extension(request_context("admin_1", "user")))
            .await
            .expect("admin can list share grants");
        assert_eq!(listed["grants"][0]["id"], "share_grant_1");
        assert_eq!(listed["grants"][0]["active"], true);

        let (_, Json(revoked)) = super::delete_share_grant(
            Extension(request_context("admin_1", "user")),
            AxumPath("share_1".into()),
        )
        .await
        .expect("admin can revoke by share id");
        assert_eq!(revoked["revokedShareId"], "share_1");
        assert_eq!(revoked["grant"]["active"], false);
        assert!(
            revoked["grant"]["revokedAt"]
                .as_str()
                .unwrap_or_default()
                .len()
                > 0
        );

        let stored = std::fs::read_to_string(&share_grants_file).expect("read share grants file");
        let stored_json: Value = serde_json::from_str(&stored).expect("share grants json");
        assert_eq!(stored_json["grants"][0]["active"], false);

        std::env::remove_var("MNOTE_ADMIN_USER_IDS");
        std::env::remove_var("MNOTE_LOCAL_ACCESS_POLICY_FILE");
        std::env::remove_var("MNOTE_SHARE_GRANTS_FILE");
        let _ = std::fs::remove_dir_all(&root);
        let _ = std::fs::remove_dir_all(&config_root);
    }

    #[tokio::test]
    async fn shared_cache_and_sync_state_record_permissions_and_conflict_report() {
        let _guard = env_lock().lock().expect("env lock");
        let root = temp_root("mnote-shared-cache-sync-root");
        let config_root = temp_root("mnote-shared-cache-sync-config");
        let access_policy_file = config_root.join("access-policy.json");
        let share_grants_file = config_root.join("share-grants.json");
        let root_uri = format!("file://{}", root.display());
        std::fs::create_dir_all(root.join(".mnote")).expect("metadata");
        std::env::set_var("MNOTE_LOCAL_ACCESS_POLICY_FILE", &access_policy_file);
        std::env::set_var("MNOTE_SHARE_GRANTS_FILE", &share_grants_file);
        std::env::set_var("MNOTE_ADMIN_USER_IDS", "admin_1");

        let (read_status, Json(read_share_payload)) = create_share_grant(
            Extension(request_context("admin_1", "user")),
            Json(LocalShareGrantRequest {
                id: "share_grant_sync_read".into(),
                share_id: "share_sync_read".into(),
                owner_user_id: "owner_1".into(),
                target_user_id: "target_1".into(),
                root_uri: root_uri.clone(),
                root_path: String::new(),
                document_id: "local-md:README.md".into(),
                allowed_resource_ids: vec!["local-md:README.md".into()],
                permission: "read".into(),
                capabilities: vec!["ai".into(), "share".into()],
            }),
        )
        .await
        .expect("create read share");
        assert_eq!(read_status, StatusCode::OK);
        assert_eq!(read_share_payload["grant"]["shareId"], "share_sync_read");
        let (write_status, Json(write_share_payload)) = create_share_grant(
            Extension(request_context("admin_1", "user")),
            Json(LocalShareGrantRequest {
                id: "share_grant_sync_write".into(),
                share_id: "share_sync_write".into(),
                owner_user_id: "owner_1".into(),
                target_user_id: "target_1".into(),
                root_uri: root_uri.clone(),
                root_path: String::new(),
                document_id: "local-md:README.md".into(),
                allowed_resource_ids: vec!["local-md:README.md".into()],
                permission: "write".into(),
                capabilities: vec!["ai".into(), "share".into()],
            }),
        )
        .await
        .expect("create write share");
        assert_eq!(write_status, StatusCode::OK);
        assert_eq!(write_share_payload["grant"]["shareId"], "share_sync_write");

        let (_, Json(cache_payload)) = record_shared_cache(
            Extension(request_context("target_1", "user")),
            Json(SharedCacheRecordRequest {
                root_uri: root_uri.clone(),
                share_id: "share_sync_read".into(),
                permission: "read".into(),
                remote_version: "remote-1".into(),
                base_version: "base-1".into(),
                source_actor: "owner_1".into(),
            }),
        )
        .await
        .expect("record cache");
        assert_eq!(cache_payload["share"]["remoteVersion"], "remote-1");
        let cache_json =
            std::fs::read_to_string(root.join(".mnote").join("share-cache.json")).expect("cache");
        assert!(cache_json.contains("share_sync_read"));
        assert!(cache_json.contains("remote-1"));

        let read_pending_error = record_sync_pending_change(
            Extension(request_context("target_1", "user")),
            Json(SyncPendingChangeRequest {
                root_uri: root_uri.clone(),
                share_id: "share_sync_read".into(),
                resource_id: "local-md:README.md".into(),
                local_version: "local-1".into(),
                base_version: "remote-1".into(),
                remote_version: "remote-1".into(),
                change_summary: "read share write attempt".into(),
            }),
        )
        .await
        .expect_err("shared_read cannot write pending changes");
        assert_eq!(read_pending_error.status(), StatusCode::FORBIDDEN);

        let (_, Json(pending_payload)) = record_sync_pending_change(
            Extension(request_context("target_1", "user")),
            Json(SyncPendingChangeRequest {
                root_uri: root_uri.clone(),
                share_id: "share_sync_write".into(),
                resource_id: "local-md:README.md".into(),
                local_version: "local-2".into(),
                base_version: "remote-1".into(),
                remote_version: "remote-1".into(),
                change_summary: "写入共享页面".into(),
            }),
        )
        .await
        .expect("shared_write can record pending change");
        assert_eq!(
            pending_payload["pendingChange"]["resourceId"],
            "local-md:README.md"
        );
        let sync_state =
            std::fs::read_to_string(root.join(".mnote").join("sync-state.json")).expect("sync");
        assert!(sync_state.contains("share_sync_write"));
        assert!(sync_state.contains("写入共享页面"));

        let conflict_error = record_sync_pending_change(
            Extension(request_context("target_1", "user")),
            Json(SyncPendingChangeRequest {
                root_uri: root_uri.clone(),
                share_id: "share_sync_write".into(),
                resource_id: "local-md:README.md".into(),
                local_version: "local-3".into(),
                base_version: "remote-1".into(),
                remote_version: "remote-2".into(),
                change_summary: "冲突写入".into(),
            }),
        )
        .await
        .expect_err("remote changed since base");
        assert_eq!(conflict_error.status(), StatusCode::CONFLICT);

        let (_, Json(report_payload)) = write_sync_conflict_report(
            Extension(request_context("target_1", "user")),
            Json(SyncConflictReportRequest {
                root_uri,
                share_id: "share_sync_write".into(),
                resource_id: "local-md:README.md".into(),
                local_version: "local-3".into(),
                remote_version: "remote-2".into(),
                base_version: "remote-1".into(),
                actor_id: "target_1".into(),
                summary: "同步冲突".into(),
            }),
        )
        .await
        .expect("write conflict report");
        assert_eq!(report_payload["report"]["source"], "shared_sync");
        assert_eq!(report_payload["report"]["shareId"], "share_sync_write");
        assert!(root.join(".mnote").join("sync-reports").is_dir());

        std::env::remove_var("MNOTE_ADMIN_USER_IDS");
        std::env::remove_var("MNOTE_LOCAL_ACCESS_POLICY_FILE");
        std::env::remove_var("MNOTE_SHARE_GRANTS_FILE");
        let _ = std::fs::remove_dir_all(&root);
        let _ = std::fs::remove_dir_all(&config_root);
    }

    #[test]
    fn create_default_local_workspace_uses_managed_data_root() {
        let base = temp_root("mnote-local-managed-data-root");
        let payload =
            create_default_local_workspace_for_actor_at_base("user@example.com", "user", &base)
                .expect("create default workspace");
        let root_uri = payload["workspace"]["rootUri"]
            .as_str()
            .expect("root uri")
            .to_string();
        let root_path = payload["workspace"]["rootPath"]
            .as_str()
            .expect("root path");
        let expected_root = base
            .join("users")
            .join("user~40example.com")
            .join("workspaces")
            .join("my-space");

        assert_eq!(std::path::Path::new(root_path), expected_root.as_path());
        assert!(expected_root.join(".mnote").join("workspace.json").exists());
        assert!(expected_root.join("pages").join("我的空间.md").exists());
        assert!(expected_root.join("assets").join("shared").is_dir());
        assert!(expected_root.join("ai-sessions").join("private").is_dir());
        assert_eq!(
            payload["workspace"]["manifest"]["workspaceId"],
            "local-ws:user~40example.com:my-space"
        );
        assert_eq!(
            payload["workspace"]["manifest"]["ownerId"],
            "user@example.com"
        );
        assert!(payload["workspace"]["manifest"]["capabilities"]
            .as_array()
            .expect("capabilities")
            .iter()
            .any(|value| value.as_str() == Some("markdown_edit")));
        ensure_local_workspace_access_for_actor("user@example.com", "user", &root_uri)
            .expect("owner can access managed workspace");

        let second =
            create_default_local_workspace_for_actor_at_base("user@example.com", "user", &base)
                .expect("idempotent create");
        assert_eq!(
            second["workspace"]["rootUri"],
            payload["workspace"]["rootUri"]
        );

        let _ = std::fs::remove_dir_all(&base);
    }

    #[test]
    fn local_tree_command_refreshes_search_index_after_rename() {
        let root = temp_root("mnote-local-tree-refresh-search-index");
        init_workspace(&root);
        std::fs::write(
            root.join("search-target.md"),
            "# Search Target\nrename-token\n",
        )
        .expect("write md");
        let root_uri = format!("file://{}", root.display());

        crate::routes::local_search_index::refresh_local_search_index(
            &root,
            &root_uri,
            "local-ws-search-index-test",
        )
        .expect("initial index");
        let before =
            std::fs::read_to_string(root.join(".mnote").join("index").join("search-index.json"))
                .expect("before index");
        assert!(before.contains("search-target.md"));

        execute_local_tree_command(
            &root_uri,
            "rename",
            "local-md:search-target.md",
            None,
            Some("Renamed Target"),
        )
        .expect("rename");

        let after =
            std::fs::read_to_string(root.join(".mnote").join("index").join("search-index.json"))
                .expect("after index");
        assert!(after.contains("Renamed Target.md"), "{after}");
        assert!(!after.contains("search-target.md"), "{after}");

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_save_refreshes_search_index_after_write() {
        let root = temp_root("mnote-local-save-refresh-search-index");
        init_workspace(&root);
        std::fs::write(root.join("README.md"), "# Before\nold-token\n").expect("write md");
        let root_uri = format!("file://{}", root.display());

        crate::routes::local_search_index::refresh_local_search_index(
            &root,
            &root_uri,
            "local-ws-search-index-test",
        )
        .expect("initial index");
        save_local_markdown_page(
            &root_uri,
            "local-md:README.md",
            None,
            &serde_json::json!([
                {
                    "id": "heading_1",
                    "type": "heading",
                    "props": { "level": 1 },
                    "content": [{ "type": "text", "text": "After" }]
                },
                {
                    "id": "p_1",
                    "type": "paragraph",
                    "content": [{ "type": "text", "text": "new-token" }]
                }
            ]),
        )
        .expect("save markdown");

        let index =
            std::fs::read_to_string(root.join(".mnote").join("index").join("search-index.json"))
                .expect("index");
        assert!(index.contains("new-token"), "{index}");
        assert!(!index.contains("old-token"), "{index}");

        let _ = std::fs::remove_dir_all(&root);
    }

    #[test]
    fn local_markdown_asset_upload_copies_next_to_markdown_with_relative_path() {
        let root = temp_root("mnote-local-markdown-asset-upload");
        init_workspace(&root);
        std::fs::create_dir_all(root.join("docs")).expect("create docs");
        std::fs::write(root.join("docs").join("README.md"), "# Assets\n").expect("write md");
        std::fs::create_dir_all(root.join("docs").join("README.assets")).expect("create assets");
        std::fs::write(
            root.join("docs").join("README.assets").join("photo.png"),
            b"old",
        )
        .expect("write existing asset");
        let root_uri = format!("file://{}", root.display());

        let asset = write_local_markdown_asset(
            &root_uri,
            "local-md:docs~2FREADME.md",
            "image",
            LocalUploadFile {
                name: "photo.png".to_string(),
                content_type: "image/png".to_string(),
                bytes: b"new-image".to_vec(),
            },
        )
        .expect("upload asset");

        assert_eq!(asset["sourcePath"], "README.assets/photo-1.png");
        assert_eq!(asset["file_url"], "README.assets/photo-1.png");
        assert_eq!(asset["asset_type"], "image");
        assert_eq!(asset["sourceKind"], "local_folder");
        assert_eq!(
            std::fs::read(root.join("docs").join("README.assets").join("photo-1.png"))
                .expect("read copied asset"),
            b"new-image"
        );

        let _ = std::fs::remove_dir_all(&root);
    }

    #[tokio::test]
    async fn local_file_open_rejects_root_escape() {
        let root = temp_root("mnote-local-file-open-root-escape");
        std::fs::write(root.join("README.txt"), "hello").expect("write file");
        init_workspace(&root);
        let root_uri = format!("file://{}", root.display());
        let mut headers = HeaderMap::new();
        headers.insert("x-mnote-actor-id", "user_test".parse().unwrap());
        headers.insert("x-mnote-actor-type", "user".parse().unwrap());
        let context = RequestContext::from_http_parts(
            &Method::GET,
            &"/api/local-folder/files/open".parse().expect("uri"),
            &headers,
        );
        let query = LocalFileOpenQuery {
            root_uri,
            path: "../escape.txt".into(),
            download: None,
        };

        let error = open_local_file(Extension(context), Query(query))
            .await
            .expect_err("should reject root escape");
        assert_eq!(error.status(), StatusCode::BAD_REQUEST);
        assert!(error.message().contains("root"));

        let _ = std::fs::remove_dir_all(&root);
    }

    #[tokio::test]
    async fn local_file_open_allows_read_grant() {
        let _guard = env_lock().lock().expect("env lock");
        let root = temp_root("mnote-local-file-open-read-grant-root");
        let policy_root = temp_root("mnote-local-file-open-read-grant-config");
        let policy_file = policy_root.join("access-policy.json");
        let root_uri = format!("file://{}", root.display());
        std::fs::write(root.join("README.txt"), "hello").expect("write file");
        std::env::set_var("MNOTE_LOCAL_ACCESS_POLICY_FILE", &policy_file);
        std::fs::write(
            &policy_file,
            serde_json::json!({
                "grants": [
                    {
                        "userId": "user_reader",
                        "rootUri": root_uri,
                        "permission": "read",
                        "recursive": true
                    }
                ]
            })
            .to_string(),
        )
        .expect("write policy");

        let mut headers = HeaderMap::new();
        headers.insert("x-mnote-actor-id", "user_reader".parse().unwrap());
        headers.insert("x-mnote-actor-type", "user".parse().unwrap());
        let context = RequestContext::from_http_parts(
            &Method::GET,
            &"/api/local-folder/files/open".parse().expect("uri"),
            &headers,
        );

        let (_, _, bytes) = open_local_file(
            Extension(context),
            Query(LocalFileOpenQuery {
                root_uri,
                path: "README.txt".into(),
                download: None,
            }),
        )
        .await
        .expect("read grant can open local file");
        assert_eq!(bytes, b"hello");

        std::env::remove_var("MNOTE_LOCAL_ACCESS_POLICY_FILE");
        let _ = std::fs::remove_dir_all(&root);
        let _ = std::fs::remove_dir_all(&policy_root);
    }
}