Files
QFT/docs/V05_EXECUTION_PLAN.md
zhy200308 376ffba96e 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)
2026-08-11 16:36:33 +08:00

220 lines
9.8 KiB
Markdown
Raw Permalink 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.5 执行计划
配套设计文档:[V05_MULTIPEER_PLAN.md](V05_MULTIPEER_PLAN.md)
---
## 0. 三个默认决策(未经确认,可推翻)
设计文档结尾留了三个待定问题,为了让计划能往下排,先按以下默认执行。任一项改变都会影响排期,改之前先说。
| 问题 | 默认决策 | 理由 |
|---|---|---|
| M1 先做还是直接上 v3? | **M1 先做** | 零协议风险,做完立刻拿到真实 PC↔PC 体验;v3 的很多设计细节需要真实使用反馈才定得准 |
| 加密在哪一版做? | **放到 v3(P2),M1 维持现状明文** | TLS 与新协议一起做只需改一次握手层;分两次做要动两遍,且 M1 的目的是尽快验证对称节点模型 |
| 共享核心怎么做? | **桌面共享 Rust + 移动端原生 + `conformance/` 一致性套件** | 桌面三平台本来就是同一份代码(实测仅 3 处平台耦合),共享零成本;移动端 FFI 要等 v3 定型才划算 |
---
## 1. 总体流程
```mermaid
flowchart TD
P0["P0 收尾验证<br/>把半成品编译掉"] --> P1["P1 桌面跨平台 + PC↔PC<br/>走现有 v2 协议"]
P1 --> P2["P2 QFT-Stream v3<br/>目录直传 + 加密"]
P2 --> P3["P3 移动端接入 v3"]
P3 --> P4["P4 手机 ↔ 手机"]
P2 -.并行.-> P5["P5 一致性套件<br/>+ 性能回归"]
P0 -.独立并行轨.-> OPT["QFT5 光学<br/>阻塞于楔形标定"]
style P0 fill:#7a2020,color:#fff
style OPT fill:#5a4a20,color:#fff
```
**P0 是硬阻塞。** 当前有三处「写了但没验证」的代码,在其之上继续叠加会让问题定位成本指数上升。
---
## 2. P0 · 收尾验证(阻塞,必须先做)
| # | 任务 | 涉及 | 验收标准 | 谁做 |
|---|---|---|---|---|
| P0.1 | Android bug 修复编译 | `DownloadClient.kt` `WifiConnector.kt` `MainActivity.kt` | `./gradlew :app:assembleDebug` 通过 | **你**(我没有 Android SDK) |
| P0.2 | Android bug 修复实测 | — | 大文件传输走完全程;断网时 3 秒内报「临时网络已断开」而非等满重试;空间不足在开始前就提示 | **你**(需真机 + Windows 主机) |
| P0.3 | iOS 模拟器编译 | `ios/QFT/App/*.swift` | Xcode 选 iPhone 模拟器,⌘B 无红色错误 | **你** |
| P0.4 | `xcode-select` 指向 Xcode | — | `xcodebuild -version` 可用 | **你**(需 sudo) |
| P0.5 | 修掉 P0.1/P0.3 暴露的编译错误 | 视情况 | 同上重跑通过 | 我 |
| P0.6 | 提交并推送 | — | 工作区干净 | 我 |
**门禁:P0.1 与 P0.3 全绿才进入 P1。**
P0.4 做完之后我可以直接在命令行编译 iOS 工程,后续 Swift 改动就不再是盲写——这一项虽然可选,但会显著提升后面所有 iOS 相关工作的质量。
---
## 3. P1 · 桌面跨平台 + PC↔PC
目标:**mac ↔ win、linux ↔ win 能互传单个文件**,仍走现有 v2 HTTP 协议。
| # | 任务 | 涉及 | 规模 | 验收标准 |
|---|---|---|---|---|
| P1.1 | `windows/` → `desktop/`,crate 更名 `qft-desktop` | 目录 + `Cargo.toml` + CI 脚本 + `VERIFY_WINDOWS_HOST.ps1` | S | `cargo check` 在 macOS 上通过 |
| P1.2 | 平台抽象层 `platform.rs` | 新增;改 `direct_ap.rs` `pairing.rs:148` `protocol.rs:194` | M | 三平台各自 `cargo test` 通过 |
| P1.3 | 配置/下载目录跨平台 | `pairing.rs` + 新增 | S | mac 写到 `~/Library/Application Support/QFT`,linux 写到 `$XDG_CONFIG_HOME/qft` |
| P1.4 | **桌面客户端** `client.rs` | 新增(当前完全缺失) | L | 单元测试:对本进程起的 receiver 完成一次上传 + 一次下载 |
| P1.5 | mDNS 发现 `discovery.rs` | 新增,`mdns-sd` crate | M | 两台机器互相出现在列表里;TXT 含 `v/id/name/platform/port` |
| P1.6 | 6 位配对码 | `pairing.rs` | M | 跨网段场景下输码可连;错码 3 次锁定 |
| P1.7 | UI:「附近的设备」页 + 拖拽发送 | `main.rs` | L | 拖文件到窗口即发送 |
| P1.8 | macOS / Linux 打包 | 新增 CI | M | 产出 `.app`(未签名)与 AppImage/tar.gz |
### P1 验收门
```
✅ mac → win 传 1GB 单文件,SHA-256 一致
✅ win → mac 同上
✅ linux → win 同上
✅ 三平台各自能在「附近的设备」里看到另外两台
✅ 拔网线重插后能续传(v2 的 Range 续传)
```
**这一门通过之前不进 P2。** 因为 v3 的价值全部建立在「对称节点模型成立」之上,先用最简单的协议把这个模型验证掉。
---
## 4. P2 · QFT-Stream v3
目标:**目录直传可用**,先只在两台 PC 之间。
| # | 任务 | 规模 | 验收标准 |
|---|---|---|---|
| P2.1 | 帧编解码 + 黄金测试向量 | M | 向量文件 `conformance/frames.json`,编解码往返一致 |
| P2.2 | Ed25519 身份 + 信任库 | M | 首次运行生成密钥;重启后身份不变 |
| P2.3 | TLS 1.3(`rustls`)+ 按公钥验证对端 | L | 错误公钥必须握手失败;6 位校验码两端一致 |
| P2.4 | 会话层:`SESSION_OPEN` / `INDEX_*` / `HAVE` | L | 断开重连后不重传已完成文件 |
| P2.5 | **流式并行索引** | M | 10 万文件树:首字节传输在遍历完成前就开始 |
| P2.6 | **小文件合批** | L | 见下方性能门 |
| P2.7 | 大文件分块并发 + 流控反压 | M | 接收端磁盘限速时内存不超过 `连接数 × 8MiB` |
| P2.8 | 路径安全层 | M | 见下方安全门 |
| P2.9 | 每文件 SHA-256 + 单遍哈希 | S | 单个坏文件只重传自己 |
### P2 性能门(在千兆有线上实测)
| 场景 | 目标 | 现状对照 |
|---|---|---|
| 5 万小文件 / 0.95 GB | **< 15 s** | v2 约 608 s |
| 3 千文件 / 11.7 GB | < 120 s | v2 约 138 s |
| 单文件 10 GB | < 95 s | v2 约 87 s(不得退化) |
| 峰值内存 | < 200 MB | — |
### P2 安全门(跨系统路径用例,全部必须通过)
```
linux → win : 目录含 CON.txt / aux.log / "a<b>.txt" / 结尾带空格的名字
linux → win : 同目录下 README.md 与 readme.md(大小写冲突)
linux → mac : 文件名含 "é"(NFC/NFD 归一化)
任意 → 任意 : 路径含 ../、绝对路径、指向根目录外的符号链接 → 整会话拒绝
win → 任意 : 路径长度超过 260
```
每条都要有自动化用例,不能靠手测。
---
## 5. P3 · 移动端接入 v3
| # | 任务 | 端 | 规模 |
|---|---|---|---|
| P3.1 | Android `NodeServer.kt`(ServerSocket + v3 帧) | Android | L |
| P3.2 | Android `NsdManager` 发现 | Android | M |
| P3.3 | Android 前台服务 + WakeLock | Android | M |
| P3.4 | Android 目录接收(SAF `OPEN_DOCUMENT_TREE`) | Android | M |
| P3.5 | iOS `PeerLink` 并入 v3 帧格式 | iOS | M |
| P3.6 | iOS 目录接收 + 「文件」App 导出 | iOS | M |
**门禁:手机 ↔ 电脑走 v3 传一个 5000 文件的目录成功。**
P3.3 是现有隐患的正式修复——当前只有 `FLAG_KEEP_SCREEN_ON`,息屏或切后台就有被系统掐断的风险。
---
## 6. P4 · 手机 ↔ 手机
| 组合 | 任务 | 备注 |
|---|---|---|
| iOS ↔ iOS | 已实现,接 v3 即可 | `PeerLink.swift` 复用 |
| Android ↔ Android | `WifiP2pManager` 或 Local Only Hotspot,回落同 LAN | 新增 |
| Android ↔ iOS | **仅同一局域网** | UI 必须明确提示,不给假希望 |
**门禁:三种组合各传一个含子目录的相册目录成功。**
---
## 7. P5 · 一致性套件(与 P2 并行)
把 `ios/CoreTests/MockPCServer.py` 的做法推广成 `conformance/`:
```
conformance/
vectors/ 黄金测试向量(帧编解码、路径规范化、合批边界)
reference_peer.py 参考对端,任一端实现都能对着它跑
run.sh 三端各自跑一遍
```
接入 `scripts/run_all_selftests.py`。**这是目前防三端协议漂移最有效的手段**,在 iOS 端已验证有效。
---
## 8. 验证责任分工
这个项目的返工大多来自「写完没法验证」。明确分工:
| 我能在这台 Mac 上做 | 只有你能做 |
|---|---|
| Rust `cargo check/test`(装了 Rust 之后) | Windows 上的 `cargo build --release` 与真机跑 |
| Swift 核心层编译 + 单测 | iOS 真机(相机、AWDL) |
| Swift 全量编译(**需你先做 P0.4**) | Android 编译与真机 |
| Python 工具与一致性套件 | 千兆有线上的性能实测 |
| 协议设计、黄金向量、代码审查 | 楔形标定拍照 |
**Kotlin 目前我完全无法编译**(本机无 Android SDK,装 kotlinc 会连带拉一个多余的 JDK)。所以 Android 侧改动我会尽量小步、单文件,每次都请你编译一次再继续——不要攒一大批。
---
## 9. 并行轨:QFT5 光学
与 v0.5 无依赖关系,可随时插入。当前**阻塞于楔形标定**:
```
你拍标定图 → 跑 wedge_analyze.py → 得到实测 px/模块
↓
≤3.2 → 按 OPTICAL_V5_PLAN 原样实施
3.2~4.0 → 目标 B 不可达,需下调指标
>4.0 → 先排查对焦/曝光,不要动协议
```
标定之前可以做的(不依赖该数值):相机帧率三级锁定、手动短曝光、关 EIS/抗闪烁、锁对焦、陀螺仪前馈。这几项**对现有 QFT2 链路也立刻有收益**(3px/模块下 33ms 自动曝光会产生 8.7px 运动模糊,等于抹掉近 3 个模块)。
---
## 10. 回滚点与风险
| 阶段 | 回滚点 | 触发条件 |
|---|---|---|
| P1 | 保留 `windows/` 分支 tag | 跨平台抽象破坏了 Windows 行为 |
| P2 | v2 与 v3 并存,节点协商版本 | v3 性能门不达标 |
| P3 | 移动端可继续用 v2 | v3 在移动端内存/耗电不可接受 |
**每个阶段结束打一个 tag**,v3 与 v2 全程并存,任一阶段失败都不影响已发布版本可用。
---
## 11. 下一步
按顺序,现在只需要做三件事:
1. `cd android && ./gradlew :app:assembleDebug` —— 把 bug 修复编译掉,报错发我
2. Xcode 选模拟器 ⌘B —— iOS UI 层编译掉,报错发我
3. (可选但强烈建议)`sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`
这三件完成后我开始 P1.1。