# Rust FFI 绑定更新流程

## 1. 概述

iOS 通过 uniffi 生成的 Swift 绑定调用 Rust Document Runtime（zx_document_core）。

更新流程：修改 Rust 代码 → 重新生成 bindings → Xcode 重新编译

---

## 2. 文件结构

```
zhixi-document-runtime/
├── crates/
│   ├── zx_document_core/       # 核心 Rust 库
│   │   ├── src/
│   │   │   ├── document.rs     # DocumentInfo + build_document_info
│   │   │   ├── material_type.rs
│   │   │   ├── markdown.rs     # Markdown 解析
│   │   │   ├── pdf.rs          # PDF 元数据/文本提取
│   │   │   ├── epub.rs         # EPUB 元数据/章节/文本
│   │   │   ├── search.rs       # 全文搜索
│   │   │   ├── anchors.rs      # NoteAnchor
│   │   │   ├── events_v2.rs    # V2 事件 buffer
│   │   │   ├── session_v2.rs   # V2 Session 管理
│   │   │   └── image_meta.rs   # 图片元数据
│   │   └── Cargo.toml
│   └── zx_document_ffi/        # FFI 绑定层
│       ├── src/
│       │   └── lib.rs          # uniffi 导出定义
│       ├── src/zx_document.udl # UDL 接口定义
│       └── Cargo.toml
└── Cargo.toml                  # Workspace root

ios-projects/
└── AIStudyApp/
    └── AIStudyApp/
        └── Core/
            ├── ZxDocumentRuntime.xcframework/  # 预编译 Rust 库
            └── zx_document.swift               # uniffi 生成的 Swift 绑定
```

---

## 3. 更新流程

### 3.1 修改 Rust 接口

1. 在 `zx_document_core/src/` 中修改或新增函数/类型
2. 在 `zx_document_ffi/src/lib.rs` 中导出新接口
3. 如需新增 UDL 定义，更新 `zx_document.udl`

### 3.2 重新生成 Swift 绑定

```bash
cd zhixi-document-runtime
cargo build --release -p zx_document_ffi

# 生成 Swift 绑定
uniffi-bindgen generate \
  crates/zx_document_ffi/src/zx_document.udl \
  --language swift \
  --out-dir ../ios-projects/AIStudyApp/AIStudyApp/Core/
```

### 3.3 构建 xcframework

```bash
# iOS arm64
cargo build --release -p zx_document_ffi --target aarch64-apple-ios

# iOS Simulator arm64 (Apple Silicon Mac)
cargo build --release -p zx_document_ffi --target aarch64-apple-ios-sim

# iOS Simulator x86_64 (Intel Mac)
cargo build --release -p zx_document_ffi --target x86_64-apple-ios

# 打包 xcframework
xcodebuild -create-xcframework \
  -library target/aarch64-apple-ios/release/libzx_document_ffi.a \
  -library target/aarch64-apple-ios-sim/release/libzx_document_ffi.a \
  -output ZxDocumentRuntime.xcframework
```

### 3.4 更新 Xcode 项目

1. 替换 `AIStudyApp/Core/ZxDocumentRuntime.xcframework`
2. 替换 `AIStudyApp/Core/zx_document.swift`
3. 在 Xcode 中 Clean Build Folder（Cmd+Shift+K）
4. 重新编译

---

## 4. 新增接口 checklist

- [ ] Rust 类型实现 `Serialize + Deserialize + uniffi::Record/Enum`
- [ ] FFI 层 `pub extern "C"` 导出函数
- [ ] UDL 文件声明接口
- [ ] Swift 绑定重新生成
- [ ] xcframework 重新编译（至少 arm64 + sim）
- [ ] iOS 编译通过
- [ ] 单元测试通过（`cargo test -p zx_document_core`）

---

## 5. 常见问题

### 5.1 xcframework 架构缺失

**症状**：`While building for macOS, no library for this platform was found`

**原因**：xcframework 仅包含 iOS 架构，Mac Catalyst 构建试图链入

**处理**：确保 Scheme 仅勾选 iOS target，或为 Mac Catalyst 添加 `aarch64-apple-ios-macabi` 目标

### 5.2 uniffi 版本不匹配

**症状**：`uniffi::ffi::foreigncallbacks` not found

**处理**：确保 `Cargo.toml` 中 uniffi 版本与 `uniffi-bindgen` CLI 版本一致

### 5.3 Swift 类型不匹配

**症状**：`Cannot convert value of type 'X' to expected argument type 'Y'`

**处理**：重新生成 `zx_document.swift`（uniffi-bindgen 输出），确保与 xcframework 版本对应

---

## 6. 版本管理

| Rust crate | 当前版本 | FFI 接口数 |
|------------|:--:|:--:|
| zx_document_core | 0.1.0 | — |
| zx_document_ffi | 0.1.0 | 12 |
| uniffi | 0.28 | — |

---

## 7. 相关文档

- [V2 事件 Pipeline 架构](./v2-event-pipeline.md)
- [阅读信息采集接入文档](./reading-info-integration.md)