zijunchiang
7ebbaef631
契约 websocket-keypoints 0.1.0 -> 0.2.0（向后兼容，子协议名与帧 version 不变；
先在 opendance-web 修改并提升版本，再同步三端快照）。
T-AND-011：连接状态异常、频繁重连（查实 3 个根因）
1. 保活用错了层：Windows 端有 5s 静默超时（只看应用层收到的帧），而本端只有
OkHttp 的协议层 ping —— 它由底层库自动应答、**不暴露给应用层**，根本不能续命。
画面里没人时 5s 必被踢、再重连，循环往复。
- 契约新增 §1.1（welcome/config 声明 silentTimeoutMs 与 heartbeatIntervalMs，
且心跳必须 < 静默超时的一半）与 §3.6（应用层 ping/pong）；
- Windows 端超时 5s -> 15s、期望心跳 5s，并在 welcome/config 中下发；
- 本端按声明发 ping，连续 3 个周期无 pong 才判定链路已死并主动重连。
2. 不该重连时也重连：契约新增 §7 关闭码策略，1000/1001/1002 与主动停止一律不重连。
3. frame_id 恒为 0：PoseDetector.detect() 算了 safeTimestamp 却忘了写回
lastTimestampMs，接收端的丢包检测因此完全失效。已修。
其他对齐：
- 契约新增 §8 连接状态机 idle -> resolving -> connecting -> handshaking ->
streaming -> degraded -> reconnecting -> stopped，两端同名便于对照日志；
resolving 只对主机名生效，局域网直连 IP 直接进 connecting；
- 退避与抖动按 §7.1 冻结：0.5s -> 1 -> 2 -> 4 -> 8 -> 15s 封顶 + ±20% 抖动；
- 契约新增 §5 设备去重：hello 携带稳定 deviceId（ANDROID_ID 的 SHA-256 前 16 位，
不含硬件序列号），Windows 端据此去重、旧连接以 1000 关闭；
- 新增 util/ConnectionLog（环形缓冲，最近 500 条：状态迁移 / close code /
子协议协商 / 首帧时间 / 保活参数），运行页可一键导出（FileProvider）。
T-AND-012：MediaPipe 初始化崩溃（ExceptionInInitializerError: null）
- 诊断：新增 pose/PoseDiagnostics 展开 cause 链取真因（通常 UnsatisfiedLinkError）、
区分 native 加载失败、比对设备 ABI 与 APK 内 ABI 并给出可执行结论；
- native 解压：packaging { jniLibs { useLegacyPackaging = true } }（AGP 8 release
默认 extractNativeLibs=false，MediaPipe JNI 对它不兼容）；
- R8：补 -keepclasseswithmembernames 的 native 方法保留规则，并 -printseeds 输出
seeds 供发布前核对（实测保留 20169 条 MediaPipe 条目）；
- 构建期新增 verifyReleaseAbi：release ABI 必须恰为 arm64-v8a/armeabi-v7a、
每个 ABI 下必须有 MediaPipe native 库、模型资源必须存在；
- 未换库：诊断指向集成配置而非 MediaPipe 本身，保留 33 点契约零成本。
T-AND-010：版本号展示与单一来源
- 版本唯一来源 versionName（= project.yaml 的 version）；versionCode 按
10000*主+100*次+修订 递增（0.2.0 -> 200）；
- 契约版本改为构建期解析 contracts/VERSION 后注入 BuildConfig（六项各自独立
递增，原先的单个 CONTRACT_VERSION 常量已失真）；界面不再手写任何版本号；
- 新增 checkReleaseConsistency 并挂到 preBuild，三者不一致直接 BUILD FAILED。
README/DSH/THIRD_PARTY/tasks 同步更新（含「导出连接日志」「保活参数」
「最近断开原因」等新增可观察项与排查表）。
测试：56 项全部通过（新增 ReconnectPolicyTest 11 项、PoseDiagnosticsTest 12 项）；
build/verify.sh 全通过（单元测试 -> 构建 -> 签名/ABI/native/seeds/dex 校验）
89 lines
2.6 KiB
YAML
89 lines
2.6 KiB
YAML
project: opendance-android-app
|
||
version: 0.2.0
|
||
repository: opendance-android
|
||
default_branch: main
|
||
platform: Android 10+（minSdk 29 / targetSdk 34）
|
||
contracts_version:
|
||
rest-api: 0.5.0
|
||
websocket-keypoints: 0.2.0
|
||
data-models: 0.7.0
|
||
skeleton-topology: 0.2.0
|
||
model-formats: 0.5.0
|
||
database: 0.4.0
|
||
|
||
# 契约变更流程（文档 7.2）：
|
||
# 任何跨端契约变更必须先在 opendance-web 修改 contracts/ 并提升版本，
|
||
# 再在本项目创建适配任务。本项目内的 contracts/ 只是只读快照。
|
||
|
||
dependencies:
|
||
- name: opendance-windows
|
||
kind: websocket-producer
|
||
contract: contracts/websocket-keypoints.md
|
||
usage: 本端为**发送方**，主动连接 Windows 客户端的 ws://<host>:8765/pose
|
||
- name: opendance-web
|
||
kind: contract-source
|
||
contract: contracts/skeleton-topology.md
|
||
usage: 33 点索引顺序与坐标语义（MediaPipe 原生顺序即契约顺序）
|
||
|
||
tasks:
|
||
- id: T-AND-001
|
||
file: tasks/001-scaffold.md
|
||
scope: Android Studio 项目骨架
|
||
status: done
|
||
- id: T-AND-002
|
||
file: tasks/002-camera-x.md
|
||
scope: CameraX 采集
|
||
status: done
|
||
- id: T-AND-003
|
||
file: tasks/003-mediapipe-pose.md
|
||
scope: MediaPipe Pose 端侧推理
|
||
status: done
|
||
- id: T-AND-004
|
||
file: tasks/004-keypoint-serializer.md
|
||
scope: 33 点 -> 239 字节帧
|
||
status: done
|
||
- id: T-AND-005
|
||
file: tasks/005-websocket-client.md
|
||
scope: WebSocket 推流 + 自动重连
|
||
status: done
|
||
- id: T-AND-006
|
||
file: tasks/006-connect-ui.md
|
||
scope: 连接页 + 主机发现
|
||
status: done
|
||
- id: T-AND-007
|
||
file: tasks/007-running-ui.md
|
||
scope: 运行页 + 状态指示
|
||
status: done
|
||
- id: T-AND-008
|
||
file: tasks/008-about-page.md
|
||
scope: 关于页 + 开源声明
|
||
status: done
|
||
- id: T-AND-009
|
||
file: tasks/009-build-apk.md
|
||
scope: Android Studio 打包
|
||
status: done
|
||
- id: T-AND-010
|
||
file: tasks/010-about-version.md
|
||
scope: 「关于」清单展示当前版本号 + 契约版本单一来源
|
||
status: done
|
||
- id: T-AND-011
|
||
file: tasks/011-reconnect.md
|
||
scope: 连接状态机 / 保活 / 去重与 Windows 端对齐
|
||
status: done
|
||
- id: T-AND-012
|
||
file: tasks/012-mediapipe-crash.md
|
||
scope: MediaPipe 初始化崩溃修复 + 诊断
|
||
status: done
|
||
|
||
deliverable:
|
||
artifact: opendance-android-v0.2.0.apk
|
||
packaging: Gradle 命令行 / Android Studio
|
||
includes:
|
||
- app-release.apk
|
||
- THIRD_PARTY.md
|
||
- README.txt
|
||
- contracts/ # 契约快照
|
||
release_rules:
|
||
- release 包只含 arm64-v8a / armeabi-v7a（真机 ABI）
|
||
- 版本号单一来源：versionName（= project.yaml 的 version）与 BuildConfig 契约版本
|