b22df85891
#56 FFI DTO V2 exports (done in A1) #83 V1 deprecated annotations #84 V2→API protocol mapping doc Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
51 lines
1.6 KiB
Markdown
51 lines
1.6 KiB
Markdown
# 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() 返回值 |
|