================================================================
OpenDance Studio —— Windows 客户端 v0.1.0  使用说明
================================================================

摄像头跳舞评分系统的核心体验端：接收 Android 辅助 App 通过 WebSocket
推送的 33 点骨骼关键点，驱动 VRM 角色，并与 Web 服务端下发的参考动作
做实时 DTW 评分。

本客户端只接收关键点坐标，不接收、不存储任何视频画面。

----------------------------------------------------------------
一、快速开始
----------------------------------------------------------------

1. 解压后得到：
     OpenDance.exe       主程序
     OpenDance.pck       资源包（必须与 exe 同目录）
     README.txt          本文件
     THIRD_PARTY.md      开源声明
     contracts/          契约快照

2. 先启动 Web 管理服务端（opendance-web），确保能访问其 API。

3. 双击 OpenDance.exe 启动。

4. 在主界面确认「服务端地址」（默认 http://127.0.0.1:3000），
   点击「保存并测试」；顶部应显示「服务端正常 ｜ DB ...」。

5. 点击「刷新目录」，左侧会出现已发布的曲目、动作与模型。

6. 在 Android 手机上启动「OpenDance 辅助 App」，填入本机显示在
   主界面上的接收地址（形如 ws://192.168.x.x:8765/pose）并连接。
   连接成功后主界面会提示「已连接 N 台设备」。

7. 依次选择曲目 → 动作 → 模型，点击「开始跟练」。

----------------------------------------------------------------
二、界面说明
----------------------------------------------------------------

主界面
  - 三栏选择：曲目 / 动作（仅列出已完成预处理的动作）/ 模型（VRM 优先）
  - 服务端地址：可修改并即时测试
  - 接收地址：Android 端要连接的 WebSocket 地址
  - 「刷新目录」重新拉取已发布资源
  - 底部展示所选动作的**来源信息**（来源类型、名称、作者、许可、链接）

游戏界面
  - 左侧 3D 视图：VRM 角色跟随关键点实时动作，相机自动框住模型
  - 右侧 HUD：实时得分、等级、连击、动作进度、连接状态、来源信息

结算界面
  - 等级（S/A/B/C/D）、平均分与最终分、动作完成度、最高单帧、最长连击
  - 「再来一次」/「返回主菜单」/「开源声明」

关于页面
  - 版本与契约版本、隐私说明、完整可滚动的第三方开源项目声明

----------------------------------------------------------------
三、配置文件
----------------------------------------------------------------

首次运行会在以下位置生成配置文件，可直接用文本编辑器修改：

  Windows: %APPDATA%\Godot\app_userdata\OpenDance Studio\opendance.cfg

可配置项：

  api_base_url      Web 服务端地址（默认 http://127.0.0.1:3000）
  listen_host       WebSocket 监听地址（默认 0.0.0.0）
  listen_port       WebSocket 监听端口（默认 8765）
  ws_subprotocol    子协议（默认 opendance.pose.v1）
  dtw_band          DTW 带宽，单位帧（默认 15 ≈ 0.5 秒抖动容忍）
  score_tolerance   评分容差：平均每步代价达到该值即 0 分（默认 0.25）
  mirror_preview    镜像预览

----------------------------------------------------------------
四、防火墙与网络
----------------------------------------------------------------

本客户端需要接受 Android 设备的入站连接：

  - Windows 防火墙需放行 OpenDance.exe 的 **TCP 8765** 入站
  - 手机与电脑需在同一局域网
  - 手机端填写主界面显示的「接收地址」

若端口被占用，可修改 opendance.cfg 中的 listen_port 后重启。

----------------------------------------------------------------
五、评分说明
----------------------------------------------------------------

- 每帧特征 = 33 点 × (x,y,z) + 9 个关节角余弦 = 108 维
  （与 Web 服务端预处理产物、Android 端推流结构完全一致）
- 置信度低于 0.5 的关键点不参与代价计算，避免遮挡导致误判
- 采用带约束 DTW（|i−j| ≤ band）对齐，能吸收一定的节奏快慢差异
- 得分 = clamp(1 − 平均代价 / 容差, 0, 1) × 100，并做指数平滑
- 等级：S ≥ 95，A ≥ 85，B ≥ 70，C ≥ 55，D 其余

----------------------------------------------------------------
六、从源码构建
----------------------------------------------------------------

前置：Godot 4.7.x + 对应版本的 export templates

  # Linux 上直接导出 Windows 可执行文件（推荐）
  GODOT_BIN=/path/to/godot bash build/export-windows.sh release

  # Windows 上兜底导出
  powershell -ExecutionPolicy Bypass -File build\export-windows.ps1

产物位于 build/windows/：OpenDance.exe + OpenDance.pck
（脚本会校验产物存在且为合法 PE 文件）

运行测试：

  GODOT=/path/to/godot
  $GODOT --headless --path . --import
  $GODOT --headless --path . --script res://tests/run_tests.gd
  $GODOT --headless --path . --quit-after 180

----------------------------------------------------------------
七、目录结构
----------------------------------------------------------------

  project.godot            工程配置（autoload / 渲染 / 窗口）
  export_presets.cfg       导出预设（必须在项目根目录）
  project.yaml             任务清单与状态
  DSH.md                   本项目 DSH 执行约束
  tasks/                   单任务说明书（T-WIN-001 ~ 011）
  contracts/               只读契约快照（来源 opendance-web v0.1.0）
  scenes/main.tscn         根节点
  src/autoload/            AppConfig / CatalogStore / PoseReceiver / ScoreService
  src/net/                 239 字节编解码、WebSocket 服务、REST 客户端
  src/model/               VRM 加载、humanoid 骨骼映射
  src/anim/                关键点 → 骨骼重定向
  src/score/               特征提取、DTW、评分规则
  src/ui/                  主界面 / 游戏界面 / 结算 / 关于 / 来源展示
  tests/                   无头测试框架与用例
  build/                   导出脚本

----------------------------------------------------------------
八、常见问题
----------------------------------------------------------------

Q: 主界面显示「服务端不可达」
A: 检查 Web 服务端是否已启动，以及「服务端地址」是否正确（含端口）。

Q: 目录里没有可用的动作
A: 动作必须先在管理端完成「预处理」（BVH → 关键点序列）并「审核通过」，
   才会出现在客户端。

Q: 模型加载失败 / 动作不完整
A: 游戏界面会显示「人形覆盖率」。低于 60% 说明模型的骨骼命名不被识别，
   请换用标准 VRM（VRoid Studio 导出）模型。

Q: 连上了手机但分数一直是 0
A: 确认手机端已开始推流；主界面的「查看接收状态」会显示累计帧数与丢帧数。

Q: 关于页面的开源声明
A: 与 THIRD_PARTY.md、contracts/open-source-credits.md 三处保持一致。

----------------------------------------------------------------
九、许可
----------------------------------------------------------------

本客户端代码以 MIT 许可发布。第三方开源项目声明见 THIRD_PARTY.md。
未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑。
