zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity
71 Commits 2 Branches 17 Tags
d1c0dd6e7aa0695c929faea11c7c841b2d645488
Commit Graph
71 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
zijunchiang d1c0dd6e7a test(scenes): 加带真实数据库的端到端用例（sql.js 内存库），把生产根因钉死 
新增 test/scenes-e2e.spec.ts（4 项，全部真实 SQL，不是 mock）：

1. Scene 在 DataSource 里有 metadata、getRepository 不抛错；
2. **反向验证生产根因**：当 ENTITIES 漏掉 Scene 时，`getRepository(Scene)` **不会抛**
   （TypeORM 0.3 是惰性的——这正是"启动完全正常"的原因），而**第一次查询**会 reject
   并抛出与生产完全一致的 `No metadata for "Scene" was found.`；
3. **上传→归档→落库→发布→目录导出 全链路**（真实 StorageService + 真实仓储）：
   - 用 multer diskStorage 的文件形状（只有 path、没有 buffer）上传 .glb；
   - 断言 GLB 已归档进 storage、临时目录不再残留该文件（验证 diskStorage 修复）；
   - 落 pending；`published()` 为空；发布后能取到完整物理参数（重力/风/地面/相机）；
   - `CatalogService.exportBundle()` 的 `scenes[]` 含该场景且参数完整；
   - `catalog/version` 指纹为 64 位十六进制；`scenes.diagnostics()` 报告可用；
   - 删除后 `published()` 不再返回（软删除生效）；
4. 越界/非法参数在**真实落库往返**（jsonText transformer）后仍是收敛值
   （重力 -200、摩擦 1、colliders auto、相机 follow）。

实现细节：库内用 `sql.js`（WASM，无原生依赖，devDependency）跑 TypeORM 的 sqljs 驱动；
SQLite 本身对列类型名宽松，但 TypeORM 的 sqlite 驱动会校验 normalizeType 的结果，
因此测试里加了一处**有注释的兼容垫片**：`char→varchar`、`mediumtext/longtext/tinytext→text`、
`enum→varchar`，以及 `bigint` 自增主键→`integer`（SQLite 的 AUTOINCREMENT 只允许
INTEGER PRIMARY KEY）。只影响本测试进程，不改动任何实体定义。

验证：npm run verify 通过（24 文件 / 289 项测试 + 契约/路由/版本一致 + 启动冒烟）。
v0.7.4 		2026-09-17 03:52:33 +08:00
zijunchiang 7a74f598be fix(entities): 场景功能的真正根因 —— Scene 未注册进 ENTITIES（v0.7.4） 
部署 v0.7.3 后，/health 的 scenes.error 给出决定性线索：

  No metadata for "Scene" was found.

src/entities/index.ts 的 ENTITIES 一直漏了 Scene：
  export const ENTITIES = [Asset, Song, Motion, CharacterModel, ReviewRecord];

TypeORM 只按 ENTITIES 注册 metadata，漏注册的后果极其隐蔽：
- 启动完全正常（DI 可解析、/health 正常、migrationsPending 0）；
- 迁移也正常（AddScenes 已执行，表其实是建好的）；
- 但第一次查 Scene 就抛 No metadata，于是 /api/scenes、/api/catalog/export、
  /api/catalog/version、/api/reviews?status=pending 全部 500
  → 客户端拉不到任何目录、管理端待审列表打不开。

即：此前"数据库缺 scenes 表"的判断也是错的（v0.7.3 的降级与诊断脚本因此仍然值得保留
—— 它们把"场景坏了"限制成"场景不可用"，而不是整站不可用）。

修复：ENTITIES 加入 Scene 并导出。

