版本模型详解
版本模型详解
M-Doc 的版本管理采用三层模型：文档 → 版本 → 文章，支持类 Git 的版本控制能力。
三层模型
Document（文档）
├── DocumentVersion（版本）
│ ├── DocumentVersionArticle（版本-文章关联）
│ │ └── ArticleVersion（文章版本快照）
│ └── ...
├── DocumentVersion（另一个版本）
│ └── ...
└── default_version_id → 指向默认版本Document（文档）
文档是最顶层的容器，归属于组织。
| 字段 | 说明 |
|---|---|
id |
文档 ID |
name |
文档名称 |
slug |
URL 标识 |
organization_id |
所属组织 |
default_version_id |
默认版本 |
visibility |
可见性 |
DocumentVersion（版本）
每个文档可以有多个版本，每个版本包含独立的文章树。
| 字段 | 说明 |
|---|---|
id |
版本 ID |
document_id |
所属文档 |
name |
版本名称（如 master, v1.0.0） |
parent_id |
父版本 ID（Fork 来源） |
status |
版本状态 |
Article（文章）
文章是逻辑实体，通过 stable_key 跨版本追踪。
| 字段 | 说明 |
|---|---|
id |
文章 ID |
document_id |
所属文档 |
stable_key |
UUID，跨版本不变 |
title |
文章标题 |
ArticleVersion（文章版本）
每次发布生成的内容快照。
| 字段 | 说明 |
|---|---|
id |
文章版本 ID |
article_id |
所属文章 |
content |
Markdown 内容 |
commit_hash |
SHA1 哈希（40字符） |
short_hash |
短哈希（7字符） |
commit_message |
提交说明 |
parent_commit_hash |
父版本哈希 |
status |
draft / published |
DocumentVersionArticle（关联表）
连接版本和文章的中间表，定义文章在版本中的位置。
| 字段 | 说明 |
|---|---|
document_version_id |
版本 ID |
article_id |
文章 ID |
article_version_id |
文章版本 ID |
parent_article_id |
父文章 ID（层级结构） |
sort_order |
排序序号 |
stable_key 跨版本追踪
stable_key 是文章的全局唯一标识（UUID），在 Fork 版本时保持不变。这使得系统能够：
- 识别同一文章：在不同版本中找到同一篇文章
- 支持合并：基于 stable_key 匹配源和目标文章
- 追踪变化：对比同一文章在不同版本中的内容差异
v1.0.0 v2.0.0（Fork 自 v1.0.0）
├── 文章A (stable_key: abc) ├── 文章A (stable_key: abc) ← 同一篇
├── 文章B (stable_key: def) ├── 文章B (stable_key: def) ← 同一篇
└── 文章C (stable_key: ghi) ├── 文章C (stable_key: ghi) ← 同一篇
└── 文章D (stable_key: jkl) ← v2.0.0 新增版本 Fork 流程
Fork 操作的内部流程：
- 创建新的
DocumentVersion记录 - 复制源版本的所有
DocumentVersionArticle记录 - 保持相同的
article_id和article_version_id - 新版本与源版本共享文章实体和版本快照
- 后续编辑在新版本中创建独立的文章版本