3e4d5861aa
实测中出现「连接码解析正确但连不上」。诊断结果不是代码问题:两台机器 同在 192.168.8.0/24,ARP 能解析对方 MAC(二层通),但 ICMP 100% 丢包、 TCP 39393 连接超时——典型的对端主机丢包,即 Windows 防火墙拦截入站。 顺带暴露的连带影响:二进制从 qft-windows.exe 改名为 qft-desktop.exe 后, 此前给旧名字放行的防火墙规则对新程序不生效,用户不会想到这一层。 README 已补充放行步骤与排查顺序。 代码侧的三个真实缺陷 1. 连接失败只说「失败」,等于什么都没说。现按 io::ErrorKind 分类: - TimedOut → 包发出去没回应:防火墙 / AP 客户端隔离 / 对方已关闭 - ConnectionRefused → 主机在线但端口没人监听:对方没点「启动接收」 - Host/NetworkUnreachable → 本机没有到该地址的路由 三者成因完全不同,给的建议也必须不同。 2. 配对超时从 10 秒缩到 4 秒。配对只是一次极小的请求,拖到 10 秒 只会让用户以为程序卡死。 3. 配对阶段就显示「正在发送 0%」。此前用 busy 兼作「正在传输」, 导致刚点连接就出现发送进度条。新增独立的 transferring 标志, 进度块只在真正推送文件时出现;配对期间改为显示 spinner 与 「正在建立连接…最多等 4 秒」。 验证:cargo test 32/32。新增两项针对错误分类的用例—— 用 RFC 5737 文档网段 192.0.2.1 触发超时路径,用刚释放的本地端口 触发拒绝路径,分别断言提示里包含对应的排查方向。
221 lines
9.3 KiB
Markdown
221 lines
9.3 KiB
Markdown
# QFT · 超速二维码文件传输 v0.4.7
|
||
|
||
Windows + Android 双向候选版。v0.4 的核心目标不是继续堆“4 码理论吞吐”,而是解决 Android 端实际识别慢的问题:**删除 2×2/4 通道,改成一个大二维码 + 动态 ROI 锁定 + 高频局部解码**。
|
||
|
||
v0.4.7 提供两套互不依赖的传输方式:
|
||
|
||
- **电脑 → 手机(纯光学)**:文件数据只经过 Windows 屏幕 → Android 摄像头;Wi‑Fi、蓝牙、局域网和互联网都不参与文件数据传输。
|
||
- **扫码本地直传(双向)**:Windows 为“手机上传”和“电脑下发”分别生成方向明确的二维码。Android 扫码后连接 QFT 本地网络、通过 UDP/网关/子网探测定位电脑,并按二维码指定方向自动进入选文件上传或接收下载;文件数据不经过外网。
|
||
|
||
### v0.4.7 直传稳定性与并发策略
|
||
|
||
- **双向均使用并行分块**:每个可分块文件以 8 路为目标并发数;分块大小根据文件大小自适应,范围为 **64 KiB–16 MiB**。小于一个最小分块的文件会自然只有一个请求。
|
||
- **手机 → 电脑**:Android 使用 offset 定位的 Parallel v2 上传;Windows 对每块进行定位写入,重复块与完成请求可安全重试,最终以 SHA-256 校验后原子改名。
|
||
- **电脑 → 手机**:Windows 支持精确的 HTTP `Range`(`206 Partial Content`);Android 对未完成块创建多个独立 Range 请求,并用 `.qftpart` 与完成位图恢复中断传输。每块最多重试 5 次,完成后校验 SHA-256 再保存至 `Downloads/QFT`。
|
||
- **连接稳定性**:Windows 监听器保持非阻塞以便及时停止服务,但已连接的文件套接字会切换为带读写超时的阻塞模式,避免 Windows `WSAEWOULDBLOCK (10035)` 造成大文件中途失败。
|
||
|
||
> v0.4.7 已完成协议、图像合成解码、ROI、双向并发传输、UDP 发现、内存预算和关键 Kotlin 源码测试。当前生成环境没有真实 Windows 显示器、Android 相机或 Wi‑Fi Direct 适配器,因此物理 30/45/60 FPS 和真实扫码配网仍需在你的设备上跑 `VERIFY_WINDOWS_HOST.ps1` 后做最终验收;详见 `TEST_REPORT.md`。
|
||
|
||
## v0.5-m1:电脑 ↔ 电脑互传(新增)
|
||
|
||
### Windows 首次运行必须放行防火墙
|
||
|
||
二进制已从 `qft-windows.exe` 改名为 `qft-desktop.exe`,**此前给旧名字放行的
|
||
防火墙规则对新程序不生效**,接收方会表现为「对方能解析连接码但连不上」。
|
||
|
||
管理员 PowerShell:
|
||
|
||
```powershell
|
||
New-NetFirewallRule -DisplayName "QFT Desktop" -Direction Inbound `
|
||
-Program "<完整路径>\qft-desktop.exe" -Action Allow -Profile Private,Domain
|
||
```
|
||
|
||
或在「允许应用通过 Windows Defender 防火墙」里勾选 `qft-desktop.exe` 的**专用网络**。
|
||
|
||
排查顺序:对端 `ping` 不通且 TCP 端口连不上,但 `arp -a` 能看到对方 MAC,
|
||
基本可以判定是对端主机在丢包(防火墙),而不是网络不通。
|
||
|
||
|
||
桌面端目录从 `windows/` 改名为 `desktop/`,crate 更名 `qft-desktop`,
|
||
**现已可在 macOS / Linux / Windows 三平台编译运行**。平台差异全部收敛在
|
||
`desktop/src/platform.rs`(配置目录、下载目录、设备名、Direct AP 能力),
|
||
其余模块不再出现 `#[cfg(target_os)]`。
|
||
|
||
新增两块此前完全缺失的能力:
|
||
|
||
- `desktop/src/client.rs` —— 桌面端的**发起侧**。此前桌面只有服务端,
|
||
`TcpStream::connect` 仅存在于测试中,因此 PC 无法主动连接另一台 PC。
|
||
- `desktop/src/discovery.rs` —— 局域网节点浏览(UDP 广播 `QFTBROWSE3`)。
|
||
既有的 `QFTDISC2` 是「已知令牌找机器」,用于手机扫码之后;
|
||
PC↔PC 没有摄像头,必须先能列出附近有哪些节点。
|
||
|
||
配对方式:接收方启动后显示 **6 位配对码**,发送方搜索到对方后输入该码
|
||
换取会话令牌(`POST /qft/pair`)。6 位约 20 bit 熵,靠严格失败计数兜底——
|
||
错 5 次即作废整个码,需要重新启动接收。
|
||
|
||
已知限制:UDP 广播只覆盖同一广播域,跨网段或开了 AP 隔离的 Wi-Fi
|
||
搜索不到对方,此时在界面上手动输入对方 IP。
|
||
|
||
## v0.4 光学链路改动
|
||
|
||
### 单码替代 4 码
|
||
|
||
4 码已从主链路彻底删除。原因是实际手机相机里,每个 QR 变小后会同时带来:
|
||
|
||
- 每模块像素下降;
|
||
- finder 搜索次数增加;
|
||
- Android 同帧多次 ZXing 解码;
|
||
- 更高的摩尔纹/滚动快门敏感度;
|
||
- Windows 理论 B/s 提升,但 Android “有效新帧/s”可能反而下降。
|
||
|
||
v0.4 把全部屏幕和解码预算投入一个大 QR。
|
||
|
||
### QFT2 + Base45 低密度帧
|
||
|
||
活跃光学协议升级为 `QFT2:`:
|
||
|
||
- 二进制帧仍包含 session / sequence / total / payload / CRC32;
|
||
- 文本层使用 RFC 9285 Base45;
|
||
- Base45 字符集属于 QR 字母数字模式可编码范围;
|
||
- DATA payload 默认 **450 B**;
|
||
- QR 使用 L 级纠错和完整 4-module quiet zone;
|
||
- 合成测试中的 450 B DATA 帧为 **QR-L v15**,旧 QFT1/Base64 480 B 对照约为 v18;
|
||
- 60 显示帧/s 的理论纯 payload 为 `450 × 60 = 27,000 B/s ≈ 26.4 KiB/s`,真实速度取决于相机真实分析 FPS 和有效新帧率。
|
||
|
||
Android 仍保留 QFT1 解析用于旧发送端兼容。
|
||
|
||
## Android 识别优化
|
||
|
||
### Acquire → Lock → Expand → Reacquire
|
||
|
||
扫描器状态机现在是:
|
||
|
||
```text
|
||
搜索大二维码
|
||
↓
|
||
ZXing finder points
|
||
↓
|
||
建立方形 ROI
|
||
↓
|
||
后续只复制/解码 ROI
|
||
↓
|
||
轻微移动:平滑跟随
|
||
↓
|
||
连续 miss:逐级扩大 ROI
|
||
↓
|
||
持续丢失:重新全局搜索
|
||
```
|
||
|
||
Android UI 会实时画出真正使用的锁定区域:
|
||
|
||
- 未锁定:白色搜索角标;
|
||
- 稳定锁定:绿色框 + 外围暗化;
|
||
- 临时 miss:黄色框;
|
||
- 锁定区域随 finder points 平滑移动,减少抖动;
|
||
- 锁定后周期性在 ROI 中心重新触发 AF/AE。
|
||
|
||
### 高频解码热路径
|
||
|
||
- `ImageAnalysis` 固定为 **640×480**;
|
||
- `STRATEGY_KEEP_ONLY_LATEST`,不追赶过时相机帧;
|
||
- Camera2Interop 从后摄实际公布的 AE FPS ranges 里选择最高不超过 60 的范围,并同时应用到 Preview/ImageAnalysis;若 OEM 拒绝该流组合,会自动回退相机默认 FPS,而不是让扫描器启动失败;
|
||
- 单个 `QRCodeReader`,无 4-reader 线程池;
|
||
- 锁定后只复制 Y 平面 ROI;
|
||
- `GrayFrameBuffer` 复用 grow-only `ByteArray`,降低 Android 7/8 GC;
|
||
- 常态使用 `GlobalHistogramBinarizer`;Hybrid 只在周期性 miss 时兜底;
|
||
- 重复显示帧虽然计入“成功解码”,但不再重复送入文件 assembler;UI 单独显示“解码/s”和“新帧/s”。
|
||
|
||
## Windows 光学 UI
|
||
|
||
Windows 光传页面已经改成“二维码优先”:
|
||
|
||
- 左侧控制区 / 右侧二维码区;
|
||
- 中间分隔条可拖动,压缩控制区后 QR 自动变大;
|
||
- “专注二维码”一键收起大部分控制 UI;
|
||
- QR 画面占比可调;
|
||
- FPS 5~60,快捷 30 / 45 / 60;
|
||
- 单个大 QR,NEAREST 纹理采样,避免插值模糊;
|
||
- 1024×1024 预编码画布,使用整数 module 像素和完整静区;
|
||
- 后台 Rayon 并行预编码未来帧,前台只复用一个 GPU TextureHandle。
|
||
|
||
推荐初次真机测试从 **30 FPS** 开始,看 Android 的“新帧/s”,再切 45、60。目标不是 Windows 数字最大,而是 Android **实际新帧/s 最大**。
|
||
|
||
## 扫码本地直传(Android ↔ Windows)
|
||
|
||
v0.3 的稳定性优化继续保留:
|
||
|
||
- QFTPAIR2 紧凑配对 QR;
|
||
- QFT Direct 或当前局域网;
|
||
- Android 10+ `WifiNetworkSpecifier`;Android 7~9 legacy Wi-Fi;
|
||
- 扫码连接后 UDP `QFTDISC2` 快速发现;
|
||
- gateway / endpoint / 当前子网 fallback;
|
||
- HTTP 请求明确绑定扫码建立的 `Network`;
|
||
- 配网请求在传输页持续持有,仅返回首页时释放;短暂网络波动会自动接入新的 `Network`;
|
||
- 手机上传和电脑下发均以 8 路为目标并发数;
|
||
- 64 KiB–16 MiB 自适应分块;
|
||
- 电脑下发使用精确 Range 响应,手机以 `.qftpart` + 位图断点续传;
|
||
- 手机上传使用定位写入和幂等完成确认;
|
||
- Windows positioned writes + `.qftpart` + SHA-256 + 最终 rename。
|
||
|
||
## Android 版本
|
||
|
||
- `minSdk = 24`,即 Android 7.0;
|
||
- Android 7~9:旧 Wi-Fi 与 Downloads 写入兼容;
|
||
- Android 10+:WifiNetworkSpecifier + MediaStore;
|
||
- Android 13+:NEARBY_WIFI_DEVICES 权限。
|
||
|
||
## 构建
|
||
|
||
### Windows
|
||
|
||
```powershell
|
||
cd desktop
|
||
cargo check
|
||
cargo test
|
||
cargo build --release
|
||
cargo run --release
|
||
```
|
||
|
||
### Android
|
||
|
||
JDK 17,compileSdk/targetSdk 35,minSdk 24:
|
||
|
||
```powershell
|
||
cd android
|
||
.\gradlew.bat :app:testDebugUnitTest :app:assembleDebug
|
||
```
|
||
|
||
APK:
|
||
|
||
`android/app/build/outputs/apk/debug/app-debug.apk`
|
||
|
||
## 一键打包
|
||
|
||
脚本只打包 `desktop/` 下的 Rust 桌面端:执行 `cargo test` 和 `cargo build --release`,随后把 Rust 二进制、协议说明和 SHA-256 校验文件收集到带时间戳的 `dist/QFT-Rust-*` 目录并生成压缩包。脚本不检查、下载或调用 Android SDK、Java、Gradle:
|
||
|
||
```bat
|
||
package.bat
|
||
```
|
||
|
||
```bash
|
||
./package.sh
|
||
```
|
||
|
||
## 字体
|
||
|
||
桌面端 UI 优先读取 `desktop/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。
|
||
|
||
## 自动验证
|
||
|
||
```bash
|
||
python scripts/run_all_selftests.py
|
||
```
|
||
|
||
Windows 主机建议直接:
|
||
|
||
```powershell
|
||
.\VERIFY_WINDOWS_HOST.ps1
|
||
```
|
||
|
||
它会继续执行 Rust `cargo check/test/build` 和 Android Gradle 单测/APK 构建。物理相机/屏幕和 Wi‑Fi Direct 项目见 `TEST_REPORT.md`。
|