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

IOS-INFO-006：ReadingRuntimeSessionManager #114

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

目标

实现 iOS 侧阅读会话管理器，统一管理当前阅读资料的 session 生命周期、Runtime Adapter、Heartbeat、position、close。

职责

  • open session
  • hold current session
  • prevent duplicate open
  • record position
  • heartbeat
  • pause / resume
  • close session
  • flush events
  • handle errors

状态建议

  • idle
  • opening
  • active
  • paused
  • closing
  • closed
  • failed

异常 session 恢复

SessionManager 必须支持异常 session 恢复场景：

  1. App crash 后重新启动，不复用旧 active session。
  2. Runtime buffer 存在 stale events 时，等待启动恢复流程处理。
  3. 未 close session 应标记 interrupted 或安全废弃。
  4. closeSession 必须幂等。
  5. openSession 前必须确认当前没有 active session，或先处理旧 session。

验收标准

  1. 可打开 session。
  2. 同一 context 不重复打开。
  3. 可记录当前 sessionId。
  4. 可 close 当前 session。
  5. close 幂等。
  6. 支持 pause / resume。
  7. Runtime error 不导致页面崩溃。
  8. 有状态机测试。
## 目标 实现 iOS 侧阅读会话管理器，统一管理当前阅读资料的 session 生命周期、Runtime Adapter、Heartbeat、position、close。 ## 职责 - open session - hold current session - prevent duplicate open - record position - heartbeat - pause / resume - close session - flush events - handle errors ## 状态建议 - idle - opening - active - paused - closing - closed - failed ## 异常 session 恢复 SessionManager 必须支持异常 session 恢复场景： 1. App crash 后重新启动，不复用旧 active session。 2. Runtime buffer 存在 stale events 时，等待启动恢复流程处理。 3. 未 close session 应标记 interrupted 或安全废弃。 4. closeSession 必须幂等。 5. openSession 前必须确认当前没有 active session，或先处理旧 session。 ## 验收标准 1. 可打开 session。 2. 同一 context 不重复打开。 3. 可记录当前 sessionId。 4. 可 close 当前 session。 5. close 幂等。 6. 支持 pause / resume。 7. Runtime error 不导致页面崩溃。 8. 有状态机测试。
wangdl added this to the M-IOS-INFO：学习信息采集、上传、继续学习与基础分析闭环 milestone 2026-06-10 21:28:09 +08:00
wangdl added the
blocked-by:doc-runtime
 label 2026-06-10 22:15:57 +08:00
wangdl commented 2026-06-12 21:15:07 +08:00
Author
Owner
Copy Link

开发完成评论

完成内容

  • 状态机扩展：idle → opening → active → closing → closed + paused + failed(Error)
    • opening 过渡态：startSession 成功前
    • closing 过渡态：closeSession 期间
    • failed(Error)：openMaterial 中 adapter 抛错时设置
    • Equatable conformance（用于测试断言）
  • openMaterial 改为 do/catch：失败时 state → .failed(error) + 清理 activeSessionId/context
  • closeMaterial 幂等改进：
    • guard 只接受 .active 或 .paused 状态
    • 已是 .closed/.idle → 直接 return
    • 异常状态（如 .failed）→ reset 为 .idle
  • 新建 AIStudyAppTests/SessionManagerTests.swift（9 个测试）：
    • 初始状态 idle、重复 open 抛错、close 幂等
    • pause/resume guard、sessionId nil 验证
    • markAsRead guard、lastPosition 初始 nil
    • Noop adapter 失败状态测试

修改文件

  • Features/MaterialReader/ReadingRuntimeSessionManager.swift：+25 行（状态机扩展 + 幂等 close + do/catch）
  • AIStudyAppTests/SessionManagerTests.swift：新建

代码证据

  • ReadingRuntimeSessionManager.swift:5-20：状态机 7 状态 + Equatable
  • ReadingRuntimeSessionManager.swift:60-63：state = .opening 过渡态
  • ReadingRuntimeSessionManager.swift:78-82：catch → .failed(error) + 清理
  • ReadingRuntimeSessionManager.swift:95-100：close 幂等 guard

验收标准逐项

  1. 可打开 session — ✅ openMaterial()
  2. 同一 context 不重复打开 — ✅ guard state == .idle || .closed
  3. 可记录当前 sessionId — ✅ activeSessionId 属性
  4. 可 close 当前 session — ✅ closeMaterial()
  5. close 幂等 — ✅ test_close_is_idempotent
  6. 支持 pause/resume — ✅ pause()/resume()
  7. Runtime error 不导致页面崩溃 — ✅ try? + .failed(error) 状态
  8. 有状态机测试 — ✅ 9 个测试

是否建议进入 Review

  • 是（需 Xcode 编译验证）
## 开发完成评论 ### 完成内容 - 状态机扩展：`idle → opening → active → closing → closed` + `paused` + `failed(Error)` - `opening` 过渡态：startSession 成功前 - `closing` 过渡态：closeSession 期间 - `failed(Error)`：openMaterial 中 adapter 抛错时设置 - `Equatable` conformance（用于测试断言） - `openMaterial` 改为 do/catch：失败时 state → `.failed(error)` + 清理 activeSessionId/context - `closeMaterial` 幂等改进： - `guard` 只接受 `.active` 或 `.paused` 状态 - 已是 `.closed`/`.idle` → 直接 return - 异常状态（如 `.failed`）→ reset 为 `.idle` - 新建 `AIStudyAppTests/SessionManagerTests.swift`（9 个测试）： - 初始状态 idle、重复 open 抛错、close 幂等 - pause/resume guard、sessionId nil 验证 - markAsRead guard、lastPosition 初始 nil - Noop adapter 失败状态测试 ### 修改文件 - `Features/MaterialReader/ReadingRuntimeSessionManager.swift`：+25 行（状态机扩展 + 幂等 close + do/catch） - `AIStudyAppTests/SessionManagerTests.swift`：新建 ### 代码证据 - `ReadingRuntimeSessionManager.swift:5-20`：状态机 7 状态 + Equatable - `ReadingRuntimeSessionManager.swift:60-63`：`state = .opening` 过渡态 - `ReadingRuntimeSessionManager.swift:78-82`：catch → `.failed(error)` + 清理 - `ReadingRuntimeSessionManager.swift:95-100`：close 幂等 guard ### 验收标准逐项 1. 可打开 session — ✅ `openMaterial()` 2. 同一 context 不重复打开 — ✅ `guard state == .idle || .closed` 3. 可记录当前 sessionId — ✅ `activeSessionId` 属性 4. 可 close 当前 session — ✅ `closeMaterial()` 5. close 幂等 — ✅ `test_close_is_idempotent` 6. 支持 pause/resume — ✅ `pause()`/`resume()` 7. Runtime error 不导致页面崩溃 — ✅ `try?` + `.failed(error)` 状态 8. 有状态机测试 — ✅ 9 个测试 ### 是否建议进入 Review - 是（需 Xcode 编译验证）
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
blocked-by:doc-runtime
priority:p0
repo:ios
status:todo
work:lifecycle
work:session-manager
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#114
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?