DOC-FULL-005：ReadingPosition V2 camelCase 与 progress clamp #106

New Issue

wangdl · 2026-06-10T21:18:33+08:00

wangdl commented

2026-06-10 21:18:33 +08:00

目标

修复 / 完成 ReadingPosition V2，确保 position JSON 使用 camelCase，并将 progress clamp 到 0~1。

字段建议

progress
pageIndex
pageCount
blockId
chapterId
scrollRatio
anchorText
raw

规则

position 输出给 iOS / API 时必须使用 camelCase。
progress 小于 0 时 clamp 到 0。
progress 大于 1 时 clamp 到 1。
pageIndex 不得小于 0。
scrollRatio 建议 clamp 到 0~1。
raw 保留特殊文档类型扩展信息。

验收标准

position 序列化字段为 camelCase。
progress clamp 生效。
scrollRatio clamp 生效。
pageIndex 非法值被处理。
V1 position 如存在 snake_case，需要兼容转换。
有单元测试。
有 FFI DTO 测试。

## 目标修复 / 完成 ReadingPosition V2，确保 position JSON 使用 camelCase，并将 progress clamp 到 0~1。 ## 字段建议 - progress - pageIndex - pageCount - blockId - chapterId - scrollRatio - anchorText - raw ## 规则 1. position 输出给 iOS / API 时必须使用 camelCase。 2. progress 小于 0 时 clamp 到 0。 3. progress 大于 1 时 clamp 到 1。 4. pageIndex 不得小于 0。 5. scrollRatio 建议 clamp 到 0~1。 6. raw 保留特殊文档类型扩展信息。 ## 验收标准 1. position 序列化字段为 camelCase。 2. progress clamp 生效。 3. scrollRatio clamp 生效。 4. pageIndex 非法值被处理。 5. V1 position 如存在 snake_case，需要兼容转换。 6. 有单元测试。 7. 有 FFI DTO 测试。

wangdl added this to the M-DOC-FULL：Document Runtime 完整阅读内核与学习事件协议 milestone 2026-06-10 21:18:33 +08:00

wangdl added the

priority:p0

area:document-runtime

repo:document-runtime

labels 2026-06-10 21:18:33 +08:00

Sign in to join this conversation.