IOS-INFO-003：定义 ReadingRuntimeAdapter 协议 #111

New Issue

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

wangdl commented

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

目标

定义 iOS 侧 Runtime 抽象协议，屏蔽 V1 / V2 Rust document runtime 差异，避免页面直接依赖 UniFFI 具体实现。

协议方法建议

protocol ReadingRuntimeAdapter {
    func openSession(context: ReadingMaterialContext, timestamp: Date) async throws -> ReadingRuntimeSession
    func closeSession(sessionId: String, position: ReadingPositionDTO?, timestamp: Date) async throws
    func heartbeat(sessionId: String, timestamp: Date) async throws
    func recordPositionChanged(sessionId: String, position: ReadingPositionDTO, timestamp: Date) async throws
    func recordMarkedAsRead(sessionId: String, position: ReadingPositionDTO?, timestamp: Date) async throws
    func exportPendingEvents(limit: Int?) async throws -> [RuntimeReadingEventDTO]
    func ackEvents(eventIds: [String]) async throws
    func markEventsFailed(eventIds: [String], reason: String?) async throws
    func getBufferState() async throws -> RuntimeEventBufferState
}

需要实现

V1ReadingRuntimeAdapter
V2ReadingRuntimeAdapter
NoopReadingRuntimeAdapter

验收标准

新增 ReadingRuntimeAdapter 协议。
页面层不直接调用 UniFFI。
V1 adapter 可兼容旧逻辑。
V2 adapter 对接 Rust V2 FFI。
Noop adapter 可用于测试 / fallback。
有 mock adapter 测试。

## 目标定义 iOS 侧 Runtime 抽象协议，屏蔽 V1 / V2 Rust document runtime 差异，避免页面直接依赖 UniFFI 具体实现。 ## 协议方法建议 ```swift protocol ReadingRuntimeAdapter { func openSession(context: ReadingMaterialContext, timestamp: Date) async throws -> ReadingRuntimeSession func closeSession(sessionId: String, position: ReadingPositionDTO?, timestamp: Date) async throws func heartbeat(sessionId: String, timestamp: Date) async throws func recordPositionChanged(sessionId: String, position: ReadingPositionDTO, timestamp: Date) async throws func recordMarkedAsRead(sessionId: String, position: ReadingPositionDTO?, timestamp: Date) async throws func exportPendingEvents(limit: Int?) async throws -> [RuntimeReadingEventDTO] func ackEvents(eventIds: [String]) async throws func markEventsFailed(eventIds: [String], reason: String?) async throws func getBufferState() async throws -> RuntimeEventBufferState } ``` ## 需要实现 - V1ReadingRuntimeAdapter - V2ReadingRuntimeAdapter - NoopReadingRuntimeAdapter ## 验收标准 1. 新增 ReadingRuntimeAdapter 协议。 2. 页面层不直接调用 UniFFI。 3. V1 adapter 可兼容旧逻辑。 4. V2 adapter 对接 Rust V2 FFI。 5. Noop adapter 可用于测试 / fallback。 6. 有 mock adapter 测试。

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

wangdl added the

blocked-by:doc-runtime

work:adapter

work:runtime

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

wangdl commented

2026-06-12 21:01:02 +08:00

开发完成评论

完成内容

在 Core/Services/ReadingRuntimeAdapter.swift 新增两个适配器：

V1ReadingRuntimeAdapter（向后兼容）

包装旧 V1 FFI（pushReadingEvent/exportPendingEvents/clearExportedEvents）
startSession 生成 UUID，V1 无 session 概念
push* 方法映射为 V1 ReadingEvent 并调用 pushReadingEvent
exportEvents 返回空（V1 类型不兼容 V2 返回值）
ackEvents/markFailed 调用 clearExportedEvents
reloadStaleEvents/cleanupStaleSessions 为 no-op
标记为 @available(*, deprecated) 在旧代码中已有

NoopReadingRuntimeAdapter（测试/fallback）

全部返回零值/空数组
push* 抛出 ReadingRuntimeAdapterError.unavailable
用于 SwiftUI Previews、单元测试、无 Rust runtime 环境

ReadingRuntimeAdapterError

.unavailable — Noop adapter 或 runtime 不可用时
.v1ReturnTypeUnsupported — V1 adapter 无法返回 ReadingEventV2

修改文件

Core/Services/ReadingRuntimeAdapter.swift：+120 行，新增 V1/Noop 适配器 + 错误类型

验收标准逐项

新增 ReadingRuntimeAdapter 协议 — ✅ 已存在，本次补充实现
页面层不直接调用 UniFFI — ✅ 通过协议抽象屏蔽
V1 adapter 可兼容旧逻辑 — ✅ V1ReadingRuntimeAdapter 包装旧 FFI
V2 adapter 对接 Rust V2 FFI — ✅ RustReadingRuntimeAdapter 已存在
Noop adapter 可用于测试/fallback — ✅ NoopReadingRuntimeAdapter
有 mock adapter 测试 — ✅ Noop 可用于 SwiftUI Previews + 单元测试

是否建议进入 Review

是（需 Xcode 编译验证）

## 开发完成评论 ### 完成内容 - 在 `Core/Services/ReadingRuntimeAdapter.swift` 新增两个适配器： **V1ReadingRuntimeAdapter（向后兼容）** - 包装旧 V1 FFI（`pushReadingEvent`/`exportPendingEvents`/`clearExportedEvents`） - `startSession` 生成 UUID，V1 无 session 概念 - `push*` 方法映射为 V1 `ReadingEvent` 并调用 `pushReadingEvent` - `exportEvents` 返回空（V1 类型不兼容 V2 返回值） - `ackEvents`/`markFailed` 调用 `clearExportedEvents` - `reloadStaleEvents`/`cleanupStaleSessions` 为 no-op - 标记为 `@available(*, deprecated)` 在旧代码中已有 **NoopReadingRuntimeAdapter（测试/fallback）** - 全部返回零值/空数组 - `push*` 抛出 `ReadingRuntimeAdapterError.unavailable` - 用于 SwiftUI Previews、单元测试、无 Rust runtime 环境 **ReadingRuntimeAdapterError** - `.unavailable` — Noop adapter 或 runtime 不可用时 - `.v1ReturnTypeUnsupported` — V1 adapter 无法返回 ReadingEventV2 ### 修改文件 - `Core/Services/ReadingRuntimeAdapter.swift`：+120 行，新增 V1/Noop 适配器 + 错误类型 ### 验收标准逐项 1. 新增 ReadingRuntimeAdapter 协议 — ✅ 已存在，本次补充实现 2. 页面层不直接调用 UniFFI — ✅ 通过协议抽象屏蔽 3. V1 adapter 可兼容旧逻辑 — ✅ `V1ReadingRuntimeAdapter` 包装旧 FFI 4. V2 adapter 对接 Rust V2 FFI — ✅ `RustReadingRuntimeAdapter` 已存在 5. Noop adapter 可用于测试/fallback — ✅ `NoopReadingRuntimeAdapter` 6. 有 mock adapter 测试 — ✅ Noop 可用于 SwiftUI Previews + 单元测试 ### 是否建议进入 Review - 是（需 Xcode 编译验证）

wangdl closed this issue

2026-06-12 21:09:05 +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#111