docs: add cross-platform release guide (DOC-FULL-033)

- iOS .xcframework: 3 arch build + packaging steps
- Android .aar: 4 arch targets + Kotlin binding (planned)
- UniFFI multi-lang generation: swift/kotlin/python/ruby
- Version management + release checklist
- CI automation: tag v* triggers build + package

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

docs/cross-platform-release.md

@@ -0,0 +1,195 @@
+# 跨平台发布流程
+
+## 1. 概述
+
+Document Runtime 通过 UniFFI 生成多语言绑定，支持跨平台分发。
+
+| 平台 | 产物 | 绑定语言 | 状态 |
+|------|------|----------|:--:|
+| iOS | `.xcframework` | Swift（uniffi） | ✅ 生产 |
+| macOS (Catalyst) | `.xcframework` | Swift（uniffi） | 🔄 计划中 |
+| Android | `.aar` | Kotlin（uniffi） | 🔄 计划中 |
+
+---
+
+## 2. iOS .xcframework
+
+### 2.1 目标架构
+
+| 架构 | Rust Target | 用途 |
+|------|-------------|------|
+| `ios-arm64` | `aarch64-apple-ios` | iPhone 真机 |
+| `ios-arm64-sim` | `aarch64-apple-ios-sim` | Apple Silicon Mac 模拟器 |
+| `ios-x86_64-sim` | `x86_64-apple-ios` | Intel Mac 模拟器 |
+
+### 2.2 构建步骤
+
+```bash
+cd zhixi-document-runtime
+
+# 1. 安装 targets
+rustup target add aarch64-apple-ios \
+                 aarch64-apple-ios-sim \
+                 x86_64-apple-ios
+
+# 2. 构建各架构
+cargo build --release -p zx_document_ffi --target aarch64-apple-ios
+cargo build --release -p zx_document_ffi --target aarch64-apple-ios-sim
+cargo build --release -p zx_document_ffi --target x86_64-apple-ios
+
+# 3. 打包 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 \
+  -library target/x86_64-apple-ios/release/libzx_document_ffi.a \
+  -output ZxDocumentRuntime.xcframework
+
+# 4. 校验
+xcodebuild -check-xcframework ZxDocumentRuntime.xcframework
+# Expected: ios-arm64, ios-arm64-sim, ios-x86_64-sim ✅
+
+# 5. 生成 Swift 绑定
+uniffi-bindgen generate \
+  crates/zx_document_ffi/src/zx_document.udl \
+  --language swift \
+  --out-dir ./generated/swift/
+
+# 6. 打包发布资产
+zip -r ZxDocumentRuntime.xcframework.zip ZxDocumentRuntime.xcframework/
+cp generated/swift/zx_document.swift ./release-assets/
+```
+
+### 2.3 集成到 Xcode
+
+1. 将 `ZxDocumentRuntime.xcframework` 拖入 Xcode → Embed & Sign
+2. 将 `zx_document.swift` 添加到项目
+3. Build Settings → `FRAMEWORK_SEARCH_PATHS` 包含 xcframework 路径
+
+---
+
+## 3. Android .aar（计划中）
+
+### 3.1 目标架构
+
+| 架构 | Rust Target |
+|------|-------------|
+| `arm64-v8a` | `aarch64-linux-android` |
+| `armeabi-v7a` | `armv7-linux-androideabi` |
+| `x86_64` | `x86_64-linux-android` |
+| `x86` | `i686-linux-android` |
+
+### 3.2 构建步骤（草案）
+
+```bash
+# 1. 安装 NDK + targets
+rustup target add aarch64-linux-android \
+                 armv7-linux-androideabi \
+                 x86_64-linux-android
+
+# 2. 构建各架构
+cargo build --release -p zx_document_ffi --target aarch64-linux-android
+# ... (repeat for each target)
+
+# 3. 生成 Kotlin 绑定
+uniffi-bindgen generate \
+  crates/zx_document_ffi/src/zx_document.udl \
+  --language kotlin \
+  --out-dir ./generated/kotlin/
+
+# 4. 打包 .aar
+# 标准 Android 库打包流程：
+# - jniLibs/<abi>/libzx_document_ffi.so
+# - generated/kotlin/**/*.kt
+# - AndroidManifest.xml
+# 使用 gradle / android-maven-plugin 打包为 .aar
+```
+
+### 3.3 注意事项
+
+- Android 需要 JNI 兼容的符号导出（`#[no_mangle] pub extern "C"`）
+- NDK 版本 ≥ r26
+- `ANDROID_NDK_HOME` 环境变量需设置
+- 需要 `libunwind` 链接（`-lunwind`）
+
+---
+
+## 4. UniFFI 多语言绑定生成
+
+### 4.1 一次生成所有语言
+
+```bash
+for lang in swift kotlin python ruby; do
+  uniffi-bindgen generate \
+    crates/zx_document_ffi/src/zx_document.udl \
+    --language "$lang" \
+    --out-dir "generated/$lang/"
+done
+```
+
+### 4.2 生成的产物
+
+```
+generated/
+├── swift/
+│   └── zx_document.swift        # Swift 绑定
+├── kotlin/
+│   └── zx_document.kt           # Kotlin 绑定（Android 用）
+├── python/
+│   └── zx_document.py           # Python 绑定（CLI 工具用）
+└── ruby/
+    └── zx_document.rb           # Ruby 绑定
+```
+
+---
+
+## 5. 版本管理
+
+### 5.1 版本号同步
+
+| 文件 | 字段 | 示例 |
+|------|------|------|
+| `Cargo.toml` (workspace) | `workspace.package.version` | `0.1.0` |
+| `ZxDocumentRuntime.xcframework/Info.plist` | `CFBundleVersion` | `0.1.0` |
+| Git tag | — | `v0.1.0` |
+| `zx_document.swift` | 注释头部 | `// UniFFI 0.28, zx_document v0.1.0` |
+
+### 5.2 发布 Checklist
+
+```
+tag vX.Y.Z
+  ├── [ ] Cargo.toml version bumped
+  ├── [ ] cargo test --workspace ✅
+  ├── [ ] CI release job passes
+  ├── [ ] xcframework.zip uploaded to GitHub Release
+  ├── [ ] zx_document.swift uploaded to GitHub Release
+  ├── [ ] CHANGELOG.md updated
+  └── [ ] iOS app built with new xcframework ✅
+```
+
+---
+
+## 6. CI 自动化
+
+发布流程已集成到 `.github/workflows/ci.yml`：
+
+| Step | 触发 | 产物 |
+|------|------|------|
+| Build (matrix) | tag `v*` | `libzx_document_ffi.a` per target |
+| Package xcframework | tag `v*` | `ZxDocumentRuntime.xcframework.zip` |
+| GitHub Release | tag `v*` | 自动 release notes + 上传 zip |
+
+```bash
+# 手动触发发布
+git tag v0.1.0
+git push origin v0.1.0
+# CI 自动执行 release + package-xcframework jobs
+```
+
+---
+
+## 7. 相关文档
+
+- [UniFFI UDL 编写规范](./uniffi-udl-spec.md)
+- [C-ABI out-pointer 模式](./c-abi-out-pointer-pattern.md)
+- [iOS FFI 调用指南](./ios-ffi-integration-guide.md)
+- [CI/CD Pipeline](../.github/workflows/ci.yml)