版本管理

WesCraft 自动保存页面的历史版本，让你随时查看变更历史、对比差异或恢复到之前的状态。

版本概念

每次保存页面时，WesCraft 会自动创建一个版本快照，存储在 wc_page_versions 表中。版本记录包含：

• 版本时间戳：精确到秒的创建时间
• 完整内容：该时刻的页面完整内容
• 变更摘要：与上一版本的差异概述
• 版本编号：递增的版本号

版本与保存的关系

用户编辑 → 防抖触发 → 保存页面 → 创建版本记录
                  ↓
            Pipeline.Trigger
          (time.AfterFunc per-pageID)

并非每次按键都会创建版本，系统使用 time.AfterFunc 配合 per-pageID timer 实现智能防抖，避免过于频繁的版本创建。

版本列表

查看版本历史

1. 打开目标页面
2. 点击页面菜单（右上角 ···）
3. 选择 版本历史
4. 查看所有历史版本列表

版本列表信息

版本列表示例

v12  2026-09-14 20:30  添加了"技术方案"章节
v11  2026-09-14 18:15  更新了项目时间线
v10  2026-09-14 14:22  修改了目标描述
v9   2026-09-13 16:40  初始化页面内容
...

版本对比

两版本 Diff 查看

1. 在版本历史中选择两个版本
2. 点击 对比
3. 查看两版本间的差异

Diff 展示方式

差异以 Block 级别展示：

对比当前版本与历史版本

快速对比当前编辑内容与某个历史版本：

1. 在版本历史中找到目标版本
2. 点击 与当前对比
3. 查看当前未保存的更改

版本恢复

恢复到指定版本

1. 在版本历史中找到目标版本
2. 点击 恢复此版本
3. 确认恢复操作

注意：恢复操作本身会创建一个新版本，原有版本不会丢失。

v1 → v2 → v3 → v4(当前) → v5(恢复到v2的内容)
                              ↑ 新版本，内容等同于 v2

部分恢复

如果只需要恢复某个 Block 的内容：

1. 打开目标历史版本的预览
2. 复制需要的 Block 内容
3. 粘贴到当前页面的对应位置

自动保存策略

防抖机制

WesCraft 使用 time.AfterFunc + per-pageID timer 实现智能防抖：

// 每个 pageID 对应一个独立的 timer
// 编辑操作触发 timer 重置
// timer 到期后执行保存和版本创建
pipeline.Trigger(pageID)

这确保了：

• 不会遗漏：编辑停止后一定会保存
• 不会过频：连续编辑只创建一个版本
• 不会爆炸：不再使用 go func() { sleep(5s) }，避免 goroutine 泄漏

保存触发条件

版本清理

自动清理策略

过旧的版本会被自动清理以节省存储空间：

• 保留最近 N 个版本：超出数量的旧版本自动删除
• 保留最近 N 天版本：超出天数的旧版本自动删除
• 关键版本豁免：手动标记的"关键版本"不会被自动清理

与页面删除的关系

删除页面时，版本记录同步清理（对齐修复 R-1）：

// DeletePage 递归处理：
// 1. SoftDeletePage(pageID) — 标记当前页面
// 2. SoftDeletePage(childIDs...) — 递归标记子页面
// 3. PurgePage — 物理删除页面数据
//    同时删除 wc_page_versions 中的对应记录

手动清理

在页面版本历史中，可以手动删除不需要的版本：

1. 打开版本历史
2. 选中要删除的版本
3. 点击 删除选中版本

注意：当前版本和标记为"关键"的版本不可删除。

版本保留策略配置

在设置中调整版本保留策略：

最佳实践

1. 重要变更前手动保存：大幅修改前先 Ctrl+S，确保有干净的恢复点
2. 标记关键版本：重要的里程碑版本手动标记为"关键"
3. 定期清理：偶尔检查版本历史，删除无意义的中间版本
4. 对比再恢复：恢复前先用 Diff 确认要恢复的内容