DOC-302a zx_document_core 类型迁移到 proc-macro #30

New Issue

wangdl · 2026-06-02T22:18:43+08:00

wangdl commented

2026-06-02 22:18:43 +08:00

目标

给 zx_document_core 的所有导出类型加 UniFFI proc-macro derive。

FFI DTO 边界规则（重要）

优先只给 FFI 边界类型添加 UniFFI derive。

如果 core 类型直接暴露给 Swift/Kotlin，可以在 core 类型上添加 derive
如果 core 类型包含 UniFFI 不支持的字段、泛型、复杂嵌套，必须在 zx_document_ffi 中定义 FFI DTO，再和 core 类型互相转换
不要让 UniFFI 的约束反向污染 core 类型设计

需要标注的类型

Enum（`#[derive(uniffi::Enum)]`）

MaterialType (material_type.rs)
PreviewMode (material_type.rs)
DocumentBlock (blocks.rs)
ReadingPosition (progress.rs)
ReadingEvent (events.rs)
NoteAnchor (anchors.rs)

Record（`#[derive(uniffi::Record)]`）

DocumentInfo (document.rs)
ImageMeta (image_meta.rs)
TextStats (text.rs)
SearchResult (search.rs)

Error（`#[derive(uniffi::Error)]`）

DocumentError (error.rs)

改动

zx_document_core/Cargo.toml 添加 uniffi = "0.28" 依赖
每个类型添加对应的 #[derive(uniffi::*)]
保留现有 #[derive(serde::*)] 等 derive

依赖

无（独立任务）

验收

cargo build -p zx_document_core 通过
cargo test 58 测试全过

## 目标给 zx_document_core 的所有导出类型加 UniFFI proc-macro derive。 ## FFI DTO 边界规则（重要）优先只给 FFI 边界类型添加 UniFFI derive。 - 如果 core 类型**直接暴露给 Swift/Kotlin**，可以在 core 类型上添加 derive - 如果 core 类型包含 UniFFI 不支持的字段、泛型、复杂嵌套，**必须在 zx_document_ffi 中定义 FFI DTO**，再和 core 类型互相转换 - **不要让 UniFFI 的约束反向污染 core 类型设计** ## 需要标注的类型 ### Enum（`#[derive(uniffi::Enum)]`） - `MaterialType` (material_type.rs) - `PreviewMode` (material_type.rs) - `DocumentBlock` (blocks.rs) - `ReadingPosition` (progress.rs) - `ReadingEvent` (events.rs) - `NoteAnchor` (anchors.rs) ### Record（`#[derive(uniffi::Record)]`） - `DocumentInfo` (document.rs) - `ImageMeta` (image_meta.rs) - `TextStats` (text.rs) - `SearchResult` (search.rs) ### Error（`#[derive(uniffi::Error)]`） - `DocumentError` (error.rs) ## 改动 1. zx_document_core/Cargo.toml 添加 `uniffi = "0.28"` 依赖 2. 每个类型添加对应的 `#[derive(uniffi::*)]` 3. 保留现有 `#[derive(serde::*)]` 等 derive ## 依赖 - 无（独立任务） ## 验收 - `cargo build -p zx_document_core` 通过 - `cargo test` 58 测试全过

wangdl added this to the M3：iOS 主 App 资料阅读闭环 milestone 2026-06-02 22:18:43 +08:00

wangdl added the

type:implementation

area:core

labels 2026-06-02 22:18:43 +08:00

wangdl commented

2026-06-03 19:59:55 +08:00

完成 (2026-06-03)

改动

zx_document_core/Cargo.toml 添加 uniffi = "0.28" 依赖 + build-dependencies
新建 crates/zx_document_core/build.rs — 最小 scaffolding 生成
lib.rs 添加 uniffi::setup_scaffolding!()
类型添加 derive：
- #[derive(uniffi::Enum)] → MaterialType, PreviewMode, ReadingPosition, ReadingEvent, NoteAnchor
- #[derive(uniffi::Record)] → DocumentInfo, ImageMeta, TextStats, SearchResult
- #[derive(uniffi::Enum)] 仅 FFI crate → DocumentBlock (core 版本跳过，FFI wrapper 替代)
DocumentError 跳过（IoError(std::io::Error) 不兼容 UniFFI）

遵守 FFI DTO 边界规则

core 类型直接暴露的加 derive
UniFFI 不兼容的类型（DocumentBlock tuple 变体、DocumentError 平铺变体）在 FFI crate 定义
不让 UniFFI 约束反向污染 core 类型设计

验证

cargo build 通过，零警告
cargo test 58 测试全过

## 完成 (2026-06-03) ### 改动 1. `zx_document_core/Cargo.toml` 添加 `uniffi = "0.28"` 依赖 + `build-dependencies` 2. 新建 `crates/zx_document_core/build.rs` — 最小 scaffolding 生成 3. `lib.rs` 添加 `uniffi::setup_scaffolding!()` 4. 类型添加 derive： - `#[derive(uniffi::Enum)]` → MaterialType, PreviewMode, ReadingPosition, ReadingEvent, NoteAnchor - `#[derive(uniffi::Record)]` → DocumentInfo, ImageMeta, TextStats, SearchResult - `#[derive(uniffi::Enum)]` 仅 FFI crate → DocumentBlock (core 版本跳过，FFI wrapper 替代) 5. DocumentError 跳过（`IoError(std::io::Error)` 不兼容 UniFFI） ### 遵守 FFI DTO 边界规则 - core 类型直接暴露的加 derive - UniFFI 不兼容的类型（DocumentBlock tuple 变体、DocumentError 平铺变体）在 FFI crate 定义 - 不让 UniFFI 约束反向污染 core 类型设计 ### 验证 - `cargo build` 通过，零警告 - `cargo test` 58 测试全过

wangdl closed this issue

2026-06-07 20:06:41 +08:00

wangdl commented

2026-06-07 20:06:43 +08:00

关闭

DOC-302a 已完成 — 类型已迁移到 proc-macro

## 关闭 DOC-302a 已完成 — 类型已迁移到 proc-macro

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#30

DOC-302a zx_document_core 类型迁移到 proc-macro #30

目标

FFI DTO 边界规则（重要）

需要标注的类型

Enum（#[derive(uniffi::Enum)]）

Record（#[derive(uniffi::Record)]）

Error（#[derive(uniffi::Error)]）

改动

依赖

验收

完成 (2026-06-03)

改动

遵守 FFI DTO 边界规则

验证

关闭

Enum（`#[derive(uniffi::Enum)]`）

Record（`#[derive(uniffi::Record)]`）

Error（`#[derive(uniffi::Error)]`）