Commilitia-Drop/ios/PLAN.md

cdrop iOS 客户端实施计划

原生 SwiftUI 界面（液态玻璃）· 离屏无头 WebView 复用传输引擎 · 控制中心剪贴板 + Share Extension + APNs 状态：架构已定（2026-06-24 修订），账号无关部分即刻可开工；真机 / 推送 / 扩展实测硬等 Apple Developer 账号。 关联：根 README.md、desktop/PLAN.md、internal/push、ios/PARITY.md（web↔iOS 同步检查单）。记忆 cdrop-state / cdrop-deploy-pointers。

---

0. 定位与关键决策（2026-06-24 修订）

定位变更：iOS 客户端不再是“web UI 装进 WebView”，而是“原生 SwiftUI 界面 + 复用的无头传输引擎”。起因——新增“服从 iOS 设计语言（液态玻璃）”硬要求，与“WebView 里跑 React UI”直接冲突：液态玻璃是 iOS 26 系统级材质，只有原生 SwiftUI 的 .glassEffect 拿得到，网页只能 CSS 仿。故 UI 转原生，但保留引擎复用。

决策 A（修订）：架构 = 原生 SwiftUI 壳 + 离屏无头 WebView 引擎

取代 2026-06-18 的“WebView 复用 React UI”决策。

• 所有可见 UI 用原生 SwiftUI（iOS 26 液态玻璃；旧版优雅回落，见 §7）。
• 文件传输的 P2P + relay + 会话 + 信令逻辑 = 现有 web/src 的 JS 引擎本体，跑在离屏（无 UI）WKWebView 里，原生经桥驱动。零重写、保住同内网 P2P、行为与 web 天然同构（上轮刚修的“按已交付字节算进度”“抽干再标完成”等自动一致）。
• 兜底方案 B：若真机上无头 WKWebView 跑 WebRTC DataChannel 不稳，退“全原生 + relay-only 重写 + 放弃 P2P”。该验证留到真机可测时优先做（R-iOS-3）。

桥方向与桌面相反（关键，易踩坑）：

• 桌面（Wails）：React UI 在 WebView 顶层，调 DOWN 到 Go 拿原生能力。
• iOS（arch A）：SwiftUI 原生在顶层，调 DOWN 到离屏 WebView 的 JS 引擎跑传输。
• 即 iOS 的 WebView 是“无头 worker”，不是“UI 容器”。需要一个独立的无头引擎入口（不加载 React、只装传输模块 + RPC 桥），而非复用 React app 再隐藏 UI。

决策 B（修订）：分发 = 非 App Store，但仍守苹果开发标准

• 必须付费 Apple Developer Program（ADP，$99/年）：cdrop 四项能力——APNs、App Groups、Keychain 共享、Associated Domains——免费 Personal Team 一律不支持（账号策略，非 OS 封锁），且免费证书 7 天过期。故“等账号”＝等付费 ADP。
• 分发走 Ad Hoc（最贴近桌面 Dropbox 旁加载的等价物）：100 台 / 年上限、设备 UDID 须预先登记、profile 年度更新。自用（自己几台设备）足够；比桌面“下载即用”多一道 UDID 登记摩擦——iOS 无更省的合规途径。
  • 备选 TestFlight：体验最好（无需 UDID、可达万级），但需经 Apple Beta 审核、build 90 天过期——与“不上架”初衷部分相悖，留作扩面再议。
  • Enterprise（ADEP $299/年）：无设备上限，但仅限“内部员工”，对外分发违反协议、证书可被吊销——不取。
• 不过审 ≠ 不守标准：仍遵守 HIG、液态玻璃规范、App Intents / WidgetKit 约定、隐私（权限说明 / just-in-time 请求）、entitlements 最小化。原 R-iOS-5（Guideline 4.2 过审风险）在 Ad Hoc 下作废；若走 TestFlight 则 Beta 审核仍在。

决策 C（新）：剪贴板 = 控制中心两控件，零推送

• 通道用持久的 /api/clipboard（REST、LWW、版本探针、作用域令牌可访问），不用 ephemeral 的 /api/message。
• iOS 18 控制中心控件（ControlWidget + App Intent）提供“上 / 下”两件：上 = 读 UIPasteboard → PUT /api/clipboard；下 = GET → 写 UIPasteboard。用户主动点、零推送（频繁剪贴板变动推送干扰极大）。
• 平台天花板：程序化读剪贴板弹一次系统横幅（写不弹）；后台无法监听复制。故“后台自动同步”降级为“一键发送 / 一键拉取”。
• 这条链纯原生 URLSession，不依赖无头 WebView——与文件传输引擎彻底解耦，互不拖累。

决策 D（新）：视图层分叉，先吃强约束、残余进检查单

