DOC-FULL-035：V2 与 API 上传协议映射文档 #111

New Issue

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

wangdl commented

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

目标

说明 Rust ReadingEvent V2 如何映射到 iOS UploadItem / API ReadingEvent 上传协议。

Rust 输出字段

eventId
clientSessionId
materialId
eventType
position
activeSecondsDelta
timestampMs
sequence

iOS 补充字段

readingTargetType
platform
appVersion
clientTimezoneOffsetMinutes
knowledgeBaseId?

API 解析字段

userId
serverReceivedAt
status
errorCode
warningCodes

必须说明

Rust 不生成 readingTargetType。
Rust 不生成 userId。
timestampMs 在 iOS/API 侧转换为 clientTimestamp。
activeSecondsDelta 是唯一计时输入。
position 使用 camelCase JSON。
iOS ack 时机是本地队列写入成功，不是 API 上传成功。

验收标准

新增 docs/reading-event-v2-api-mapping.md。
字段映射表完整。
明确 Rust / iOS / API 的职责。
明确不应把 readingTargetType 放回 Rust。
明确 activeSecondsDelta 语义。
可供 API / iOS 对齐使用。

## 目标说明 Rust ReadingEvent V2 如何映射到 iOS UploadItem / API ReadingEvent 上传协议。 ## Rust 输出字段 - eventId - clientSessionId - materialId - eventType - position - activeSecondsDelta - timestampMs - sequence ## iOS 补充字段 - readingTargetType - platform - appVersion - clientTimezoneOffsetMinutes - knowledgeBaseId? ## API 解析字段 - userId - serverReceivedAt - status - errorCode - warningCodes ## 必须说明 1. Rust 不生成 readingTargetType。 2. Rust 不生成 userId。 3. timestampMs 在 iOS/API 侧转换为 clientTimestamp。 4. activeSecondsDelta 是唯一计时输入。 5. position 使用 camelCase JSON。 6. iOS ack 时机是本地队列写入成功，不是 API 上传成功。 ## 验收标准 1. 新增 docs/reading-event-v2-api-mapping.md。 2. 字段映射表完整。 3. 明确 Rust / iOS / API 的职责。 4. 明确不应把 readingTargetType 放回 Rust。 5. 明确 activeSecondsDelta 语义。 6. 可供 API / 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

Sign in to join this conversation.