新增静态防线 test/entities-registry.spec.ts（4 项）：扫描 src/entities/*.entity.ts 里的
@Entity() 类并逐一与 ENTITIES 对账（漏一个即失败）、检查无重复/无多余、核对 AddScenes
迁移文件存在。已做反向验证：把 Scene 从 ENTITIES 移除后该测试立刻失败。
这类缺陷既过得了 tsc、也过得了启动冒烟（应用能启动），只能靠静态核对兜住。

文档：README.md/.txt 增加 v0.7.4 修订说明；tasks/015-scene-management.md 增
「缺陷修复记录四」；开发文档 §4.12 补「新增实体必须加入 ENTITIES」的硬性要求。

验证：npm run verify 通过（23 文件 / 285 项测试 + 契约/路由/版本一致 + 启动冒烟）；
发布产物 opendance-web-v0.7.4.tar.gz
sha256 e680c23fc382b6c39498608ea0154f8f80e9e6b5c13518f0f88095644ce88fe1。
 2026-09-17 03:48:52 +08:00
zijunchiang 74332e20d8 docs(proxy): 更正「Gitea 附件通道坏了/磁盘写满」的误判 —— 实际是上传字段名写错 
排查 Windows 整包上传时的 500 曾被判成"Gitea 宿主机磁盘写满"。**这个结论是错的**，
本次用对照实验确认并更正：Gitea 的 Release 附件接口 multipart 字段名是
**`attachment`**，用 `file=` 会得到

  HTTP 500 {"message":"","url":"https://gitea.kasugano.cn/api/swagger"}

空消息，极易误判成服务器故障。同一 1 KB 文件、同一 Release 的实测对照：
  -F "attachment=@probe.bin"                      → 201
  --data-binary @probe.bin (+?name=)              → 201
  -F "file=@probe.bin"                            → 500（空消息）

**仍然真实存在、且是唯一限制的是 IIS `maxAllowedContentLength`（默认 30,000,000 字节）**：
927 KB / 14 MB / 16,372,427 B 通过；30.5 MB / 38,245,602 B / 40 MB 一律 HTTP 413。

文档更正：
- deploy/proxy/README.md 第九节重写 9.1（含"误判更正"小节）与 9.3（复验命令改用
  正确字段名），并给出两种可直接照抄的上传写法；
- DSH 开发文档 v1.6 §5.7 的"阶段二"表格改为"误判更正"记录；
- opendance-windows/tasks/014-full-package.md 同步更正并附正确上传命令；
- 本仓库 README.md/.txt 的 v0.7.3 说明补第 6 条。

验证：npm run verify 通过（22 文件 / 281 项测试 + 启动冒烟）；重新打包
opendance-web-v0.7.3.tar.gz（sha256 见 dist-release/SHA256SUMS）。
v0.7.3 		2026-09-17 03:39:36 +08:00
zijunchiang 828c7cea49 fix(scenes): 场景上传一律 400 —— diskStorage 却按内存存储判断 file.buffer 
现场（真实部署 v0.7.2，用 curl 对照验证过）：
  POST /api/models  → 201（同一份 multipart 文件）
  POST /api/scenes  → 400「上传场景必须带 file 字段（.glb 为主…）」
即**任何场景都传不上来**（冒烟脚本里 6 项场景断言全红）。

根因：上传中间件在 storage.module.ts 里配置为 multer 的 **diskStorage**
（先落 ${STORAGE_DIR}/tmp，避免 512 MiB 级 VRM 打爆内存），落盘后的文件对象
**只有 path、没有 buffer**；而 ScenesService.create() 当初按内存存储写：

  if (!file || !file.buffer || file.buffer.length === 0) { …400… }

file.buffer 恒为 undefined，于是必然 400。

修复：与 models/motions 统一到同一套上传处理
- requireUploadedFile(file)：校验确实落盘（path），并修正 busboy 按 latin1 解出的
  中文/日文文件名；
- 直接导入（.glb/.gltf）：storage.persistTempFile(AssetKind.Scene, upload.path, …)
  —— 归档并顺带清理临时文件；
- 需转换（.zip/.pmx/.fbx）：readFile(upload.path) 取 buffer 后转换 → persistBuffer，
  并在 finally 中 unlink(upload.path)；
- 体积上限用 upload.size 判断（UPLOAD_MAX_BYTES），超限 400 且不落盘；
- UploadedSceneFile 改为 UploadedFileLike 的别名（有 path 无 buffer）；
- 日志里的文件名改用解码后的 upload.originalname。

同时全局排查过同类写法：除这两处注释外，代码里已无按 file.buffer 处理上传的地方。

新增 test/scene-upload.spec.ts（5 项，修复前必失败）：diskStorage 形状的文件不再
被判成「缺少 file 字段」、GLB 直传标注未做重编码且落 pending、中文文件名被还原、
缺文件仍 400、超限 400 且不落盘。

文档：README.md/.txt 的 v0.7.3 说明补上这条；tasks/015-scene-management.md 增
「缺陷修复记录三」。

验证：npm run verify 通过（契约六项一致、35 条路由、22 文件 / 281 项测试、
nest build、启动冒烟）；重新打包 opendance-web-v0.7.3.tar.gz
sha256 07463a3b9f971346d0af1f73919e6e4dfa98ef20fd160419405d57272e9d4524。
 2026-09-17 03:28:31 +08:00
zijunchiang f3b97fec53 fix(scenes): 场景表不可用不再拖垮整站（生产事故修复）+ 诊断脚本 
现场（真实部署 v0.7.2）：数据库缺 scenes 表，于是
  /api/scenes、/api/scenes/:id、/api/catalog/export、/api/catalog/version、
  /api/reviews?status=pending 全部 500，而 /api/songs、/api/motions、/api/models
  正常。后果不是"场景不可用"，而是客户端拉不到任何目录（Windows/Android 全废）、
管理端待审列表打不开。`/health` 却显示 database.connected=true、
migrationsPending=0 —— 因为 DataSource.showMigrations() 只比较**代码里加载到的**
迁移；部署的 dist 若缺 AddScenes.js，该迁移不在比较集合里，于是"没有待执行迁移"
但表不存在（最隐蔽的一种不一致）。

修复思路：契约与文档都写明「场景是可选资源」（没有可用场景时客户端回退内置空
场景），所以场景表的问题不允许影响与场景无关的功能 —— 改为降级：

- ScenesService 新增 queryScenes() 包装：数据库层面失败时返回空结果，**只记一次
  日志**（避免刷屏），原因写入 diagnostics()；下一次查询成功即自动复位；
- ReviewsService.listByStatus() 对场景查询单独 catch，待审列表照常返回其它资源；
- /health 新增 scenes: { available, error } —— 降级但绝不静默；
- HealthModule 增加 imports: [ScenesModule]（HealthController 注入了 ScenesService，
  Nest 的 DI 按模块解析，漏了会直接 UnknownDependenciesException；
  scripts/check-bootstrap.mjs 已能拦住这一类）。

新增 web-server/scripts/diagnose-scenes.mjs（默认只读）：打印运行期真实连的库、
表清单、typeorm_migrations 记录、**代码实际加载的迁移**、scenes 实际列 vs 实体
期望列的逐列 diff；`--fix` 仅在缺表时用迁移里同一份 DDL 幂等补表。

顺带修正 models.controller.ts 的误导性注释：模型上传**不接受** isPrimary/status
（契约：上传一律 pending，默认模型由审核通过时带 setPrimary=true 或
POST /api/models/:id/primary 设定）。test/smoke.mjs 此前正是按错误预期断言
"isPrimary 已置位"，已改为：上传断言 pending + isPrimary=false → 审核通过时带
setPrimary=true → 再断言 isPrimary=true；同时给目录导出/指纹等检查补上失败细节
（HTTP 状态 + 响应体），并把待审列表查询的 pageSize 放大到 200（避免库里待审项多
时新条目被挤出第一页）。

文档：README.md/.txt 增加 v0.7.3 修订说明；tasks/015-scene-management.md 增
「缺陷修复记录二」；开发文档 §4.12 补充硬性要求（场景不可用必须降级 + /health 暴露
+ showMigrations 的陷阱说明）。

测试：新增 test/scenes-degradation.spec.ts（6 项）；npm run verify 通过
（契约六项一致、35 条路由、21 文件 / 276 项测试、nest build、启动冒烟）；
发布产物解压后 npm ci --omit=dev + node dist/main.js 实测打印「应用版本 v0.7.3」。

注意：Gitea 附件上传通道仍故障（1 KB 也瞬时 500），因此本版**尚未上传 Release**，
产物先在本地交付（sha256 见 SHA256SUMS）。
 2026-09-17 03:24:56 +08:00
zijunchiang 2224195d05 docs: 补齐部署必需的 Gitea 域名与属主（不再脱敏成占位符） 
域名与仓库属主属于「部署必需且非隐私」的信息，此前写成 `<Gitea 地址>` / `<owner>`
会让文档无法照做（照抄的 clone / 下载命令直接失败）。本次把它们补成真实值：
gitea.kasugano.cn / zijunchiang。口令、访问令牌、数据库口令等**秘密项**继续用占位符。

改动：
- README.md / README.txt：发布包下载地址补成真实 Release 地址
  （https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/vX.Y.Z/…），
  并写明域名与属主是部署必需信息、不是隐私项；
- README.md / README.txt：说明 `<服务器地址>` 是**部署方自己的**服务端地址
  （部署方决定），不是被脱敏的信息，避免与「被隐藏的域名」混淆；
- deploy/proxy/README.md：第九节的附件接口复验 curl 补成真实 Gitea 域名与属主；
  自检清单里 `<反代地址>` 加一行说明（你们自己的反代域名或 IP）；
- deploy/systemd/opendance-api.service：`Documentation=` 补成真实仓库地址。
 2026-09-17 03:07:23 +08:00
zijunchiang 50688e7ce4 test: 补目录导出交付逻辑与场景端到端冒烟（①/④ 的验收证据） 
目标 ④（场景管理）此前只有"上传/配置收敛"的测试，**没有任何测试覆盖
「场景是否真的随 catalog/export 下发到客户端」**；①（非 VRM 不进目录）也只有
实现没有断言。补上两层：

1. 新增 test/catalog-export.spec.ts（12 项，纯 mock、不依赖数据库）
   - ① 目录查询必须同时限定 status=published 与 format=vrm；
     /catalog/version 的模型查询同样只算 VRM；
     GLB/glTF/FBX 这类"未产出 VRM"的中间格式不得进入目录；
   - ④ exportBundle().scenes 来自 ScenesService.published()，且
     重力/风/地面/碰撞体等物理参数完整透传；无场景时是空数组而非 undefined；
   - ④ 场景新增/改名/换 GLB/更新时间变化都必须改变 catalog/version 指纹
     （否则客户端不会重新拉取）；
   - defaultModelId 透传与空值回退。

2. test/smoke.mjs 新增 [7] 场景管理端到端段（18 项断言），并在 [9] 清理：
   - 上传 GLB 场景 → 一律 pending、GLB 直传不重编码、glbUrl 生成；
   - 合法物理参数原样入库；越界参数（重力 -9999、摩擦 5）被夹紧到 -200/1；
     非法枚举（colliders/相机模式）回退默认值；
   - 缺少来源五元组 → 400；
   - **待审场景不出现在客户端目录**；审核通过后才进入 scenes[]，且带完整物理参数；
   - 目录指纹随场景发布而变化；GET /api/scenes/:id 与 ?status= 过滤可用。

   夹具可信性已单独验证：用**真实检查器**（inspectModelFile）解析 smoke 里同款
   构造方式生成的场景 GLB，得到 meshes=1 / vertices=3 / triangles=1 / nodes=1，
   证明该夹具是合法 GLB，而不是"写了个跑不通的脚本"。

顺带核查管理端构建产物：/scenes 路由、"场景管理"入口、"v0.7.2" 版本标签与
物理参数相关文案都在 bundle 中（Web 左下角版本号来自 package.json，见
scripts/check-version.mjs）。

验证：npm run verify 通过（契约六项一致、35 条路由一致、版本一致、
20 文件 / 269 项测试、nest build、启动冒烟）。
 2026-09-17 01:56:20 +08:00
zijunchiang 7037abf066 docs(proxy): 修正 Gitea 附件上传失败的结论——与体积无关，指向宿主机磁盘 
上一版把失败记成「两阶段 + 约 16.4 MB 边界」，那是**误判**：
当时磁盘正在被失败的请求逐步填满，所以看起来像有个体积阈值。补做与体积、
与仓库都无关的隔离测试后，结论要改：

- 1 KB 与 100 KB 也失败，且**瞬间**失败（0.14~0.3 s，不是读完请求体才判断）
  -> 不是 [attachment] MAX_SIZE 这类体积上限；
- opendance-web / opendance-windows / opendance-android 三个 Release 的资产
  上传接口**同样**失败 -> 与仓库无关；
- 创建 Release、PATCH Release 说明（纯 JSON）都成功 -> 只有「附件文件落盘」
  这条通道坏掉；
- 全部失败期间仍有 927 KB 的附件成功上传过一次 -> 间歇性。

最可能的原因：**Gitea 宿主机磁盘（或上传临时目录所在分区/tmpfs）几乎写满**
（Gitea 先把请求体写入数据目录的临时目录，空间不足时返回 500 而非 413）。

同时确认：IIS 那一关**已经放开且生效**（38,245,661 字节的请求体被完整接收，
不再 413），因此若仍失败应直接排查 Gitea 宿主机，而不是继续改 IIS。

deploy/proxy/README.md 第九节的 9.1 重写为上述隔离结论，并给出运维排查顺序
（df -h / Gitea 日志里的真实错误 / 清理临时文件 / 最后再改 MAX_SIZE）。

Windows 端 tasks/014-full-package.md 同步修正（原先的「16.4 MB 边界」表述作废）。
 2026-09-17 01:51:32 +08:00
zijunchiang 2433cd22a5 fix(boot): CatalogModule 漏 import ScenesModule 导致产物起不来 + /health 版本号错 
两个都是**只有真正启动服务才会暴露**的缺陷，v0.7.0 / v0.7.1 的产物受影响。

1. 【致命】CatalogModule 漏 import ScenesModule
   CatalogService 因为 catalog/export 要下发 scenes[] 而注入 ScenesService，但
   CatalogModule 的 imports 只列了 SongsModule / MotionsModule / ModelsModule。
   Nest 的 DI 按模块解析，于是 node dist/main.js 在 bootstrap 阶段直接抛
   UnknownDependenciesException: Nest can't resolve dependencies of the
   CatalogService (... ? ...) —— 服务完全起不来（装得上、起不来）。
   为什么三层检查全绿：nest build/tsc 看不出运行时 DI；258 项单元测试直接 new
   服务或测纯函数，从不编译 AppModule；打包脚本只校验文件清单与压缩包完整性。
   修复：CatalogModule.imports 补上 ScenesModule。

2. /health 的 version 在原生部署下永远是 0.1.0
   原实现 process.env.npm_package_version ?? '0.1.0'，而该变量只在 npm 脚本下
   存在；正式部署是原生服务（ExecStart=node dist/main.js），npm 不参与 ->
   恒为 undefined -> 回退到硬编码 0.1.0，与管理端左下角展示的 vX.Y.Z 冲突，
   违反文档 11.2 第 4 条「可核对：Web 端至少与 GET /health 的 version 一致」。
   修复：新增 src/config/app-version.ts 作为运行时唯一解析点
   （APP_VERSION -> 运行入口旁/工作目录的 package.json（带包名校验）
   -> npm_package_version -> 显式 0.0.0），/health 改用 resolveAppVersion()，
   main.ts 启动首行也打印版本号。新增 12 项测试，其中一项显式模拟无 npm
   环境变量的原生部署。

防线（都挂进了 verify 与打包脚本）
- scripts/check-bootstrap.mjs：以正式部署方式（node dist/main.js、无 npm 环境
  变量、不需要数据库）拉起真实产物，断言①无依赖解析类错误②启动日志的应用版本
  等于 package.json ③已推进到数据库连接阶段。已做反向验证：删掉 ScenesModule
  后该检查立刻失败。
- scripts/check-version.mjs（并入 contracts:check）：校验
  web-server/package.json = admin/package.json = project.yaml，正则禁止
  health.controller.ts 再出现硬编码版本回退，管理端已构建时断言产物 JS 含 vX.Y.Z。
- npm run verify 现在包含 bootstrap:check；package-release.sh 在构建后、打包前
  各跑一次（构建管理端后再跑 version:check，因为此时才需要校验产物内版本）。

文档：README.md / README.txt 增加 v0.7.2 修订说明；
tasks/011-version-display.md 与 tasks/015-scene-management.md 补「缺陷修复记录」
（含为什么当时没被发现的三层检查对照表）。

验证：npm run verify 通过（契约六项一致、35 条路由、258 项测试、nest build、
启动冒烟）；产物 opendance-web-v0.7.2.tar.gz
sha256 f04ecc85d17517ec00754238616eb1237cdb2fe17440af6dce731827c0922b26。
v0.7.2 		2026-09-17 01:49:52 +08:00
zijunchiang 698d60bb65 docs(proxy): 记录 Gitea 附件上传上限的两阶段实测（IIS 放开后仍是 500） 
按文档 §5.7 硬性要求 4「若用 A 方案，先在发布文档里记录实测上限」，把这次
Windows v0.2.0 整包（38,245,661 字节）发布的实测结果写进 deploy/proxy/README.md
第九节，并修正第九节里「只改 IIS 就够」的隐含假设：

第一阶段（IIS 未放开）：14 MB 通过；30.5 / 40 MB 返回 HTTP 413。
第二阶段（IIS 已放开）：38,245,661 字节的请求体被**完整接收**（115 s），
不再有 413 —— 说明 maxAllowedContentLength 已经够用；但随后 **Gitea 自己返回
HTTP 500**（响应体是 Gitea 的 API 错误信封，message 为空），瓶颈转移到了 Gitea 侧。

同接口边界测量：914 KB 与 16,372,427 B 通过；16,400,000 B 及以上失败；
且**在若干次大包失败之后，连 100 KB 都会在 0.3 秒内 500** ——
这不符合「上传体积上限」的特征（体积判断会先读完请求体），
更像上传临时目录 / 数据盘写满（Gitea 先写 data/tmp）。

因此文档明确要求运维按顺序查两件事：①Gitea 数据盘剩余空间（含 data/tmp，
以及它是否在小容量 tmpfs 上）并清理失败上传的残留临时文件；
②app.ini 的 [attachment] MAX_SIZE。并在 IIS 配置小节加醒目提示：
若放开 requestLimits 后仍为 500 而非 413，说明请求体已到达 Gitea，
要按上述两件事继续排查。
 2026-09-17 01:40:27 +08:00
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。
v0.7.1 		2026-09-17 01:30:41 +08:00
zijunchiang 50073b97cf docs(contracts): 补齐 rest-api 里 CatalogBundle.scenes[] 与 Scene/SceneConfig 结构 
`catalog/export` 自 v0.7.0 起就返回 `scenes[]`（catalog.service.ts 已实现，
data-models.md §7 也已冻结），但 rest-api.yaml 的 CatalogBundle 漏了这个字段，
且 components 里没有 Scene / SceneConfig 定义 —— 属于"实现已发布、规格漏写"。

本次只补规格，不改线格式，因此六个契约版本号均不变（rest-api 仍为 0.5.0，
与文档 v1.6 §5.6「客户端契约升级到 rest-api 0.5.0」一致）：
- CatalogBundle 增加 scenes[]（标注 0.5.0 起下发）
- 新增 Scene（含 glbUrl/thumbnailUrl/config/stats/来源五元组/status）
- 新增 SceneConfig（physics.gravity/wind/ground/colliders、environment、
  spawnPoints<=16、camera）与复用的 Vec3

注入依赖：Windows 端 T-WIN-013 需要按这份结构生成 GDScript 类型，
规格缺失会导致两端对字段边界（如 0~1、±200）的理解不一致。

同时补 deploy/proxy/README.md 第九节：托管 Gitea 的 IIS 站点
附件上传上限（与一~五节的 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（交付缺陷）。
 2026-09-17 00:46:35 +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。
v0.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 场景选择留待下一轮。
v0.6.0 		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。
v0.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。
v0.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。
v0.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）。
v0.2.5 		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 命令）。
v0.2.4 		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 容量约束。
v0.2.3 		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（它按发行版依赖对应的库版本）。
v0.2.2 		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 e9de740d66 chore(release): 打包脚本默认版本改为 0.2.1 v0.2.1 2026-09-15 22:27:16 +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 纳入发布包与关键文件校验。
v0.2.0 		2026-09-15 21:53:29 +08:00
opendance 60c182f1b2 docs: 消除 Gitea 模棱两可 Unicode 告警（全角标点紧邻 ASCII 时改为半角） 
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则
（analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记，
且 _common 表恒定生效），把说明文档中会被标记的全角标点
（，：；？！（） 等）改为半角，并保证成对括号宽度一致。
中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。

同时删除临时探针目录 _probe/（仅用于确认 Gitea 判定规则）。
 2026-09-15 21:45:51 +08:00
opendance a34cca007c chore(probe): add ambiguous-unicode probes for Gitea highlighter 2026-09-15 21:40:52 +08:00
zijunchiang d61843d068 test: 二分探针 round1（8 段） 2026-09-15 21:38:37 +08:00
zijunchiang f61d40eafc test: 临时 Unicode 探针（用于测定 Gitea 混淆字符判定规则，随后删除） 2026-09-15 21:37:23 +08:00
zijunchiang 06c2fd688b docs: 全角 ｜ ／ ？ 改 ASCII（Gitea 混淆字符检测的剩余触发项） 2026-09-15 21:36:41 +08:00
zijunchiang 6913e181b5 docs: 其余易混淆字符改 ASCII（× − ≥ ≤ ≈ ✓ 等），消除 Gitea 告警 
实测确认 Gitea 的「模棱两可 Unicode」检测覆盖：— – … § → × − ≥ ≤ ≈ ✓。
三库 .md/.txt 全部替换为 x - >= <= ~ OK；contracts 三库同源保持一致。
重新打包 v0.2.0。
 2026-09-15 21:35:10 +08:00
zijunchiang 5de0891706 docs: 修回被误压空格的 ':=' 写法；契约与文档去真实 MariaDB 版本串 
- contracts/websocket-keypoints.md（三库同源）：把上一轮空格清理误伤的
  'var x:= ...' 修回 'var x := ...'，保持文档内代码样例可读
- contracts/rest-api.yaml（三库同源）：'如 MariaDB 10.11.19' -> '如 MariaDB 10.5+'
- DSH.md / tasks/001：去掉真实部署实例版本号，改为'由部署方确认'的表述
- 重新打包 v0.2.0

验证：契约 6 项一致（三库 md5 相同）、30 条路由一致。
 2026-09-15 21:33:20 +08:00
zijunchiang 8c2f2afaea docs: 三库文档规范化（去混淆字符 + 占位符）+ Web README 初次部署清单 
- 三库所有 .md/.txt 与配置样例中的 — – … § → 一律换成 ASCII（Gitea 的
  「模棱两可的 Unicode 字符」告警即由这几个字符触发；中文全角标点不受影响，
  实测 README.txt 修正后告警消失）
- contracts/* 在三库保持逐字节一致（已校验 md5）
- 残留真实值清理：README.txt 建库 SQL 的 dpendance -> opendance/opendance_app，
  Android HostDiscovery.kt 注释示例 192.168.1.23 -> 192.0.2.23
- Web README.txt 新增「初次部署（从零跑起来）」8 步清单与「常见问题（初次部署）」
  7 条；去掉纯文本 README 里的 markdown 粗体标记；统一 '以 root 直接执行' 写法
- 重新打包 v0.2.0

验证：168 项单测通过；契约 6 项与 30 条路由一致。
 2026-09-15 21:28:12 +08:00
zijunchiang ebd871018f docs(readme): 新增初次部署清单与常见问题；统一 root 执行写法；清除 markdown 粗体标记与残留真实库名 2026-09-15 21:27:29 +08:00
zijunchiang 9c8379e5eb docs(readme): 破折号/箭头/省略号/节号改 ASCII，消除 Gitea 混淆字符告警 2026-09-15 21:25:56 +08:00
zijunchiang 9f08d316d0 docs: 清除文档中的真实部署信息与易混淆 Unicode 字符 
需求：公开仓库的说明文档不应暴露开发/部署期信息，且 Gitea 会对 README.txt
报"含模棱两可的 Unicode 字符"。

敏感信息（全部替换为占位符或文档示例值）：
- 真实数据库实例：DB_HOST=192.168.150.10 / DB_USER=dpendance / DB_NAME=dpendance
  → <数据库主机> / opendance_app / opendance（web-server/.env.example、
  deploy/.env.example、contracts/database.md ×3 库、project.yaml、README.txt
  的建库 SQL、tasks/001、tasks/002）
- 内网网段 192.168.150.0/24 / 192.168.150.20 / 192.168.1.10
  → RFC 5737 文档网段 192.0.2.0/24 等（含测试夹具，行为不变）
- 真实 Gitea 域名 → https://<Gitea 地址>/<owner>/<repo>（systemd 单元、
  Windows/Android README 的交叉链接）
- 测试夹具里的真实口令字面量 → 虚构口令（仍覆盖特殊字符场景）
- 保留 /opt/opendance、/var/lib/opendance 等产品默认安装路径（非敏感）

README.txt 易混淆字符：
- 全角拉丁字母（Ｉ/Ｋ 等）与全角 ASCII 标点（（），：；？）→ 半角 + 中文排版空格
- 正文里的乱码字节样例（模å…）→ 改为文字描述
- × → x，★ → *
- 注意：代码/测试/契约里的全角「ＩＫ」是 MMD 真实骨骼名，**必须保留**，
  已回滚误改（mmd-skeleton.ts、mmd-vmd.spec.ts、inspect-vmd.mjs、各契约）

验证：168 项单测通过（含 VMD 31 项，确认全角骨骼名未被破坏）。
 2026-09-15 21:25:25 +08:00
zijunchiang c342a804a1 feat(models): 新增历史模型回填（reanalyze）并修复存储去重的悬挂文件问题 
背景：升级到带 models.stats 的版本后，库里已有模型没有分析与缩略图，
审核界面会全部显示"未分析、无预览图"。E2E 验证时还发现一个真问题：
sha256 去重命中旧资产但文件不存在（换过 STORAGE_DIR、或只恢复数据库）时，
分析会静默产出"全 0 结果"。

- POST /api/models/:id/reanalyze：重新分析（面数/骨骼树/humanoid/可驱动性）
  并重建缩略图，只改 stats 与 thumbnailAssetId；文件在存储中不存在时返回 409，
  避免用空结果覆盖已有分析数据
- scripts/reanalyze-models.mjs：批量回填 CLI（--dry-run / --model-id / --force）
- StorageService.persistBuffer：去重命中但文件不存在时按原路径**自愈补写**
- 契约：rest-api 新增 /api/models/{id}/reanalyze（路由 29 → 30 条）
- 文档：README / tasks/005 / 发布说明补回填章节与升级步骤

实测：真实 21MB VRM（290 骨骼）回填出面数 53552 / 顶点 44662 / humanoid 7/22，
并重建 512×512 缩略图；文件缺失场景返回 409 且不覆盖既有数据。
测试 168 项通过；契约与 30 条路由一致。
 2026-09-15 21:18:15 +08:00
zijunchiang 53bf182476 feat(models): 发布 v0.2.0 —— GLB/VRM 主力格式、自动缩略图与分析、模型审核与骨骼预览 
需求 1：系统确定以 GLB / VRM 为模型主力格式
- 服务端新增支持库：
  - model-inspector.ts：解析 GLB/VRM 的面数、顶点、材质、贴图、形变目标、
    **骨骼树（名称/层级/是否蒙皮/humanoid 映射/子节点数）**、humanoid 覆盖率与可驱动性
  - model-thumbnail.ts：**纯 TS 软件光栅化**（z-buffer + Lambert + 完整蒙皮矩阵）
    生成 512×512 PNG 缩略图，零原生依赖、不装 headless-gl
  - vrm-writer.ts：GLB → VRM 1.0（写入 VRMC_vrm 扩展与 humanoid 映射）
  - gltf-packer.ts：glTF（.gltf + .bin + 贴图）→ 单文件 GLB
- humanoid 候选表与 Godot 客户端 humanoid_map.gd **逐字对齐**，并有单测断言两边一致
  （服务端判定的"可驱动" = 客户端实际能否驱动）

需求 2：模型管理
- .glb / .vrm / .gltf **直接导入**（不重编码，GLB 含 VRM 扩展会自动识别为 VRM）
- .pmx / .fbx 服务端转换：assimp → .glb →（失败）→ .gltf 后自行打包成 GLB
  →（MODEL_CONVERT_FORMAT=vrm 时）补 VRMC_vrm 产出 VRM 1.0；每步 assimp info 回读校验
- .zip **自动搜索包内可用模型**：.vrm → .glb → .gltf（直接导入）优先，
  其次 .pmx → .fbx（转换）；同优先级内按"指名字 → 目录最浅 → 文件最大"
- 入库后自动分析（models.stats）与生成缩略图（models.thumbnail_asset_id），
  失败均不阻断入库；管理端列表显示小缩略图、预览放开到 vrm/glb/gltf

需求 3：审核功能
- 上传的模型状态**一律 pending**（不再自动发布、不再自动设默认）
- 审核界面新增模型面板：体积、面数、顶点、材质、贴图、骨骼、形变目标等指标，
  humanoid 覆盖进度、可驱动性结论（缺哪些必需骨骼）、warnings，以及
  **骨骼详细预览**（层级缩进、蒙皮/Humanoid 徽章、子节点数、搜索保留祖先链、
  仅看蒙皮、限高滚动 + 只渲染前 400 行）
- 审核通过可带 setPrimary=true 一并设为默认模型（此时才写源码种子）；
  POST /api/models/:id/primary 仅允许 published（否则 409）
- scripts/import-default-model.mjs 改为"上传 → 审核通过 + 设默认"流程

其它：
- models 新增 stats 列（迁移 AddModelStats1789460000000，已在真实库执行）
- 契约升至 rest-api/data-models/model-formats 0.4.0、database 0.3.0（另两库已同步）
- 版本号 0.1.0 → 0.2.0（package.json ×2 + lockfile + project.yaml）
- 文档：README.txt / DSH.md / project.yaml / tasks 005·007·010 全面更新；
  顶层开发书更新为 v1.4

验证：168 项单测通过（10 文件）；契约 6 项与 29 条路由一致；typecheck/build 通过；
真实端到端：MMD 压缩包 → GLB + 分析(面数 9071/骨骼 238/humanoid 0-22) + 缩略图(15KB PNG)；
GLB 直接导入 sha256 与源文件一致；审核通过后 defaultModelId 由 VRM 变为该模型
 2026-09-15 20:37:53 +08:00
zijunchiang ccced34dd6 fix(models): 默认模型改用「压缩包 sha256」匹配（转换产物非字节级确定） 
实测发现：同一份 zip 连续转换三次得到三个不同的产物 sha256（大小都是 1,152,464
字节，差异集中在 BIN chunk 的十几字节），说明 Assimp 的 GLB 导出不是字节级确定的。
因此原先把「转换产物 sha256」当作默认模型匹配键的设计是错的——换一次转换就失效。

- default-model.ts / default-model-source.ts：种子拆成 sourceSha256（上传压缩包的
  sha256，稳定，主匹配键）与 fileSha256（产物 sha256，仅作记录）
- models.service.ts：resolveDefaultModelId 依次按 压缩包 sha256 → 产物 sha256 →
  名称 匹配，都落空才回落到 VRM 优先规则并告警
- ModelDto 增加 sourceSha256（非压缩包上传为 null）
- scripts/import-default-model.mjs：写种子时用 sourceSha256；顺带修掉位置参数解析
  （文件当第一个参数时识别不出，会打印用法）
- 契约与文档同步：data-models §4.1、model-formats §1.1 记录该确定性结论；
  README / DSH / tasks/005 的「按产物 sha256 匹配」表述已更正

另附：把模型格式能力的实测矩阵写进 Release 说明（原生只支持 glTF 系；
PMX→FBX 失败；VRM→GLB 丢 VRM 扩展；humanoid 骨骼命名覆盖率）。

验证：125 项单测通过；清理掉两个"文件只在本机临时目录"的模型（避免 sha256 去重
导致后续上传不落盘）；种子按压缩包 sha256 命中后 defaultModelId 正确解析。
 2026-09-15 19:36:37 +08:00
zijunchiang e4351c5062 feat(models): 模型压缩包自动转换 + 默认模型写进源码；首次启动 .env 引导；HOST 默认 0.0.0.0 
需求 1：模型上传支持压缩包（MMD 模型包）
- common/zip-reader.ts：纯 TS 极简 ZIP 读取器（EOCD/中央目录、STORE+DEFLATE、
  ZIP64 大小字段、Shift-JIS/GBK 文件名回退、拒绝 zip-slip 与加密条目）
- models/model-convert.ts：解压 → 选主模型（指名字/最浅/最大）→ Assimp 导出 FBX
  → **assimp info 回读校验**（Assimp 对带蒙皮大骨架模型会写出损坏文件：
  实测 714 骨骼 PMX 导出退出码 11、产物回读报 FBX-DOM no Objects dictionary found）
  → 失败自动回退 GLB；两种都失败则 422
- models/glb-textures.ts：把 Assimp 写成外部 URI 的贴图内嵌进 GLB 的 BIN chunk，
  保证模型库里单文件即可加载（否则是白模）
- 溯源：压缩包原件存为 model-archive 资产；models 新增 source_asset_id /
  conversion_note（迁移 1789450000000-AddModelConversionFields，已在真实库上
  验证 up/down 可逆）
- 默认模型：转换成功且 autoDefault 不为 false → is_primary=1 + published，
  并把身份（名称/格式/产物 sha256）写进源码 src/config/default-model.ts；
  resolveDefaultModelId 增加 DEFAULT_MODEL_ID 与源码种子两步（按 sha256 匹配，
  换库仍有效），实测库中有 2 个 VRM 时默认模型仍解析为该 GLB
- scripts/import-default-model.mjs：运维 CLI（上传 zip 并写源码 / --write-source-only）
- 修复 multipart 中文文件名乱码（upload.util.decodeUploadName）
- DTO/契约新增 conversionNote、fileSha256；管理端 accept 增加 .zip 并展示转换来源

需求 2：首次启动 .env 引导
- deploy/init-env.sh：交互式逐项填写 8 个键（回车保留默认、口令不回显不加引号、
  端口校验、mysql2 连通性自检且口令只经环境变量传递、只改这 8 个键并保留模板注释、
  chmod 600、结尾打码摘要）；--force/--check/-y/-i/--skip-db-check 等开关；
  非交互（-y、OPENDANCE_NONINTERACTIVE、stdin 关闭）绝不提问、读取带超时
- install.sh 缺 .env 时改为调用引导，失败才 die

需求 3：默认监听 0.0.0.0
- 代码默认值、两份 .env 模板、install.sh、init-env.sh 五处一致，并新增测试守护
  （未设置 HOST 时为 0.0.0.0；两份模板都写着 HOST=0.0.0.0）

契约：rest-api / data-models / model-formats → 0.3.0，database → 0.2.0（另两库已同步）

验证：125 项单测通过（7 文件）；契约 6 项与 29 条路由一致；typecheck/build 通过；
真实包端到端 HTTP 201 / 0.89s / format=glb / isPrimary=true / published；
GLB 1,152,464 字节、1 mesh / 240 nodes / 1 skin(238 joints) / 2 张内嵌贴图；
迁移 revert→run 实测可逆且数据无损恢复
 2026-09-15 13:55:54 +08:00
zijunchiang bba5bcf59e feat(web): 端口分离 + VMD 动作支持；契约升至 0.2.0 
需求 1：管理端端口与软件 API 端口分离
- 软件 API 端口 PORT（默认 3000）只提供 /api、/health、/static、/contracts，
  不提供管理页面（未命中路径 404）；管理端端口 ADMIN_PORT（默认 3001）
  提供管理页面与全部接口；ADMIN_HOST 可单独限制管理端来源
- main.ts 同进程监听两个端口，用 req.socket.localPort 区分端口行为；
  ADMIN_PORT=PORT 为单端口兼容模式（只创建一个 server，无 EADDRINUSE）
- 端口非法在生产环境中止启动；ADMIN_PORT=PORT 只 warn
- 启动日志分别打印两个端口的访问地址

需求 2：动作数据支持 VMD（MikuMikuDance）
- vmd-parser.ts：二进制解析（30 字节头 + Shift-JIS 模型名 + 111 字节/条骨骼
  关键帧 + morph 段）、MMD 贝塞尔插值、GBK 模型名回退、固定 30fps
- mmd-skeleton.ts：标准 MMD 骨架；静止比例从参考 PMX 骨骼段实测得到
  （足首 1.43 / 膝 6.57 / 髋 11.50 / 首 16.21 / 頭 17.16，腿长 10.09）
- mmd-pose.ts：FK + 两骨骼解析腿部 IK（膝盖朝正面，不可达收敛为伸直）
  + 左手系→右手系 Z 镜像（由真实数据对照实验确定：94.1% vs 5.9%）
- retarget.ts：抽出 worldFramesToKeypointFrames()，BVH 与 VMD 共用重定向
- MotionFormat 增 vmd、扩展名映射增 .vmd；管理端上传支持 .vmd
- scripts/inspect-vmd.mjs：上传前自查工具

契约：rest-api / data-models / model-formats → 0.2.0（另两库已同步逐字节一致）

验证：85 项单测通过（VMD 31 项）；契约与 29 条路由一致；typecheck/build 通过；
真实样本经 HTTP 端到端：霜雪千年 2901 帧（IK 腿）、恋爱循环 4604 帧（FK 腿）
均 preprocessState=done、0 NaN、0 越界（测试数据已从数据库清理）。
 2026-09-15 08:47:37 +08:00
zijunchiang 76725e5ce3 feat(log): 启动日志打印真实可访问地址，回环绑定时显式告警 
绑定 0.0.0.0 时日志直接拼 http://0.0.0.0:3000——浏览器打不开，
排障时只会看到"已启动"却不知道访问哪个 IP。

- 新增 src/config/access-hint.ts：describeAccess() 把绑定地址翻译成
  监听描述 + 可访问地址（回环 / 具体网卡 / 通配取真实网卡 IPv4）；
  独立成模块是为了可测——main.ts 顶层会执行 bootstrap()，不能被 import
- main.ts：启动日志改为「监听 …（全部网卡，外部可访问）」+ 真实访问地址；
  HOST=127.0.0.1 时用 warn 明确提示"只能本机访问"并给出修复方法
- 新增 test/access-log.spec.ts（4 项）覆盖三种绑定模式，
  断言通配模式绝不出现 0.0.0.0 形式的 URL

实测三种模式日志输出正确；单测 35/35、契约与 29 条路由校验通过。
 2026-09-15 02:04:51 +08:00
zijunchiang 44451028dd fix(deploy): 安装脚本按真实 HOST 报告监听地址，并主动提示外部不可达 
背景：旧版 .env.example 的 HOST=127.0.0.1 会让服务只监听回环，
本机 curl 一切正常、安装日志毫无异常，但外部永远连不上。

install.sh 修复：
- 不再写死 API_HOST=127.0.0.1：从 deploy/.env 读 HOST 得到 BIND_HOST，
  绑定具体网卡时用该地址做健康检查（原来用回环会误判启动失败）
- 汇总输出改为真实监听地址 + 按三种绑定模式给出正确 URL
  （回环写 127.0.0.1、具体网卡写该地址、通配写探测到的对外 IP）
- 新增安装期外部可达性自测：用对外 IP 请求 /health，
  只监听回环 → 打印改 HOST 与重启命令；
  监听正常但自测失败 → 打印防火墙 / 云安全组放行步骤
- 反代提示里回显当前 HOST 实际值，避免照抄"建议 127.0.0.1"改坏配置

README.txt 同步说明。验证：用真实脚本片段 + 打桩跑四种场景
（回环 / 通配可达 / 通配被防火墙拦 / 指定网卡），输出逐一核对。
 2026-09-15 01:48:04 +08:00
zijunchiang 34c5040e6b feat(deploy): 新增外部访问诊断脚本 check-access.sh 
"服务已启动但外部访问不了"时一次性定位原因，只读诊断、不改配置：
- 读出 .env 的 HOST/PORT，并对 127.0.0.1 这种只监听回环的配置直接报错
- 检查实际监听地址（ss/netstat），区分通配与仅回环
- 回环 + 对外 IP 两次 /health 自测（用 ip route get 取真实出口 IP）
- 检查 80/443 上有没有反向代理，并说明本项目不部署反代
- 检查 firewalld / ufw / iptables 对端口的放行情况，给出修复命令
- 结尾按"直连后端"与"经反代"两条路径给出结论

同时更新 README.txt、deploy/proxy/README.md（新增第八节：还没有反代时
如何直连后端）与打包校验清单。
 2026-09-15 01:43:35 +08:00
zijunchiang 321ab1f584 docs(web): 清理 Docker/nginx 残留引用，反代职责边界写进任务书与契约 
- tasks/010-deploy.md: 按"仅业务服务、不部署反代、服务自托管管理端"重写，
  补充四层进程降级、无 sudo 降权、上传上限两侧一致等实现说明与验收表
- deploy/uninstall.sh: 删除 nginx 站点清理逻辑（本项目从未安装过反代，
  也不应改动运维侧的 nginx / IIS 配置）
- scripts/package-release.sh: 修正产物结构注释，去掉已删除的
  web-server/admin/nginx.conf 拷贝与 deploy/nginx 备份清理
- web-server/.env.example: 修正"容器内路径 / docker-compose 挂载"过时注释
- contracts/rest-api.yaml: 服务地址描述改为业务服务部署语义
 2026-09-15 01:27:47 +08:00
zijunchiang 8c76b0a599 feat(web): 移除 Docker 与反代部署，改为 Linux 业务服务并自带管理端托管 
需求变更：Web 端只保留业务需求，反向代理交由另外的服务处理，
本项目仅提供 IIS / nginx 反代说明文档，不部署反代。

主要改动：
- web-server: 新增管理端静态托管（ADMIN_DIR、SPA 深链接回退），
  反代因此只需一条全匹配转发规则；新增 adminDir 配置项
- deploy/install.sh: 删除 nginx 安装与站点配置逻辑，改为原生 Linux
  服务部署（systemd → OpenRC → SysVinit → 后台进程四级降级），
  打印反代交接指引
- deploy/ctl.sh: 启停/状态/日志脚本
- deploy/proxy/: 新增反代说明文档（README.md、nginx.conf.example、
  web.config.example），标注上传上限与超时必须同步调整
- 删除 deploy/nginx/、web-server/admin/nginx.conf、Dockerfile、
  docker-compose.yml、.dockerignore
- scripts/package-release.sh: 锚定排除规则 + 产物完整性校验
- 文档同步：README.txt、DSH.md、project.yaml、tasks/008、tasks/010
 2026-09-15 01:25:19 +08:00
zijunchiang 653d9d168c feat(deploy): 缺少 deploy/.env 时复用安装目录中的历史配置 
用户在重新解压发布包后再次执行 install.sh，因缺少 deploy/.env 被拦下。
按文档流程每次升级都要重新解压，若每次都要求重填数据库口令，既繁琐
又容易出错（口令含 * 等特殊字符）。

- 优先使用当前目录的 deploy/.env
- 其次复用 $APP_DIR/deploy/.env（上次安装留下的配置）
- 两处都没有才报错，且错误信息列出需要填写的五个字段及注意事项

实测三种情形：
  全新安装（两处都无）→ 报错并给出字段说明，退出码 1
  安装目录有历史配置   → 自动复用，退出码 0
  当前目录已有 .env    → 直接使用，不覆盖
 2026-09-15 01:03:20 +08:00
zijunchiang 87a1ded2d2 fix(deploy): install.sh 复制时同样误排除了 storage 目录 
用户重装后仍报同一错误，且日志显示「复制 web-server … 174 个文件」。
经复现：发布包内 web-server 有 180 个文件（含 src/storage 2 个、
dist/storage 4 个），但 install.sh 复制后只剩 174 个——storage 被剔除了。

根因：上一轮只修了 package-release.sh，install.sh 里**还有一份独立的
copy_tree() 排除规则**，其中 'storage' 同样未锚定。install.sh 的
COPY_EXCLUDES 与 tar 回退分支都把 'storage' 当作任意层级模式，
于是 src/storage 与 dist/storage 在复制进 /opt/opendance 时被剔除。

这是同一类错误在本项目的第三次（.gitignore → package-release.sh →
install.sh）。因此这次不再只改模式，而是把语义显式化并加硬校验：

- 排除规则拆成三类常量，语义明确：
    TOP_DIRS  仅顶层：storage data tmp dist-release   → 必须锚定
    ANY_DIRS  任意层级：node_modules .git coverage .gradle
    TOP_FILES 仅顶层文件：.env .env.local
- rsync 用前导 '/' 锚定；tar 对 TOP_* 只给 './x'（绝不给 '*/storage'），
  对 ANY_* 才给 './x' + '*/x'
