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
parent bba5bcf59e
commit e4351c5062
34 changed files with 3204 additions and 65 deletions
@@ -31,6 +31,8 @@ opendance-web  ←── 本仓库
 | 管理前端 | React 18 + Vite + TypeScript |
 | 3D 预览 | three.js + @pixiv/three-vrm |
 | 多格式解析 | BVH / VMD 内置纯 TS 解析器；FBX/glTF 走可选外部 Assimp |
+| 模型压缩包 | 纯 TS ZIP 读取器（`common/zip-reader.ts`）+ 外部 Assimp 转换（`models/model-convert.ts`）；GLB 贴图内嵌见 `models/glb-textures.ts` |
+| 默认模型种子 | `web-server/src/config/default-model.ts`（服务端/CLI 写入，运行期只读） |
 | 认证 | **本版本不含认证**（内网部署）；上线前须补 ≥ T-WEB-011 |

 ## 3. 单次会话加载范围
@@ -70,23 +72,34 @@ opendance-web/
 │   ├── VERSION                  # 契约版本（唯一来源）
 │   ├── rest-api.yaml            # OpenAPI 3.0
 │   ├── websocket-keypoints.md   # 239 字节关键点帧 + 控制消息
-│   ├── data-models.md           # 资源字段与 VRM 优先规则
+│   ├── data-models.md           # 资源字段与默认模型选择规则
 │   ├── skeleton-topology.md     # MediaPipe 33 点拓扑 + 关节角
 │   ├── model-formats.md         # 支持格式、预处理产物、上传限制
 │   ├── database.md              # 现有 MySQL 连接与迁移约定
 │   └── open-source-credits.md   # 开源声明锚点（三端共用）
 ├── web-server/                  # NestJS 服务端
-│   ├── src/                     # 源码（entities / modules / preprocess）
+│   ├── src/                     # 源码（entities / models / preprocess）
+│   │   ├── common/zip-reader.ts # 纯 TS ZIP 读取器（STORE/DEFLATE、ZIP64、zip-slip 防护）
+│   │   ├── models/              # 模型上传 + 压缩包转换 + VRM 识别
+│   │   │   ├── model-convert.ts         # 解压 → 选 PMX → Assimp → 回读校验 → 回退
+│   │   │   ├── glb-textures.ts          # 把外部贴图内嵌进 GLB 的 BIN chunk
+│   │   │   ├── default-model-source.ts  # 渲染 / 写入 src/config/default-model.ts
+│   │   │   └── vrm-inspector.ts
+│   │   ├── config/default-model.ts      # 默认模型种子（由服务端/CLI 写入，运行期只读）
+│   │   ├── migrations/          # TypeORM 迁移（含 AddModelConversionFields）
 │   │   └── preprocess/          # BVH / VMD / FBX → MediaPipe33
 │   │       ├── vmd-parser.ts    # VMD 二进制 + Shift-JIS + 贝塞尔插值
 │   │       ├── mmd-skeleton.ts  # 标准 MMD 骨架（静止比例实测自参考 PMX）
 │   │       ├── mmd-pose.ts      # MMD FK + 两骨骼腿部 IK + 左手系→右手系 Z 镜像
 │   │       └── retarget.ts      # worldFramesToKeypointFrames()：BVH / VMD 共用
 │   ├── admin/                   # React 管理端
-│   ├── test/                    # 单元测试 + 端到端冒烟（含 mmd-vmd.spec.ts）
+│   ├── test/                    # 单元测试 + 端到端冒烟
+│   │                            #   （mmd-vmd / model-archive / init-env / admin-port …）
 │   └── scripts/                 # migrate.mjs / check-contracts.mjs / check-routes.mjs
-│                                #   / inspect-vmd.mjs（VMD 诊断工具）
+│                                #   / inspect-vmd.mjs（VMD 诊断）
+│                                #   / import-default-model.mjs（默认模型导入 / 补写源码）
 ├── deploy/                      # ★ 业务服务部署（不含 MySQL、不含反代）
+│   ├── init-env.sh              # ★ 首次启动的 .env 交互引导（install.sh 缺 .env 时调用）
 │   ├── install.sh               # 一键部署（systemd / OpenRC / SysVinit / 后台进程）
 │   ├── uninstall.sh
 │   ├── ctl.sh                   # 无 init 系统时的进程控制
