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

# iOS 学习信息采集 总设计

> IOS-INFO-000 | v1.0 | 2026-06-08

## 1. 概述

iOS 端学习信息采集系统的目标：从 MaterialReader 生命周期的各个环节采集阅读行为数据，经 Rust document runtime 生成事件，再经本地上传队列可靠投递到 API 服务端。

### 职责边界

```
┌─────────────────────────────────────────────────────────┐
│ iOS App                                                │
│  ┌─────────────┐   ┌──────────────┐   ┌─────────────┐ │
│  │ Reader View  │──▶│ Rust Runtime  │──▶│ UploadQueue │ │
│  │ (Lifecycle)  │   │ (Event V2)   │   │ (ack/retry) │ │
│  └─────────────┘   └──────────────┘   └──────┬──────┘ │
│                                               │        │
│  ┌─────────────┐   ┌──────────────┐          │        │
│  │ Continue     │   │ Progress     │          │        │
│  │ Learning    │   │ Restore      │          │        │
│  └─────────────┘   └──────────────┘          │        │
└───────────────────────────────────────────────┼────────┘
                                                │
                                    POST /learning/reading-events/batch
                                                │
                                        ┌───────▼────────┐
                                        │  API Server    │
                                        │  (M8)          │
                                        └────────────────┘
```

**Rust 负责：** 事件生成（UUID/sequence/delta）、position normalize、session 管理、buffer 状态机
**iOS 负责：** 生命周期触发、readingTargetType 补充、上传队列、ack/reload、位置缓存、UI 联动

## 2. V1 → V2 迁移

### 当前状态（V1）

```swift
// ReadingEventCollector.swift — V1 API
pushReadingEvent(event: ReadingEvent.materialOpened(...))
exportPendingEvents()           // → [ReadingEvent]
clearExportedEvents(count: n)   // 无 ack，无重试
```

### 致命问题（F1-F4 审查发现）

| ID | 问题 | 影响 |
|----|------|------|
| F1 | `open/close` 被注释 | 事件链路断裂，无数据 |
| F2 | 无上传队列 | 事件丢失无重试 |
| F3 | 继续学习硬编码 | 无法动态更新 |
| F4 | 位置恢复仅本地 | 跨设备无法同步 |

### 目标状态（V2）

```swift
// ReadingRuntimeSessionManager.swift — V2 API
let sid = try startReadingSessionV2(material: material, timestampMs: now)
let ev = try pushMaterialOpenedV2(sessionId: sid, materialId: id, timestampMs: now)
let batch = exportPendingEventsV2(limit: 100, timestampMs: now)
ackEventsV2(eventIds: ids)         // 成功后确认删除
markEventsFailedV2(eventIds: ids)  // 失败后标记重试
reloadStaleEventsV2()              // App 启动恢复
```

### 迁移对照

| V1 API (废弃) | V2 API (使用) |
|--------------|-------------|
| `pushReadingEvent(ReadingEvent.materialOpened)` | `pushMaterialOpenedV2(sessionId, materialId, ts)` |
| `pushReadingEvent(ReadingEvent.heartbeat)` | `pushHeartbeatV2(sessionId, materialId, delta, pos, ts)` |
| `exportPendingEvents()` | `exportPendingEventsV2(limit, ts)` |
| `clearExportedEvents(count)` | `ackEventsV2(eventIds)` |
| — | `markEventsFailedV2(eventIds)` |
| — | `reloadStaleEventsV2()` |
| `activeSeconds` (累计) | `activeSecondsDelta` (增量) |

## 3. 核心类型

### ReadingMaterialContext

```swift
struct ReadingMaterialContext {
    let materialId: String
    let readingTargetType: ReadingTargetType // knowledge_source | temporary_file
    let title: String?
    let knowledgeBaseId: String?
    let materialType: MaterialType           // Rust MaterialType
    let previewMode: PreviewMode             // Rust PreviewMode
}

enum ReadingTargetType: String {
    case knowledgeSource = "knowledge_source"
    case temporaryFile = "temporary_file"
}
```

### ReadingRuntimeAdapter 协议

```swift
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(sessionId: String, materialId: String, timestampMs: Int64) throws -> ReadingEventV2
    func pushClosed(sessionId: String, materialId: String, delta: UInt32, timestampMs: Int64) throws -> ReadingEventV2
    func pushPositionChanged(sessionId: String, materialId: String, position: ReadingPosition, timestampMs: Int64) throws -> ReadingEventV2
    func pushHeartbeat(sessionId: String, materialId: String, delta: UInt32, position: ReadingPosition?, timestampMs: Int64) throws -> ReadingEventV2
    func pushMarkedAsRead(sessionId: String, materialId: String, timestampMs: Int64) 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
}
```

### ReadingEventUploadItem

```swift
struct ReadingEventUploadItem: Codable {
    // From Rust ReadingEventV2
    let eventId: String
    let clientSessionId: String
    let materialId: String
    let eventType: String
    let position: ReadingPosition?
    let activeSecondsDelta: Int
    let clientTimestampMs: Int64
    let sequence: UInt64

    // iOS supplements
    let readingTargetType: String
    let platform: String = "ios"
    let appVersion: String
    let clientTimezoneOffsetMinutes: Int
}
```

