V0.4.0加入锁定二维码

This commit is contained in:
zhy
2026-08-10 17:09:30 +08:00
parent d885259e2b
commit 241e22abea
34 changed files with 1754 additions and 985 deletions
+67 -65
View File
@@ -1,86 +1,88 @@
# QFT protocol overview · v0.3.0-rc3
# QFT protocol notes — v0.4.0-rc2
## QFT1 — Windows → Android optical stream
## 1. Windows → Android optical: QFT2
Wire text:
Active display text:
`QFT1:<base64url(binary frame)>`
```text
QFT2:<Base45(binary-frame)>
```
Binary frame fields:
Base45 is used because its alphabet fits QR alphanumeric encoding, while Android can consume a normal ZXing `Result.text`. The receiver also keeps legacy `QFT1:<base64url(...)>` parsing for old senders.
- magic `QFT1`
- protocol version
- frame kind: MANIFEST / DATA / END
- session id
- sequence index
- total chunks
- payload length
- payload
- CRC32
### Binary frame
MANIFEST contains file name, file size, chunk size, total chunks, SHA-256 and Windows sender-device name. DATA frames are replayed cyclically; Android de-duplicates chunks and waits for missing chunks in later rounds. No Android→Windows feedback channel is used in optical mode.
```text
magic 4 "QFT2"
version 1 2
kind 1 1=MANIFEST / 2=DATA / 3=END
session 8 u64 BE
sequence 4 u32 BE
total 4 u32 BE
payloadLen 2 u16 BE
payload N
crc32 4 u32 BE over everything before crc32
```
v0.3 defaults: 900-byte DATA payload, 4 QR/page, target up to 60 pages/s.
### MANIFEST payload
## QFTPAIR2 — Android → Windows pairing
```text
fileSize 8 u64 BE
chunkSize 2 u16 BE
sha256 32
fileNameLen 2 u16 BE
fileName N UTF-8
senderLen 2 u16 BE
senderDevice N UTF-8
```
Text:
### Optical parameters in rc2
`QFTPAIR2:<base64url(compact JSON)>`
- one QR per display frame;
- DATA payload: **450 B**;
- QR error correction: L;
- full 4-module quiet zone;
- Windows display target: 5~60 FPS, default 45;
- synthetic representative DATA frame: 722 text chars / QR-L v15;
- theoretical payload at 60 display FPS: 27,000 B/s ≈ 26.4 KiB/s before camera misses/replay.
Compact JSON keys:
Sender continuously loops `MANIFEST → DATA 0..N-1 → END`. Android deduplicates by sequence number and reconstructs once all chunks are present. No reverse ACK/network channel exists for this direction.
- `v`: 2
- `s`: one-time session token
- `n`: Windows device name
- `p`: receiver TCP port
- `e`: local HTTP endpoint hints; Direct AP normally carries one short hint
- `w`: optional `[ssid, passphrase]` for QFT Direct
## 2. Android optical ROI state machine
QFTPAIR1 remains parser-compatible for older QR payloads.
```text
ACQUIRE
center search
occasional full frame
↓ success
LOCKED
copy Y-plane ROI only
GlobalHistogram every frame
sparse Hybrid fallback
↓ finder points
smooth ROI position/size
↓ misses
expand ROI
↓ sustained misses
REACQUIRE
```
Android treats pairing QR as untrusted. HTTP endpoint hints must be literal private/local IPv4 addresses on the advertised port. Every `/qft/*` request must carry the one-time `X-QFT-Token` session value.
The overlay is derived from the same ROI used by the decoder, so the green/yellow box is not decorative—it reflects the actual analysis area.
## Receiver discovery
## 3. Android → Windows pairing
UDP request to port 39392:
`QFTPAIR2` remains the active pairing format from v0.3. It contains local-only session/network metadata. Android validates the pairing endpoint as a literal local/private IPv4 and binds subsequent discovery/upload to the selected local `Network`.
`QFTDISC2:<session>`
Discovery order includes QR hint, UDP `QFTDISC2`, gateway/direct candidates and bounded current-subnet fallback.
Windows response:
## 4. Android → Windows upload
`QFTHERE2:<session>:<tcp_port>`
Parallel v2 flow:
Android combines UDP result with QR hint, the actual connected Wi-Fi gateway, common Windows local addresses and a bounded current-subnet fallback scan.
```text
POST /qft/upload/init
POST /qft/upload/chunk (parallel, offset based)
POST /qft/upload/finish
```
## Parallel v2 upload
### Ping
`GET /qft/ping`
Headers include `X-QFT-Token` and encoded Android device name.
### Init
`POST /qft/upload/init`
Headers include file name, file size and desired chunk size. Android requests 4/8/16 MiB depending on file size; Windows clamps accepted chunks to 1~16 MiB.
Response includes `upload_id`, accepted `chunk_size`, and `total_chunks`.
### Chunk
`POST /qft/upload/chunk/<upload_id>/<index>`
Body is exactly that file range. Up to eight Android workers send distinct chunks concurrently. Windows writes each accepted chunk to the preallocated `.qftpart` file at its deterministic offset.
### Finish
`POST /qft/upload/finish/<upload_id>`
Windows rejects finish while chunks are missing. Once complete it computes SHA-256, renames the temporary file to its final unique name, and returns success.
### Compatibility
`POST /qft/upload` remains the single-stream fallback for old clients or content providers that cannot sustain seekable parallel reads.
Windows preallocates a `.qftpart`, writes chunks at explicit offsets, verifies SHA-256, then renames to the final file. Per-file worker count is capped at 8; chunk size is selected from 4/8/16 MiB by file size.