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。
103 lines
3.8 KiB
YAML
103 lines
3.8 KiB
YAML
project: opendance-web-server
|
||
version: 0.7.1
|
||
repository: opendance-web
|
||
default_branch: main
|
||
contracts_version:
|
||
rest-api: 0.5.0
|
||
websocket-keypoints: 0.2.0
|
||
data-models: 0.7.0
|
||
skeleton-topology: 0.2.0
|
||
model-formats: 0.5.0
|
||
database: 0.4.0
|
||
|
||
# 契约变更流程（文档 7.2）：
|
||
# 任何跨端契约变更必须先在本项目修改 contracts/ 并提升版本，
|
||
# 再在 opendance-windows / opendance-android 创建适配任务。
|
||
|
||
database:
|
||
# 使用现有实例，本项目不部署、不管理 MySQL
|
||
managed_by: external
|
||
engine: MySQL 兼容（含 MariaDB 10.5+）
|
||
name: opendance
|
||
charset: utf8mb4
|
||
migrations: TypeORM migration
|
||
synchronize: forbidden
|
||
|
||
tasks:
|
||
- id: T-WEB-001
|
||
file: tasks/001-scaffold.md
|
||
scope: NestJS 骨架 + 连接现有 MySQL
|
||
status: done
|
||
- id: T-WEB-002
|
||
file: tasks/002-db-migration.md
|
||
scope: TypeORM 迁移生成 opendance 表结构
|
||
status: done
|
||
- id: T-WEB-003
|
||
file: tasks/003-song-crud.md
|
||
scope: /api/songs CRUD
|
||
status: done
|
||
- id: T-WEB-004
|
||
file: tasks/004-motion-upload.md
|
||
scope: 动作数据上传（BVH / VMD / FBX / glTF / keypoints）+ 来源字段
|
||
status: done
|
||
- id: T-WEB-005
|
||
file: tasks/005-model-upload.md
|
||
scope: 模型上传（GLB/VRM 直接导入 + PMX/FBX 转换 + .zip 自动搜索）+ 自动分析/缩略图 + 上传即待审
|
||
status: done
|
||
- id: T-WEB-006
|
||
file: tasks/006-keypoint-preprocess.md
|
||
scope: BVH / VMD / FBX -> 关键点序列预处理
|
||
status: done
|
||
- id: T-WEB-007
|
||
file: tasks/007-upload-review.md
|
||
scope: 上传审核流程
|
||
status: done
|
||
- id: T-WEB-008
|
||
file: tasks/008-admin-ui-songs.md
|
||
scope: 歌曲管理界面
|
||
status: done
|
||
- id: T-WEB-009
|
||
file: tasks/009-admin-ui-models.md
|
||
scope: 模型管理界面 + 来源展示
|
||
status: done
|
||
- id: T-WEB-010
|
||
file: tasks/010-deploy.md
|
||
scope: 部署脚本（双端口：软件 API 3000 + 管理端 3001，不部署 MySQL）+ deploy/.env 初始化引导（init-env.sh，HOST 默认 0.0.0.0）
|
||
status: done
|
||
- id: T-WEB-011
|
||
file: tasks/011-version-display.md
|
||
scope: 管理端左下角展示当前版本号（唯一来源 package.json）
|
||
status: done
|
||
- id: T-WEB-012
|
||
file: tasks/012-vrm-first.md
|
||
scope: 模型主力格式全面转为 VRM（非 VRM 入库标记不可用，不进已发布目录）
|
||
status: done
|
||
- id: T-WEB-013
|
||
file: tasks/013-bone-rebinding.md
|
||
scope: 动作内部标准（33 点）+ 模型骨骼按名重绑定（含 MMD/中文名）
|
||
status: done
|
||
- id: T-WEB-014
|
||
file: tasks/014-motion-preview.md
|
||
scope: 动作管理预览（离线骨架缩略图 + 管理端 3D 回放）
|
||
status: done
|
||
- id: T-WEB-015
|
||
file: tasks/015-scene-management.md
|
||
scope: 场景管理（GLB + 重力/风/物理参数，服务端只存参数）
|
||
status: done
|
||
- id: T-WEB-016
|
||
file: tasks/016-websocket-contract-020.md
|
||
scope: 契约 websocket-keypoints 0.2.0（保活 / 设备去重 / 状态机，与 T-AND-011 对齐）
|
||
status: done
|
||
|
||
deliverable:
|
||
artifact: opendance-web-v0.7.1.tar.gz
|
||
packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker）
|
||
includes:
|
||
- web-server/ # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换）
|
||
- admin/ # React 管理端构建产物
|
||
- deploy/ # install.sh / init-env.sh / systemd / openrc / initd / ctl.sh / .env.example（PORT、ADMIN_PORT、HOST）
|
||
- deploy/proxy/ # 反向代理说明（nginx / IIS，仅供参考不部署）
|
||
- contracts/ # 当前版本契约快照（rest-api 0.5.0 / websocket-keypoints 0.2.0 / data-models 0.7.0 / database 0.4.0）
|
||
- THIRD_PARTY.md # 开源声明
|
||
- README.txt # 使用说明
|