- 复制后硬校验关键产物（dist/main.js、dist/storage/storage.module.js、
  dist/app.module.js、admin/index.html），缺失即 die 并指出是排除规则问题

实测：
- rsync 路径：180 文件，src/storage 与 dist/storage 均在，
  运行时 storage 与 .env 未带入，.env.example 保留
- tar 回退路径（隔离 PATH 屏蔽 rsync 后真跑）：同样 180 文件，存储目录完整
- git 检出布局：214 文件，嵌套 admin/node_modules 未带入，本地 .env 未带入
- 对照实验：把锚定改回未锚定 → 复制剩 174 文件 → 守卫立刻报
  「缺少关键文件 dist/storage/storage.module.js」并终止，不再拖到启动才炸
 2026-09-15 01:00:58 +08:00
zijunchiang caca7672cb fix(release): 修复发布包缺失 storage 模块，并加入产物完整性校验 
用户实测：用发布包部署后启动报 MODULE_NOT_FOUND
  at dist/models/models.module.js:13  require('../storage/storage.module')

根因：package-release.sh 的 rsync 用了 --exclude 'storage'。该模式匹配
**任意层级**的同名目录，把源码目录 src/storage/ 与编译产物 dist/storage/
一并排除——发布包里完全没有 storage 模块，服务必然起不来。
这与第一阶段 .gitignore 里 'storage/' 误伤 src/storage/ 是同一类错误，
本项目第二次踩到。

修复：
- 排除模式全部锚定到 web-server 根：'/storage/'、'/data/'、'/tmp/'、
  '/.env'、'/admin/'，不再匹配嵌套同名目录
- 新增产物完整性校验（打包后自动执行，失败即删除压缩包）：
  src 下每个 .ts 必须有对应 dist/*.js；关键文件清单齐全；
  不得混入 node_modules / 真实 .env / 运行时存储 / keystore
- ctl.sh 补上缺失的 warn 函数（line 120: warn: command not found）

实测：
- 对照实验：排除模式改回 'storage' 后校验准确报出缺少
  dist/storage/storage.module.js 并删除压缩包，退出码 1
- 新包端到端：解压 → npm ci --omit=dev（213 包）→ 启动 → /health 200、
  MariaDB 已连接、迁移 0、catalog/songs/models/motions 全部 200
 2026-09-15 00:54:22 +08:00