ios-projects/AIStudyApp/docs/ios-learning-info-architecture.md

iOS 学习信息采集架构设计

IOS-INFO-000 | v1.0 | 2026-06-12

本文档定义 iOS 学习信息采集系统的架构决策、模块职责边界与核心链路。 具体类型定义、API 签名、代码示例见 ios-learning-info-design.md。

1. 三方职责边界

┌──────────────────────────────────────────────────────────────┐
│ iOS App                                                      │
│                                                              │
│  ① 生命周期触发   ② ReadingMaterialContext 管理              │
│  ③ readingTargetType 补充   ④ 本地上传队列                   │
│  ⑤ ack/reload    ⑥ API reading-progress 查询                 │
│  ⑦ 继续学习 UI   ⑧ 分析页数据展示                            │
│                              │                               │
│              ReadingRuntimeAdapter (FFI)                      │
│                              ▼                               │
│  ┌────────────────────────────────────────┐                  │
│  │ Rust Document Runtime (zhixi-document-runtime) │          │
│  │                                                        │  │
│  │  ① 事件生成 (UUID/sequence/delta)                      │  │
│  │  ② position normalize                                  │  │
│  │  ③ session 管理 + buffer 状态机                        │  │
│  │  ④ 只存 materialId，不存 readingTargetType/userId      │  │
│  └────────────────────────────────────────┘                  │
└──────────────────────────────────────────────────────────────┘
                              │
          POST /learning/reading-events/batch
          GET  /materials/:id/reading-progress
          GET  /learning/continue
          GET  /learning/summary | /learning/trend | /activity/heatmap
                              │
                              ▼
              ┌───────────────────────────────┐
              │  API Server                   │
              │  ① 事件落库 + 二次校验        │
              │  ② reading-progress 权威数据源 │
              │  ③ 继续学习 / 分析 / 历史      │
              │  ④ 幂等处理 (duplicate event)  │
              └───────────────────────────────┘

层	负责	不负责
Rust	事件生成、session、buffer 状态机、position normalize	readingTargetType/userId、上传 API、UI
iOS	生命周期触发、ReadingMaterialContext、上传队列、ack/reload、UI 联动	事件生成、聚合分析、直接写业务主表
API	事件落库、reading-progress 权威数据、继续学习、分析聚合	事件生成、本地 buffer 管理

2. 核心链路：export → queue → ack

MaterialReader Lifecycle
        │
        ▼
ReadingRuntimeSessionManager
        │
        ▼
ReadingRuntimeAdapter (FFI → Rust)
        │
        ▼
Rust document runtime
  ① push*.V2 → buffer
  ② exportPendingEventsV2 → [ReadingEventV2]
        │
        ▼
iOS export + supplement
  ③ 映射 ReadingEventV2 → ReadingEventUploadItem
  ④ 补充 readingTargetType, platform, appVersion, timezone
        │
        ▼
ReadingEventUploadQueue
  ⑤ enqueue (写入本地持久化)
        │
        ▼
ackEventsV2 (告诉 Rust 删除已导出的事件)
  ⚠️ ack 在写入本地队列成功后立即执行，不等 API 上传
        │
        ▼
UploadScheduler (定时或前台/网络恢复触发)
  ⑥ POST /learning/reading-events/batch
        │
   ┌────┴────┐
   ▼         ▼
 HTTP 200   HTTP !200 / 网络错误
   │         │
   ▼         ▼
从队列移除   markFailed → keep → 下次 retry

关键时序约束：

1. Rust export → iOS 写入本地队列 → Rust ack
2. ack 不等待 API 上传（ack 在 export 后立即执行）
3. API 上传失败不影响下一轮 export

3. 九条核心原则

原则 1：Rust 只接 materialId

Rust document runtime 的 ReadingMaterialRef V2 仅包含 materialId。 readingTargetType、userId、platform 等由 iOS 在 UploadItem 层补充。

原则 2：iOS 负责 ReadingMaterialContext

ReadingMaterialContext 由 iOS 构造，包含 materialId、readingTargetType、title、knowledgeBaseId、Rust 层的 MaterialType 和 PreviewMode。

原则 3：iOS 上传时补充 iOS 专属字段