接受 web（React）与 iOS（SwiftUI）视图层是两套实现（液态玻璃决定不可能像素一致）。一致性按两层管，详见 §5：

• 强约束同步（机制保证、漂移不可能）：① 传输行为靠 arch A 共享引擎；② i18n 文案单一源（iOS 读 web 那份 JSON）；③ 品牌资产 + 主色单一源；④ 后端 API 即共享契约。
• 检查单（机制管不住、人判定的残余）：元素 / 屏 / 功能存在性对等、非引擎驱动的新流程、后端字段变更提醒、允许分叉登记。
• 明确不做：设计令牌 codegen 管线（过度工程，且与液态玻璃系统材质 / 语义色 / SF Symbol 母语相冲）——间距 / 圆角 / 字阶归“允许分叉”，仅品牌主色 + logo 作共享源。

决策 E（新）：权限策略 = 持久权限首启显式询问 + 缺失则降级或阻塞提示

• 持久型权限（本地网络、相机）在首次启动的引导中显式询问：先用一屏说明用途、再触发系统弹窗——既满足“首启显式获取”，又不踩 HIG 的“无上下文裸弹窗”反模式。这类权限一次授予长期持久（iOS 18 有重装后状态不重置的已知 bug，需 UI 兜底）。
• 缺失 / 拒绝时按特性二选一：① 有兜底则降级——本地网络→回退中继并提示“仅中继、无法同内网直连”；通知→无后台推送但前台仍可用。② 无兜底则提示“无权限”并阻塞该特性——相机→扫码不可用，提示 + 跳系统设置；阻塞的是该特性、非整个 app。
• 不拿任一权限当整个 app 的门槛（HIG 5.1.2）。详见 §9.2 逐权限映射。

决策 F（新，2026-06-28）：iOS P2P 数据面下沉原生 libwebrtc（与桌面 pion 对称）

修订决策 A 的“数据面亦跑在无头 WebView JS 里”。P2P DataChannel 的字节收发（数据面）已从无头 WebView 的 JS 引擎移到原生 libwebrtc（Sources/Engine/LibWebRtcEngine.swift，RTCPeerConnection），与桌面把数据面移到 Go/pion 完全对称。

• 无头 WebView 此后只跑编排：信令转发 / 会话 / presence / 消息 / 状态机 / relay（hub.ts + transfer.ts），不再承载 P2P 数据面。决策 A 的“原生壳 + 无头引擎”仍成立，只是引擎的职责收窄到编排层。
• 缘由（U1→U2 翻案）：先试 gomobile+pion（与桌面同引擎，U1），真机 POC 证伪——Go raw BSD socket 不与 iOS Network framework 集成（连接时好时坏 + 中途断流）。按闸退到 libwebrtc.framework（U2，stasel/WebRTC M149 经 SPM、pin exactVersion 149.0.0）。完整决策依据与实测证据见 desktop/NATIVE-TRANSFER.md §7/§8。
• 收益：libwebrtc 原生集成 iOS 网络栈 + DcSCTP 默认 ~5MB rwnd——摆脱 WebKit 写死的 256KB 接收窗（R-iOS-3 的吞吐残差）对数据面的钳制，连通性与吞吐一并根治。
• 互通靠线协议逐字节对齐：LibWebRtcEngine 是 desktop/engine 的 engine.go/session.go 线协议的忠实 Swift 端口——DataChannel cdrop-file（ordered）、meta/二进制分片(64KB)/done/ack 帧、16MB/4MB 水位背压、ack 追平完成、不冲突落盘。故 iOS↔桌面（pion）、iOS↔浏览器（JS）三端互通。
• 桥与 JS 路由零改动：IOS_NATIVE 开关、p2pIos.ts/net/ios.ts 桥协议原样；只在 Swift 侧新增一条原生传输 RPC（startOutgoing/startIncoming/handleSignal/cancel，completion-based，经 resolveOnMain 跳主线程 resolve）。iOS 定向的引擎配置绝不回流 desktop/engine 共享包。
• 验证：环回端到端（两个引擎同进程交叉连、20MB 经完整线协议传输后逐字节比对）✅；模拟器全 app 编译 ✅；web typecheck/build ✅。真机 / 真网吞吐互通为剩余闸（须 deploy prod 让设备拿到 IOS_NATIVE=true 引擎 + 真机装机，二者 Touch ID 门控）。

---

1. 后端现状（决定 iOS 能做什么，2026-06-24 扫描）

能力	结论	对 iOS 的含义
文件传输	纯实时（P2P / 实时 relay，relay 是内存环 64MiB、2 分钟空闲释放），零落盘暂存	Share Extension 不靠服务端暂存；接收方须同时在线
剪贴板 /api/clipboard	持久 LWW + REST，作用域令牌可访问	决策 C 的纯原生链路
消息 /api/message	临时、不持久、不可轮询	文本同步走剪贴板通道，消息仅尽力而为实时
作用域令牌	仅 clipboard 一个 scope，rejectScoped 挡死 /transfer	发送须完整会话；Share Extension 用交接而非自带令牌
推送	仅 Web Push（VAPID），无 APNs	APNs 须新建（§3）
原生鉴权	IdP bearer（RS256）/ 扫码自签会话；设备隐式登记（X-Device-Name）	原生 app 可正常登录持会话

