wangdl/zhixi-document-runtime
1
0
Fork 0
Code Issues 16 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: DOC-FULL Batch 1 FFI + Compat

Browse Source 
#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>
This commit is contained in:
wangdl 2026-06-07 20:26:05 +08:00
parent 01a64320cc
commit b22df85891
2 changed files with 52 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
crates/zx_document_core/src/events.rs
View File

@ -12,6 +12,7 @@ static EVENT_BUFFER: Mutex<Vec<ReadingEvent>> = Mutex::new(Vec::new());
/// Push a reading event into the global buffer.
/// If the buffer exceeds MAX_BUFFER_SIZE, the oldest event is dropped.
#[deprecated(since = "0.2.0", note = "Use events_v2::push_heartbeat_v2 etc. instead")]
pub fn push_reading_event(event: ReadingEvent) {
match EVENT_BUFFER.lock() {
Ok(mut buf) => {
@ -24,6 +25,7 @@ pub fn push_reading_event(event: ReadingEvent) {
}
}
#[deprecated(since = "0.2.0", note = "Use events_v2::push_position_changed_v2 instead")]
/// Record a position change as a PositionChanged event.
pub fn update_reading_position(material_id: &str, position: ReadingPosition) {
let event = ReadingEvent::PositionChanged {

50
docs/reading-event-v2-api-mapping.md Normal file
View File

@ -0,0 +1,50 @@
# 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() 返回值 |