Files
QFT/README.md
T
2026-08-10 15:45:04 +08:00

132 lines
5.8 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 · 超速二维码文件传输 v0.3.0-rc3
Windows + Android 双向候选版。两个方向采用不同链路:
- **Windows → Android:纯光学**。文件数据只经过 Windows 屏幕 → Android 摄像头;不使用 Wi‑Fi、蓝牙、局域网或互联网。
- **Android → Windows:扫码本地直连**。Windows 选择保存目录并启动 QFT Direct 临时 Wi‑Fi/接收服务;Android 扫码后请求配网、自动发现电脑,然后并行分块上传。文件不经过外网。
> rc3 是性能/兼容性候选版。仓库内的协议、二维码、并行上传、UDP 发现、内存预算与 Kotlin 关键源文件测试已通过;真正的 Windows Wi‑Fi Direct 驱动、Windows 防火墙、60Hz 显示器与不同 Android 相机组合仍必须在真实设备上做验收,详见 `TEST_REPORT.md`。
## v0.3.0-rc3 针对性优化
### 1. Windows → Android:最高 60 FPS 显示目标
- Windows UI 支持 `1~60 FPS`,提供 15/30/60 与“极速预设”。
- 默认 **4 QR/页 + 60 FPS**,每次刷新最多承载 4 个独立 QFT1 数据帧。
- 单 QR payload 默认 900 B;理论原始文件载荷约 `900 × 4 × 60 = 216,000 B/s`(约 210.9 KiB/s),实际速度取决于显示器刷新率、Android 相机 FPS、曝光/滚动快门和识别率。
- Android 光学扫描采用 1280×720 分析帧、4 象限并行 ZXing 解码、`KEEP_ONLY_LATEST`、Y 平面直接读取且不再整帧旋转。
- Windows 预编码使用 Rayon 多核并行;GPU 纹理复用,不再每帧创建新的纹理对象。
- UI 动态显示目标 FPS、实际页面 FPS、理论载荷和 Android 实际“相机 FPS / 有效 QR/s”。
### 2. 文件与内存优化
- Windows 光学源文件不做整文件 mmap;使用定位读取,避免大文件被整体映射/触碰进工作集。
- 预编码缓存硬设计目标:整进程约 **≤ 1100 MiB**。
- 4 QR / 960px 模式缓存最多 192 页,估算约 **675 MiB**;另为 UI、WGPU/GPU staging、线程栈、二维码临时对象和系统 I/O 留出余量。
- Android → Windows 每个文件内部最高 **8 路并行**。
- 分块根据文件大小自适应:小文件 4 MiB、中型 8 MiB、大文件 16 MiB;每个 worker 仅使用约 1 MiB 应用层 I/O buffer。
- Windows 端预分配 `.qftpart`,多个独立文件句柄按 offset 写入,完成后 SHA-256 校验并原子改名。
### 3. Android → Windows:连接速度/稳定性
扫码二维码升级到更短的 `QFTPAIR2`:
- 短字段 JSON + Base64URL。
- 配对 QR 使用中等级纠错,候选测试为 QR version 10。
- QFT Direct 二维码携带一个快速 endpoint hint,同时保留真实 Wi‑Fi 网关、UDP 发现与当前子网扫描作为 fallback。
- Android 配对扫描分辨率降到 640×480,优先 GlobalHistogram 快速路径;失败才周期性使用 HybridBinarizer。
- Android 连接 Wi‑Fi 后不立即假定网络可用,而是等待真实 IPv4/route。
- 电脑发现顺序:
1. QR endpoint hint;
2. `QFTDISC2` UDP 发现;
3. Android 真实 Wi‑Fi gateway;
4. 常见 Windows Direct 地址;
5. 当前实际子网最多 /24 的并发 fallback 扫描。
- 所有 HTTP 请求绑定到扫码建立的 `Network`,避免手机 4G/5G/其他 Wi‑Fi 抢路由。
- Android Manifest 同时启用 local cleartext network security config;QFTPAIR 解析器仍只允许 literal private/local IPv4 + 本次 session token。
### 4. Android 7 → 最新
- `minSdk = 24`(Android 7.0)。
- Android 10+:`WifiNetworkSpecifier` local-only 配网。
- Android 7~9:`WifiManager/WifiConfiguration` 兼容路径。
- Android 13+:`NEARBY_WIFI_DEVICES`。
- Android 7~12:位置权限兼容。
- Android 7~9 光学保存:`WRITE_EXTERNAL_STORAGE` + `Downloads/QFT`。
- Android 10+ 光学保存:MediaStore Downloads。
## Windows → Android 使用
1. Windows:进入 `电脑 → Android`。
2. 选择文件。
3. 建议先用 `30 FPS / 4 码` 验证,再切 `60 FPS / 4 码`。
4. Android:`电脑 → 手机 → 开始光学接收`。
5. 让 2×2 QR 区域尽量完整占据手机取景框。
6. Android UI 会实时显示相机分析 FPS 和有效 QR/s;若识别偏低,靠近屏幕或把 Windows 降为 30 FPS。
7. 收齐后自动 SHA-256 校验并保存。
## Android → Windows 使用
1. Windows:`Android → 电脑`。
2. 选择接收文件夹。
3. 默认选择 `QFT Direct`。
4. 点击“启动接收并生成二维码”。
5. Windows 保持该页面开启。若 Windows Defender Firewall 首次询问网络访问,请允许 QFT 访问**专用网络**。
6. Android:`手机 → 电脑 → 扫码连接电脑`。
7. 首次连接具体 QFT Direct AP 时,Android 系统可能要求确认该本地 Wi‑Fi。
8. App 自动完成 endpoint/UDP/gateway/subnet 发现,出现“已连接电脑”后选择文件并开始传输。
如果电脑没有可用 Wi‑Fi Direct 适配器,可切换 Windows 的“当前局域网”备用模式。
## 构建
### Windows
需要 Rust stable MSVC + Visual C++ Build Tools / Windows SDK。
```powershell
cd windows
cargo check
cargo build --release
cargo run --release
```
### Android
当前构建栈:compileSdk/targetSdk 35、minSdk 24、JDK 17。
```powershell
cd android
.\gradlew.bat :app:testDebugUnitTest :app:assembleDebug
```
APK:
`android/app/build/outputs/apk/debug/app-debug.apk`
## 字体
Windows UI 优先读取:
`windows/assets/qft-ui.ttf`
也可设置 `QFT_FONT_PATH` 指向支持中文的 TTF。项目不会分发第三方字体文件。
## 验证
开发侧测试:
```bash
python scripts/run_all_selftests.py
python scripts/optical_image_decode_selftest.py
python scripts/local_transfer_integration_selftest.py
```
Windows 真机环境可运行根目录:
```powershell
.\VERIFY_WINDOWS_HOST.ps1
```
详细结果与尚未能在当前生成环境自动验证的硬件项目见 `TEST_REPORT.md`。