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

IOS-INFO-014：App 前后台 flush / pause / resume #122

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

目标

在 App 前后台切换时正确处理阅读 session、heartbeat、事件导出和本地队列写入。

场景

  • active → background
  • background → active
  • active → inactive
  • app terminate best effort

规则

  1. 进入后台时 pause heartbeat。
  2. 进入后台时 best-effort export pending events。
  3. export 后写本地队列，成功才 ack。
  4. 回到前台时 resume heartbeat。
  5. 若 session 已失效，重新 open 或恢复 session。
  6. 前后台切换不应重复 open。

Session 失效判断条件

  1. App 从冷启动恢复，内存中的 sessionId 不存在。
  2. Runtime 返回 SESSION_NOT_FOUND。
  3. Runtime 返回 SESSION_ALREADY_CLOSED。
  4. session 进入后台超过 sessionResumeMaxAge。
  5. App crash / system kill 后重新启动。
  6. Runtime buffer 经 reload_stale_events_v2 恢复后，旧 session 不再可继续写入。

处理规则

  1. session 失效后，不继续 heartbeat。
  2. session 失效后，不继续 recordPositionChanged。
  3. 若用户仍在阅读页，重新 open 新 session。
  4. 旧 session 尽量标记 interrupted。
  5. 新旧 session 的事件不能混用同一个 clientSessionId。

验收标准

  1. 进入后台会 pause。
  2. 进入后台会尝试 flush。
  3. flush 成功后 ack。
  4. 回前台会 resume。
  5. 不重复创建 session。
  6. App 生命周期日志可观察。
  7. 有测试或手动验收脚本。
## 目标 在 App 前后台切换时正确处理阅读 session、heartbeat、事件导出和本地队列写入。 ## 场景 - active → background - background → active - active → inactive - app terminate best effort ## 规则 1. 进入后台时 pause heartbeat。 2. 进入后台时 best-effort export pending events。 3. export 后写本地队列，成功才 ack。 4. 回到前台时 resume heartbeat。 5. 若 session 已失效，重新 open 或恢复 session。 6. 前后台切换不应重复 open。 ## Session 失效判断条件 1. App 从冷启动恢复，内存中的 sessionId 不存在。 2. Runtime 返回 SESSION_NOT_FOUND。 3. Runtime 返回 SESSION_ALREADY_CLOSED。 4. session 进入后台超过 sessionResumeMaxAge。 5. App crash / system kill 后重新启动。 6. Runtime buffer 经 reload_stale_events_v2 恢复后，旧 session 不再可继续写入。 ## 处理规则 1. session 失效后，不继续 heartbeat。 2. session 失效后，不继续 recordPositionChanged。 3. 若用户仍在阅读页，重新 open 新 session。 4. 旧 session 尽量标记 interrupted。 5. 新旧 session 的事件不能混用同一个 clientSessionId。 ## 验收标准 1. 进入后台会 pause。 2. 进入后台会尝试 flush。 3. flush 成功后 ack。 4. 回前台会 resume。 5. 不重复创建 session。 6. App 生命周期日志可观察。 7. 有测试或手动验收脚本。
wangdl added this to the M-IOS-INFO：学习信息采集、上传、继续学习与基础分析闭环 milestone 2026-06-10 21:28:13 +08:00
wangdl added the
blocked-by:doc-runtime
 label 2026-06-10 22:15:58 +08:00
wangdl commented 2026-06-12 21:51:25 +08:00
Author
Owner
Copy Link

开发完成评论

完成内容

  • SessionManager 添加 Session 失效检测：
    • backgroundedAtMs — 记录进入后台时间戳
    • sessionResumeMaxAgeMs — 5 分钟后台超时
    • isSessionStale — 后台超过 5 分钟判定为 stale
    • pause() 记录 backgroundedAtMs = nowMs()
    • resume() 检测 isSessionStale → 自动 closeMaterial() 让调用方重新 open
  • 已有前后台处理（前序 Issue）：
    • App 级 scenePhase.background → pause + flush
    • App 级 scenePhase.active → resume + recovery
    • View 级 scenePhase.background → pause + flush（IOS-INFO-007）
    • View 级 scenePhase.active → resume（IOS-INFO-007）
    • exportAndEnqueue ack 时机正确（IOS-INFO-011）
  • 新建 AIStudyAppTests/AppLifecycleFlushTests.swift（6 个测试）：
    • pause → paused 状态
    • resume → active 状态
    • stale session close 清理
    • idle resume no-op
    • pipeline exportAndEnqueue 不崩溃
    • 3 次 pause/resume 循环

修改文件

  • Features/MaterialReader/ReadingRuntimeSessionManager.swift：+15 行（stale 检测 + pause/resume 增强）
  • AIStudyAppTests/AppLifecycleFlushTests.swift：新建

验收标准逐项

  1. 进入后台会 pause — ✅ App 级 + View 级双层 scenePhase.background → pause()
  2. 进入后台会尝试 flush — ✅ exportAndEnqueue() + flush()
  3. flush 成功后 ack — ✅ ack 在 enqueue 后立即执行（IOS-INFO-011）
  4. 回前台会 resume — ✅ App 级 + View 级双层 scenePhase.active → resume()
  5. 不重复创建 session — ✅ isV2Active guard
  6. App 生命周期日志可观察 — ✅ print("[SessionManager] Session stale...")
  7. 有测试 — ✅ 6 个测试

是否建议进入 Review

  • 是（需 Xcode 编译验证）
## 开发完成评论 ### 完成内容 - SessionManager 添加 Session 失效检测： - `backgroundedAtMs` — 记录进入后台时间戳 - `sessionResumeMaxAgeMs` — 5 分钟后台超时 - `isSessionStale` — 后台超过 5 分钟判定为 stale - `pause()` 记录 `backgroundedAtMs = nowMs()` - `resume()` 检测 `isSessionStale` → 自动 `closeMaterial()` 让调用方重新 open - 已有前后台处理（前序 Issue）： - App 级 `scenePhase.background` → pause + flush - App 级 `scenePhase.active` → resume + recovery - View 级 `scenePhase.background` → pause + flush（IOS-INFO-007） - View 级 `scenePhase.active` → resume（IOS-INFO-007） - `exportAndEnqueue` ack 时机正确（IOS-INFO-011） - 新建 `AIStudyAppTests/AppLifecycleFlushTests.swift`（6 个测试）： - pause → paused 状态 - resume → active 状态 - stale session close 清理 - idle resume no-op - pipeline exportAndEnqueue 不崩溃 - 3 次 pause/resume 循环 ### 修改文件 - `Features/MaterialReader/ReadingRuntimeSessionManager.swift`：+15 行（stale 检测 + pause/resume 增强） - `AIStudyAppTests/AppLifecycleFlushTests.swift`：新建 ### 验收标准逐项 1. 进入后台会 pause — ✅ App 级 + View 级双层 `scenePhase.background → pause()` 2. 进入后台会尝试 flush — ✅ `exportAndEnqueue()` + `flush()` 3. flush 成功后 ack — ✅ ack 在 enqueue 后立即执行（IOS-INFO-011） 4. 回前台会 resume — ✅ App 级 + View 级双层 `scenePhase.active → resume()` 5. 不重复创建 session — ✅ `isV2Active` guard 6. App 生命周期日志可观察 — ✅ `print("[SessionManager] Session stale...")` 7. 有测试 — ✅ 6 个测试 ### 是否建议进入 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:flush
work:lifecycle
work:offline
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#122
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?