DOC-301 实现 Rust 侧阅读事件缓冲区 #27

New Issue

wangdl · 2026-06-02T20:11:21+08:00

wangdl commented

2026-06-02 20:11:21 +08:00

背景

docs/app-rust-bridge.md 定义了以下两个 Rust 函数，但代码中未实现：

fn export_pending_events() -> Vec<ReadingEvent>
fn clear_exported_events(count: usize)

现状

ReadingEvent 类型已定义（events.rs），54 个单元测试全过
ReadingPosition 类型已定义并已通过 UDL 暴露到 iOS
但事件没有收集/存储/导出机制
update_reading_position() 也未实现

需要实现

事件缓冲区（内存队列，Mutex 保护）
update_reading_position(material_id, position) — 记录位置变更
export_pending_events() — 返回所有未导出事件
clear_exported_events(count) — 确认前 count 条已上传

验收标准

打开/关闭资料可生成 MaterialOpened/MaterialClosed 事件
Heartbeat 和 PositionChanged 可正常入队
export + clear 流程可正常工作
线程安全（多线程读写缓冲区不 panic）

## 背景 `docs/app-rust-bridge.md` 定义了以下两个 Rust 函数，但代码中未实现： ```rust fn export_pending_events() -> Vec<ReadingEvent> fn clear_exported_events(count: usize) ``` ## 现状 - `ReadingEvent` 类型已定义（events.rs），54 个单元测试全过 - `ReadingPosition` 类型已定义并已通过 UDL 暴露到 iOS - 但事件没有收集/存储/导出机制 - `update_reading_position()` 也未实现 ## 需要实现 1. 事件缓冲区（内存队列，Mutex 保护） 2. `update_reading_position(material_id, position)` — 记录位置变更 3. `export_pending_events()` — 返回所有未导出事件 4. `clear_exported_events(count)` — 确认前 count 条已上传 ## 验收标准 - 打开/关闭资料可生成 MaterialOpened/MaterialClosed 事件 - Heartbeat 和 PositionChanged 可正常入队 - export + clear 流程可正常工作 - 线程安全（多线程读写缓冲区不 panic）

wangdl added this to the M3：iOS 主 App 资料阅读闭环 milestone 2026-06-02 20:11:21 +08:00

wangdl added the

priority:p1

area:core

area:events

labels 2026-06-02 20:11:21 +08:00

wangdl commented

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

实现完成 (2026-06-02)

Rust Core (`events.rs`)

添加全局事件缓冲区：

static EVENT_BUFFER: Mutex<Vec<ReadingEvent>> = Mutex::new(Vec::new());

新增 4 个函数：

函数	行为
`push_reading_event(event)`	将事件推入缓冲区（Mutex 保护）
`update_reading_position(material_id, position)`	生成 PositionChanged 事件并推入缓冲区
`export_pending_events() → Vec<ReadingEvent>`	返回所有未导出事件（不清空）
`clear_exported_events(count)`	移除前 count 个已上传事件

辅助函数：now_ms() — UNIX 毫秒时间戳

FFI / UDL 暴露

UDL 新增 4 个 namespace 函数：

void push_reading_event(ReadingEvent event)
void update_reading_position(string material_id, ReadingPosition position)
sequence<ReadingEvent> export_pending_events()
void clear_exported_events(u32 count)

测试

新增 4 个单元测试：

test_push_and_export — 推入 → 导出数量正确
test_clear_exported — 部分清除后缓冲区剩余正确
test_update_reading_position — 位置变更自动生成 PositionChanged 事件
test_empty_export — 空缓冲区导出为空

全部 58 测试通过，零警告。

产物

XCFramework 已重建
Swift binding 已重新生成（1977 行）
iOS 可用 pushReadingEvent(event:) / exportPendingEvents() / clearExportedEvents(count:) / updateReadingPosition(materialId:position:)

## 实现完成 (2026-06-02) ### Rust Core (`events.rs`) 添加全局事件缓冲区： ```rust static EVENT_BUFFER: Mutex<Vec<ReadingEvent>> = Mutex::new(Vec::new()); ``` 新增 4 个函数： | 函数 | 行为 | |---|---| | `push_reading_event(event)` | 将事件推入缓冲区（Mutex 保护） | | `update_reading_position(material_id, position)` | 生成 PositionChanged 事件并推入缓冲区 | | `export_pending_events() → Vec<ReadingEvent>` | 返回所有未导出事件（不清空） | | `clear_exported_events(count)` | 移除前 count 个已上传事件 | 辅助函数：`now_ms()` — UNIX 毫秒时间戳 ### FFI / UDL 暴露 UDL 新增 4 个 namespace 函数： - `void push_reading_event(ReadingEvent event)` - `void update_reading_position(string material_id, ReadingPosition position)` - `sequence<ReadingEvent> export_pending_events()` - `void clear_exported_events(u32 count)` ### 测试新增 4 个单元测试： - `test_push_and_export` — 推入 → 导出数量正确 - `test_clear_exported` — 部分清除后缓冲区剩余正确 - `test_update_reading_position` — 位置变更自动生成 PositionChanged 事件 - `test_empty_export` — 空缓冲区导出为空全部 58 测试通过，零警告。 ### 产物 - XCFramework 已重建 - Swift binding 已重新生成（1977 行） - iOS 可用 `pushReadingEvent(event:)` / `exportPendingEvents()` / `clearExportedEvents(count:)` / `updateReadingPosition(materialId:position:)`

wangdl closed this issue

2026-06-07 20:06:46 +08:00

wangdl commented

2026-06-07 20:06:46 +08:00

关闭

DOC-301 被 V2 替代 — events_v2.rs (DOC-FULL-003+006) 已实现完整 buffer + ack

## 关闭 DOC-301 被 V2 替代 — events_v2.rs (DOC-FULL-003+006) 已实现完整 buffer + ack

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#27

DOC-301 实现 Rust 侧阅读事件缓冲区 #27

背景

现状

需要实现

验收标准

实现完成 (2026-06-02)

Rust Core (events.rs)

FFI / UDL 暴露

测试

产物

关闭

Rust Core (`events.rs`)