pigway-frame-flow/docs/REAL_DEVICE_TEST.md

Real device test plan / 单次实机测试计划

Not executed. Explicit owner authorization is required before any write. 只读核对完成后询问：“真实设备只读验收完成，是否允许进行一次真实图片上传与显示测试？”

1. GET Frame Flow device (driver POST /device); record current imageId AND coverId, synced, geometry, model, rotation, timezone, firmware, heartbeat and battery.
2. POST /listImages for metadata only. Record count, current image, sorted IDs, duplicates, name/date/dimensions anomalies. No download-all action.
3. Stop on discrepancy. Missing model fields must be reported as unavailable.
4. Once explicitly authorized, locally render one 1200×1600 test image containing PIGWAY FRAME FLOW TEST and Shanghai timestamp, no private content.
5. Record an operation ID and previous image; one upload only, no write retries.
6. Poll device read-only no more often than 60 seconds, respecting the 20/min budget. Confirm imageId and synced. If sent but response lost, mark UNKNOWN, block writes, reconcile gallery/device; never upload again to guess the outcome.
7. Keep the test image visible at most 1–3 minutes, then restore the recorded artwork with a separate tracked switch operation. Query once more to confirm restored imageId and synced. Record coverId after restoration too.
8. Delete only that known test image after restoration is positively confirmed AND it is not a base/previous/override/current reference. If ambiguous, leave it and report. Never delete art or retry a timed-out delete.
9. Disable real writes again. Report each operation ID/result and remaining test image.

The API cannot set coverId. Restoration guarantees a requested image switch when confirmed, not arbitrary cover metadata restoration. Physical screen refresh has no documented pixel telemetry; visual owner observation supplements cloud synced.

Upload response reconciliation

Before an upload, the service persists its asset ID, exact SHA256/size, filename, existing gallery IDs and timestamp. When the response is lost, read-only queries look for one new image in the upload time window; only an exact downloaded-byte match identifies it. Ambiguous, missing or altered content remains locked for manual review. No upload or switch is replayed by reconciliation.

A proven upload completes the display only when the device reports that exact image and synced=true. If a normal display remains on its previous synced image beyond the sync timeout plus five minutes, two observations at least one minute apart record DISPLAY_NOT_CONFIRMED and unblock future scheduled work. Temporary overrides retain their restore behavior and are not automatically closed as failed. Legacy operations without durable upload evidence require manual acknowledgement; absence from the gallery alone never proves failure.

错误与有限重试

完整错误矩阵、重试边界、持久化恢复状态和人工处理见 KoKonna 恢复策略。自动重试只允许只读请求、连接建立超时或明确限流拒绝；读取超时等未知写入不会重发。