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

tasks/006-keypoint-preprocess.md

@@ -0,0 +1,67 @@
+# T-WEB-006 BVH/FBX → 关键点序列预处理
+
+- **状态**：done
+- **依赖**：T-WEB-004
+
+## 目标
+
+把上传的 3D 动作数据转换为与 Android 端输出**同构**的 MediaPipe 33 点关键点序列，
+使 Windows 端 DTW 引擎只有一条输入通路。
+
+## load
+
+```
+DSH.md
+contracts/model-formats.md       # 锚点：§2 动作格式、§2.1 预处理产物、§2.2 关节名映射
+contracts/skeleton-topology.md   # 锚点：§1 33 点、§3 父节点表、§5 关节角
+web-server/src/preprocess/*
+```
+
+## 端点
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/api/motions/:id/preprocess` | 执行预处理，返回更新后的 Motion |
+| GET | `/api/motions/:id/keypoints` | 下载 NDJSON 关键点序列 |
+
+## 实现分层
+
+| 文件 | 职责 |
+|---|---|
+| `bvh-parser.ts` | 纯 TS BVH 词法/语法解析 + 逐帧前向运动学（FK） |
+| `math3d.ts` | 向量/矩阵工具、旋转合成、关节角余弦 |
+| `joint-map.ts` | BVH 关节名 → MediaPipe 点索引的默认映射表 |
+| `retarget.ts` | 单帧解算 35 项（33 点 + neck/pelvis 虚拟关节）→ 骨盆归零 → 自适应缩放 → 投影 |
+| `keypoint-codec.ts` | 239 字节二进制帧编解码、NDJSON 序列化/解析、关键点 JSON 校验 |
+| `assimp.ts` | 可选外部 Assimp 调用（FBX/glTF → BVH） |
+| `preprocess.service.ts` | 编排、落盘、状态与错误记录 |
+
+## 拓扑与缩放（契约冻结）
+
+- 33 点顺序与父节点表来自 `contracts/skeleton-topology.md`，虚拟关节
+  `neck=33`、`pelvis=34` 只参与关节角计算，**不进入输出序列**。
+- 投影：`x_img = 0.5 + x·s`，`y_img = 0.5 − y·s`，`z_img = −z·s`，
+  `s = 0.35 / max(|x|,|y|,|z|)`（按整段动作自适应，保证不出画）。
+- 置信度分层：直接映射 **1.0**、按层级推算 **0.5**、无法推算 **0.0**。
+
+## 格式支持
+
+| 格式 | 处理 |
+|---|---|
+| `.bvh` | 内置解析器，无外部依赖 |
+| `.json` | 直通校验与规范化（须符合 `mediapipe33@0.1.0`） |
+| `.fbx` `.gltf` `.glb` | 调用可选 Assimp 转 BVH；未安装 Assimp 时写入可读错误并置 `preprocessState=failed` |
+
+## 验收
+
+```bash
+npm run test          # 25 例：解析 / FK / 重定向 / 编解码 / 拓扑 / 契约版本
+npm run test:smoke    # 冒烟 [3] 段落
+```
+
+覆盖：60 帧样例经预处理后 **60 帧 × 33 点 × 9 关节角**、坐标落在
+MediaPipe 归一化范围、置信度分层、时间戳按帧率推进、序列随时间变化、
+NDJSON 往返、解码器拒绝错误长度与 magic。
+
+样例数据由 `test/fixtures/generate-sample-bvh.mjs` 生成（60 帧挥手 + 深蹲，
+21 关节 / 63 通道），可复现。