# iOS 分发（TestFlight）— 一次性配置

iOS 不能像安卓那样把安装包挂网页直接侧载。本项目通过 **TestFlight** 分发：CI 自动构建签名 IPA 并上传 App Store Connect，用户装 TestFlight app 后用公开链接安装。

所有凭证通过 Forgejo Secrets 注入，**不入库**。配置完成前 `build-ios` job 会自动跳过（exit 0），不阻塞发版。

## 前置：Apple Developer 账号

- 注册 Apple Developer Program（$99/年）。
- 在 [App Store Connect](https://appstoreconnect.apple.com) 新建 App，Bundle ID = `com.yanmei.jiu`（与工程一致）。

## 1. 发行证书（Apple Distribution）

在钥匙串/开发者后台创建 **Apple Distribution** 证书，导出为 `.p12`（设一个导出密码）：

```bash
# 已在 Xcode/钥匙串里有 Distribution 证书时，从「钥匙串访问」导出 .p12
base64 -i dist.p12 | pbcopy        # → ANDROID 同理，复制到剪贴板
```

## 2. Provisioning Profile（App Store 类型）

开发者后台 → Profiles → 新建 **App Store** 类型，关联 App ID `com.yanmei.jiu` 与上面的发行证书，下载 `.mobileprovision`：

```bash
base64 -i jiu_appstore.mobileprovision | pbcopy
```

## 3. App Store Connect API Key

App Store Connect → Users and Access → Integrations → App Store Connect API → 新建密钥（角色 App Manager 即可），下载 `AuthKey_XXXX.p8`，记下 **Key ID** 与 **Issuer ID**：

```bash
base64 -i AuthKey_XXXX.p8 | pbcopy
```

## 4. 在 Forgejo 仓库配置 Secrets

仓库 → Settings → Actions → Secrets，新增 7 项：

| Secret 名 | 值 |
|-----------|-----|
| `IOS_DIST_CERT_P12_BASE64` | 第 1 步 .p12 的 base64 |
| `IOS_DIST_CERT_PASSWORD` | .p12 导出密码 |
| `IOS_PROVISIONING_PROFILE_BASE64` | 第 2 步 .mobileprovision 的 base64 |
| `IOS_TEAM_ID` | Apple Developer Team ID（10 位） |
| `APPSTORE_API_KEY_ID` | 第 3 步 Key ID |
| `APPSTORE_API_ISSUER_ID` | 第 3 步 Issuer ID |
| `APPSTORE_API_KEY_P8_BASE64` | 第 3 步 .p8 的 base64 |

## 5. 配置 TestFlight 公开链接（下载页）

TestFlight 设置「公开链接」后，把链接填到 `backend/config/version.yaml`：

```yaml
download_urls:
  ios: "https://testflight.apple.com/join/XXXXXXXX"
```

填上后下载页的 iOS 卡片自动激活为「通过 TestFlight 安装」；客户端「立即更新」在 iOS 上也会跳到该链接。release.sh 不会覆盖此行（仅改 macos/windows/android）。

## 6. 验证

打 tag 触发流水线，确认 `build-ios` job：
- 日志非 `SKIP`，出现 `uploading to TestFlight`；
- App Store Connect → TestFlight 出现新 build（处理需几分钟）；
- 在 TestFlight 里设置测试组/公开链接后即可分发。

## 工作原理

- `scripts/ci/compile-ios.sh`：建临时 keychain 导入证书、安装 profile、生成 ExportOptions（manual / app-store）、`flutter build ipa`、`xcrun altool --upload-app` 上传；CFBundleVersion 由版本号推导单调递增；缺 secrets 时跳过。
- `.gitea/workflows/deploy-client.yml` 的 `build-ios` job：mac runner，串行于 build-android。
- 工程：`client/ios`（bundle id `com.yanmei.jiu`，应用名「岩美酒库」）。