# 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 收尾验证
把半成品编译掉"] --> P1["P1 桌面跨平台 + PC↔PC
走现有 v2 协议"] P1 --> P2["P2 QFT-Stream v3
目录直传 + 加密"] P2 --> P3["P3 移动端接入 v3"] P3 --> P4["P4 手机 ↔ 手机"] P2 -.并行.-> P5["P5 一致性套件
+ 性能回归"] P0 -.独立并行轨.-> OPT["QFT5 光学
阻塞于楔形标定"] 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.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。