DOC-FULL-031 P1 | 文档：ReadingEvent 协议【status:partial】 #80

New Issue

wangdl · 2026-06-07T11:33:20+08:00

wangdl commented

2026-06-07 11:33:20 +08:00

ReadingTarget/Session/EventV2/eventId/clientSessionId/sequence/activeSecondsDelta/position/EventBuffer/export ack/与 API 字段映射

M-DOC-FULL 里程碑 issue。详见设计文档。

## ReadingTarget/Session/EventV2/eventId/clientSessionId/sequence/activeSecondsDelta/position/EventBuffer/export ack/与 API 字段映射 M-DOC-FULL 里程碑 issue。详见设计文档。

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

wangdl changed title from ~~DOC-FULL-031 P1 | 文档：ReadingEvent 协议~~ to DOC-FULL-031 P1 | 文档：ReadingEvent 协议【status:partial】

2026-06-07 19:15:07 +08:00

wangdl commented

2026-06-07 19:15:08 +08:00

审查结论：document runtime 当前有文件类型识别/MaterialType/PreviewMode/DocumentInfo(基本)/Markdown解析/Text解析/ImageMeta/Search(V1 Markdown+Text)/NoteAnchor(V1)/ReadingEvent(V1)/ReadingPosition(V1)/EventBuffer(V1基础)/iOS构建/UniFFI绑定/docs。但 V2 核心模型(ReadingSession/EventV2/ActiveTimeTracker)不存在，EventBuffer 缺 ack/failed，Position 缺 camelCase+clamp，PDF/EPUB/Office 为 stub，测试覆盖不足 V2。

本 Issue: docs/event-protocol.md 存在。需对齐 V2 和 API 协议。blocked-by:doc-v2-core

状态: status:partial
工作类型: work:docs

## 审查结论：document runtime 当前有文件类型识别/MaterialType/PreviewMode/DocumentInfo(基本)/Markdown解析/Text解析/ImageMeta/Search(V1 Markdown+Text)/NoteAnchor(V1)/ReadingEvent(V1)/ReadingPosition(V1)/EventBuffer(V1基础)/iOS构建/UniFFI绑定/docs。但 V2 核心模型(ReadingSession/EventV2/ActiveTimeTracker)不存在，EventBuffer 缺 ack/failed，Position 缺 camelCase+clamp，PDF/EPUB/Office 为 stub，测试覆盖不足 V2。 **本 Issue**: docs/event-protocol.md 存在。需对齐 V2 和 API 协议。blocked-by:doc-v2-core **状态**: status:partial **工作类型**: work:docs

wangdl commented

2026-06-07 22:01:12 +08:00

完成报告

新增文档

docs/reading-event-protocol.md — 完整 V2 协议文档：

ReadingSessionV2 结构 + 生命周期（Active→Paused→Active→Closed）
ReadingMaterialRef（material_id only，readingTargetType 由 iOS 补充）
ReadingEventV2 字段详解（eventId UUID/clientSessionId/sequence/activeSecondsDelta/position/timestamp）
eventType 5 种取值 + Rust↔API 映射
activeSecondsDelta 规则表
ActiveTimeTracker 工作原理（iOS tick→Rust delta）
EventBuffer 状态机（Pending→Exported→Acked/Failed，含 recover）
溢出驱逐策略（Failed→Exported→oldest Pending）
API 上传字段映射表
iOS 上传流程 7 步

已有文档

docs/reading-event-v2-api-mapping.md — API 字段映射速查

## 完成报告 ### 新增文档 `docs/reading-event-protocol.md` — 完整 V2 协议文档： - ReadingSessionV2 结构 + 生命周期（Active→Paused→Active→Closed） - ReadingMaterialRef（material_id only，readingTargetType 由 iOS 补充） - ReadingEventV2 字段详解（eventId UUID/clientSessionId/sequence/activeSecondsDelta/position/timestamp） - eventType 5 种取值 + Rust↔API 映射 - activeSecondsDelta 规则表 - ActiveTimeTracker 工作原理（iOS tick→Rust delta） - EventBuffer 状态机（Pending→Exported→Acked/Failed，含 recover） - 溢出驱逐策略（Failed→Exported→oldest Pending） - API 上传字段映射表 - iOS 上传流程 7 步 ### 已有文档 `docs/reading-event-v2-api-mapping.md` — API 字段映射速查

wangdl closed this issue

2026-06-07 22:01:56 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#80

DOC-FULL-031 P1 | 文档：ReadingEvent 协议 【status:partial】 #80

ReadingTarget/Session/EventV2/eventId/clientSessionId/sequence/activeSecondsDelta/position/EventBuffer/export ack/与 API 字段映射

完成报告

新增文档

已有文档

DOC-FULL-031 P1 | 文档：ReadingEvent 协议【status:partial】 #80