85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# @go/docDB
|
||
|
||
`docDB` 是一个独立的高级文档存储引擎，基于 `@go/tableDB` 构建，提供全自动版本管理、历史存证、流式大文件处理及生命周期钩子。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
go get apigo.cc/go/docDB
|
||
```
|
||
|
||
## 🛠 核心功能
|
||
|
||
1. **版本管控**：`SetDoc` 强制提升版本号并自动归档旧版；`SetMeta` 仅更新属性不触碰版本。
|
||
2. **历史存证**：即使文档被删除，其所有历史版本（包括被删除前的最后一版）依然可通过 `GetByVersion` 获取。
|
||
3. **权限隔离**：完全继承 `tableDB` 的 RLS (Row Level Security) 体系。
|
||
4. **流式上传**：`BinaryContent` 采用 `io.Reader` 接口，支持低内存处理 GB 级大文件落盘。
|
||
5. **事件驱动**：提供标准的 `Hooks` 机制，支持监听文档创建、更新与移除。
|
||
6. **智能提取**：自动提取 Markdown 目录结构 (ToC)，且能智能跳过代码块内容。
|
||
|
||
## 🚀 API 指南
|
||
|
||
### 1. 初始化与授权
|
||
|
||
```go
|
||
import (
|
||
"apigo.cc/go/docDB"
|
||
"apigo.cc/go/tableDB"
|
||
)
|
||
|
||
// 创建基础数据库连接 (tableDB 层)
|
||
unauthorizedDB := tableDB.GetDB("sqlite://docs.db", logger)
|
||
|
||
// 获取 docDB 引擎 (自动完成表结构初始化)
|
||
engine := docDB.GetDB(unauthorizedDB, "./storage_root")
|
||
|
||
// 授权并获取操作句柄
|
||
db := engine.Auth("user_123")
|
||
```
|
||
|
||
### 2. 文档操作 (DocDB API)
|
||
|
||
- **`SetDoc(doc *Document) error`**
|
||
- 保存文档。如果是更新，会自动将旧版本移入 `_Doc_History`，并递增 `version`。
|
||
- **`SetMeta(id string, meta map[string]any) error`**
|
||
- 更新文档元数据（如 Title, Tags）。**不提升版本号**。
|
||
- **`Get(id string) (*Document, error)`**
|
||
- 获取文档的当前最新版本。
|
||
- **`GetByVersion(id string, version uint64) (*Document, error)`**
|
||
- 获取指定版本的文档。即使当前文档已被 `Remove`，历史版本依然可查。
|
||
- **`Remove(id string) error`**
|
||
- 删除文档。删除前会自动将当前最后一版归档至历史表。
|
||
|
||
### 3. 生命周期钩子 (Hooks)
|
||
|
||
```go
|
||
engine.Hooks.OnCreatedDoc = func(doc *docDB.Document) {
|
||
// 处理新文档创建，如提交搜索索引
|
||
}
|
||
|
||
engine.Hooks.OnUpdatedDoc = func(doc *docDB.Document) {
|
||
// 处理内容更新
|
||
}
|
||
|
||
engine.Hooks.OnRemoved = func(id string) {
|
||
// 处理物理删除后的清理工作
|
||
}
|
||
```
|
||
|
||
## 📝 数据结构
|
||
|
||
### Document
|
||
| 字段 | 类型 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| `ID` | `string` | 唯一标识 (10位随机码) |
|
||
| `Path` | `string` | 逻辑路径 (如 /docs/readme.md) |
|
||
| `BinaryContent` | `io.Reader` | 瞬态流，用于接收上传内容 |
|
||
| `TextContent` | `string` | 文档正文 (Markdown/Plain) |
|
||
| `Version` | `uint64` | 单调递增的版本号 |
|
||
| `ToC` | `[]ToCNode` | 自动生成的目录树 |
|
||
|
||
## 💡 注意事项
|
||
|
||
- **路径对齐**：所有物理文件存储在 `baseDir/doc/` 下，按 ID 前缀进行三级目录隔离。
|
||
- **自动初始化**：`GetDB` 内部使用 `_system` 权限自动维护 `_Doc` 和 `_Doc_History` 的表结构。
|