Files
QFT/README.md
T
zhy200308 0f0dbaef47 fix(desktop): 防火墙提权改为手动触发;构建前检测占用;清理警告
三个问题一起处理。

1. 提权改为手动
上一版会在点「启动接收」时自动弹 UAC。实际用下来太侵入——多数人
只是想收个文件,却先被要求管理员授权。现在:
- 检测保持自动,但**只读**,无任何副作用
- 提权只在用户点「放行防火墙(需要管理员授权)」时发生
- 按钮无条件保留,不再只在"检测到被拦"时出现:检测可能不准,
  而用户遇到「对方连不上」时需要有地方可点
- 同时移除了拒绝标记的持久化——提权已不自动发生,无需记忆

2. Windows 构建报 os error 5
  error: failed to remove file `...\target\release\qft-desktop.exe`
  Caused by: 拒绝访问。 (os error 5)
原因是 QFT 窗口还开着,运行中的 exe 锁住了产物文件,而 cargo 的报错
完全看不出这一层。VERIFY_WINDOWS_HOST.ps1 现在会在构建前检测
qft-desktop 进程,列出 PID 并询问是否结束;README 也补了说明
(含 Defender 扫描导致的偶发同类报错)。

3. 构建警告 15 → 5
长期堆积的警告会训练人忽略所有警告,所以逐条处理:
- 真实问题:if 条件多余的括号,已修
- 为后续里程碑准备但尚未接线的 API(client::ping、download_file、
  platform::direct_ap_support/ensure_dir),加 #[allow(dead_code)]
  并注明将在哪个阶段使用
- 仅特定平台构造的项(firewall::RULE_NAME 只用于 Windows,
  FirewallStatus::Unsupported 只在 Linux 返回),改用
  #[cfg_attr(not(...), allow(dead_code))],避免无条件放行
剩余 5 个均为本次改动之前既有(cache_mib、v/transport、security、
path),不属本次范围,未改动。

验证:cargo test 35/35,release 构建 5 个警告且全部是既有的。
2026-08-11 18:28:43 +08:00

242 lines
10 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.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 构建报 `os error 5 拒绝访问`
```
error: failed to remove file `...\target\release\qft-desktop.exe`
Caused by: 拒绝访问。 (os error 5)
```
**QFT 窗口还开着**,正在运行的 exe 锁住了产物文件。关掉窗口再构建即可。
`VERIFY_WINDOWS_HOST.ps1` 会在构建前检测并询问是否结束进程。
若关掉后仍然报错,通常是 Windows Defender 正在扫描刚生成的 exe,
稍等几秒重试;也可以把 `desktop\target` 加入 Defender 排除目录。
### 防火墙放行(手动)
接收端要监听入站 TCP,Windows 防火墙默认会拦截未授权程序,表现是
「对方能解析连接码但连接一直超时」。
程序在「电脑 ↔ 电脑 → 我要接收」页会**只读检测**防火墙状态,并提供
「放行防火墙(需要管理员授权)」按钮——**提权只在你点击时发生**,
不会在启动时自动弹 UAC。
也可以自己加规则。注意二进制已从 `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`。