opendance
4913760a8b
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则 （analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记， 且 _common 表恒定生效），把说明文档中会被标记的全角标点 （，：；？！（） 等）改为半角，并保证成对括号宽度一致。 中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。
45 lines
1.5 KiB
Markdown
45 lines
1.5 KiB
Markdown
# 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` 解析均符合契约。
|