ReadingEvent V2 → API 上传协议映射
字段映射
| Rust ReadingEventV2 |
API ReadingEventUploadItem |
来源 |
| event_id |
eventId |
Rust 生成 UUID |
| client_session_id |
clientSessionId |
Rust 生成 UUID（start_reading_session_v2） |
| material_id |
materialId |
Rust 保存，iOS 传入 |
| event_type |
eventType |
Rust→iOS 转 snake_case |
| position |
position |
Rust（camelCase JSON，clamped） |
| active_seconds_delta |
activeSecondsDelta |
Rust ActiveTimeTracker 计算 |
| timestamp_ms |
clientTimestampMs |
Rust |
| sequence |
sequence |
Rust（session 内递增） |
| — |
readingTargetType |
iOS 补充 |
| — |
platform |
iOS 补充（= "ios"） |
| — |
appVersion |
iOS 补充 |
| — |
clientTimezoneOffsetMinutes |
iOS 补充 |
iOS 上传适配流程
1. Rust export_pending_events_v2(limit, ts)
2. iOS 获得 Vec<ReadingEventV2>
3. iOS 遍历每个 event，补充 readingTargetType/platform/appVersion/timezone
4. iOS 写入本地上传队列
5. 成功后调用 Rust ack_events_v2(eventIds)
6. 失败后调用 Rust mark_events_failed_v2(eventIds)
7. App 启动时调用 reload_stale_events_v2() 恢复未 ack 的事件
eventType 映射
| Rust |
API |
| MaterialOpened |
material_opened |
| MaterialClosed |
material_closed |
| PositionChanged |
position_changed |
| Heartbeat |
heartbeat |
| MarkedAsRead |
marked_as_read |
delta 规则
| 事件 |
delta |
| MaterialOpened |
0 |
| PositionChanged |
0 |
| MarkedAsRead |
0 |
| Heartbeat |
tracker.tick() 返回值 |
| MaterialClosed |
tracker.close() 返回值 |
b22df85891