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

2026-09-14 19:00:55 +08:00
parent 5a8b77b0a4
commit b9215d4190
16 changed files with 1461 additions and 0 deletions
@@ -0,0 +1,56 @@
+# T-WEB-004 动作数据上传 + 来源字段
+
+- **状态**：done
+- **依赖**：T-WEB-002
+
+## 目标
+
+上传动作文件（BVH / FBX / glTF / GLB / keypoints-json），**强制填写来源五元组**。
+
+## load
+
+```
+DSH.md
+contracts/rest-api.yaml          # 锚点：#/paths/~1api~1motions
+contracts/data-models.md         # 锚点：§3 Motion
+contracts/model-formats.md       # 锚点：§2 动作格式、§3 上传限制
+web-server/src/motions/*
+web-server/src/storage/storage.service.ts
+```
+
+## 端点
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/motions` | 分页 + `q`/`songId`/`format`/`status` 过滤 |
+| POST | `/api/motions` | multipart 上传 |
+| GET | `/api/motions/:id` | 详情 |
+| PATCH | `/api/motions/:id` | 更新元数据（含 `detachSong`） |
+| DELETE | `/api/motions/:id` | 软删除 |
+
+## 存储策略（`contracts/model-formats.md` §3）
+
+```
+${STORAGE_DIR}/{kind}/{yyyy}/{mm}/{sha256前2位}/{sha256}.{ext}
+```
+
+- 上传先落 `${STORAGE_DIR}/tmp`（multer diskStorage），避免大文件占用内存
+- `StorageService` 流式计算 sha256；**相同内容只落盘一次**，复用 `assets` 记录
+- 并发同文件上传靠 `assets.sha256` 唯一索引兜底，冲突后回退到已存在记录
+- 路径永不使用原始文件名；`absolutePath()` 拒绝逃逸存储根目录
+
+## 校验
+
+- 扩展名白名单：`.bvh .fbx .gltf .glb .json`，其他 → 400
+- 来源五元组缺任一项 → 400
+- `songId` 指向不存在的曲目 → 400
+- 单文件上限 `UPLOAD_MAX_BYTES`（默认 512 MiB）
+
+## 验收
+
+```bash
+npm run test:smoke
+```
+
+冒烟 [2] 段落：上传 201、自动识别 `format=bvh`、`fileSize` 记录、缺来源 400、
+`evil.exe` 400。