DOC-FULL-002 P0 | ReadingSession V2 【status:todo】 #51

New Issue

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

wangdl commented

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

v2 模型

pub struct ReadingSessionV2 {
    pub client_session_id: String,  // Rust 生成 UUID
    pub material: ReadingMaterialRef,
    pub started_at_ms: i64,
    pub last_event_at_ms: i64,
    pub next_sequence: u64,
    pub total_active_seconds: u32,
    pub last_position: Option<ReadingPosition>,
    pub status: ReadingSessionStatus,  // Active|Paused|Closed
}

API

start_reading_session / pause / resume / close / get_client_session_id

规则

sequence 从 1 递增
pause 后不计 active time
close 后不允许 heartbeat

## v2 模型 ```rust pub struct ReadingSessionV2 { pub client_session_id: String, // Rust 生成 UUID pub material: ReadingMaterialRef, pub started_at_ms: i64, pub last_event_at_ms: i64, pub next_sequence: u64, pub total_active_seconds: u32, pub last_position: Option<ReadingPosition>, pub status: ReadingSessionStatus, // Active|Paused|Closed } ``` ## API start_reading_session / pause / resume / close / get_client_session_id ## 规则 - sequence 从 1 递增 - pause 后不计 active time - close 后不允许 heartbeat

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-002 P0 | 重构 ReadingSession：clientSessionId / sequence / lifecycle~~ to DOC-FULL-002 P0 | ReadingSession V2

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

wangdl changed title from ~~DOC-FULL-002 P0 | ReadingSession V2~~ to DOC-FULL-002 P0 | ReadingSession 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: ReadingSession 不存在。无 clientSessionId/sequence/lifecycle。iOS 侧自行管理 session(ReadingEventCollector)。

状态: 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**: ReadingSession 不存在。无 clientSessionId/sequence/lifecycle。iOS 侧自行管理 session(ReadingEventCollector)。 **状态**: status:todo **工作类型**: work:new-module

wangdl closed this issue

2026-06-07 19:35:12 +08:00

wangdl commented

2026-06-07 19:35:12 +08:00

完成情况 ✅

交付物

crates/zx_document_core/src/session_v2.rs (255行)

模型

pub struct ReadingSessionV2 {
    pub client_session_id: String,   // UUID，Rust 生成
    pub material: ReadingMaterialRef,
    pub started_at_ms: i64,
    pub last_event_at_ms: i64,
    pub next_sequence: u64,          // 从 1 递增
    pub total_active_seconds: u32,
    pub last_position: Option<ReadingPosition>,
    pub status: ReadingSessionStatus,  // Active|Paused|Closed
}

API

start_reading_session_v2(material, timestamp_ms) → clientSessionId
pause_reading_session_v2(session_id) / resume / close
record_session_event_v2(session_id, ts, delta, position) → sequence
get_session_v2(session_id) / remove_session_v2(session_id)

规则

start 生成 UUID clientSessionId
sequence 从 1 递增
pause 后拒绝 delta>0 的事件（允许 delta=0 的 PositionChanged）
close 后拒绝所有事件
两个 session 独立运行
OnceLock<Mutex<HashMap>> 线程安全

测试

test session_v2: 7 passed, 0 failed
  test_start_session
  test_pause_resume_close
  test_sequence_increments
  test_closed_rejects_events
  test_paused_rejects_active_seconds
  test_not_found
  test_two_sessions_independent

涉及文件

文件	变更
crates/zx_document_core/src/session_v2.rs	新建
crates/zx_document_core/src/lib.rs	+1行

## 完成情况 ✅ ### 交付物 `crates/zx_document_core/src/session_v2.rs` (255行) ### 模型 ```rust pub struct ReadingSessionV2 { pub client_session_id: String, // UUID，Rust 生成 pub material: ReadingMaterialRef, pub started_at_ms: i64, pub last_event_at_ms: i64, pub next_sequence: u64, // 从 1 递增 pub total_active_seconds: u32, pub last_position: Option<ReadingPosition>, pub status: ReadingSessionStatus, // Active|Paused|Closed } ``` ### API - `start_reading_session_v2(material, timestamp_ms)` → clientSessionId - `pause_reading_session_v2(session_id)` / `resume` / `close` - `record_session_event_v2(session_id, ts, delta, position)` → sequence - `get_session_v2(session_id)` / `remove_session_v2(session_id)` ### 规则 - start 生成 UUID clientSessionId - sequence 从 1 递增 - pause 后拒绝 delta>0 的事件（允许 delta=0 的 PositionChanged） - close 后拒绝所有事件 - 两个 session 独立运行 - `OnceLock<Mutex<HashMap>>` 线程安全 ### 测试 ``` test session_v2: 7 passed, 0 failed test_start_session test_pause_resume_close test_sequence_increments test_closed_rejects_events test_paused_rejects_active_seconds test_not_found test_two_sessions_independent ``` ### 涉及文件 | 文件 | 变更 | |------|------| | crates/zx_document_core/src/session_v2.rs | 新建 | | crates/zx_document_core/src/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#51