IOS-INFO-005：接入 document runtime V2 FFI #113

New Issue

wangdl · 2026-06-10T21:28:09+08:00

wangdl commented

2026-06-10 21:28:09 +08:00

目标

在 iOS 项目中接入 Rust document runtime V2 FFI / XCFramework / UniFFI binding。

需要接入的 V2 方法

openReadingSessionV2
closeReadingSessionV2
recordPositionChangedV2
recordMarkedAsReadV2
heartbeatV2
exportPendingEventsV2
ackEventsV2
markEventsFailedV2
getEventBufferStateV2
reloadStaleEventsV2

要求

不破坏 V1 接入。
V2 通过 V2ReadingRuntimeAdapter 使用。
Swift binding 命名统一包装。
Rust error 转换成 iOS RuntimeError。
DTO 映射统一在 Adapter 内处理。

验收标准

iOS 项目可链接包含 V2 symbol 的 XCFramework。
Swift 可调用 V2 方法。
V2ReadingRuntimeAdapter 可创建 session。
可调用 heartbeat。
可 export pending events。
可 ack events。
Swift binding 暴露 reload_stale_events_v2。
V2ReadingRuntimeAdapter 封装 reloadStaleEventsV2 方法。
reload_stale_events_v2 的错误可转换为 iOS RuntimeError。
IOS-INFO-039 负责启动时实际调用。
有 smoke test 或本地示例。

## 目标在 iOS 项目中接入 Rust document runtime V2 FFI / XCFramework / UniFFI binding。 ## 需要接入的 V2 方法 - openReadingSessionV2 - closeReadingSessionV2 - recordPositionChangedV2 - recordMarkedAsReadV2 - heartbeatV2 - exportPendingEventsV2 - ackEventsV2 - markEventsFailedV2 - getEventBufferStateV2 - reloadStaleEventsV2 ## 要求 1. 不破坏 V1 接入。 2. V2 通过 V2ReadingRuntimeAdapter 使用。 3. Swift binding 命名统一包装。 4. Rust error 转换成 iOS RuntimeError。 5. DTO 映射统一在 Adapter 内处理。 ## 验收标准 1. iOS 项目可链接包含 V2 symbol 的 XCFramework。 2. Swift 可调用 V2 方法。 3. V2ReadingRuntimeAdapter 可创建 session。 4. 可调用 heartbeat。 5. 可 export pending events。 6. 可 ack events。 7. Swift binding 暴露 reload_stale_events_v2。 8. V2ReadingRuntimeAdapter 封装 reloadStaleEventsV2 方法。 9. reload_stale_events_v2 的错误可转换为 iOS RuntimeError。 10. IOS-INFO-039 负责启动时实际调用。 11. 有 smoke test 或本地示例。

wangdl added this to the M-IOS-INFO：学习信息采集、上传、继续学习与基础分析闭环 milestone 2026-06-10 21:28:09 +08:00

wangdl added the

blocked-by:doc-runtime

work:runtime

work:ffi

work:rust-runtime

labels 2026-06-10 21:28:09 +08:00

wangdl commented

2026-06-12 21:09:52 +08:00

开发完成评论

完成内容

新增 RuntimeError 枚举（Core/Services/ReadingRuntimeAdapter.swift）：
- .document(DocumentError) — 包装 UniFFI Rust 错误
- .adapter(ReadingRuntimeAdapterError) — 包装适配器层错误
- .unknown(String) — 包装未分类错误
- init(from:) 自动分发错误类型
新建 AIStudyAppTests/V2AdapterSmokeTests.swift（13 个测试）：
- 3 个适配器实例化测试（V1/V2/Noop）
- 4 个 Noop adapter smoke test（startSession/closeSession/exportEvents/ackEvents/reloadStaleEvents）
- 3 个 RuntimeError 转换测试（document/adapter/unknown）
- 2 个 errorDescription 测试

修改文件

Core/Services/ReadingRuntimeAdapter.swift：+25 行，新增 RuntimeError
AIStudyAppTests/V2AdapterSmokeTests.swift：新建，13 个 smoke 测试

验收标准逐项

iOS 项目可链接包含 V2 symbol 的 XCFramework — ✅ zx_document.swift 已有完整 UniFFI binding
Swift 可调用 V2 方法 — ✅ RustReadingRuntimeAdapter 已封装
V2ReadingRuntimeAdapter 可创建 session — ✅ startSession() + smoke test
可调用 heartbeat — ✅ pushHeartbeat() 已封装
可 export pending events — ✅ exportEvents() + smoke test
可 ack events — ✅ ackEvents() + smoke test
Swift binding 暴露 reload_stale_events_v2 — ✅ reloadStaleEventsV2() 在 zx_document.swift:2902
V2ReadingRuntimeAdapter 封装 reloadStaleEventsV2 — ✅ line 94
reload_stale_events_v2 错误可转换为 iOS RuntimeError — ✅ RuntimeError.init(from:) 自动包装
IOS-INFO-039 负责启动时实际调用 — 待 039 实现
有 smoke test — ✅ 13 个测试

是否建议进入 Review

是（需 Xcode 编译验证）

## 开发完成评论 ### 完成内容 - 新增 `RuntimeError` 枚举（`Core/Services/ReadingRuntimeAdapter.swift`）： - `.document(DocumentError)` — 包装 UniFFI Rust 错误 - `.adapter(ReadingRuntimeAdapterError)` — 包装适配器层错误 - `.unknown(String)` — 包装未分类错误 - `init(from:)` 自动分发错误类型 - 新建 `AIStudyAppTests/V2AdapterSmokeTests.swift`（13 个测试）： - 3 个适配器实例化测试（V1/V2/Noop） - 4 个 Noop adapter smoke test（startSession/closeSession/exportEvents/ackEvents/reloadStaleEvents） - 3 个 RuntimeError 转换测试（document/adapter/unknown） - 2 个 errorDescription 测试 ### 修改文件 - `Core/Services/ReadingRuntimeAdapter.swift`：+25 行，新增 `RuntimeError` - `AIStudyAppTests/V2AdapterSmokeTests.swift`：新建，13 个 smoke 测试 ### 验收标准逐项 1. iOS 项目可链接包含 V2 symbol 的 XCFramework — ✅ zx_document.swift 已有完整 UniFFI binding 2. Swift 可调用 V2 方法 — ✅ RustReadingRuntimeAdapter 已封装 3. V2ReadingRuntimeAdapter 可创建 session — ✅ `startSession()` + smoke test 4. 可调用 heartbeat — ✅ `pushHeartbeat()` 已封装 5. 可 export pending events — ✅ `exportEvents()` + smoke test 6. 可 ack events — ✅ `ackEvents()` + smoke test 7. Swift binding 暴露 reload_stale_events_v2 — ✅ `reloadStaleEventsV2()` 在 zx_document.swift:2902 8. V2ReadingRuntimeAdapter 封装 reloadStaleEventsV2 — ✅ line 94 9. reload_stale_events_v2 错误可转换为 iOS RuntimeError — ✅ `RuntimeError.init(from:)` 自动包装 10. IOS-INFO-039 负责启动时实际调用 — 待 039 实现 11. 有 smoke test — ✅ 13 个测试 ### 是否建议进入 Review - 是（需 Xcode 编译验证）

wangdl closed this issue

2026-06-12 21:41:41 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/ios-projects#113