feat: 增强 webMcpService，新增内容校验与区块创建事件

- 新增 `requiredContent` 函数，用于校验区块输入内容
- 定义 `BLOCK_CREATED_EVENT`，区块创建成功后派发该事件
- 更新区块创建逻辑，接入新增内容校验并触发事件

feat: 在 workflowService 规范化导出链接
- 实现 `normalizeExportDownloadUrl`，将工作流生成的导出地址适配为后端配置域名
- 更新 `triggerDocumentWorkflow`，调用新的地址规范化方法

feat: 在 chatStore 实现活跃会话管理
- 基于 localStorage 实现活跃会话的持久化与读取能力
- 升级会话管理逻辑，保障活跃会话正常加载与保存

refactor: 精简 editorStore，抽离工具函数
- 将区块操作相关工具函数迁移至 `editorStoreHelpers.ts`
- 清理 `editorStore.ts` 冗余代码，提升代码可读性
- 新增 `applyRemoteBlockInsert`，更高效处理远端区块新增操作

chore: 将 editorStore 类型定义拆分至独立文件
- 新建 `editorStoreTypes.ts`，定义编辑器状态、操作相关接口，提升类型安全性与代码整洁度

refactor: 优化区块序列化与更新处理逻辑
- 优化 `editorStoreHelpers.ts` 内区块序列化逻辑，妥善处理区块更新与状态管理
- 整合区块更新合并、序列化相关函数，提升代码可维护性

src/App.tsx

@@ -25,13 +25,15 @@
  */
 
 import React, { useCallback, useEffect, useState, memo, lazy, Suspense, useMemo } from 'react';
-import { ConfigProvider, Alert, Button, Drawer, Spin } from 'antd';
+import { ConfigProvider, Alert, Button, Drawer, Spin, message } from 'antd';
 import { MessageOutlined } from '@ant-design/icons';
 import zhCN from 'antd/locale/zh_CN';
 
 import { ErrorBoundary } from './components/common';
 import ResizableLayout from './components/Layout/ResizableLayout';
 import { useUIStore } from './stores/uiStore';
+import { getDocument } from './services/documentService';
+import { isApiError } from './services/api';
 
 // ── Lazy-loaded panel components (Req 13.2, 13.8) ────────────────────────────
 // These non-first-screen panels are split into separate chunks by Vite,
@@ -73,6 +75,14 @@ const PanelFallback: React.FC = memo(() => (
 ));
 PanelFallback.displayName = 'PanelFallback';
 
+const leftPanel = (
+  <Suspense fallback={<PanelFallback />}>
+    <ChatPanel />
+  </Suspense>
+);
+
+const CURRENT_USER_ID = 'default-user';
+
 // ── Styles ────────────────────────────────────────────────────────────────────
 
 const appStyle: React.CSSProperties = {
@@ -137,15 +147,34 @@ const App: React.FC = () => {
 
   useEffect(() => {
     const documentId = new URLSearchParams(window.location.search).get('documentId');
-    if (documentId) openDocumentPreview(documentId);
-  }, [openDocumentPreview]);
+    if (!documentId) return;
+
+    let disposed = false;
+    void getDocument(documentId, { includeBlocks: false })
+      .then(() => {
+        if (!disposed) openDocumentPreview(documentId);
+      })
+      .catch((error: unknown) => {
+        if (disposed) return;
+        const url = new URL(window.location.href);
+        url.searchParams.delete('documentId');
+        window.history.replaceState({}, '', `${url.pathname}${url.search}${url.hash}`);
+        closeDocumentPreview();
+        message.error(
+          isApiError(error) && error.status === 404
+            ? '文档不存在，已清理失效的文档链接'
+            : '文档加载失败，请稍后重试'
+        );
+      });
+
+    return () => {
+      disposed = true;
+    };
+  }, [openDocumentPreview, closeDocumentPreview]);
 
   // ── Session history drawer ────────────────────────────────────────────────
   const [sessionListOpen, setSessionListOpen] = useState(false);
 
-  // ── User ID (in a real app, this would come from auth context) ───────────
-  const currentUserId = 'default-user';
-
   /** Stable callback to close the session drawer */
   const handleCloseSessionList = useCallback(() => setSessionListOpen(false), []);
   /** Stable callback to open the session drawer */
@@ -159,19 +188,6 @@ const App: React.FC = () => {
   }, [closeDocumentPreview]);
 
   // ── Panels ────────────────────────────────────────────────────────────────