Share Extension 落法（据上）：抓文件 → 写 App Group 容器 → 深链唤起主程序选设备发送（接收方须在线、大文件主程序稳跑、扩展不持完整令牌更安全）。

---

2. 桥协议（arch A 的接口契约，账号无关、可先冻结）

状态（2026-06-28，决策 F 后）：本节描述的桥是编排与控制面（信令 / 会话 / presence / 消息 / 接收回退字节通道）。P2P 数据面（含其磁盘 I/O）现走原生 libwebrtc（决策 F），不再经此桥的 sendFile / Begin-Append-Finalize 路径；那条接收字节通道仅保留给 relay / 非原生回退。下文桥语义对编排层仍准确。

原生 ↔ 无头 JS 引擎的 RPC：WKScriptMessageHandler（JS→Swift）+ evaluateJavaScript（Swift→JS），类比 Wails 的 EventsEmit / bound methods，但方向相反（原生在顶层）。

• 平台判定：isIOSShell()（web/src/net/ios.ts）查 window.webkit.messageHandlers.cdropEngine 在场（类比 isDesktop() 查 window.go.main.App）。无头入口（web/src/engine/main.ts）据此装配桥。
• 注入：原生在加载 bundle 前经 WKUserScript 注入 window.__CDROP_BOOT__ = { session, device_name, api_base, device_type:"ios" }，store 在 import 时即水合（沿桌面同一注入范式）；JS 永不持有长寿命密钥（refresh_token 只在原生 Keychain）。
• 原生 → 引擎命令（原生 evaluateJavaScript 调 window.__cdropEngineEvent(name, payload)）：sendFile { target, url, name, size, type? }、cancelTransfer { sessionId }、switchToRelay { sessionId }、session { access_token, user }（续期令牌）、shutdown。
• 引擎 → 原生：① 单向通知（postMessage({ notify, payload })）：ready / transfers / transferDone / sendStarted / error；② 请求 / 响应 RPC（postMessage({ id, method, payload })，原生回调 window.__cdropEngineResolve(id, ok, value)）：接收落盘 saveDownload / beginDownload / appendDownload / finalizeDownload / abortDownload（data 为 base64，复用桌面同形）。剪贴板不走此桥（决策 C 纯原生）。
• 复用边界：接收侧字节桥沿用桌面已验证的 base64 分批、有界内存（iOS 上限更小，64MB/16MB 避 jetsam）；发送侧经 url 取回文件为唯一新实现点——当前整文件 fetch 进内存（小 / 中文件可行），大文件按 slice 向原生拉取是真机优化点（R-iOS-4）。
• 已落地（web 侧，账号无关、tsc/vite build 双过、对现网零影响）：net/ios.ts（桥 + isIOSShell + 接收封装 + notifyNative）、engine/main.ts（无头入口）、incomingSink.ts（通用混合槽路由 iOS）、engine.html + vite.config.ts 多入口。
• 加载源（关键）：无头引擎必须从安全上下文加载——RTCPeerConnection 在非安全 origin（如自定义 cdrop:// scheme，WebKit 视作 non-secure context）下可能被禁。故引擎页走 https://：线上 drop.commilitia.net 或应用内本地 https 服务的静态 bundle；自定义 scheme 仅用于 WKURLSchemeHandler 给 JS 流式喂文件字节，不可用它直载引擎页。见 R-iOS-3。

---

3. 服务端 APNs 通道（账号无关的结构，.p8 到位再落代码）

新增 internal/apns 与 internal/push 并列，只换发送后端：

• 库：APNs 走 HTTP/2 + JWT（.p8 的 ES256 签名），可用 github.com/sideshow/apns2，或自手写（与现有 go-jose 一致）。
• 配置（koanf，CDROP_APNS_*，全可选，缺失即 iOS 推送惰性关闭）：APNS_KEY_PATH、APNS_KEY_ID、APNS_TEAM_ID、APNS_TOPIC（bundle id）、APNS_ENV。
• 存储：push_subscriptions 加 platform 列，iOS 行存 APNs token。SubscriptionID 仍用 token 哈希保幂等 upsert。
• 端点：POST /api/push/apns/register {device_token, locale}（鉴权 + X-Device-Name，与 /api/push/subscribe 同组）。
• 触发：在 transfer:incoming / transfer:done|failed / message 的“未投递”分支按 platform 分流。文案复用 internal/push 的 localize。注意——剪贴板不触发推送（决策 C 走控制中心拉取）。

