wangdl/ios-projects
2
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

IOS-INFO-000：iOS 学习信息采集总设计文档 #108

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

目标

输出 iOS 学习信息采集与上传总设计，明确 iOS 在 Rust document runtime、API 学习信息体系、首页继续学习、资料详情页、分析页之间的职责边界。

背景

当前 iOS 侧存在致命问题：

  1. ReadingEventCollector.open/close 被注释，事件链路断裂。
  2. 无本地上传队列。
  3. 首页继续学习硬编码。
  4. 阅读位置恢复仅本地，且 collector.open 被注释后 lastPosition 可能永远为 nil。
  5. 无 ReadingMaterialContext。
  6. 当前只接 V1 document runtime，V2 事件协议尚未接入。

核心原则

  1. Rust document runtime 只接收 materialId。
  2. iOS 负责 ReadingMaterialContext。
  3. iOS 上传时补 readingTargetType、platform、appVersion、timezone。
  4. Rust export 后，iOS 写入本地 ReadingEventUploadQueue 成功后才 ack。
  5. ack 不等 API 上传成功。
  6. ReadingPositionStore 只能作为兜底。
  7. API reading-progress 是主数据源。
  8. 首页 continue 必须替换硬编码。
  9. iOS 不直接判断聚合结果，只负责采集、上传、展示 API 结果。

文档必须覆盖

  • 模块结构
  • ReadingMaterialContext
  • ReadingRuntimeAdapter
  • ReadingRuntimeSessionManager
  • MaterialReaderView 生命周期
  • Heartbeat Timer
  • position 采集
  • Rust export → local queue → ack
  • ReadingEventUploadQueue
  • UploadScheduler
  • API Client
  • reading-progress 查询
  • continue learning 查询
  • 分析页 summary / trend / heatmap 接入
  • 学习历史 records 接入
  • 离线 / 登录状态 / 删除 / 权限错误
  • 调试面板与日志
  • 测试范围

验收标准

  1. 新增 docs/ios-learning-info-architecture.md。
  2. 文档明确 iOS、Rust、API 的职责边界。
  3. 文档明确 iOS 负责 readingTargetType。
  4. 文档明确 export → local queue → ack 顺序。
  5. 文档明确 API reading-progress 优先，本地缓存兜底。
  6. 文档明确首页 continue 替换硬编码。
  7. 文档能指导 IOS-INFO-001~037 实现。
## 目标 输出 iOS 学习信息采集与上传总设计，明确 iOS 在 Rust document runtime、API 学习信息体系、首页继续学习、资料详情页、分析页之间的职责边界。 ## 背景 当前 iOS 侧存在致命问题： 1. ReadingEventCollector.open/close 被注释，事件链路断裂。 2. 无本地上传队列。 3. 首页继续学习硬编码。 4. 阅读位置恢复仅本地，且 collector.open 被注释后 lastPosition 可能永远为 nil。 5. 无 ReadingMaterialContext。 6. 当前只接 V1 document runtime，V2 事件协议尚未接入。 ## 核心原则 1. Rust document runtime 只接收 materialId。 2. iOS 负责 ReadingMaterialContext。 3. iOS 上传时补 readingTargetType、platform、appVersion、timezone。 4. Rust export 后，iOS 写入本地 ReadingEventUploadQueue 成功后才 ack。 5. ack 不等 API 上传成功。 6. ReadingPositionStore 只能作为兜底。 7. API reading-progress 是主数据源。 8. 首页 continue 必须替换硬编码。 9. iOS 不直接判断聚合结果，只负责采集、上传、展示 API 结果。 ## 文档必须覆盖 - 模块结构 - ReadingMaterialContext - ReadingRuntimeAdapter - ReadingRuntimeSessionManager - MaterialReaderView 生命周期 - Heartbeat Timer - position 采集 - Rust export → local queue → ack - ReadingEventUploadQueue - UploadScheduler - API Client - reading-progress 查询 - continue learning 查询 - 分析页 summary / trend / heatmap 接入 - 学习历史 records 接入 - 离线 / 登录状态 / 删除 / 权限错误 - 调试面板与日志 - 测试范围 ## 验收标准 1. 新增 docs/ios-learning-info-architecture.md。 2. 文档明确 iOS、Rust、API 的职责边界。 3. 文档明确 iOS 负责 readingTargetType。 4. 文档明确 export → local queue → ack 顺序。 5. 文档明确 API reading-progress 优先，本地缓存兜底。 6. 文档明确首页 continue 替换硬编码。 7. 文档能指导 IOS-INFO-001~037 实现。
wangdl added this to the M-IOS-INFO：学习信息采集、上传、继续学习与基础分析闭环 milestone 2026-06-10 21:28:08 +08:00
wangdl commented 2026-06-12 20:37:18 +08:00
Author
Owner
Copy Link

开发完成评论

完成内容

  • 新建 docs/ios-learning-info-architecture.md（335 行）
  • 覆盖全部要求内容：
    • §1 三方职责边界（iOS/Rust/API 表格 + 架构图）
    • §2 核心链路 export → queue → ack（时序约束）
    • §3 九条核心原则逐条定义
    • §4 模块结构（Core/Upload/Networking/Recovery/Home/Analysis/Debug/Tests）
    • §5 ReadingMaterialContext
    • §6 ReadingRuntimeAdapter 协议
    • §7 SessionManager 完整生命周期（onAppear → heartbeat → onDisappear → bg/fg）
    • §8 上传队列 + UploadScheduler 触发时机表
    • §9 阅读位置恢复：API 优先 + 本地兜底决策树
    • §10 API 端点完整列表
    • §11 错误处理表（6 种错误类型 → iOS 动作）
    • §12 离线/登录/删除/权限场景
    • §13 测试范围
    • §14 实现指导（明确引导 IOS-INFO-001~037）