-  // Each panel is wrapped in <Suspense> so the lazy chunk loads independently.
-  // useMemo ensures the JSX elements are stable references and don't cause
-  // Suspense to remount unnecessarily on parent re-renders (Req 13.7).
-
-  const leftPanel = useMemo(() => {
-    // Always show chat panel on the left
-    return (
-      <Suspense fallback={<PanelFallback />}>
-        <ChatPanel />
-      </Suspense>
-    );
-  }, []);
-
   const rightPanel = useMemo(() => {
     // If a document is being previewed, show EditorPanel
     // Otherwise show ExportRecordList (default)
@@ -190,10 +206,10 @@ const App: React.FC = () => {
     // Default: show export records list
     return (
       <Suspense fallback={<PanelFallback />}>
-        <ExportRecordList userId={currentUserId} />
+        <ExportRecordList userId={CURRENT_USER_ID} />
       </Suspense>
     );
-  }, [previewDocumentId, previewDocumentName, handleCloseEditor, currentUserId]);
+  }, [previewDocumentId, previewDocumentName, handleCloseEditor]);
 
   // ── Session history drawer ────────────────────────────────────────────────
   const sessionListDrawer = sessionListOpen ? (

src/components/ChatPanel/MessageItem.tsx

@@ -15,7 +15,7 @@ import { Typography, Card, message as antdMessage, Spin } from 'antd';
 import { FileTextOutlined, DownloadOutlined, LoadingOutlined } from '@ant-design/icons';
 import { formatDate } from '../../utils/formatDate';
 import type { ChatMessage } from '../../types/chat';
-import { useDocumentStore } from '../../stores/documentStore';
+import { createDocument } from '../../services/documentService';
 import { useChatStore } from '../../stores/chatStore';
 import { downloadBlob, getFileNameFromContentDisposition } from '../../utils/download';
 
@@ -217,7 +217,6 @@ const MessageItem: React.FC<MessageItemProps> = memo(
   ({ message, onPreviewDocument, className }) => {
     const { role, content, timestamp, exportRecord } = message;
     const [isCreatingDocument, setIsCreatingDocument] = useState(false);
-    const createDocument = useDocumentStore((state) => state.createDocument);
     const currentSessionId = useChatStore((state) => state.currentSessionId);
 
     /**
@@ -246,7 +245,9 @@ const MessageItem: React.FC<MessageItemProps> = memo(
         if (cachedDocId) {
           // Step 2: Verify cached document still exists
           try {
-            await apiClient.get(`/api/v1/documents/${cachedDocId}`);
+            await apiClient.get(`/api/v1/documents/${cachedDocId}`, {
+              skipErrorNotification: true,
+            });
             // Document exists, reuse it
             documentId = cachedDocId;
           } catch (error) {
@@ -291,7 +292,7 @@ const MessageItem: React.FC<MessageItemProps> = memo(
       } finally {
         setIsCreatingDocument(false);
       }
-    }, [exportRecord, onPreviewDocument, isCreatingDocument, createDocument, currentSessionId]);
+    }, [exportRecord, onPreviewDocument, isCreatingDocument, currentSessionId]);
 
     /**
      * Handle download document click

src/components/Editor/BlockCanvas.tsx

@@ -52,16 +52,10 @@ export const BlockCanvas = React.memo(function BlockCanvas({
     const sorted = [...blocks].sort((a, b) => a.block_order - b.block_order);
     let tocFound = false;
     let headingIndex = -1;
-
-    sorted.forEach((block, index) => {
-      if (block.type === 'toc') tocFound = true;
-      if (headingIndex === -1 && block.type === 'heading') {
-        headingIndex = index;
-      }
-    });
-
     const collapsible = new Set<string>();
     sorted.forEach((block, index) => {
+      if (block.type === 'toc') tocFound = true;
+      if (headingIndex === -1 && block.type === 'heading') headingIndex = index;
       if (block.type !== 'heading') return;
 
       const nextBlock = sorted[index + 1];

src/components/Editor/BlockEditor.tsx

@@ -11,10 +11,10 @@ import React, { useEffect, useCallback } from 'react';
 import { Spin, message } from 'antd';
 import { useShallow } from 'zustand/react/shallow';
 import { useEditorStore } from '../../stores/editorStore';
-import { BLOCK_DELETED_EVENT, BLOCK_UPDATED_EVENT } from '../../services/blockService';
+import { BLOCK_CREATED_EVENT, BLOCK_DELETED_EVENT, BLOCK_UPDATED_EVENT } from '../../services/blockService';
 import { BlockCanvas } from './BlockCanvas';
 import { MainToolbar } from './toolbar/MainToolbar';
-import type { BlockUpdate } from '../../types/editor';
+import type { BlockUpdate, DocumentBlock } from '../../types/editor';
 import './BlockEditor.css';
 
 // ══════════════════════════════════════════════════════════════════════════════
@@ -90,6 +90,17 @@ export const BlockEditor: React.FC<BlockEditorProps> = ({
 
   // 接收聊天/WebMCP 已保存的块更新，立即同步当前打开的文档。
   useEffect(() => {
+    const handleBlockCreated = (event: Event) => {
+      const detail = (event as CustomEvent<{ documentId?: unknown; block?: unknown }>).detail;
+      if (detail?.documentId !== documentId || !detail.block || typeof detail.block !== 'object') return;
+      useEditorStore.getState().applyRemoteBlockInsert(detail.block as DocumentBlock);
+    };
+
+    window.addEventListener(BLOCK_CREATED_EVENT, handleBlockCreated);
+    return () => window.removeEventListener(BLOCK_CREATED_EVENT, handleBlockCreated);
+  }, [documentId]);
+
+  useEffect(() => {
     const handleBlockUpdated = (event: Event) => {
       const detail = (event as CustomEvent<{
         documentId?: unknown;

src/components/Editor/DocumentOutline.tsx

@@ -109,22 +109,23 @@ export const DocumentOutline: React.FC<DocumentOutlineProps> = ({ visible = true
   const headings = useEditorStore(
     useShallow((state) => {
       const seenIds = new Set<string>();
-      return state.blocks
-        .filter(
-          (block): block is HeadingBlock =>
-            block.type === 'heading' &&
-            typeof block.id === 'string' &&
-            block.id.length > 0 &&
-            Number.isInteger(block.level) &&
-            block.level >= 1 &&
-            block.level <= 6
-        )
-        .sort((left, right) => left.block_order - right.block_order)
-        .filter((heading) => {
-          if (seenIds.has(heading.id)) return false;
-          seenIds.add(heading.id);
-          return true;
-        });
+      const result: HeadingBlock[] = [];
+      for (const block of state.blocks) {
+        if (
+          block.type !== 'heading' ||
+          typeof block.id !== 'string' ||
+          block.id.length === 0 ||
+          !Number.isInteger(block.level) ||
+          block.level < 1 ||
+          block.level > 6 ||
+          seenIds.has(block.id)
+        ) {
+          continue;
+        }
+        seenIds.add(block.id);
+        result.push(block);
+      }
+      return result.sort((left, right) => left.block_order - right.block_order);
     })
   );
   const selectedBlockId = useEditorStore((state) => state.selectedBlockId);

src/components/ExportRecordList/ExportRecordList.tsx

@@ -106,15 +106,18 @@ const ExportRecordList: React.FC<ExportRecordListProps> = ({
 
   // Fetch records on mount and when page changes
   useEffect(() => {
+    let disposed = false;
     const refresh = () => {
+      if (disposed) return;
       setLoading(true);
       void fetchRecords();
     };
 
     window.addEventListener(EXPORT_RECORD_CREATED_EVENT, refresh);
-    void fetchRecords();
+    queueMicrotask(refresh);
 
     return () => {
+      disposed = true;
       window.removeEventListener(EXPORT_RECORD_CREATED_EVENT, refresh);
     };
   }, [fetchRecords]);

src/services/api.ts

@@ -17,6 +17,12 @@ import type { AxiosInstance, InternalAxiosRequestConfig, AxiosResponse } from 'a
 import type { ApiResponse } from '../types/api';
 import { message } from 'antd';
 
+declare module 'axios' {
+  interface AxiosRequestConfig {
+    skipErrorNotification?: boolean;
+  }
+}
+
 /**
  * Normalized API error structure
  */

src/services/blockService.ts

@@ -31,6 +31,7 @@ const BLOCKS_BASE_URL = '/api/v1/documents';
 
 export const BLOCK_UPDATED_EVENT = 'ax:block-updated';
 export const BLOCK_DELETED_EVENT = 'ax:block-deleted';
+export const BLOCK_CREATED_EVENT = 'ax:block-created';
 
 function encodeResourceId(value: string, name: string): string {
   const hasUnsafeCharacter = Array.from(value).some((character) => {

src/services/documentService.ts

@@ -26,6 +26,34 @@ import type {
   GetDocumentOptions,
 } from '../types/document';
 
+const encodeResourceId = (value: string, name: string): string => {
+  const hasUnsafeCharacter = Array.from(value).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint < 32 || codePoint === 127 || character === '/' || character === '\\';
+  });
+  if (!value || value.length > 128 || hasUnsafeCharacter) {
+    throw new Error(`无效的${name}`);
+  }
+  return encodeURIComponent(value);
+};
+
+const normalizeExportDownloadUrl = (fileUrl: string): string => {
+  const configuredBaseUrl = import.meta.env.VITE_API_BASE_URL;
+  if (!configuredBaseUrl || !fileUrl) return fileUrl;
+
+  try {
+    const configuredUrl = new URL(configuredBaseUrl);
+    const exportUrl = new URL(fileUrl, configuredUrl);
+    if (!exportUrl.pathname.startsWith('/api/v1/export/records/')) return fileUrl;
+
+    exportUrl.protocol = configuredUrl.protocol;
+    exportUrl.host = configuredUrl.host;
+    return exportUrl.toString();
+  } catch {
+    return fileUrl;
+  }
+};
+
 /**
  * Create a new document from a Word file URL
  *
@@ -40,9 +68,14 @@ export const createDocument = async (
   request: CreateDocumentRequest
 ): Promise<CreateDocumentResponse> => {
   try {
+    const normalizedRequest = {
+      ...request,
+      fileUrl: normalizeExportDownloadUrl(request.fileUrl),
+    };
     const response = await apiClient.post<ApiResponse<CreateDocumentResponse>>(
       '/api/v1/documents',
-      request
+      normalizedRequest,
+      { skipErrorNotification: true }
     );
     return response.data.data;
   } catch (error: unknown) {
@@ -79,9 +112,12 @@ export const getDocument = async (
       params.includeBlocks = true;
     }
 
-    const response = await apiClient.get<ApiResponse<Document>>(`/api/v1/documents/${documentId}`, {
-      params,
-    });
+    const response = await apiClient.get<ApiResponse<Document>>(
+      `/api/v1/documents/${encodeResourceId(documentId, '文档 ID')}`,
+      {
+        params,
+      }
+    );
     return response.data.data;
   } catch (error: unknown) {
     let friendlyMessage = '获取文档失败';
@@ -107,7 +143,9 @@ export const getDocument = async (
  */
 export const deleteDocuments = async (sessionId: string): Promise<string> => {
   try {
-    const response = await apiClient.delete<ApiResponse<void>>(`/api/v1/documents/${sessionId}`);
+    const response = await apiClient.delete<ApiResponse<void>>(
+      `/api/v1/documents/${encodeResourceId(sessionId, '会话 ID')}`
+    );
 
     const message = response.data.message || 'Documents deleted successfully';
     return message;

src/services/webMcpService.ts

@@ -6,7 +6,7 @@ import type { BlockType, CreateBlockRequest, UpdateBlockRequest } from '../types
 import type { DocumentListFilters } from '../types/document';
 import { useUIStore } from '../stores/uiStore';
 import { finishWebMcpActivity, startWebMcpActivity } from './webMcpActivityService';
-import { BLOCK_DELETED_EVENT, BLOCK_UPDATED_EVENT } from './blockService';
+import { BLOCK_CREATED_EVENT, BLOCK_DELETED_EVENT, BLOCK_UPDATED_EVENT } from './blockService';
 
 export interface WebMcpToolResult {
 	ok: boolean;
@@ -81,6 +81,20 @@ const requiredString = (input: Record<string, unknown>, key: string): string =>
 	return value.trim();
 };
 
+const requiredContent = (input: Record<string, unknown>, key: string): string | object | unknown[] => {
+	const value = input[key];
+	if (typeof value === 'string') {
+		if (!value.trim()) throw new Error(`${key} 不能为空`);
+		if (value.length > 200_000) throw new Error(`${key} 长度过长`);
+		return value;
+	}
+	if (Array.isArray(value) || isRecord(value)) {
+		if (JSON.stringify(value).length > 200_000) throw new Error(`${key} 内容过大`);
+		return value;
+	}
+	throw new Error(`${key} 必须是字符串、对象或数组`);
+};
+
 const optionalString = (input: Record<string, unknown>, key: string): string | undefined => {
 	const value = input[key];
 	if (value === undefined || value === null || value === '') return undefined;
@@ -252,20 +266,34 @@ const tools: WebMcpTool[] = [
 				documentId: documentIdProperty,
 				type: { type: 'string', enum: ['heading', 'paragraph', 'table', 'image', 'toc'] },
 				content: { type: 'string', description: '块内容', maxLength: 200000 },
-				level: { type: 'number', minimum: 1, maximum: 6 },
+				level: { type: 'number', minimum: 0, maximum: 6 },
 				afterBlockId: { type: 'string', description: '插入到此块之后，可选' },
+				clientBlockId: { type: 'string', description: '可选，客户端幂等块 ID' },
 			},
 			['documentId', 'type', 'content']
 		),
-		execute: (input) => run(() => {
+		execute: (input) => run(async () => {
 			const type = requiredString(input, 'type') as BlockType;
-			const request: CreateBlockRequest = {
+			const level = input.level === undefined ? 0 : numberOr(input, 'level', 0);
+			if (type === 'heading' && (level < 1 || level > 6)) {
+				throw new Error('heading 的 level 必须是 1-6');
+			}
+			if (type !== 'heading' && level !== 0) {
+				throw new Error('非 heading 块的 level 必须是 0');
+			}
+			const documentId = requiredString(input, 'documentId');
+			const response = await blockService.createBlock(documentId, {
 				type,
-				content: requiredString(input, 'content'),
-				level: input.level === undefined ? undefined : numberOr(input, 'level', 0),
+				content: requiredContent(input, 'content') as CreateBlockRequest['content'],
+				level,
 				after_block_id: optionalString(input, 'afterBlockId'),
-			};
-			return blockService.createBlock(requiredString(input, 'documentId'), request);
+				client_block_id: optionalString(input, 'clientBlockId'),
+			});
+			const created = await blockService.getBlock(documentId, response.blockId);
+			window.dispatchEvent(new CustomEvent(BLOCK_CREATED_EVENT, {
+				detail: { documentId, block: created.block },
+			}));
+			return { ...response, block: created.block, message: 'Block created successfully' };
 		}),
 	},
 	{

src/services/workflowService.ts

@@ -85,6 +85,26 @@ const getWorkflowConfig = (): WorkflowConfig => {
   };
 };
 
+/** Normalize workflow-generated export URLs to the configured backend origin. */
+const normalizeExportDownloadUrl = (downloadUrl: string): string => {
+  const configuredBaseUrl = import.meta.env.VITE_API_BASE_URL;
+  if (!configuredBaseUrl || !downloadUrl) return downloadUrl;
+
+  try {
+    const configuredUrl = new URL(configuredBaseUrl);
+    const exportUrl = new URL(downloadUrl, configuredUrl);
+    if (exportUrl.pathname.startsWith('/api/v1/export/records/')) {
+      exportUrl.protocol = configuredUrl.protocol;
+      exportUrl.host = configuredUrl.host;
+      return exportUrl.toString();
+    }
+  } catch {
+    // Keep the original value so the caller can report an invalid URL.
+  }
+
+  return downloadUrl;
+};
+
 /**
  * Check if user input should trigger document generation workflow
  *
@@ -272,6 +292,10 @@ export const triggerDocumentWorkflow = async (
       content = '✅ 文档已生成，点击下方卡片预览或下载';
     }
 
+    if (exportRecord?.downloadUrl) {
+      exportRecord.downloadUrl = normalizeExportDownloadUrl(exportRecord.downloadUrl);
+    }
+
     return {
       content,
       exportRecord,

src/stores/chatStore.ts

@@ -35,6 +35,7 @@ import {
 // ── Constants ──────────────────────────────────────────────────────────────
 
 const STORAGE_KEY = 'ax-chat-sessions';
+const ACTIVE_SESSION_STORAGE_KEY = 'ax-active-session-id';
 const MAX_SESSIONS = 50; // Maximum number of sessions to keep
 const MAX_MESSAGES_PER_SESSION = 200;
 const STORAGE_WRITE_DELAY = 150;
@@ -104,6 +105,27 @@ const loadSessionsFromStorage = (): ChatSession[] => {
   }
 };
 
+const getActiveSession = (sessions: ChatSession[]): ChatSession | undefined => {
+  try {
+    const activeSessionId = localStorage.getItem(ACTIVE_SESSION_STORAGE_KEY);
+    return sessions.find((session) => session.id === activeSessionId) || sessions[0];
+  } catch {
+    return sessions[0];
+  }
+};
+
+const persistActiveSession = (sessionId: string | null): void => {
+  try {
+    if (sessionId) {
+      localStorage.setItem(ACTIVE_SESSION_STORAGE_KEY, sessionId);
+    } else {
+      localStorage.removeItem(ACTIVE_SESSION_STORAGE_KEY);
+    }
+  } catch (error) {
+    console.warn('保存当前会话失败', error);
+  }
+};
+
 /**
  * Save sessions to localStorage
  */
@@ -240,9 +262,16 @@ const getAIResponse = async (
  */
 export const useChatStore = create<ChatStoreState>((set, get) => ({
   // ============ State ============
-  currentSessionId: null,
-  sessions: loadSessionsFromStorage(),
-  messages: [],
+  ...(() => {
+    const sessions = loadSessionsFromStorage();
+    const activeSession = getActiveSession(sessions);
+    persistActiveSession(activeSession?.id ?? null);
+    return {
+      currentSessionId: activeSession?.id ?? null,
+      sessions,
+      messages: activeSession?.messages ?? [],
+    };
+  })(),
   isLoading: false,
 
   // ============ Actions ============
@@ -268,6 +297,7 @@ export const useChatStore = create<ChatStoreState>((set, get) => ({
     set((state) => {
       const updatedSessions = [newSession, ...state.sessions];
       saveSessionsToStorage(updatedSessions);
+      persistActiveSession(sessionId);
 
       return {
         currentSessionId: sessionId,
@@ -296,6 +326,7 @@ export const useChatStore = create<ChatStoreState>((set, get) => ({
       currentSessionId: sessionId,
       messages: session.messages,
     });
+    persistActiveSession(sessionId);
   },
 
   /**
@@ -318,6 +349,9 @@ export const useChatStore = create<ChatStoreState>((set, get) => ({
       saveSessionsToStorage(updatedSessions);
       const newCurrentSessionId =
         state.currentSessionId === sessionId ? null : state.currentSessionId;
+      if (newCurrentSessionId === null) {
+        persistActiveSession(null);
+      }
 
       return {
         currentSessionId: newCurrentSessionId,
@@ -414,8 +448,11 @@ export const useChatStore = create<ChatStoreState>((set, get) => ({
       let aiResponse: string;
       let exportRecord: ExportRecordInfo | undefined;
 
-      // 先尝试匹配聊天中的 WebMCP 命令。未匹配时保持原有 AI 和文档工作流。
-      const webMcpResult = await executeWebMcpChatCommand(content);
+      // 文档生成请求必须直接进入工作流，避免被 WebMCP 转译成导出等工具操作。
+      const workflowRequest = shouldTriggerWorkflow(content);
+      const webMcpResult = workflowRequest
+        ? { handled: false as const }
+        : await executeWebMcpChatCommand(content);
       if (webMcpResult.handled) {
         if (webMcpResult.requiresConfirmation) {
           const confirmed = await confirmWebMcpCommand(webMcpResult.response || '请确认此操作');
@@ -428,7 +465,7 @@ export const useChatStore = create<ChatStoreState>((set, get) => ({
         } else {
           aiResponse = webMcpResult.response || 'WebMCP 操作已完成。';
         }
-      } else if (shouldTriggerWorkflow(content)) {
+      } else if (workflowRequest) {
         // Use workflow for document generation
         // ⭐ 重要: 传递 sessionId 确保生成的文档与当前会话关联
         // 在同一个会话中生成多个文档时:

src/stores/editorStore.ts

@@ -12,7 +12,6 @@
 
 import { create } from 'zustand';
 import pLimit from 'p-limit';
-import hashSum from 'hash-sum';
 import { v4 as uuidv4 } from 'uuid';
 import { message } from 'antd';
 import type {
@@ -23,12 +22,21 @@ import type {
   TableBlock,
 } from '../types/editor';
 import { blockService } from '../services/blockService';
-import { getErrorMessage } from '../services/api';
+import { getErrorMessage, isApiError } from '../services/api';
+import { normalizeTableBlock, validateTableStructure } from '../utils/blockOperations';
 import {
-  normalizeTableBlock,
-  serializeTableBlock,
-  validateTableStructure,
-} from '../utils/blockOperations';
+  computeBlockHash,
+  computeInsertOrder,
+  isCanceledRequest,
+  isReadonlyBlock,
+  mergeBlockUpdates,
+  rebalanceOrders,
+  serializeBlockForSave,
+  serializePendingBlockUpdate,
+  snapshotBlocks,
+  waitForStructuralOperations,
+} from '../utils/editorStoreHelpers';
+import type { EditorHistoryEntry, EditorStore } from './editorStoreTypes';
 
 // 并发保存限制器（最多同时进行 3 个请求，降低服务器压力）
 const saveConcurrencyLimit = pLimit(3);
@@ -42,347 +50,6 @@ const MAX_RETRY_ATTEMPTS = 3;
 const MAX_HISTORY_ENTRIES = 100;
 const HISTORY_COALESCE_WINDOW = 500;
 
-function waitForStructuralOperations(isReady: () => boolean): Promise<void> {
-  return new Promise((resolve) => {
-    const check = () => {
-      if (isReady()) {
-        resolve();
-        return;
-      }
-      setTimeout(check, 16);
-    };
-    check();
-  });
-}
-
-interface EditorHistoryEntry {
-  blocks: DocumentBlock[];
-  selectedBlockId: string | null;
-}
-
-function snapshotBlocks(blocks: DocumentBlock[]): DocumentBlock[] {
-  // 块更新采用不可变替换，历史快照只需复制数组即可复用块对象。
-  return blocks.slice();
-}
-
-/**
- * 计算块内容的哈希值
- * 用于检测内容是否真的发生了变化
- */
-function computeBlockHash(block: DocumentBlock): string {
-  // 只计算可编辑字段的哈希，忽略 id 等不可变元数据
-  const contentForHash = {
-    type: block.type,
-    content: block.content,
-    style: block.style,
-    word_style: block.word_style,
-    level: block.level,
-    block_order: block.block_order,
-  };
-  return hashSum(contentForHash);
-}
-
-function isReadonlyBlock(block: DocumentBlock): boolean {
-  const metadata: object = block.metadata;
-  return (
-    ('readonly' in metadata && metadata.readonly === true) ||
-    ('is_auto_generated' in metadata && metadata.is_auto_generated === true)
-  );
-}
-
-function isCanceledRequest(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    (error.name === 'AbortError' ||
-      error.name === 'CanceledError' ||
-      error.message.toLowerCase().includes('cancel'))
-  );
-}
-
-function serializeBlockForSave(block: DocumentBlock): Pick<BlockUpdate, 'content' | 'style'> {
-  if (block.type === 'table') {
-    const serializedTable = serializeTableBlock(block as TableBlock);
-    return {
-      content: serializedTable.content,
-      style: block.style,
-    };
-  }
-
-  if ((block.type === 'heading' || block.type === 'paragraph') && Array.isArray(block.content)) {
-    const firstStyle = block.content[0]?.style;
-    const allSameStyle =
-      !!firstStyle &&
-      block.content.every(
-        (segment) => JSON.stringify(segment.style) === JSON.stringify(firstStyle)
-      );
-
-    return {
-      content: block.content.map((segment) => segment.text).join(''),
-      style:
-        allSameStyle && Object.keys(firstStyle).length > 0
-          ? { ...block.style, ...firstStyle }
-          : block.style,
-    };
-  }
-
-  return {
-    content: block.content,
-    style: block.style,
-  };
-}
-
-function mergeBlockUpdates(previous: BlockUpdate | undefined, next: BlockUpdate): BlockUpdate {
-  return { ...(previous || {}), ...next };
-}
-
-function serializePendingBlockUpdate(
-  block: DocumentBlock,
-  pending: BlockUpdate | undefined
-): BlockUpdate {
-  if (!pending) {
-    const serialized = serializeBlockForSave(block);
-    return {
-      type: block.type,
-      level: block.level,
-      content: serialized.content,
-      style: serialized.style,
-      word_style: block.word_style,
-      metadata: block.metadata,
-      block_order: block.block_order,
-    };
-  }
-  const updates = pending || {};
-  const serialized = serializeBlockForSave(block);
-  const payload: BlockUpdate = {};
-
-  if ('type' in updates) payload.type = block.type;
-  if ('level' in updates) payload.level = block.level;
-  if ('content' in updates) payload.content = serialized.content;
-  if ('style' in updates) payload.style = serialized.style;
-  if ('word_style' in updates) payload.word_style = block.word_style;
-  if ('metadata' in updates) payload.metadata = block.metadata;
-  if ('block_order' in updates) payload.block_order = block.block_order;
-
-  return payload;
-}
-
-// ══════════════════════════════════════════════════════════════════════════════
-// Store State Interface
-// ══════════════════════════════════════════════════════════════════════════════
-
-interface EditorStore {
-  // ── 文档状态 ────────────────────────────────────────────────────────────
-  documentId: string | null;
-  documentTitle: string;
-  blocks: DocumentBlock[];
-  selectedBlockId: string | null;
-  focusRequestId: number;
-  past: EditorHistoryEntry[];
-  future: EditorHistoryEntry[];
-  lastHistoryEditBlockId: string | null;
-  lastHistoryEditAt: number | null;
-  isHistoryApplying: boolean;
-  pendingStructuralOperations: number;
-
-  // ── 加载/保存状态 ──────────────────────────────────────────────────────
-  isLoading: boolean;
-  isSaving: boolean;
-  error: string | null;
-
-  // ── 保存进度 ────────────────────────────────────────────────────────────
-  /** 正在保存的块数量 */
-  savingProgress: { current: number; total: number } | null;
-
-  // ── 修改状态追踪 ────────────────────────────────────────────────────────
-  /** 文档是否已被修改(用于控制保存按钮状态) */
-  hasModified: boolean;
-  /** 原始blocks快照(用于检测变化) */
-  originalBlocksSnapshot: string | null;
-  /** 保存失败的块ID列表 */
-  failedBlocks: string[];
-  /** 被修改但未保存的块ID集合 */
-  dirtyBlocks: Set<string>;
-  /** 上次成功保存的快照 */
-  lastSavedSnapshot: string | null;
-  /** 块内容哈希映射表（用于精确检测内容变化）*/
-  blockHashes: Map<string, string>;
-  /** 每个块尚未提交的字段变更，只在保存时转换为 API patch */
-  pendingBlockUpdates: Map<string, BlockUpdate>;
-
-  // ── 保存控制 ────────────────────────────────────────────────────────────
-  /** 当前正在进行的保存 Promise */
-  currentSavePromise: Promise<void> | null;
-  /** 用于取消请求的 AbortController */
-  saveAbortController: AbortController | null;
-  /** 用于取消文档加载请求的 AbortController */
-  loadAbortController: AbortController | null;
-
-  // ── 自动保存 ────────────────────────────────────────────────────────────
-  /** 自动保存定时器 */
-  autoSaveTimer: ReturnType<typeof setTimeout> | null;
-  /** 是否启用自动保存 */
-  autoSaveEnabled: boolean;
-  /** 上次保存时间戳 */
-  lastSaveTime: number | null;
-
-  // ── 重试机制 ────────────────────────────────────────────────────────────
-  /** 块重试次数记录 */
-  retryAttempts: Map<string, number>;
-  /** 延迟重试定时器 */
-  retryTimer: ReturnType<typeof setTimeout> | null;
-
-  // ── 操作方法 ────────────────────────────────────────────────────────────
-
-  /**
-   * 加载文档
-   */
-  loadDocument: (documentId: string) => Promise<void>;
-
-  /**
-   * 保存文档
-   */
-  saveDocument: () => Promise<void>;
-
-  /**
-   * 重试保存失败的块
-   */
-  retryFailedBlocks: () => Promise<void>;
-
-  /**
-   * 添加块
-   * @param block 块数据(部分字段)
-   * @param afterBlockId 插入位置(在此块之后),不传则追加到末尾
-   */
-  addBlock: (block: PartialBlock, afterBlockId?: string) => void;
-
-  /**
-   * 更新块
-   * @param id 块ID
-   * @param updates 更新数据
-   */
-  updateBlock: (id: string, updates: BlockUpdate) => void;
-
-  /** 应用来自聊天/WebMCP 的已保存块更新 */
-  applyRemoteBlockUpdate: (id: string, updates: BlockUpdate) => void;
-
-  /** 应用来自聊天/WebMCP 的已保存块删除 */
-  applyRemoteBlockDelete: (id: string) => void;
-
-  /**
-   * 标记文档已修改
-   */
-  markAsModified: () => void;
-
-  /**
-   * 标记文档已保存
-   */
-  markAsSaved: () => void;
-
-  /**
-   * 删除块
-   * @param id 块ID
-   */
-  deleteBlock: (id: string) => Promise<void>;
-
-  /**
-   * 移动块
-   * @param id 块ID
-   * @param targetOrder 目标位置
-   */
-  moveBlock: (id: string, targetOrder: number) => void;
-
-  /**
-   * 选中块
-   * @param id 块ID
-   */
-  selectBlock: (id: string | null) => void;
-
-  /**
-   * 根据ID获取块
-   */
-  getBlockById: (id: string) => DocumentBlock | undefined;
-
-  /**
-   * 根据类型获取块
-   */
-  getBlocksByType: (type: BlockType) => DocumentBlock[];
-
-  /**
-   * 检查块是否为脏块（已修改未保存）
-   */
-  isBlockDirty: (id: string) => boolean;
-
-  /**
-   * 获取所有脏块
-   */
-  getDirtyBlocks: () => DocumentBlock[];
-
-  /**
-   * 保存单个block的更改
-   */
-  saveBlock: (id: string) => Promise<void>;
-
-  /**
-   * 重新计算所有块的block_order(稀疏排序)
-   */
-  recomputeBlockOrders: () => void;
-
-  /**
-   * 启用/禁用自动保存
-   */
-  setAutoSaveEnabled: (enabled: boolean) => void;
-
-  /**
-   * 触发自动保存（带防抖）
-   */
-  triggerAutoSave: () => void;
-
-  /**
-   * 取消自动保存定时器
-   */
-  cancelAutoSave: () => void;
-
-  /**
-   * 重置状态
-   */
-  reset: () => void;
-  /** 撤销最近一次编辑 */
-  undo: () => Promise<void>;
-  /** 重做最近一次撤销 */
-  redo: () => Promise<void>;
-}
-
-// ══════════════════════════════════════════════════════════════════════════════
-// Utility Functions
-// ══════════════════════════════════════════════════════════════════════════════
-
-/**
- * 计算插入位置的block_order
- * 稀疏排序策略:在两个块之间找到中间值
- */
-function computeInsertOrder(prevOrder: number, nextOrder: number): number {
-  const gap = nextOrder - prevOrder;
-
-  if (gap > 1) {
-    // 有间隙,直接取中间值
-    return Math.floor((prevOrder + nextOrder) / 2);
-  }
-
-  // 间隙不足,需要重排
-  return -1;
-}
-
-/**
- * 重新平衡block_order(稀疏排序,间隔100)
- */
-function rebalanceOrders(blocks: DocumentBlock[]): DocumentBlock[] {
-  const sorted = [...blocks].sort((a, b) => a.block_order - b.block_order);
-  return sorted.map((block, index) => ({
-    ...block,
-    block_order: index * 100,
-  }));
-}
-
 // ══════════════════════════════════════════════════════════════════════════════
 // Store Implementation
 // ══════════════════════════════════════════════════════════════════════════════
@@ -612,7 +279,10 @@ export const useEditorStore = create<EditorStore>((set, get) => {
         });
       } catch (error: unknown) {
         if (controller.signal.aborted || isCanceledRequest(error)) return;
+        const documentMissing = isApiError(error) && error.status === 404;
         set({
+          documentId: documentMissing ? null : documentId,
+          blocks: documentMissing ? [] : get().blocks,
           error: getErrorMessage(error) || '加载文档失败',
           isLoading: false,
           loadAbortController: null,
@@ -649,14 +319,14 @@ export const useEditorStore = create<EditorStore>((set, get) => {
         return;
       }
 
-      const dirtyBlocks = new Set(
-        blocks
-          .filter(
-            (block) =>
-              currentDirtyBlocks.has(block.id) && block.type !== 'toc' && !isReadonlyBlock(block)
-          )
-          .map((block) => block.id)
-      );
+      const dirtyBlocks = new Set<string>();
+      const blocksToSave: DocumentBlock[] = [];
+      for (const block of blocks) {
+        if (currentDirtyBlocks.has(block.id) && block.type !== 'toc' && !isReadonlyBlock(block)) {
+          dirtyBlocks.add(block.id);
+          blocksToSave.push(block);
+        }
+      }
 
       if (dirtyBlocks.size === 0) {
         set({
@@ -697,15 +367,6 @@ export const useEditorStore = create<EditorStore>((set, get) => {
       // 创建保存 Promise
       const savePromise = (async () => {
         try {
-          // 获取需要保存的块（只保存脏块）
-          const blocksToSave = blocks.filter((block) => {
-            // 必须在脏块列表中
-            if (!dirtyBlocks.has(block.id)) {
-              return false;
-            }
-
-            return true;
-          });
           const pendingUpdatesAtSave = new Map(currentPendingBlockUpdates);
 
           const totalBlocks = blocksToSave.length;
@@ -728,12 +389,9 @@ export const useEditorStore = create<EditorStore>((set, get) => {
               );
 
               try {
-                const result = await blockService.updateBlock(
-                  documentId,
-                  block.id,
-                  payload,
-                  { signal: newAbortController.signal }
-                );
+                const result = await blockService.updateBlock(documentId, block.id, payload, {
+                  signal: newAbortController.signal,
+                });
                 if (newAbortController.signal.aborted || get().documentId !== documentId) {
                   return result;
                 }
@@ -788,11 +446,17 @@ export const useEditorStore = create<EditorStore>((set, get) => {
             // 更新成功保存的块的哈希值
             const newBlockHashes = new Map(latestStateBeforeResult.blockHashes);
             const newPendingBlockUpdates = new Map(latestStateBeforeResult.pendingBlockUpdates);
+            const savedBlocksById = new Map(blocks.map((block) => [block.id, block]));
+            const latestBlocksById = new Map(
+              latestStateBeforeResult.blocks.map((block) => [block.id, block])
+            );
             successIds.forEach((id) => {
-              const block = blocks.find((b) => b.id === id);
-              const latestBlock = latestStateBeforeResult.blocks.find((b) => b.id === id);
-              if (block && latestBlock && computeBlockHash(block) === computeBlockHash(latestBlock)) {
-                newBlockHashes.set(id, computeBlockHash(block));
+              const block = savedBlocksById.get(id);
+              const latestBlock = latestBlocksById.get(id);
+              if (!block || !latestBlock) return;
+              const savedHash = computeBlockHash(block);
+              if (savedHash === computeBlockHash(latestBlock)) {
+                newBlockHashes.set(id, savedHash);
                 newPendingBlockUpdates.delete(id);
               }
             });
@@ -837,9 +501,11 @@ export const useEditorStore = create<EditorStore>((set, get) => {
             const newDirtyBlocks = new Set(latestState.dirtyBlocks);
             const newBlockHashes = new Map(latestState.blockHashes);
             const newPendingBlockUpdates = new Map(latestState.pendingBlockUpdates);
+            const savedBlocksById = new Map(blocks.map((block) => [block.id, block]));
+            const latestBlocksById = new Map(latestState.blocks.map((block) => [block.id, block]));
             successIds.forEach((id) => {
-              const savedBlock = blocks.find((block) => block.id === id);
-              const latestBlock = latestState.blocks.find((block) => block.id === id);
+              const savedBlock = savedBlocksById.get(id);
+              const latestBlock = latestBlocksById.get(id);
               if (!savedBlock || !latestBlock) return;
 
               const savedHash = computeBlockHash(savedBlock);
@@ -942,7 +608,8 @@ export const useEditorStore = create<EditorStore>((set, get) => {
       const savePromise = (async () => {
         try {
           // 获取失败的块
-          const blocksToRetry = blocks.filter((block) => failedBlocks.includes(block.id));
+          const failedBlockIds = new Set(failedBlocks);
+          const blocksToRetry = blocks.filter((block) => failedBlockIds.has(block.id));
           const savedHashes = new Map(
             blocksToRetry.map((block) => [block.id, computeBlockHash(block)])
           );
@@ -1000,8 +667,9 @@ export const useEditorStore = create<EditorStore>((set, get) => {
           const latestState = get();
           const newDirtyBlocks = new Set(latestState.dirtyBlocks);
           const newBlockHashes = new Map(latestState.blockHashes);
+          const latestBlocksById = new Map(latestState.blocks.map((block) => [block.id, block]));
           successIds.forEach((id) => {
-            const latestBlock = latestState.blocks.find((block) => block.id === id);
+            const latestBlock = latestBlocksById.get(id);
             const savedHash = savedHashes.get(id);
             if (latestBlock && savedHash === computeBlockHash(latestBlock)) {
               newDirtyBlocks.delete(id);
@@ -1257,10 +925,7 @@ export const useEditorStore = create<EditorStore>((set, get) => {
       if (originalHash && newHash === originalHash) {
         newPendingBlockUpdates.delete(id);
       } else {
-        newPendingBlockUpdates.set(
-          id,
-          mergeBlockUpdates(pendingBlockUpdates.get(id), updates)
-        );
+        newPendingBlockUpdates.set(id, mergeBlockUpdates(pendingBlockUpdates.get(id), updates));
       }
 
       set({
@@ -1307,6 +972,29 @@ export const useEditorStore = create<EditorStore>((set, get) => {
       });
     },
 
+    // ── applyRemoteBlockInsert ─────────────────────────────────────────────
+    applyRemoteBlockInsert: (block: DocumentBlock) => {
+      const { documentId, blocks, blockHashes, dirtyBlocks, pendingBlockUpdates } = get();
+      if (!documentId || blocks.some((currentBlock) => currentBlock.id === block.id)) return;
+
+      const updatedBlocks = [...blocks, block].sort(
+        (left, right) => left.block_order - right.block_order
+      );
+      const updatedHashes = new Map(blockHashes);
+      updatedHashes.set(block.id, computeBlockHash(block));
+      const snapshot = JSON.stringify(updatedBlocks);
+
+      set({
+        blocks: updatedBlocks,
+        blockHashes: updatedHashes,
+        dirtyBlocks,
+        pendingBlockUpdates,
+        hasModified: dirtyBlocks.size > 0,
+        originalBlocksSnapshot: snapshot,
+        lastSavedSnapshot: snapshot,
+      });
+    },
+
     // ── applyRemoteBlockDelete ─────────────────────────────────────────────
     applyRemoteBlockDelete: (id: string) => {
       const { documentId, blocks, blockHashes, dirtyBlocks, pendingBlockUpdates } = get();
@@ -1390,69 +1078,11 @@ export const useEditorStore = create<EditorStore>((set, get) => {
       });
 
       try {
-        // 1. 调用后端API删除块
+        // 稀疏 block_order 不需要因删除而重排，避免对剩余块逐个发起更新请求。
         await blockService.deleteBlock(documentId, id);
 
-        // 2. 删除成功后，重新计算并更新所有块的 block_order
-        // 按照当前顺序重新分配 block_order（使用稀疏排序，间隔100）
-        const sortedBlocks = [...newBlocks].sort((a, b) => a.block_order - b.block_order);
-        const blocksNeedUpdate: Array<{ block: DocumentBlock; newOrder: number }> = [];
-
-        sortedBlocks.forEach((block, index) => {
-          const expectedOrder = index * 100;
-          if (block.block_order !== expectedOrder) {
-            blocksNeedUpdate.push({
-              block,
-              newOrder: expectedOrder,
-            });
-          }
-        });
-
-        // 3. 如果有块需要更新顺序，批量调用 PUT API 更新
-        if (blocksNeedUpdate.length > 0) {
-          // 并发调用 PUT API 更新所有受影响块的顺序。
-          // 只发送顺序字段，避免用删除前的块快照覆盖并发编辑。
-          const updatePromises = blocksNeedUpdate.map(({ block, newOrder }) =>
-            blockService.updateBlock(documentId, block.id, {
-              block_order: newOrder,
-            })
-          );
-
-          await Promise.all(updatePromises);
-
-          // 4. 更新本地状态中的 block_order，并更新这些块的哈希值
-          const { blocks: currentBlocks, blockHashes: currentBlockHashes } = get();
-          const updatedBlocks = currentBlocks.map((b) => {
-            const update = blocksNeedUpdate.find((u) => u.block.id === b.id);
-            if (update) {
-              return { ...b, block_order: update.newOrder };
-            }
-            return b;
-          });
-
-          // 更新这些块的哈希值，因为后端已经保存了
-          const updatedBlockHashes = new Map(currentBlockHashes);
-          updatedBlocks.forEach((block) => {
-            if (blocksNeedUpdate.some((u) => u.block.id === block.id)) {
-              updatedBlockHashes.set(block.id, computeBlockHash(block));
-            }
-          });
-
-          // 5. 更新本地状态，不标记为已修改（因为后端已经同步）
-          const latestState = get();
-          set({
-            blocks: updatedBlocks,
-            blockHashes: updatedBlockHashes,
-            dirtyBlocks: latestState.dirtyBlocks,
-            hasModified: latestState.dirtyBlocks.size > 0,
-          });
-        } else {
-          // 没有块需要更新顺序（可能删除的是最后一个块）
-          const latestState = get();
-          set({
-            hasModified: latestState.dirtyBlocks.size > 0,
-          });
-        }
+        const latestState = get();
+        set({ hasModified: latestState.dirtyBlocks.size > 0 });
         pushHistory(blocks, get().selectedBlockId);
       } catch (error: unknown) {
         if (get().documentId !== documentId) {

src/stores/editorStoreTypes.ts

@@ -0,0 +1,70 @@
+import type { BlockType, BlockUpdate, DocumentBlock, PartialBlock } from '../types/editor';
+
+export interface EditorHistoryEntry {
+  blocks: DocumentBlock[];
+  selectedBlockId: string | null;
+}
+
+export interface EditorStore {
+  documentId: string | null;
+  documentTitle: string;
+  blocks: DocumentBlock[];
+  selectedBlockId: string | null;
+  focusRequestId: number;
+  past: EditorHistoryEntry[];
+  future: EditorHistoryEntry[];
+  lastHistoryEditBlockId: string | null;
+  lastHistoryEditAt: number | null;
+  isHistoryApplying: boolean;
+  pendingStructuralOperations: number;
+
+  isLoading: boolean;
+  isSaving: boolean;
+  error: string | null;
+  savingProgress: { current: number; total: number } | null;
+
+  hasModified: boolean;
+  originalBlocksSnapshot: string | null;
+  failedBlocks: string[];
+  dirtyBlocks: Set<string>;
+  lastSavedSnapshot: string | null;
+  blockHashes: Map<string, string>;
+  pendingBlockUpdates: Map<string, BlockUpdate>;
+
+  currentSavePromise: Promise<void> | null;
+  saveAbortController: AbortController | null;
+  loadAbortController: AbortController | null;
+
+  autoSaveTimer: ReturnType<typeof setTimeout> | null;
+  autoSaveEnabled: boolean;
+  lastSaveTime: number | null;
+
+  retryAttempts: Map<string, number>;
+  retryTimer: ReturnType<typeof setTimeout> | null;
+
+  loadDocument: (documentId: string) => Promise<void>;
+  saveDocument: () => Promise<void>;
+  retryFailedBlocks: () => Promise<void>;
+  addBlock: (block: PartialBlock, afterBlockId?: string) => void;
+  updateBlock: (id: string, updates: BlockUpdate) => void;
+  applyRemoteBlockUpdate: (id: string, updates: BlockUpdate) => void;
+  applyRemoteBlockInsert: (block: DocumentBlock) => void;
+  applyRemoteBlockDelete: (id: string) => void;
+  markAsModified: () => void;
+  markAsSaved: () => void;
+  deleteBlock: (id: string) => Promise<void>;
+  moveBlock: (id: string, targetOrder: number) => void;
+  selectBlock: (id: string | null) => void;
+  getBlockById: (id: string) => DocumentBlock | undefined;
+  getBlocksByType: (type: BlockType) => DocumentBlock[];
+  isBlockDirty: (id: string) => boolean;
+  getDirtyBlocks: () => DocumentBlock[];
+  saveBlock: (id: string) => Promise<void>;
+  recomputeBlockOrders: () => void;
+  setAutoSaveEnabled: (enabled: boolean) => void;
+  triggerAutoSave: () => void;
+  cancelAutoSave: () => void;
+  reset: () => void;
+  undo: () => Promise<void>;
+  redo: () => Promise<void>;
+}

src/utils/editorStoreHelpers.ts

@@ -0,0 +1,121 @@
+import hashSum from 'hash-sum';
+import type { BlockUpdate, DocumentBlock, TableBlock } from '../types/editor';
+import { serializeTableBlock } from './blockOperations';
+
+export function waitForStructuralOperations(isReady: () => boolean): Promise<void> {
+  return new Promise((resolve) => {
+    const check = () => {
+      if (isReady()) {
+        resolve();
+        return;
+      }
+      setTimeout(check, 16);
+    };
+    check();
+  });
+}
+
+export function computeInsertOrder(prevOrder: number, nextOrder: number): number {
+  const gap = nextOrder - prevOrder;
+  return gap > 1 ? Math.floor((prevOrder + nextOrder) / 2) : -1;
+}
+
+export function rebalanceOrders(blocks: DocumentBlock[]): DocumentBlock[] {
+  return [...blocks]
+    .sort((left, right) => left.block_order - right.block_order)
+    .map((block, index) => ({ ...block, block_order: index * 100 }));
+}
+
+export function snapshotBlocks(blocks: DocumentBlock[]): DocumentBlock[] {
+  return blocks.slice();
+}
+
+export function computeBlockHash(block: DocumentBlock): string {
+  return hashSum({
+    type: block.type,
+    content: block.content,
+    style: block.style,
+    word_style: block.word_style,
+    level: block.level,
+    block_order: block.block_order,
+  });
+}
+
+export function isReadonlyBlock(block: DocumentBlock): boolean {
+  const metadata = block.metadata as { readonly?: unknown; is_auto_generated?: unknown };
+  return metadata.readonly === true || metadata.is_auto_generated === true;
+}
+
+export function isCanceledRequest(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (error.name === 'AbortError' ||
+      error.name === 'CanceledError' ||
+      error.message.toLowerCase().includes('cancel'))
+  );
+}
+
+export function serializeBlockForSave(
+  block: DocumentBlock
+): Pick<BlockUpdate, 'content' | 'style'> {
+  if (block.type === 'table') {
+    const serializedTable = serializeTableBlock(block as TableBlock);
+    return { content: serializedTable.content, style: block.style };
+  }
+
+  if ((block.type === 'heading' || block.type === 'paragraph') && Array.isArray(block.content)) {
+    const firstStyle = block.content[0]?.style;
+    const firstStyleSerialized = firstStyle ? JSON.stringify(firstStyle) : undefined;
+    const allSameStyle =
+      !!firstStyle &&
+      block.content.every((segment) => JSON.stringify(segment.style) === firstStyleSerialized);
+
+    return {
+      content: block.content.map((segment) => segment.text).join(''),
+      style:
+        allSameStyle && Object.keys(firstStyle).length > 0
+          ? { ...block.style, ...firstStyle }
+          : block.style,
+    };
+  }
+
+  return { content: block.content, style: block.style };
+}
+
+export function mergeBlockUpdates(
+  previous: BlockUpdate | undefined,
+  next: BlockUpdate
+): BlockUpdate {
+  return { ...(previous || {}), ...next };
+}
+
+export function serializePendingBlockUpdate(
+  block: DocumentBlock,
+  pending: BlockUpdate | undefined
+): BlockUpdate {
+  if (!pending) {
+    const serialized = serializeBlockForSave(block);
+    return {
+      type: block.type,
+      level: block.level,
+      content: serialized.content,
+      style: serialized.style,
+      word_style: block.word_style,
+      metadata: block.metadata,
+      block_order: block.block_order,
+    };
+  }
+
+  const payload: BlockUpdate = {};
+  if ('type' in pending) payload.type = block.type;
+  if ('level' in pending) payload.level = block.level;
+  if ('content' in pending || 'style' in pending) {
+    const serialized = serializeBlockForSave(block);
+    if ('content' in pending) payload.content = serialized.content;
+    if ('style' in pending) payload.style = serialized.style;
+  }
+  if ('word_style' in pending) payload.word_style = block.word_style;
+  if ('metadata' in pending) payload.metadata = block.metadata;
+  if ('block_order' in pending) payload.block_order = block.block_order;
+  return payload;
+}