# V1 → V2 兼容层

## 策略

V1 不删除，V2 新增独立模块。iOS 可逐步迁移。

## V1 模块（保留 deprecated）

| 文件 | 状态 | 说明 |
|------|------|------|
| `events.rs` | `#[deprecated]` | 旧 ReadingEvent 类型 + push/export/clear |
| `reading_material.rs` | `#[deprecated]` | 旧 ReadingMaterialRef（仅 material_id） |

所有 V1 `#[uniffi::export]` 方法保留，确保现有 iOS V1 接入不中断。

## V2 模块（新增）

| 文件 | 内容 |
|------|------|
| `reading_material.rs` | ReadingMaterialRefV2（camelCase, 8 fields） |
| `session_v2.rs` | ReadingSessionV2 + 5 statuses + lifecycle methods |
| `events_v2.rs` | ReadingEventV2 + EventBuffer (ack/failed/reload/state) |
| `time_tracker.rs` | ActiveTimeTracker（iOS 控制 tick） |
| `progress.rs` | ReadingPosition（camelCase + clamp） |

## V1 vs V2 差异

| 维度 | V1 | V2 |
|------|----|----|
| material ref | `ReadingMaterialRef { material_id }` | `ReadingMaterialRefV2 { 8 fields }` |
| session | 无独立模型 | `ReadingSessionV2` + lifecycle |
| event_id | 无 | UUID v4, 36 char |
| session_id | 无 | UUID v4 |
| sequence | 无 | u64 递增 |
| active_seconds | 累计/语义模糊 | `activeSecondsDelta` 增量 |
| position | snake_case | camelCase + clamp 0~1 |
| buffer 管理 | 无 ack/failed | export→ack/failed/reload 完整生命周期 |
| time tracker | 无 | ActiveTimeTracker（iOS tick / pause / resume） |
| session recovery | 无 | reload_stale_events_v2 + interrupted/failed |

## iOS 迁移路径

```
Phase 1 (当前):
  iOS 继续使用 V1 接入（V1 方法仍可用）

Phase 2:
  iOS 实现 V2ReadingRuntimeAdapter（使用 V2 方法）
  同时保留 V1ReadingRuntimeAdapter 作为 fallback

Phase 3:
  全量切换到 V2
  V1 接口留在代码中保持编译兼容

Phase 4 (未来):
  确认所有端都切换到 V2 后，可移除 V1
```

## active_seconds vs activeSecondsDelta

| V1 | V2 |
|----|----|
| `active_seconds` 语义模糊，可能是累计值 | `active_seconds_delta` 每次 heartbeat 增量 |
| iOS 侧自己算 | ActiveTimeTracker 计算，基于 timestamp 差值 |
| 无 clamp / 校验 | maxDeltaSeconds=60，超出 clamp + warning |

## FFI 接口对比

| V1 (deprecated) | V2 |
|-----------------|-----|
| `push_reading_event(ReadingEvent)` | `push_material_opened_v2 / push_heartbeat_v2 / ...` |
| `export_pending_events() → Vec<ReadingEvent>` | `export_pending_events_v2(limit, ts) → Vec<ReadingEventV2>` |
| `clear_exported_events(count)` | `ack_events_v2(eventIds)` + `mark_events_failed_v2(eventIds)` |
| — | `reload_stale_events_v2()` |
| — | `get_event_buffer_state_v2()` |

## 验收

- [x] V1 仍可编译（所有 V1 tests pass）
- [x] V2 新接口可用（169 tests pass）
- [x] V1 deprecated 信息清楚（`#[deprecated]` annotations）
- [x] active_seconds 与 activeSecondsDelta 差异说明
- [x] iOS 迁移路径说明