Files
QFT/ios/README.md
T
2026-08-11 13:43:31 +08:00

119 lines
5.6 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.4.7
三种传输方式:
| 方向 | 链路 | 说明 |
|---|---|---|
| 电脑 → iPhone | 局域网 HTTP | 扫 Windows 端的 `QFTSEND2` 码,自动下载,支持断点续传 |
| iPhone → 电脑 | 局域网 HTTP | 扫 `QFTPAIR2` 码,选文件后并行分块上传 |
| **iPhone ↔ iPhone** | **点对点直连** | 发送方显示二维码,接收方扫码,**不需要连同一个 Wi-Fi** |
## 打开工程
```bash
open ios/QFT.xcodeproj
```
工程已提交到仓库,不需要 XcodeGen 之类的额外工具。首次构建前在
Target → Signing & Capabilities 里选一下你自己的开发者账号(免费账号即可,
生成的描述文件 7 天有效)。
增删源文件后重新生成工程:
```bash
python3 ios/tools/generate_xcodeproj.py
```
- 最低系统:iOS 17.0
- Bundle ID:`com.qft.transfer`(按需改 `generate_xcodeproj.py` 里的常量)
## 隔空投送式点对点传输
`PeerLink` 用 `Network.framework` 并打开 `includePeerToPeer`。底层就是
AirDrop 用的那条链路——BLE 发现 + AWDL 点对点 Wi-Fi,两台设备不需要路由器,
也不需要连同一个 Wi-Fi。两端在同一个 Wi-Fi 下时它会自动优先走基础网络。
握手用 **TLS-PSK**:预共享密钥(32 字节)由发送端随机生成并写进二维码,
扫码这个动作本身就完成了带外密钥交换与双向认证。没扫到码的第三方
连上来也过不了 TLS 握手,因此不需要任何证书体系,也不需要配对弹窗。
```
发送方 接收方
选文件 → 算 SHA-256
启动 NWListener(Bonjour: _qft-p2p._tcp)
生成 32 字节 PSK
显示 QFTP2P1 二维码 ──────扫码────→ 解析出 PSK + 服务实例名
NWBrowser 找到实例
←──────── TLS-PSK 握手 ────────→
MANIFEST(JSON) ─────────────────────→ 校验与二维码是否一致
DATA × N ─────────────────────→ 落盘 + 增量 SHA-256
EOF ─────────────────────→
←──────── RESULT(JSON) ──────── 校验通过才 rename
```
**AWDL 是苹果私有链路,Windows 无法参与**,所以与电脑互传仍走局域网 HTTP。
如果现场没有路由器,可行的替代是让 iPhone 开个人热点、电脑连上来。
## 已知的 iOS 平台限制
1. **无法用代码连接指定 Wi-Fi。** Android 端用 `WifiNetworkSpecifier` 自动加入
Windows 的 QFT Direct AP,iOS 对应的 `NEHotspotConfiguration` 需要
HotspotConfiguration entitlement,免费开发者账号拿不到。因此 iOS 端
**不实现 Direct AP 流程**,`PairingProtocol` 在二维码不带可用 endpoint 时
会直接拒绝,而不是给用户一个连不上的假成功。
2. **首次访问局域网会弹权限窗。** 已在 `Info.plist` 声明
`NSLocalNetworkUsageDescription` 与 `NSBonjourServices`。
若用户误点了拒绝,需要去 设置 → 隐私与安全性 → 本地网络 里重新打开。
3. **没有「下载」文件夹。** 收到的文件存在 App 的 Documents/QFT 下,
通过 `UIFileSharingEnabled` + `LSSupportsOpeningDocumentsInPlace`
暴露到「文件」App,也可以在 App 内直接分享出去。
4. **上传块固定 4 MiB。** Android 端按文件大小选 4/8/16 MiB,但 iOS 上
`worker 数 × 块大小` 就是内存峰值,16 MiB × 6 会在旧机型触发 jetsam。
4 MiB × 6 = 24 MiB 峰值,局域网速度下每块的往返开销可以忽略。
## 测试
核心层(协议、发现、上传、下载、P2P 链路)不依赖 UIKit,
可以直接以 macOS 为目标编译运行,**不需要 Xcode,也不需要模拟器**:
```bash
./ios/CoreTests/run.sh
```
也已接入主自检套件(`python scripts/run_all_selftests.py`)。
测试内容:
- `Base64URL` 与三端一致性(含 200 组随机字节往返)
- `QFTPAIR2` / `QFTSEND2` / `QFTP2P1` 解析,含各类畸形输入
- **端点白名单**:二维码是不可信输入,只接受字面量私有 IPv4 + 声明端口。
已覆盖域名、公网地址、`172.32` 边界、非规范八位组、IPv6、带凭据/路径/query 等 11 种拒绝用例
- **与 `MockPCServer.py` 的完整传输**:该 mock 严格复刻 `receiver.rs` / `sender.rs`
的线上语义(路径、header 名、JSON 字段、Range 行为、chunk 长度校验),
因此这组测试就是 Swift 端与 Rust 端的**线格式契约测试**——任何一边改了协议都会红
- **真实 TLS-PSK 握手**下的 P2P 端到端传输,含错误密钥必须被拒
## 目录
```
ios/
QFT.xcodeproj/ 生成的工程(已提交)
QFT/
Info.plist 权限声明、Bonjour 服务、ATS 本地网络例外
App/ SwiftUI 界面 + 相机扫码(需要 Xcode 才能构建)
Core/ 纯 Foundation,可在 macOS 上编译测试
Base64URL.swift
PairingProtocol.swift QFTPAIR2 / QFTSEND2 + 端点白名单
HostDiscovery.swift endpoint 探测 → UDP 广播 → 子网扫描
DownloadClient.swift 流式落盘 + 增量 SHA-256 + Range 续传
UploadClient.swift init/chunk/finish 并行上传
PeerPairing.swift QFTP2P1 配对码
PeerLink.swift TLS-PSK + 分帧的点对点链路
CoreTests/
run.sh 编译并运行(swiftc,无需 Xcode)
main.swift 测试用例
MockPCServer.py 复刻 Windows 端线上语义的假电脑
tools/
generate_xcodeproj.py 工程生成器
```