mnote/rust/design/core/03-storage-event-indexing-v0.md

# 03. Storage / Event / Indexing v0

更新时间：2026-04-11
适用范围：`/mnt/Data1T/mnote-rust`

---

## 1. 目标

本文件定义 `mnote-rust` 在当前路线下的持久化、事件日志、索引体系。

它要回答：

- 当前系统事实层应落在哪里
- Rust 内核怎样接入既有事实层而不重复造库
- 写操作如何进入事件链路
- 搜索、引用、RAG、回放、审计依赖什么数据面
- 如何既保证性能，又保证 AI 可观测、可维护、可回放

这部分的前提必须先讲清：

> 对当前 `mnote` / `mnote-next` 主线来说，**Convex 仍是主事实层**。

因此，这份文档不再讨论“用 SQLite 取代 Convex 做主库”，而是讨论：

- 如何在 **Convex 主事实层** 之上建立 Rust 内核
- 如何把索引、事件、导出、离线缓存、本地处理组织清楚
- 如何避免再次引入第二套事实真相

如果这层设计不好，系统最终仍会退化成：

- 页面组件自己维护真相
- 各类能力各写各的缓存
- AI 看不到完整上下文
- Rust 内核与现有系统各管一套数据
- 回滚、审计、重建索引都变得困难

---

## 2. 总原则

### 2.1 主事实层、事件日志、索引必须分层

三者职责不同：

- **主事实层**：保存系统当前真相
- **事件日志**：保存“如何变成现在”的过程
- **索引层**：为检索、聚合、推荐、RAG 提供加速读模型

禁止让任一层越权：

- 不能拿索引当真相
- 不能只靠事件流而没有可直接读取的当前状态
- 不能让页面缓存成为事实层
- 不能让本地缓存演化成第二主库

### 2.2 当前主事实层应继续落在 Convex

基于 `mnote` 与 `mnote-next` 已有主线，当前阶段应坚持：

- **Convex 是唯一主事实层**
- Rust 内核通过协议与 bridge 接入 Convex，而不是绕开它再建一套主库
- 旧仓与新仓共享的核心对象，应优先复用既有 Convex schema / deployment / caller 体系

这不是保守，而是避免推翻已经跑通的主链路。

### 2.3 本地文件系统与本地嵌入式存储仍然重要

虽然主事实层继续用 Convex，但本地层仍然需要：

- **文件系统**：资产原文件、导出文件、缓存、派生产物、临时工作目录
- **可选本地嵌入式存储**：离线缓存、索引快照、dry-run、调试态数据、临时队列

但这些都不能升级为新的主事实层。

### 2.4 写入必须原子化到“主事实层 + 事件落账”

一次命令成功后，至少要保证：

- 主事实层写入完成
- 事件写入成功
- 命令日志有记录

索引允许异步追平，但必须可检测 lag。

### 2.5 索引必须可重建

搜索索引、向量索引、聚合视图都必须满足：

- 可从主事实层 + 事件重新构建
- 可做全量重建
- 可做增量追平

否则后期会不可维护。

---

## 3. 三层数据面

```text
[主事实层]
Convex + FileSystem

[事件与日志层]
CommandLog + DomainEvent + JobLog + AuditTrail

[索引与派生层]
FTS / Reference Graph / Backlink View / Outline View / Vector Index
```

### 3.1 主事实层负责

- Workspace / Page / Block / Asset / Reference / Task / AgentSession 当前状态
- 事务性写入
- 读取当前真相
- 提供稳定 schema
- 承担权限与主对象约束

### 3.2 事件与日志层负责

- 记录命令与事件
- 记录 actor、reason、scope、结果
- 支持回放、审计、问题追踪
- 作为索引增量更新输入

### 3.3 索引与派生层负责

- 全文搜索
- 页面大纲
- 反链
- 资产片段搜索
- RAG 检索读模型
- 推荐 / 关系聚合

---

## 4. 主事实层选型

## 4.1 当前阶段的明确结论

推荐：

- **Convex**：结构化主事实层
- **File System**：存原始资产与大对象
- **Rust bridge / protocol layer**：作为统一命令、查询、工具接入面

原因：

- 与 `mnote` 中“Convex 已完全替换 Supabase”的现实一致
- 与 `mnote-next` 中“默认复用现有 Convex deployment / project”的路线一致
- 复用现有 deployment、schema、自建与 AI 开发经验，避免重建第二套数据库主线
- 更符合“复用成熟能力，重构边界，不做无意义重建”的迁移原则

## 4.2 本地嵌入式存储的正确定位

可以保留本地嵌入式存储，但只限于：

- CLI / Agent 的离线缓存
- 全文索引引擎的本地数据文件
- dry-run / scaffold / 调试态数据
- 单机导入处理中的临时工作库

不能把它写成：

- 第二套主事实层
- 与 Convex 并列的正式写入真相
- 长期双写的核心业务库

## 4.3 不建议的中心方案

