@spacecorexdev/core 0.0.2 → 0.0.5

package/src/ui/FileManager/hooks/useFileManagerActions.ts

@@ -0,0 +1,2532 @@
+import React, { useCallback, useRef, useMemo, useState, useEffect } from 'react';
+import { useSearchParams } from 'react-router-dom';
+import { message, Modal, DatePicker, Input } from 'antd';
+import dayjs, { Dayjs } from 'dayjs';
+import { API } from '../../../api/index';
+import { ResponseCode } from '../../../api/_base';
+import { ProjectFile, ProjectRole, FileManagerApi, FileManagerFeatures, FileSortBy } from '../types';
+import { projectFileManagerApi } from '../projectFileManagerApi';
+import { CacheUserInfo } from '../../../utils/CacheUserInfo';
+import { CachePermissionInfo, PERMISSION_FOLDER_DOWNLOAD } from '../../../utils/CachePermissionInfo';
+import { CacheFileContent, CacheFileMeta } from '../../../utils/CacheFileContent';
+import { buildFileTree, getDescendantIds, getFileDescendants, sortFiles } from '../utils/fileTree';
+import { uploadFileBlob, uploadFileDelta, uploadMarkdownDelta, sanitizeFileName, getFileExtension, stripFileExtension, getMimeType, calculateCRC32, extractFilesFromDrop } from '../utils/fileUpload';
+import { uiFilePreview } from '../../UIFilePreview/index';
+import uiConfirm from '../../UIConfirm';
+import { getViewMode, setViewMode as saveViewMode } from '../../../utils/CacheViewToggleInfo';
+import { copyToClipboard } from '../../../utils/clipboard';
+import {
+  listLocalFilesByProject,
+  createLocalOnlyFile,
+  saveUnsyncedServerFile,
+  updateLocalFileContent,
+  markLocalFileSynced,
+  deleteLocalFile,
+  getLocalFileByServerId,
+  getLocalFile,
+  LocalFileRecord,
+} from '../../UIFilePreview/IndexedDBUtils';
+import uiToast from '../../UIToast';
+import { CONTRACTS_VIRTUAL_FOLDER_ID, filterNotesRootFiles } from '../utils/fileUtils';
+
+const PAGE_KEY = 'file-manager';
+const FILE_DESCS_MAX_LENGTH = 255;
+const CONTRACTS_FOLDER_NAME = '__contracts__';
+
+/** 冲突检查结果：no-conflict 走差分；overwrite 走全量覆盖；cancel 终止上传 */
+type ConflictCheckResult = 'no-conflict' | 'overwrite' | 'cancel';
+
+/** 冲突检查 + 服务器最新元数据 */
+interface ConflictCheckInfo {
+  result: ConflictCheckResult;
+  /** 服务器最新文件 CRC32（如果能拿到） */
+  serverCrc32?: number;
+  /** 服务器最新 fileResourcePath（如果能拿到） */
+  serverFileResourcePath?: string;
+}
+
+/**
+ * 上传前冲突检查：对比编辑开始时的 uploadTime 与服务端最新 uploadTime。
+ * 若服务端文件已被其他用户更新，弹框询问是否覆盖。
+ * 同时返回服务器最新 crc32，用于校验差分基准是否与服务端一致。
+ */
+const checkFileUpdateConflict = async (api: FileManagerApi, editingFile: ProjectFile): Promise<ConflictCheckInfo> => {
+  // 本地新建文件无原版本可对比，直接放行
+  if (editingFile.isLocalOnly) return { result: 'no-conflict' };
+  try {
+    const res = await api.getDetail(editingFile.id);
+    if (res.code !== ResponseCode.SUCCESS || !res.data) {
+      return { result: 'no-conflict' };
+    }
+    const baseTime = new Date(editingFile.uploadTime).getTime();
+    const latestTime = new Date(res.data.uploadTime).getTime();
+    if (!isNaN(baseTime) && !isNaN(latestTime) && latestTime > baseTime) {
+      const confirmed = await uiConfirm.confirm('已经有其他用户更新了文件，是否覆盖？');
+      return {
+        result: confirmed ? 'overwrite' : 'cancel',
+        serverCrc32: res.data.crc32,
+        serverFileResourcePath: res.data.fileResourcePath,
+      };
+    }
+    return {
+      result: 'no-conflict',
+      serverCrc32: res.data.crc32,
+      serverFileResourcePath: res.data.fileResourcePath,
+    };
+  } catch (err) {
+    console.warn('检查文件更新冲突失败:', err);
+  }
+  return { result: 'no-conflict' };
+};
+
+/**
+ * 上传成功后获取服务端最新 uploadTime，用于更新 editingFile。
+ * 避免下次冲突检测把自己刚上传的误判为"他人更新"。
+ */
+const fetchLatestFileMeta = async (api: FileManagerApi, fileId: string): Promise<{ uploadTime: Date; updateTime: Date } | null> => {
+  try {
+    const res = await api.getDetail(fileId);
+    if (res.code === ResponseCode.SUCCESS && res.data) {
+      return { uploadTime: res.data.uploadTime, updateTime: res.data.updateTime };
+    }
+  } catch (err) {
+    console.warn('获取最新文件元数据失败:', err);
+  }
+  return null;
+};
+
+type ViewMode = 'table' | 'grid';
+type CreatingFileType = 'pptx' | 'md' | 'xlsx' | 'docx' | 'rdoc' | null;
+
+/** 新建文件类型对应的目标扩展名（含点号），用于新建对话框保留正确扩展名 */
+const CREATE_FILE_EXT_MAP: Record<Exclude<CreatingFileType, null>, string> = {
+  pptx: '.pptx',
+  md: '.md',
+  xlsx: '.xlsx',
+  docx: '.docx',
+  rdoc: '.rdoc',
+};
+
+/**
+ * 将合同附件路径转换为虚拟 ProjectFile（合同子文件夹 + 链接文件）。
+ * 每个合同创建一个以合同名称命名的虚拟子文件夹，链接文件放在子文件夹内。
+ * fileResourcePaths 是 JSON 字符串数组，每项为文件名；
+ * 完整资源路径为 /private/projects/{projectId}/contracts/{contractId}/seal/{fileName}
+ * 未签约合同没有盖章文件，展示其最新版本的合同文件作为链接文件。
+ */
+async function buildContractLinkFiles(
+  contracts: Array<{ id: string; projectId: string; name: string; tag?: string; status?: string; fileResourcePaths: string; updateTime: Date; createBy: string }>,
+  projectId: string,
+): Promise<ProjectFile[]> {
+  const result: ProjectFile[] = [];
+  for (const contract of contracts) {
+    const signed = contract.status === 'SIGNED';
+    const contractTag = contract.tag || '未分类';
+
+    // 使用合同 ID 作为文件夹 fileName 以保证路径唯一性，descs 存储合同名称用于显示
+    // 未签约合同没有盖章文件，但同样生成子文件夹以便在文件列表中展示（弱化显示）
+    const subfolderId = `contract-folder-${contract.id}`;
+    const subfolderPath = `/${CONTRACTS_FOLDER_NAME}/`;
+    result.push({
+      id: subfolderId,
+      isSecure: false,
+      projectId,
+      parentId: null,
+      fileName: contract.id,
+      filePath: subfolderPath,
+      fileType: 'folder',
+      fileSize: 0,
+      crc32: 0,
+      fileResourcePath: '',
+      uploaderName: '',
+      uploadTime: new Date(contract.updateTime),
+      createTime: new Date(contract.updateTime),
+      updateTime: new Date(contract.updateTime),
+      createBy: contract.createBy,
+      updateBy: contract.createBy,
+      isContractSubfolder: true,
+      contractSigned: signed,
+      contractTag,
+      descs: contract.name || '未命名合同',
+    });
+
+    let hasSealFiles = false;
+    if (!contract.fileResourcePaths) {
+      hasSealFiles = false;
+    } else {
+      let paths: string[] = [];
+      try {
+        paths = JSON.parse(contract.fileResourcePaths);
+      } catch {
+        hasSealFiles = false;
+      }
+      if (Array.isArray(paths) && paths.length > 0) {
+        hasSealFiles = true;
+        for (const fileName of paths) {
+          if (!fileName) continue;
+          result.push({
+            id: `contract-file-${contract.id}-${fileName}`,
+            isSecure: false,
+            projectId,
+            parentId: subfolderId,
+            fileName,
+            filePath: `${subfolderPath}${contract.id}/`,
+            fileType: getMimeType(fileName),
+            fileSize: 0,
+            crc32: 0,
+            fileResourcePath: `/private/projects/${projectId}/contracts/${contract.id}/seal/${fileName}`,
+            uploaderName: '合同',
+            uploadTime: new Date(contract.updateTime),
+            createTime: new Date(contract.updateTime),
+            updateTime: new Date(contract.updateTime),
+            createBy: contract.createBy,
+            updateBy: contract.createBy,
+            isContractLink: true,
+            contractSigned: signed,
+            contractTag,
+            descs: contract.name,
+          });
+        }
+      } else {
+        hasSealFiles = false;
+      }
+    }
+
+    // 未签约合同：展示最新版本的合同文件（弱化显示）
+    if (!signed && !hasSealFiles) {
+      try {
+        const versionRes = await API.project.contract.getVersionList({ contractId: contract.id });
+        if (versionRes.code === ResponseCode.SUCCESS && versionRes.data?.length) {
+          const latest = versionRes.data.reduce((a, b) => ((b.versionNumber ?? 0) > (a.versionNumber ?? 0) ? b : a));
+          if (latest.fileResourcePath && latest.fileName) {
+            result.push({
+              id: `contract-file-${contract.id}-v${latest.versionNumber}-${latest.fileName}`,
+              isSecure: false,
+              projectId,
+              parentId: subfolderId,
+              fileName: latest.fileName,
+              filePath: `${subfolderPath}${contract.id}/`,
+              fileType: getMimeType(latest.fileName),
+              fileSize: latest.fileSize || 0,
+              crc32: 0,
+              fileResourcePath: latest.fileResourcePath,
+              uploaderName: '合同',
+              uploadTime: new Date(latest.createTime || contract.updateTime),
+              createTime: new Date(latest.createTime || contract.updateTime),
+              updateTime: new Date(latest.createTime || contract.updateTime),
+              createBy: latest.createBy || contract.createBy,
+              updateBy: latest.createBy || contract.createBy,
+              isContractLink: true,
+              contractSigned: false,
+              contractTag,
+              descs: contract.name,
+            });
+          }
+        }
+      } catch (err) {
+        console.warn('[合同文件夹] 加载未签约合同版本失败:', contract.id, err);
+      }
+    }
+  }
+  return result;
+}
+
+/** 创建虚拟合同文件夹节点 */
+function createVirtualContractsFolder(projectId: string): ProjectFile {
+  return {
+    id: CONTRACTS_VIRTUAL_FOLDER_ID,
+    isSecure: false,
+    projectId,
+    parentId: null,
+    fileName: CONTRACTS_FOLDER_NAME,
+    filePath: '/',
+    fileType: 'folder',
+    fileSize: 0,
+    crc32: 0,
+    fileResourcePath: '',
+    uploaderName: '',
+    uploadTime: new Date(),
+    createTime: new Date(),
+    updateTime: new Date(),
+    createBy: '',
+    updateBy: '',
+    isVirtualContractFolder: true,
+  };
+}
+
+/**
+ * "按类型"排序时的合同布局：在合同文件夹一级生成以分类标签命名的虚拟文件夹，
+ * 将各合同子文件夹及其附件移动到对应标签文件夹下。
+ * 其他排序方式保持原有扁平结构（合同子文件夹直接位于合同文件夹下）。
+ */
+function layoutContractFilesByType(
+  files: ProjectFile[],
+  sortBy: FileSortBy,
+): ProjectFile[] {
+  if (sortBy !== 'fileType') return files;
+  if (!files.some((f) => f.isContractSubfolder || f.isContractLink)) return files;
+
+  const rootPath = `/${CONTRACTS_FOLDER_NAME}`;
+  const contractsPrefix = `${rootPath}/`;
+
+  // 合同 ID -> 分类标签（子文件夹的 fileName 即合同 ID）
+  const contractTagMap = new Map<string, string>();
+  files.forEach((f) => {
+    if (f.isContractSubfolder) {
+      contractTagMap.set(f.fileName, f.contractTag || '未分类');
+    }
+  });
+
+  const result: ProjectFile[] = [];
+  const tagFolders = new Map<string, ProjectFile>();
+  const ensureTagFolder = (tag: string, projectId: string, time: Date): string => {
+    const tagFolderId = `contract-tag-${tag}`;
+    let folder = tagFolders.get(tag);
+    if (!folder) {
+      folder = {
+        id: tagFolderId,
+        isSecure: false,
+        projectId,
+        parentId: null,
+        fileName: tag,
+        filePath: contractsPrefix,
+        fileType: 'folder',
+        fileSize: 0,
+        crc32: 0,
+        fileResourcePath: '',
+        uploaderName: '',
+        uploadTime: time,
+        createTime: time,
+        updateTime: time,
+        createBy: '',
+        updateBy: '',
+        isContractTagFolder: true,
+      };
+      tagFolders.set(tag, folder);
+      result.push(folder);
+    } else if (new Date(time).getTime() > new Date(folder.uploadTime).getTime()) {
+      folder.uploadTime = time;
+      folder.updateTime = time;
+    }
+    return tagFolderId;
+  };
+
+  for (const f of files) {
+    if (f.isContractSubfolder) {
+      const tag = f.contractTag || '未分类';
+      const tagFolderId = ensureTagFolder(tag, f.projectId, new Date(f.uploadTime));
+      result.push({ ...f, filePath: `${contractsPrefix}${tag}/`, parentId: tagFolderId });
+    } else if (f.filePath && f.filePath.startsWith(contractsPrefix)) {
+      // 合同子文件夹下的链接文件/真实文件：{prefix}{contractId}/... -> {prefix}{tag}/{contractId}/...
+      const rest = f.filePath.substring(contractsPrefix.length);
+      const contractId = rest.split('/')[0];
+      const tag = f.contractTag || contractTagMap.get(contractId);
+      if (tag) {
+        ensureTagFolder(tag, f.projectId, new Date(f.uploadTime));
+        result.push({ ...f, filePath: `${contractsPrefix}${tag}/${rest}` });
+      } else {
+        result.push(f);
+      }
+    } else {
+      result.push(f);
+    }
+  }
+  return result;
+}
+
+/** 将本地文件记录（IndexedDB localFiles store）映射为可在文件列表中显示的 ProjectFile */
+function localFileRecordToProjectFile(local: LocalFileRecord): ProjectFile {
+  const now = new Date(local.updatedAt);
+  return {
+    id: local.localId, // 本地文件使用 localId 作为列表 id；避免与服务器文件 id 重复
+    localId: local.localId,
+    isLocalOnly: local.isLocalOnly,
+    hasUnsyncedChanges: local.hasUnsyncedChanges,
+    isSecure: false,
+    projectId: local.projectId,
+    parentId: local.parentId,
+    fileName: local.fileName,
+    filePath: '/',
+    fileType: local.fileType,
+    fileSize: local.fileSize,
+    crc32: 0,
+    hasLocalCache: true,
+    fileResourcePath: '',
+    uploaderName: '我',
+    uploadTime: now,
+    createTime: new Date(local.createdAt),
+    updateTime: now,
+    createBy: local.userId,
+    updateBy: local.userId,
+  };
+}
+
+// 复制失败时（如部分移动端 webview）弹出可手动选中复制的输入框
+function showLinkCopyModal(link: string) {
+  const inputRef: { current: any } = { current: null };
+  Modal.info({
+    title: '请手动复制链接',
+    content: React.createElement(Input, {
+      value: link,
+      readOnly: true,
+      ref: (input: any) => { inputRef.current = input; },
+      onFocus: (e: any) => e.target.select(),
+    }),
+    okText: '关闭',
+    width: 480,
+    afterClose: () => {},
+    onOk: () => {},
+  });
+  // 延迟聚焦选中，确保弹窗已渲染
+  setTimeout(() => {
+    inputRef.current?.focus?.();
+    inputRef.current?.select?.();
+  }, 100);
+}
+
+interface FileManagerState {
+  files: ProjectFile[];
+  expandedRowKeys: string[];
+  selectedFolderId: string | null;
+  dragOverId: string | null;
+  /** 排序字段（与 useFileManagerState 中定义保持一致） */
+  sortBy: FileSortBy;
+  /** 当前用户是否具备项目管理权限（文件夹下载等入口） */
+  isManager: boolean;
+}
+
+interface FileManagerStateActions {
+  setFiles: (files: ProjectFile[]) => void;
+  setFileTreeData: (data: ProjectFile[]) => void;
+  setLoading: (loading: boolean) => void;
+  setExpandedRowKeys: (keys: string[]) => void;
+  setViewMode: (mode: ViewMode) => void;
+  setSelectedFolderId: (id: string | null) => void;
+  setUploadPercent: (percent: number | undefined) => void;
+  setUploadSuccess: (success: boolean | undefined) => void;
+  setDragUploadPercent: (percent: number | undefined) => void;
+  setDragUploadSuccess: (success: boolean | undefined) => void;
+  setDragUploadingFileName: (name: string) => void;
+  setIsExternalDragOver: (over: boolean) => void;
+  setNewFolderName: (name: string) => void;
+  setIsManager: (manager: boolean) => void;
+  setEditingFile: (file: ProjectFile | null) => void;
+  setEditorVisible: (visible: boolean) => void;
+  setPreviewFileName: (name: string | null) => void;
+  setPreviewUrl: (url: string | null) => void;
+  setPreviewVisible: (visible: boolean) => void;
+  setPreviewingFile: (file: ProjectFile | null) => void;
+  setPreviewCrc32: (crc32: number | undefined) => void;
+  setShareToWechatFile: (file: ProjectFile | null) => void;
+  setShareToWechatVisible: (visible: boolean) => void;
+  setRenameFileId: (id: string | null) => void;
+  setRenameFileName: (name: string) => void;
+  setRenameVisible: (visible: boolean) => void;
+  setDescsFileId: (id: string | null) => void;
+  setDescsValue: (value: string) => void;
+  setDescsVisible: (visible: boolean) => void;
+  setIsEncryptedFolder: (encrypted: boolean) => void;
+  setCreateFolderVisible: (visible: boolean) => void;
+  setNewFolderDescs: (descs: string) => void;
+  setCreatingFileName: (name: string) => void;
+  setCreatingFileType: (type: CreatingFileType) => void;
+  setCreatorVisible: (visible: boolean) => void;
+  setContextMenuVisible: (visible: boolean) => void;
+  setContextMenuRecord: (record: ProjectFile | null) => void;
+  setContextMenuPosition: (pos: { x: number; y: number }) => void;
+  setMoveCopyFiles: (files: ProjectFile[]) => void;
+  setMoveCopyMode: (mode: 'move' | 'copy') => void;
+  setMoveCopyModalVisible: (visible: boolean) => void;
+  setVersionHistoryFile: (file: ProjectFile | null) => void;
+  setVersionHistoryModalVisible: (visible: boolean) => void;
+  setDragSourceId: (id: string | null) => void;
+  setDragOverId: (id: string | null) => void;
+  setRootDragOver: (over: boolean) => void;
+  setIsOnline: (online: boolean) => void;
+  setPreviewLocalId: (localId: string | null) => void;
+  setPreviewIsLocalOnly: (isLocalOnly: boolean) => void;
+  setPreviewHasUnsyncedChanges: (has: boolean) => void;
+  setCreateFileVisible: (visible: boolean) => void;
+  setNewFileName: (name: string) => void;
+  setPendingFileType: (type: CreatingFileType) => void;
+}
+
+interface FileManagerActions {
+  loadFiles: () => Promise<void>;
+  uploadFiles: (fileList: any[]) => Promise<void>;
+  handlePreview: (file: ProjectFile) => void;
+  handleDownload: (file: ProjectFile) => void;
+  /** 发起文件夹异步打包下载（仅管理员/负责人可用） */
+  handleDownloadFolder: (file: ProjectFile) => void;
+  handleShareToWechat: (file: ProjectFile) => void;
+  handleCopyLink: (file: ProjectFile) => void;
+  handleJumpToContract: (file: ProjectFile) => void;
+  /** 在合同根文件夹右键菜单中点击"创建合同"：切换到合同页签并打开新建合同弹窗 */
+  handleCreateContract: (file: ProjectFile) => void;
+  handleGenerateTempLink: (file: ProjectFile) => void;
+  handleDelete: (fileId: string) => void;
+  isFolderExpanded: (folderId: string) => boolean;
+  handleMove: (fileId: string, targetFolderId: string | null) => void;
+  handleRename: (file: ProjectFile) => void;
+  handleEditDescs: (file: ProjectFile) => void;
+  handleDescsConfirm: (descsFileId: string | null, descsValue: string) => void;
+  handleRenameConfirm: (renameFileId: string | null, renameFileName: string) => void;
+  handleCreateFolder: () => void;
+  openCreator: (fileName: string, fileType: CreatingFileType) => void;
+  handleCreatePptx: () => void;
+  handleCreateMarkdown: () => void;
+  handleCreateRdoc: () => void;
+  handleCreateExcel: () => void;
+  handleCreateWord: () => void;
+  handleCreateFileConfirm: (fileName: string, fileType: CreatingFileType) => void;
+  handleCreateFolderConfirm: (newFolderName: string, newFolderDescs: string, isEncryptedFolder: boolean) => void;
+  handleEditFile: (file: ProjectFile) => void;
+  handleUploadBlob: (editingFile: ProjectFile | null, initialBlob: Blob | undefined, blob: Blob, fileName: string) => void;
+  handleUploadMarkdown: (editingFile: ProjectFile | null, oldContent: string, content: string, fileName: string) => void;
+  handleCreateUploadBlob: (initialBlob: Blob | undefined, blob: Blob, fileName: string) => void;
+  handleCreateUploadMarkdown: (oldContent: string, content: string, fileName: string) => void;
+  /** 编辑器点击"保存本地缓存"时调用：同步更新 localFiles store 内容，使 hasUnsyncedChanges 标记生效 */
+  handleSaveLocalBlob: (localId: string | null | undefined, blob: Blob, fileName: string, markUnsynced?: boolean) => Promise<void>;
+  /** Markdown 编辑器点击"保存本地缓存"时调用 */
+  handleSaveLocalMarkdown: (localId: string | null | undefined, content: string, fileName: string, markUnsynced?: boolean) => Promise<void>;
+  handleExpand: (expanded: boolean, record: ProjectFile) => void;
+  toggleFolderExpand: (record: ProjectFile, tableView: boolean) => void;
+  handleDragStart: (fileId: string) => void;
+  handleDragEnd: () => void;
+  handleDragOver: (fileId: string) => void;
+  handleDragLeave: (fileId: string) => void;
+  handleDrop: (sourceId: string, targetId: string) => void;
+  handleExternalDragEnter: (e: React.DragEvent) => void;
+  handleExternalDragOver: (e: React.DragEvent) => void;
+  handleExternalDragLeave: (e: React.DragEvent) => void;
+  handleExternalDrop: (e: React.DragEvent) => void;
+  handleContextMenu: (event: React.MouseEvent, record: ProjectFile) => void;
+  handleMoveToProject: (file: ProjectFile) => void;
+  handleCopyToProject: (file: ProjectFile) => void;
+  handleCopyToSelf: (file: ProjectFile) => void;
+  handleMoveCopySuccess: () => void;
+  handleViewVersionHistory: (file: ProjectFile) => void;
+  handleClearCache: (file: ProjectFile) => void;
+  handleCacheSaved: (fileId: string) => void;
+  handleOpenInNewWindow: (file: ProjectFile) => void;
+  handleRootDragOver: (e: React.DragEvent) => void;
+  handleRootDragLeave: () => void;
+  handleRootDrop: (e: React.DragEvent) => void;
+  initUserRole: () => void;
+  initViewMode: () => void;
+}
+
+export const useFileManagerActions = (
+  projectId: string,
+  currentUserRole: ProjectRole | null,
+  state: FileManagerState,
+  actions: FileManagerStateActions,
+  options?: {
+    /** 数据接口适配器，缺省为项目文件 API */
+    api?: FileManagerApi;
+    /** 功能开关，缺省全部开启 */
+    features?: FileManagerFeatures;
+  }
+): FileManagerActions => {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const externalDragCounter = useRef(0);
+  const actionsRef = useRef(actions);
+  const stateRef = useRef(state);
+  const handleCacheSavedRef = useRef<(fileId: string) => void>(() => {});
+  /** 文件夹打包下载轮询定时器（jobId → timer） */
+  const folderDownloadTimersRef = useRef<Map<string, ReturnType<typeof setInterval>>>(new Map());
+  /** 最近一次 loadFiles 的原始扁平列表（未应用合同标签分组布局），排序切换时基于它重新布局 */
+  const rawFilesRef = useRef<ProjectFile[]>([]);
+  actionsRef.current = actions;
+  stateRef.current = state;
+
+  // 数据接口与功能开关（缺省项目实现、全部功能开启）
+  const api = options?.api || projectFileManagerApi;
+  const features = options?.features || {};
+  const enableContracts = features.contracts !== false;
+  const apiRef = useRef(api);
+  apiRef.current = api;
+
+  // 排序方式变化时重新应用合同标签分组布局（"按类型"排序时合同收进分类标签文件夹），无需重新请求服务器
+  useEffect(() => {
+    if (rawFilesRef.current.length === 0) return;
+    const finalFiles = sortFiles(layoutContractFilesByType(rawFilesRef.current, stateRef.current.sortBy));
+    actionsRef.current.setFileTreeData(buildFileTree(finalFiles));
+    actionsRef.current.setFiles(finalFiles);
+  }, [state.sortBy]);
+
+  // 组件卸载时清理所有文件夹打包下载轮询
+  useEffect(() => {
+    const timers = folderDownloadTimersRef.current;
+    return () => {
+      timers.forEach((timer) => clearInterval(timer));
+      timers.clear();
+    };
+  }, []);
+
+  // 网络状态监听：在线/离线事件同步到 React state
+  useEffect(() => {
+    const handleOnline = () => actionsRef.current.setIsOnline(true);
+    const handleOffline = () => actionsRef.current.setIsOnline(false);
+    window.addEventListener('online', handleOnline);
+    window.addEventListener('offline', handleOffline);
+    actionsRef.current.setIsOnline(typeof navigator !== 'undefined' ? navigator.onLine : true);
+    return () => {
+      window.removeEventListener('online', handleOnline);
+      window.removeEventListener('offline', handleOffline);
+    };
+  }, []);
+
+  const loadFiles = useCallback(async () => {
+    actionsRef.current.setLoading(true);
+    try {
+      // 1. 先加载本地文件记录（IndexedDB localFiles store）
+      //    离线时用于重建服务器文件列表；在线时用于标记未同步修改
+      const userInfo = await CacheUserInfo.getUserInfo({ forceRefresh: false });
+      const userId = userInfo?.id || 'local-user';
+      let localRecords: LocalFileRecord[] = [];
+      try {
+        localRecords = await listLocalFilesByProject(userId, projectId);
+      } catch (err) {
+        console.warn('加载本地文件列表失败:', err);
+      }
+
+      // 2. 加载服务器文件（在线请求 API；离线时用本地持久化的元数据缓存重建列表）
+      let serverFiles: ProjectFile[] = [];
+      const isOnlineFlag = typeof navigator !== 'undefined' ? navigator.onLine : true;
+      if (isOnlineFlag) {
+        const response = await api.listFiles(projectId);
+        if (response.code === ResponseCode.SUCCESS && response.data) {
+          serverFiles = response.data as ProjectFile[];
+        }
+        // 在线时把服务器返回的所有元数据都持久化到 CacheFileMeta，供离线时使用
+        CacheFileMeta.saveFileMetaBatch(projectId, serverFiles).catch(err =>
+          console.warn('持久化文件元数据缓存失败:', err)
+        );
+      } else {
+        // 离线：多种来源合并重建服务器文件列表
+        //   a) CacheFileMeta 中按项目保存的完整元数据（每次 listFiles 在线时写入）
+        //   b) localFiles 中服务器文件记录带的 originalServerFile 快照
+        //   c) CacheFileContent 中有 Blob 缓存但 a/b 都没覆盖到的 fileId，用 CacheFileMeta.getFileMeta 单条查
+        const metaFromBatch: ProjectFile[] = await CacheFileMeta.listFileMetaByProject(projectId);
+        const metaFromLocalFiles: ProjectFile[] = localRecords
+          .filter(l => !l.isLocalOnly && l.serverFileId && l.originalServerFile)
+          .map(l => l.originalServerFile as ProjectFile);
+
+        // c) 补齐 CacheFileContent 中存在但 a/b 没有的元数据
+        const existingIds = new Set([
+          ...metaFromBatch.map(f => f.id),
+          ...metaFromLocalFiles.map(f => f.id),
+        ]);
+        const contentIds: string[] = (await CacheFileContent.getCacheList())
+          .map(r => r.fileId)
+          .filter(id => !existingIds.has(id));
+        const extraFromMeta: ProjectFile[] = [];
+        for (const cid of contentIds) {
+          const m = await CacheFileMeta.getFileMeta(cid);
+          if (m && m.projectId === projectId) extraFromMeta.push(m);
+        }
+
+        // 合并去重：以 metaFromBatch 优先，metaFromLocalFiles 次之，extra 再补
+        const merged: Map<string, ProjectFile> = new Map();
+        for (const f of metaFromBatch) merged.set(f.id, f);
+        for (const f of metaFromLocalFiles) if (!merged.has(f.id)) merged.set(f.id, f);
+        for (const f of extraFromMeta) if (!merged.has(f.id)) merged.set(f.id, f);
+        serverFiles = Array.from(merged.values());
+      }
+
+      const localOnlyProjectFiles: ProjectFile[] = localRecords
+        .filter(l => l.isLocalOnly)
+        .map(localFileRecordToProjectFile);
+
+      // 3. 标记服务器文件：hasUnsyncedChanges / localId，并预计算 hasLocalCache
+      const unsyncedServerIds = new Set(
+        localRecords.filter(l => !l.isLocalOnly && l.serverFileId && l.hasUnsyncedChanges).map(l => l.serverFileId!)
+      );
+      const serverIdToLocalRecord: Record<string, LocalFileRecord> = {};
+      for (const l of localRecords) {
+        if (l.serverFileId) serverIdToLocalRecord[l.serverFileId] = l;
+      }
+      const mergedServerFiles = await Promise.all(
+        serverFiles.map(async (sf) => {
+          const localMatch = serverIdToLocalRecord[sf.id];
+          const cacheHit = sf.fileType !== 'folder'
+            ? (!!localMatch || await CacheFileContent.hasCache(sf.id))
+            : false;
+          return {
+            ...sf,
+            hasUnsyncedChanges: unsyncedServerIds.has(sf.id),
+            localId: localMatch?.localId,
+            hasLocalCache: cacheHit,
+          } as ProjectFile;
+        })
+      );
+
+      // 4. 非私有项目：构建虚拟"合同"文件夹（始终显示，不依赖合同 API 结果）
+      const isPrivateProject = projectId === userId;
+      let contractLinkFiles: ProjectFile[] = [];
+      let contractsFolderId: string | null = null;
+
+      // 4. 合同文件夹：仅查看（viewer）成员不展示合同文件夹（后端合同列表接口对 VIEWER 同样返回空列表）
+      if (enableContracts && !isPrivateProject && currentUserRole !== 'viewer') {
+        // 查找根目录下是否已存在真实的 __contracts__ 文件夹
+        const realContractsFolder = mergedServerFiles.find(
+          f => f.fileType === 'folder' && f.fileName === CONTRACTS_FOLDER_NAME && f.filePath === '/',
+        );
+        if (realContractsFolder) {
+          realContractsFolder.isVirtualContractFolder = true;
+          contractsFolderId = realContractsFolder.id;
+        } else {
+          // 创建虚拟文件夹
+          const virtualFolder = createVirtualContractsFolder(projectId);
+          mergedServerFiles.push(virtualFolder);
+          contractsFolderId = virtualFolder.id;
+        }
+
+        // 加载合同附件（仅在在线时请求）
+        if (isOnlineFlag && contractsFolderId) {
+          try {
+            const contractRes = await API.project.contract.getContractList({
+              projectId,
+              pageNum: 1,
+              pageSize: 10000,
+            });
+            if (contractRes.code === ResponseCode.SUCCESS && contractRes.data?.list?.length) {
+              contractLinkFiles = await buildContractLinkFiles(
+                contractRes.data.list, projectId,
+              );
+            }
+          } catch (err) {
+            console.warn('[合同文件夹] 加载合同列表失败:', err);
+          }
+        }
+      }
+
+      // 5. 合并并排序（"按类型"排序时合同按分类标签分组到虚拟文件夹）
+      //    笔记模块的根目录（$$__notes$$__）及其内容不展示在文件管理中
+      const allFiles = filterNotesRootFiles([...mergedServerFiles, ...localOnlyProjectFiles, ...contractLinkFiles]);
+      rawFilesRef.current = allFiles;
+      const sortedFiles = sortFiles(layoutContractFilesByType(allFiles, stateRef.current.sortBy));
+      actionsRef.current.setFileTreeData(buildFileTree(sortedFiles));
+      actionsRef.current.setFiles(sortedFiles);
+    } catch (error) {
+      console.error('加载文件列表失败:', error);
+      message.error('加载文件列表失败');
+    } finally {
+      actionsRef.current.setLoading(false);
+    }
+  }, [projectId, currentUserRole, api, enableContracts]);
+
+  const uploadFiles = useCallback(async (fileList: any[]) => {
+    try {
+      const { files, selectedFolderId } = stateRef.current;
+      const selectedFolder = files.find((f) => f.id === selectedFolderId);
+      const file = fileList[0];
+
+      const { crc32, serverFileName } = await uploadFileBlob(file as Blob, (file as any).name,
+        () => {},
+      );
+
+      const response = await api.addFile(projectId, {
+        fileName: (file as any).name,
+        filePath: selectedFolder ? `${selectedFolder.filePath}${selectedFolder.fileName}/` : `/`,
+        fileType: (file as any).type,
+        fileSize: (file as any).size,
+        crc32,
+        fileResourcePath: serverFileName
+      });
+      if (response.code === ResponseCode.SUCCESS) {
+        await CacheFileContent.saveToCache(response.data!.fileId, file as Blob, crc32, file.size);
+        loadFiles();
+      }
+    } catch (error) {
+      message.error('文件上传失败');
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handlePreview = useCallback((file: ProjectFile) => {
+    if (file.fileType === 'folder') {
+      return;
+    }
+
+    // ---- 本地文件：点击后直接进入编辑模式（可继续上次未完成的编辑）----
+    // 离线时，有本地缓存（localId）的服务器文件也走本地加载，确保可查看编辑
+    const isOnlineFlag = typeof navigator !== 'undefined' ? navigator.onLine : true;
+    if (file.isLocalOnly || file.hasUnsyncedChanges || (!isOnlineFlag && file.localId)) {
+      actionsRef.current.setEditingFile(file);
+      actionsRef.current.setEditorVisible(true);
+      actionsRef.current.setPreviewLocalId(file.localId || null);
+      actionsRef.current.setPreviewIsLocalOnly(!!file.isLocalOnly);
+      actionsRef.current.setPreviewHasUnsyncedChanges(!!file.hasUnsyncedChanges);
+      actionsRef.current.setPreviewFileName(file.fileName);
+      return;
+    }
+
+    // ---- 服务器文件的普通预览流程 ----
+    actionsRef.current.setPreviewFileName(file.fileName);
+    actionsRef.current.setPreviewUrl(file.fileResourcePath);
+    // 合同链接文件为虚拟文件（无 fileId/缓存语义），crc32 必须置空，
+    // 否则预览组件会因"有 crc32 但无 fileId"守卫永久跳过加载
+    actionsRef.current.setPreviewCrc32(file.isContractLink ? undefined : file.crc32);
+    // 预览时不使用编辑器模式 → 清空本地相关标识
+    actionsRef.current.setPreviewLocalId(null);
+    actionsRef.current.setPreviewIsLocalOnly(false);
+    actionsRef.current.setPreviewHasUnsyncedChanges(false);
+
+    // 仅当 crc32 实际变化时才更新 files/fileTreeData，避免不必要的新数组引用
+    // 触发 index.tsx 的 useEffect（该 effect 依赖 state.files），在 setSearchParams
+    // 尚未同步到 currentFileId 时可能用旧 fileid 覆盖刚设置的预览状态，导致首次
+    // 打开合同链接文件时出现竞态访问错误。
+    const state = stateRef.current;
+    const existingFile = state.files.find(f => f.id === file.id);
+    if (existingFile && existingFile.crc32 !== file.crc32) {
+      const filesWithCrc32 = state.files.map(f =>
+        f.id === file.id ? { ...f, crc32: file.crc32 } : f
+      );
+      actionsRef.current.setFiles(filesWithCrc32);
+      actionsRef.current.setFileTreeData(buildFileTree(filesWithCrc32));
+    }
+    actionsRef.current.setPreviewVisible(true);
+    // 同步设置 previewingFile：作为 previewFile 计算的权威来源，
+    // 避免依赖 setSearchParams 异步更新的 currentFileId（首次渲染时
+    // currentFileId 可能仍为旧值，导致 previewFile 找到错误的文件 → fileId 错误 → 请求被 abort）。
+    actionsRef.current.setPreviewingFile(file);
+    setSearchParams(prev => {
+      const newParams = new URLSearchParams(prev);
+      newParams.set('fileid', file.id);
+      return newParams;
+    }, { replace: true });
+  }, [setSearchParams]);
+
+  const handleDownload = useCallback(async (file: ProjectFile) => {
+    // 有 localId 时（本地新建文件 或 服务器文件的未同步修改），优先下载本地编辑的最新版本
+    if (file.localId) {
+      try {
+        const localFile = await getLocalFile(file.localId);
+        if (localFile && localFile.content) {
+          const content = localFile.content;
+          let blob: Blob;
+          if (typeof content === 'string') {
+            blob = new Blob([content], { type: 'text/markdown' });
+          } else {
+            blob = new Blob([content], { type: getMimeType(file.fileName) });
+          }
+          const url = URL.createObjectURL(blob);
+          const a = document.createElement('a');
+          a.href = url;
+          a.download = file.fileName;
+          document.body.appendChild(a);
+          a.click();
+          document.body.removeChild(a);
+          URL.revokeObjectURL(url);
+          uiToast.success('文件已下载，请查看浏览器的下载文件夹');
+          return;
+        }
+      } catch (err) {
+        console.warn('下载本地文件失败，回退到服务器下载:', err);
+      }
+    }
+
+    // 本地新建文件（从未上传）无服务器资源，不尝试服务器下载
+    if (file.isLocalOnly) {
+      uiToast.error('本地文件内容不可用');
+      return;
+    }
+
+    uiFilePreview.downloadFile(file.fileResourcePath, file.fileName, file.id, file.crc32)
+      .then(() => {
+        handleCacheSavedRef.current(file.id);
+      })
+      .catch(() => {
+        // downloadFile 内部已统一提示下载失败，此处仅避免未捕获的 Promise 拒绝
+      });
+  }, []);
+
+  /**
+   * 发起文件夹打包下载：后端异步打包，前端轮询任务状态；
+   * 打包完成后自动触发下载，若用户已离开页面则由通知中心兜底。
+   */
+  const handleDownloadFolder = useCallback(async (file: ProjectFile) => {
+    if (file.fileType !== 'folder') return;
+
+    const downloadFolderApi = api.downloadFolder;
+    const statusApi = api.getFolderDownloadStatus;
+    if (!downloadFolderApi || !statusApi) {
+      uiToast.error('当前场景不支持文件夹下载');
+      return;
+    }
+    if (!stateRef.current.isManager) {
+      uiToast.error('无权下载此文件夹');
+      return;
+    }
+
+    actionsRef.current.setContextMenuVisible(false);
+    actionsRef.current.setContextMenuRecord(null);
+
+    try {
+      const res = await downloadFolderApi(projectId, file.filePath || '/', file.fileName);
+      if (res.code !== ResponseCode.SUCCESS || !res.data || !res.data.jobId) {
+        uiToast.error(res.message || '发起文件夹打包失败');
+        return;
+      }
+      const jobId = res.data.jobId;
+      const zipFileName = `${file.fileName.replace(/[\\/:*?"<>|]/g, '_')}.zip`;
+
+      uiToast.info(`正在打包文件夹「${file.fileName}」，完成后将自动下载，也可在通知中心查看`);
+
+      let attempts = 0;
+      const timer = setInterval(async () => {
+        attempts += 1;
+        // 最多轮询约 10 分钟
+        if (attempts > 300) {
+          clearInterval(timer);
+          folderDownloadTimersRef.current.delete(jobId);
+          uiToast.info('打包仍在进行，完成后可在通知中心查看下载地址');
+          return;
+        }
+
+        try {
+          const statusRes = await statusApi(jobId);
+          if (statusRes.code !== ResponseCode.SUCCESS) {
+            clearInterval(timer);
+            folderDownloadTimersRef.current.delete(jobId);
+            uiToast.error(statusRes.message || '打包任务不存在或已过期');
+            return;
+          }
+          if (!statusRes.data) return;
+
+          const job = statusRes.data;
+          if (job.status === 'pending') return;
+
+          clearInterval(timer);
+          folderDownloadTimersRef.current.delete(jobId);
+
+          if (job.status === 'success' && job.url) {
+            uiToast.success('文件夹打包完成，即将开始下载');
+            uiFilePreview
+              .downloadFile(job.url, job.fileName || zipFileName)
+              .catch(() => {
+                // downloadFile 内部已提示下载失败
+              });
+          } else {
+            uiToast.error(job.message || '文件夹打包失败');
+          }
+        } catch (err) {
+          // 单次轮询失败不中断，等待下一次
+          console.warn('查询文件夹打包状态失败:', err);
+        }
+      }, 2000);
+
+      folderDownloadTimersRef.current.set(jobId, timer);
+    } catch (err) {
+      console.error('发起文件夹打包失败:', err);
+      uiToast.error('发起文件夹打包失败');
+    }
+  }, [projectId, api]);
+
+  const handleShareToWechat = useCallback((file: ProjectFile) => {
+    actionsRef.current.setShareToWechatFile(file);
+    actionsRef.current.setShareToWechatVisible(true);
+  }, []);
+
+  const handleCopyLink = useCallback(async (file: ProjectFile) => {
+    const fileLink = `${window.location.origin}/filepreview?fileid=${file.id}&path=${encodeURIComponent(file.fileResourcePath)}&name=${encodeURIComponent(file.fileName)}`;
+    try {
+      await copyToClipboard(fileLink);
+      message.success('链接已复制到剪贴板');
+    } catch (err) {
+      // 移动端部分 webview 下 Clipboard API 与 execCommand 均可能失效，
+      // 弹出可手动选中复制的输入框作为最终兜底
+      showLinkCopyModal(fileLink);
+    }
+  }, []);
+
+  const handleJumpToContract = useCallback((file: ProjectFile) => {
+    // 合同链接文件 ID 格式: contract-file-{contractId}-{fileName}
+    // 合同子文件夹 ID 格式: contract-folder-{contractId}
+    // contractId 为 24 位 MongoDB ObjectId
+    let contractId: string | undefined;
+    if (file.isContractSubfolder) {
+      const match = file.id.match(/^contract-folder-([0-9a-f]{24})$/);
+      contractId = match?.[1];
+    } else {
+      const match = file.id.match(/^contract-file-([0-9a-f]{24})-/);
+      contractId = match?.[1];
+    }
+    if (!contractId) {
+      message.warning('无法获取合同信息');
+      return;
+    }
+    setSearchParams(prev => {
+      const newParams = new URLSearchParams(prev);
+      newParams.set('tab', 'contracts');
+      newParams.set('contractId', contractId!);
+      return newParams;
+    }, { replace: true });
+  }, [setSearchParams]);
+
+  const handleCreateContract = useCallback((_file: ProjectFile) => {
+    // 切换到合同页签，并通过 URL 参数通知 ContractManager 自动打开新建合同弹窗
+    setSearchParams(prev => {
+      const newParams = new URLSearchParams(prev);
+      newParams.set('tab', 'contracts');
+      newParams.set('createContract', '1');
+      newParams.delete('contractId');
+      return newParams;
+    }, { replace: true });
+  }, [setSearchParams]);
+
+  const handleGenerateTempLink = useCallback(async (file: ProjectFile) => {
+    try {
+      const expireInfo = await new Promise<{ seconds: number; label: string }>((resolve) => {
+        const stateRef = { current: 30 };
+        const presetOptions = [
+          { days: 7, label: '7天' },
+          { days: 30, label: '30天' },
+          { days: 90, label: '90天' },
+          { days: 365, label: '1年' },
+        ];
+
+        const ExpireModalContent = () => {
+          const [selectedValue, setSelectedValue] = useState<string>('30');
+
+          useEffect(() => {
+            stateRef.current = parseInt(selectedValue);
+          }, [selectedValue]);
+
+          return React.createElement('div', { className: 'flex flex-col gap-4' }, [
+            React.createElement('div', null, '选择有效期'),
+            React.createElement('div', { className: 'flex gap-2' }, 
+              presetOptions.map((option) =>
+                React.createElement(
+                  'label',
+                  {
+                    key: option.days,
+                    className: `flex items-center gap-1 px-3 py-2 rounded cursor-pointer border cursor-pointer ${
+                      selectedValue === String(option.days)
+                        ? 'border-blue-500 bg-blue-50'
+                        : 'border-gray-300 hover:border-gray-400'
+                    }`,
+                    onClick: () => setSelectedValue(String(option.days)),
+                  },
+                  [
+                    React.createElement('input', {
+                      type: 'radio',
+                      name: 'expireTime',
+                      value: option.days,
+                      checked: selectedValue === String(option.days),
+                      onChange: () => setSelectedValue(String(option.days)),
+                      className: 'hidden',
+                    }),
+                    React.createElement('span', null, option.label),
+                  ]
+                )
+              )
+            )
+          ]);
+        };
+
+        const modal = Modal.confirm({
+          className: 'ant-modal-nofull',
+          title: '选择临时链接有效期',
+          content: React.createElement(ExpireModalContent),
+          onOk: () => {
+            const days = stateRef.current;
+            resolve({
+              seconds: days * 24 * 60 * 60,
+              label: presetOptions.find(o => o.days === days)?.label || `${days}天`,
+            });
+          },
+          onCancel: () => {
+            resolve({ seconds: 0, label: '' });
+          },
+          okText: '生成链接',
+          cancelText: '取消',
+          width: 400,
+        });
+
+        return () => modal.destroy();
+      });
+
+      if (!expireInfo.seconds) return;
+
+      if (!api.generateTempAccessToken) return;
+
+      const r = await api.generateTempAccessToken(file.id, expireInfo.seconds);
+
+      if (r.code === ResponseCode.SUCCESS && r.data) {
+        const tempLink = r.data;
+        let shareLink = `${window.location.origin}/filepreview?fileid=${file.id}&path=${encodeURIComponent(file.fileResourcePath)}&name=${encodeURIComponent(file.fileName || '')}&token=${encodeURIComponent(tempLink)}`;
+        if (file.fileType === 'folder') {
+          const folderParams = new URLSearchParams({
+            token: tempLink,
+            folderId: file.id,
+            name: file.fileName || '',
+            path: `${file.filePath}${file.fileName}/`,
+          });
+          shareLink = `${window.location.origin}/fileshare?${folderParams.toString()}`;
+        }
+
+        await copyToClipboard(shareLink);
+        message.success(`临时链接已复制到剪贴板（有效期 ${expireInfo.label}）`);
+      } else {
+        message.error(r.message || '生成临时链接失败');
+      }
+    } catch (err) {
+      console.error('生成临时链接失败:', err);
+      message.error('生成临时链接失败');
+    }
+  }, [api]);
+
+  const handleDelete = useCallback(async (fileId: string) => {
+    try {
+      const { files } = stateRef.current;
+      const file = files.find((f) => f.id === fileId);
+
+      // 合同附件链接文件、虚拟合同文件夹和合同子文件夹不允许删除
+      if (
+        file?.isContractLink ||
+        file?.isVirtualContractFolder ||
+        file?.isContractSubfolder ||
+        file?.isContractTagFolder
+      ) {
+        message.warning('合同附件不支持删除');
+        return;
+      }
+
+      const confirm = await uiConfirm.confirm('确认删除文件吗？');
+      if (!confirm) return;
+
+      // 本地新建文件（isLocalOnly）：无需请求服务器，直接从 IndexedDB localFiles store 删除
+      if (file?.isLocalOnly) {
+        if (file.localId) {
+          await deleteLocalFile(file.localId);
+        }
+        // 从文件列表中移除
+        const refreshed = files.filter((f) => f.id !== fileId);
+        actionsRef.current.setFiles(refreshed);
+        actionsRef.current.setFileTreeData(buildFileTree(refreshed));
+        message.success('文件删除成功');
+        return;
+      }
+
+      // 服务器文件：请求服务器删除
+      const r = await api.removeFile(fileId);
+      if (r.code === ResponseCode.SUCCESS) {
+        // 如果该服务器文件有未同步的本地修改，也一并清理
+        if (file?.localId) {
+          try { await deleteLocalFile(file.localId); } catch { /* ignore */ }
+        }
+        message.success('文件删除成功');
+        loadFiles();
+      }
+    } catch (error) {
+      message.error('文件删除失败');
+    }
+  }, [api, loadFiles]);
+
+  const isFolderExpanded = useCallback((folderId: string) => {
+    return stateRef.current.expandedRowKeys.includes(folderId);
+  }, []);
+
+  const handleMove = useCallback(async (fileId: string, targetFolderId: string | null) => {
+    const { files } = stateRef.current;
+    const source = files.find((f) => f.id === fileId);
+    if (!source) return;
+
+    // 合同附件链接文件、虚拟合同文件夹和合同子文件夹不允许移动
+    if (
+      source.isContractLink ||
+      source.isVirtualContractFolder ||
+      source.isContractSubfolder ||
+      source.isContractTagFolder
+    ) {
+      message.warning('合同附件不支持移动');
+      return;
+    }
+
+    if (targetFolderId) {
+      if (source.id === targetFolderId) return;
+      const descendantIds = getDescendantIds(source, files);
+      if (descendantIds.includes(targetFolderId)) {
+        message.warning('无法将文件夹移动到其子项中');
+        return;
+      }
+    } else {
+      if (source.filePath === '/') {
+        return;
+      }
+    }
+
+    try {
+      const oldFile = files.find((f) => f.id === fileId);
+      const newFile = files.find((f) => f.id === targetFolderId);
+
+      let newFilePath = '/';
+      if (newFile) {
+        newFilePath = newFile.filePath + newFile.fileName + '/';
+      }
+
+      const result = await api.moveFile(projectId, {
+        oldFileName: oldFile?.fileName || '',
+        oldFilePath: oldFile?.filePath || '',
+        newFileName: oldFile?.fileName || '',
+        newFilePath: newFilePath
+      });
+
+      if (result.code === ResponseCode.SUCCESS) {
+        message.success('移动成功');
+        loadFiles();
+      }
+    } catch (error) {
+      message.error('移动失败');
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleRename = useCallback((file: ProjectFile) => {
+    actionsRef.current.setRenameFileId(file.id);
+    actionsRef.current.setRenameFileName(file.fileName);
+    actionsRef.current.setRenameVisible(true);
+  }, []);
+
+  const handleEditDescs = useCallback((file: ProjectFile) => {
+    actionsRef.current.setDescsFileId(file.id);
+    actionsRef.current.setDescsValue(file.descs || '');
+    actionsRef.current.setDescsVisible(true);
+    actionsRef.current.setContextMenuVisible(false);
+    actionsRef.current.setContextMenuRecord(null);
+  }, []);
+
+  const handleDescsConfirm = useCallback(async (descsFileId: string | null, descsValue: string) => {
+    if (!descsFileId) return;
+
+    try {
+      const result = await api.updateFileDescs({
+        fileId: descsFileId,
+        descs: descsValue.trim().slice(0, FILE_DESCS_MAX_LENGTH),
+      });
+
+      if (result.code === ResponseCode.SUCCESS) {
+        message.success('备注已保存');
+        actionsRef.current.setDescsVisible(false);
+        actionsRef.current.setDescsFileId(null);
+        actionsRef.current.setDescsValue('');
+        loadFiles();
+      } else {
+        message.error(result.message || '备注保存失败');
+      }
+    } catch (error) {
+      message.error('备注保存失败');
+    }
+  }, [api, loadFiles]);
+
+  const handleRenameConfirm = useCallback(async (renameFileId: string | null, renameFileName: string) => {
+    const { files } = stateRef.current;
+    const source = files.find((f) => f.id === renameFileId);
+    if (!source) return;
+
+    // 合同附件链接文件、虚拟合同文件夹和合同子文件夹不允许重命名
+    if (
+      source.isContractLink ||
+      source.isVirtualContractFolder ||
+      source.isContractSubfolder ||
+      source.isContractTagFolder
+    ) {
+      message.warning('合同附件不支持重命名');
+      actionsRef.current.setRenameVisible(false);
+      return;
+    }
+
+    let rename = sanitizeFileName(renameFileName);
+
+    // 不允许修改扩展名：文件夹不处理；文件保留原扩展名，丢弃用户输入的扩展名
+    if (source.fileType !== 'folder') {
+      const originalExt = getFileExtension(source.fileName);
+      const userInputExt = getFileExtension(rename);
+      // 用户尝试修改扩展名时提示（大小写差异不视为修改）
+      if (userInputExt.toLowerCase() !== originalExt.toLowerCase()) {
+        message.warning(originalExt
+          ? `扩展名不允许修改，已保留原扩展名 ${originalExt}`
+          : '扩展名不允许修改，已去除输入的扩展名');
+      }
+      rename = stripFileExtension(rename) + originalExt;
+    }
+
+    if (rename !== renameFileName) {
+      actionsRef.current.setRenameFileName(rename);
+    }
+
+    if (source.fileName === rename) return;
+
+    try {
+      const result = await api.moveFile(projectId, {
+        oldFileName: source.fileName,
+        oldFilePath: source.filePath,
+        newFileName: rename,
+        newFilePath: source.filePath,
+      });
+
+      if (result.code === ResponseCode.SUCCESS) {
+        message.success('重命名成功');
+        actionsRef.current.setRenameVisible(false);
+        loadFiles();
+      }
+    } catch (error) {
+      message.error('重命名失败');
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleCreateFolder = useCallback(() => {
+    actionsRef.current.setIsEncryptedFolder(false);
+    actionsRef.current.setCreateFolderVisible(true);
+    actionsRef.current.setNewFolderName('');
+    actionsRef.current.setNewFolderDescs('');
+  }, []);
+
+  /** 通用：在 IndexedDB 中创建本地空白的"新建文件"记录（未上传），然后直接在编辑器中打开 */
+  const createLocalOnlyAndOpen = useCallback(async (fileName: string, fileType: 'pptx' | 'xlsx' | 'md' | 'markdown' | 'docx' | 'rdoc') => {
+    try {
+      const userInfo = await CacheUserInfo.getUserInfo({ forceRefresh: false });
+      const userId = userInfo?.id || 'local-user';
+      const { selectedFolderId } = stateRef.current;
+      // 创建本地记录：传空 content（编辑器会生成空白文档）
+      const createdRecord = await createLocalOnlyFile({
+        userId,
+        projectId,
+        parentId: selectedFolderId,
+        fileName,
+        fileType,
+        content: '',
+      });
+      const newPf = localFileRecordToProjectFile(createdRecord);
+
+      // 立即追加到当前文件列表（无需等待 reload）
+      const currentFiles = stateRef.current.files;
+      const newFiles = sortFiles([...currentFiles, newPf]);
+      actionsRef.current.setFiles(newFiles);
+      actionsRef.current.setFileTreeData(buildFileTree(newFiles));
+
+      // 打开编辑器（编辑本地文件）
+      actionsRef.current.setEditingFile(newPf);
+      actionsRef.current.setEditorVisible(true);
+      actionsRef.current.setPreviewLocalId(createdRecord.localId);
+      actionsRef.current.setPreviewIsLocalOnly(true);
+      actionsRef.current.setPreviewHasUnsyncedChanges(createdRecord.hasUnsyncedChanges);
+      actionsRef.current.setPreviewFileName(fileName);
+    } catch (err) {
+      console.error('创建本地文件失败:', err);
+      message.error('创建本地文件失败');
+    }
+  }, [projectId]);
+
+  const openCreator = useCallback((fileName: string, fileType: CreatingFileType) => {
+    // 旧逻辑保留兼容（部分特殊入口仍可能使用）
+    actionsRef.current.setCreatingFileName(fileName);
+    actionsRef.current.setCreatingFileType(fileType);
+    actionsRef.current.setCreatorVisible(true);
+  }, []);
+
+  /** 打开新建文件名输入对话框，预填默认文件名 */
+  const openCreateFileDialog = useCallback((defaultFileName: string, fileType: CreatingFileType) => {
+    actionsRef.current.setNewFileName(defaultFileName);
+    actionsRef.current.setPendingFileType(fileType);
+    actionsRef.current.setCreateFileVisible(true);
+  }, []);
+
+  /** 新建文件名对话框确认：校验文件名并保留对应扩展名后创建本地文件并打开编辑器 */
+  const handleCreateFileConfirm = useCallback((fileName: string, fileType: CreatingFileType) => {
+    if (!fileType) return;
+    let name = sanitizeFileName(fileName);
+    if (!name) {
+      message.warning('请输入文件名称');
+      return;
+    }
+    // 根据待创建类型确定目标扩展名，保留对应扩展名，丢弃用户输入的扩展名（与重命名一致）
+    const targetExt = CREATE_FILE_EXT_MAP[fileType];
+    const userInputExt = getFileExtension(name);
+    if (userInputExt.toLowerCase() !== targetExt.toLowerCase()) {
+      name = stripFileExtension(name) + targetExt;
+      actionsRef.current.setNewFileName(name);
+    }
+    actionsRef.current.setCreateFileVisible(false);
+    createLocalOnlyAndOpen(name, fileType);
+  }, [createLocalOnlyAndOpen]);
+
+  const handleCreatePptx = useCallback(() => {
+    openCreateFileDialog('新建演示文稿.pptx', 'pptx');
+  }, [openCreateFileDialog]);
+
+  const handleCreateMarkdown = useCallback(() => {
+    openCreateFileDialog('新建文档.md', 'md');
+  }, [openCreateFileDialog]);
+
+  const handleCreateExcel = useCallback(() => {
+    openCreateFileDialog('新建表格.xlsx', 'xlsx');
+  }, [openCreateFileDialog]);
+
+  const handleCreateWord = useCallback(() => {
+    openCreateFileDialog('新建文档.docx', 'docx');
+  }, [openCreateFileDialog]);
+
+  const handleCreateRdoc = useCallback(() => {
+    openCreateFileDialog('新建文档.rdoc', 'rdoc');
+  }, [openCreateFileDialog]);
+
+  const handleCreateFolderConfirm = useCallback(async (newFolderName: string, newFolderDescs: string, isEncryptedFolder: boolean) => {
+    if (!newFolderName.trim()) {
+      message.warning('请输入文件夹名称');
+      return;
+    }
+
+    const folderName = sanitizeFileName(newFolderName);
+    if (folderName !== newFolderName) {
+      actionsRef.current.setNewFolderName(folderName);
+    }
+
+    try {
+      const { files, selectedFolderId } = stateRef.current;
+      const selectedFolder = files.find((f) => f.id === selectedFolderId);
+
+      await api.addFile(projectId, {
+        fileName: folderName,
+        filePath: selectedFolder ? `${selectedFolder.filePath}${selectedFolder.fileName}/` : `/`,
+        fileType: 'folder',
+        fileSize: 0,
+        fileResourcePath: '',
+        isSecure: isEncryptedFolder,
+        descs: newFolderDescs.trim().slice(0, FILE_DESCS_MAX_LENGTH),
+      });
+
+      loadFiles();
+      actionsRef.current.setCreateFolderVisible(false);
+    } catch (error) {
+      message.error('文件夹创建失败');
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleEditFile = useCallback(async (file: ProjectFile) => {
+    const ext = file.fileName.toLowerCase().split('.').pop() || '';
+    if (!['md', 'xlsx', 'docx', 'rdoc'].includes(ext)) {
+      message.error('不支持编辑该文件类型');
+      return;
+    }
+
+    const isOnlineFlag = typeof navigator !== 'undefined' ? navigator.onLine : true;
+
+    // ---- 本地文件：直接在编辑器中打开（已有 localId）----
+    if (file.localId) {
+      actionsRef.current.setEditingFile(file);
+      actionsRef.current.setEditorVisible(true);
+      actionsRef.current.setPreviewLocalId(file.localId);
+      actionsRef.current.setPreviewIsLocalOnly(!!file.isLocalOnly);
+      actionsRef.current.setPreviewHasUnsyncedChanges(!!file.hasUnsyncedChanges);
+      actionsRef.current.setPreviewFileName(file.fileName);
+      return;
+    }
+
+    // ---- 服务器文件：离线时先在 localFiles 创建"未同步修改"的快照条目 ----
+    if (!isOnlineFlag) {
+      try {
+        const userInfo = await CacheUserInfo.getUserInfo({ forceRefresh: false });
+        const userId = userInfo?.id || 'local-user';
+        // 读取现有缓存（若存在）作为初始内容
+        let initialContent: ArrayBuffer | string = '';
+        const cacheRec = await CacheFileContent.getCachedContent(file.id);
+        if (cacheRec) initialContent = await cacheRec.content.arrayBuffer();
+
+        // 若此文件已经有本地未同步记录，使用那个 localId
+        const existing = await getLocalFileByServerId(userId, file.id);
+        const rec = existing ?? await saveUnsyncedServerFile({
+          userId,
+          projectId,
+          parentId: file.parentId ?? null,
+          fileName: file.fileName,
+          fileType: (ext === 'docx' ? 'docx'
+            : ext === 'xlsx' ? 'xlsx'
+            : ext === 'pptx' ? 'pptx'
+            : ext === 'md' ? 'md' : 'markdown') as any,
+          serverFileId: file.id,
+          originalServerFile: file,
+          content: initialContent,
+        });
+        // 打开编辑器（使用 localFiles 中的内容）
+        actionsRef.current.setEditingFile({
+          ...file,
+          localId: rec.localId,
+          isLocalOnly: false,
+          hasUnsyncedChanges: true,
+        });
+        actionsRef.current.setEditorVisible(true);
+        actionsRef.current.setPreviewLocalId(rec.localId);
+        actionsRef.current.setPreviewIsLocalOnly(false);
+        actionsRef.current.setPreviewHasUnsyncedChanges(true);
+        actionsRef.current.setPreviewFileName(file.fileName);
+        // 列表中立即标记
+        const updated = stateRef.current.files.map(f =>
+          f.id === file.id ? { ...f, localId: rec.localId, hasUnsyncedChanges: true } : f
+        );
+        actionsRef.current.setFiles(updated);
+        actionsRef.current.setFileTreeData(buildFileTree(updated));
+        return;
+      } catch (err) {
+        console.warn('创建离线编辑快照失败:', err);
+        // 降级：继续按照普通在线流程打开（无法上传）
+      }
+    }
+
+    // ---- 服务器文件（在线）：不提前创建 localFiles 记录 ----
+    // fetchFileBuffer 内部会检查 CacheFileContent 缓存，上传后的文件可直接从缓存加载。
+    // 仅在用户保存本地缓存时（handleSaveLocalBlob/handleSaveLocalMarkdown）才创建 localFiles 记录。
+    actionsRef.current.setEditingFile(file);
+    actionsRef.current.setEditorVisible(true);
+    actionsRef.current.setPreviewLocalId(file.localId || null);
+    actionsRef.current.setPreviewIsLocalOnly(false);
+    actionsRef.current.setPreviewHasUnsyncedChanges(!!file.hasUnsyncedChanges);
+    actionsRef.current.setPreviewFileName(file.fileName);
+    actionsRef.current.setPreviewCrc32(file.crc32);
+  }, [projectId]);
+
+  // ---- 编辑器保存到本地缓存时调用（在 IndexedDB localFiles store 中同步更新内容和 hasUnsyncedChanges）----
+  const handleSaveLocalBlob = useCallback(async (localId: string | null | undefined, blob: Blob, fileName: string, markUnsynced: boolean = true) => {
+    try {
+      const buf = await blob.arrayBuffer();
+      let newLocalId: string | null | undefined = localId;
+      // 实际 stateRef 里包含 editingFile，本文件局部 FileManagerState 类型未声明，使用 any 绕过
+      const st = stateRef.current as any;
+
+      // localId 为空（例如上传成功后清除了，继续编辑首次保存）→ 在 localFiles 中新建一条记录
+      if (!newLocalId) {
+        const editingFile = st.editingFile as ProjectFile | null;
+        // 只处理服务器文件的未同步修改（本地新建文件由其他流程处理）
+        if (!editingFile || editingFile.isLocalOnly || !editingFile.id) return;
+
+        const ext = fileName.split('.').pop()?.toLowerCase() || '';
+        const userInfo = await CacheUserInfo.getUserInfo({ forceRefresh: false });
+        const userId = userInfo?.id || 'local-user';
+
+        // 从 CacheFileContent 获取原始服务器内容，用于后续差分上传基准
+        let originalContent: ArrayBuffer | undefined;
+        try {
+          const cached = await CacheFileContent.getCachedContent(editingFile.id);
+          if (cached) {
+            originalContent = await cached.content.arrayBuffer();
+          }
+        } catch (err) { console.warn('获取原始服务器缓存失败:', err); }
+
+        const rec = await saveUnsyncedServerFile({
+          userId,
+          projectId,
+          parentId: editingFile.parentId ?? null,
+          fileName,
+          fileType: (ext === 'docx' ? 'docx'
+            : ext === 'xlsx' ? 'xlsx'
+            : ext === 'pptx' ? 'pptx'
+            : ext === 'md' ? 'md' : 'markdown') as any,
+          serverFileId: editingFile.id,
+          originalServerFile: editingFile,
+          content: buf,
+          originalContent,
+          markUnsynced,
+        });
+        newLocalId = rec.localId;
+      } else {
+        // 已有 localId → 更新内容。
+        // 兜底：如果记录已被删除（例如上传后 deleteLocalFile 但 localId 未重置），
+        // updateLocalFileContent 返回 null，此时需要新建一条记录。
+        const updated = await updateLocalFileContent(newLocalId, buf, fileName, markUnsynced);
+        if (!updated) {
+          const editingFile = st.editingFile as ProjectFile | null;
+          if (!editingFile || editingFile.isLocalOnly || !editingFile.id) return;
+
+          const ext = fileName.split('.').pop()?.toLowerCase() || '';
+          const userInfo = await CacheUserInfo.getUserInfo({ forceRefresh: false });
+          const userId = userInfo?.id || 'local-user';
+
+          const rec = await saveUnsyncedServerFile({
+            userId,
+            projectId,
+            parentId: editingFile.parentId ?? null,
+            fileName,
+            fileType: (ext === 'docx' ? 'docx'
+              : ext === 'xlsx' ? 'xlsx'
+              : ext === 'pptx' ? 'pptx'
+              : ext === 'md' ? 'md' : 'markdown') as any,
+            serverFileId: editingFile.id,
+            originalServerFile: editingFile,
+            content: buf,
+            markUnsynced,
+          });
+          newLocalId = rec.localId;
+        }
+      }
+
+      // 同步刷新列表中的 hasUnsyncedChanges 标记、localId 和 fileSize
+      // markUnsynced=false（自动保存/手动保存）时不修改 hasUnsyncedChanges，只更新内容和 localId
+      const refreshed = stateRef.current.files.map(f => {
+        if (st.editingFile && f.id === (st.editingFile as ProjectFile).id) {
+          return { ...f, hasUnsyncedChanges: markUnsynced ? true : f.hasUnsyncedChanges, localId: newLocalId, fileSize: buf.byteLength };
+        }
+        if (f.localId === newLocalId) {
+          return { ...f, hasUnsyncedChanges: markUnsynced ? true : f.hasUnsyncedChanges, fileSize: buf.byteLength };
+        }
+        return f;
+      });
+      actionsRef.current.setFiles(refreshed);
+      actionsRef.current.setFileTreeData(buildFileTree(refreshed));
+
+      // 同步更新预览和编辑器的未同步状态
+      if (markUnsynced) {
+        actionsRef.current.setPreviewHasUnsyncedChanges(true);
+      }
+      if (newLocalId) {
+        actionsRef.current.setPreviewLocalId(newLocalId);
+      }
+      if (st.editingFile) {
+        actionsRef.current.setEditingFile({
+          ...st.editingFile,
+          hasUnsyncedChanges: markUnsynced ? true : (st.editingFile as ProjectFile).hasUnsyncedChanges,
+          localId: newLocalId ?? st.editingFile.localId,
+        });
+      }
+    } catch (err) {
+      console.error('保存本地文件失败:', err);
+    }
+  }, [projectId]);
+
+  const handleSaveLocalMarkdown = useCallback(async (localId: string | null | undefined, content: string, fileName: string, markUnsynced: boolean = true) => {
+    try {
+      let newLocalId: string | null | undefined = localId;
+      const st = stateRef.current as any;
+
+      if (!newLocalId) {
+        const editingFile = st.editingFile as ProjectFile | null;
+        if (!editingFile || editingFile.isLocalOnly || !editingFile.id) return;
+
+        const userInfo = await CacheUserInfo.getUserInfo({ forceRefresh: false });
+        const userId = userInfo?.id || 'local-user';
+
+        // 从 CacheFileContent 获取原始服务器内容，用于后续差分上传基准
+        let originalContent: string | undefined;
+        try {
+          const cached = await CacheFileContent.getCachedContent(editingFile.id);
+          if (cached) {
+            originalContent = await cached.content.text();
+          }
+        } catch (err) { console.warn('获取原始服务器缓存失败:', err); }
+
+        const rec = await saveUnsyncedServerFile({
+          userId,
+          projectId,
+          parentId: editingFile.parentId ?? null,
+          fileName,
+          fileType: 'md',
+          serverFileId: editingFile.id,
+          originalServerFile: editingFile,
+          content,
+          originalContent,
+          markUnsynced,
+        });
+        newLocalId = rec.localId;
+      } else {
+        // 兜底：如果记录已被删除，updateLocalFileContent 返回 null，新建一条
+        const updated = await updateLocalFileContent(newLocalId, content, fileName, markUnsynced);
+        if (!updated) {
+          const editingFile = st.editingFile as ProjectFile | null;
+          if (!editingFile || editingFile.isLocalOnly || !editingFile.id) return;
+
+          const userInfo = await CacheUserInfo.getUserInfo({ forceRefresh: false });
+          const userId = userInfo?.id || 'local-user';
+
+          const rec = await saveUnsyncedServerFile({
+            userId,
+            projectId,
+            parentId: editingFile.parentId ?? null,
+            fileName,
+            fileType: 'md',
+            serverFileId: editingFile.id,
+            originalServerFile: editingFile,
+            content,
+            markUnsynced,
+          });
+          newLocalId = rec.localId;
+        }
+      }
+
+      const refreshed = stateRef.current.files.map(f => {
+        if (st.editingFile && f.id === (st.editingFile as ProjectFile).id) {
+          return { ...f, hasUnsyncedChanges: markUnsynced ? true : f.hasUnsyncedChanges, localId: newLocalId, fileSize: content.length };
+        }
+        if (f.localId === newLocalId) {
+          return { ...f, hasUnsyncedChanges: markUnsynced ? true : f.hasUnsyncedChanges, fileSize: content.length };
+        }
+        return f;
+      });
+      actionsRef.current.setFiles(refreshed);
+      actionsRef.current.setFileTreeData(buildFileTree(refreshed));
+
+      if (markUnsynced) {
+        actionsRef.current.setPreviewHasUnsyncedChanges(true);
+      }
+      if (newLocalId) {
+        actionsRef.current.setPreviewLocalId(newLocalId);
+      }
+      if (st.editingFile) {
+        actionsRef.current.setEditingFile({
+          ...st.editingFile,
+          hasUnsyncedChanges: markUnsynced ? true : (st.editingFile as ProjectFile).hasUnsyncedChanges,
+          localId: newLocalId ?? st.editingFile.localId,
+        });
+      }
+    } catch (err) {
+      console.error('保存本地 Markdown 失败:', err);
+    }
+  }, [projectId]);
+
+  const handleUploadBlob = useCallback(async (editingFile: ProjectFile | null, initialBlob: Blob | undefined, blob: Blob, fileName: string) => {
+    if (!editingFile) return;
+    try {
+      const isLocalOnly = !!editingFile.isLocalOnly;
+      const localId = editingFile.localId;
+      let serverFileIdForCache = editingFile.id; // 服务器文件 id（新建后会替换）
+
+      if (isLocalOnly) {
+        // ========== 本地新建文件（首次上传）→ CREATE 流程：上传文件 + addFile 到服务器 ==========
+        const { files, selectedFolderId } = stateRef.current;
+        const selectedFolder = files.find((f) => f.id === selectedFolderId);
+        const filePath = selectedFolder ? `${selectedFolder.filePath}${selectedFolder.fileName}/` : '/';
+
+        const { crc32, serverFileName } = await uploadFileBlob(blob, fileName,
+          percent => actionsRef.current.setUploadPercent(percent),
+          success => actionsRef.current.setUploadSuccess(success),
+        );
+
+        const response = await api.addFile(projectId, {
+          fileName,
+          filePath,
+          fileType: getMimeType(fileName),
+          fileSize: blob.size,
+          crc32,
+          fileResourcePath: serverFileName,
+        });
+
+        if (response.code === ResponseCode.SUCCESS && response.data) {
+          serverFileIdForCache = response.data.fileId;
+          // 标记本地记录为已同步（删除本地条目，因为服务器已经成为权威来源）
+          if (localId) {
+            try {
+              await markLocalFileSynced(localId, serverFileIdForCache);
+              await deleteLocalFile(localId);
+            } catch (err) { console.warn('标记本地已同步失败:', err); }
+          }
+          // 保存服务器缓存
+          await CacheFileContent.saveToCache(serverFileIdForCache, blob, crc32, blob.size);
+          actionsRef.current.setUploadPercent(undefined);
+          message.success('文件上传成功');
+          loadFiles();
+        } else {
+          actionsRef.current.setUploadPercent(undefined);
+          message.error(response.message || '上传失败');
+        }
+        return;
+      }
+
+      // ========== 服务器文件的修改 → UPDATE 流程 ==========
+      // 上传前检查文件是否被其他用户更新过（基于 uploadTime 对比）
+      const conflictInfo = await checkFileUpdateConflict(api, editingFile);
+      if (conflictInfo.result === 'cancel') {
+        actionsRef.current.setUploadPercent(undefined);
+        return;
+      }
+
+      // 差分基准选择：
+      // - 有 localId（未同步修改）：优先使用 CacheFileContent 中经过 CRC 校验的服务器内容，
+      //   其次使用本地记录中保存的 originalContent，
+      //   最后回退到 initialBlob（可能是编辑后的内容，差分可能失败）
+      // - 无 localId（在线编辑）：使用 initialBlob 作为差分基准
+      let deltaBaseBlob = initialBlob;
+      if (localId && !conflictInfo.result.includes('overwrite')) {
+        // 优先：从 CacheFileContent 获取并 CRC 校验
+        try {
+          const cached = await CacheFileContent.getCachedContent(editingFile.id);
+          if (cached && conflictInfo.serverCrc32 !== undefined) {
+            const cachedCrc = await calculateCRC32(new File([cached.content], fileName, { type: getMimeType(fileName) }));
+            if (cachedCrc === conflictInfo.serverCrc32) {
+              const buf = await cached.content.arrayBuffer();
+              deltaBaseBlob = new Blob([buf]);
+            } else {
+              console.warn('[上传诊断] CacheFileContent CRC 不匹配服务器, cached:', cachedCrc, 'server:', conflictInfo.serverCrc32);
+            }
+          }
+        } catch (err) {
+          console.warn('[上传诊断] CacheFileContent 获取失败:', err);
+        }
+
+        // 其次：从本地记录的 originalContent 获取
+        if (deltaBaseBlob === initialBlob) {
+          try {
+            const localRec = await getLocalFile(localId);
+            if (localRec?.originalContent) {
+              const origBuf = typeof localRec.originalContent === 'string'
+                ? new TextEncoder().encode(localRec.originalContent).buffer
+                : localRec.originalContent;
+              deltaBaseBlob = new Blob([origBuf]);
+            }
+          } catch (err) {
+            console.warn('[上传诊断] 加载 originalContent 失败:', err);
+          }
+        }
+      }
+
+      // 冲突覆盖 → 强制全量上传；无冲突 → 先尝试差分上传
+      // deltaBaseBlob / initialBlob 为空时无法做差分，走全量
+      const forceFullUpload = conflictInfo.result === 'overwrite' || !deltaBaseBlob;
+
+      // 差分失败时的确认回调：有 localId 时提示"其他用户已上传新版本"，无 localId 时自动回退
+      const onDeltaFail = localId ? async () => {
+        const confirmed = await uiConfirm.confirm('已经有其他用户更新了文件，是否全量覆盖上传？');
+        return confirmed;
+      } : undefined;
+
+      const { crc32 } = await uploadFileDelta(
+        editingFile.id,
+        fileName,
+        deltaBaseBlob || new Blob([]),
+        blob,
+        percent => actionsRef.current.setUploadPercent(percent),
+        success => actionsRef.current.setUploadSuccess(success),
+        forceFullUpload,
+        onDeltaFail,
+        { updateFile: api.updateFile, updateFileDelta: api.updateFileDelta },
+      );
+
+      // 更新服务器缓存
+      await CacheFileContent.removeFromCache(editingFile.id);
+      await CacheFileContent.saveToCache(editingFile.id, blob, crc32, blob.size);
+
+      // 若之前是未同步修改的服务器文件 → 标记同步完成
+      if (localId) {
+        try {
+          await markLocalFileSynced(localId, editingFile.id);
+          await deleteLocalFile(localId);
+        } catch (err) { console.warn('标记未同步文件为已同步失败:', err); }
+        // 刷新本地标记
+        const refreshed = stateRef.current.files.map(f =>
+          f.id === editingFile.id ? { ...f, hasUnsyncedChanges: false, localId: undefined } : f
+        );
+        actionsRef.current.setFiles(refreshed);
+        actionsRef.current.setFileTreeData(buildFileTree(refreshed));
+      }
+      // 清除编辑器中的"有未同步修改"标记
+      actionsRef.current.setPreviewHasUnsyncedChanges(false);
+      // 重置 previewLocalId：上传成功后旧的 localFiles 记录已被删除，
+      // 若不重置，后续编辑保存时 effectiveLocalId 仍指向已删除的 localId，
+      // 导致 updateLocalFileContent 找不到记录、内容不持久化，再次打开时出现 "No document loaded"。
+      actionsRef.current.setPreviewLocalId(null);
+      // 同步更新 editingFile，确保编辑器 props 中的 hasUnsyncedChanges 立即生效
+      // 同时刷新 uploadTime，避免下次冲突检测把自己刚上传的误判为"他人更新"
+      const latestMeta = await fetchLatestFileMeta(api, editingFile.id);
+      actionsRef.current.setEditingFile({
+        ...editingFile,
+        hasUnsyncedChanges: false,
+        localId: undefined,
+        uploadTime: latestMeta?.uploadTime ?? editingFile.uploadTime,
+        updateTime: latestMeta?.updateTime ?? editingFile.updateTime,
+      });
+      actionsRef.current.setUploadPercent(undefined);
+      message.success('文件更新成功');
+      loadFiles();
+    } catch (error) {
+      actionsRef.current.setUploadPercent(undefined);
+      console.error('更新/上传文件失败:', error);
+      message.error(typeof error === 'string' ? error : '上传失败');
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleUploadMarkdown = useCallback(async (editingFile: ProjectFile | null, oldContent: string, content: string, fileName: string) => {
+    if (!editingFile) return;
+    try {
+      const isLocalOnly = !!editingFile.isLocalOnly;
+      const localId = editingFile.localId;
+      let serverFileIdForCache = editingFile.id;
+      const uploadMimeType = fileName.toLowerCase().endsWith('.rdoc') ? 'application/json' : 'text/markdown';
+      const blob = new Blob([content], { type: uploadMimeType });
+
+      if (isLocalOnly) {
+        // ========== 本地新建 Markdown（首次上传）→ CREATE 流程 ==========
+        const { files, selectedFolderId } = stateRef.current;
+        const selectedFolder = files.find((f) => f.id === selectedFolderId);
+        const filePath = selectedFolder ? `${selectedFolder.filePath}${selectedFolder.fileName}/` : '/';
+
+        const { crc32, serverFileName } = await uploadFileBlob(blob, fileName,
+          percent => actionsRef.current.setUploadPercent(percent),
+          success => actionsRef.current.setUploadSuccess(success),
+        );
+
+        const response = await api.addFile(projectId, {
+          fileName,
+          filePath,
+          fileType: uploadMimeType,
+          fileSize: blob.size,
+          crc32,
+          fileResourcePath: serverFileName,
+        });
+
+        if (response.code === ResponseCode.SUCCESS && response.data) {
+          serverFileIdForCache = response.data.fileId;
+          if (localId) {
+            try {
+              await markLocalFileSynced(localId, serverFileIdForCache);
+              await deleteLocalFile(localId);
+            } catch (err) { console.warn('标记本地已同步失败:', err); }
+          }
+          await CacheFileContent.saveToCache(serverFileIdForCache, blob, crc32, blob.size);
+          actionsRef.current.setUploadPercent(undefined);
+          message.success('Markdown 文档上传成功');
+          loadFiles();
+        } else {
+          actionsRef.current.setUploadPercent(undefined);
+          message.error(response.message || '上传失败');
+        }
+        return;
+      }
+
+      // ========== 服务器 Markdown 文件的修改 → UPDATE 流程 ==========
+      // 上传前检查文件是否被其他用户更新过（基于 uploadTime 对比）
+      const conflictInfo = await checkFileUpdateConflict(api, editingFile);
+      if (conflictInfo.result === 'cancel') {
+        actionsRef.current.setUploadPercent(undefined);
+        return;
+      }
+
+      // 差分基准选择：
+      // - 有 localId（未同步修改）：优先使用 CacheFileContent 中经过 CRC 校验的服务器内容，
+      //   其次使用本地记录中保存的 originalContent，
+      //   最后回退到 oldContent
+      // - 无 localId（在线编辑）：使用 oldContent 作为差分基准
+      let deltaBaseContent = oldContent;
+      if (localId && !conflictInfo.result.includes('overwrite')) {
+        // 优先：从 CacheFileContent 获取并 CRC 校验
+        try {
+          const cached = await CacheFileContent.getCachedContent(editingFile.id);
+          if (cached && conflictInfo.serverCrc32 !== undefined) {
+            const cachedText = await cached.content.text();
+            const cachedCrc = await calculateCRC32(new File([cachedText], fileName, { type: 'text/markdown' }));
+            if (cachedCrc === conflictInfo.serverCrc32) {
+              deltaBaseContent = cachedText;
+            } else {
+              console.warn('[上传诊断] Markdown CacheFileContent CRC 不匹配, cached:', cachedCrc, 'server:', conflictInfo.serverCrc32);
+            }
+          }
+        } catch (err) {
+          console.warn('[上传诊断] Markdown CacheFileContent 获取失败:', err);
+        }
+
+        // 其次：从本地记录的 originalContent 获取
+        if (deltaBaseContent === oldContent) {
+          try {
+            const localRec = await getLocalFile(localId);
+            if (localRec?.originalContent && typeof localRec.originalContent === 'string') {
+              deltaBaseContent = localRec.originalContent;
+            }
+          } catch (err) {
+            console.warn('[上传诊断] Markdown 加载 originalContent 失败:', err);
+          }
+        }
+      }
+
+      const forceFullUpload = conflictInfo.result === 'overwrite';
+
+      // 差分失败时的确认回调：有 localId 时提示"其他用户已上传新版本"
+      const onDeltaFail = localId ? async () => {
+        const confirmed = await uiConfirm.confirm('已经有其他用户更新了文件，是否全量覆盖上传？');
+        return confirmed;
+      } : undefined;
+
+      const { crc32 } = await uploadMarkdownDelta(
+        editingFile.id,
+        fileName,
+        deltaBaseContent,
+        content,
+        percent => actionsRef.current.setUploadPercent(percent),
+        success => actionsRef.current.setUploadSuccess(success),
+        forceFullUpload,
+        onDeltaFail,
+        { updateFile: api.updateFile, updateFileDelta: api.updateFileDelta },
+      );
+      await CacheFileContent.removeFromCache(editingFile.id);
+      await CacheFileContent.saveToCache(editingFile.id, blob, crc32, blob.size);
+
+      if (localId) {
+        try {
+          await markLocalFileSynced(localId, editingFile.id);
+          await deleteLocalFile(localId);
+        } catch (err) { console.warn('标记未同步文件为已同步失败:', err); }
+        const refreshed = stateRef.current.files.map(f =>
+          f.id === editingFile.id ? { ...f, hasUnsyncedChanges: false, localId: undefined } : f
+        );
+        actionsRef.current.setFiles(refreshed);
+        actionsRef.current.setFileTreeData(buildFileTree(refreshed));
+      }
+      // 清除编辑器中的"有未同步修改"标记
+      actionsRef.current.setPreviewHasUnsyncedChanges(false);
+      // 重置 previewLocalId：上传成功后旧的 localFiles 记录已被删除
+      actionsRef.current.setPreviewLocalId(null);
+      // 同步更新 editingFile，确保编辑器 props 中的 hasUnsyncedChanges 立即生效
+      // 同时刷新 uploadTime，避免下次冲突检测把自己刚上传的误判为"他人更新"
+      const latestMeta = await fetchLatestFileMeta(api, editingFile.id);
+      actionsRef.current.setEditingFile({
+        ...editingFile,
+        hasUnsyncedChanges: false,
+        localId: undefined,
+        uploadTime: latestMeta?.uploadTime ?? editingFile.uploadTime,
+        updateTime: latestMeta?.updateTime ?? editingFile.updateTime,
+      });
+      actionsRef.current.setUploadPercent(undefined);
+      message.success('文档更新成功');
+      loadFiles();
+    } catch (error) {
+      actionsRef.current.setUploadPercent(undefined);
+      console.error('更新/上传失败:', error);
+      message.error('更新失败');
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleCreateUploadBlob = useCallback(async (initialBlob: Blob | undefined, blob: Blob, fileName: string) => {
+    try {
+      const { files, selectedFolderId } = stateRef.current;
+      const selectedFolder = files.find((f) => f.id === selectedFolderId);
+      const filePath = selectedFolder ? `${selectedFolder.filePath}${selectedFolder.fileName}/` : '/';
+
+      const { crc32, serverFileName } = await uploadFileBlob(blob, fileName,
+        percent => actionsRef.current.setUploadPercent(percent),
+        success => {
+          actionsRef.current.setUploadSuccess(success);
+        }
+      );
+
+      const response = await api.addFile(projectId, {
+        fileName: fileName,
+        filePath: filePath,
+        fileType: getMimeType(fileName),
+        fileSize: blob.size,
+        crc32,
+        fileResourcePath: serverFileName
+      });
+
+      actionsRef.current.setUploadPercent(undefined);
+
+      if (response.code === ResponseCode.SUCCESS) {
+        await CacheFileContent.saveToCache(response.data!.fileId, blob, crc32, blob.size);
+        loadFiles();
+      } else {
+        message.error(response.message || '创建失败');
+      }
+    } catch (error) {
+      actionsRef.current.setUploadPercent(undefined);
+      console.error('创建文件失败:', error);
+      message.error('创建失败');
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleCreateUploadMarkdown = useCallback(async (oldContent: string, content: string, fileName: string) => {
+    try {
+      const { files, selectedFolderId } = stateRef.current;
+      const selectedFolder = files.find((f) => f.id === selectedFolderId);
+      const filePath = selectedFolder ? `${selectedFolder.filePath}${selectedFolder.fileName}/` : '/';
+      const createMimeType = fileName.toLowerCase().endsWith('.rdoc') ? 'application/json' : 'text/markdown';
+      const blob = new Blob([content], { type: createMimeType });
+
+      const { crc32, serverFileName } = await uploadFileBlob(blob, fileName,
+        percent => actionsRef.current.setUploadPercent(percent),
+        success => actionsRef.current.setUploadSuccess(success),
+      );
+
+      const response = await api.addFile(projectId, {
+        fileName: fileName,
+        filePath: filePath,
+        fileType: createMimeType,
+        fileSize: blob.size,
+        crc32,
+        fileResourcePath: serverFileName
+      });
+
+      actionsRef.current.setUploadPercent(undefined);
+
+      if (response.code === ResponseCode.SUCCESS) {
+        await CacheFileContent.saveToCache(response.data!.fileId, blob, crc32, blob.size);
+        loadFiles();
+      } else {
+        message.error(response.message || '创建失败');
+      }
+    } catch (error) {
+      actionsRef.current.setUploadPercent(undefined);
+      console.error('创建 Markdown 文档失败:', error);
+      message.error('创建失败');
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleExpand = useCallback((expanded: boolean, record: ProjectFile) => {
+    if (!record.fileType || record.fileType !== 'folder') return;
+    const { expandedRowKeys } = stateRef.current;
+    actionsRef.current.setExpandedRowKeys(expanded
+      ? [...expandedRowKeys, record.id]
+      : expandedRowKeys.filter(key => key !== record.id)
+    );
+    actionsRef.current.setSelectedFolderId(expanded ? record.id : null);
+  }, []);
+
+  const toggleFolderExpand = useCallback((record: ProjectFile, tableView: boolean) => {
+    if (record.fileType !== 'folder') return;
+
+    const { expandedRowKeys, selectedFolderId, files } = stateRef.current;
+
+    actionsRef.current.setExpandedRowKeys(expandedRowKeys.includes(record.id)
+      ? expandedRowKeys.filter(key => key !== record.id)
+      : [...expandedRowKeys, record.id]
+    );
+
+    actionsRef.current.setSelectedFolderId(selectedFolderId === record.id ? null : record.id);
+
+    if (!tableView) {
+      if (!isFolderExpanded(record.id)) {
+        actionsRef.current.setFileTreeData(buildFileTree(getFileDescendants(record, files)));
+      } else {
+        const parentFolder = files.find((f) => f.id === record.parentId);
+        actionsRef.current.setFileTreeData(buildFileTree(parentFolder
+          ? getFileDescendants(parentFolder, files)
+          : files
+        ));
+      }
+    }
+  }, [isFolderExpanded]);
+
+  const handleDragStart = useCallback((fileId: string) => {
+    actionsRef.current.setDragSourceId(fileId);
+  }, []);
+
+  const handleDragEnd = useCallback(() => {
+    actionsRef.current.setDragSourceId(null);
+    actionsRef.current.setDragOverId(null);
+  }, []);
+
+  const handleDragOver = useCallback((fileId: string) => {
+    actionsRef.current.setDragOverId(fileId);
+  }, []);
+
+  const handleDragLeave = useCallback((fileId: string) => {
+    if (stateRef.current.dragOverId === fileId) {
+      actionsRef.current.setDragOverId(null);
+    }
+  }, []);
+
+  const handleDrop = useCallback((sourceId: string, targetId: string) => {
+    handleMove(sourceId, targetId);
+    actionsRef.current.setDragOverId(null);
+  }, [handleMove]);
+
+  const handleExternalDragEnter = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    if (e.dataTransfer.types.includes('Files') || e.dataTransfer.items.length > 0) {
+      externalDragCounter.current++;
+      actionsRef.current.setIsExternalDragOver(true);
+    }
+  }, []);
+
+  const handleExternalDragOver = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    if (e.dataTransfer.types.includes('Files') || e.dataTransfer.items.length > 0) {
+      e.dataTransfer.dropEffect = 'copy';
+    }
+  }, []);
+
+  const handleExternalDragLeave = useCallback((e: React.DragEvent) => {
+    externalDragCounter.current--;
+    if (externalDragCounter.current <= 0) {
+      externalDragCounter.current = 0;
+      actionsRef.current.setIsExternalDragOver(false);
+    }
+  }, []);
+
+  const handleExternalDrop = useCallback(async (e: React.DragEvent) => {
+    e.preventDefault();
+    externalDragCounter.current = 0;
+    actionsRef.current.setIsExternalDragOver(false);
+
+    const droppedFiles = await extractFilesFromDrop(e.dataTransfer.items);
+    if (droppedFiles.length === 0) return;
+
+    try {
+      const { files, selectedFolderId } = stateRef.current;
+      const selectedFolder = files.find((f) => f.id === selectedFolderId);
+      const basePath = selectedFolder ? `${selectedFolder.filePath}${selectedFolder.fileName}/` : '/';
+      const allCreatedFolders = new Set<string>();
+
+      const existingFolderKeys = new Set(
+        files
+          .filter(f => f.fileType === 'folder')
+          .map(f => `${f.filePath}${f.fileName}`)
+      );
+
+      for (const [index, { file, relativePath }] of droppedFiles.entries()) {
+        actionsRef.current.setDragUploadingFileName(droppedFiles.length > 1 ? `${relativePath} (${index + 1}/${droppedFiles.length})` : relativePath);
+        actionsRef.current.setDragUploadPercent(0);
+        actionsRef.current.setDragUploadSuccess(undefined);
+
+        const lastSlashIndex = relativePath.lastIndexOf('/');
+        const fileName = lastSlashIndex >= 0 ? relativePath.substring(lastSlashIndex + 1) : relativePath;
+        const folderPath = lastSlashIndex >= 0 ? relativePath.substring(0, lastSlashIndex) : '';
+
+        let targetFilePath = basePath;
+        if (folderPath) {
+          const fullFolderPath = basePath + folderPath + '/';
+          if (!allCreatedFolders.has(fullFolderPath)) {
+            const parts = folderPath.split('/');
+            let currentPath = basePath;
+
+            for (const part of parts) {
+              const sanitizedPart = sanitizeFileName(part);
+              const folderKey = `${currentPath}${sanitizedPart}`;
+
+              if (!existingFolderKeys.has(folderKey) && !allCreatedFolders.has(folderKey)) {
+                await api.addFile(projectId, {
+                  fileName: sanitizedPart,
+                  filePath: currentPath,
+                  fileType: 'folder',
+                  fileSize: 0,
+                  fileResourcePath: '',
+                  isSecure: false,
+                });
+                allCreatedFolders.add(folderKey);
+              }
+
+              currentPath = `${currentPath}${sanitizedPart}/`;
+            }
+          }
+          allCreatedFolders.add(fullFolderPath);
+          targetFilePath = fullFolderPath;
+        }
+
+        const { crc32, serverFileName } = await uploadFileBlob(file, fileName,
+          (p) => actionsRef.current.setDragUploadPercent(p),
+          (s) => actionsRef.current.setDragUploadSuccess(s),
+        );
+
+        const response = await api.addFile(projectId, {
+          fileName: fileName,
+          filePath: targetFilePath,
+          fileType: file.type || 'application/octet-stream',
+          fileSize: file.size,
+          crc32,
+          fileResourcePath: serverFileName,
+        });
+
+        if (response.code !== ResponseCode.SUCCESS) {
+          actionsRef.current.setDragUploadSuccess(false);
+          message.error(response.message || `文件 ${relativePath} 上传失败`);
+        } else {
+          // 上传成功后保存缓存
+          if (response.data?.fileId) {
+            await CacheFileContent.saveToCache(response.data.fileId, file as Blob, crc32, file.size);
+          }
+        }
+      }
+
+      loadFiles();
+    } catch (error) {
+      console.error('文件上传失败:', error);
+      actionsRef.current.setDragUploadSuccess(false);
+      if (typeof error === 'string') {
+        message.error('文件上传失败: ' + error);
+      } else {
+        message.error('文件上传失败');
+      }
+    } finally {
+      window.setTimeout(() => {
+        actionsRef.current.setDragUploadPercent(undefined);
+        actionsRef.current.setDragUploadSuccess(undefined);
+        actionsRef.current.setDragUploadingFileName('');
+      }, 1000);
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleContextMenu = useCallback((event: React.MouseEvent, record: ProjectFile) => {
+    event.preventDefault();
+    actionsRef.current.setContextMenuRecord(record);
+    actionsRef.current.setContextMenuPosition({ x: event.clientX, y: event.clientY });
+    actionsRef.current.setContextMenuVisible(true);
+  }, []);
+
+  const handleMoveToProject = useCallback((file: ProjectFile) => {
+    actionsRef.current.setMoveCopyFiles([file]);
+    actionsRef.current.setMoveCopyMode('move');
+    actionsRef.current.setMoveCopyModalVisible(true);
+    actionsRef.current.setContextMenuVisible(false);
+    actionsRef.current.setContextMenuRecord(null);
+  }, []);
+
+  const handleCopyToProject = useCallback((file: ProjectFile) => {
+    actionsRef.current.setMoveCopyFiles([file]);
+    actionsRef.current.setMoveCopyMode('copy');
+    actionsRef.current.setMoveCopyModalVisible(true);
+    actionsRef.current.setContextMenuVisible(false);
+    actionsRef.current.setContextMenuRecord(null);
+  }, []);
+
+  const handleCopyToSelf = useCallback(async (file: ProjectFile) => {
+    actionsRef.current.setContextMenuVisible(false);
+    actionsRef.current.setContextMenuRecord(null);
+    if (!api.copyFileToProject) return;
+    try {
+      const response = await api.copyFileToProject(projectId, file.id);
+      if (response.code === ResponseCode.SUCCESS) {
+        message.success(`复制成功，文件名为：${response.data}`);
+        loadFiles();
+      } else {
+        message.error(response.message || '复制失败');
+      }
+    } catch (error) {
+      message.error('复制失败');
+      console.error('复制副本失败:', error);
+    }
+  }, [projectId, api, loadFiles]);
+
+  const handleMoveCopySuccess = useCallback(() => {
+    actionsRef.current.setMoveCopyModalVisible(false);
+    actionsRef.current.setMoveCopyFiles([]);
+    loadFiles();
+  }, [loadFiles]);
+
+  const handleViewVersionHistory = useCallback((file: ProjectFile) => {
+    actionsRef.current.setVersionHistoryFile(file);
+    actionsRef.current.setVersionHistoryModalVisible(true);
+    actionsRef.current.setContextMenuVisible(false);
+    actionsRef.current.setContextMenuRecord(null);
+  }, []);
+
+  const handleOpenInNewWindow = useCallback((file: ProjectFile) => {
+    if (file.fileType === 'folder') return;
+    const fileLink = `${window.location.origin}/filepreview?fileid=${file.id}&path=${encodeURIComponent(file.fileResourcePath)}&name=${encodeURIComponent(file.fileName)}`;
+    window.open(fileLink, '_blank', 'noopener,noreferrer');
+    actionsRef.current.setContextMenuVisible(false);
+    actionsRef.current.setContextMenuRecord(null);
+  }, []);
+
+  const handleRootDragOver = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    actionsRef.current.setRootDragOver(true);
+  }, []);
+
+  const handleRootDragLeave = useCallback(() => {
+    actionsRef.current.setRootDragOver(false);
+  }, []);
+
+  const handleRootDrop = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    actionsRef.current.setRootDragOver(false);
+    const sourceId = e.dataTransfer.getData('text/plain');
+    if (sourceId) {
+      handleMove(sourceId, null);
+    }
+  }, [handleMove]);
+
+  const initUserRole = useCallback(() => {
+    if (!api.resolveIsManager) return;
+    api.resolveIsManager(projectId).then(isManager => {
+      if (!isManager) {
+        actionsRef.current.setIsManager(false);
+        return;
+      }
+
+      // 非私有项目需要额外检查文件夹下载权限
+      const checkFolderDownloadPermission = async (): Promise<boolean> => {
+        const userInfo = await CacheUserInfo.getUserInfo({ forceRefresh: false });
+        const userId = userInfo?.id || 'local-user';
+        const isPrivateProject = projectId === userId;
+        if (isPrivateProject) {
+          return true;
+        }
+        return CachePermissionInfo.hasPermission({ permission: PERMISSION_FOLDER_DOWNLOAD });
+      };
+
+      checkFolderDownloadPermission().then(hasPermission => {
+        if (hasPermission) {
+          actionsRef.current.setIsManager(true);
+        }
+      }).catch(() => { /* 忽略权限检查失败，保持默认非管理员 */ });
+    }).catch(() => { /* 忽略角色解析失败，保持默认非管理员 */ });
+  }, [projectId, api]);
+
+  const initViewMode = useCallback(async () => {
+    const cached = await getViewMode(PAGE_KEY);
+    if (cached && (cached === 'grid' || cached === 'table')) {
+      actionsRef.current.setViewMode(cached);
+    }
+  }, []);
+
+  const handleClearCache = useCallback(async (file: ProjectFile) => {
+    try {
+      // 1. 清除文件内容缓存（IndexedDB fileCache store）
+      await CacheFileContent.removeFromCache(file.id);
+      // 2. 清除文件元数据缓存（IndexedDB fileMeta store）
+      try {
+        await CacheFileMeta.removeFileMeta(file.id);
+      } catch (err) {
+        console.warn('删除 fileMeta 记录失败:', err);
+      }
+      // 3. 清除 localFiles store 中的未同步记录（含 hasUnsyncedChanges 标记）
+      if (file.localId) {
+        try {
+          await deleteLocalFile(file.localId);
+        } catch (err) {
+          console.warn('删除 localFiles 记录失败:', err);
+        }
+      }
+      message.success('缓存清理成功');
+      // 4. 更新文件列表状态：清除 hasLocalCache、hasUnsyncedChanges、localId
+      const { files } = stateRef.current;
+      const updatedFiles = files.map(f => 
+        f.id === file.id ? { ...f, hasLocalCache: false, hasUnsyncedChanges: false, localId: undefined } : f
+      );
+      actionsRef.current.setFileTreeData(buildFileTree(updatedFiles));
+      actionsRef.current.setFiles(updatedFiles);
+      actionsRef.current.setContextMenuVisible(false);
+      actionsRef.current.setContextMenuRecord(null);
+    } catch (error) {
+      console.error('清理缓存失败:', error);
+      message.error('清理缓存失败');
+    }
+  }, []);
+
+  const handleCacheSaved = useCallback((fileId: string) => {
+    const { files } = stateRef.current;
+    const file = files.find(f => f.id === fileId);
+    if (file && !file.hasLocalCache) {
+      const updatedFiles = files.map(f => 
+        f.id === fileId ? { ...f, hasLocalCache: true } : f
+      );
+      actionsRef.current.setFileTreeData(buildFileTree(updatedFiles));
+      actionsRef.current.setFiles(updatedFiles);
+    }
+  }, []);
+  handleCacheSavedRef.current = handleCacheSaved;
+
+  return useMemo(() => ({
+    loadFiles,
+    uploadFiles,
+    handlePreview,
+    handleDownload,
+    handleDownloadFolder,
+    handleShareToWechat,
+    handleCopyLink,
+    handleJumpToContract,
+    handleCreateContract,
+    handleGenerateTempLink,
+    handleDelete,
+    isFolderExpanded,
+    handleMove,
+    handleRename,
+    handleEditDescs,
+    handleDescsConfirm,
+    handleRenameConfirm,
+    handleCreateFolder,
+    openCreator,
+    handleCreatePptx,
+    handleCreateMarkdown,
+    handleCreateRdoc,
+    handleCreateExcel,
+    handleCreateWord,
+    handleCreateFileConfirm,
+    handleCreateFolderConfirm,
+    handleEditFile,
+    handleUploadBlob,
+    handleUploadMarkdown,
+    handleCreateUploadBlob,
+    handleCreateUploadMarkdown,
+    handleSaveLocalBlob,
+    handleSaveLocalMarkdown,
+    handleExpand,
+    toggleFolderExpand,
+    handleDragStart,
+    handleDragEnd,
+    handleDragOver,
+    handleDragLeave,
+    handleDrop,
+    handleExternalDragEnter,
+    handleExternalDragOver,
+    handleExternalDragLeave,
+    handleExternalDrop,
+    handleContextMenu,
+    handleMoveToProject,
+    handleCopyToProject,
+    handleCopyToSelf,
+    handleMoveCopySuccess,
+    handleViewVersionHistory,
+    handleClearCache,
+    handleCacheSaved,
+    handleOpenInNewWindow,
+    handleRootDragOver,
+    handleRootDragLeave,
+    handleRootDrop,
+    initUserRole,
+    initViewMode,
+  }), [
+    loadFiles,
+    uploadFiles,
+    handlePreview,
+    handleDownload,
+    handleDownloadFolder,
+    handleShareToWechat,
+    handleCopyLink,
+    handleJumpToContract,
+    handleCreateContract,
+    handleGenerateTempLink,
+    handleDelete,
+    isFolderExpanded,
+    handleMove,
+    handleRename,
+    handleEditDescs,
+    handleDescsConfirm,
+    handleRenameConfirm,
+    handleCreateFolder,
+    openCreator,
+    handleCreatePptx,
+    handleCreateMarkdown,
+    handleCreateRdoc,
+    handleCreateExcel,
+    handleCreateWord,
+    handleCreateFileConfirm,
+    handleCreateFolderConfirm,
+    handleEditFile,
+    handleUploadBlob,
+    handleUploadMarkdown,
+    handleCreateUploadBlob,
+    handleCreateUploadMarkdown,
+    handleSaveLocalBlob,
+    handleSaveLocalMarkdown,
+    handleExpand,
+    toggleFolderExpand,
+    handleDragStart,
+    handleDragEnd,
+    handleDragOver,
+    handleDragLeave,
+    handleDrop,
+    handleExternalDragEnter,
+    handleExternalDragOver,
+    handleExternalDragLeave,
+    handleExternalDrop,
+    handleContextMenu,
+    handleMoveToProject,
+    handleCopyToProject,
+    handleCopyToSelf,
+    handleMoveCopySuccess,
+    handleViewVersionHistory,
+    handleClearCache,
+    handleCacheSaved,
+    handleOpenInNewWindow,
+    handleRootDragOver,
+    handleRootDragLeave,
+    handleRootDrop,
+    initUserRole,
+    initViewMode,
+  ]);
+};