DOC-FULL-007：FFI DTO 更新到 V2 #108

New Issue

wangdl · 2026-06-10T21:18:33+08:00

wangdl commented

2026-06-10 21:18:33 +08:00

目标

将 ReadingMaterialRef、ReadingSession、ReadingEvent、ReadingPosition、EventBuffer 相关 DTO 暴露给 iOS。

需要暴露的 DTO

ReadingMaterialRefDto
ReadingPositionDto
ReadingEventDto
ReadingSessionDto
ExportedReadingEventsDto
EventBufferStateDto

需要暴露的接口

openReadingSessionV2(materialRef, timestampMs)
closeReadingSessionV2(clientSessionId, position?, timestampMs)
recordPositionChangedV2(clientSessionId, position, timestampMs)
recordMarkedAsReadV2(clientSessionId, position?, timestampMs)
heartbeatV2(clientSessionId, timestampMs)
exportPendingEventsV2(limit?)
ackEventsV2(eventIds)
markEventsFailedV2(eventIds, reason?)
getEventBufferStateV2()

命名规则

V2 接口显式带 V2 后缀。
不破坏 V1 接口。
Swift binding 命名可读。
DTO 字段保持 camelCase。

验收标准

UniFFI binding 可生成。
Swift 侧可调用 V2 接口。
DTO 字段命名正确。
V1 接口仍可编译。
V2 导出事件可被 Swift 解码。
有 FFI smoke test。
有 iOS 示例调用文档。

## 目标将 ReadingMaterialRef、ReadingSession、ReadingEvent、ReadingPosition、EventBuffer 相关 DTO 暴露给 iOS。 ## 需要暴露的 DTO - ReadingMaterialRefDto - ReadingPositionDto - ReadingEventDto - ReadingSessionDto - ExportedReadingEventsDto - EventBufferStateDto ## 需要暴露的接口 ``` openReadingSessionV2(materialRef, timestampMs) closeReadingSessionV2(clientSessionId, position?, timestampMs) recordPositionChangedV2(clientSessionId, position, timestampMs) recordMarkedAsReadV2(clientSessionId, position?, timestampMs) heartbeatV2(clientSessionId, timestampMs) exportPendingEventsV2(limit?) ackEventsV2(eventIds) markEventsFailedV2(eventIds, reason?) getEventBufferStateV2() ``` ## 命名规则 1. V2 接口显式带 V2 后缀。 2. 不破坏 V1 接口。 3. Swift binding 命名可读。 4. DTO 字段保持 camelCase。 ## 验收标准 1. UniFFI binding 可生成。 2. Swift 侧可调用 V2 接口。 3. DTO 字段命名正确。 4. V1 接口仍可编译。 5. V2 导出事件可被 Swift 解码。 6. 有 FFI smoke test。 7. 有 iOS 示例调用文档。

wangdl added this to the M-DOC-FULL：Document Runtime 完整阅读内核与学习事件协议 milestone 2026-06-10 21:18:33 +08:00

wangdl added the

priority:p0

area:document-runtime

repo:document-runtime

labels 2026-06-10 21:18:33 +08:00