DOC-FULL-000：Document Runtime V2 总体架构文档 #101

New Issue

wangdl · 2026-06-10T21:18:32+08:00

wangdl commented

2026-06-10 21:18:32 +08:00

目标

输出 Document Runtime V2 架构文档，明确 Rust document runtime 在知习学习信息收集体系中的职责边界、事件模型、FFI 边界、iOS 嵌入方式、V1/V2 兼容策略。

核心原则

Rust document runtime 只负责文档解析、阅读状态、阅读事件、位置、搜索、锚点。
Rust 不负责用户业务身份。
Rust 不保存 readingTargetType。
Rust 只保存 materialId。
readingTargetType = knowledge_source / temporary_file 由 iOS / API 负责。
iOS 控制 heartbeat tick。
Rust 只根据 timestamp 计算 activeSecondsDelta。
Rust EventBuffer 不是长期可靠队列。
Rust export 后，iOS 写入本地 ReadingEventUploadQueue 成功后才 ack。
Rust ack 后立即删除 buffer 事件。
V1 保留 deprecated，不直接删除。
V2 新增独立模块，不破坏旧接口。

文档必须覆盖

模块结构
V1 / V2 边界
ReadingMaterialRef
ReadingSession V2
ReadingEvent V2
ReadingPosition V2
ActiveTimeTracker
EventBuffer
FFI DTO
export / ack / failed 流程
iOS 嵌入流程
XCFramework / UniFFI 生成关系
与 API 上传协议的映射边界
错误码与 warning 设计
测试范围

不做范围

不接入 API。
不直接上传服务器。
不处理 userId。
不处理 platform / appVersion。
不处理 readingTargetType。
不处理 knowledgeBaseId。
不做 iOS 本地上传队列。
不做 iOS UI。

验收标准

新增 docs/document-runtime-v2-architecture.md。
文档明确 Rust 不保存 readingTargetType。
文档明确 iOS 控制 tick，Rust 计算 delta。
文档明确 export → iOS queue → ack 的顺序。
文档明确 V1 deprecated、V2 独立模块。
文档明确 FFI 暴露接口。
文档明确和 iOS / API 的职责边界。
文档能指导 DOC-FULL-001~008 实现。

## 目标输出 Document Runtime V2 架构文档，明确 Rust document runtime 在知习学习信息收集体系中的职责边界、事件模型、FFI 边界、iOS 嵌入方式、V1/V2 兼容策略。 ## 核心原则 1. Rust document runtime 只负责文档解析、阅读状态、阅读事件、位置、搜索、锚点。 2. Rust 不负责用户业务身份。 3. Rust 不保存 readingTargetType。 4. Rust 只保存 materialId。 5. readingTargetType = knowledge_source / temporary_file 由 iOS / API 负责。 6. iOS 控制 heartbeat tick。 7. Rust 只根据 timestamp 计算 activeSecondsDelta。 8. Rust EventBuffer 不是长期可靠队列。 9. Rust export 后，iOS 写入本地 ReadingEventUploadQueue 成功后才 ack。 10. Rust ack 后立即删除 buffer 事件。 11. V1 保留 deprecated，不直接删除。 12. V2 新增独立模块，不破坏旧接口。 ## 文档必须覆盖 - 模块结构 - V1 / V2 边界 - ReadingMaterialRef - ReadingSession V2 - ReadingEvent V2 - ReadingPosition V2 - ActiveTimeTracker - EventBuffer - FFI DTO - export / ack / failed 流程 - iOS 嵌入流程 - XCFramework / UniFFI 生成关系 - 与 API 上传协议的映射边界 - 错误码与 warning 设计 - 测试范围 ## 不做范围 - 不接入 API。 - 不直接上传服务器。 - 不处理 userId。 - 不处理 platform / appVersion。 - 不处理 readingTargetType。 - 不处理 knowledgeBaseId。 - 不做 iOS 本地上传队列。 - 不做 iOS UI。 ## 验收标准 1. 新增 docs/document-runtime-v2-architecture.md。 2. 文档明确 Rust 不保存 readingTargetType。 3. 文档明确 iOS 控制 tick，Rust 计算 delta。 4. 文档明确 export → iOS queue → ack 的顺序。 5. 文档明确 V1 deprecated、V2 独立模块。 6. 文档明确 FFI 暴露接口。 7. 文档明确和 iOS / API 的职责边界。 8. 文档能指导 DOC-FULL-001~008 实现。

wangdl added this to the M-DOC-FULL：Document Runtime 完整阅读内核与学习事件协议 milestone 2026-06-10 21:18:32 +08:00

wangdl added the

priority:p0

area:document-runtime

repo:document-runtime

labels 2026-06-10 21:18:32 +08:00

Sign in to join this conversation.