# 崩溃监控集成（Firebase Crashlytics）

## 1. 概述

Firebase Crashlytics 用于收集 iOS 应用崩溃日志，支持 Swift 层和 Rust FFI 层的崩溃追踪。

## 2. 集成步骤

### 2.1 添加依赖

```swift
// Package.swift 或 Xcode SPM
.package(url: "https://github.com/firebase/firebase-ios-sdk", from: "11.0.0")

// Target dependencies
.product(name: "FirebaseCrashlytics", package: "firebase-ios-sdk"),
```

### 2.2 初始化

```swift
// AppDelegate.swift 或 AIStudyApp.swift
import Firebase

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    FirebaseApp.configure()
    return true
}
```

### 2.3 GoogleService-Info.plist

从 Firebase Console 下载 `GoogleService-Info.plist`，放入 Xcode 项目根目录（不要加入 git，加入 .gitignore）。

```bash
# .gitignore
GoogleService-Info.plist
```

### 2.4 dSYM 上传

```bash
# Build Phase: Run Script
"${BUILD_DIR%/Build/Products}/${CONFIGURATION}-${PLATFORM_NAME}/AIStudyApp.app/dSYMs"
${PODS_ROOT}/FirebaseCrashlytics/upload-symbols \
  -gsp "${PROJECT_DIR}/GoogleService-Info.plist" \
  -p ios "${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}"
```

---

## 3. 自定义日志

### 3.1 Swift 层

```swift
import FirebaseCrashlytics

// 记录关键路径
Crashlytics.crashlytics().log("Reading session opened: \(materialId)")

// 设置用户标识
Crashlytics.crashlytics().setUserID(userId)

// 自定义 key
Crashlytics.crashlytics().setCustomValue(materialId, forKey: "last_material_id")
Crashlytics.crashlytics().setCustomValue(sessionState, forKey: "session_state")
```

### 3.2 Rust FFI 层

Rust panic 通过 `std::panic::catch_unwind` 捕获后，通过 FFI 回调通知 Swift：

```swift
// zx_document.swift (uniffi generated)
// Rust panics are caught and returned as errors;
// Swift layer logs them to Crashlytics
do {
    try documentRuntime.openMaterial(materialId)
} catch {
    Crashlytics.crashlytics().record(error: error)
}
```

---

## 4. 关键监控点

| 位置 | 监控内容 |
|------|----------|
| `AppDelegate.didFinishLaunching` | 启动崩溃 |
| `MaterialReaderView.onAppear` | 阅读器打开 |
| `UploadScheduler.flush()` | 批量上传 |
| `RuntimeRecoveryService.recover()` | 会话恢复 |
| `FFI 调用点` | Rust panic |
| `sceneDidEnterBackground` | 后台切换 |

---

## 5. 符号化

### 5.1 Swift 符号

Xcode Archive 自动包含 dSYM。Crashlytics 通过 upload-symbols 脚本自动符号化。

### 5.2 Rust 符号

Rust xcframework 的 dSYM 需手动生成：

```bash
# 构建带调试符号的 Rust 库
cargo build --release -p zx_document_ffi --target aarch64-apple-ios

# 提取 dSYM
dsymutil target/aarch64-apple-ios/release/libzx_document_ffi.a \
  -o ZxDocumentRuntime.dSYM

# 上传到 Crashlytics
${PODS_ROOT}/FirebaseCrashlytics/upload-symbols \
  -gsp GoogleService-Info.plist \
  -p ios ZxDocumentRuntime.dSYM
```

---

## 6. 告警阈值

| 指标 | 阈值 | 响应 |
|------|:--:|------|
| Crash-free rate | < 99% | 紧急修复 |
| Crash-free rate | < 99.5% | P1 调查 |
| 新 crash 类型 | ≥ 1 | 24h 内分类 |
| 回归 crash | ≥ 1 | 立即回滚 |

---

## 7. 隐私合规

- Crashlytics 不采集 PII（个人身份信息）
- 用户 ID 使用匿名化标识符（UUID），不关联登录邮箱
- 崩溃日志保留 90 天
- 在隐私政策中声明使用 Firebase Crashlytics

---

## 8. 相关文档

- [App Store 提审 Checklist](./app-store-submission-checklist.md)
- [iOS CI/CD](./ios-ci.yml) (.github/workflows/)