# cdrop iOS 真机分发手册

把 cdrop 装到你自己的 iPhone（开发签名，1 年 profile）。代码侧全部就绪并经模拟器验证；真机只差**账号 + 门户 + 签名**这一层。本手册走**手动签名 + 全 CLI**路线——门户你手动建（一次），构建装机一条命令，**全程不碰 Xcode GUI**。

## 包名与标识（门户里要用的）

| 项 | 值 |
|---|---|
| 主 app Bundle ID | `net.commilitia.Commilitia-Drop` |
| Share Extension | `net.commilitia.Commilitia-Drop.share` |
| 控件扩展 | `net.commilitia.Commilitia-Drop.widgets` |
| App Group | `group.net.commilitia.cdrop`（与包名相互独立，刻意不同名） |
| APNs topic（服务端 `CDROP_APNS_TOPIC`） | `net.commilitia.Commilitia-Drop` |

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

---

## A. 门户操作（developer.apple.com/account，一次性）

> 入口：登录后左侧 **Certificates, Identifiers & Profiles**（证书 / 标识符 / 描述文件总枢纽）——A1–A5 都在这里面；A6 在 **Keys**；Team ID 在 **Membership details**（10 位，记下）。

1. **证书**（Apple Development）：本机「钥匙串访问」可能已有（「我的证书」分类里看）。没有就：钥匙串访问菜单 → 证书助理 → 从证书颁发机构请求证书 → 存到磁盘 → 门户 **Certificates** → ＋ → Apple Development → 传 CSR → 下载 `.cer` 双击安装。
2. **App IDs ×3**（**Identifiers** → ＋ → App IDs → App，Bundle ID 选 **Explicit**）：
   - `net.commilitia.Commilitia-Drop` — 勾 **App Groups** + **Push Notifications**
   - `net.commilitia.Commilitia-Drop.share` — 勾 **App Groups**
   - `net.commilitia.Commilitia-Drop.widgets` — 勾 **App Groups**
3. **App Group**：**Identifiers** 页类型筛选切到 **App Groups** → ＋ → `group.net.commilitia.cdrop`。再回上面 3 个 App ID 各自的 App Groups 能力里 **Edit/Configure** 关联它（三个都要）。
4. **设备**：**Devices** → ＋ → 填 UDID（插上手机后 `just ios-devices` 读）。
5. **描述文件 ×3**（**Profiles** → ＋ → **iOS App Development**，非 Distribution）：每个选对应 App ID + 证书 + 设备，命名清楚（建议 `CDrop Dev` / `CDrop Share Dev` / `CDrop Widgets Dev`）→ 下载 → 双击安装。
6. **APNs Auth Key**（**Keys** → ＋ → 勾 Apple Push Notifications service）：下载 `AuthKey_XXXXX.p8`（仅一次），记 **Key ID** + **Issuer ID**（服务端发推送用，见 D）。这把 `.p8` 与 A1 的证书是两码事。

> 常见坑：Bundle ID 选 **Explicit** 不是 Wildcard；App Group 务必 3 个 App ID 都关联；Profile 选 **Development** 不要 Distribution。

---

## B. 本地签名配置（gitignore，填一次）

在 `ios/CDrop/Local.xcconfig` 写入（此文件已 gitignore，公开仓库不留你的账号标识）：

```
CDROP_TEAM_ID = ABCDE12345
CDROP_PROFILE_APP = CDrop Dev
CDROP_PROFILE_SHARE = CDrop Share Dev
CDROP_PROFILE_WIDGETS = CDrop Widgets Dev
```

- `CDROP_TEAM_ID`＝A0 的 Team ID；三个 `CDROP_PROFILE_*`＝A5 你起的 profile 名（**名字**，不是文件路径）。
- 机制：`Signing.xcconfig`（已提交）仅对 **device SDK（iphoneos）** 套用手动签名 + 这些值；**模拟器**仍走 `project.yml` 的 ad-hoc（`CODE_SIGN_IDENTITY = "-"`），故缺 `Local.xcconfig` 也不影响模拟器构建。

---

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

```sh
just ios-devices                 # 手机插 USB，读 UDID（填进门户 A4 + 下行）
just ios-device <你的设备UDID>   # 真机构建（手动签名）+ devicectl 装机
```

- `just ios-device` ＝ `xcodegen generate` → `xcodebuild`（device，手动签名走 `Local.xcconfig`）→ `xcrun devicectl device install app`。无 Xcode GUI。
- 首次装机后，iPhone 上首启该开发者 app 即可直接跑（付费 ADP 开发证书，无需手动「信任开发者」）。

---

## D. 服务端前置

1. **引擎可达**：真机上引擎 WebView 加载 `https://drop.commilitia.net/engine.html`——**该文件随 cdrop 二进制部署到 prod**（`//go:embed` 进 binary，`just docker-image` 含最新 `dist`）。手机要用，prod 须是含本轮改动的最新部署。
2. **APNs 真发**：把 A6 的 `.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` 指向可达引擎。

---

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

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

- [ ] 液态玻璃真机渲染（陀螺仪高光 / 动效）。
- [ ] 扫码登录：本机显码 → 已登录 cdrop 扫码批准 → 进主界面（强制 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 推送**：离线设备收「收到文件」通知（需 D2 的 `.p8`）。
- [ ] **Share Extension**：别的 app 分享 → 选 Commilitia Drop → 唤起主 app 选设备发送。
- [ ] **控制中心剪贴板两控件**：控制中心加「上传 / 拉取剪贴板」控件 → 锁屏 / 解锁态点按 → 云剪贴板读写。