修改文件

  • docs/ios-learning-info-architecture.md：新建

验收标准逐项

  1. 新增 docs/ios-learning-info-architecture.md — ✅
  2. 文档明确 iOS、Rust、API 职责边界 — ✅ §1 表格 + 架构图
  3. 文档明确 iOS 负责 readingTargetType — ✅ 原则 2 + §5
  4. 文档明确 export → local queue → ack 顺序 — ✅ §2 流程图 + 时序约束
  5. 文档明确 API reading-progress 优先，本地缓存兜底 — ✅ §9 决策树
  6. 文档明确首页 continue 替换硬编码 — ✅ 原则 7
  7. 文档能指导 IOS-INFO-001~037 实现 — ✅ §14 显式列出引导 Issue

是否建议进入 Review

  • 是
## 开发完成评论 ### 完成内容 - 新建 `docs/ios-learning-info-architecture.md`（335 行） - 覆盖全部要求内容： - §1 三方职责边界（iOS/Rust/API 表格 + 架构图） - §2 核心链路 export → queue → ack（时序约束） - §3 九条核心原则逐条定义 - §4 模块结构（Core/Upload/Networking/Recovery/Home/Analysis/Debug/Tests） - §5 ReadingMaterialContext - §6 ReadingRuntimeAdapter 协议 - §7 SessionManager 完整生命周期（onAppear → heartbeat → onDisappear → bg/fg） - §8 上传队列 + UploadScheduler 触发时机表 - §9 阅读位置恢复：API 优先 + 本地兜底决策树 - §10 API 端点完整列表 - §11 错误处理表（6 种错误类型 → iOS 动作） - §12 离线/登录/删除/权限场景 - §13 测试范围 - §14 实现指导（明确引导 IOS-INFO-001~037） ### 修改文件 - `docs/ios-learning-info-architecture.md`：新建 ### 验收标准逐项 1. 新增 docs/ios-learning-info-architecture.md — ✅ 2. 文档明确 iOS、Rust、API 职责边界 — ✅ §1 表格 + 架构图 3. 文档明确 iOS 负责 readingTargetType — ✅ 原则 2 + §5 4. 文档明确 export → local queue → ack 顺序 — ✅ §2 流程图 + 时序约束 5. 文档明确 API reading-progress 优先，本地缓存兜底 — ✅ §9 决策树 6. 文档明确首页 continue 替换硬编码 — ✅ 原则 7 7. 文档能指导 IOS-INFO-001~037 实现 — ✅ §14 显式列出引导 Issue ### 是否建议进入 Review - 是
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:ai
AI对话
area:analysis
分析页
area:auth
认证/Apple登录
area:import
文件导入
area:ios-info
iOS 学习信息采集与上传
area:library
知识库
area:notification
通知推送
area:profile
我的页面
area:quiz
测验/自测
area:review
复习卡片
area:search
搜索
area:study
学习首页
audit:planned
已完成宏观规划
blocked-by:api
等待 API 接口
blocked-by:api-info-core
等待 API 学习信息体系核心
blocked-by:doc-runtime
等待 Rust document runtime
priority:p0
最高优先级
priority:p1
高优先级
priority:p2
中优先级
repo:ios
iOS App 仓库
status:blocked
被阻塞
status:done
已完成
status:partial
部分存在，需补全
status:todo
待执行
type:bug
缺陷修复
type:docs
文档
type:feature
新功能
type:ui
UI/UX
work:adapter
适配器
work:analysis
分析页
work:api-client
API Client
work:api-contract
API 契约
work:architecture
架构
work:auth
认证
work:background
后台
work:bg-task
BGTask
work:compatibility
兼容性
work:context
阅读上下文
work:continue-learning
继续学习
work:debug
调试
work:design
架构设计
work:developer-tool
开发者工具
work:diagnostics
诊断
work:docs
文档
work:dto
DTO/数据传输
work:e2e
端到端
work:error-handling
错误处理
work:event
事件
work:event-chain
事件链路
work:event-export
事件导出
work:ffi
FFI 绑定
work:flush
刷新推送
work:heartbeat
心跳计时
work:heatmap
热力图
work:history
历史
work:home
首页
work:integration
接入
work:lifecycle
生命周期
work:local-cache
本地缓存
work:local-queue
本地队列
work:logging
日志
work:mapping
字段映射
work:marked-as-read
标记已读
work:material-detail
资料详情
work:model
数据模型
work:network
网络
work:offline
离线
work:permission
权限
work:persistence
持久化
work:position
阅读位置
work:queue
队列
work:reader-view
阅读器视图
work:reading-progress
阅读进度
work:records
学习记录
work:recovery
恢复
work:restore
位置恢复
work:retry
重试
work:routing
路由
work:runtime
Runtime 接入
work:rust-runtime
Rust document runtime
work:scheduler
调度器
work:session-manager
会话管理
work:state
状态管理
work:summary
Summary
work:test
测试
work:time-tracking
时长追踪
work:trend
趋势
work:ui
UI
work:upload
上传
No Label
area:ios-info
audit:planned
priority:p0
repo:ios
status:todo
work:architecture
work:design
work:docs
Milestone
No items
No Milestone M-IOS-INFO：学习信息采集、上传、继续学习与基础分析闭环
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/ios-projects#108
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?