ReadingEventUploadItem 中补充 readingTargetType、platform: "ios"、appVersion、timezoneOffsetMinutes。

原则 4：ack 不等 API 上传

Rust exportPendingEventsV2 → iOS 写入 ReadingEventUploadQueue 成功 → Rust ackEventsV2。 ack 在 API 上传之前完成。

原则 5：ReadingPositionStore 只做兜底

位置恢复优先 API GET /materials/:id/reading-progress。 ReadingPositionStore（UserDefaults）仅在 API 不可用或返回 not_started 时使用。

原则 6：API reading-progress 是主数据源

跨设备同步、首次阅读、重新阅读等场景以 API 的 reading-progress 为准。

原则 7：首页继续学习替换硬编码

替换当前硬编码的"推荐继续阅读"，替换为 GET /learning/continue 动态数据。 API 返回 type=none 时不显示。

原则 8：iOS 不直接判断聚合结果

iOS 只负责采集、上传、展示 API 结果。 分析判断（薄弱点、下一步建议等）由 API / AI Runtime 产出，iOS 只展示。

原则 9：debug 面板仅开发模式

Debug 面板（日志、buffer 状态、上传队列状态）仅在 #if DEBUG 下编译。

4. 模块结构

Core/
  Reading/
    ReadingMaterialContext.swift          // 上下文类型
    ReadingRuntimeAdapter.swift           // FFI 适配器协议
    ReadingRuntimeSessionManager.swift    // 生命周期 + 心跳管理
    ReadingPositionStore.swift            // 本地位置缓存（兜底）
    MaterialReaderView.swift              // 阅读页生命周期
    HeartbeatTimer.swift                  // 心跳定时器

Upload/
    ReadingEventUploadItem.swift          // 上传条目 DTO
    ReadingEventUploadQueue.swift         // 本地上传队列 + 持久化
    UploadScheduler.swift                 // 定时 + 前后台触发 flush

Networking/
    LearningInfoAPIClient.swift           // API 客户端

Recovery/
    ReadingPositionRestoreService.swift   // 位置恢复（API 优先 + 本地兜底）

Home/
    ContinueLearningService.swift         // 继续学习查询

Analysis/
    AnalysisSummaryService.swift          // 分析页数据接入
    LearningHistoryService.swift          // 学习历史

Debug/
    ReadingEventDebugPanel.swift          // Debug 面板（#if DEBUG）

Tests/
    ReadingInfoUploadTests/               // 单元测试 + 集成测试

5. ReadingMaterialContext

ReadingMaterialContext
├── materialId: String
├── readingTargetType: ReadingTargetType   (.knowledgeSource | .temporaryFile)
├── title: String?
├── knowledgeBaseId: String?
├── materialType: MaterialType            // Rust 侧类型
└── previewMode: PreviewMode              // Rust 侧类型

iOS 在 openMaterial(ctx) 时构造并向 Rust 传递 materialId，其余字段在 upload 时补充到 ReadingEventUploadItem。

6. ReadingRuntimeAdapter 协议

protocol ReadingRuntimeAdapter {
    // Session
    func startSession(material: ReadingMaterialRef, timestampMs: Int64) throws -> String
    func closeSession(_ sessionId: String) throws
    func pauseSession(_ sessionId: String) throws
    func resumeSession(_ sessionId: String) throws

    // Events
    func pushOpened(...) throws -> ReadingEventV2
    func pushClosed(...) throws -> ReadingEventV2
    func pushPositionChanged(...) throws -> ReadingEventV2
    func pushHeartbeat(...) throws -> ReadingEventV2
    func pushMarkedAsRead(...) throws -> ReadingEventV2

    // Buffer
    func exportEvents(limit: UInt32, timestampMs: Int64) -> [ReadingEventV2]
    func ackEvents(_ eventIds: [String]) -> UInt32
    func markFailed(_ eventIds: [String]) -> UInt32
    func reloadStale() -> UInt32
    func cleanupStaleSessions(nowMs: Int64, maxAgeMs: Int64) -> UInt32
}

7. SessionManager 生命周期

