DOC-FULL-019 P0 | NoteAnchor 完整模型【status:partial】 #68

New Issue

wangdl · 2026-06-07T11:33:16+08:00

wangdl commented

2026-06-07 11:33:16 +08:00

Material/MarkdownBlock/TextLine/PdfPage/Image/EpubChapter/KnowledgeItem/SearchResult 类型，含 materialId/knowledgeItemId/blockId/lineNumber/pageNumber/chapterId/positionSnapshot

M-DOC-FULL 里程碑 issue。详见设计文档。

## Material/MarkdownBlock/TextLine/PdfPage/Image/EpubChapter/KnowledgeItem/SearchResult 类型，含 materialId/knowledgeItemId/blockId/lineNumber/pageNumber/chapterId/positionSnapshot M-DOC-FULL 里程碑 issue。详见设计文档。

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

wangdl changed title from ~~DOC-FULL-019 P0 | NoteAnchor 完整模型~~ to DOC-FULL-019 P0 | NoteAnchor 完整模型【status:partial】

2026-06-07 19:15:04 +08:00

wangdl commented

2026-06-07 19:15:04 +08:00

审查结论：document runtime 当前有文件类型识别/MaterialType/PreviewMode/DocumentInfo(基本)/Markdown解析/Text解析/ImageMeta/Search(V1 Markdown+Text)/NoteAnchor(V1)/ReadingEvent(V1)/ReadingPosition(V1)/EventBuffer(V1基础)/iOS构建/UniFFI绑定/docs。但 V2 核心模型(ReadingSession/EventV2/ActiveTimeTracker)不存在，EventBuffer 缺 ack/failed，Position 缺 camelCase+clamp，PDF/EPUB/Office 为 stub，测试覆盖不足 V2。

本 Issue: anchors.rs 7 种类型。from_position() 实现。缺: from_search_result()、SearchResult anchor 映射。

状态: status:partial
工作类型: work:extend-existing

## 审查结论：document runtime 当前有文件类型识别/MaterialType/PreviewMode/DocumentInfo(基本)/Markdown解析/Text解析/ImageMeta/Search(V1 Markdown+Text)/NoteAnchor(V1)/ReadingEvent(V1)/ReadingPosition(V1)/EventBuffer(V1基础)/iOS构建/UniFFI绑定/docs。但 V2 核心模型(ReadingSession/EventV2/ActiveTimeTracker)不存在，EventBuffer 缺 ack/failed，Position 缺 camelCase+clamp，PDF/EPUB/Office 为 stub，测试覆盖不足 V2。 **本 Issue**: anchors.rs 7 种类型。from_position() 实现。缺: from_search_result()、SearchResult anchor 映射。 **状态**: status:partial **工作类型**: work:extend-existing

wangdl commented

2026-06-07 21:03:58 +08:00

完成报告

改动文件

crates/zx_document_core/src/anchors.rs — NoteAnchor 枚举新增 SearchResultAnchor 变体（material_id + block_id/line_number/page_number/chapter_id + snippet），新增 position_snapshot: Option<ReadingPosition> 字段到 6 个变体（Material/MarkdownBlock/TextLine/PdfPage/Image/EpubChapter），新增 from_search_result() 构造函数
crates/zx_document_ffi/src/lib.rs — 新增 create_note_anchor_from_search uniffi 导出 + C-ABI 包装
crates/zx_document_ffi/src/zx_document.udl — 更新 NoteAnchor 枚举（SearchResultAnchor + position_snapshot）

向后兼容

position_snapshot 使用 #[serde(skip_serializing_if = "Option::is_none", default)]，旧 JSON 无此字段仍可正确反序列化
测试 test_backward_compat_no_snapshot 验证

测试覆盖（6 个新增）

test_from_search_result_markdown / test_from_search_result_pdf / test_from_search_result_epub
test_search_result_anchor_serde / test_anchor_serde_with_snapshot / test_backward_compat_no_snapshot

代码证据

// anchors.rs — SearchResultAnchor variant
SearchResultAnchor {
    material_id: String,
    block_id: Option<String>,
    line_number: Option<u32>,
    page_number: Option<u32>,
    chapter_id: Option<String>,
    snippet: String,
}

// from_search_result constructor
pub fn from_search_result(material_id: &str, result: &SearchResult) -> Self {
    NoteAnchor::SearchResultAnchor {
        material_id: material_id.to_string(),
        block_id: Some(result.block_id.clone()),
        line_number: result.line_number,
        page_number: result.page_number,
        chapter_id: result.chapter_id.clone(),
        snippet: result.snippet.clone(),
    }
}

验证

cargo test anchors — 18 passed, 0 failed
cargo test — 139 passed, 0 failed

## 完成报告 ### 改动文件 - `crates/zx_document_core/src/anchors.rs` — NoteAnchor 枚举新增 `SearchResultAnchor` 变体（material_id + block_id/line_number/page_number/chapter_id + snippet），新增 `position_snapshot: Option<ReadingPosition>` 字段到 6 个变体（Material/MarkdownBlock/TextLine/PdfPage/Image/EpubChapter），新增 `from_search_result()` 构造函数 - `crates/zx_document_ffi/src/lib.rs` — 新增 `create_note_anchor_from_search` uniffi 导出 + C-ABI 包装 - `crates/zx_document_ffi/src/zx_document.udl` — 更新 NoteAnchor 枚举（SearchResultAnchor + position_snapshot） ### 向后兼容 - `position_snapshot` 使用 `#[serde(skip_serializing_if = "Option::is_none", default)]`，旧 JSON 无此字段仍可正确反序列化 - 测试 `test_backward_compat_no_snapshot` 验证 ### 测试覆盖（6 个新增） - `test_from_search_result_markdown` / `test_from_search_result_pdf` / `test_from_search_result_epub` - `test_search_result_anchor_serde` / `test_anchor_serde_with_snapshot` / `test_backward_compat_no_snapshot` ### 代码证据 ```rust // anchors.rs — SearchResultAnchor variant SearchResultAnchor { material_id: String, block_id: Option<String>, line_number: Option<u32>, page_number: Option<u32>, chapter_id: Option<String>, snippet: String, } // from_search_result constructor pub fn from_search_result(material_id: &str, result: &SearchResult) -> Self { NoteAnchor::SearchResultAnchor { material_id: material_id.to_string(), block_id: Some(result.block_id.clone()), line_number: result.line_number, page_number: result.page_number, chapter_id: result.chapter_id.clone(), snippet: result.snippet.clone(), } } ``` ### 验证 ``` cargo test anchors — 18 passed, 0 failed cargo test — 139 passed, 0 failed ```

wangdl closed this issue

2026-06-07 21:04:18 +08:00

wangdl referenced this issue

2026-06-07 21:54:08 +08:00

DOC-FULL-019A P1 | NoteAnchor 完整性验收 + from_search_result 【status:todo】 #87

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#68

DOC-FULL-019 P0 | NoteAnchor 完整模型 【status:partial】 #68

Material/MarkdownBlock/TextLine/PdfPage/Image/EpubChapter/KnowledgeItem/SearchResult 类型，含 materialId/knowledgeItemId/blockId/lineNumber/pageNumber/chapterId/positionSnapshot

完成报告

改动文件

向后兼容

测试覆盖（6 个新增）

代码证据

验证

DOC-FULL-019 P0 | NoteAnchor 完整模型【status:partial】 #68