DOC-FULL-003：ReadingEvent V2 #104

New Issue

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

wangdl commented

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

目标

定义 V2 阅读事件模型，作为 iOS 上传 API 的原始事件来源。

字段

eventId
clientSessionId
materialId
eventType
position
activeSecondsDelta
timestampMs
sequence

eventType

material_opened
position_changed
heartbeat
marked_as_read
material_closed

Rust 不生成字段

readingTargetType
platform
appVersion
clientTimezoneOffsetMinutes
userId
knowledgeBaseId

这些字段由 iOS / API 补充。

activeSecondsDelta 规则

material_opened: 0
position_changed: 0
marked_as_read: 0
heartbeat: 本次 tick 新增有效学习秒数
material_closed: 最后残余有效学习秒数

验收标准

新增 ReadingEvent V2 类型。
eventId 由 Rust 生成。
eventType 使用稳定枚举。
activeSecondsDelta 使用增量语义。
timestampMs 使用毫秒时间戳。
sequence 单 session 内递增。
不包含 readingTargetType。
可序列化为 FFI DTO。
有事件生成单元测试。

## 目标定义 V2 阅读事件模型，作为 iOS 上传 API 的原始事件来源。 ## 字段 - eventId - clientSessionId - materialId - eventType - position - activeSecondsDelta - timestampMs - sequence ## eventType - material_opened - position_changed - heartbeat - marked_as_read - material_closed ## Rust 不生成字段 - readingTargetType - platform - appVersion - clientTimezoneOffsetMinutes - userId - knowledgeBaseId 这些字段由 iOS / API 补充。 ## activeSecondsDelta 规则 - material_opened: 0 - position_changed: 0 - marked_as_read: 0 - heartbeat: 本次 tick 新增有效学习秒数 - material_closed: 最后残余有效学习秒数 ## 验收标准 1. 新增 ReadingEvent V2 类型。 2. eventId 由 Rust 生成。 3. eventType 使用稳定枚举。 4. activeSecondsDelta 使用增量语义。 5. timestampMs 使用毫秒时间戳。 6. sequence 单 session 内递增。 7. 不包含 readingTargetType。 8. 可序列化为 FFI DTO。 9. 有事件生成单元测试。

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

wangdl commented

2026-06-11 21:05:33 +08:00

完成证据

产物: crates/zx_document_core/src/events_v2.rs (已有 610 行 + 本次新增 31 行 delta 测试)
提交: a29ee12 feat: ReadingEvent V2 delta semantics verification (DOC-FULL-003)

ReadingEventV2 (已有)：

eventId (UUID v4), clientSessionId, materialId, eventType, position?, activeSecondsDelta, timestampMs, sequence
#[serde(rename_all = "camelCase")] + uniffi::Record
不含 readingTargetType / userId / knowledgeBaseId / platform / appVersion

ReadingEventTypeV2 (已有)：MaterialOpened / MaterialClosed / PositionChanged / Heartbeat / MarkedAsRead

activeSecondsDelta 语义：

MaterialOpened = 0
PositionChanged = 0
MarkedAsRead = 0
Heartbeat = 调用方传入的增量值
MaterialClosed = 残余活跃秒数

测试: 23 个测试 (22 已有 + 1 新增 delta semantics) — 168 passed / 0 failed (serial)

## 完成证据 **产物**: `crates/zx_document_core/src/events_v2.rs` (已有 610 行 + 本次新增 31 行 delta 测试) **提交**: `a29ee12` feat: ReadingEvent V2 delta semantics verification (DOC-FULL-003) **ReadingEventV2** (已有)： - eventId (UUID v4), clientSessionId, materialId, eventType, position?, activeSecondsDelta, timestampMs, sequence - `#[serde(rename_all = "camelCase")]` + `uniffi::Record` - **不含** readingTargetType / userId / knowledgeBaseId / platform / appVersion **ReadingEventTypeV2** (已有)：MaterialOpened / MaterialClosed / PositionChanged / Heartbeat / MarkedAsRead **activeSecondsDelta 语义**： - MaterialOpened = 0 - PositionChanged = 0 - MarkedAsRead = 0 - Heartbeat = 调用方传入的增量值 - MaterialClosed = 残余活跃秒数 **测试**: 23 个测试 (22 已有 + 1 新增 delta semantics) — 168 passed / 0 failed (serial)

wangdl closed this issue

2026-06-11 21:05:34 +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#104