@go/docDB

docDB 是一个独立的高级文档存储引擎，基于 @go/tableDB 构建，提供全自动版本管理、历史存证、流式大文件处理及精细化生命周期钩子。

📦 安装

go get apigo.cc/go/docDB

🛠 核心功能

1. 路径驱动：以 Path 作为文档的唯一标识。
2. 版本管控：SetDoc 强制提升版本号并自动归档旧版；SetMeta 仅更新属性不触碰版本。
3. 智能 ToC：自动提取 Markdown 目录结构，支持代码块识别；SetMeta 更新正文时能自动重算 ToC。
4. 精细化事件：提供文档与目录（ToC）的增删改精细钩子，支持搜索引擎与知识库高效同步。
5. 历史存证：即使文档被删除，其所有历史版本依然可通过 GetByVersion 获取。
6. 权限隔离：完全继承 tableDB 的 RLS (Row Level Security) 体系。

🚀 API 指南

1. 初始化与授权

import (
    "apigo.cc/go/docDB"
    "apigo.cc/go/log"
)

// 获取引擎实例
engine := docDB.GetDB("sqlite://docs.db", log.DefaultLogger, "", "./storage_root")

// 授权
db := engine.Auth("user_123")

2. 文档操作

• SetDoc(doc *Document) error：保存文档，提升版本。触发 OnUpdatedDoc 和 OnUpdatedToC。
• SetMeta(path string, meta map[string]any) error：更新元数据，不提升版本。若包含 textContent 且为 Markdown，会自动触发 OnRemovedToC 和 OnUpdatedToC。
• Move(oldPath, newPath string) error：重命名。触发 OnRemovedDoc(oldPath) -> OnUpdatedDoc(newPath)。
• Get(path string) (*Document, error)：获取最新版。
• GetByVersion(path string, version uint64) (*Document, error)：获取历史版（含已删除）。
• Remove(path string) error：删除文档。触发 OnRemovedDoc。

3. 生命周期钩子 (Hooks)

// 文档级事件
engine.Hooks.OnUpdatedDoc = func(doc *docDB.Document) {
    // 文档创建或内容更新时触发 (SetDoc 或 Move 触发)
}
engine.Hooks.OnRemovedDoc = func(path string) {
    // 文档被物理删除或 Move 移除旧路径时触发
}

// 目录(ToC)级事件
engine.Hooks.OnUpdatedToC = func(path string, toc []docDB.ToCNode) {
    // 目录生成或变更时触发
}
engine.Hooks.OnRemovedToC = func(path string) {
    // 目录失效时触发
}

📝 数据结构

Document

字段	类型	说明
Path	string	核心标识
BinaryContent	io.Reader	瞬态流，用于上传
TextContent	string	正文内容
Version	uint64	版本号
ToC	[]ToCNode	目录树 (自动生成)

💡 注意事项

• SetMeta 行为：SetMeta 不会触发 OnUpdatedDoc，但如果更新了正文导致目录变化，会触发 ToC 相关事件。
• Move 行为：为了兼容搜索索引等外部系统，Move 被抽象为“删除旧路径文档”与“更新新路径文档”的组合操作。