@@ -146,18 +159,23 @@ git push origin task/T-WEB-0XX

 ## 8. 环境变量

-见 `web-server/.env.example` 与 `deploy/.env.example`。生产关键项：
+见 `web-server/.env.example` 与 `deploy/.env.example`。首次部署的 `deploy/.env`
+可由 `deploy/init-env.sh` 交互生成（见 §12）。生产关键项：

 ```
 DB_HOST DB_PORT DB_USER DB_PASS DB_NAME
 DB_SYNCHRONIZE=false
 PORT=3000                   # 软件 API 端口（客户端调用，不含管理页面）
 ADMIN_PORT=3001             # 管理端端口（默认 PORT + 1；等于 PORT 为单端口兼容模式）
-HOST=0.0.0.0                # 软件 API 监听地址
+HOST=0.0.0.0                # 软件 API 监听地址（未设置时默认即 0.0.0.0）
 ADMIN_HOST=0.0.0.0          # 可选，管理端监听地址，默认跟随 HOST
 STORAGE_DIR=/data/storage
 UPLOAD_MAX_BYTES=536870912
-ASSIMP_BIN=assimp           # 可选
+ASSIMP_BIN=assimp           # 可选；上传 .zip 模型包时必需
+MODEL_CONVERT_FORMAT=fbx    # 压缩包首选格式；导出后回读校验，失败自动回退 glb
+MODEL_CONVERT_PMX="Hatsune Miku.pmx"  # 优先选用的 PMX 文件名（大小写不敏感）
+MODEL_CONVERT_TIMEOUT_MS=180000
+DEFAULT_MODEL_ID=1          # 可选；未设置时按 src/config/default-model.ts 的种子匹配
 CONTRACTS_DIR=/contracts    # 可选，读取实时契约版本
 ```

@@ -199,7 +217,69 @@ CONTRACTS_DIR=/contracts    # 可选，读取实时契约版本
  （打印头部/模型名/帧数/轨道数、未识别骨骼、IK 还是 FK、关键点序列异常统计、膝肘角分布）。
 - 契约 `contracts/model-formats.md` §2.3；测试 `test/mmd-vmd.spec.ts`（31 项）。

