zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity
62 Commits 2 Branches 17 Tags
698d60bb65e14cd35b59cfdd3f21faa04aa6a3d6
Commit Graph
14 Commits
Author SHA1 Message Date
zijunchiang 3738bd91b9 release(v0.7.1): 契约 websocket-keypoints 0.2.0 + 补齐场景规格与任务文档 
契约变更（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。
 2026-09-17 01:30:41 +08:00
opendance f2e231c0b2 feat(admin): 场景管理页——列表/上传/物理参数编辑 + 3D 预览（T-WEB-015 补齐） 
- 新增 admin/src/pages/Scenes.tsx（路由 /scenes + 侧栏「场景管理」入口）：
  * 列表：40px 缩略图（点击进详情）、物理摘要、体积、状态、软删除；
  * 上传表单：GLB 文件 + 名称 + 来源五元组 + 物理参数（重力、风基础向量、
    阵风幅度/频率、地面摩擦/坡度、碰撞体、环境光），multipart 走 POST /api/scenes；
  * 详情：复用 VrmPreview（懒加载 three.js 分包）预览场景 GLB + 参数可视化编辑
    并通过 PATCH /api/scenes/:id 保存；
- 新增 admin/src/lib/scene-physics.ts：DEFAULT_SCENE_CONFIG（与契约 7.1、服务端
  scene-config.ts 单一真源，测试断言两端一致）与 physicsSummary()；
- 场景页两栏自适应样式；types/endpoints 补齐场景五接口。
- 测试：场景用例增至 9 项；规模 19 文件 / 245 项。版本 0.7.0。
 2026-09-17 00:32:05 +08:00
opendance 584b7eaca9 feat(scenes): 场景管理后端 + 契约 0.5.0/0.7.0/0.4.0（T-WEB-015） 
契约先行（三端逐字节一致，已同步 windows/android）：
- rest-api -> 0.5.0：新增 GET/POST /api/scenes、GET/PATCH/DELETE /api/scenes/{id}
- data-models -> 0.7.0：新增 §7 Scene 与 7.1 SceneConfig（物理/环境/出生点/相机）
- database -> 0.4.0：新增 scenes 表（config/stats 用 MEDIUMTEXT，迁移可逆）

后端：
- entities/scene.entity.ts + 迁移 AddScenes1789650000000（scenes 表）
- scenes/scene-config.ts：SceneConfig 定义 + 默认值 + **边界收敛**（越界夹紧、
  非法枚举回退），保证客户端拿到的参数一定可解释；服务端只存参数不跑物理
- scenes/scenes.service.ts：上传（.glb/.gltf 直接导入；.zip/.pmx/.fbx 转 GLB，
  场景不做 humanoid 重绑定、不转 VRM）、列表/详情/更新/软删除、缩略图复用模型
  光栅化器、分析复用模型检查器、config 同时接受 JSON 字符串与平铺字段
- scenes/scenes.controller.ts + scenes.module.ts（app.module 注册）
- 审核复用 /api/reviews/:type/:id：TargetType.Scene 接入待审列表与状态流转
- catalog/export 增 scenes[]，目录指纹纳入场景变更
- 枚举：TargetType.Scene、AssetKind.Scene / SceneThumbnail

测试：新增 test/scene-config.spec.ts 6 项（默认值/夹紧/枚举回退/出生点上限/颜色/
序列化）；规模 19 文件 / 243 项；check-routes 35 条一致。版本 0.6.0。

注：管理端场景页（GLB 预览 + 物理参数可视化）与 Windows 场景选择留待下一轮。
 2026-09-17 00:27:08 +08:00
opendance aad60cbd2e feat(motions): 动作预览——骨架缩略图 + 管理端 3D 回放（契约 data-models 0.6.0） 
按《DSH 开发文档 v1.6》4.11（T-WEB-014，用户标注「重要」）：

