DOC-004 定义核心数据模型 #4

New Issue

wangdl · 2026-05-30T19:48:59+08:00

wangdl commented

2026-05-30 19:48:59 +08:00

定义以下核心模型（所有支持 serde 序列化）：
MaterialType / PreviewMode / DocumentInfo / DocumentBlock / ReadingPosition / ReadingEvent / SearchResult / NoteAnchor / DocumentError

建议文件在 crates/zx_document_core/src/ 下：
material_type.rs / document.rs / blocks.rs / progress.rs / events.rs / search.rs / anchors.rs / error.rs

ReadingPosition 需支持：Markdown、Text、Pdf、Image、Epub
DocumentBlock 需支持：heading、paragraph、list、code、quote、table、image

验收标准：所有核心模型已定义、支持 serde、有基础单元测试

定义以下核心模型（所有支持 serde 序列化）： MaterialType / PreviewMode / DocumentInfo / DocumentBlock / ReadingPosition / ReadingEvent / SearchResult / NoteAnchor / DocumentError 建议文件在 crates/zx_document_core/src/ 下： material_type.rs / document.rs / blocks.rs / progress.rs / events.rs / search.rs / anchors.rs / error.rs ReadingPosition 需支持：Markdown、Text、Pdf、Image、Epub DocumentBlock 需支持：heading、paragraph、list、code、quote、table、image 验收标准：所有核心模型已定义、支持 serde、有基础单元测试

wangdl added this to the M0：项目初始化与技术边界冻结 milestone 2026-05-30 19:48:59 +08:00

wangdl added the

priority:p0

type:design

area:core

labels 2026-05-30 19:48:59 +08:00

wangdl commented

2026-05-30 20:22:45 +08:00

完成项

✅ 所有核心数据模型已定义并编译通过

模型清单

文件	类型	说明
material_type.rs	MaterialType PreviewMode	Markdown/Text/Pdf/Image/Epub/Word/Excel/PPT/Unknown + NativeReader/PlatformPreview/ExternalOpen/Unsupported
blocks.rs	DocumentBlock	Heading/Paragraph/List/CodeBlock/Quote/Table/Image/HorizontalRule，serde(tag = "type")
document.rs	DocumentInfo	material_id/title/material_type/preview_mode/file_size/page_count/word_count/created_at
progress.rs	ReadingPosition	Markdown(block_id,scroll)/Text(line,scroll)/Pdf(page,progress)/Image(zoom,offset)/Epub(chapter,progress)/Unknown
events.rs	ReadingEvent	MaterialOpened/MaterialClosed/PositionChanged/Heartbeat/MarkedAsRead，含 timestamp_ms + active_seconds
search.rs	SearchResult	block_id/line_number/snippet/match_start/match_end
anchors.rs	NoteAnchor	Material/MarkdownBlock/TextLine/PdfPage/Image/EpubChapter/KnowledgeItem
error.rs	DocumentError	FileNotFound/UnsupportedFormat/ParseError/InvalidEncoding/IoError，impl Error + Display + Fromio::Error

技术细节

所有模型实现 Serialize + Deserialize（serde）
枚举使用 #[serde(tag = "type")] 内部标签序列化
依赖：serde = { version = "1", features = ["derive"] } + serde_json = "1"
cargo check 编译通过 ✅
修复了 crate edition 2024 → 2021

待跟进

⬜ 编写单元测试（serde 序列化/反序列化往返测试）
⬜ DOC-005 App ↔ Rust 调用协议
⬜ DOC-101 实现文件类型识别

## 完成项 ✅ 所有核心数据模型已定义并编译通过 ### 模型清单 | 文件 | 类型 | 说明 | |------|------|------| | material_type.rs | MaterialType PreviewMode | Markdown/Text/Pdf/Image/Epub/Word/Excel/PPT/Unknown + NativeReader/PlatformPreview/ExternalOpen/Unsupported | | blocks.rs | DocumentBlock | Heading/Paragraph/List/CodeBlock/Quote/Table/Image/HorizontalRule，serde(tag = "type") | | document.rs | DocumentInfo | material_id/title/material_type/preview_mode/file_size/page_count/word_count/created_at | | progress.rs | ReadingPosition | Markdown(block_id,scroll)/Text(line,scroll)/Pdf(page,progress)/Image(zoom,offset)/Epub(chapter,progress)/Unknown | | events.rs | ReadingEvent | MaterialOpened/MaterialClosed/PositionChanged/Heartbeat/MarkedAsRead，含 timestamp_ms + active_seconds | | search.rs | SearchResult | block_id/line_number/snippet/match_start/match_end | | anchors.rs | NoteAnchor | Material/MarkdownBlock/TextLine/PdfPage/Image/EpubChapter/KnowledgeItem | | error.rs | DocumentError | FileNotFound/UnsupportedFormat/ParseError/InvalidEncoding/IoError，impl Error + Display + From<io::Error> | ### 技术细节 - 所有模型实现 Serialize + Deserialize（serde） - 枚举使用 #[serde(tag = "type")] 内部标签序列化 - 依赖：serde = { version = "1", features = ["derive"] } + serde_json = "1" - cargo check 编译通过 ✅ - 修复了 crate edition 2024 → 2021 ### 待跟进 ⬜ 编写单元测试（serde 序列化/反序列化往返测试） ⬜ DOC-005 App ↔ Rust 调用协议 ⬜ DOC-101 实现文件类型识别

wangdl closed this issue

2026-05-30 20:31:14 +08:00

wangdl commented

2026-06-02 20:14:54 +08:00

审查同步 (2026-06-02)

核心数据模型文档已与代码同步：

README 中 Table 变体补 headers: Vec<String> 字段（代码已有，文档漏了）
README 中补 HorizontalRule { id: String } 变体（代码已有，文档漏了）
所有 8 个 DocumentBlock 变体现在文档与代码一致：Heading / Paragraph / List / CodeBlock / Quote / Table / Image / HorizontalRule

## 审查同步 (2026-06-02) 核心数据模型文档已与代码同步： - README 中 Table 变体补 `headers: Vec<String>` 字段（代码已有，文档漏了） - README 中补 `HorizontalRule { id: String }` 变体（代码已有，文档漏了） - 所有 8 个 DocumentBlock 变体现在文档与代码一致：Heading / Paragraph / List / CodeBlock / Quote / Table / Image / HorizontalRule

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#4