feat(desktop): 跨平台桌面端 + 电脑↔电脑互传(v0.5.0-m1)

对应 V05_EXECUTION_PLAN 的 P1。核心改动是把「PC 只能当服务端」
这个写死的角色拆开——此前 TcpStream::connect 只出现在测试里,
桌面端根本无法主动连接另一台桌面端,PC↔PC 因此完全不可用。

跨平台
- windows/ → desktop/,crate 更名 qft-desktop
- 新增 platform.rs 收敛全部平台差异:配置目录(LOCALAPPDATA /
  Application Support / XDG)、下载目录(含 Linux 本地化的 ~/下载)、
  设备名、Direct AP 能力。约定:其余模块不得再出现 #[cfg(target_os)]
- direct_ap.rs 的 Context 导入按平台条件化,非 Windows 上不再告警
- macOS 上已实测编译并链接出可执行文件(65 MB Mach-O arm64),
  这是本仓库首次在非 Windows 平台构建成功

电脑 ↔ 电脑
- 新增 client.rs:桌面端发起侧。手写 HTTP,不引入客户端依赖——
  服务端本来就是手写的,两边同一套解析更容易与 Android/iOS 对齐。
  含并发分块上传(自适应 4/8/16 MiB、最多 8 worker)与 Range 断点续传
- 新增 discovery.rs:UDP 广播 QFTBROWSE3 浏览局域网节点。
  既有的 QFTDISC2 是「已知令牌找机器」,用于扫码之后;
  PC 没有摄像头,必须先能列出附近有谁
- receiver.rs 新增 POST /qft/pair:用 6 位配对码换会话令牌。
  这是唯一不校验令牌的端点。6 位仅约 20 bit 熵,配严格失败计数兜底——
  错 5 次即作废,需重启接收;比较用定长实现,不做短路返回
- 新增「电脑 ↔ 电脑」界面:接收方显示配对码与本机地址;
  发送方搜索/手动输入地址 → 输码连接 → 多选文件 → 带进度发送

验证(macOS,Rust 1.97.1)
- cargo check 0 错误,cargo test 17/17 通过
- 新增端到端用例:真实起接收服务 → 配对(含错误码必须被拒)→
  9 MB 跨多分块并发上传 → 校验落盘内容逐字节一致且 SHA-256 与
  接收端返回值相同。这就是 PC↔PC 的完整链路
- 11 项 Python 自检全部通过

顺带修复
- single_channel_guard_selftest 长期为红:它断言
  DEFAULT_CHUNK_SIZE = 450,而代码早已改为 320。改名前即存在,
  已用 git stash 验证与本次无关。改为范围检查(128~4096)并在
  PASS 信息里打印实际值,既挡住"退回多通道小块"又不会因调参误报

已知限制
- UDP 广播只覆盖同一广播域。跨网段或 AP 隔离的 Wi-Fi 上搜索不到,
  需手动输入对方 IP(界面已说明)。mDNS 留待后续
- 本阶段仍走 v2 明文 HTTP,加密随 QFT-Stream v3 一起做(见 P2)
This commit is contained in:
zhy200308
2026-08-11 16:36:33 +08:00
parent a960ad91d8
commit 376ffba96e
26 changed files with 2139 additions and 44 deletions
+25 -3
View File
@@ -16,6 +16,28 @@ v0.4.7 提供两套互不依赖的传输方式:
> 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/` 改名为 `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 码
@@ -129,7 +151,7 @@ v0.3 的稳定性优化继续保留:
### Windows
```powershell
cd windows
cd desktop
cargo check
cargo test
cargo build --release
@@ -151,7 +173,7 @@ APK:
## 一键打包
脚本只打包 `windows/` 下的 Rust 桌面端:执行 `cargo test` 和 `cargo build --release`,随后把 Rust 二进制、协议说明和 SHA-256 校验文件收集到带时间戳的 `dist/QFT-Rust-*` 目录并生成压缩包。脚本不检查、下载或调用 Android SDK、Java、Gradle:
脚本只打包 `desktop/` 下的 Rust 桌面端:执行 `cargo test` 和 `cargo build --release`,随后把 Rust 二进制、协议说明和 SHA-256 校验文件收集到带时间戳的 `dist/QFT-Rust-*` 目录并生成压缩包。脚本不检查、下载或调用 Android SDK、Java、Gradle:
```bat
package.bat
@@ -163,7 +185,7 @@ package.bat
## 字体
Windows UI 优先读取 `windows/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。
桌面端 UI 优先读取 `desktop/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。
## 自动验证