书签清理与归档器

一、立项背景与目标
浏览器书签长期使用后往往杂乱无章，原生管理器缺乏批量整理和云端备份能力。本项目构建一个 Chrome 扩展，让用户在独立工作区中以可视化图谱方式导入、整理书签，支持写回浏览器或同步至 WebDAV 云端，并提供版本管理和撤销保护，确保操作安全可逆。
当前已落地工程基线、启动导入链路、草稿图谱编辑、本地备份恢复、WebDAV 同步等核心能力，浏览器覆盖写回仍在收尾中。
二、核心功能模块
草稿图谱（bookmark-graph）：核心模块。以思维导图式布局展示书签树，支持节点创建（同级/子级）、重命名、编辑URL、删除、拖拽移动、键盘重排/提升，内置搜索、重复书签聚焦和 Ctrl+Z 撤销。节点分为 folder 和 bookmark 两类，来源标记为 browser 或 draft。
浏览器同步（browser-sync）：启动引导模块。按"本地草稿优先 → 浏览器书签导入 → 首次持久化"策略完成工作区初始化。
WebDAV 同步（webdav）：云端备份与恢复。支持草稿/书签快照上传，版本化存储（最多5版），支持从历史版本选择恢复并自动清理旧版本。
本地持久化（local-persistence）：基于 chrome.storage.local 持久化草稿会话、WebDAV 配置和本地备份产物，覆盖操作前自动创建备份用于撤销保护。
浏览器书签适配器（browser-bookmarks）：封装 Chrome 书签 API，提供读取、导入、导出和覆盖写回能力，写入失败时自动回退。
工作区入口（workspace-entry）：处理扩展图标点击，实现打开或聚焦工作区页面。
三、业务流程
启动：点击扩展图标 → 打开工作区 → 检测本地草稿：有则恢复，无则读取浏览器书签导入并持久化。
编辑：在图谱工作区浏览书签树 → 通过菜单/快捷键编辑节点（创建、重命名、删除、拖拽） → 搜索查找或重复聚焦 → Ctrl+Z 撤销。
同步写回：触发"同步到浏览器" → 确认覆盖 → 自动备份浏览器书签 → 导出草稿为书签树写回浏览器 → 失败自动回退。
WebDAV 流程：配置服务端并测试连通 → 上传快照到云端（版本化存储） → 恢复时选择目标版本 → 确认前自动备份 → 执行恢复。
撤销保护：每次覆盖操作前自动备份当前状态，用户可通过"撤销覆盖"恢复到操作前的草稿或浏览器书签。

一、整体架构与设计思路
项目采用五层架构：应用层（app）为 React 壳层与工作区编排；特性层（features）按业务域划分——bookmark-graph（图谱编辑）、browser-sync（启动引导）、webdav（云端同步）、workspace-entry（扩展入口）；领域层（domain）为纯业务模型，不依赖框架；适配器层（adapters）隔离 Chrome 书签 API、chrome.storage.local、原生 fetch 等外部依赖；共享层（shared）管理文案和通用工具。
技术栈：React 19 + TypeScript + Vite，Vitest + Testing Library，Chrome Extension MV3，WebDAV 用原生 fetch。核心设计思路：业务真相在规范化草稿图谱层，浏览器和 WebDAV 是外部映射目标，所有覆盖操作先备份再执行，失败可回退。
二、负责模块与量化成果
独立完成 T01 至 T13 共 13 个里程碑，涵盖从工程 scaffold 到项目收尾的完整生命周期。
32 个源文件 + 35 个测试文件，约 21,600 行代码，测试文件数超过源文件数。已落地：浏览器书签读取/导入/导出/写回全链路（含失败自动回退）；图谱 7 种编辑操作 + 键盘重排/提升；5 种变更类型的 patch 撤销；WebDAV 版本化上传（最多 5 版）+ 双端恢复；覆盖前自动备份，支持双端撤销恢复；35
个测试套件覆盖启动、编辑、拖拽、WebDAV、搜索、撤销等核心链路；状态历史与配置均持久化。
三、难点与解决方案
浏览器写回安全性：Chrome 书签 API 不可逆，中断会丢失书签。解决方案：writeManagedBrowserTree 先读快照作回滚基准，异常时自动反向回退，区分"回滚成功/失败"给出精确提示。
可视化图谱自研布局：未引入第三方图库，需手写思维导图布局。解决方案：实现递归 MindmapLayout 算法，参数化控制节点宽度、间距、分支颜色，支持 400+ 节点视口裁剪和窗口 resize 自适应。
WebDAV 权限适配：Chrome MV3 跨域需动态申请 host_permissions。解决方案：封装权限检测/申请为独立适配器，操作前显式检查，区分 denied/unavailable/invalid-origin 给出精确提示，状态持久化避免重复弹窗。
撤销与外部操作隔离：Ctrl+Z 应撤销编辑但不影响已完成的写回/上传。解决方案：撤销历史仅记录草稿内部变更，外部操作不进 undo 栈，通过 snapshotVersion 和 checkpoint 管理快照一致性。