# 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`。