DOC-FULL-002：ReadingSession V2 #103

New Issue

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

wangdl commented

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

目标

实现 V2 阅读会话模型。一次打开资料到关闭资料为一个 ReadingSession。

字段建议

clientSessionId
materialId
openedAtMs
closedAtMs?
lastEventAtMs
lastPosition?
sequence
status

status

active
closed
interrupted
failed

规则

clientSessionId 由 Rust 生成。
每个 session 内 sequence 单调递增。
ReadingSession 不保存 readingTargetType。
ReadingSession 不保存 userId。
MaterialOpened 创建 session。
MaterialClosed 关闭 session。
interrupted 用于异常中断或未正常 close 场景。

需要提供的方法

openSession(materialRef, timestampMs)
closeSession(clientSessionId, position?, timestampMs)
getActiveSession(materialId)
markSessionInterrupted(clientSessionId)

验收标准

openSession 可生成 clientSessionId。
closeSession 可关闭 active session。
sequence 在同一 session 内递增。
Session 不包含业务字段。
异常中断可标记 interrupted。
有单元测试。
可通过 FFI 暴露必要接口。

## 目标实现 V2 阅读会话模型。一次打开资料到关闭资料为一个 ReadingSession。 ## 字段建议 - clientSessionId - materialId - openedAtMs - closedAtMs? - lastEventAtMs - lastPosition? - sequence - status ## status - active - closed - interrupted - failed ## 规则 1. clientSessionId 由 Rust 生成。 2. 每个 session 内 sequence 单调递增。 3. ReadingSession 不保存 readingTargetType。 4. ReadingSession 不保存 userId。 5. MaterialOpened 创建 session。 6. MaterialClosed 关闭 session。 7. interrupted 用于异常中断或未正常 close 场景。 ## 需要提供的方法 ``` openSession(materialRef, timestampMs) closeSession(clientSessionId, position?, timestampMs) getActiveSession(materialId) markSessionInterrupted(clientSessionId) ``` ## 验收标准 1. openSession 可生成 clientSessionId。 2. closeSession 可关闭 active session。 3. sequence 在同一 session 内递增。 4. Session 不包含业务字段。 5. 异常中断可标记 interrupted。 6. 有单元测试。 7. 可通过 FFI 暴露必要接口。

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:03:39 +08:00

完成证据

产物: crates/zx_document_core/src/session_v2.rs (+141 行), crates/zx_document_ffi/src/lib.rs (+25 行)
提交: c30957e feat: ReadingSession V2 complete (DOC-FULL-002)

新增状态: Interrupted / Failed（+ 原有 Active / Paused / Closed）

新增字段: closedAtMs (Option)

新增方法:

mark_session_interrupted_v2 / mark_session_failed_v2
get_active_session_v2 (按 materialId 查询)
set_session_closed_at_ms (独立设置关闭时间)

FFI 暴露: 6 个新接口 (set_session_closed_at_ms_v2 / mark_session_interrupted_v2 / mark_session_failed_v2 / get_active_session_v2 / get_session_v2_ffi)

规则验证:

Session 不保存 readingTargetType / userId / knowledgeBaseId（编译时保证）
sequence 单 session 内单调递增
close / interrupted / failed 幂等

构建: cargo check 0 errors, cargo test 167 passed / 0 failed

## 完成证据 **产物**: `crates/zx_document_core/src/session_v2.rs` (+141 行), `crates/zx_document_ffi/src/lib.rs` (+25 行) **提交**: `c30957e` feat: ReadingSession V2 complete (DOC-FULL-002) **新增状态**: Interrupted / Failed（+ 原有 Active / Paused / Closed） **新增字段**: closedAtMs (Option<i64>) **新增方法**: - mark_session_interrupted_v2 / mark_session_failed_v2 - get_active_session_v2 (按 materialId 查询) - set_session_closed_at_ms (独立设置关闭时间) **FFI 暴露**: 6 个新接口 (set_session_closed_at_ms_v2 / mark_session_interrupted_v2 / mark_session_failed_v2 / get_active_session_v2 / get_session_v2_ffi) **规则验证**: - Session 不保存 readingTargetType / userId / knowledgeBaseId（编译时保证） - sequence 单 session 内单调递增 - close / interrupted / failed 幂等 **构建**: cargo check 0 errors, cargo test 167 passed / 0 failed

wangdl closed this issue

2026-06-11 21:03:39 +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#103