版本管理实现（功能清单 + 数据 + 接口 + 流程）

本篇围绕“功能→实现”的结构展开，便于二开快速对齐。

1) 功能清单

• 版本列表（分页/搜索可扩展）
• 创建版本（手动/自动）
• 版本详情（查看元信息与内容）
• 更新版本信息（标题/描述）
• 删除版本（软/硬删除可拓展）
• 版本对比（两版本内容对比）
• 版本恢复（将某版本设为当前内容，并建议产生恢复点）

2) 数据模型与存储

• 存储位置：server/db/version/{docId}.json
• 结构：按时间追加的版本数组

{
  "id": "20250301T120001_xxx",
  "documentId": "doc-123",
  "content": { "type": "doc", "content": [] },
  "title": "版本 2025-03-01",
  "description": "自动保存",
  "author": "user-1",
  "createdAt": "2025-03-01T12:00:01.000Z",
  "updatedAt": "2025-03-01T12:00:01.000Z"
}

• 企业化建议：迁移 DB，增加索引/审计/软删除/归档

3) 后端接口（router/version.js）

功能	方法与路径	入参要点	返回
列表	GET /documents/:docId/versions	page, limit
创建	POST /documents/:docId/versions	content, title?, description?, author?
详情	GET /documents/:docId/versions/:versionId	-	版本条目
更新	PUT /documents/:docId/versions/:versionId	title?, description?	更新后条目
删除	DELETE /documents/:docId/versions/:versionId	-
对比	GET /documents/:docId/versions/:v1/compare/:v2	-

前端封装：app/src/api/version.ts

4) 前端交互与组件

• components/VersionManager.vue：列表/创建/删除/恢复入口
• components/VersionCompare.vue：并排对比或高亮差异（与内容结构适配）

创建版本（伪代码）：

const content = editor.getJSON?.() ?? editor.getHTML?.()
await versionApi.createVersion(docId, { content, title, description })

恢复版本流程：

5) 边界与最佳实践

• 自动保存节流：按时间/更改量阈值触发
• 恢复即创建恢复点：保证可逆
• 审计：删除/恢复/批量操作务必记录
• 压力与容量：版本文件过大时归档/拆分；高并发迁 DB

6) 待扩展（建议）

• 标签/里程碑字段
• 对比视图差异高亮
• 批量导出版本（打包ZIP）