docs: add iOS reading info integration guide (IOS-INFO-026)
- Architecture diagram: Swift UI → SessionManager → Collector → Queue → API - Core components: Context, SessionManager, Events, Position, UploadQueue - API protocol: batch upload, progress query, continue-learning, summary - Path resolution, marked-read store, app lifecycle, error handling Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
wangdl
parent
de384dc027
commit
6c2f742676
231
docs/reading-info-integration.md
Normal file
231
docs/reading-info-integration.md
Normal file
@ -0,0 +1,231 @@
|
|||||||
|
# iOS 阅读信息采集接入文档
|
||||||
|
|
||||||
|
## 1. 概述
|
||||||
|
|
||||||
|
AIStudyApp 通过 Rust FFI（zx_document_core）和自有 Swift 层采集用户阅读行为数据，上传至 API Server，为 AI 分析和个性化推荐提供数据基础。
|
||||||
|
|
||||||
|
数据流：Swift UI → ReadingRuntimeSessionManager → ReadingEventCollector → ReadingEventUploadQueue → API Server
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 架构
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ SwiftUI Layer │
|
||||||
|
│ MaterialReaderView → open/close/heartbeat/position │
|
||||||
|
└──────────────────┬──────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌──────────────────▼──────────────────────────────────┐
|
||||||
|
│ ReadingRuntimeSessionManager (Singleton) │
|
||||||
|
│ 职责：生命周期管理、状态机、适配器路由 │
|
||||||
|
│ 状态：idle → opened → reading → closed │
|
||||||
|
└──────────────────┬──────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌──────────────────▼──────────────────────────────────┐
|
||||||
|
│ ReadingEventCollector (Singleton) │
|
||||||
|
│ 职责：事件缓冲、去重、序列化 │
|
||||||
|
│ 事件类型：opened / heartbeat / position_changed / │
|
||||||
|
│ closed / marked_as_read / failed │
|
||||||
|
└──────────────────┬──────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌──────────────────▼──────────────────────────────────┐
|
||||||
|
│ ReadingEventUploadQueue (Singleton) │
|
||||||
|
│ 职责：批量上传、重试、ACK 确认 │
|
||||||
|
│ 上传间隔：30s（默认） │
|
||||||
|
│ 最大批次：50 条 │
|
||||||
|
└──────────────────┬──────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌──────────────────▼──────────────────────────────────┐
|
||||||
|
│ ReadingAPIService (APIClient) │
|
||||||
|
│ 端点：POST /api/reading-events/batch │
|
||||||
|
│ GET /api/reading/progress/:id │
|
||||||
|
└─────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 核心组件
|
||||||
|
|
||||||
|
### 3.1 ReadingMaterialContext
|
||||||
|
|
||||||
|
打开阅读器时需要提供的上下文：
|
||||||
|
|
||||||
|
```swift
|
||||||
|
struct ReadingMaterialContext {
|
||||||
|
let readingTargetType: ReadingTargetType // .material, .knowledgeSource
|
||||||
|
let materialId: String
|
||||||
|
let knowledgeBaseId: String?
|
||||||
|
let userId: String?
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 ReadingRuntimeSessionManager
|
||||||
|
|
||||||
|
| 方法 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `openMaterial(_ ctx:)` | 打开阅读会话，触发 `opened` 事件 |
|
||||||
|
| `closeMaterial()` | 关闭会话，触发 `closed` 事件 |
|
||||||
|
| `updatePosition(_ pos:)` | 更新阅读位置，触发 `position_changed` 事件 |
|
||||||
|
| `sendHeartbeat()` | 心跳，更新活跃时间 |
|
||||||
|
| `markAsRead()` | 标记已读 |
|
||||||
|
| `adapter` | V1/V2 适配器切换 |
|
||||||
|
|
||||||
|
### 3.3 ReadingEvent
|
||||||
|
|
||||||
|
```swift
|
||||||
|
enum ReadingEvent {
|
||||||
|
case opened(materialId: String, timestamp: UInt64)
|
||||||
|
case heartbeat(materialId: String, position: ReadingPosition?, timestamp: UInt64)
|
||||||
|
case positionChanged(materialId: String, position: ReadingPosition, timestamp: UInt64)
|
||||||
|
case closed(materialId: String, totalActiveMs: UInt64, timestamp: UInt64)
|
||||||
|
case markedAsRead(materialId: String, timestamp: UInt64)
|
||||||
|
case failed(materialId: String, errorCode: String, timestamp: UInt64)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.4 ReadingPosition
|
||||||
|
|
||||||
|
```swift
|
||||||
|
enum ReadingPosition {
|
||||||
|
case markdown(blockId: String, scrollProgress: Float)
|
||||||
|
case text(lineNumber: UInt32, scrollProgress: Float)
|
||||||
|
case pdf(pageNumber: UInt32, pageProgress: Float, overallProgress: Float)
|
||||||
|
case image(zoomScale: Float, offsetX: Float, offsetY: Float)
|
||||||
|
case epub(chapterId: String, chapterProgress: Float, overallProgress: Float)
|
||||||
|
case unknown
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 上传协议
|
||||||
|
|
||||||
|
### 4.1 批量上传
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/reading-events/batch
|
||||||
|
Authorization: Bearer <USER_JWT>
|
||||||
|
|
||||||
|
{
|
||||||
|
"events": [
|
||||||
|
{
|
||||||
|
"eventType": "position_changed",
|
||||||
|
"materialId": "mat-001",
|
||||||
|
"position": { "type": "Markdown", "blockId": "b1", "scrollProgress": 0.5 },
|
||||||
|
"timestampMs": 1700000000123,
|
||||||
|
"sessionId": "sess-abc"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 阅读进度查询
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/reading/progress/:materialId?targetType=knowledge_source
|
||||||
|
Authorization: Bearer <USER_JWT>
|
||||||
|
|
||||||
|
Response 200:
|
||||||
|
{
|
||||||
|
"materialId": "mat-001",
|
||||||
|
"targetType": "knowledge_source",
|
||||||
|
"status": "in_progress",
|
||||||
|
"totalActiveSeconds": 300,
|
||||||
|
"isMarkedRead": false,
|
||||||
|
"lastReadAt": "2026-06-18T12:00:00Z",
|
||||||
|
"lastPosition": { "type": "Markdown", "blockId": "b1", "scrollProgress": 0.5 }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 位置恢复
|
||||||
|
|
||||||
|
### 5.1 继续学习
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/reading/continue-learning
|
||||||
|
Authorization: Bearer <USER_JWT>
|
||||||
|
|
||||||
|
Response 200:
|
||||||
|
{
|
||||||
|
"type": "knowledge_source",
|
||||||
|
"materialId": "mat-001",
|
||||||
|
"title": "Machine Learning Basics",
|
||||||
|
"lastProgress": 0.5,
|
||||||
|
"totalActiveSeconds": 600,
|
||||||
|
"lastReadAt": "2026-06-18T10:00:00Z",
|
||||||
|
"lastPosition": { "type": "Markdown", "blockId": "b1", "scrollProgress": 0.5 }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 学习摘要
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/reading/learning-summary
|
||||||
|
Authorization: Bearer <USER_JWT>
|
||||||
|
|
||||||
|
Response 200:
|
||||||
|
{
|
||||||
|
"todaySeconds": 3600,
|
||||||
|
"weekSeconds": 7200,
|
||||||
|
"totalSeconds": 50000,
|
||||||
|
"activeDays": 5,
|
||||||
|
"sessionsCount": 12,
|
||||||
|
"materialsReadCount": 3,
|
||||||
|
"markedReadCount": 1,
|
||||||
|
"dailyAverageSeconds": 1200
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 文件路径解析
|
||||||
|
|
||||||
|
`MaterialPathResolver` 负责将 API 返回的 materialId 解析为本地文件路径：
|
||||||
|
|
||||||
|
| 优先级 | 策略 | 路径 |
|
||||||
|
|:--:|------|------|
|
||||||
|
| 1 | Knowledge Source | `Documents/knowledge_sources/<id>/<filename>` |
|
||||||
|
| 2 | Documents 目录 | `Documents/<materialId>` |
|
||||||
|
| 3 | Caches 目录 | `Caches/<materialId>` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 已读标记
|
||||||
|
|
||||||
|
`MarkedReadStore` 提供离线已读标记（UserDefaults 持久化）：
|
||||||
|
|
||||||
|
- `mark(materialId)` — 标记已读
|
||||||
|
- `unmark(materialId)` — 取消标记
|
||||||
|
- `contains(materialId)` — 查询是否已读
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. App 生命周期
|
||||||
|
|
||||||
|
| 事件 | 处理 |
|
||||||
|
|------|------|
|
||||||
|
| `sceneDidEnterBackground` | UploadScheduler.flush() 强制上传 |
|
||||||
|
| `sceneWillEnterForeground` | RuntimeRecoveryService 恢复未完成会话 |
|
||||||
|
| `applicationWillTerminate` | 关闭所有活跃 Session + flush |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 错误处理
|
||||||
|
|
||||||
|
| 场景 | 策略 |
|
||||||
|
|------|------|
|
||||||
|
| 网络不可用 | 事件缓冲在本地队列，最多保留 1000 条 |
|
||||||
|
| 上传失败 | 指数退避重试（1s→2s→4s→8s→30s） |
|
||||||
|
| ACK 丢失 | 未 ACK 事件下次上传时重发 |
|
||||||
|
| Rust FFI 崩溃 | V1 fallback 适配器（NoopReadingRuntimeAdapter） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 相关文档
|
||||||
|
|
||||||
|
- [阅读事件 API 协议](./reading-event-api-protocol.md)（api-server 仓库）
|
||||||
|
- [V2 事件 Pipeline 架构](./v2-event-pipeline.md)
|
||||||
|
- [Rust FFI 绑定更新流程](./rust-ffi-update.md)
|
||||||
Loading…
x
Reference in New Issue
Block a user