{ "planVersion": "1.0.0", "generatedDate": "2026-06-03", "project": "MarkLite", "basedOnRequirements": "docs/optimization-requirements.json", "optimization_phases": [ { "phase": 1, "name": "基础设施与代码规范", "priority": "P0-CRITICAL", "estimatedEffort": "1-2 天", "description": "建立代码质量基线：ESLint + Prettier + EditorConfig + ErrorBoundary + 路径别名修复。这些是后续所有优化的前提。", "items": ["CQ-01", "CQ-02", "CQ-03", "AR-05", "DX-07"], "rationale": "CQ-01 (ESLint) 是所有代码质量改进的基础；AR-05 (ErrorBoundary) 保护后续重构不会导致白屏；DX-07 (路径别名) 修复后简化后续 import。", "exitCriteria": [ "npm run lint 通过且返回 0", "npm run format 能格式化全部源文件", "ErrorBoundary 包裹 App 组件", "TypeScript 路径别名在 vite config 中完整映射" ] }, { "phase": 2, "name": "关键性能修复", "priority": "P0-CRITICAL", "estimatedEffort": "1-2 天", "description": "修复影响日常使用的核心性能瓶颈：Markdown 处理器缓存、Zustand 选择器重渲染、CodeMirror Compartment 主题切换、Preview 防抖、IndexedDB 去抖。", "items": ["PF-01", "PF-02", "PF-04", "PF-07", "PF-08"], "rationale": "PF-01 和 PF-02 是 P0-CRITICAL 级性能问题，直接影响用户感知；PF-04 的 Compartment 重构是 PF-03 (React.memo) 的前置；PF-07/08 是低风险高收益的防抖优化。", "exitCriteria": [ "Markdown processor 实例复用率 > 90%", "编辑时仅 activeTab 相关组件重渲染（React DevTools Profiler 验证）", "darkMode 切换不销毁 EditorView", "Preview 渲染频率 < 10 次/秒（快速输入场景）", "IndexedDB 写入频率 < 3 次/秒（连续编辑场景）" ] }, { "phase": 3, "name": "架构重构与代码质量", "priority": "P1-HIGH", "estimatedEffort": "2-3 天", "description": "组件拆分、TypeScript 类型完善、错误处理统一、消除架构反模式（DOM CustomEvent、重复设置加载）。", "items": ["AR-01", "AR-02", "AR-03", "AR-04", "CQ-04", "CQ-05", "PF-03"], "rationale": "组件拆分 (AR-01/02) 和 React.memo (PF-03) 依赖 Phase 1 的 ESLint 和 Phase 2 的 Zustand 优化；类型完善 (CQ-04) 和错误处理 (CQ-05) 可与架构重构并行。", "exitCriteria": [ "App.tsx < 150 行", "Sidebar.tsx < 120 行", "所有函数参数有显式类型标注", "无空 catch 块，所有错误有具体描述", "设置加载只触发一次 IndexedDB 读取" ] }, { "phase": 4, "name": "用户体验改进", "priority": "P1-HIGH", "estimatedEffort": "2-3 天", "description": "替换原生 confirm()、添加加载状态指示、改进 Toast 通知系统、增强可访问性。", "items": ["UX-01", "UX-02", "UX-05", "UX-07"], "rationale": "UX 改进依赖 Phase 3 的组件拆分（新的 ConfirmDialog、Toast 组件需要独立目录）和 ErrorBoundary（统一错误处理模式）。", "exitCriteria": [ "零处原生 confirm() 调用", "文件打开、目录加载、Markdown 渲染有 loading 状态", "Toast 支持多条堆叠 + 类型区分 (success/error/warning)", "所有交互元素有 ARIA 属性" ] }, { "phase": 5, "name": "开发体验与测试", "priority": "P2-MEDIUM", "estimatedEffort": "2-3 天", "description": "建立单元测试框架、强化类型安全、添加项目文档和 Git hooks。", "items": ["DX-01", "DX-02", "DX-04", "DX-05"], "rationale": "测试框架应在代码稳定后添加（Phase 1-4 的重构会导致测试频繁失效）；DX-02 (preload 类型安全) 依赖 CQ-04 (类型完善)。", "exitCriteria": [ "Vitest + React Testing Library 可运行", "核心模块测试覆盖 > 60%", "README.md 包含完整开发指南", "pre-commit 钩子执行 ESLint + typecheck" ] }, { "phase": 6, "name": "高级功能与安全加固", "priority": "P2-P3", "estimatedEffort": "3-5 天", "description": "代码分割、分屏模式、拖拽排序、文件搜索、安全加固 (CSP/file:// 协议)、CI/CD 配置。", "items": ["PF-06", "UX-03", "UX-04", "UX-06", "SE-01", "SE-02", "SE-03", "DX-06"], "rationale": "这些是「锦上添花」的优化，不阻塞核心功能。代码分割 (PF-06) 和分屏模式 (UX-03) 是大规模功能，需要在架构稳定后实施。", "exitCriteria": [ "renderer bundle 拆分为 3+ 个 chunk", "分屏模式可正常编辑+预览", "CSP header 配置且预览正常渲染", "GitHub Actions CI 流水线 lint → typecheck → test → build" ] } ], "file_manifest": { "new_files": [ { "path": "eslint.config.js", "phase": 1, "item": "CQ-01", "description": "ESLint v9 flat config 格式配置文件", "size_estimate": "small" }, { "path": ".prettierrc", "phase": 1, "item": "CQ-02", "description": "Prettier 代码格式化配置", "size_estimate": "trivial" }, { "path": ".prettierignore", "phase": 1, "item": "CQ-02", "description": "Prettier 忽略文件列表", "size_estimate": "trivial" }, { "path": ".editorconfig", "phase": 1, "item": "CQ-03", "description": "编辑器统一行为配置", "size_estimate": "trivial" }, { "path": "src/renderer/components/ErrorBoundary/ErrorBoundary.tsx", "phase": 1, "item": "AR-05", "description": "React ErrorBoundary 组件，显示错误信息和重启按钮", "size_estimate": "small" }, { "path": "src/renderer/components/ErrorBoundary/index.ts", "phase": 1, "item": "AR-05", "description": "ErrorBoundary barrel export", "size_estimate": "trivial" }, { "path": "src/renderer/components/AboutDialog/AboutDialog.tsx", "phase": 3, "item": "AR-01", "description": "从 App.tsx 提取的 About 对话框组件", "size_estimate": "medium" }, { "path": "src/renderer/components/AboutDialog/index.ts", "phase": 3, "item": "AR-01", "description": "AboutDialog barrel export", "size_estimate": "trivial" }, { "path": "src/renderer/hooks/useFileOperations.ts", "phase": 3, "item": "AR-01", "description": "从 App.tsx 提取的文件操作 hook（open/save/saveAs/openRecent）", "size_estimate": "medium" }, { "path": "src/renderer/components/Sidebar/FileTree.tsx", "phase": 3, "item": "AR-02", "description": "从 Sidebar.tsx 提取的递归文件树组件", "size_estimate": "medium" }, { "path": "src/renderer/hooks/useSidebarResize.ts", "phase": 3, "item": "AR-02", "description": "从 Sidebar.tsx 提取的 resize 逻辑 hook", "size_estimate": "small" }, { "path": "src/renderer/components/ConfirmDialog/ConfirmDialog.tsx", "phase": 4, "item": "UX-01", "description": "自定义确认对话框组件，替代原生 confirm()", "size_estimate": "medium" }, { "path": "src/renderer/components/ConfirmDialog/index.ts", "phase": 4, "item": "UX-01", "description": "ConfirmDialog barrel export", "size_estimate": "trivial" }, { "path": "src/renderer/hooks/useConfirm.ts", "phase": 4, "item": "UX-01", "description": "确认对话框状态管理 hook", "size_estimate": "small" }, { "path": "src/renderer/components/LoadingSpinner/LoadingSpinner.tsx", "phase": 4, "item": "UX-02", "description": "通用加载指示器组件", "size_estimate": "small" }, { "path": "src/renderer/components/icons/toolbar-icons.tsx", "phase": 3, "item": "AR-06", "description": "工具栏相关 SVG 图标组件", "size_estimate": "small" }, { "path": "src/renderer/components/icons/sidebar-icons.tsx", "phase": 3, "item": "AR-06", "description": "侧边栏相关 SVG 图标组件", "size_estimate": "small" }, { "path": "src/renderer/components/icons/app-icons.tsx", "phase": 3, "item": "AR-06", "description": "应用级 SVG 图标组件", "size_estimate": "small" }, { "path": "src/renderer/components/icons/index.ts", "phase": 3, "item": "AR-06", "description": "Icons barrel export（保持向后兼容）", "size_estimate": "trivial" }, { "path": "src/renderer/lib/markdown-processor.ts", "phase": 2, "item": "PF-01", "description": "Markdown processor 缓存管理器", "size_estimate": "small" }, { "path": "src/renderer/hooks/useSettingsInit.ts", "phase": 3, "item": "AR-03", "description": "统一设置加载 hook，一次 IndexedDB 读取分发到 store", "size_estimate": "small" }, { "path": "vitest.config.ts", "phase": 5, "item": "DX-01", "description": "Vitest 测试框架配置", "size_estimate": "small" }, { "path": "src/renderer/stores/__tests__/tabStore.test.ts", "phase": 5, "item": "DX-01", "description": "tabStore 单元测试", "size_estimate": "medium" }, { "path": "src/renderer/lib/__tests__/fileUtils.test.ts", "phase": 5, "item": "DX-01", "description": "fileUtils 单元测试", "size_estimate": "small" }, { "path": "src/renderer/lib/__tests__/markdown.test.ts", "phase": 5, "item": "DX-01", "description": "Markdown 渲染单元测试", "size_estimate": "medium" }, { "path": "README.md", "phase": 5, "item": "DX-04", "description": "项目介绍、安装、开发、构建说明", "size_estimate": "medium" }, { "path": "CONTRIBUTING.md", "phase": 5, "item": "DX-04", "description": "贡献指南、代码规范、PR 流程", "size_estimate": "small" }, { "path": ".github/workflows/ci.yml", "phase": 6, "item": "DX-06", "description": "GitHub Actions CI 配置", "size_estimate": "small" } ], "modified_files": [ { "path": "package.json", "phase": [1, 2, 5], "item": ["CQ-02", "DX-05", "DX-01"], "changes": [ "添加 prettier、eslint-config-prettier 依赖", "添加 vitest、@testing-library/react、jsdom 依赖", "添加 husky、lint-staged 依赖", "添加 test、test:watch、test:coverage、format 脚本" ] }, { "path": "electron.vite.config.ts", "phase": [1, 6], "item": ["DX-07", "PF-06"], "changes": [ "renderer.resolve.alias 添加 @main 映射", "renderer.build.rollupOptions.output 添加 manualChunks 分割策略" ] }, { "path": "src/renderer/main.tsx", "phase": 1, "item": "AR-05", "changes": [ "用 ErrorBoundary 包裹 App 组件" ] }, { "path": "src/renderer/App.tsx", "phase": [1, 3], "item": ["AR-01", "AR-05", "CQ-05"], "changes": [ "提取 About 对话框到 AboutDialog 组件", "提取文件操作逻辑到 useFileOperations hook", "统一错误处理模式" ] }, { "path": "src/renderer/lib/markdown.ts", "phase": 2, "item": "PF-01", "changes": [ "引入 markdown-processor.ts 缓存管理器", "renderMarkdown 改为使用缓存的 processor 实例", "添加 processor 缓存失效策略（仅 filePath 变化时重建）" ] }, { "path": "src/renderer/stores/tabStore.ts", "phase": [2, 3], "item": ["PF-02", "PF-08", "AR-07"], "changes": [ "添加 getActiveTab() 选择器方法（返回 activeTab 对象引用）", "添加 getActiveTabId() 选择器方法", "将 setTimeout(saveToDB, 0) 替换为 debounce(saveToDB, 500)", "统一异步保存模式为 Zustand subscribeWithSelector middleware" ] }, { "path": "src/renderer/components/Editor/Editor.tsx", "phase": 2, "item": "PF-02", "changes": [ "替换 const tabs = useTabStore(s => s.tabs) 为 const activeTab = useTabStore(s => s.getActiveTab())", "消除 tabs.find() 调用" ] }, { "path": "src/renderer/components/Preview/Preview.tsx", "phase": [2], "item": ["PF-02", "PF-07"], "changes": [ "替换 tabs 订阅为 activeTab 选择器", "添加 150ms 防抖（useDebounce hook）", "使用新的 markdown processor 缓存" ] }, { "path": "src/renderer/components/StatusBar/StatusBar.tsx", "phase": 2, "item": "PF-02", "changes": [ "替换 tabs 订阅为 activeTab 选择器" ] }, { "path": "src/renderer/components/Sidebar/Sidebar.tsx", "phase": [2, 3], "item": ["PF-02", "AR-02"], "changes": [ "替换 tabs 订阅为 activeTab 选择器", "提取 FileTree 组件到独立文件", "提取 resize 逻辑到 useSidebarResize hook" ] }, { "path": "src/renderer/components/Editor/useCodeMirror.ts", "phase": 2, "item": "PF-04", "changes": [ "引入 Compartment API（@codemirror/state）", "theme 扩展放入 Compartment", "darkMode 变化时通过 compartment.reconfigure() 切换主题", "移除 EditorView 销毁重建逻辑" ] }, { "path": "src/renderer/components/Toolbar/Toolbar.tsx", "phase": 3, "item": "PF-03", "changes": [ "用 React.memo 包装组件导出" ] }, { "path": "src/renderer/components/TabBar/TabBar.tsx", "phase": [3, 4], "item": ["PF-03", "UX-01"], "changes": [ "用 React.memo 包装组件导出", "替换 4 处 confirm() 为自定义 ConfirmDialog" ] }, { "path": "src/renderer/hooks/useUnsavedWarning.ts", "phase": 4, "item": "UX-01", "changes": [ "替换 confirm() 为 electron.dialog.showMessageBox 或自定义 ConfirmDialog" ] }, { "path": "src/renderer/hooks/useTheme.ts", "phase": 3, "item": "AR-03", "changes": [ "移除独立的 settingsRepository.load() 调用", "改为从统一的 useSettingsInit hook 获取设置" ] }, { "path": "src/renderer/hooks/useSettings.ts", "phase": 3, "item": "AR-03", "changes": [ "移除独立的 settingsRepository.load() 调用", "改为从统一的 useSettingsInit hook 获取设置" ] }, { "path": "src/renderer/hooks/useFileWatch.ts", "phase": 3, "item": "AR-04", "changes": [ "移除 window.dispatchEvent(CustomEvent) 调用", "改为调用 Zustand store action 更新文件状态" ] }, { "path": "src/renderer/components/Icons.tsx", "phase": 3, "item": "AR-06", "changes": [ "拆分为 icons/toolbar-icons.tsx、icons/sidebar-icons.tsx、icons/app-icons.tsx", "原文件改为 re-export barrel 文件（向后兼容）" ] }, { "path": "src/renderer/components/Toast/Toast.tsx", "phase": 4, "item": "UX-05", "changes": [ "支持多条堆叠 Toast", "添加 success/error/warning 类型", "添加手动关闭按钮" ] }, { "path": "src/renderer/styles/global.css", "phase": 4, "item": ["UX-01", "UX-02", "UX-05"], "changes": [ "添加 ConfirmDialog 样式", "添加 LoadingSpinner 样式", "添加 Toast 堆叠和类型样式" ] }, { "path": "src/preload/index.ts", "phase": 5, "item": "DX-02", "changes": [ "添加 ElectronAPI 类型约束: const api: ElectronAPI = { ... }", "确保 contextBridge.exposeInMainWorld 返回值类型匹配" ] }, { "path": "src/renderer/types/settings.ts", "phase": 6, "item": "UX-03", "changes": [ "ViewMode 类型扩展为 'editor' | 'preview' | 'split'" ] }, { "path": "src/renderer/index.html", "phase": 6, "item": "SE-01", "changes": [ "添加 CSP meta tag 或在 main process BrowserWindow 中配置 CSP header" ] }, { "path": "src/main/window-manager.ts", "phase": 6, "item": "SE-01", "changes": [ "在 BrowserWindow webPreferences 中配置 CSP header", "确认 nodeIntegration=false, contextIsolation=true, sandbox=true" ] }, { "path": "src/renderer/lib/markdown.ts", "phase": 6, "item": "SE-02", "changes": [ "rehypeFixImages 中的路径校验从简单 '..' 检查改为 path.resolve + allowlist 检查" ] } ], "deleted_files": [] }, "technical_solutions": { "CQ-01_eslint_config": { "id": "CQ-01", "title": "ESLint v9 Flat Config", "solution": "创建 eslint.config.js，使用 ESM flat config 格式。", "implementation": { "file": "eslint.config.js", "format": "ESM (export default [...])", "config_content": { "imports": [ "eslint-plugin-react-hooks", "eslint-plugin-react-refresh", "@typescript-eslint/eslint-plugin" ], "ignores": ["dist/**", "node_modules/**", "out/**"], "languageOptions": { "parser": "@typescript-eslint/parser", "parserOptions": { "ecmaVersion": "latest", "sourceType": "module", "ecmaFeatures": { "jsx": true } } }, "rules": { "@typescript-eslint/no-unused-vars": "error", "no-console": "warn", "prefer-const": "error", "react-hooks/rules-of-hooks": "error", "react-hooks/exhaustive-deps": "warn", "react-refresh/only-export-components": ["warn", { "allowConstantExport": true }] } }, "notes": "ESLint v9 不再支持 --ext 参数，flat config 中通过 files glob 控制。需更新 package.json 的 lint 脚本。" }, "dependencies": [], "risk": "LOW" }, "PF-01_markdown_cache": { "id": "PF-01", "title": "Markdown Processor 缓存", "solution": "将 unified processor 实例提取到独立模块，使用 Map 按 filePath 缓存。", "implementation": { "new_file": "src/renderer/lib/markdown-processor.ts", "approach": "Module-level singleton cache", "cache_strategy": { "key": "filePath (string)", "value": "Processor instance (unified processor with all 7 plugins)", "invalidation": "filePath 变化时创建新 processor，旧实例保留在 cache 中供回退", "max_cache_size": 10, "eviction": "LRU - 超过 max_cache_size 时移除最久未使用的" }, "code_sketch": "const processorCache = new Map();\nexport function getProcessor(filePath: string): Processor {\n if (processorCache.has(filePath)) return processorCache.get(filePath)!;\n const p = unified().use(remarkParse)...;\n processorCache.set(filePath, p);\n return p;\n}" }, "dependencies": [], "risk": "LOW - unified processor 是无状态的，缓存安全" }, "PF-02_zustand_selectors": { "id": "PF-02", "title": "Zustand 选择器优化", "solution": "在 tabStore 中添加 getActiveTab 派生选择器，各组件只订阅 activeTab 引用。", "implementation": { "approach": "在 store 中添加 getter 方法 + useShallow", "store_changes": { "new_methods": [ "getActiveTab(): Tab | undefined — 从 state.tabs 和 state.activeTabId 派生", "getActiveTabId(): string | null — 直接返回 state.activeTabId" ], "notes": "Zustand 5 中 useShallow 来自 'zustand/react/shallow'" }, "component_changes": { "before": "const tabs = useTabStore(s => s.tabs);\nconst activeTab = tabs.find(t => t.id === activeTabId);", "after": "const activeTab = useTabStore(s => s.tabs.find(t => t.id === s.activeTabId));", "note": "直接在选择器中 find，当 activeTab 的引用未变时不会触发重渲染。或使用 useShallow + getActiveTab 方法。" }, "affected_files": [ "src/renderer/components/Editor/Editor.tsx", "src/renderer/components/Preview/Preview.tsx", "src/renderer/components/StatusBar/StatusBar.tsx", "src/renderer/components/Sidebar/Sidebar.tsx" ] }, "dependencies": ["PF-01"], "risk": "MEDIUM - 需验证所有订阅点，遗漏会导致功能异常" }, "PF-04_codemirror_compartment": { "id": "PF-04", "title": "CodeMirror Compartment 主题切换", "solution": "使用 @codemirror/state 的 Compartment API 封装主题扩展，darkMode 变化时 reconfigure 而非销毁重建。", "implementation": { "file": "src/renderer/components/Editor/useCodeMirror.ts", "approach": "Compartment + reconfigure", "code_sketch": "import { Compartment } from '@codemirror/state';\nconst themeCompartment = new Compartment();\n\n// 创建时:\nconst extensions = [\n // ... other extensions\n themeCompartment.of(darkMode ? oneDark : [])\n];\n\n// darkMode 变化时:\nuseEffect(() => {\n if (editorView) {\n editorView.dispatch({\n effects: themeCompartment.reconfigure(darkMode ? oneDark : [])\n });\n }\n}, [darkMode]);", "key_changes": [ "移除 useEffect 中 EditorView 销毁重建逻辑", "theme 扩展改为 Compartment.of() 包装", "darkMode 变化改为 dispatch reconfigure effect", "保留其他扩展不变（keymap、language 等）" ] }, "dependencies": [], "risk": "HIGH - 影响编辑器核心初始化流程，需仔细测试切换前后编辑器状态保留" }, "PF-07_preview_debounce": { "id": "PF-07", "title": "Preview 渲染防抖", "solution": "创建 useDebounce hook，在 Preview.tsx 中对 content 变化进行 150ms 防抖。", "implementation": { "new_file": "src/renderer/hooks/useDebounce.ts", "approach": "标准 useDebounce hook + useEffect", "code_sketch": "function useDebounce(value: T, delay: number): T {\n const [debouncedValue, setDebouncedValue] = useState(value);\n useEffect(() => {\n const timer = setTimeout(() => setDebouncedValue(value), delay);\n return () => clearTimeout(timer);\n }, [value, delay]);\n return debouncedValue;\n}", "usage_in_preview": "const content = activeTab?.content ?? '';\nconst debouncedContent = useDebounce(content, 150);\nuseEffect(() => {\n // renderMarkdown(debouncedContent)\n}, [debouncedContent]);" }, "dependencies": ["PF-01", "PF-02"], "risk": "LOW" }, "PF-08_indexeddb_debounce": { "id": "PF-08", "title": "IndexedDB 保存去抖", "solution": "将 tabStore 中的 setTimeout(saveToDB, 0) 替换为 debounce(saveToDB, 500)。", "implementation": { "file": "src/renderer/stores/tabStore.ts", "approach": "引入 debounce 工具函数", "code_sketch": "// utils/debounce.ts\nexport function debounce any>(fn: T, ms: number): T {\n let timer: ReturnType;\n return ((...args: any[]) => {\n clearTimeout(timer);\n timer = setTimeout(() => fn(...args), ms);\n }) as T;\n}\n\n// tabStore.ts\nconst debouncedSaveToDB = debounce(() => saveToDB(), 500);\nconst debouncedSaveActiveTab = debounce((id: string) => tabRepository.saveActiveTabId(id), 300);", "affected_patterns": [ "setTimeout(() => saveToDB(), 0) → debouncedSaveToDB()", "setTimeout(() => tabRepository.saveActiveTabId(activeTabId), 0) → debouncedSaveActiveTab(activeTabId)" ] }, "dependencies": [], "risk": "LOW - 去抖延迟可配置，用户关闭窗口前需 flush" }, "AR-05_error_boundary": { "id": "AR-05", "title": "React ErrorBoundary", "solution": "创建 class component ErrorBoundary，捕获渲染错误，显示友好错误页面。", "implementation": { "file": "src/renderer/components/ErrorBoundary/ErrorBoundary.tsx", "features": [ "componentDidCatch + getDerivedStateFromError", "显示错误信息、错误栈（开发模式）", "「重新加载」按钮调用 location.reload() 或 window.electronAPI 重启", "「复制错误信息」按钮", "支持 fallback 自定义 UI" ], "integration": "在 main.tsx 中 " }, "dependencies": [], "risk": "LOW" }, "AR-01_app_split": { "id": "AR-01", "title": "App.tsx 拆分", "solution": "提取 AboutDialog 组件和 useFileOperations hook。", "implementation": { "extractions": [ { "name": "AboutDialog", "source": "App.tsx 内联 JSX (~40 行)", "target": "src/renderer/components/AboutDialog/AboutDialog.tsx", "props": "{ visible: boolean; onClose: () => void; version: string }" }, { "name": "useFileOperations", "source": "App.tsx 中的 handleOpenFile, handleSave, handleSaveAs, handleOpenRecent 函数", "target": "src/renderer/hooks/useFileOperations.ts", "returns": "{ handleOpenFile, handleSave, handleSaveAs, handleOpenRecent }" } ], "expected_result": "App.tsx 从 ~307 行减少到 ~120 行" }, "dependencies": ["CQ-01", "AR-05"], "risk": "LOW - 提取式重构，行为不变" }, "AR-03_unified_settings": { "id": "AR-03", "title": "统一设置加载", "solution": "创建 useSettingsInit hook，一次性从 IndexedDB 加载所有设置，分发到各 store。", "implementation": { "new_file": "src/renderer/hooks/useSettingsInit.ts", "approach": "单次加载 + Zustand setState 分发", "code_sketch": "export function useSettingsInit() {\n const [loaded, setLoaded] = useState(false);\n useEffect(() => {\n settingsRepository.load().then(settings => {\n useThemeStore.getState().applySettings(settings);\n useEditorStore.getState().applySettings(settings);\n setLoaded(true);\n });\n }, []);\n return loaded;\n}", "affected_files": [ "src/renderer/hooks/useTheme.ts — 移除独立 load()", "src/renderer/hooks/useSettings.ts — 移除独立 load()" ] }, "dependencies": [], "risk": "MEDIUM - 设置加载时序变化可能影响首次渲染" }, "UX-01_confirm_dialog": { "id": "UX-01", "title": "自定义确认对话框", "solution": "创建 ConfirmDialog 组件 + useConfirm hook，替代原生 confirm()。", "implementation": { "approach": "Promise-based confirm API", "code_sketch": "// useConfirm.ts\nexport function useConfirm() {\n const [state, setState] = useState<{ message: string; resolve: (v: boolean) => void } | null>(null);\n const confirm = (message: string) => new Promise(resolve => setState({ message, resolve }));\n const handleConfirm = () => { state?.resolve(true); setState(null); };\n const handleCancel = () => { state?.resolve(false); setState(null); };\n return { confirm, dialog: state ? : null };\n}", "affected_locations": [ "TabBar.tsx — 4 处 confirm() 调用", "useUnsavedWarning.ts — 1 处 confirm() 调用" ] }, "dependencies": ["AR-01"], "risk": "MEDIUM - Promise-based API 与原生 confirm() 的同步行为不同，需确保调用方正确 await" }, "UX-03_split_mode": { "id": "UX-03", "title": "分屏模式", "solution": "扩展 ViewMode 为 'split'，布局组件根据 mode 同时渲染 Editor 和 Preview。", "implementation": { "approach": "CSS Grid/ResizeObserver 双栏布局", "key_changes": [ "types/settings.ts: ViewMode = 'editor' | 'preview' | 'split'", "App.tsx 或新 Layout 组件: 根据 viewMode 条件渲染", "split 模式: 左 50% Editor + 右 50% Preview，可拖拽调整比例", "添加 Ctrl+3 快捷键切换到 split 模式", "可选：编辑器滚动同步预览滚动位置" ] }, "dependencies": ["PF-01", "PF-02", "PF-04"], "risk": "HIGH - 需要同时维护两个视图实例，内存和性能需关注" }, "PF-06_code_splitting": { "id": "PF-06", "title": "代码分割", "solution": "在 electron.vite.config.ts 中配置 Rollup manualChunks，按依赖类型分割。", "implementation": { "file": "electron.vite.config.ts", "approach": "manualChunks + dynamic import", "chunks_config": { "vendor-react": ["react", "react-dom"], "vendor-codemirror": ["@codemirror/state", "@codemirror/view", "@codemirror/commands", "@codemirror/lang-markdown", "@codemirror/language", "@codemirror/search", "@codemirror/theme-one-dark"], "vendor-markdown": ["unified", "remark-parse", "remark-gfm", "remark-rehype", "rehype-raw", "rehype-sanitize", "rehype-stringify", "rehype-highlight"], "vendor-db": ["dexie"] }, "dynamic_import_targets": [ "rehype-highlight (仅 Preview 组件需要)" ] }, "dependencies": [], "risk": "MEDIUM - 代码分割后需验证 Electron 打包正确性和加载时序" }, "SE-01_csp": { "id": "SE-01", "title": "CSP 配置", "solution": "在 main process 的 BrowserWindow 中通过 session.defaultSession.webRequest 配置 CSP header。", "implementation": { "file": "src/main/window-manager.ts", "approach": "session.webRequest.onHeadersReceived", "csp_policy": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' file: data:; font-src 'self' data:;", "notes": "style-src 需要 'unsafe-inline' 因为 CodeMirror 通过 JS 注入内联样式。rehype-highlight 引入 highlight.js 样式也需要考虑。" }, "dependencies": ["PF-04"], "risk": "MEDIUM - CSP 可能阻断 CodeMirror 样式注入，需测试" } }, "dependency_graph": { "description": "优化项之间的依赖关系。箭头表示 'A -> B' 意味着 B 依赖 A（A 需先完成）。", "edges": [ { "from": "CQ-01", "to": "CQ-02", "reason": "Prettier 需与 ESLint 集成 (eslint-config-prettier)" }, { "from": "CQ-01", "to": "AR-01", "reason": "组件拆分前需确保代码质量基线" }, { "from": "CQ-01", "to": "AR-02", "reason": "组件拆分前需确保代码质量基线" }, { "from": "CQ-01", "to": "PF-03", "reason": "React.memo 添加前需 ESLint 规则配合" }, { "from": "CQ-01", "to": "DX-05", "reason": "lint-staged 依赖 ESLint 配置" }, { "from": "CQ-01", "to": "DX-01", "reason": "测试代码也需遵循 ESLint 规则" }, { "from": "CQ-04", "to": "DX-02", "reason": "preload 类型安全依赖类型完善" }, { "from": "PF-01", "to": "PF-02", "reason": "Zustand 选择器优化涉及 Preview 组件，需配合 Markdown 缓存" }, { "from": "PF-01", "to": "PF-07", "reason": "Preview 防抖依赖渲染管道已优化" }, { "from": "PF-02", "to": "PF-07", "reason": "Preview 防抖依赖 activeTab 选择器" }, { "from": "PF-02", "to": "PF-03", "reason": "React.memo 效果依赖选择器优化减少不必要更新" }, { "from": "AR-01", "to": "UX-01", "reason": "ConfirmDialog 依赖组件拆分后的目录结构" }, { "from": "AR-01", "to": "UX-02", "reason": "LoadingSpinner 依赖组件拆分后的目录结构" }, { "from": "PF-01", "to": "UX-03", "reason": "分屏模式的预览面板依赖 Markdown 缓存" }, { "from": "PF-02", "to": "UX-03", "reason": "分屏模式需要高效的 store 订阅" }, { "from": "PF-04", "to": "UX-03", "reason": "分屏模式的编辑器依赖 Compartment 动态配置" }, { "from": "PF-04", "to": "SE-01", "reason": "CSP 配置需在 Compartment 稳定后进行，避免相互影响" }, { "from": "AR-05", "to": "AR-01", "reason": "ErrorBoundary 应在 App.tsx 拆分前完成，保护重构过程" } ], "parallelizable": [ ["CQ-01", "AR-05", "DX-07"], ["PF-01", "PF-04", "PF-08"], ["CQ-04", "CQ-05", "AR-03", "AR-04"], ["UX-01", "UX-02", "UX-05"], ["DX-01", "DX-04"] ] }, "risk_assessment": { "high_risk": [ { "id": "PF-04", "title": "CodeMirror Compartment 重构", "risk_level": "HIGH", "description": "影响编辑器核心初始化流程。Compartment reconfigure 如果处理不当，可能导致编辑器状态丢失（光标位置、选区、undo 历史）。", "impact": "编辑器完全不可用", "probability": "MEDIUM", "mitigation": [ "保留现有销毁重建逻辑作为 fallback（feature flag 控制）", "编写测试验证切换主题后光标位置和 undo 历史保留", "逐步迁移：先用 Compartment 切换主题，验证稳定后再扩展到其他扩展" ], "rollback": "revert useCodeMirror.ts 到使用前的版本" }, { "id": "UX-03", "title": "分屏模式", "risk_level": "HIGH", "description": "需要同时维护 Editor 和 Preview 两个实例，可能增加内存占用和 CPU 消耗。滚动同步逻辑复杂。", "impact": "性能下降、内存溢出（大文件场景）", "probability": "MEDIUM", "mitigation": [ "Preview 面板使用延迟加载（只在 split 模式激活时挂载）", "大文件场景下限制预览刷新频率（500ms debounce）", "考虑虚拟化预览（只渲染可视区域）" ], "rollback": "ViewMode 从 'editor' | 'preview' | 'split' 移除 'split' 值" } ], "medium_risk": [ { "id": "PF-02", "title": "Zustand 选择器重构", "risk_level": "MEDIUM", "description": "选择器重构可能遗漏某些订阅点，导致某些组件在 activeTab 变化时不再更新。", "impact": "编辑器/预览/状态栏内容不同步", "probability": "LOW", "mitigation": [ "使用 React DevTools Profiler 逐一验证每个受影响组件的重渲染行为", "逐个文件修改，每修改一个文件后手动测试", "编写 tabStore 选择器的单元测试" ], "rollback": "逐文件恢复原始订阅方式" }, { "id": "SE-01", "title": "CSP 配置", "risk_level": "MEDIUM", "description": "CSP 配置过于严格可能阻断 CodeMirror 内联样式注入或 rehype-highlight 的样式。", "impact": "编辑器或预览样式丢失", "probability": "LOW", "mitigation": [ "使用 'unsafe-inline' 允许 style-src（CodeMirror 依赖）", "分步启用 CSP 先 report-only 模式测试", "测试所有主题切换和 Markdown 语法高亮场景" ], "rollback": "移除 CSP header 配置" }, { "id": "AR-03", "title": "统一设置加载", "risk_level": "MEDIUM", "description": "将两次 IndexedDB 读取合并为一次可能改变设置加载时序，导致首次渲染闪烁或主题闪烁。", "impact": "首次加载时短暂显示默认主题再切换到用户主题", "probability": "LOW", "mitigation": [ "在设置加载完成前显示 loading 状态（不渲染 App）", "使用 init() 方式在 main.tsx 中等待设置加载完成后再渲染" ], "rollback": "恢复 useTheme 和 useSettings 各自独立加载" }, { "id": "PF-08", "title": "IndexedDB 去抖", "risk_level": "MEDIUM", "description": "去抖延迟期间如果 Electron 进程被杀或用户关闭窗口，可能丢失最后一次保存。", "impact": "用户数据丢失（最后一次编辑）", "probability": "LOW", "mitigation": [ "在 beforeunload / window close 事件中 flush debounce", "使用 navigator.sendBeacon 或 Electron app.on('before-quit') 事件触发同步保存", "记录 dirty flag，关闭前检查" ], "rollback": "恢复 setTimeout(fn, 0) 立即保存" } ], "low_risk": [ { "id": "CQ-01", "title": "ESLint 配置", "risk_level": "LOW", "description": "纯增量添加，不影响运行时行为。", "mitigation": ["确保 .eslintignore 排除构建产物"] }, { "id": "PF-01", "title": "Markdown 处理器缓存", "risk_level": "LOW", "description": "unified processor 是无状态管道，缓存复用安全。", "mitigation": ["设置 max cache size 防止内存泄漏"] }, { "id": "PF-07", "title": "Preview 防抖", "risk_level": "LOW", "description": "防抖只是延迟渲染，不影响最终结果。", "mitigation": ["防抖时间可配置，默认 150ms"] }, { "id": "AR-05", "title": "ErrorBoundary", "risk_level": "LOW", "description": "纯增量添加，只在出错时生效。", "mitigation": ["测试注入错误验证 ErrorBoundary 正常捕获"] } ] }, "summary": { "total_optimization_items": 35, "total_new_files": 28, "total_modified_files": 22, "total_phases": 6, "estimated_total_effort": "12-18 天", "critical_path": "CQ-01 → AR-05 → AR-01 → UX-01 → DX-05", "parallel_speedup_potential": "约 30-40%（Phase 1 和 Phase 2 可部分并行）", "highest_impact_items": ["PF-02", "PF-01", "PF-04", "AR-05"], "recommended_execution_order": [ "Phase 1 (Day 1-2): ESLint + Prettier + ErrorBoundary — 建立基线", "Phase 2 (Day 3-4): 性能修复 — 解决核心瓶颈", "Phase 3 (Day 5-7): 架构重构 — 提升可维护性", "Phase 4 (Day 8-10): UX 改进 — 提升用户体验", "Phase 5 (Day 11-13): 测试 + 文档 — 建立质量保障", "Phase 6 (Day 14-18): 高级功能 — 锦上添花" ] } }