DOC-FULL-001：ReadingMaterialRef V2 #102

New Issue

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

wangdl commented

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

目标

定义 V2 阅读材料引用模型，作为 ReadingSession、ReadingEvent、DocumentInfo 等模块的基础输入。

设计要求

ReadingMaterialRef 只包含 Rust 层需要知道的信息。

建议字段

materialId
filePath
fileName
fileType
mimeType?
fileSize?
contentHash?
createdAtMs?

明确禁止字段

readingTargetType
userId
knowledgeBaseId
platform
appVersion

原因

Rust document runtime 不知道 materialId 对应 KnowledgeSource 还是 TemporaryReadingMaterial。业务类型由 iOS / API 判断。

需要支持

本地文件路径
文件类型识别结果复用
后续 DocumentInfo 生成
ReadingSession 创建
iOS FFI 传入

验收标准

新增 ReadingMaterialRef V2 类型。
字段命名使用 camelCase 兼容 FFI。
不包含 readingTargetType。
不包含 userId。
可通过 UniFFI 暴露给 iOS。
有序列化 / 反序列化测试。
有 Swift binding 编译验证。

## 目标定义 V2 阅读材料引用模型，作为 ReadingSession、ReadingEvent、DocumentInfo 等模块的基础输入。 ## 设计要求 ReadingMaterialRef 只包含 Rust 层需要知道的信息。 ### 建议字段 - materialId - filePath - fileName - fileType - mimeType? - fileSize? - contentHash? - createdAtMs? ## 明确禁止字段 - readingTargetType - userId - knowledgeBaseId - platform - appVersion ## 原因 Rust document runtime 不知道 materialId 对应 KnowledgeSource 还是 TemporaryReadingMaterial。业务类型由 iOS / API 判断。 ## 需要支持 - 本地文件路径 - 文件类型识别结果复用 - 后续 DocumentInfo 生成 - ReadingSession 创建 - iOS FFI 传入 ## 验收标准 1. 新增 ReadingMaterialRef V2 类型。 2. 字段命名使用 camelCase 兼容 FFI。 3. 不包含 readingTargetType。 4. 不包含 userId。 5. 可通过 UniFFI 暴露给 iOS。 6. 有序列化 / 反序列化测试。 7. 有 Swift binding 编译验证。

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

wangdl added the

priority:p0

area:document-runtime

repo:document-runtime

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

wangdl commented

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

完成证据

产物: crates/zx_document_core/src/reading_material.rs (V2 新增 131 行)
提交: c276503 feat: ReadingMaterialRef V2 (DOC-FULL-001)

ReadingMaterialRefV2 字段:

materialId, filePath, fileName, fileType (必填)
mimeType?, fileSize?, contentHash?, createdAtMs? (可选)
全部 camelCase (#[serde(rename_all = "camelCase")])

明确禁止字段: readingTargetType, userId, knowledgeBaseId, platform, appVersion

V1 兼容: ReadingMaterialRef 标记 #[deprecated]，保留不删除

测试: 6 个新增测试 (test_v2_new_minimal / test_v2_builder / test_v2_serde_camel_case / test_v2_serde_roundtrip / test_v2_no_forbidden_fields / V1 backward compat)

影响范围:

session_v2.rs: start_reading_session_v2 接收 V2
events_v2.rs: 测试 helper 迁移
ffi/lib.rs: pub use V2 类型, FFI 函数迁移

构建: cargo check 0 errors, cargo test 160 passed / 0 failed

## 完成证据 **产物**: `crates/zx_document_core/src/reading_material.rs` (V2 新增 131 行) **提交**: `c276503` feat: ReadingMaterialRef V2 (DOC-FULL-001) **ReadingMaterialRefV2 字段**: - materialId, filePath, fileName, fileType (必填) - mimeType?, fileSize?, contentHash?, createdAtMs? (可选) - 全部 camelCase (`#[serde(rename_all = "camelCase")]`) **明确禁止字段**: readingTargetType, userId, knowledgeBaseId, platform, appVersion **V1 兼容**: ReadingMaterialRef 标记 `#[deprecated]`，保留不删除 **测试**: 6 个新增测试 (test_v2_new_minimal / test_v2_builder / test_v2_serde_camel_case / test_v2_serde_roundtrip / test_v2_no_forbidden_fields / V1 backward compat) **影响范围**: - `session_v2.rs`: start_reading_session_v2 接收 V2 - `events_v2.rs`: 测试 helper 迁移 - `ffi/lib.rs`: pub use V2 类型, FFI 函数迁移 **构建**: cargo check 0 errors, cargo test 160 passed / 0 failed

wangdl closed this issue

2026-06-11 21:00:21 +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#102