# cdrop iOS 真机自测手册

账号到位即可照做。模拟器构建不需签名，已全程 compile + 跑通；**真机**要付费 ADP + 签名 + 实体 iPhone，下面是 turnkey 步骤 + 只能真机验的清单。

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

## 出工程 + 签名
1. `cd ios/CDrop && xcodegen generate`（从 `project.yml` 生成 `CDrop.xcodeproj`）。
2. Xcode 打开 `CDrop.xcodeproj` → 选 `CDrop` target → Signing & Capabilities：
   - **Team** 选你的 ADP 团队；**Bundle Identifier** 用你账号下可注册的（默认 `net.commilitia.cdrop`，前缀按你的改）。
   - 让 Xcode 自动管理签名（Automatically manage signing）。
3. 连 iPhone、信任、选作运行目标 → Run。
   - `project.yml` 里 `CODE_SIGNING_ALLOWED: NO` 是给模拟器的；Xcode 真机自动签名会覆盖它，无需手改。

## 引擎可达性（让传输真能连）
- 真机上引擎 WebView 默认加载 `https://drop.commilitia.net/engine.html`——**该文件要先随 web 部署到 prod**（`vite build` 已产出 `dist/engine.html`，随正常 web 发布上线）。
- 或本机联调：设环境变量 `CDROP_ENGINE_URL` 指向可达引擎、`CDROP_API_BASE` 指向后端。

## 后续功能要补的 capability（按需，各自要在 Developer Portal 配 App ID）
- **App Groups**（`group.net.commilitia.cdrop`）：Share Extension / 控制中心控件与主 app 共享数据。
- **Push Notifications** + APNs `.p8`：传输事件推送。
- **Keychain Sharing**：跨 app / 扩展共享登录态。
- **Associated Domains**：若改用 OIDC Universal Link 回调（扫码登录则不需要）。

## 只能真机验的清单
- [ ] 液态玻璃在真机渲染（含陀螺仪高光 / 动效）。
- [ ] 扫码登录：本机显码 → 用已登录 cdrop 扫码批准 → app 进入主界面。
- [ ] **本地网络权限**：首次同内网传输弹 `NSLocalNetworkUsageDescription` 提示；授予后 ICE 收到 host 候选（R-iOS-6）；拒绝则回退中继仍可传。
- [ ] 发送：选文件 → 选设备 → 对端收到。
- [ ] 接收：对端发来 → 落到 Files（沙盒 Documents）。
- [ ] 后台：传输中切后台 → `BGContinuedProcessingTask` 续传行为（R-iOS-1 / R-iOS-3）。
- [ ] 大文件：发送侧内存（当前整文件入内存，大文件需转分块流式 = R-iOS-4）。

## 已知 TODO（真机阶段一并收）
- 会话 Keychain 持久化 + 自动续期（当前会话在内存、重启需重扫；续期端点 `/api/auth/refresh` 已可用，靠 cookie）。
- 发送侧大文件分块流式（R-iOS-4）。
- 剪贴板 App Intent + 控制中心控件（决策 C）、Share Extension——需上面的 capability + 账号才能跑。