MaterialReader.onAppear
  → openMaterial(ctx)
  → startSession(material)
  → pushOpened(sessionId, materialId, ts)
  → startHeartbeat(interval: 15s)

Heartbeat Timer (every 15s)
  → pushHeartbeat(sessionId, materialId, delta, position, ts)

Scroll/Page Change (debounced 500ms)
  → updatePosition(pos)
  → pushPositionChanged(sessionId, materialId, position, ts)

Tap "Mark as Read"
  → markAsRead()
  → pushMarkedAsRead(sessionId, materialId, ts)

MaterialReader.onDisappear
  → stopHeartbeat()
  → pushClosed(sessionId, materialId, delta, ts)
  → closeSession(sessionId)

App → Background
  → exportEvents → enqueue → ackEvents
  → stopHeartbeat()
  → UploadScheduler.flush()

App → Foreground
  → reloadStaleEventsV2
  → cleanupStaleSessions
  → UploadScheduler.flush()
  → startHeartbeat() if reader is active

8. 上传队列

ReadingEventUploadQueue

final class ReadingEventUploadQueue {
    private var items: [ReadingEventUploadItem]  // 内存
    private let persistenceURL: URL              // 磁盘持久化

    func enqueue(_ items: [ReadingEventUploadItem])  // 写入内存 + 磁盘
    func flush() async -> FlushResult               // POST batch → 成功则移除
    func retryFailed() async -> FlushResult         // 网络恢复重试
    func reloadOnLaunch()                           // 启动时加载磁盘缓存 + reloadStale
}

UploadScheduler 触发时机

时机	动作
App → Background	flush()
App → Foreground	flush()
Network recovery (NWPathMonitor)	retryFailed()
Timer (every 30s)	flush()
App launch	reloadOnLaunch()

9. 阅读位置恢复：API 优先 + 本地兜底

ReadingPositionRestoreService.restore(materialId, readingTargetType)
  │
  ├── ① GET /materials/:id/reading-progress
  │    ├── 200 + lastPosition != nil → 使用 API 位置
  │    └── 其他 → ②
  │
  └── ② ReadingPositionStore.shared.get(materialId)
       └── 本地缓存兜底

10. API 端点

端点	iOS 用途
POST /learning/reading-events/batch	批量上传事件
GET /materials/:id/reading-progress	位置恢复（主数据源）
GET /learning/continue	首页继续学习
GET /learning/summary	分析页摘要
GET /learning/trend?days=7	趋势曲线
GET /activity/heatmap?days=365	热力图
GET /learning/history	学习历史

11. 错误处理

错误类型	动作
MATERIAL_ACCESS_DENIED	从队列移除，不重试，toast
TEMPORARY_MATERIAL_EXPIRED	从队列移除
DUPLICATE_EVENT	直接 ack 移除
SOURCE_DELETED	toast，从队列移除
INVALID_*	从队列移除，记录日志
网络错误	保留队列，等 NWPathMonitor 通知后 retry
HTTP 5xx	指数退避重试 (1s/2s/4s/8s, max 3 retry)

12. 离线与登录状态

• 离线：事件正常写入 Rust buffer + 本地队列，export 正常执行，upload 跳过
• 网络恢复：reloadStaleEventsV2() + flush()
• 登录态变化（登出/切换账号）：丢弃本地队列（不属于当前用户），cleanupStaleSessions
• 删除资料：API 返回 SOURCE_DELETED → 从队列移除关联事件

13. 测试范围

层级	内容
单元测试	ReadingMaterialContext 构造、UploadItem 映射、PositionRestore 优先级
集成测试	Adapter FFI mock → SessionManager → UploadQueue → API mock
UI 测试	MaterialReader 生命周期触发、Debug 面板

14. 实现指导

本文档中的架构决策和模块边界直接指导以下 Issue 的实现：

• IOS-INFO-001：ReadingMaterialContext 实现
• IOS-INFO-003：ReadingRuntimeAdapter 协议定义
• IOS-INFO-006：ReadingRuntimeSessionManager 实现
• IOS-INFO-011：ReadingEventUploadQueue 实现
• IOS-INFO-016：API Client 实现

详细类型定义和代码示例参见 ios-learning-info-design.md。