服务端：
- 抽出公共 PNG 编码器 src/common/png.ts（模型缩略图改为复用，零原生依赖不变）
- 新增 src/motions/motion-thumbnail.ts：关键点序列 -> 正视图骨架 PNG
  （复用 33 点 PARENT_TABLE 连线，包围盒按整段计算，低置信度点不画）
- motions 增 thumbnail_asset_id（迁移 AddMotionThumbnail）+ AssetKind.MotionThumbnail
- /preprocess 生成缩略图并落库，失败只记 warning；MotionDto 增 thumbnailUrl（契约 0.6.0）

管理端：
- 新增 MotionPreview：懒加载 NDJSON -> 骨架线框 + 关节实例球体
  支持播放/暂停、上一帧/下一帧、时间轴拖动、0.25x-2x 变速、循环
  叠加帧号/当前时间/总时长，按整段包围盒自动取景
  three.js 单独分包（lazy + Suspense），主包 241 kB 不涨
- 动作列表新增 40px 骨架缩略图列（点击开预览）+ 预览按钮 + 内联预览面板
- 新增 admin/src/lib/keypoint-sequence.ts 与 lib/skeleton-topology.ts

测试：新增 8 项；规模 18 文件 / 237 项。版本 0.5.0。
 2026-09-17 00:21:09 +08:00
opendance 9eae6f3e43 feat(models): 骨骼重绑定——修复 MMD 模型 humanoid 恒为 0/22（契约 skeleton-topology 0.2.0） 
根因：normalizeBoneName() 只保留 a-z0-9，**中日文字符被整个丢掉**：
'上半身'/'左ひじ'/'首' 归一化后都是空串，MMD 模型的骨名必然失配，
humanoid 覆盖率恒为 0/22 -> 不可驱动 -> 只能回退交付 GLB 并标记不可用。

修复：
1. 归一化保留 CJK/平假名/片假名/长音符/々，并把全角 ASCII（足ＩＫ）折成半角；
2. 候选表补齐四类命名（22 根 x 8-13 个候选）：VRoid / Mixamo /
   MMD 标准骨架（下半身/上半身/上半身2/首/頭/左肩/左腕/左ひじ/左手首/
   左足/左ひざ/左足首/左つま先）/ 常见中文名（臀部/头/脖子/左大臂/左大腿…）；
   精确匹配保证「左足ＩＫ」不会抢占「左足」；
3. Windows 客户端 humanoid_map.gd 的 CANDIDATES 由服务端表**生成写入**，
   normalize() 同步改造，parity 测试断言键/候选顺序完全一致；
4. 契约 skeleton-topology -> 0.2.0：新增 §6「内部动作标准与模型骨骼重绑定」
   （三层标准、22/16 根骨、归一化与匹配规则、实测记录）；
5. 新增 4 项测试；规模 17 文件 / 229 项。

实测：奥黛塔 PMX 0/22 -> 21/22、初音未来 PMX 0/22 -> 19/22，均 drivable=true 且产出 VRM。
版本 0.4.0。
 2026-09-17 00:10:07 +08:00
opendance 39bfd390e3 feat(models): 模型一律转 VRM（契约 0.5.0）+ 可用性门槛 + 管理端版本号展示 
按《DSH 开发文档 v1.6》4.9 与第十一章实现，Web 端第一步：

1. 契约先行（先改 contracts/ 再同步三端）：
   * model-formats.md -> 0.5.0：模型主力格式改为 VRM，所有上传模型一律转 VRM
     （.pmx/.fbx: assimp -> GLB -> VRM；glb/gltf: 包装为 VRM）；
     新增 humanoid 硬门槛与"不达标回退 GLB + usable=false"的交付表；
   * data-models.md -> 0.5.0：Model 新增 usable / unusableReason，明确
     usable=false 不进入 catalog/export；format 说明改为主力 vrm；
   * VERSION 与 contract-versions.ts 同步（三端契约文件逐字节一致）。
