# T-AND-011 连接状态与重连修复

- **状态**: done
- **依赖**: T-AND-005、T-AND-006
- **文档**: v1.6 §6.5；契约 `websocket-keypoints` **0.2.0**（本次提升）

## 问题

「连接状态异常、频繁重连」。逐条核对原实现后，找到 **3 个真实根因**，
都不是"退避参数没调好"这种表象问题：

### 根因 1：保活用错了层（最要命）

- 服务端（Windows `pose_server.gd`）有 `CLIENT_TIMEOUT_MS = 5000` 的**静默超时**：
  5 秒内没有收到**应用层**的数据帧或文本帧就 `close(1001, "timeout")`；
- App 端只有 OkHttp 的 `pingInterval = 15s`。**WebSocket 协议层的 ping 由底层库
  自动应答，不会暴露给接收端的应用层** —— 也就是说它根本不能续命；
- 结果：只要画面里没有人（或相机暂停）而 `stats` 又没发出去，5 秒后必然被踢，
  然后重连，循环往复 —— 这就是"频繁重连"。

**修复（两端一起改）**：

- 契约新增 §1.1：接收端必须在 `welcome`/`config` 中声明 `silentTimeoutMs` 与
  `heartbeatIntervalMs`，且 **`heartbeatIntervalMs < silentTimeoutMs / 2`**；
- 新增 §3.6 应用层 `ping` / `pong`（协议层 ping 不可见，必须自己定义）；
- Windows 端超时从 5s 提到 **15s**、期望心跳 **5s**，并在 `welcome`/`config` 中下发；
- App 端按声明值周期发 `ping`，连续 3 个周期没收到 `pong` 才判定链路已死
  并主动重连（而不是干等）。

### 根因 2：不该重连的时候也重连

原 `scheduleReconnect()` 只看 `manualClose`：服务端因重启发的 `1001`、
协议不匹配的 `1002`、乃至收到 `bye` 之后的正常 `1000`，都会触发重连。

**修复**：契约新增 §7 关闭码策略，App 用 `ReconnectPolicy.shouldReconnect()` 判定 ——
`1000` / `1001` / `1002` 与主动停止一律**不**重连。

### 根因 3：frame_id 恒为 0

`PoseDetector.detect()` 计算出 `safeTimestamp` 后**忘了写回 `lastTimestampMs`**，
于是 `handleResult()` 里 `frameId = lastTimestampMs and 0x7FFFFFFF` 永远是 0 ——
接收端据此做的丢包检测完全失效，`frames_dropped` 恒为 0。顺带修掉。

## 其他对齐项

| 项 | 做法 |
|--|--|
| 状态机同名 | 契约新增 §8：`idle → resolving → connecting → handshaking → streaming → degraded → reconnecting → stopped`；App 的 `State` 枚举带 `wireName`，Windows 端 `PoseServer.ClientState` 同名，日志可直接对照 |
| resolving | 主机名不是 IP 字面量时先解析（`InetAddress`），局域网直连 IP 直接进 connecting |
| 退避与抖动 | 契约新增 §7.1 冻结：0.5s→1→2→4→8→15s 封顶 + **±20% 抖动**（避免同网段多机同时重连打尖峰） |
| 设备去重 | 契约新增 §5：hello 携带稳定 `deviceId`（`ANDROID_ID` 的 SHA-256 前 16 位，**不含硬件序列号**）；Windows 端按它去重，旧连接以 `1000` 关闭（旧连接不重连），设备数按去重后计数 |
| 可诊断 | 新增 `ConnectionLog`（进程内环形缓冲，最近 500 条）：状态迁移、close code/reason、子协议协商结果、首帧时间、保活参数；运行页「导出连接日志」经 FileProvider 分享 |
| 界面 | 运行页显示状态机名、协商子协议、最近断开（close code + 中文原因）、保活参数、心跳 RTT、重试倒计时 |

## 契约变更（`websocket-keypoints` 0.1.0 → 0.2.0）

按文档 §7.2，先在 `opendance-web/contracts/websocket-keypoints.md` 修改并提升版本，
再同步本仓库快照（三端逐字节一致）。

**向后兼容**：子协议名与二进制帧 `version` 均不变，只**新增可选**控制字段与
一种新控制类型；仅实现 v0.1.0 的一端仍可互通（它不发 `ping`、不读
`silentTimeoutMs`，但每帧关键点 + 每秒 `stats` 已足够保活）。

## 验收（文档 §6.5）

| 验收项 | 结果 |
|--|--|
| 连续推流 30 分钟不出现非预期重连 | ⚠️ 需真机 30 分钟实测（本环境无设备）；根因 1 已消除，且保活节奏有单测锁定 |
| 首次连接与断网恢复各有明确日志与状态 | ✅ 状态机 + `ConnectionLog`（可导出）；`resolving/connecting/handshaking/streaming` 各有记录 |
| 服务端主动关闭 / 客户端主动停止**不**触发重连 | ✅ 契约 §7 策略 + `ReconnectPolicyTest` 逐码断言 |
| Windows 端设备数与手机端一致（重复连接去重） | ✅ 两端都按 `deviceId` 去重；Windows 端 `test_duplicate_device_id_is_deduplicated` 断言旧连接被 `1000` 关闭且设备数仍为 1 |
| 两端协议（子协议名、帧格式、心跳）与契约一致 | ✅ 契约 0.2.0 已冻结；两端快照 md5 相同 |

## 测试

- `ReconnectPolicyTest`（11 项）：退避序列逐值、抖动上下界、契约 §7 关闭码策略、
  心跳安全性（严格小于静默超时的一半）、越界与非法输入。
- Windows 端 `tests/test_pose_server.gd` 新增 7 项：welcome 声明保活参数、
  ping→pong 回显、同 deviceId 去重、状态名与契约一致、
  状态随握手/首帧推进到 streaming、丢帧进入 degraded 后恢复、
  snapshot 暴露设备数与保活参数。