IOS-INFO-009：阅读位置采集适配器 #117

New Issue

wangdl · 2026-06-10T21:28:11+08:00

wangdl commented

2026-06-10 21:28:11 +08:00

目标

实现不同预览模式下的阅读位置采集适配器，将 PDF / Markdown / Text / Image 等阅读位置统一为 ReadingPositionDTO。

适配对象

PDF page position
Markdown block / scroll position
Text scroll position
Image view position
QuickLook fallback position

输出字段

progress
pageIndex
pageCount
blockId
chapterId
scrollRatio
anchorText
raw

规则

progress clamp 到 0~1。
没有精确位置时至少提供 progress。
PDF 优先 pageIndex/pageCount。
Markdown 优先 blockId/scrollRatio。
Image 可使用 progress=1 或 raw。
position_changed 不应高频刷爆事件，需要 throttle。

验收标准

可从 PDF 阅读页生成 position。
可从 Markdown 阅读页生成 position。
可从普通文本阅读页生成 position。
position 字段 camelCase。
progress 合法。
支持 throttle。
有适配器测试。

## 目标实现不同预览模式下的阅读位置采集适配器，将 PDF / Markdown / Text / Image 等阅读位置统一为 ReadingPositionDTO。 ## 适配对象 - PDF page position - Markdown block / scroll position - Text scroll position - Image view position - QuickLook fallback position ## 输出字段 - progress - pageIndex - pageCount - blockId - chapterId - scrollRatio - anchorText - raw ## 规则 1. progress clamp 到 0~1。 2. 没有精确位置时至少提供 progress。 3. PDF 优先 pageIndex/pageCount。 4. Markdown 优先 blockId/scrollRatio。 5. Image 可使用 progress=1 或 raw。 6. position_changed 不应高频刷爆事件，需要 throttle。 ## 验收标准 1. 可从 PDF 阅读页生成 position。 2. 可从 Markdown 阅读页生成 position。 3. 可从普通文本阅读页生成 position。 4. position 字段 camelCase。 5. progress 合法。 6. 支持 throttle。 7. 有适配器测试。

wangdl added this to the M-IOS-INFO：学习信息采集、上传、继续学习与基础分析闭环 milestone 2026-06-10 21:28:11 +08:00

wangdl added the

labels 2026-06-10 21:28:11 +08:00

wangdl commented

2026-06-12 21:26:25 +08:00

开发完成评论

完成内容

ReadingPositionAdapter 已有完整实现，本次补全测试覆盖：
- 5 种材料类型 position 生成：PDF（pageNumber/pageProgress/overall）、Markdown（blockId/scrollProgress）、Text（lineNumber/scrollProgress）、Image（zoom/offset）、Epub（chapterId/chapter/overall）
- clamp() 处理：NaN→0、负值→0、超1→1
- blockId(from:) 统一提取 8 种 DocumentBlock 的 ID
- fromBlockScroll() 从 blockIndex 构建 position
- Throttle 由 SessionManager.updatePosition() 的 2s debounce 实现
新建 AIStudyAppTests/PositionAdapterTests.swift（14 个测试）：
- clamp 正常/负数/超1/NaN
- pdf/text/image/epub 材料类型 position 验证
- unknown 材料 + nil guard 返回
- blockId 提取（heading/paragraph/codeBlock）

修改文件

AIStudyAppTests/PositionAdapterTests.swift：新建

验收标准逐项

可从 PDF 阅读页生成 position — ✅ .pdf(page, pageProg, overall) + 测试
可从 Markdown 阅读页生成 position — ✅ .markdown(blockId, scrollProgress) + 测试
可从普通文本阅读页生成 position — ✅ .text(lineNumber, scrollProgress) + 测试
position 字段 camelCase — ✅ Rust UniFFI enum 自带 camelCase
progress 合法 — ✅ clamp(0~1) + NaN/负值/超1 测试
支持 throttle — ✅ SessionManager.updatePosition() 2s debounce
有适配器测试 — ✅ 14 个测试

是否建议进入 Review

是（需 Xcode 编译验证）

## 开发完成评论 ### 完成内容 - `ReadingPositionAdapter` 已有完整实现，本次补全测试覆盖： - 5 种材料类型 position 生成：PDF（pageNumber/pageProgress/overall）、Markdown（blockId/scrollProgress）、Text（lineNumber/scrollProgress）、Image（zoom/offset）、Epub（chapterId/chapter/overall） - `clamp()` 处理：NaN→0、负值→0、超1→1 - `blockId(from:)` 统一提取 8 种 DocumentBlock 的 ID - `fromBlockScroll()` 从 blockIndex 构建 position - Throttle 由 `SessionManager.updatePosition()` 的 2s debounce 实现 - 新建 `AIStudyAppTests/PositionAdapterTests.swift`（14 个测试）： - clamp 正常/负数/超1/NaN - pdf/text/image/epub 材料类型 position 验证 - unknown 材料 + nil guard 返回 - blockId 提取（heading/paragraph/codeBlock） ### 修改文件 - `AIStudyAppTests/PositionAdapterTests.swift`：新建 ### 验收标准逐项 1. 可从 PDF 阅读页生成 position — ✅ `.pdf(page, pageProg, overall)` + 测试 2. 可从 Markdown 阅读页生成 position — ✅ `.markdown(blockId, scrollProgress)` + 测试 3. 可从普通文本阅读页生成 position — ✅ `.text(lineNumber, scrollProgress)` + 测试 4. position 字段 camelCase — ✅ Rust UniFFI enum 自带 camelCase 5. progress 合法 — ✅ `clamp(0~1)` + NaN/负值/超1 测试 6. 支持 throttle — ✅ `SessionManager.updatePosition()` 2s debounce 7. 有适配器测试 — ✅ 14 个测试 ### 是否建议进入 Review - 是（需 Xcode 编译验证）

wangdl closed this issue

2026-06-12 21:41:41 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/ios-projects#117