zijunchiang
3738bd91b9
契约变更（T-WEB-016，与 Android T-AND-011「两端一起改」配套）
- websocket-keypoints 0.1.0 -> 0.2.0，均为向后兼容（子协议名与二进制帧
version 均不变，只新增可选控制字段与一种新控制类型）：
1.1 保活：接收端必须声明 silentTimeoutMs 与 heartbeatIntervalMs，且心跳必须
小于静默超时的一半。根因是客户端只能用 OkHttp 的协议层 ping，而它由
底层库自动应答、**不暴露给应用层**，接收端根本看不到，无法续命；
3.1 hello.deviceId（该安装实例的稳定标识，不使用任何硬件序列号）；
3.2/3.3 welcome/config 携带保活字段；
3.6 应用层 ping/pong（回显 sentAtMs，pong 另带 serverAtMs 供算 RTT）；
5 设备去重：同一 deviceId 只保留最新连接，旧连接以 1000 关闭
（刻意用 1000：对端据 §7 不会重连，否则形成"挤掉-重连-再挤掉"循环）；
7 关闭码与重连策略：1000/1001/1002 与主动停止不重连，其余重连；
7.1 退避参数冻结：min(500ms*2^(n-1), 15000ms) + ±20% 抖动；
8 连接状态机（两端同名，日志可直接对照）。
- contracts/VERSION 与 src/config/contract-versions.ts 同步到 0.2.0。
补齐 rest-api.yaml 漏写的场景结构（只补规格，不改线格式，版本号不变）
- CatalogBundle 增加 scenes[]（标注 0.5.0 起下发）；
- 新增 Scene / SceneConfig / Vec3 schemas。catalog/export 自 v0.7.0 起就返回
scenes[]，data-models 7 也已冻结，但规格漏写会让两端对字段边界
（如 0~1、±200）的理解不一致。
deploy/proxy/README.md 新增第九节：Gitea 站点的附件上传上限
- 与一~五节的 Web 服务反代是**两个不同站点**；实测 30.5 MB / 40 MB 上传返回
HTTP 413，根因是 IIS 默认 maxAllowedContentLength = 30,000,000 字节；
- 给出放宽到 256 MB 的 IIS / ARR / Gitea app.ini / nginx 四处配置与复验命令；
- 这解释了 Windows 端 v0.1.0 为何被拆成 zip.part0/1/2（交付缺陷）。
文档与脚本
- 补齐 tasks/011~016 与 project.yaml 条目（T-WEB-011~015 此前已在代码中落地
却缺任务说明书）；project.yaml 的 contracts_version 由单个 0.4.0 改为六项字典；
- scripts/package-release.sh 的版本号改为从 web-server/package.json 读取
（与 GET /health 的 version、管理端左下角展示同源），并与 project.yaml 交叉校验；
同时补上 SHA256SUMS 与自校验（此前是手工生成的）。
验证：npm run verify 通过（contracts:check 六项一致 + 35 条路由一致、
typecheck、246 项测试、nest build）；产物 opendance-web-v0.7.1.tar.gz
sha256 27f92cfb125bbcf29077d4ad90c44720cbca46d23ddef12cd7826d73bd8865e2。
OpenDance Studio 管理端(opendance-admin)
基于 React 18 + TypeScript + Vite 的管理后台，对接 web-server 的 NestJS API。
接口契约以 ../contracts/rest-api.yaml(rest-api 0.1.0)为准，
字段语义见 ../contracts/data-models.md。
界面语言为简体中文；无任何 UI 组件框架，全部样式集中在 src/styles.css。
快速开始
npm install # 或 pnpm install
npm run dev # 开发服务器 http://localhost:5173
npm run build # 生产构建(tsc -b && vite build)-> dist/
npm run preview # 本地预览 dist/
npm run typecheck # 只做类型检查(tsc --noEmit)
管理端请求的是同源的
/api/**与/health，不含任何硬编码域名。
开发代理(dev proxy)
vite.config.ts 已把 /api 与 /health 代理到 http://localhost:3000:
server: {
port: 5173,
proxy: {
'/api': { target: 'http://localhost:3000', changeOrigin: true },
'/health': { target: 'http://localhost:3000', changeOrigin: true },
},
}
因此本地只需先启动服务端，再 npm run dev 即可，无需配置 CORS。
VITE_API_BASE
src/api/client.ts 的基址取自：
const BASE_URL = import.meta.env.VITE_API_BASE?? '';
-
不设置（默认，空串）：同源请求 -- 开发期走上面的 vite 代理，生产期走 nginx 反代。推荐。
-
设置：例如服务端在另一台机器上：
#.env.local（不要提交） VITE_API_BASE=http://192.0.2.10:3000此时浏览器会直接跨域请求该地址，需要服务端开启 CORS。 构建期注入：
VITE_API_BASE=https://api.example.com npm run build。
生产构建与部署
npm run build # 产物在 dist/
vite.config.ts 使用 base: './'，产物使用相对路径引用，可挂在任意子路径下。
生产部署（业务服务自带管理端，不需要反代托管静态文件）
构建产物 dist/ 会被安装到 $APP_DIR/admin，并由 NestJS 服务自身托管
（含 SPA 深链接回退）。因此反向代理只需要把请求整体转发到后端端口即可，
不需要在代理层再配置静态站点或 try_files。
# 仓库根目录，一键部署后端（含管理端）
bash deploy/install.sh
- 后端通过
ADMIN_DIR定位管理端产物，默认../admin - 反代配置样例：
deploy/proxy/nginx.conf.example(nginx)、deploy/proxy/web.config.example(IIS) - 完整说明：
deploy/proxy/README.md
目录结构
src/
main.tsx 入口(BrowserRouter)
App.tsx 路由表
styles.css 全部样式
api/
client.ts fetch 封装(ApiError / 分页 / multipart)
types.ts 契约类型（与 rest-api.yaml 一一对应）
endpoints.ts 契约端点封装
components/
Layout.tsx 左侧导航骨架
ui.tsx 通用组件(表格/弹窗/分页/来源五元组展示与表单...)
VrmPreview.tsx three + @pixiv/three-vrm 的 3D 预览（懒加载分包）
lib/
labels.ts 枚举中文文案
format.ts 时间/字节/时长格式化
validation.ts 客户端校验（来源五元组等）
useAsync.ts 加载/错误/重试 hook
pages/
Dashboard.tsx 概览
Songs.tsx 歌曲管理 T-WEB-008
Models.tsx 模型管理 T-WEB-009
Motions.tsx 动作管理 T-WEB-004/006
Reviews.tsx 审核 T-WEB-007
页面与任务对照
| 路由 | 说明 | 任务 |
|---|---|---|
/ |
概览：三类资产按状态计数、契约版本与目录指纹、健康检查、API 不可达告警 | - |
/songs |
歌曲管理：分页/搜索/筛选、来源五元组必填、音频上传、软删除 | T-WEB-008 |
/models |
模型管理：VRM 优先、来源五元组完整展示、设为默认、3D 预览 | T-WEB-009 |
/motions |
动作管理：上传、预处理、关键点 NDJSON 下载 | T-WEB-004/006 |
/reviews |
审核：待审列表 + 审核流水，通过/驳回（驳回必填意见） | T-WEB-007 |
所有页面都显式处理加载中 / 空数据 / 请求失败三种状态，请求失败不会白屏。
3D 预览说明
src/components/VrmPreview.tsx: GLTFLoader + VRMLoaderPlugin（来自 @pixiv/three-vrm），
- 依据
vrm.meta.metaVersion区分 VRM 0.x / 1.0, 0.x 自动执行VRMUtils.rotateVRM0; - 自实现鼠标拖拽旋转与滚轮缩放（未引入 OrbitControls）；
requestAnimationFrame循环内调用vrm.update(delta)，并按包围盒自动取景；- 卸载时取消 RAF、断开 ResizeObserver、释放 renderer / geometry / material / texture;
- 无 WebGL 上下文时降级为错误提示，不会让页面崩溃。
three + @pixiv/three-vrm（约 750 kB）通过 React.lazy 单独分包，仅进入模型页时加载。