代码结构账号无关，但真发 / 真测要 .p8，故与 iOS 客户端同期落（账号到位后），避免悬空实现。

---

4. 里程碑（修订）

里程碑	内容	账号依赖
I0 账号与证书前置	付费 ADP（$99/年，4 项能力全要）；主 app + 各扩展 App ID（扩展 id 须主 app 前缀）；开启 Push / App Groups / Keychain / Associated Domains；注册 App Group ID；APNs Auth Key .p8（仅一次下载）；Distribution 证书 + Ad Hoc Profile（登记设备 UDID）	硬等付费账号
I1 原生骨架 + 无头引擎装配	Xcode 工程（SwiftUI）；离屏 WKWebView 载无头引擎入口；isIOSShell 注入桥	模拟器可跑 UI；引擎入口 web 侧账号无关
I2 登录态	ASWebAuthenticationSession PKCE / 扫码；refresh_token 存 Keychain；session 注入 JS	模拟器可跑
I3 传输（核心）	无头引擎桥（send 自定义 scheme 流式 / receive 复用 Begin-Append-Finalize）+ 原生传输 UI（液态玻璃、含进度 / 速度 / 状态）	真机硬等账号
I4 剪贴板	控制中心两控件 + App Intents；纯原生 /api/clipboard 读写 + 版本探针	控件真机硬等账号；REST 链路可先写
I5 Share Extension	抓文件 → App Group → 深链主程序选设备发送	真机硬等账号
I6 APNs	服务端通道（§3）+ 原生注册；不含剪贴板	.p8 + 真机硬等账号
I7 打磨与分发	后台窗口；图标 / 启动屏（复用品牌资产）；旁加载分发	硬等账号

实现状态（2026-06-27）：I1/I2/I3/I4/I5/I6 的代码全部落地——发送端流式（R-iOS-4，FileSource + 原生 Range，整文件不进 WebView 内存）；后台续传（BGContinuedProcessingTask）；APNs（后端 internal/apns ES256 + 原生注册经引擎桥）；Share Extension（App Group 收件箱 + cdrop://share 深链）；控制中心两控件（专用 broker 设备会话，纯原生 REST，不与引擎抢 refresh 轮换）。模拟器验 + ultracode 多 agent 审查修讫（0 HIGH，修 2 MED + 7 LOW）。I0 账号 / 证书 + 真机签名 / 真发推送 / 旁加载分发仍账号门控——手册 ios/CDrop/REALDEVICE.md（ASC API Key 自动 provisioning + just ios-device 全 CLI 装机，-allowProvisioningUpdates 自动登记设备 / 建 profile）。包名 net.commilitia.Commilitia-Drop，App Group group.net.commilitia.Commilitia-Drop。

更新（2026-06-28）：① P2P 数据面改原生 libwebrtc（决策 F；完整依据 desktop/NATIVE-TRANSFER.md §7/§8）——已真机装机、用户反馈“传输总体良好”，真网吞吐互通为剩余闸；② UX 改造（发送预览直入 / 消息按设备会话 / 删除粒度，§10）；③ 品牌与字体系统（logo + Orbit Gothic / Maple Mono / Fredoka，§11）。

---

5. 一致性：强约束同步 vs 检查单（决策 D 展开）

检查单是兜底，不是默认。 先尽量用强约束（单一真源、两端机械消费、漂移不可能），管不住的残余才进检查单（见 ios/PARITY.md）。

强约束（机制保证）

1. 传输行为 → arch A 共享 JS 引擎。 整套状态机 / 进度 / 完成 / 错误 / 协议无法漂移，零额外成本。
2. i18n 文案 → 单一源。 iOS 原生侧薄 loader 读 web 那份 i18n JSON（随 bundle 或从服务端取），不写转换器、不做 .xcstrings 镜像。缺键即露。
3. 品牌资产 + 主色 → 单一源。 资产沿用 Dropbox 那套（web+desktop 已接）；品牌主色 + logo 作小共享常量。
4. 后端 API → 后端即共享契约。 两端瘦客户端对齐同一 JSON 形状，不加 codegen（过度工程）；字段变更的人工残余进检查单。

检查单（人判定的残余）

见 ios/PARITY.md：① 元素 / 屏 / 功能存在性对等；② 非引擎驱动的新流程 / 状态；③ 后端 API 字段变更提醒；④ 允许分叉登记。

明确不做

设计令牌 codegen 管线——过度工程，且与液态玻璃系统材质 / 语义色 / SF Symbol 母语相冲。间距 / 圆角 / 字阶归“允许分叉”。

---

6. 现在能做 vs 等账号（修订）

账号无关、即刻可做：

