docDB/README.md

# @go/docDB v1.0.9

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

## 📦 安装

```bash
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. 初始化与授权

```go
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(oldDoc)` -> `OnUpdatedDoc(newDoc)`。
- **`Get(path string) (*Document, error)`**：获取最新版。
- **`GetByVersion(path string, version uint64) (*Document, error)`**：获取历史版（含已删除）。
- **`Remove(path string) error`**：删除文档。触发 `OnRemovedDoc(doc)`。

### 3. 生命周期钩子 (Hooks)

```go
// 所有 Hook 统一返回 *Document 对象，方便外部获取 Path, ToC, Metadata 等完整上下文
engine.Hooks.OnUpdatedDoc = func(doc *docDB.Document) {
    // 文档创建或内容更新时触发 (SetDoc 或 Move 触发)
}
engine.Hooks.OnRemovedDoc = func(doc *docDB.Document) {
    // 文档被物理删除或 Move 移除旧路径时触发
}

// 目录(ToC)级事件
engine.Hooks.OnUpdatedToC = func(doc *docDB.Document) {
    // 目录生成或变更时触发
}
engine.Hooks.OnRemovedToC = func(doc *docDB.Document) {
    // 目录失效时触发
}
```

## 📝 数据结构

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

## 💡 注意事项

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