wangdl/zhixi-document-runtime
1
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-06-10 21:18:33 +08:00 by wangdl · 1 comment
wangdl commented 2026-06-10 21:18:33 +08:00
Owner
Copy Link

目标

说明 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 对齐使用。
## 目标 说明 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 commented 2026-06-11 21:21:11 +08:00
Author
Owner
Copy Link

完成证据

产物: (50 行，已有)
已有提交: feat: DOC-FULL-003 ReadingEventV2

字段映射表:

Rust ReadingEventV2 iOS UploadItem API 来源
eventId eventId eventId Rust
clientSessionId clientSessionId clientSessionId Rust
materialId materialId materialId Rust
eventType eventType eventType Rust→iOS snake_case
position position position Rust (camelCase)
activeSecondsDelta activeSecondsDelta activeSecondsDelta Rust
timestampMs clientTimestamp clientTimestampMs Rust
sequence sequence sequence Rust
— readingTargetType readingTargetType iOS 补充
— platform platform iOS 补充
— appVersion appVersion iOS 补充
— clientTimezoneOffsetMinutes clientTimezoneOffsetMinutes iOS 补充
— — userId API 补充

核心原则: Rust 不生成 readingTargetType/userId, iOS ack 时机是本地队列写入成功, activeSecondsDelta 是唯一计时输入

## 完成证据 **产物**: (50 行，已有) **已有提交**: feat: DOC-FULL-003 ReadingEventV2 **字段映射表**: | Rust ReadingEventV2 | iOS UploadItem | API | 来源 | |---|---|---|---| | eventId | eventId | eventId | Rust | | clientSessionId | clientSessionId | clientSessionId | Rust | | materialId | materialId | materialId | Rust | | eventType | eventType | eventType | Rust→iOS snake_case | | position | position | position | Rust (camelCase) | | activeSecondsDelta | activeSecondsDelta | activeSecondsDelta | Rust | | timestampMs | clientTimestamp | clientTimestampMs | Rust | | sequence | sequence | sequence | Rust | | — | readingTargetType | readingTargetType | iOS 补充 | | — | platform | platform | iOS 补充 | | — | appVersion | appVersion | iOS 补充 | | — | clientTimezoneOffsetMinutes | clientTimezoneOffsetMinutes | iOS 补充 | | — | — | userId | API 补充 | **核心原则**: Rust 不生成 readingTargetType/userId, iOS ack 时机是本地队列写入成功, activeSecondsDelta 是唯一计时输入
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:android
Android 集成
area:architecture
架构设计
area:ci
CI/CD
area:core
zx_document_core
area:document-runtime
Document Runtime 相关
area:epub
EPUB 相关
area:events
阅读事件
area:ffi
FFI 绑定层
area:image
图片处理
area:ios
iOS 集成
area:markdown
Markdown 解析
area:notes
笔记锚点
area:office
Office 格式
area:pdf
PDF 相关
area:progress
阅读位置与进度
area:search
搜索
area:text
TXT 解析
audit:planned
已完成宏观规划
priority:p0
最高优先级，阻塞发布
priority:p1
高优先级，本里程碑必需
priority:p2
中优先级，后续版本
repo:document-runtime
Rust Document Runtime 仓库
status:blocked
被阻塞
status:needs-review
待审查
status:todo
待执行
type:design
设计与建模
type:docs
文档相关
type:implementation
功能实现
type:integration
平台集成与绑定
type:research
调研与评估
type:test
测试相关
work:api-mapping
API 协议映射
work:architecture
架构
work:compatibility
兼容性
work:contract
协议/契约
work:design
架构设计
work:docs
文档
work:event
阅读事件
work:event-buffer
事件缓冲
work:example
示例代码
work:ffi
FFI 绑定
work:ffi-contract
FFI 契约
work:ios-contract
iOS 嵌入契约
work:model
数据模型
work:position
阅读位置
work:queue
队列
work:session
阅读会话
work:time-tracking
时长计算
work:uniffi
UniFFI
work:v1-v2
V1/V2 迁移
work:v2
V2 模块
No Label
area:document-runtime
audit:planned
priority:p0
repo:document-runtime
status:todo
work:api-mapping
work:contract
work:docs
Milestone
No items
No Milestone M-DOC-FULL：Document Runtime 完整阅读内核与学习事件协议
Projects
Clear projects
No project
Assignees
Clear assignees
wangdl
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#111
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?