iOS CI/CD / Build & Test (push) Has been cancelled

Details

docs: add iOS ops docs + CI config (IOS-INFO-028~031)

- rust-ffi-update.md: FFI binding update workflow
- app-store-submission-checklist.md: 9-section App Store review
- ios-ci.yml: GitHub Actions build + test on macos-15
- firebase-crashlytics-integration.md: Crashlytics setup guide

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-06-18 14:25:15 +08:00

4.2 KiB

Raw Blame History

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 接口

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

3.2 重新生成 Swift 绑定

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

# 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 项目

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

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	—

4.2 KiB Raw Blame History Unescape Escape