# Chat API 插件 SPM 迁移说明

## 迁移概述

`chat_api` 插件已经完成了 Swift Package Manager (SPM) 支持的迁移，现在可以自动处理 OpenAI Swift 包的依赖。

## 主要变更

### 1. 目录结构调整

```
ios/
├── chat_api.podspec          # 保留，支持双轨模式
├── Classes/                   # 已清空（源码已迁移）
└── chat_api/                  # 新增 SPM 结构
    ├── Package.swift          # SPM 包定义
    └── Sources/
        └── chat_api/          # 源码新位置
            ├── ChatApiPlugin.swift
            └── ChatService.swift
```

### 2. Package.swift 配置

- 声明了 MacPaw OpenAI 包依赖
- 自动管理版本（0.4.0+）
- 设置最低 iOS 版本为 13.0

### 3. podspec 更新

- 更新了 `source_files` 路径指向新的 SPM 结构
- 添加了友好的迁移提示脚本

### 4. pubspec.yaml 更新

- 添加了 `dartPluginClass` 声明，明确支持 SPM

## 使用方式对比

### 旧方式（手动集成）

1. 运行 `pod install`
2. 打开 Xcode
3. 手动添加 OpenAI Swift Package
4. 配置依赖关系

### 新方式（自动集成）

1. 启用 SPM：`flutter config --enable-swift-package-manager`
2. 运行 `flutter run`
3. 完成！Flutter 自动处理所有依赖

## 兼容性

- **Flutter 3.24+**：完整 SPM 支持，推荐使用
- **Flutter < 3.24**：自动降级到 CocoaPods 模式
- **混合项目**：如果项目中有其他插件未迁移到 SPM，Flutter 会智能选择合适的集成方式

## 验证集成

### SPM 项目

```bash
# 在 example 目录下
flutter clean
flutter pub get
flutter run --verbose
```

成功标志：
- 看到 "Adding Swift Package Manager integration..." 消息
- Xcode 中 Package Dependencies 自动出现 OpenAI 包
- 构建成功，无需手动干预

### CocoaPods 项目

如果项目仍使用 CocoaPods，会看到：
- podspec 中的迁移提示
- 需要按照 `IOS_INTEGRATION_LEGACY.md` 手动添加依赖

## 故障排除

1. **清理缓存**
   ```bash
   flutter clean
   rm -rf ios/Pods ios/Podfile.lock
   rm -rf ~/Library/Developer/Xcode/DerivedData
   ```

2. **重置 SPM 缓存**
   - Xcode: File > Packages > Reset Package Caches

3. **确认 SPM 已启用**
   ```bash
   flutter config
   # 应该看到 enable-swift-package-manager: true
   ```

## 开发者注意事项

1. **源码位置**：所有 Swift 代码现在位于 `ios/chat_api/Sources/chat_api/`
2. **双轨支持**：保持 podspec 和 Package.swift 同时更新
3. **版本管理**：OpenAI 包版本在 Package.swift 中管理

## 未来计划

- 当 Flutter 生态系统完全迁移到 SPM 后，可以考虑移除 CocoaPods 支持
- 持续跟踪 MacPaw OpenAI 库的更新