docs: 新增「初次部署（从零跑起来）」；去混淆字符与真实内网信息
- README.md / README.txt 新增初次部署章节：前置条件（JDK 17 / SDK 34 / Gradle 8.9）、 获取代码与本地配置（local.properties 不入仓）、Debug/Release 构建、装到手机与相机权限、 连接配置（只连 Windows 客户端，默认 8765 / /pose）、第一次跑通、自检清单、常见问题 - 单测数量按实际（30 项）修正 - 三库同源契约：':=' 写法修回、去掉真实 MariaDB 版本串 - 全文去除易被 Gitea 判为「模棱两可 Unicode」的字符 - 本机 JDK 路径与内网示例地址改占位符 / RFC 5737 文档网段
This commit is contained in:
@@ -39,7 +39,7 @@ JDK 17 ／ Gradle 8.9 ／ AGP 8.7.3 ／ Kotlin 2.0.21 ／ Compose BOM 2024.10.01
|
||||
## 验收
|
||||
|
||||
```bash
|
||||
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
|
||||
export JAVA_HOME=<JDK 17 路径>
|
||||
./gradlew assembleDebug
|
||||
```
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
```
|
||||
DSH.md
|
||||
contracts/skeleton-topology.md # 锚点：§1 33 点、§4 坐标系
|
||||
contracts/skeleton-topology.md # 锚点：1 33 点、4 坐标系
|
||||
app/src/main/java/com/opendance/studio/pose/PoseDetector.kt
|
||||
```
|
||||
|
||||
@@ -22,7 +22,7 @@ app/src/main/java/com/opendance/studio/pose/PoseDetector.kt
|
||||
## 关键实现
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
|--|--|
|
||||
| 运行模式 | `LIVE_STREAM` + `detectAsync`，不阻塞相机线程 |
|
||||
| 模型 | `pose_landmarker_lite.task`（随 APK 分发，`noCompress "task"` 保证可读） |
|
||||
| 置信度阈值 | detection / presence / tracking 均 0.5 |
|
||||
@@ -32,7 +32,7 @@ app/src/main/java/com/opendance/studio/pose/PoseDetector.kt
|
||||
|
||||
## 坐标与镜像语义
|
||||
|
||||
- 发送**未镜像的原始 MediaPipe 坐标**（契约 §4）
|
||||
- 发送**未镜像的原始 MediaPipe 坐标**（契约 4）
|
||||
- 是否镜像由帧头 `flags.bit0` 声明，接收端据此决定如何还原
|
||||
- 叠加层绘制时才取 `1 - x`，与前置摄像头预览的镜像观感一致
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# T-AND-004 33 点 → 239 字节帧
|
||||
# T-AND-004 33 点 -> 239 字节帧
|
||||
|
||||
- **状态**：done
|
||||
- **依赖**：T-AND-003（数据结构）、T-AND-001
|
||||
@@ -11,8 +11,8 @@
|
||||
|
||||
```
|
||||
DSH.md
|
||||
contracts/websocket-keypoints.md # 锚点：§2 二进制帧（冻结）
|
||||
contracts/skeleton-topology.md # 锚点：§1 33 点、§4 坐标系
|
||||
contracts/websocket-keypoints.md # 锚点：2 二进制帧（冻结）
|
||||
contracts/skeleton-topology.md # 锚点：1 33 点、4 坐标系
|
||||
app/src/main/java/com/opendance/studio/model/KeypointFrame.kt
|
||||
app/src/main/java/com/opendance/studio/model/SkeletonTopology.kt
|
||||
```
|
||||
@@ -21,7 +21,7 @@ app/src/main/java/com/opendance/studio/model/SkeletonTopology.kt
|
||||
|
||||
```
|
||||
偏移 长度 字段
|
||||
0 2 magic u16 = 0x4F44 ('OD')，小端序 → 字节序为 44 4F
|
||||
0 2 magic u16 = 0x4F44 ('OD')，小端序 -> 字节序为 44 4F
|
||||
2 1 version u8 = 1
|
||||
3 1 flags u8 bit0 镜像 | bit1 低置信度 | bit2 上半身
|
||||
4 4 frame_id u32 LE
|
||||
@@ -44,7 +44,7 @@ const { encodeBinaryFrame } = require('./dist/preprocess/keypoint-codec.js');
|
||||
const points = [], conf = [];
|
||||
for (let i = 0; i < 33; i++) {
|
||||
points.push([(i%33)/32, 1-(i%33)/32, ((i%7)-3)/10]);
|
||||
conf.push(i%2===0 ? 1.0 : 0.5);
|
||||
conf.push(i%2===0? 1.0: 0.5);
|
||||
}
|
||||
const buf = encodeBinaryFrame(42, points.map((p,i)=>[...p,conf[i]]), 0b101);
|
||||
console.log(buf.toString('hex'));
|
||||
@@ -52,7 +52,7 @@ console.log(buf.toString('hex'));
|
||||
```
|
||||
|
||||
固定输入：`xs = (i%33)/32`、`ys = 1-(i%33)/32`、`zs = ((i%7)-3)/10`、
|
||||
`confidence = i%2==0 ? 1.0 : 0.5`、`frameId = 42`、`flags = 0b101`。
|
||||
`confidence = i%2==0? 1.0: 0.5`、`frameId = 42`、`flags = 0b101`。
|
||||
|
||||
## 关键实现
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
```
|
||||
DSH.md
|
||||
contracts/websocket-keypoints.md # 锚点：§1 端点与子协议、§3 控制帧
|
||||
contracts/websocket-keypoints.md # 锚点：1 端点与子协议、3 控制帧
|
||||
app/src/main/java/com/opendance/studio/net/PoseWebSocketClient.kt
|
||||
```
|
||||
|
||||
@@ -22,11 +22,11 @@ app/src/main/java/com/opendance/studio/net/PoseWebSocketClient.kt
|
||||
## 关键实现
|
||||
|
||||
| 项 | 做法 | 理由 |
|
||||
|---|---|---|
|
||||
| 子协议 | 请求头 `Sec-WebSocket-Protocol: opendance.pose.v1` | 契约 §1 |
|
||||
|--|--|--|
|
||||
| 子协议 | 请求头 `Sec-WebSocket-Protocol: opendance.pose.v1` | 契约 1 |
|
||||
| 二进制帧 | `socket.send(ByteString)` | 契约要求生产链路用二进制 |
|
||||
| 控制帧 | `send(text)`，JSON | hello / stats / bye |
|
||||
| 自动重连 | 指数退避 1s → 2s → 4s … 上限 15s，连接成功即重置 | 避免抖动时打爆对端 |
|
||||
| 自动重连 | 指数退避 1s -> 2s -> 4s... 上限 15s，连接成功即重置 | 避免抖动时打爆对端 |
|
||||
| 非连接态发送 | 直接丢弃并计入 `droppedFrames` | **绝不阻塞相机线程** |
|
||||
| 心跳 | OkHttp `pingInterval(15s)` | 及时发现半开连接 |
|
||||
| 读超时 | 0（不超时） | WebSocket 长连接 |
|
||||
|
||||
@@ -27,15 +27,15 @@ HTTP 端点发现。因此：
|
||||
|
||||
1. 取手机在 WiFi 网的 IPv4 地址（排除 `rmnet*` 蜂窝网卡与 `169.254.*` 链路本地地址）
|
||||
2. 推导 `/24` 网段
|
||||
3. 并发 TCP 探测 `192.168.x.1-254:8765`（并发 32、单机超时 300ms）
|
||||
4. 以 `Flow` 形式边扫边产出，按延迟升序展示——最快响应的最可能是目标机
|
||||
3. 并发 TCP 探测 `<局域网网段>.1-254:8765`（并发 32、单机超时 300ms）
|
||||
4. 以 `Flow` 形式边扫边产出，按延迟升序展示--最快响应的最可能是目标机
|
||||
|
||||
整段扫描约 2~3 秒。
|
||||
|
||||
## 可配置项
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
|--|--|
|
||||
| IP / 端口 | 默认 8765，与契约一致 |
|
||||
| 分辨率 | 480×360 / 640×480 / 1280×720 |
|
||||
| 目标帧率 | 写入 hello 的 targetFps |
|
||||
|
||||
@@ -28,7 +28,7 @@ CameraX(ImageAnalysis) ──ImageProxy──▶ MediaPipe PoseLandmarker（端
|
||||
## 状态指示（本任务的验收重点）
|
||||
|
||||
| 指标 | 含义 |
|
||||
|---|---|
|
||||
|--|--|
|
||||
| 连接状态 | 未连接 / 连接中 / 已连接 / 重连中（第 N 次）/ 已断开 |
|
||||
| 目标 | 完整 WS 地址 |
|
||||
| 会话 | 服务端 welcome 回来的 sessionId |
|
||||
@@ -39,7 +39,7 @@ CameraX(ImageAnalysis) ──ImageProxy──▶ MediaPipe PoseLandmarker（端
|
||||
| 平均置信度 | < 70% 时转黄，提示光线或遮挡问题 |
|
||||
| 最近错误 | 连接或推理的错误原因 |
|
||||
|
||||
叠加层把 **低置信度点画成红色**，用户能直接看出是哪个部位没识别到——
|
||||
叠加层把 **低置信度点画成红色**，用户能直接看出是哪个部位没识别到--
|
||||
比只显示一个错误码有用得多。
|
||||
|
||||
## 其他
|
||||
|
||||
@@ -20,10 +20,10 @@ app/build.gradle.kts
|
||||
## 交付物
|
||||
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
|--|--|
|
||||
| `build/gen-keystore.sh` | 生成发布签名密钥库（**不入库**） |
|
||||
| `build/build-apk.sh` | 构建 + 校验产物（魔数、签名方案） |
|
||||
| `build/verify.sh` | 单元测试 → 构建 → 产物校验 一条龙 |
|
||||
| `build/verify.sh` | 单元测试 -> 构建 -> 产物校验 一条龙 |
|
||||
|
||||
## 签名设计
|
||||
|
||||
@@ -32,7 +32,7 @@ app/build.gradle.kts
|
||||
```
|
||||
1. keystore.properties（build/gen-keystore.sh 生成，已 gitignore）
|
||||
2. 环境变量 KEYSTORE_PATH / KEYSTORE_PASSWORD / KEY_ALIAS / KEY_PASSWORD
|
||||
3. 两者都缺失 → 回退 debug 签名，保证 CI 上 assembleRelease 也能产出已签名 APK
|
||||
3. 两者都缺失 -> 回退 debug 签名，保证 CI 上 assembleRelease 也能产出已签名 APK
|
||||
```
|
||||
|
||||
正式发布必须走 1 或 2；回退路径仅为让 CI/验收可跑通，并在构建日志中给出提示。
|
||||
@@ -41,16 +41,16 @@ app/build.gradle.kts
|
||||
|
||||
```
|
||||
1. Android Studio 打开 opendance-android/
|
||||
2. Build → Generate Signed Bundle / APK
|
||||
3. 选择 APK → 选择或创建 keystore → 选择 release
|
||||
2. Build -> Generate Signed Bundle / APK
|
||||
3. 选择 APK -> 选择或创建 keystore -> 选择 release
|
||||
4. 生成 app-release.apk
|
||||
```
|
||||
|
||||
## 验收（文档 §6.3 T-AND-009）
|
||||
## 验收（文档 6.3 T-AND-009）
|
||||
|
||||
| 验收项 | 结果 |
|
||||
|---|---|
|
||||
| Android Studio 可 Build → Generate Signed APK | ✅ 工程为标准 AGP 结构，`keystore.properties` 就位即可 |
|
||||
|--|--|
|
||||
| Android Studio 可 Build -> Generate Signed APK | ✅ 工程为标准 AGP 结构，`keystore.properties` 就位即可 |
|
||||
| `./gradlew assembleRelease` 成功生成签名 APK | ✅ 见下 |
|
||||
| APK 在 Android 10+ 设备可安装运行 | ⚠️ 本环境无 Android 设备/模拟器，未实机安装 |
|
||||
| 关于页包含开源项目声明 | ✅ `CreditsTest` 覆盖，且声明随包分发 |
|
||||
@@ -68,7 +68,7 @@ app-release.apk 55.5 MiB apksigner: Verifies（v2 方案）
|
||||
|
||||
## 环境记录
|
||||
|
||||
- JDK 17（`/usr/lib/jvm/java-17-openjdk-amd64`）
|
||||
- JDK 17（本地安装路径，示例 `<JDK 17 路径>`）
|
||||
- Android SDK：`platforms;android-34`、`build-tools;34.0.0`
|
||||
- 构建期修复的问题：`proguard-rules.pro` 缺失导致 R8 配置告警（已补全 keep 规则）、
|
||||
androidTest 的 `androidx.test.runner` 依赖补齐
|
||||
|
||||
Reference in New Issue
Block a user