docs(win): 任务说明、DSH 约束与交付文档

2026-09-14 20:04:54 +08:00
parent 315cf79708
commit a83e4f6a1f
15 changed files with 975 additions and 0 deletions
@@ -0,0 +1,44 @@
+# T-WIN-002 调用 Web 服务端 API
+
+- **状态**：done
+- **依赖**：T-WIN-001
+
+## 目标
+
+调用 opendance-web 的 REST 接口拉取目录与参考动作序列，只消费冻结契约。
+
+## load
+
+```
+DSH.md
+contracts/rest-api.yaml        # 锚点：#/paths/~1api~1catalog
+contracts/data-models.md       # 锚点：§2 Song、§3 Motion、§4 Model、§6 CatalogBundle
+src/net/api_client.gd
+src/net/catalog_types.gd
+src/autoload/catalog_store.gd
+```
+
+## 交付物
+
+| 文件 | 说明 |
+|---|---|
+| `src/net/api_client.gd` | HTTPRequest 封装；统一返回 `{ok,status,data,error}`，不抛异常 |
+| `src/net/catalog_types.gd` | Song / Motion / Model / CatalogBundle / SourceInfo 类型化解析 |
+| `src/net/keypoint_sequence.gd` | NDJSON 关键点序列 → 特征向量序列 |
+| `src/autoload/catalog_store.gd` | 目录刷新、模型文件下载缓存、序列缓存 |
+
+## 关键实现
+
+- `default_model()` 直接使用服务端解析好的 `defaultModelId`，客户端不重复实现 VRM 优先级
+- `Motion.is_scorable()` 要求 `preprocessState == "done"` 且有帧数
+- 错误体解析兼容 NestJS 的 `message: string[]`
+- 模型文件按 `user://models/<id>.<ext>` 缓存，避免重复下载 10 MB 级 VRM
+
+## 验收
+
+`tests/test_api_integration.gd` 对**真实运行中**的服务端断言：
+health / catalog version / catalog export / 关键点序列，服务端不可达时显式跳过。
+
+## 结果
+
+集成测试通过：目录解析、来源五元组齐备性、`defaultModelId` 解析均符合契约。