Files
QFT/ios/README.md
T
zhy200308 eae24000e9 优化IOS
2026-08-19 09:31:21 +08:00

259 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# QFT iOS 客户端 v0.5.0
对齐当前 Windows / macOS / Android 三端的能力,四条链路:
| 方向 | 链路 | 说明 |
|---|---|---|
| 电脑 → iPhone(光学) | **屏幕 → 摄像头** | 扫电脑「光学传输」页循环播放的 QFT2 二维码,文件数据完全不经过网络 |
| iPhone ↔ Windows | **专用网络(QFT Direct)** | 扫码后加入电脑开的专用 Wi-Fi,从路由表认出网关即电脑 |
| iPhone ↔ Mac / Linux | **局域网** | 扫二维码,或直接输电脑上的连接码;下发走 8 路并行 Range |
| iPhone ↔ iPhone | **隔空(AWDL 点对点)** | 多选文件后显示二维码,对方扫一下即可,**不需要连同一个 Wi-Fi** |
本次改动只在 `ios/` 目录内,未改动 `desktop/`(Windows/macOS/Linux)与 `android/` 的任何实现。
## 系统版本与向下兼容
- **最低系统:iOS 15.0**,覆盖 iPhone 6s(2015)及以后,与 Android 端 `minSdk 24`
(Android 7.0,2016)覆盖的机型年代大致相当。
- 再往下走不动了:`URLSession` 的 async 接口是 iOS 15 才有的,低于 15 就要把
全部网络代码改回 completion handler,代价与收益不成比例。
- 新系统上更好的实现照样用,但一律走 `App/Compatibility.swift` 分叉,不把整个
App 的部署目标顶上去:
- `NavigationStack` / `ShareLink` / `LabeledContent`(iOS 16)→ iOS 15 上分别回落
`NavigationView` / `UIActivityViewController` / 手写 `HStack`;
- 两参数 `onChange`(iOS 17)→ 统一用 `onReceive`;
- `videoRotationAngle`(iOS 17)→ iOS 15/16 上用 `videoOrientation`;
- `UnsafeRawPointer.loadUnaligned`(Swift 5.7 运行时 / iOS 16)→ 改成手工拼大端
与 `memcpy`。
## 打开工程
```bash
open ios/QFT.xcodeproj
```
工程已提交到仓库,不需要 XcodeGen 之类的额外工具。首次构建前在
Target → Signing & Capabilities 里选一下你自己的开发者账号(免费账号即可,
生成的描述文件 7 天有效)。
增删源文件后重新生成工程:
```bash
python3 ios/tools/generate_xcodeproj.py
```
Bundle ID:`com.qft.transfer`(按需改 `generate_xcodeproj.py` 里的常量)。
## 光学接收(不用网络的那条)
首页「光学接收」对准电脑的「光学传输」页即可。这条链路上文件数据**只经过屏幕和
摄像头**——Wi-Fi、蓝牙、局域网、互联网都不参与,因此也是「电脑不允许接任何网络」
场合下唯一可用的路径。
实现与 Android 端同一套状态机,只是解码器换成 Vision:
```text
居中搜索(92% 画面)
↓ 解出一帧
按条码外接框建立 ROI(放大 1.22 倍、按像素修成正方形)
↓
后续只把 ROI 交给 Vision
↓ 轻微移动:平滑跟随(alpha 0.35)
↓ 连续 3 帧丢失:逐级放大 ROI
↓ 连续 12 帧丢失:回到全画面重新搜索
```
其它与 Android 对齐的点:
- 相机格式在「支持 ≥60 FPS 的格式里取分辨率最高的」,锁定固定帧率,关 HDR 与防抖;
- `alwaysDiscardsLateVideoFrames`,追不上就丢,不播放过时的相机帧;
- 锁定后每 2.5 秒在 ROI 中心重新对焦/测光(屏幕是平面光源,连续自动对焦会拉风箱);
- 屏幕上同一帧会被连续拍到多次,重复帧不会重复送进装配器;UI 同时显示
**解码/s** 和**有效新帧/s**——决定传输时间的是后者,据此在电脑端选 30 / 45 / 60 FPS;
- 每帧 CRC32 + 整份 SHA-256,校验不过就整份丢弃等下一轮重播,绝不把半份文件交给用户。
## 专用网络(iPhone ↔ Windows)
Windows 进入接收后会用 Wi-Fi Direct Legacy AP 开一张专用网,二维码里**按设计不带
任何电脑地址**(见 `desktop/src/pairing.rs::qr_endpoints`):手机必须先加入那张
Wi-Fi,再从路由表里把网关认出来——那就是电脑。
iOS 侧两条路径,取决于**签名能力**:
| 情况 | 行为 |
|---|---|
| 有 `HotspotConfiguration` entitlement | `NEHotspotConfiguration` 自动加入(`joinOnce`,会话结束不留在系统 Wi-Fi 列表里) |
| 没有(免费账号) | 显示 SSID / 密码 + 「打开设置」,用户手动连一次,回 App 点「我已连上」继续 |
**不会假装成功**:拿不到能力时直接转手动引导,而不是让用户对着一个永远连不上的
进度条等下去。
entitlement 只有付费账号签得出来,带上它免费账号会直接签名失败,因此工程默认
**不引用** `QFT/QFT.entitlements`。要开启:
```
Target → Build Settings → QFT_ENTITLEMENTS = QFT/QFT.entitlements
```
加入之后判据不是「系统说加好了」,而是**协议层握手成功**——能用正确令牌 ping 通
`/qft/ping` 才算数。系统接受配置 ≠ 拿到 IPv4 ≠ 电脑那侧的 Wi-Fi Direct 数据通道已建立。
## 局域网(iPhone ↔ Mac / Linux)
两种入口:
1. **扫二维码**:和 Windows 的 LAN 模式完全一样。
2. **连接码**:电脑上打开 QFT →「电脑 ↔ 电脑」→「我要接收」,屏幕上会显示
`K7M2-9X4P-QR3T` 这样一串码,**地址、端口和配对秘密都编在码里**。iPhone 在
「连接附近的电脑」页输入即可,不用扫码、不要求同网段可广播。
「附近的电脑」列表用 `QFTBROWSE3` 广播(`desktop/src/discovery.rs` 的客户端实现),
只是帮用户确认「就是这台」;真正建立会话仍然靠连接码换令牌(`POST /qft/pair`)。
电脑端输错 5 次即作废整个码,所以 App 绝不重试。
**边界说清楚**:连接码换来的是电脑**接收端**的会话,因此这条路径只能「把文件发到
电脑」。要让电脑下发文件,请在电脑上选好文件后扫它生成的二维码。
### 更高效在哪
电脑下发改成 **8 路并行 Range 下载**:
- 块大小按文件自适应,落在 64 KiB–16 MiB,目标 8 路并发;
- 每块最多重试 5 次,403 立即失败不重试;
- 完成情况写进 `.qftpart` 旁边的账本(并行块是乱序落盘的,「已落盘长度即断点」
那套在这里不成立),中断后只补没收到的块;
- 全部收齐后单遍 SHA-256,通过才 rename;
- 对端返回 200(忽略了 Range)时显式失败并**回落单流下载**,不会因为遇到老版本
电脑端就直接报错。
## 隔空(iPhone ↔ iPhone)
`PeerLink` 用 `Network.framework` 并打开 `includePeerToPeer`。底层就是隔空投送用的
那条链路——BLE 发现 + AWDL 点对点 Wi-Fi,两台设备不需要路由器,也不需要连同一个
Wi-Fi。两端在同一个 Wi-Fi 下时它会自动优先走基础网络。
握手用 **TLS-PSK**:预共享密钥(32 字节)由发送端随机生成并写进二维码,扫码这个
动作本身就完成了带外密钥交换与双向认证。没扫到码的第三方连上来也过不了 TLS 握手,
因此不需要任何证书体系,也不需要配对弹窗。
v0.5.0 起支持**多文件队列**(对齐 Android → Android 的手机互传):
```
发送方 接收方
多选文件 → 逐个算 SHA-256
启动 NWListener(Bonjour: _qft-p2p._tcp)
生成 32 字节 PSK
显示 QFTP2P2 二维码 ──────扫码────→ 解析出 PSK + 服务实例名 + 清单摘要
NWBrowser 找到实例
←──────── TLS-PSK 握手 ────────→
QUEUE(JSON 清单) ───────────────────→ 摘要必须与二维码一致
FILE_BEGIN / DATA×N / FILE_END ─────→ 逐个落盘 + 单文件 SHA-256
(对队列里每个文件重复)
EOF ────────────────────→
←──────── RESULT(JSON) ──────── 全部通过才算成功
```
**文件清单不进二维码**,只放一个 SHA-256 摘要:十几个文件的元数据会让二维码密到
扫不动。清单在 TLS 建立之后才传,接收端拿摘要比对——扫码这一下依然锁定了
「你看到的就是你收到的」。摘要对的是**清单帧的原始字节**,不是重新序列化的结果。
> QFTP2P1(单文件)已移除。iOS 端从未发布过,保留一个没有用户的线格式只会腐坏。
**AWDL 是苹果私有链路,Windows/Android 无法参与**,所以与电脑互传仍走局域网/专用网络
HTTP,与 Android 手机互传只能同一个局域网。
## 已知的平台限制
1. **没有「下载」文件夹。** 收到的文件存在 App 的 Documents/QFT 下,通过
`UIFileSharingEnabled` + `LSSupportsOpeningDocumentsInPlace` 暴露到「文件」App,
也可以在 App 内直接分享出去。
2. **首次访问局域网会弹权限窗。** 已在 `Info.plist` 声明 `NSLocalNetworkUsageDescription`
与 `NSBonjourServices`。若用户误点了拒绝,需要去 设置 → 隐私与安全性 → 本地网络 里重新打开。
3. **上传块固定 4 MiB。** Android 端按文件大小选 4/8/16 MiB,但 iOS 上
`worker 数 × 块大小` 就是内存峰值,16 MiB × 6 会在旧机型触发 jetsam。
4 MiB × 6 = 24 MiB 峰值,局域网速度下每块的往返开销可以忽略。
4. **光学链路是单向的**,只有「电脑 → iPhone」。iPhone 屏幕小、电脑普遍没有摄像头,
反方向没有意义。
## 测试
核心层(协议、发现、上传/下载、光学解码、P2P 链路)不依赖 UIKit/AVFoundation,
可以直接以 macOS 为目标编译运行,**不需要 Xcode,也不需要模拟器**:
```bash
./ios/CoreTests/run.sh
```
也已接入主自检套件(`python scripts/run_all_selftests.py`)。当前 180 项检查全绿。
测试内容:
- `Base64URL`、`Base45` 与三端一致性(Base45 用的是 `desktop/src/base45.rs` 里的同一组向量)
- `QFTPAIR2` / `QFTSEND2` / `QFTP2P2` 解析,含各类畸形输入
- **端点白名单**:二维码是不可信输入,只接受字面量私有 IPv4 + 声明端口。
已覆盖域名、公网地址、`172.32` 边界、非规范八位组、IPv6、带凭据/路径/query 等 11 种拒绝用例
- **专用网络**:只带 Wi-Fi 凭据的二维码被接受,既无地址又无凭据的被拒;
有/无 entitlement 时的决策分支
- **光学链路**:合成 QFT2 播放列表 →「乱序 + 重复」重播 → 落盘校验;
CRC 篡改整帧丢弃;清单摘要不符整份丢弃;0 字节文件边界;ROI 状态机的
锁定 / 放大 / 重新搜索 / 越界夹取
- **连接码**:四组向量由 Rust 实现直接产出,任何一边改了编码都会红;
Crockford 容错、改一位必须失败、公网地址必须被白名单拒绝
- **与 `MockPCServer.py` 的完整传输**:该 mock 严格复刻 `receiver.rs` / `sender.rs`
的线上语义(路径、header 名、JSON 字段、Range 行为、chunk 长度校验、
`/qft/pair` 的错 5 次作废),因此这组测试就是 Swift 端与 Rust 端的**线格式契约测试**
- **8 路并行 Range 下载**与按账本续传
- **真实 TLS-PSK 握手**下的 P2P 多文件端到端传输,含错误密钥与清单摘要不符必须被拒
### 只有真机能验的部分
以下需要你在设备上跑,这台机器上没有 Xcode(只有 Command Line Tools),
App 层(SwiftUI + AVFoundation + Vision + NetworkExtension)无法在此编译:
- [ ] Xcode 打开工程,选模拟器 ⌘B 通过
- [ ] 光学接收的真机吞吐矩阵(电脑 30 / 45 / 60 FPS × 机型),记录有效新帧/s
- [ ] 加入 Windows QFT Direct 专用网(分别验证有/无 entitlement 两条路径)
- [ ] iPhone ↔ iPhone 在**关掉 Wi-Fi 路由器**的场合走 AWDL
- [ ] iOS 15 / 16 / 17+ 各跑一遍(兼容层分叉都要走到)
## 目录
```
ios/
QFT.xcodeproj/ 生成的工程(已提交)
QFT/
Info.plist 权限声明、Bonjour 服务、ATS 本地网络例外
QFT.entitlements HotspotConfiguration(默认不引用,见上文)
App/ SwiftUI 界面(需要 Xcode 才能构建)
Compatibility.swift iOS 15/16/17 分叉
HomeView.swift
ScannerView.swift 配对码扫描(AVCaptureMetadataOutput)
OpticalReceiveView.swift 光学接收(AVCaptureVideoDataOutput + Vision + ROI)
DesktopConnectView.swift 附近的电脑 / 连接码 / 手动加入专用 Wi-Fi
TransferModel.swift
Core/ 纯 Foundation/Network,可在 macOS 上编译测试
Base64URL.swift
Base45.swift RFC 9285,光学帧文本层
Checksums.swift CRC-32(光学帧)/ CRC-8(连接码)
PairingProtocol.swift QFTPAIR2 / QFTSEND2 + 端点白名单
ConnectCode.swift 桌面端连接码
HostDiscovery.swift endpoint → 网关 → UDP 广播 → 子网扫描
RouteTable.swift sysctl 路由表 / 定向广播 / 候选地址
PeerBrowser.swift QFTBROWSE3 节点浏览 + POST /qft/pair
DedicatedNetwork.swift 专用 Wi-Fi 加入策略与 NEHotspotConfiguration
DownloadClient.swift 单流下载(回落路径)
RangeDownloadClient.swift 8 路并行 Range + 断点账本
UploadClient.swift init/chunk/finish 并行上传
OpticalProtocol.swift QFT2 / QFT1 帧与清单
OpticalROI.swift ROI 状态机(纯几何)
OpticalAssembler.swift 会话装配、校验、落盘、速率统计
PeerPairing.swift QFTP2P2 配对码 + 文件清单
PeerLink.swift TLS-PSK + 分帧的点对点链路
CoreTests/
run.sh 编译并运行(swiftc,无需 Xcode)
main.swift 测试用例
MockPCServer.py 复刻 Windows/macOS 端线上语义的假电脑
tools/
generate_xcodeproj.py 工程生成器
```