DOC-FULL-003 P0 | ReadingEvent V2 【status:todo】 #52

New Issue

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

wangdl commented

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

v2 模型

pub struct ReadingEventV2 {
    pub event_id: String,  // Rust 生成 UUID
    pub client_session_id: String,
    pub material_id: String,
    pub event_type: ReadingEventTypeV2,
    pub position: Option<ReadingPosition>,
    pub active_seconds_delta: u32,  // 增量，非累计
    pub timestamp_ms: i64,
    pub sequence: u64,
}

delta 规则

MaterialOpened=0, PositionChanged=0, MarkedAsRead=0, Heartbeat=tick delta, MaterialClosed=残余 delta

V1 兼容

V1 保留 deprecated，不删除

## v2 模型 ```rust pub struct ReadingEventV2 { pub event_id: String, // Rust 生成 UUID pub client_session_id: String, pub material_id: String, pub event_type: ReadingEventTypeV2, pub position: Option<ReadingPosition>, pub active_seconds_delta: u32, // 增量，非累计 pub timestamp_ms: i64, pub sequence: u64, } ``` ## delta 规则 MaterialOpened=0, PositionChanged=0, MarkedAsRead=0, Heartbeat=tick delta, MaterialClosed=残余 delta ## V1 兼容 V1 保留 deprecated，不删除

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

wangdl changed title from ~~DOC-FULL-003 P0 | 重构 ReadingEvent V2：eventId / delta / target / sequence~~ to DOC-FULL-003 P0 | ReadingEvent V2

2026-06-07 11:45:14 +08:00

wangdl changed title from ~~DOC-FULL-003 P0 | ReadingEvent V2~~ to DOC-FULL-003 P0 | ReadingEvent V2 【status:todo】

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

wangdl commented

2026-06-07 19:15:00 +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: ReadingEvent V1 在用，V2 不存在。V1 缺 eventId/clientSessionId/sequence/delta。active_seconds 为累计值非增量。

状态: status:todo
工作类型: work:new-module

## 审查结论：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**: ReadingEvent V1 在用，V2 不存在。V1 缺 eventId/clientSessionId/sequence/delta。active_seconds 为累计值非增量。 **状态**: status:todo **工作类型**: work:new-module

wangdl closed this issue

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

wangdl commented

2026-06-07 19:37:20 +08:00

完成 ✅

crates/zx_document_core/src/events_v2.rs (286行)

模型

ReadingEventV2{event_id(UUID), client_session_id, material_id, event_type, position?, active_seconds_delta, timestamp_ms, sequence}
ReadingEventTypeV2: MaterialOpened|Closed|PositionChanged|Heartbeat|MarkedAsRead
#[serde(rename_all=camelCase)] JSON 输出

delta 规则

MaterialOpened=0, PositionChanged=0, MarkedAsRead=0, Heartbeat=tick, MaterialClosed=残余

push 函数

push_material_opened_v2/closed_v2/position_changed_v2/heartbeat_v2/marked_as_read_v2 — 全部集成 ReadingSessionV2

测试: 10 passed

5种事件生成正确类型+delta+sequence
session 集成
export+clear
closed session 拒绝事件
JSON serde roundtrip (含 position)

涉及文件

crates/zx_document_core/src/events_v2.rs (新建), lib.rs (+1行)

## 完成 ✅ `crates/zx_document_core/src/events_v2.rs` (286行) ### 模型 - ReadingEventV2{event_id(UUID), client_session_id, material_id, event_type, position?, active_seconds_delta, timestamp_ms, sequence} - ReadingEventTypeV2: MaterialOpened|Closed|PositionChanged|Heartbeat|MarkedAsRead - #[serde(rename_all=camelCase)] JSON 输出 ### delta 规则 MaterialOpened=0, PositionChanged=0, MarkedAsRead=0, Heartbeat=tick, MaterialClosed=残余 ### push 函数 push_material_opened_v2/closed_v2/position_changed_v2/heartbeat_v2/marked_as_read_v2 — 全部集成 ReadingSessionV2 ### 测试: 10 passed - 5种事件生成正确类型+delta+sequence - session 集成 - export+clear - closed session 拒绝事件 - JSON serde roundtrip (含 position) ### 涉及文件 crates/zx_document_core/src/events_v2.rs (新建), lib.rs (+1行)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#52