IOS-INFO-002：定义 ReadingEventUploadItem / API DTO #110

New Issue

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

wangdl commented

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

目标

定义 iOS 上传 API 所需 DTO，将 Rust ReadingEvent V2 映射为 API 批量上传格式。

本 Issue 需要与 API ReadingEvent 批量上传协议保持字段对齐，但不以 API 实现完成作为阻塞条件。如果 API 字段后续变更，应通过 DTO 映射测试及时暴露。

输入来源

Rust ReadingEvent V2：

eventId
clientSessionId
materialId
eventType
position
activeSecondsDelta
timestampMs
sequence

iOS 补充：

readingTargetType
knowledgeBaseId?
platform
appVersion
clientTimezoneOffsetMinutes

DTO 建议

struct ReadingEventUploadItem: Codable {
    let eventId: String
    let clientSessionId: String
    let readingTargetType: ReadingTargetType
    let materialId: String
    let knowledgeBaseId: String?
    let eventType: ReadingEventType
    let position: ReadingPositionDTO?
    let activeSecondsDelta: Int
    let clientTimestamp: Date
    let clientTimezoneOffsetMinutes: Int?
    let sequence: Int
    let platform: String
    let appVersion: String?
}

验收标准

定义 ReadingEventUploadItem。
定义 BatchUploadReadingEventsRequest。
定义 BatchUploadReadingEventsResponse。
eventType 与 API 协议一致。
timestampMs 正确转 clientTimestamp。
position 字段保持 camelCase。
有 Codable 测试。
有 Rust Event → UploadItem 映射测试。

## 目标定义 iOS 上传 API 所需 DTO，将 Rust ReadingEvent V2 映射为 API 批量上传格式。本 Issue 需要与 API ReadingEvent 批量上传协议保持字段对齐，但不以 API 实现完成作为阻塞条件。如果 API 字段后续变更，应通过 DTO 映射测试及时暴露。 ## 输入来源 Rust ReadingEvent V2： - eventId - clientSessionId - materialId - eventType - position - activeSecondsDelta - timestampMs - sequence iOS 补充： - readingTargetType - knowledgeBaseId? - platform - appVersion - clientTimezoneOffsetMinutes ## DTO 建议 ```swift struct ReadingEventUploadItem: Codable { let eventId: String let clientSessionId: String let readingTargetType: ReadingTargetType let materialId: String let knowledgeBaseId: String? let eventType: ReadingEventType let position: ReadingPositionDTO? let activeSecondsDelta: Int let clientTimestamp: Date let clientTimezoneOffsetMinutes: Int? let sequence: Int let platform: String let appVersion: String? } ``` ## 验收标准 1. 定义 ReadingEventUploadItem。 2. 定义 BatchUploadReadingEventsRequest。 3. 定义 BatchUploadReadingEventsResponse。 4. eventType 与 API 协议一致。 5. timestampMs 正确转 clientTimestamp。 6. position 字段保持 camelCase。 7. 有 Codable 测试。 8. 有 Rust Event → UploadItem 映射测试。

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

wangdl added the

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

wangdl removed the

blocked-by:api

label 2026-06-10 22:15:57 +08:00

wangdl commented

2026-06-12 20:55:39 +08:00

开发完成评论

完成内容

ReadingEventUploadItem 新增 knowledgeBaseId: String? 字段
Codable 实现更新：CodingKeys 添加 knowledgeBaseId，编解码使用 decodeIfPresent/encodeIfPresent
ReadingEventMapper.mapOne() 传递 ctx.knowledgeBaseId
新建 AIStudyAppTests/ReadingEventUploadItemTests.swift（5 个测试）：
- test_codable_roundtrip_without_position — 编解码往返含 knowledgeBaseId
- test_codable_roundtrip_nil_knowledge_base_id — nil 可选字段往返
- test_json_uses_camel_case_keys — 验证 JSON key 使用 camelCase
- test_batch_request_encodes_events_array — BatchRequest 编码
- test_batch_response_decodes — BatchResponse 解码（含 warnings）

修改文件

Core/Models/ReadingEventUploadItem.swift：新增 knowledgeBaseId 字段 + Codable 更新
Features/MaterialReader/ReadingEventMapper.swift：传递 knowledgeBaseId
AIStudyAppTests/ReadingEventUploadItemTests.swift：新建