2. 实现：
   * MODEL_CONVERT_FORMAT 默认改为 vrm（deploy/.env.example 同步）；
   * 新增 isUsableModel()/unusableReason()：usable 等价于"已产出 VRM"，
     原因从 stats 里带出 humanoid 覆盖度；
   * catalog/export 与 catalog/version 指纹都只统计 format=vrm 的已发布模型，
     resolveDefaultModelId 同样只在可用模型中选；
   * 管理端：模型列表与审核面板显示「不可用」及原因；
   * 管理端左下角展示当前版本号（构建期从 web-server/package.json 注入
     __APP_VERSION__，与 GET /health 同源），并去掉写死的"契约 rest-api 0.1.0"。
3. 测试：新增 test/model-usability.spec.ts 5 项；规模 16 文件 / 225 项。
4. 版本 0.3.0。
 2026-09-17 00:05:02 +08:00
opendance eebccd55b4 fix(models): MMD 材质对齐——补回双面标志、规范化 PBR 参数、可选 unlit 着色 
背景（用户反馈 + 本地用真 Assimp 6.0.4 复现）：
PMX 的着色模型（卡通阶梯 + 球面贴图 + 平坦环境光）与 glTF PBR 不是一回事，
Assimp 转换会丢掉其中一部分。实测样本【奥黛塔】_by_原神.zip（39 个材质）：

1. 主因：PMX 里 36 个材质带 drawFlag bit0（不剔除背面），而导出的 GLB 里
   doubleSided 一个都没有 -> 头发/裙摆/睫毛这类薄片被单面剔除，
   看起来就是颜色/贴图不对；
2. PMX 的 shininess/specular/ambient 与 PBR 无映射；Assimp 还会带上
   KHR_materials_specular / KHR_materials_volume 等与 MMD 无关的扩展；
3. Assimp 把 accessor.min/max 写坏（实测 min = 2.2250738585072014e-308），
   Godot 等客户端用它算包围盒。

修复：
1. 新增 src/models/pmx-materials.ts：只读 PMX 材质段（布局与权威库 mmd-parser
   一致，注意贴图索引宽度是 1 字节），拿到 name/diffuse/specular/shininess/
   ambient/drawFlag/球面贴图/toon/faceCount；
2. 新增 src/models/glb-materials.ts：转换后按索引把 PMX 参数补回 GLB ——
   doubleSided、metallicFactor=0、roughnessFactor=clamp(1-shininess/100,0.5,1)、
   baseColorFactor x diffuse(含 alpha)；清掉与 MMD 无关的扩展；
   修正全部浮点 accessor 的 min/max；支持 KHR_materials_unlit（MODEL_SHADING）；
3. 抽出 src/common/glb-chunks.ts（JSON/BIN chunk 读写），vrm-writer 改为复用；
4. 能力边界写清楚：PMX 的球面贴图（该模型 15 项）与 toon 阶梯在 glTF core 里
   没有对应槽位，任何转换器都无法保留，数量写进 conversion_note 供审核查看；
5. 新增 test/mmd-materials.spec.ts 9 项；规模 15 文件 / 220 项；
6. 新增 MODEL_SHADING 配置（默认 pbr，可选 unlit），文档同步（README.md/.txt、DSH.md、.env.example）。
 2026-09-16 18:55:25 +08:00
opendance ae8a68e98f fix(thumbnail): 缩略图采样 baseColorTexture，修复 MMD 模型显示为白模 
现象（用户反馈）：导入 PMX 转换出的 GLB 后，列表页/审核面板里的模型是白模，
脸部颜色信息全部丢失。

定位过程（本地装真 Assimp 6.0.4 + 该模型完整复现）：
1. 转换本身正常：23.7MB GLB、643 骨骼、93,350 面；
2. 18 张贴图逐字节与压缩包原图一致；用一个权威 PMX 解析器比对后确认
   39 个材质 -> 贴图的对应关系与 PMX 完全一致（不是映射错）；
