# ReadingEvent V2 协议

## 概述

V2 阅读事件协议定义了一套完整的学习行为采集框架：**阅读会话 → 事件生成 → buffer 暂存 → export 导出 → ack 确认**。

与 V1 的区别：
- V1：无 session，无 ack，无 id 追踪
- V2：session 管理 + 全局事件 buffer + export/ack 确认 + crash recovery

## 核心概念

### ReadingSessionV2

一次阅读会话。iOS App 一次打开资料即创建一个 session。

```rust
pub struct ReadingSessionV2 {
    pub client_session_id: String,   // UUID v4，会话标识
    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
}
```

#### 生命周期

```
start → Active → (pause → Paused → resume → Active)* → close → Closed
```

- **Active**：可推送任意类型事件
- **Paused**：仅可推送 delta=0 事件（PositionChanged/MarkedAsRead）
- **Closed**：不可推送事件，不可重新打开

### ReadingMaterialRef

```rust
pub struct ReadingMaterialRef {
    pub material_id: String,
}
```

Rust 不存储 `readingTargetType`（如 knowledge/material/course/note），由 iOS 上传时补充。

### ReadingEventV2

```rust
pub struct ReadingEventV2 {
    pub event_id: String,            // UUID v4，全局唯一事件 ID
    pub client_session_id: String,   // 关联的会话 ID
    pub material_id: String,         // 资料 ID
    pub event_type: ReadingEventTypeV2, // 事件类型
    pub position: Option<ReadingPosition>, // 阅读位置（camelCase JSON）
    pub active_seconds_delta: u32,   // 距上次事件的活跃秒数
    pub timestamp_ms: i64,           // 客户端时间戳
    pub sequence: u64,               // session 内递增序号（1-based）
}
```

#### eventType 取值

| Rust | API JSON |
|------|----------|
| `MaterialOpened` | `material_opened` |
| `MaterialClosed` | `material_closed` |
| `PositionChanged` | `position_changed` |
| `Heartbeat` | `heartbeat` |
| `MarkedAsRead` | `marked_as_read` |

#### activeSecondsDelta 规则

| 事件 | delta |
|------|-------|
| MaterialOpened | 0 |
| PositionChanged | 0 |
| MarkedAsRead | 0 |
| Heartbeat | ActiveTimeTracker.tick() 返回值 |
| MaterialClosed | ActiveTimeTracker.close() 返回值 |

### ActiveTimeTracker

iOS 控制 tick 节奏，Rust 计算 delta：

```
start(ts) → tick(ts+15s) → tick(ts+30s) → close(ts+43s)
             delta=15       delta=15        delta=13
```

- 暂停时不累计时间
- 时间倒退返回 0
- 余数毫秒累积到下次 tick

### EventBuffer 状态机

```
              push
                │
                ▼
          ┌─ Pending ──┐
          │             │
     export()      reload_stale()
          │             │
          ▼             │
        Exported ───────┘
          │
    ┌─────┴─────┐
    │           │
  ack()    mark_failed()
    │           │
    ▼           ▼
 (removed)   Failed
                │
           export() ──→ 重试
```

- **Pending**：新事件，等待导出
- **Exported**：已导出，等待 ack。crash 后 `reload_stale_events()` 恢复为 Pending
- **Failed**：上传失败，下次 export 重试
- **Ack 后删除**：从 buffer 移除

### 溢出驱逐

Buffer 容量：1000 条。满时驱逐顺序：
1. Failed（最早失败的）
2. Exported（最早导出的）
3. 最早 Pending

## API 上传字段映射

| Rust ReadingEventV2 | API ReadingEventUploadItem | 来源 |
|---------------------|---------------------------|------|
| event_id | eventId | Rust UUID |
| client_session_id | clientSessionId | Rust UUID |
| material_id | materialId | Rust 保存 |
| event_type | eventType | Rust→snake_case |
| position | position | Rust（camelCase JSON，clamped） |
| active_seconds_delta | activeSecondsDelta | ActiveTimeTracker |
| timestamp_ms | clientTimestampMs | Rust |
| sequence | sequence | session 内递增 |
| — | readingTargetType | **iOS 补充** |
| — | platform | **iOS 补充** |
| — | appVersion | **iOS 补充** |
| — | clientTimezoneOffsetMinutes | **iOS 补充** |

## iOS 上传流程

```
1. Rust export_pending_events_v2(limit, timestamp) → Vec<ReadingEventV2>
2. iOS 遍历事件，补充 readingTargetType/platform/appVersion/timezone
3. iOS 构造 API 请求体
4. POST /reading/events
5. 成功 → Rust ack_events_v2(eventIds)
6. 失败 → Rust mark_events_failed_v2(eventIds)
7. App 启动 → Rust reload_stale_events_v2()
```