DOC-FULL-006：EventBuffer V2 ack / failed / state #107

New Issue

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

wangdl commented

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

目标

实现 Rust 侧事件 buffer，用于暂存待导出的 ReadingEvent V2。

核心原则

Rust EventBuffer 不是长期可靠队列。
iOS 写入本地 ReadingEventUploadQueue 成功后，才调用 ack。
Rust ack 后立即删除对应事件。
ack 不等待 API 上传成功。

需要支持

append(event)
exportPendingEventsV2(limit?)
ackEventsV2(eventIds)
markEventsFailedV2(eventIds, reason?)
getBufferState()
clearClosedSessionEvents()

Event 状态

pending
exported
acked
failed

规则

exportPendingEventsV2 只导出 pending / failed 可重试事件。
导出后可标记 exported。
ack 后立即删除事件或标记 acked 后清理。
failed 事件可再次导出。
eventId 不存在时 ack 不应崩溃。
重复 ack 应幂等。
Buffer 应有最大容量保护。

验收标准

pending event 可导出。
ack 后事件从 buffer 删除。
failed event 可重新导出。
重复 ack 幂等。
不存在 eventId ack 不崩溃。
buffer state 可查询。
超出容量有明确错误或丢弃策略。
有单元测试。

## 目标实现 Rust 侧事件 buffer，用于暂存待导出的 ReadingEvent V2。 ## 核心原则 Rust EventBuffer 不是长期可靠队列。 iOS 写入本地 ReadingEventUploadQueue 成功后，才调用 ack。 Rust ack 后立即删除对应事件。 ack 不等待 API 上传成功。 ## 需要支持 ``` append(event) exportPendingEventsV2(limit?) ackEventsV2(eventIds) markEventsFailedV2(eventIds, reason?) getBufferState() clearClosedSessionEvents() ``` ## Event 状态 - pending - exported - acked - failed ## 规则 1. exportPendingEventsV2 只导出 pending / failed 可重试事件。 2. 导出后可标记 exported。 3. ack 后立即删除事件或标记 acked 后清理。 4. failed 事件可再次导出。 5. eventId 不存在时 ack 不应崩溃。 6. 重复 ack 应幂等。 7. Buffer 应有最大容量保护。 ## 验收标准 1. pending event 可导出。 2. ack 后事件从 buffer 删除。 3. failed event 可重新导出。 4. 重复 ack 幂等。 5. 不存在 eventId ack 不崩溃。 6. buffer state 可查询。 7. 超出容量有明确错误或丢弃策略。 8. 有单元测试。

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

Sign in to join this conversation.