3. UV 采样也正确：脸部材质取到的就是皮肤色 (246,221,216)；
4. 真正的问题在**我们自己的缩略图渲染器**：它刻意不解码 baseColorTexture，
   只用 baseColorFactor 上色（见文件头取舍说明）；而 MMD 模型的
   baseColorFactor 基本都是白色 -> 缩略图必然全白。管理端 3D 预览有贴图，
   只有列表/审核的缩略图是白的。

修复：
1. model-thumbnail.ts 内置极简 PNG 解码器（zlib inflate + 逐行反滤波，
   8 位非隔行，colorType 0/2/3/4/6），按 baseColorFactor x 贴图逐像素采样，
   透视校正 UV；解码失败/非 PNG/隔行扫描回退纯色，绝不抛错；
2. 按 alphaMode 处理透明度：OPAQUE 忽略贴图 alpha（MMD 语义）、
   MASK 按 alphaCutoff 丢弃、BLEND 做 source-over；
3. 取景收紧 FRAMING 1.6 -> 1.3，40px 列表缩略图主体更清楚；
4. 新增 test/model-thumbnail-texture.spec.ts 6 项（含白模回归：
   baseColorFactor 全白 + 红贴图必须输出偏红，以及 MASK/OPAQUE/坏图回退）；
5. 版本 0.2.4，README(.md/.txt)/DSH.md 补修订说明与 FAQ（含重新生成缩略图
   的 reanalyze-models.mjs --force 命令）。
 2026-09-16 04:02:35 +08:00
opendance 8e8cc0475b fix(models): 修复上传 PMX 返回 500（models.stats 超 TEXT 上限）与 GBK 丢贴图 
现象（真实故障）：导入示例文件/【奥黛塔】_by_原神.zip 返回 500 Internal server error。

根因一（500）：
  该 PMX 643 根骨骼、93,350 面，转换本身成功（GLB 23.7MB），但分析结果里的
  骨骼树按骨骼逐条展开，JSON 实测 70,980 字节，而 models.stats 是 TEXT
  （上限 65,535）。MySQL/MariaDB 严格模式直接拒绝写入（ER_DATA_TOO_LONG /
  1406），而这一步没有兜底 -> 未捕获 -> 500。

根因二（丢贴图）：
  tex/髮.png 的 GBK 字节是 F3 8C。文件名解码先试 Shift-JIS，而 WHATWG 的
  shift_jis 把未定义码位映射成私用区不可见字符（不是 U+FFFD），于是被判为
  「解码成功」，永不回退 GBK；贴图名对不上，该模型 18 张贴图只内嵌了 17 张。

修复：
1. models.stats -> MEDIUMTEXT（实体 mediumtext + transformer，保留 JSON 语义；
   不用 simple-json 以免元数据与库列型不一致），新增迁移
   AddModelStatsMediumText1789550000000；
2. 新增 shrinkStatsForStorage() 兜底：即使库未迁移，也只截断骨骼树
   （父在前，保留祖先链），面数/骨骼数/humanoid 覆盖/可驱动性/warnings 全部保留；
   服务层 saveWithStatsFallback() 仅在 1406/DATA_TOO_LONG 时裁剪重试一次，
   其它数据库错误照旧抛出；
3. 压缩包文件名解码把「私用区字符」也算作解错信号，回退 GBK；实测该模型
   贴图由 17/18 变为 18/18 全部内嵌；
4. 新增 12 项测试（test/model-stats-limit.spec.ts 9 项 + 压缩包编码/目录条目 3 项）；
5. 版本 0.2.3，README(.md/.txt)/DSH.md 补修订说明、500 的 FAQ 与 stats 容量约束。
 2026-09-16 03:30:12 +08:00