- 用 SQLite 取代 Convex 成为主真相
- OnlyOffice / 第三方编辑器内部状态作为主真相
- 仅事件溯源、无当前态表
- 单纯 Markdown 文件散落 + 大量 sidecar 作为唯一结构源
- 长期维护 Convex + SQLite 双事实源

这些都会让系统再次陷入边界混乱。

---

## 5. 主事实对象结构建议

这里讨论的是**领域对象结构**，不是要求新建第二套数据库。

## 5.1 结构原则

- 主对象必须能映射到现有 Convex schema
- 单对象一组稳定字段或有限关联表
- 避免过度 EAV
- JSON 仅用于局部扩展字段，不替代主 schema

## 5.2 建议主对象

至少包含：

- `workspaces`
- `pages`
- `page_versions`（可选）
- `blocks`
- `block_relations`（可选，若不全放在 block 表中）
- `assets`
- `asset_versions`
- `references`
- `tasks`
- `agent_sessions`
- `command_logs`
- `domain_events`
- `jobs`
- `job_logs`

这些对象应优先映射或扩展到现有 Convex 主线，而不是在新仓先落一套平行本地表。

## 5.3 blocks 对象建议

关键字段：

- `block_id`
- `workspace_id`
- `page_id`
- `parent_block_id`
- `sort_key`
- `block_type`
- `content_json`
- `props_json`
- `annotations_json`
- `revision`
- `deleted_at`

说明：

- `sort_key` 建议支持稀疏排序，避免频繁全量重排
- 软删除优于直接硬删，方便审计与恢复
- `revision` 用于乐观并发控制

## 5.4 assets 对象建议

- `asset_id`
- `workspace_id`
- `asset_kind`
- `mime_type`
- `current_version_id`
- `storage_strategy`
- `status`
- `metadata_json`

## 5.5 references 对象建议

- `reference_id`
- `source_object_type`
- `source_object_id`
- `target_object_type`
- `target_object_id`
- `anchor_json`
- `ref_kind`
- `status`

---

## 6. 文件系统布局建议

资产不要全塞数据库 blob。

建议：

```text
workspace-data/
├─ assets/
│  ├─ asset_xxx/
│  │  ├─ v1/original.docx
│  │  ├─ v2/original.docx
│  │  ├─ extracted/outline.json
│  │  ├─ extracted/text.md
│  │  └─ derived/preview.png
├─ indexes/
│  ├─ fts/
│  └─ vector/
├─ runtime/
│  ├─ jobs/
│  ├─ sessions/
│  └─ temp/
└─ export/
```

原则：

- 结构化真相仍以 Convex 为主
- 原始大文件入文件系统
- 派生产物有明确目录归属
- 临时文件与正式资产分离

---

## 7. Command Log

`CommandLog` 是所有写命令的正式记录。

### 7.1 最低字段

- `command_log_id`
- `command_name`
- `actor_type`
- `actor_id`
- `source`
- `workspace_id`
- `target_objects`
- `payload_summary`
- `refs_json`
- `idempotency_key`
- `status`
- `created_at`
- `finished_at`

### 7.2 设计要求

- 能关联到一次真实主写入
- 能关联后续 domain events
- 能关联 tool call / job / rollback
- 能为 AI 回放与人类审计提供最小闭包

### 7.3 与 Convex 的关系

命令日志可以：

- 直接进入 Convex 主线对象
- 或通过 bridge 落到与主对象同一事实层

但不要单独把命令日志只记在本地、主对象却记在远端；那会破坏统一审计链路。

---

## 8. Domain Event

`DomainEvent` 不是为了炫技，而是为了：

- 给索引层提供标准增量输入
- 给回放和审计提供结构化事件
- 给异步任务提供稳定订阅源

### 8.1 事件最低字段

- `event_id`
- `workspace_id`
- `aggregate_type`
- `aggregate_id`
- `event_type`
- `event_version`
- `payload_json`
- `command_log_id`
- `actor_type`
- `created_at`

### 8.2 事件边界

建议记录领域事件，而不是 UI 手势。

例如：

- `page_created`
- `page_renamed`
- `block_inserted`
- `block_moved`
- `block_content_replaced`
- `asset_version_added`
- `reference_created`
- `task_status_changed`

不建议记录：

- 弹窗打开
- 光标移动
- hover 展示
- 面板折叠

---

## 9. Job 与异步链路

不是所有事情都应进主事务。

应把这些放入 Job：

- OCR
- OnlyOffice 提取/转换
- 向量切片与嵌入
- 全量重建索引
- 大文件导入
- 外部同步

### 9.1 Job 最低字段

- `job_id`
- `job_type`
- `workspace_id`
- `target_objects`
- `input_json`
- `status`
- `progress`
- `error`
- `created_at`
- `started_at`
- `finished_at`

### 9.2 不能放进主事务的内容

- 大模型推理
- OCR
- 大文件转换
- 向量重建
- 远程同步

这些必须走 Job。

---

## 10. 索引体系

## 10.1 Full Text Search

最低必做：

- 页面标题全文检索
- 块内容全文检索
- 资产提取文本全文检索
- 引用 snippet 检索

建议：