## 4. 架构：ReadingRuntimeSessionManager

```swift
@MainActor
final class ReadingRuntimeSessionManager {
    static let shared = ReadingRuntimeSessionManager()

    private var activeSessionId: String?
    private var context: ReadingMaterialContext?
    private var heartbeatTimer: Timer?
    private var lastPosition: ReadingPosition?

    // MARK: - Lifecycle

    func openMaterial(_ ctx: ReadingMaterialContext)
    func closeMaterial()
    func appDidEnterBackground()
    func appWillEnterForeground()

    // MARK: - Position
    func updatePosition(_ pos: ReadingPosition)  // debounced
    func markAsRead()

    // MARK: - Heartbeat
    func startHeartbeat(interval: TimeInterval = 15)
    func stopHeartbeat()
}
```

## 5. 上传队列：ReadingEventUploadQueue

### 状态机

```
          Rust export
              │
              ▼
          LocalQueue (Swift array, persisted to disk)
              │
              ▼
          POST /learning/reading-events/batch
              │
        ┌─────┴─────┐
        ▼           ▼
     成功(200)    失败/网络错误
        │           │
        ▼           ▼
    ackEvents    markFailed
    (Rust delete)  (Rust retry mark)
        │           │
        ▼           ▼
    remove from   keep in queue
    local queue   for next attempt
```

### UploadQueue 核心方法

```swift
final class ReadingEventUploadQueue {
    func enqueue(_ items: [ReadingEventUploadItem])
    func flush() async -> FlushResult       // called on timer + app background
    func retryFailed() async -> FlushResult // called on network recovery
    func reloadOnLaunch()                    // reloadStaleEventsV2 + load persisted
}

struct FlushResult {
    let uploaded: Int
    let failed: Int
    let warnings: [String]
}
```

## 6. 关键时机

| 时机 | 触发方 | 动作 |
|------|--------|------|
| MaterialReader onAppear | SwiftUI | `openMaterial(ctx)` |
| MaterialReader onDisappear | SwiftUI | `closeMaterial()` |
| Scroll/page change | Reader View | `updatePosition(pos)` |
| Tap "Mark as Read" | UI Button | `markAsRead()` |
| App → background | ScenePhase | `flush()` + stop heartbeat |
| App → foreground | ScenePhase | `reloadStale()` + `cleanupStaleSessions()` |
| Network recovery | NWPathMonitor | `retryFailed()` |
| Every 30s (timer) | UploadScheduler | `flush()` |
| On launch | App init | `reloadOnLaunch()` |

## 7. 继续学习

### 当前（F3 硬编码）

```swift
// 硬编码"推荐继续阅读"文案，无数据源
```

### 目标

```swift
struct ContinueLearningService {
    func fetch() async -> ContinueLearningItem? {
        let resp = try await api.get("/learning/continue")
        switch resp.type {
        case "knowledge_source", "temporary_file":
            return ContinueLearningItem(
                materialId: resp.materialId,
                title: resp.title ?? "Untitled",
                lastPosition: resp.lastPosition,
                lastProgress: resp.lastProgress
            )
        case "none":
            return nil
        default:
            return nil
        }
    }
}
```

## 8. 阅读位置恢复

### 当前（F4 仅本地）

```swift
// ReadingPositionStore: UserDefaults only
```

### 目标

```swift
struct ReadingPositionRestoreService {
    func restore(for materialId: String, targetType: ReadingTargetType) async -> ReadingPosition? {
        // 1. Try API: GET /materials/:id/reading-progress
        if let remote = try? await api.getProgress(materialId, targetType),
           remote.status != "not_started",
           let pos = remote.lastPosition {
            return pos
        }
        // 2. Fallback: local cache (ReadingPositionStore)
        return ReadingPositionStore.shared.get(for: materialId)
    }
}
```

## 9. 分析页对齐

| API | iOS 界面 |
|-----|---------|
| GET /learning/summary | AnalysisHomeView 顶部卡片 |
| GET /learning/trend?days=7 | 趋势曲线 |
| GET /activity/heatmap?days=365 | 热力图 |

## 10. 错误处理

| 错误码 | iOS 动作 |
|--------|---------|
| MATERIAL_ACCESS_DENIED | 不重试，从队列移除，toast 提示 |
| TEMPORARY_MATERIAL_EXPIRED | 从队列移除 |
| DUPLICATE_EVENT | 直接 ack 移除 |
| SOURCE_DELETED | toast 提示，从队列移除 |
| INVALID_* | 从队列移除，记录日志 |
| 网络错误 | 保留队列，等网络恢复后 retry |
| 5xx | 指数退避重试（1s/2s/4s/8s max 3 retry） |

## 11. 离线策略

- 事件始终写入 Rust buffer + 本地队列
- 无网络时 export 继续执行（Rust buffer 正常），upload 跳过
- 网络恢复时 `reloadStaleEventsV2()` + `flush()`
- 本地队列持久化到文件（JSON），App 重启可恢复