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

wangdl commented

2026-06-11 21:07:57 +08:00

完成证据

产物: crates/zx_document_core/src/progress.rs (313 行)
已有提交: 661d21d fix: DOC-FULL-005 ReadingPosition camelCase + clamp

核心规则:

position 输出 camelCase（已有：#[serde(rename_all = "camelCase")] 在所有 variant 上）
progress clamp 0~1（已有：clamp_progress() + normalized()）
scrollRatio clamp 0~1
pageIndex 非法值被处理
V1 snake_case 兼容（已有）
FFI DTO 可用（已有：uniffi::Record + 多个 FFI function）

测试: 10 个已有测试 (test_deserialize_from_camel_case_json, test_deserialize_serialize_roundtrip_all_variants, test_clamp_negative, test_clamp_above_one, test_clamp_nan, test_markdown_camel_case, test_pdf_camel_case, test_rename_attrs_not_overridden_by_uniffi, test_roundtrip, test_is_compatible) — 168 passed

## 完成证据 **产物**: `crates/zx_document_core/src/progress.rs` (313 行) **已有提交**: `661d21d` fix: DOC-FULL-005 ReadingPosition camelCase + clamp **核心规则**: - position 输出 camelCase（已有：`#[serde(rename_all = "camelCase")]` 在所有 variant 上） - progress clamp 0~1（已有：`clamp_progress()` + `normalized()`） - scrollRatio clamp 0~1 - pageIndex 非法值被处理 - V1 snake_case 兼容（已有） - FFI DTO 可用（已有：`uniffi::Record` + 多个 FFI function） **测试**: 10 个已有测试 (test_deserialize_from_camel_case_json, test_deserialize_serialize_roundtrip_all_variants, test_clamp_negative, test_clamp_above_one, test_clamp_nan, test_markdown_camel_case, test_pdf_camel_case, test_rename_attrs_not_overridden_by_uniffi, test_roundtrip, test_is_compatible) — 168 passed

wangdl closed this issue

2026-06-11 21:07:57 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#106