-## 11. 上下文超标时的拆分策略
+## 11. 模型压缩包转换（.zip → FBX / GLB）与默认模型种子
+
+```
+.zip（MMD 包）─▶ zip-reader.ts ─▶ pickModelFile() ─▶ model-convert.ts ─▶ glb-textures.ts
+                 中央目录/EOCD    优先 MODEL_CONVERT_PMX   Assimp 导出       GLB 贴图内嵌
+                 STORE+DEFLATE    否则目录最浅、文件最大   + info 回读校验
+                 拒绝 zip-slip/加密                       失败回退 FBX → GLB
+```
+
+- `POST /api/models` 的 `file` 也接受 **`.zip`**，视为 MMD 模型包；只认包内 `.pmx`。
+- 新增模块（均在 `web-server/src/`）：
+  - `common/zip-reader.ts`：纯 TS 极简 ZIP 读取器（中央目录/EOCD、STORE+DEFLATE、
+    ZIP64 大小字段、Shift-JIS/GBK 文件名回退、拒绝 zip-slip 与加密条目、
+    不支持的压缩方式报错）。
+  - `models/model-convert.ts`：解压 → 选主模型 → Assimp 转换 → 回读校验 → 回退。
+  - `models/glb-textures.ts`：把 GLB 里 Assimp 写成外部 URI 的贴图内嵌进 BIN chunk。
+  - `models/default-model-source.ts`：渲染 / 写入 `src/config/default-model.ts`。
+  - `config/default-model.ts`：默认模型种子（服务端/CLI 写入，运行期只读）。
+- **选主模型**：优先 `MODEL_CONVERT_PMX`（默认 `Hatsune Miku.pmx`，大小写不敏感）；
+  否则取目录最浅、其次文件最大者。
+- **转换与回退**：先试 `MODEL_CONVERT_FORMAT`（默认 `fbx`）；**导出后必须用
+  `assimp info` 回读校验**，失败自动回退 `glb`，两次尝试写进 `conversion_note`。
+  实测 Assimp 6.0.4 对 714 骨骼的 Miku PMX 导出 FBX 失败（退出码 11，产物回读报
+  `FBX-DOM no Objects dictionary found`），实际入库为 GLB。
+- **默认模型**：转换成功且 `autoDefault` 不为 false（默认 true）→ `is_primary=1` +
+  `status=published`，并把身份写进源码种子；`GET /api/catalog/export` 的
+  `defaultModelId` 解析顺序为 `DEFAULT_MODEL_ID` → 源码种子（按产物 sha256 匹配）
+  → 已发布且 is_primary 的 VRM → 任意已发布 VRM → id 最小的已发布模型。
+- **溯源**：压缩包原件存为 `model-archive` 资产，记入 `models.source_asset_id`
+  （迁移 `AddModelConversionFields1789450000000`）；`models.conversion_note` 记转换说明。
+- **失败**：包内没有 `.pmx`、Assimp 不可用、两种格式都失败 → **HTTP 422**，
+  不产生模型记录。
+- **文件名编码**：`common/upload.util.ts` 的 `decodeUploadName()` 修正 multipart
+  文件名的 latin1/UTF-8 乱码（中文文件名原先存成 `æ¨¡å_…`）。
+- 契约：`contracts/model-formats.md` §1.1、`contracts/data-models.md` §4.1；
+  DTO 新增 `conversionNote` / `fileSha256`；测试 `test/model-archive.spec.ts`（22 项）。
+
+## 12. 首次启动的 .env 引导（deploy/init-env.sh）与监听地址
+
+- `deploy/init-env.sh`：交互式逐项询问 `DB_HOST / DB_PORT / DB_USER / DB_PASS /
+  DB_NAME / PORT / ADMIN_PORT / HOST`，回车保留默认；口令 `read -rs` 不回显、
+  按约定写盘不加引号；校验必填与端口范围；可用 Node + mysql2 做连通性自检
+  （口令只经环境变量传递、失败仅告警）；只替换/追加这 8 个键、保留模板注释，
+  写完 `chmod 600` 并回读校验；结尾打印摘要（口令 `***`）与变更列表。
+- 开关：`--force` / `--check` / `-y|--yes|--non-interactive` / `-i|--interactive` /
+  `--skip-db-check` / `--dir` / `--env-file` / `--example` / `--timeout` / `-h`；
+  环境变量 `OPENDANCE_NONINTERACTIVE` / `OPENDANCE_INTERACTIVE` /
+  `OPENDANCE_SKIP_DB_CHECK` / `OPENDANCE_ENV_FILE` / `OPENDANCE_ENV_EXAMPLE` /
+  `OPENDANCE_PROMPT_TIMEOUT`。
+- **非交互绝不挂住**：stdin 非 TTY 且是 `</dev/null`/关闭，或带 `-y` 等开关 →
+  只校验不提问；所有 read 带超时，EOF/超时立即 `exit 1`。
+- 接入点：`deploy/install.sh` 缺 `deploy/.env` 时先调用 `init-env.sh` 引导，
+  失败才 die（若 `$APP_DIR/deploy/.env` 已存在则复用，保持原语义）。
+- **监听地址默认 `0.0.0.0`**：`configuration.ts` 的
+  `bindHost = process.env.HOST ?? '0.0.0.0'`，`adminHost` 默认跟随 `HOST`
+  （同样回落 `0.0.0.0`）；`deploy/.env.example` 与 `web-server/.env.example`
+  均为 `HOST=0.0.0.0`；`install.sh` 的 `BIND_HOST="${HOST:-0.0.0.0}"`，
+  `init-env.sh` 的 HOST 默认值也是 `0.0.0.0`。
+  （`install.sh` 的 `HEALTH_HOST`/`API_HOST` 是**本机健康检查**用的回环地址，
+  与对外监听的默认值无关。）
+- 测试 `test/init-env.spec.ts`（16 项）。
+
+## 13. 上下文超标时的拆分策略

 | 超标原因 | 拆分方式 |
 |---|---|