• 本计划 + ios/PARITY.md 同步检查单（✔ 本轮）。
• web 侧无头引擎入口（✔ 已实现，账号无关）：net/ios.ts（桥 + isIOSShell() + 接收封装 + notifyNative）、engine/main.ts（不加载 React 的独立入口：水合 store → startHub → 暴露 RPC + 订阅推事件）、incomingSink.ts（通用混合槽路由 iOS，内存上限 64MB/16MB 避 jetsam）、engine.html + vite.config.ts 多入口。tsc / vite build 双过、对现网 web / 桌面零影响。
• 桥协议契约冻结（§2，✔ 已与实现对齐）。
• i18n 单一源：现有 catalog 已是扁平 { key: string } 结构（src/i18n/locales/*.ts），数据形态即可导出 JSON；原生侧薄 loader + 构建期 emit 待原生工程就位时同期落（避免向无消费方空导出）。
• 剪贴板 REST 链路（/api/clipboard 读写 + 版本探针）的数据流设计（控件实现等账号，协议可先定）。
• iOS 原生 scaffold（✔ 已实现，账号无关）：ios/CDrop/（xcodegen project.yml）——液态玻璃壳（TabView + .tabBarMinimizeBehavior + .buttonStyle(.glassProminent)）+ 离屏引擎 WKWebView 宿主 + 桥 EngineController（对侧契约同 net/ios.ts）+ DownloadManager（落沙盒）。已编过 iphonesimulator26.5（iOS 26 SDK，含液态玻璃）——证 arch A Swift 侧成立。启动 / 截图待 iOS 26 模拟器运行时（约 7GB，账号无关）下载（xcodebuild -downloadPlatform iOS）。
• 明确不做（避免悬空 / 过度工程）：设计令牌 codegen；APNs 发送代码（.p8 到位再落）。（注：原“Xcode 工程等账号”已作废——模拟器构建不需签名 / Provisioning，工程已建且 compile-verified；只有真机签名 / APNs 真发 / 分发才等付费 ADP。）

硬等付费 ADP 账号：真机签名 / 跑、APNs 真发、Share Extension、控制中心控件真机、旁加载分发。

---

7. 风险与未决（修订）

• R-iOS-1 后台挂起 / JS 全停：app 退后台即挂起、WKWebView JS（含 WebRTC 事件循环）停摆，DataChannel 无媒体轨后台不保活。文件传输本需前台（双方在线、用户看进度），可接受；用户主动触发的传输用 iOS 26 BGContinuedProcessingTask 续跑（带系统进度 UI）。剪贴板走控制中心 App Intent，不依赖常驻 WebView。
• R-iOS-2 剪贴板后台限制：读弹横幅、后台不可监听 → 控制中心手动两控件已据此设计；app 内读用 UIPasteControl、探测用 hasStrings（均不弹横幅）。
• R-iOS-3 无头 WebRTC 真机稳定性 + 安全上下文：arch A 最大未验证点——① RTCPeerConnection 须在安全 origin；② BGContinuedProcessingTask 能否让 WebView JS 不被挂起待验。2026-06-24 模拟器已部分证实：iOS 26 WKWebView 从 http://127.0.0.1（isSecureContext=true，loopback ＝ 潜在可信源）跑 RTCPeerConnection + DataChannel + createOffer ＝ RTC:ok、STUN srflx 候选正常、原生↔JS 桥往返正常 → arch A 核心成立、不转 B。注：安全源不止 https，loopback 亦可（可选应用内本地 https/loopback 服务内嵌 bundle，离线可用）。余真机验：host / 同内网直连候选 + 本地网络权限（R-iOS-6）、后台挂起续传（BGContinuedProcessingTask）。
• R-iOS-4 字节桥：接收侧复用桌面 Begin/Append/Finalize（base64 分批、有界）已验证；发送侧自定义 scheme（WKURLSchemeHandler）流式喂 JS 为新实现点。
• R-iOS-5（原 App Store 过审）在 Ad Hoc 旁加载下作废；若改走 TestFlight 则 Beta 审核仍在。
• R-iOS-6 本地网络权限（同内网 P2P 硬墙）：WebRTC host 候选 / mDNS 触发 NSLocalNetworkUsageDescription（须配 NSBonjourServices），拒绝即只剩中继候选 → 回退 relay（cdrop 已有兜底）；mDNS 失败不可区分“无服务”，UI 须降级。不可拿它当核心功能门槛。
• R-iOS-7 付费账号 + 分发摩擦：4 项能力 + 分发全需付费 ADP；Ad Hoc 100 台 + UDID 预登记是旁加载硬约束——比桌面 Dropbox“下载即用”多一道摩擦。

---

8. iOS 设计规范要点（HIG · 液态玻璃）

抓取自 Apple HIG / WWDC25（2026-06-24），只取对 cdrop 界面有约束力的重点。

8.1 液态玻璃（材质用法）

• 两层模型：玻璃只用于功能 / 导航层（Tab bar / Nav bar / Toolbar / 浮动控件 / sheet 边框）；内容层禁用——列表、设备卡、传输卡属内容层，不加玻璃。
• 用 iOS 26 SDK 编译，Tab bar / Nav bar / Toolbar / sheet 自动玻璃化；同时移除所有自定义 bar 背景 / 装饰色（否则破坏系统玻璃）。
• 自定义悬浮控件（如传输卡上的取消 / 暂停 pill）才手动 .glassEffect(.regular.interactive())，多块玻璃须放进 GlassEffectContainer 共享采样；主操作用 .buttonStyle(.glassProminent)。
• 禁忌：玻璃叠玻璃、滚动内容区铺玻璃、大面积内容玻璃背景、非主操作滥用 tint。
• Tab bar 滚动收起 .tabBarMinimizeBehavior(.onScrollDown)；全局传输状态可置 .tabViewBottomAccessory（类 Apple Music 迷你条）。圆角走同心 .rect(cornerRadius: .containerConcentric)，sheet / popover 系统自动同心。

8.2 基础（色彩 / 字体 / 图标 / 布局）

• 色彩：用语义色（label / secondaryLabel、systemBackground 层级、systemFill、separator），不硬编码 hex——暗色 / 对比度 / vibrancy 免费。品牌主色以 Asset Catalog 的 Color Set（含 Dark 变体）接入（Color("BrandPrimary")）——这正是强约束③（§5）在 iOS 侧的落地形态。
• 字体 / Dynamic Type：系统 text styles（Body 17 / Headline / Title…）+ 必须支持 Dynamic Type（正文 / 标题 / 主按钮可缩放）。与“字体归允许分叉”不矛盾——分叉的是字体选择，Dynamic Type 支持是硬要求。
• SF Symbols：优先系统符号（自动与文字对齐 / 字重匹配），四种渲染模式（mono / hierarchical / palette / multicolor）；品牌专属才自定义 symbol（须注解四模式以获 Dynamic Type / 无障碍）。
• 布局：内容 / 控件留安全区，最小命中区 44×44pt，对比度 4.5:1（正文）/ 3:1（大字 / 非文字），不硬编码宽度。

8.3 控件 / App Intents（剪贴板两控件落地）

• 剪贴板“上 / 下”用 ControlWidgetButton（一次性动作）；SF Symbol 必备（锁屏 / 操作按钮只显示图标，须独立达意）。跨设备状态靠推送 reload（ControlCenter.reloadControls）、不轮询；控件内不发网络请求，经 App Group 容器读主 app 写入。
• App Intent：动词+宾语命名、title 编译期常量本地化串、默认后台执行（返回 dialog / snippet、不开 app）；iOS 26 Interactive Snippets 可在不开 app 下做“选设备”二级操作。

8.4 分享（Share Extension）

• 扩展只做轻：内容预览 + 选设备 + 验证 → 写 App Group 容器 + 交接主 app；不在扩展内跑传输引擎（内存 ~120MB，见 §9.1）。宽度系统固定不可改；完成即“已提交”退出，不等传输完成。

8.5 通知（APNs）

• 文案具体（“文件 X 已接收（3.2MB）”）；中断级别用 .active（传输完成 / 失败），不滥用 .timeSensitive；threadIdentifier 按“完成 / 失败 / 消息”分组；首个有价值操作后再 just-in-time 请求权限，按类别细分开关。剪贴板不推送（决策 C）。

8.6 无障碍（玻璃语境）

• Reduce Transparency / Increase Contrast / Reduce Motion：系统对 Tab / Nav 自动回落；自定义玻璃控件须自行提供不透明回落 + 关动效。传输进度动画检测 accessibilityReduceMotion 降级为渐隐 / 变色。VoiceOver：图标按钮 accessibilityLabel 用动词（“发送文件”而非“箭头向上”）。

8.7 App 图标（iOS 26）

• 用 Icon Composer 做分层图标（logo 前景 + 品牌色渐变背景），系统材质自动出高光 / 折射 / 阴影——源稿不要烘焙圆角 / 阴影 / 斜面。须验明 / 暗 / clear / tinted 各变体（暗背景下 logo 填充色可辨）。接品牌资产源（强约束③）。

---

9. 开发禁区 / 平台约束（硬性 vs 审核 / 账号）

分级：【OS 硬】＝系统强制、绕不过；【账号】＝付费 / 账号策略；【审核】＝仅 App Store / TestFlight 审核约束（Ad Hoc 旁加载不触发）。

9.1 运行 / 生命周期

• 【OS 硬】后台一律挂起、JS 全停：app 退后台即被挂起，WKWebView 的 JS（含 WebRTC 事件循环）停摆，DataChannel（无媒体轨）后台不保活 → 传输必须前台发起；用户主动触发的传输用 iOS 26 BGContinuedProcessingTask 续跑（带系统进度 UI，能否让 WebView JS 不被挂起须真机验，R-iOS-3）。
• 【OS 硬】无后台常驻监听：剪贴板 / 消息不能后台轮询监听 → 决策 C 的控制中心手动触发正据此。
• 【OS 硬】自定义 scheme = 非安全上下文 + OPFS 单文件 ~10MB：故引擎从 https 安全源加载（§2）、大文件不走 OPFS、经原生桥 Begin/Append/Finalize 落沙盒（接收侧已是此设计）。
• 【OS 硬】Share Extension ~120MB jetsam：扩展内装不下 WKWebView + WebRTC 引擎 → 只做交接（§8.4）。

9.2 权限 / 隐私 / 网络（落实决策 E 的逐权限映射）

• 【OS 硬】本地网络权限（持久）：同内网 P2P 直连（WebRTC host 候选 / mDNS）触发 NSLocalNetworkUsageDescription，须配 NSBonjourServices；一次授予长期持久 → 首启引导显式询问（决策 E）。缺失静默失败、拒绝则只剩中继候选 → 降级回退 relay 并提示“仅中继”（cdrop 已有兜底；mDNS 失败不可区分“无服务”，UI 须降级）。
• 【OS 硬】相机权限（持久，扫码登录）：NSCameraUsageDescription 缺失即崩；首启 / 首次扫码时显式询问。无兜底 → 拒绝则提示“无权限”并阻塞“扫码”特性（跳系统设置）；登录可走 OIDC 等其他途径，阻塞的是扫码、非整个 app。
• 【OS 硬】Info.plist 用途说明缺失即崩：相机、相册键（若选图）必声明；剪贴板无 iOS plist key（横幅系统自动、关不掉）。
• 【OS 硬】ATS 强制 HTTPS / TLS1.2+：cdrop 已全 https，无需例外。
• 【OS 硬】剪贴板：后台不可读、读内容弹横幅（关不掉）、写不弹、hasStrings 探测不弹、UIPasteControl 读不弹 → “上”控件接受一次横幅、app 内读用 UIPasteControl、“下”控件写无感。
• 【审核】隐私清单 PrivacyInfo.xcprivacy + Required Reason API（UserDefaults CA92.1 等）：上架 / TestFlight 才强制；Ad Hoc 非硬性，但第三方 WebRTC SDK 自带清单仍建议补。

9.3 能力 / 扩展 / 签名 / 分发

• 【账号】4 项能力全需付费 ADP：APNs / App Groups / Keychain 共享 / Associated Domains——免费 Personal Team 一律不支持（决策 B / I0）。
• 【OS 硬】扩展归属：Share Extension / ControlWidget 的 bundle id 须主 app 前缀、同 Team 签名；与主 app 共享数据唯一合法途径 = App Group 容器。
• 【OS 硬 + 账号】Ad Hoc 100 台 / 年 + UDID 预登记：旁加载的硬上限与摩擦（决策 B）。
• 【OS 硬】APNs 环境隔离：dev profile＝sandbox、ad-hoc / 分发＝production，token 不互通。

---

10. UX 改造（2026-06-28，真机反馈驱动）

真机使用后落地的三块结构性改造，均属决策 D 的“非引擎驱动 UI 流程”（进 ios/PARITY.md 残余项 1/2，已登记）。

10.1 发送预览界面（取代即弹的设备选择框）

• 选文件 / 选图后不再直接弹设备选择，而是进入发送预览（Sources/SendComposeSheet.swift）：列出待发文件名 + 字节大小，下方列表选目标设备。手动发送与分享发送共用此界面。
• 手动入口支持多选：fileImporter(allowsMultipleSelection: true) + photosPicker(selection:) 数组；RootView 的 present/sendPicked/clearPicked/loadPhotos 串起选取→预览→发送。

10.2 分享直入预览（修“必须重启 app”）

• Share Extension 抓取 → 暂存 App Group → 唤起主程序，主程序直入发送预览（同 SendComposeSheet）。
• 修复“分享后必须重启 app 才出现传输”：唤起宿主 app 经响应链 IMP 调现代 openURL:options:completionHandler:（旧单参 openURL: 在 iOS 18+ 已成空壳），并以 scenePhase 回 .active 时 loadPendingShares() 兜底——回前台即扫 App Group 暂存、补出预览，不依赖那条 iOS 灰区的扩展→宿主唤起是否可靠。分享引导界面见 §11.3。

10.3 消息按设备会话聚合 + 删除粒度

• 消息从扁平流改为按设备聚合的会话列表（社交 app 模型，Sources/MessagesView.swift）：会话列表项 = 有历史或当前可达的设备；点进 ConversationView 看与该设备的线程。非 APNs 离线设备不能作为发送对象，但历史可查看（canMessage() 判定）。
• 每设备未读分桶：EngineController 的 unreadByPeer: [String: Int] + activeConversation；每设备会话显示各自未读红点，“消息”标签显示总未读（unreadMessages = unreadByPeer.values.reduce(0,+)）。进会话即 markConversationRead + setActiveConversation。
• 任意删除：可删单条消息与整个设备的历史（deleteConversation()），避免废 session 堆积。

---

11. 品牌与字体系统（2026-06-28，对齐 web）

iOS 界面引入与 web 一致的品牌资产与字体栈——这是强约束③（§5，品牌资产 + 主色单一源）在视觉层的延伸。

11.1 品牌 logo

• Shared/Brand.swift：BrandMark（吉祥物，资产 Shared/Brand.xcassets/LogoMark，源 web/public/logo-mark.png）、Wordmark（“Commilitia” 主色 + “Drop” cdropAmber，Fredoka SemiBold）、BrandLockup、BrandHero(tagline:)。
• 接入点：登录页（BrandMark + Wordmark 取代纯文字标题）、传输空态（BrandHero）、设置页顶部横向品牌头、控制中心控件重设计（吉祥物 + 品牌渐变 + 全宽按钮，最大化空间）。Theme.swift 加 Color.cdropAmber（#DB9410 / #F8C637）。

11.2 字体栈（Orbit Gothic + Maple Mono + Fredoka）

• 与 web fonts.css 同源：Sans = Orbit Gothic CJK SC（Regular + SemiBold）、Mono = Maple Mono、字标 = Fredoka SemiBold。
• woff2 运行期注册：Orbit / Maple 以 woff2 内嵌（约 TTF 的 1/3 体积），UIAppFonts 历史只认 ttf/otf，故经 CTFontManagerRegisterFontsForURL 运行期注册（iOS 13+ Core Text 原生支持 woff2，实测 register→true）——见 Sources/BrandFonts.swift 的 BrandFonts.register()（AppDelegate 启动调）。Fredoka 是 ttf，走 UIAppFonts。
• 助手 + sweep：BrandFonts 暴露 Font.oBody/.oHeadline/…（Orbit，对位 SF 语义样式）、Font.maple(…)（Maple Mono）；导航 / 标签栏标题经 UIKit appearance 代理换 Orbit；7 个视图的 .font(.语义) → .font(.o语义) sweep。
• 仅主 app：CJK 字体大，不进 Share / 控件扩展（它们保持系统字 + 仅 Fredoka 字标）；生僻字超 Orbit 字汇时 iOS 字体级联自动回退苹方，不出豆腐块。
• 字体不入库：Orbit Gothic 为专有 / 定制字体（公开仓库不分发），Maple / Fredoka 虽开源也统一不入库保持精简；经 .gitignore 排除，构建前 just ios-fonts（已 chain 进 ios-device / ios-sim-build）从私有 CDN / Google Fonts 幂等拉取。详见 Sources/Fonts/README.md。

11.3 分享引导界面

• Share/ShareGuideView.swift（ShareModel: ObservableObject）：扩展内呈现吉祥物 + Wordmark + “已就绪 N 个文件” + “打开 Commilitia Drop” 主按钮 + 取消，引导用户回到主程序完成发送（扩展内不跑传输引擎，§8.4）。取消则删暂存；started 标志防重入。

---

12. 全平台平均速度（2026-06-28）

传输完成后，速度列不再显示最后一次瞬时速率，而显示平均速度（总字节 / 总耗时）。三端一致：web store/slices/transfer.ts 的 completeTransfer 在 DONE 时置 bytesPerSec = total / (elapsedMs/1000)、TransferRow.tsx 在 DONE 读 avgRate；iOS RootView 卡片 / 详情完成态显平均速度；i18n 加 transfer.avgRate（web 3 locale + ios 3 JSON）。桌面（Wails）共享 web store，逻辑自动生效，但需 just desktop-build-{mac,win} 重建 + 重分发方落到已装客户端。

---

附：与桌面端策略对照（修订）

维度	桌面（Wails）	iOS（arch A）
UI	复用 web/src	原生 SwiftUI（分叉，PARITY 管）
引擎	Go 原生	复用 web/src JS（无头）
桥方向	JS-UI 顶层 → Go	SwiftUI 顶层 → 无头 JS
refresh_token	Go keyring	iOS Keychain
登录	loopback PKCE	ASWebAuthenticationSession / 扫码
后台通知	Go 常驻进程 + 原生 API	服务端 APNs
剪贴板	Go Monitor 实时双向	控制中心手动两控件（纯原生 REST）
平台判定	isDesktop()（window.runtime）	isIOSShell()（window.webkit.messageHandlers）
分发	Dropbox 旁加载	旁加载（非 App Store）