# Commilitia Drop iPhone／iPad 真机分发手册

把 Commilitia Drop 覆盖安装到已登记的 iPhone 与 iPad（开发签名）。本手册走
**既有 Apple Development 证书 + ASC API Key provisioning + 全 CLI** 路线：签名身份固定为
钥匙串内既有证书的 SHA-1；ASC Key 只用于登记设备、更新 App ID／App Group／Push 能力和 profile。
构建装机一条命令，**全程不碰 Xcode GUI、不新建开发证书、不修改私钥 ACL**。

## 包名与标识

| 项 | 值 |
|---|---|
| 主 app Bundle ID | `net.commilitia.Commilitia-Drop` |
| Share Extension | `net.commilitia.Commilitia-Drop.share` |
| 控件扩展 | `net.commilitia.Commilitia-Drop.widgets` |
| App Group | `group.net.commilitia.Commilitia-Drop` |
| APNs topic（服务端 `CDROP_APNS_TOPIC`） | `net.commilitia.Commilitia-Drop` |

## 前置
- 付费 Apple Developer Program（$99/年）。
- 一台 iPhone（iOS 26）+ Mac（Xcode 26 命令行工具）。
- 一个已登录的 Commilitia Drop（网页 / 桌面）——用来扫码批准本机登录。

---

## A. 既有签名身份 + ASC API Key + .env

先用 CLI 列出当前钥匙串中可用的代码签名身份：

```sh
security find-identity -v -p codesigning
```

找到必须复用的 `Apple Development` 证书，记录行首 40 位 SHA-1。若身份不存在或私钥不可用，停止
构建并解锁当前登录钥匙串；不要让自动签名生成替代证书。

`-allowProvisioningUpdates` 凭 App Store Connect API Key 自动登记设备、建／改 App ID（含 App
Groups + Push 能力）、更新 App Group 与 profile，免去手动 profile 的设备选择问题。签名证书由
`CDROP_APPLE_DEVELOPMENT_IDENTITY` 固定，不由 provisioning 自行选择。

**生成 API Key**：appstoreconnect.apple.com → **用户和访问** → **集成** → **App Store Connect API** → **团队密钥** → 「＋」→ 角色 **Admin**（要能管设备 / profile / 标识符）→ 命名 → 生成 → 下载 `AuthKey_XXXXX.p8`（**仅一次**）。记下三样：

- **Key ID**（密钥行里那串，10 位）
- **Issuer ID**（密钥页顶部，UUID 形）
- **Team ID**（账号 **Membership** 里，10 位）

**配 `.env`**（仓库根目录，已 gitignore，公开仓库不留账号凭据）：

```
CDROP_TEAM_ID=ABCDE12345
CDROP_ASC_KEY_PATH=/绝对路径/AuthKey_XXXXX.p8
CDROP_ASC_KEY_ID=XXXXXXXXXX
CDROP_ASC_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CDROP_APPLE_DEVELOPMENT_IDENTITY=<既有证书的40位SHA-1>
```

`.p8` 放仓库外即可，`CDROP_ASC_KEY_PATH` 指它绝对路径（落本目录则被 `*.p8` 忽略）。

> 你若已在门户手动建过 App ID / App Group，自动 provisioning 会复用或更新。**「手动建
> profile 时设备列表只剩 Mac」**＝那台 iPhone 在 **Devices** 里被登记成了 macOS 平台（登记
> 表单 Platform 默认 macOS）；自动 provisioning 按连接的真机登记，绕过此坑。

**顺手：APNs Auth Key**（发推送用，与上面 ASC Key 是两码事）：门户 **Keys** → ＋ → 勾 **Apple Push Notifications service** → 下载 `AuthKey_YYYYY.p8`（仅一次），记 Key ID + Issuer ID（服务端配，见 C）。

---

## B. 构建装机（全 CLI）

```sh
just ios-devices                 # 手机插 USB，读 UDID
just ios-device <你的设备UDID>   # 自动 provisioning 构建 + devicectl 装机
```

- `just ios-device` 先确认 `.env` 指定的既有证书仍在钥匙串，再执行 `xcodegen generate` →
  `xcodebuild -allowProvisioningUpdates`（固定该 SHA-1 签名，ASC Key 更新设备与 profile）→
  `xcrun devicectl device install app`。无 Xcode GUI。
- 首次装机后，iPhone 上首启该开发者 app 即可直接跑（付费 ADP 开发证书，无需手动「信任开发者」）。

若出现 `errSecInternalComponent`，优先在当前用户的普通 Terminal 解锁登录钥匙串，然后重试原证书。
不要创建新证书、修改钥匙串 ACL，或改用 Xcode GUI。

---

## C. 服务端前置

1. **引擎可达**：真机上引擎 WebView 加载 `https://drop.commilitia.net/engine.html`——该文件随 Commilitia Drop 服务端二进制部署到 prod（`//go:embed` 进 binary，`just docker-image` 含最新 `dist`）。手机要用，prod 须是含本轮改动的最新部署。
2. **APNs 真发**：把 A 里那把 **APNs Auth Key** `.p8` 放到服务器，给后端容器配 `CDROP_APNS_KEY_PATH` / `CDROP_APNS_KEY_ID` / `CDROP_APNS_TEAM_ID` / `CDROP_APNS_TOPIC=net.commilitia.Commilitia-Drop` / `CDROP_APNS_ENV`（Xcode 开发构建的 device token 属 **sandbox**，故联调填 `sandbox`）。缺配置则推送惰性关闭，其余功能照常。
3. 本机联调可选：环境变量 `CDROP_ENGINE_URL` 指向可达引擎。

---

## D. 只能真机验的清单

代码已实现，下列是真机才能验的点：

- [ ] 液态玻璃真机渲染（陀螺仪高光 / 动效）。
- [ ] 扫码登录：本机显码 → 已登录 Commilitia Drop 扫码批准 → 进主界面（强制 full/persist）。
- [ ] **本地网络权限 + 同内网直连**（R-iOS-6）：首次同内网传输弹 `NSLocalNetworkUsageDescription`；授予后 ICE 收 host 候选、走真直连；拒绝则回退中继仍可传。
- [ ] 发送 / 接收：选文件 → 选设备 → 对端收到；对端发来落 Files（Documents）。
- [ ] **大文件流式发送**（R-iOS-4 已实现）：发大文件，WebView 内存应有界（按 Range 块拉取，不整文件入内存）。
- [ ] **后台续传**（R-iOS-1 / R-iOS-3）：传输中切后台 → `BGContinuedProcessingTask` 系统进度 UI；验 WKWebView JS 是否随之保活（不保活则退化为回前台续传，可接受）。
- [ ] **APNs 推送**：离线设备收「收到文件」通知（需 C2 的 `.p8`）。
- [ ] **Share Extension**：别的 app 分享 → 选 Commilitia Drop → 唤起主 app 选设备发送。
- [ ] **控制中心剪贴板两控件**：控制中心加「上传 / 拉取剪贴板」控件 → 锁屏 / 解锁态点按 → 云剪贴板读写。