opendance afed67e175 fix(deploy): apt 安装 Assimp 不再写死 libassimp6 
Debian 11 / Ubuntu 22.04 的库包是 libassimp5，Debian 12+ 才是 libassimp6；
写死库名会让 apt 报 'no installation candidate'，自动安装直接失败。
改为只装 assimp-utils（它按发行版依赖对应的库版本）。
 2026-09-16 02:56:50 +08:00
opendance da03777995 fix(models): Assimp 缺失时给出可操作报错，部署脚本自动安装 
现象：服务器未安装 Assimp，上传 PMX 压缩包只得到
  GLB 直出：导出失败（ENOENT）：spawn assimp ENOENT
  glTF 直出：导出失败（ENOENT）：spawn assimp ENOENT
用户看不出缺什么、怎么装，也不知道只传 glb/vrm 其实不需要它。

修复：
1. 新增 src/common/assimp.ts：按 ASSIMP_BIN -> PATH -> /usr/bin、/usr/local/bin
   等常见目录定位可执行文件（只认文件，不认同名目录），转换前先预检；
   找不到就一次性给出各发行版安装命令、查过的路径与替代办法，
   不再打两条 ENOENT。动作预处理（FBX/glTF -> BVH）复用同一文案。
2. 新增 deploy/assimp-lib.sh：install.sh 按发行版自动安装
   （apt-get / dnf / yum / zypper / apk / pacman），装在非常规目录时把绝对
   路径写入 deploy/.env 的 ASSIMP_BIN；装不上只告警不中止，可用
   SKIP_ASSIMP_INSTALL=1 跳过。check-access.sh 自检增加 Assimp 一行。
3. /health 增加 assimp.path；管理端「概览 -> 服务健康」显示 Assimp 状态，
   不可用时给出安装提示。
4. 新增 test/assimp-locate.spec.ts 13 项；强化「assimp 不存在」用例断言安装命令。
   测试规模 12 文件 / 193 项。
5. 版本 0.2.2，README(.md/.txt)/DSH.md 同步（前置要求、FAQ、环境变量说明）。
 2026-09-16 02:55:32 +08:00
opendance ea58520fc2 fix(deploy): .env 中带空格的值未加引号导致 install.sh 以 127 失败 
现象：
  ./deploy/.env: line 53: Miku.pmx: command not found
  [install] 第 53 行执行失败（退出码 127）

根因：deploy/.env.example 的 MODEL_CONVERT_PMX=Hatsune Miku.pmx 值含空格
却没加引号，install.sh 用 `set -a; . deploy/.env` 载入时被切成
「赋值 + 命令」，Miku.pmx 被当成命令执行。

修复：
1. 模板改为 MODEL_CONVERT_PMX="Hatsune Miku.pmx"（占位符值同样加引号）；
2. 新增 deploy/env-lib.sh：.env 语法预检，install.sh / ctl.sh 在 source
   之前检查，报错给出「哪一行 / 原文 / 改法」， 与反引号建议单引号；
3. install.sh 的 ERR trap 补上出错文件名（lineno 属于被 source 的 .env，
   只报行号无法定位）；
4. 新增 test/env-file.spec.ts 12 项回归测试，锁住「模板可被 shell 原样载入」；
5. 版本升到 0.2.1，README(.md/.txt)/DSH.md 补 .env 写法约定、FAQ 与测试数量。
 2026-09-15 22:26:58 +08:00
zijunchiang d6376ec5a5 更新 README.md 2026-09-15 22:17:49 +08:00
opendance b7748a50eb docs: web 端根说明补充 Markdown 版本 README.md 
仓库首页(Gitea/编辑器)以 .md 为准,windows/android 两端都已有
README.md + README.txt 两份,web 端此前只有 README.txt。
本次按同风格补齐 README.md:标题/状态/初次部署/环境变量/API/目录结构
等改为 Markdown 结构(标题层级、表格、带语言的代码块),内容与
README.txt 逐项等价;同时把 README.md 纳入发布包与关键文件校验。
 2026-09-15 21:53:29 +08:00