- 初期直接用本地全文索引引擎（如 SQLite FTS5、Tantivy 或兼容方案）
- 索引文档单位统一为“可定位对象”

例如：

- page
- block
- asset_fragment
- reference_snippet

### 10.2 为什么块级索引重要

因为你的产品最终不是“整篇文档搜索”，而是：

- 找到某一段
- 跳回块位置
- 让 AI 只编辑局部
- 给引用与上下文最小闭包

## 10.3 Reference Graph

必须维护引用图读模型：

- page -> page
- block -> block
- block -> asset fragment
- task -> source object

这对：

- 反链
- 影响面分析
- AI 上下文组装
- 知识导航

都很关键。

## 10.4 Outline View

页面大纲、Office 文档提取大纲、PDF 目录、Mindmap 树都应是派生读模型。

优点：

- 不污染主事实层
- 允许多种提取策略
- 容易重建

## 10.5 Vector Index

向量索引建议延后，但结构上预留。

原则：

- 向量索引只是检索加速层
- 向量 chunk 必须能回指 `page_id / block_id / asset_id / anchor`
- 向量索引失效可重建，不影响系统主真相

---

## 11. 索引更新策略

## 11.1 起步建议：异步增量 + 可全量重建

每次事件提交后：

- 生成索引任务
- 按对象粒度增量更新
- 记录 lag 与最后处理 event id

## 11.2 索引一致性要求

- 主事实层一致性 > 索引实时性
- 查询可返回“索引处理中”状态
- 对必须强一致的局部场景，可同步刷新小范围索引

## 11.3 失败恢复

索引 worker 挂了也不能影响主写入。

必须支持：

- 从 `last_processed_event_id` 继续追平
- 指定对象重建
- 指定 workspace 全量重建

### 11.4 回放与索引重建的正式入口

从 task-034 开始，回放和重建不再只是“库里有个纯函数”，而要成为统一命令面的一部分。

最小要求：

- `event_replay`：从统一事件列表读取，输出 replay 后的 `cursor` 与受影响 event 摘要
- `index_rebuild`：基于 `last_processed_event_id` / `last_processed_at` 重建索引批次，并返回新的 cursor
- 两者都复用同一套 `request_id`、`trace_id`、`workspace_id`、`command_id` 语义，不允许临时脚本私有解释

这意味着后续无论是 CLI、AI 还是 Web 排障，都应先调用同一条 Rust 恢复命令面，而不是各自写一套索引补数脚本。

---

## 12. AI 可观测性

AI 全流程介入后，系统必须能回答：

- 某次回答引用了哪些对象
- 某次编辑基于哪些上下文
- 某个工具为什么失败
- 当前搜索索引是否滞后
- 哪些对象正在被长任务处理

因此建议额外维护：

### 12.1 AgentSession 关联表

- `agent_session_objects`
- `agent_session_tool_calls`
- `agent_session_outputs`

### 12.2 Tool Call Log

记录：

- tool name
- input
- output summary
- duration
- error
- command_log_id / query trace id

这样后期 AI 排障、回放、评估都会容易很多。

---

## 13. 性能关键点

### 13.1 不要整页全文重写

编辑块时，只更新相关块与局部派生视图。

### 13.2 不要同步重建全索引

任何全库重建都必须后台化。

### 13.3 资产处理走异步

OCR、Office 转换、预览图生成、向量切片都不能阻塞主编辑事务。

### 13.4 读写模型分离

高频 UI 读需求可通过派生视图优化，不要污染主事实 schema。

---

## 14. OnlyOffice 在存储层的正确位置

OnlyOffice 相关对象建议这样落地：

- 原始 `docx/xlsx/pptx/pdf`：作为 `Asset` + `AssetVersion`
- 文档编辑结果：生成新 `AssetVersion`
- 提取结构（目录、批注、书签、文本片段）：作为派生读模型或 `Reference`
- 当前选区、当前页码：作为短生命周期 `SelectionAnchor`

不要把：

- OnlyOffice 内部文档状态
- 插件瞬时 UI 状态
- callback 的临时 payload

直接当成主事实层。

---

## 15. 迁移建议

先做：

1. 盘点现有 Convex schema 与 `mnote-rust` 领域对象的映射
2. 落 `CommandLog / DomainEvent` 的主事实层方案
3. 落 `Page / Block / Asset / Reference` 的 bridge / repo 接口
4. 建立全文索引最小实现
5. 建立索引 worker 骨架

再做：

6. AgentSession / ToolCallLog
7. Outline / Backlink 读模型
8. 向量索引占位
9. Office / OCR / Mindmap 派生索引
10. 必要的离线缓存 / dry-run 本地层

---

## 16. 一句话结论

`mnote-rust` 当前应采用 **Convex 主事实层 + FileSystem 资产存储 + CommandLog/DomainEvent 事件链路 + 可重建全文/引用/向量索引** 的分层结构；
Rust 内核负责把命令、查询、工具、索引、异步任务与外部能力重新组织清楚，而不是再造一套与现有主线并列的数据库事实源。