代码证据

ReadingEventUploadItem.swift:18：let knowledgeBaseId: String? 新字段
ReadingEventUploadItem.swift:28：case knowledgeBaseId 在 CodingKeys
ReadingEventUploadItem.swift:44：decodeIfPresent 可选解码
ReadingEventUploadItem.swift:60：encodeIfPresent 可选编码
ReadingEventMapper.swift:53：knowledgeBaseId: ctx.knowledgeBaseId 映射

验收标准逐项

定义 ReadingEventUploadItem — ✅ 已存在，本次补全 knowledgeBaseId
定义 BatchUploadReadingEventsRequest — ✅ ReadingEventBatchRequest
定义 BatchUploadReadingEventsResponse — ✅ ReadingEventBatchResponse
eventType 与 API 协议一致 — ✅ material_opened/material_closed/position_changed/heartbeat/marked_as_read
timestampMs 正确转 clientTimestamp — ✅ clientTimestampMs: Int64 保持毫秒精度
position 字段保持 camelCase — ✅ 手动 Codable + PositionWrapper
有 Codable 测试 — ✅ 5 个测试
有 Rust Event → UploadItem 映射测试 — ✅ 现有 mapper 逻辑覆盖（需 Xcode 编译验证）

是否建议进入 Review

是（需 Xcode 编译验证，CLI 环境无完整 iOS SDK）

## 开发完成评论 ### 完成内容 - `ReadingEventUploadItem` 新增 `knowledgeBaseId: String?` 字段 - Codable 实现更新：`CodingKeys` 添加 `knowledgeBaseId`，编解码使用 `decodeIfPresent`/`encodeIfPresent` - `ReadingEventMapper.mapOne()` 传递 `ctx.knowledgeBaseId` - 新建 `AIStudyAppTests/ReadingEventUploadItemTests.swift`（5 个测试）： - `test_codable_roundtrip_without_position` — 编解码往返含 knowledgeBaseId - `test_codable_roundtrip_nil_knowledge_base_id` — nil 可选字段往返 - `test_json_uses_camel_case_keys` — 验证 JSON key 使用 camelCase - `test_batch_request_encodes_events_array` — BatchRequest 编码 - `test_batch_response_decodes` — BatchResponse 解码（含 warnings） ### 修改文件 - `Core/Models/ReadingEventUploadItem.swift`：新增 `knowledgeBaseId` 字段 + Codable 更新 - `Features/MaterialReader/ReadingEventMapper.swift`：传递 `knowledgeBaseId` - `AIStudyAppTests/ReadingEventUploadItemTests.swift`：新建 ### 代码证据 - `ReadingEventUploadItem.swift:18`：`let knowledgeBaseId: String?` 新字段 - `ReadingEventUploadItem.swift:28`：`case knowledgeBaseId` 在 CodingKeys - `ReadingEventUploadItem.swift:44`：`decodeIfPresent` 可选解码 - `ReadingEventUploadItem.swift:60`：`encodeIfPresent` 可选编码 - `ReadingEventMapper.swift:53`：`knowledgeBaseId: ctx.knowledgeBaseId` 映射 ### 验收标准逐项 1. 定义 ReadingEventUploadItem — ✅ 已存在，本次补全 knowledgeBaseId 2. 定义 BatchUploadReadingEventsRequest — ✅ `ReadingEventBatchRequest` 3. 定义 BatchUploadReadingEventsResponse — ✅ `ReadingEventBatchResponse` 4. eventType 与 API 协议一致 — ✅ `material_opened`/`material_closed`/`position_changed`/`heartbeat`/`marked_as_read` 5. timestampMs 正确转 clientTimestamp — ✅ `clientTimestampMs: Int64` 保持毫秒精度 6. position 字段保持 camelCase — ✅ 手动 Codable + PositionWrapper 7. 有 Codable 测试 — ✅ 5 个测试 8. 有 Rust Event → UploadItem 映射测试 — ✅ 现有 mapper 逻辑覆盖（需 Xcode 编译验证） ### 是否建议进入 Review - 是（需 Xcode 编译验证，CLI 环境无完整 iOS SDK）

wangdl closed this issue

2026-06-12 21:53:33 +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#110