From 7f79802e0a69dc62e3e8d3c8c95d5cc9bc3c1d22 Mon Sep 17 00:00:00 2001
From: wangdl <wangdl@longde.cloud>
Date: Thu, 11 Jun 2026 21:10:58 +0800
Subject: [PATCH] docs: update V2 architecture to reflect DOC-FULL-001~006
 changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ReadingMaterialRef → ReadingMaterialRefV2 (full fields, camelCase)
- ReadingSessionV2: add closed_at_ms, Interrupted/Failed statuses
- EventBuffer: add reload_stale_events_v2, buffer_size_v2
- V1/V2 diff table: add session status/recovery rows
- Verification chain: add startup recovery + V2 MaterialRef

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 docs/document-runtime-architecture.md | 51 ++++++++++++++++++++-------
 1 file changed, 38 insertions(+), 13 deletions(-)

diff --git a/docs/document-runtime-architecture.md b/docs/document-runtime-architecture.md
index 4e4fc45..28ec80e 100644
--- a/docs/document-runtime-architecture.md
+++ b/docs/document-runtime-architecture.md
@@ -103,29 +103,43 @@ Rust exportPendingEventsV2 → iOS 写本地队列 → iOS ackEventsV2(eventIds)
 
 ## 3. 核心 V2 模型
 
-### 3.1 ReadingMaterialRef
+### 3.1 ReadingMaterialRefV2
 
 ```rust
-pub struct ReadingMaterialRef {
-    pub material_id: String,
+pub struct ReadingMaterialRefV2 {
+    pub material_id: String,         // 业务 ID
+    pub file_path: String,           // 本地文件路径
+    pub file_name: String,           // 文件名
+    pub file_type: String,           // markdown / pdf / epub / text / image / office
+    pub mime_type: Option<String>,   // MIME 类型（可选）
+    pub file_size: Option<u64>,      // 文件大小字节（可选）
+    pub content_hash: Option<String>,// 内容哈希（可选）
+    pub created_at_ms: Option<i64>,  // 创建时间毫秒（可选）
 }
 ```
 
+不包含：`readingTargetType`, `userId`, `knowledgeBaseId`, `platform`, `appVersion`。
+
+V1 `ReadingMaterialRef`（仅 `material_id`）标记 `#[deprecated]`，保留不删除。
+
 ### 3.2 ReadingSessionV2
 
 ```rust
 pub struct ReadingSessionV2 {
     pub client_session_id: String,   // UUID, Rust 生成
-    pub material: ReadingMaterialRef,
+    pub material: ReadingMaterialRefV2,
     pub started_at_ms: i64,
+    pub closed_at_ms: Option<i64>,   // 关闭时间（由 iOS 传入）
     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
+    pub status: ReadingSessionStatus, // Active | Paused | Closed | Interrupted | Failed
 }
 ```
 
+新增方法：`mark_session_interrupted_v2`, `mark_session_failed_v2`, `get_active_session_v2`, `set_session_closed_at_ms`。
+
 ### 3.3 ReadingEventV2
 
 ```rust
@@ -173,10 +187,12 @@ pub struct BufferedReadingEventV2 {
 }
 ```
 
-方法：`push_event_v2 / export_pending_events_v2 / ack_events_v2 / mark_events_failed_v2`
+方法：`push_event_v2 / export_pending_events_v2 / ack_events_v2 / mark_events_failed_v2 / reload_stale_events_v2 / buffer_size_v2`
 
 容量：最大 1000 条，超出时 Failed→Exported→Pending 顺序清理。
 
+`reload_stale_events_v2`：启动时将 Exported 但未 ack 的事件重置为 Pending，用于 App crash 后的恢复。iOS 启动时必须调用。
+
 ---
 
 ## 4. V1 → V2 迁移策略
@@ -197,7 +213,9 @@ pub struct BufferedReadingEventV2 {
 | client_session_id | 无 | UUID |
 | active_seconds | 累计值/语义模糊 | active_seconds_delta 增量 |
 | sequence | 无 | 递增 |
-| target | material_id 裸字符串 | ReadingMaterialRef |
+| target | material_id 裸字符串 | ReadingMaterialRefV2（含 filePath/fileName/fileType 等） |
+| session status | - | Active/Paused/Closed/Interrupted/Failed |
+| session recovery | - | reload_stale_events_v2 / mark_session_interrupted_v2 |
 
 ---
 
@@ -253,13 +271,20 @@ zhixi-document-runtime
 ## 7. 最终验收链路
 
 ```
-iOS 创建 materialId
-→ Rust startReadingSessionV2
-→ Rust 生成 clientSessionId
-→ push MaterialOpened / PositionChanged / Heartbeat / MaterialClosed
+App 启动
+→ reload_stale_events_v2（重置未 ack 的 Exported 事件为 Pending）
+→ cleanup_stale_sessions_v2（清理超时旧 session）
+
+iOS 创建 ReadingMaterialRefV2（只传 materialId + 文件信息）
+→ Rust startReadingSessionV2（生成 clientSessionId）
+→ push MaterialOpened（delta=0）
+→ heartbeat tick 每 15s → push Heartbeat（delta=增量秒数）
+→ push PositionChanged（delta=0）
+→ push MarkedAsRead（delta=0）
+→ push MaterialClosed（delta=残余秒数）
 → exportPendingEventsV2
-→ iOS 写入本地队列
-→ ackEventsV2
+→ iOS 写入本地 ReadingEventUploadQueue
+→ ackEventsV2（按 eventId 精确删除）
 → iOS 补 readingTargetType / platform / appVersion / timezone
 → API batch upload
 ```