docs(readme): 新增初次部署清单与常见问题；统一 root 执行写法；清除 markdown 粗体标记与残留真实库名

tasks/005-model-upload.md

@@ -15,8 +15,8 @@
 ```
 DSH.md
 contracts/rest-api.yaml          # 锚点：#/paths/~1api~1models
-contracts/data-models.md         # 锚点：§4 Model、§4.1 默认模型选择规则
-contracts/model-formats.md       # 锚点：§1 角色模型、§1.1 上传与转换策略
+contracts/data-models.md         # 锚点：4 Model、4.1 默认模型选择规则
+contracts/model-formats.md       # 锚点：1 角色模型、1.1 上传与转换策略
 web-server/src/models/*
 web-server/src/models/model-inspector.ts
 web-server/src/models/model-thumbnail.ts
@@ -36,7 +36,7 @@ web-server/scripts/import-default-model.mjs
 ## 端点
 
 | 方法 | 路径 | 说明 |
-|---|---|---|
+|--|--|--|
 | GET | `/api/models` | 分页 + `q`/`format`/`status`/`primaryOnly` |
 | POST | `/api/models` | multipart 上传（`file` + 名称 + 来源五元组）；`file` 接受 `.glb`/`.vrm`/`.gltf`/`.pmx`/`.fbx`/`.zip`；**入库一律 pending** |
 | GET | `/api/models/:id` | 详情（含 `stats`、`thumbnailUrl`、`conversionNote`、`fileSha256`、`sourceSha256`） |
@@ -47,7 +47,7 @@ web-server/scripts/import-default-model.mjs
 ## 格式策略（服务端与客户端一致）
 
 | 输入 | 行为 |
-|---|---|
+|--|--|
 | `.glb` / `.vrm` | **直接导入**，不重编码；`.vrm` = GLB + VRM 扩展 |
 | `.gltf` | **直接导入**（分离的 `.bin` / 贴图不在同一文件里，会缺资源，建议随 zip 上传） |
 | `.pmx` / `.fbx` | 服务端转换：优先 GLB、其次 VRM（见下） |
@@ -60,36 +60,36 @@ web-server/scripts/import-default-model.mjs
 ## 压缩包自动搜索与转换
 
 ```
-.zip ─▶ readZipEntries() ─▶ 自动搜索主模型 ─┬─ .vrm/.glb/.gltf ─▶ 直接导入
-        zip-reader.ts        .vrm>.glb>       │
-                             .gltf>.pmx>.fbx  └─ .pmx/.fbx ─▶ Assimp 转换
-                                                              ├─ 1) → .glb
-                                                              ├─ 2) → .gltf → gltf-packer → GLB
-                                                              ├─ 3) MODEL_CONVERT_FORMAT=vrm → vrm-writer
+.zip ─▶ readZipEntries() ─▶ 自动搜索主模型 ─┬─.vrm/.glb/.gltf ─▶ 直接导入
+        zip-reader.ts.vrm>.glb>       │
+                             .gltf>.pmx>.fbx  └─.pmx/.fbx ─▶ Assimp 转换
+                                                              ├─ 1) ->.glb
+                                                              ├─ 2) ->.gltf -> gltf-packer -> GLB
+                                                              ├─ 3) MODEL_CONVERT_FORMAT=vrm -> vrm-writer
                                                               └─ 每步 assimp info 回读
 ```
 
 | 环节 | 实现 | 规则 |
-|---|---|---|
+|--|--|--|
 | ZIP 读取 | `common/zip-reader.ts` | 中央目录/EOCD、STORE(0)+DEFLATE(8)、ZIP64 大小字段、Shift-JIS/GBK 文件名回退；拒绝 zip-slip 与加密条目；不支持的压缩方式报错 |
-| 选主模型 | `model-convert.ts` | 格式优先级 `.vrm` → `.glb` → `.gltf` → `.pmx` → `.fbx`；同一优先级内"`MODEL_CONVERT_PMX` 指名字（默认 `Hatsune Miku.pmx`，大小写不敏感）→ 目录最浅 → 文件最大" |
+| 选主模型 | `model-convert.ts` | 格式优先级 `.vrm` -> `.glb` -> `.gltf` -> `.pmx` -> `.fbx`；同一优先级内"`MODEL_CONVERT_PMX` 指名字（默认 `Hatsune Miku.pmx`，大小写不敏感）-> 目录最浅 -> 文件最大" |
 | 直接导入 | `importModelFile()` | `.vrm`/`.glb`/`.gltf` 原样入库；`.glb` 若含 `VRMC_vrm`/`VRM` 扩展会被识别为 VRM |
 | 转换 | `convertModelFile()` / `convertModelArchive()` | `MODEL_CONVERT_FORMAT=glb`（默认）｜`vrm`；超时 `MODEL_CONVERT_TIMEOUT_MS`（默认 180000） |
 | 回读校验 | `exportAndValidate()` | 每步产物**必须** `assimp info` 回读；退出码 0 但产物损坏也判失败 |
 | GLB 打包 | `gltf-packer.ts` | GLB 直出失败时导出 `.gltf`，把 `.bin` 与外部贴图自行合成单文件 GLB |
-| VRM 封装 | `vrm-writer.ts` | `MODEL_CONVERT_FORMAT=vrm` 时只改 JSON chunk 补 `extensions.VRMC_vrm`；humanoid 骨骼不全 → **回退交付 GLB**，缺失骨骼写进说明 |
+| VRM 封装 | `vrm-writer.ts` | `MODEL_CONVERT_FORMAT=vrm` 时只改 JSON chunk 补 `extensions.VRMC_vrm`；humanoid 骨骼不全 -> **回退交付 GLB**，缺失骨骼写进说明 |
 | 贴图内嵌 | `glb-textures.ts` | 把 GLB 中外部 URI 贴图追加 bufferView 并内嵌进 BIN chunk（4 字节对齐） |
-| 溯源 | 迁移 `AddModelConversionFields1789450000000` | 压缩包原件存为 `model-archive` 资产 → `models.source_asset_id`；说明 → `models.conversion_note` |
-| 失败 | `models.service.ts` | 无可用模型 / Assimp 不可用 / 两条路径都失败 → **HTTP 422**，不产生模型记录 |
-| 文件名编码 | `common/upload.util.ts` `decodeUploadName()` | 修正 multipart 文件名的 latin1/UTF-8 乱码（中文文件名原先存成 `模å_…`） |
-| DTO | `conversionNote` / `fileSha256` / `sourceSha256` / `stats` / `thumbnailUrl` | 契约 `data-models.md` §4、`rest-api.yaml` |
+| 溯源 | 迁移 `AddModelConversionFields1789450000000` | 压缩包原件存为 `model-archive` 资产 -> `models.source_asset_id`；说明 -> `models.conversion_note` |
+| 失败 | `models.service.ts` | 无可用模型 / Assimp 不可用 / 两条路径都失败 -> **HTTP 422**，不产生模型记录 |
+| 文件名编码 | `common/upload.util.ts` `decodeUploadName()` | 修正 multipart 文件名的 latin1/UTF-8 乱码（中文文件名原先存成 `模å_...`） |
+| DTO | `conversionNote` / `fileSha256` / `sourceSha256` / `stats` / `thumbnailUrl` | 契约 `data-models.md` 4、`rest-api.yaml` |
 
 ## 入库后自动：分析 + 缩略图（尽力而为，失败不影响入库）
 
 | 项 | 实现 | 说明 |
-|---|---|---|
-| 分析 | `model-inspector.ts` → `models.stats` | 面数 / 顶点 / 网格 / 材质 / 贴图 / 节点 / 形变目标 / 动画 / 蒙皮骨骼数 / **骨骼树** / humanoid 覆盖 / **可驱动性（缺哪些必需骨骼）** / warnings；迁移 `AddModelStats1789460000000` 新增 `models.stats TEXT` |
-| 缩略图 | `model-thumbnail.ts` → `models.thumbnail_asset_id` | 纯 TS 软件光栅化 512×512 PNG（读 GLB/glTF → 节点层级与蒙皮 → 包围盒构图 → 透视投影 → z-buffer 平面着色 → 手写 PNG），**零原生依赖**；失败或非 glTF 容器留空，前端退化为格式占位图 |
+|--|--|--|
+| 分析 | `model-inspector.ts` -> `models.stats` | 面数 / 顶点 / 网格 / 材质 / 贴图 / 节点 / 形变目标 / 动画 / 蒙皮骨骼数 / **骨骼树** / humanoid 覆盖 / **可驱动性（缺哪些必需骨骼）** / warnings；迁移 `AddModelStats1789460000000` 新增 `models.stats TEXT` |
+| 缩略图 | `model-thumbnail.ts` -> `models.thumbnail_asset_id` | 纯 TS 软件光栅化 512×512 PNG（读 GLB/glTF -> 节点层级与蒙皮 -> 包围盒构图 -> 透视投影 -> z-buffer 平面着色 -> 手写 PNG），**零原生依赖**；失败或非 glTF 容器留空，前端退化为格式占位图 |
 
 ## 状态与默认模型（硬性）
 
@@ -107,7 +107,7 @@ web-server/scripts/import-default-model.mjs
 2. format='vrm' 且 published 且 is_primary=1
 3. format='vrm' 且 published，按 id 升序取第一个
 4. published，按 (format='vrm' DESC, id ASC) 取第一个
-5. 无 → 客户端使用内置占位模型
+5. 无 -> 客户端使用内置占位模型
 ```
 
 `POST /:id/primary` 在**同一事务**内先清零其余 `is_primary`，保证互斥。
@@ -116,23 +116,23 @@ web-server/scripts/import-default-model.mjs
 
 `vrm-inspector.ts` 直接读取 GLB 头部 JSON chunk，不依赖完整 3D 库：
 
-- `extensions.VRMC_vrm` → VRM **1.0**（取 `specVersion`）
-- `extensions.VRM` → VRM **0.x**
-- 两者皆无 → `null`（普通 GLB）
+- `extensions.VRMC_vrm` -> VRM **1.0**（取 `specVersion`）
+- `extensions.VRM` -> VRM **0.x**
+- 两者皆无 -> `null`（普通 GLB）
 
 ## 实测（v0.2.0）
 
-- 上传含 `Hatsune Miku.pmx` 的 MMD 压缩包 → **HTTP 201 / 0.86s**、`format=glb`、
-  `status=pending`、`conversionNote=Hatsune Miku.pmx → GLB，已内嵌 2 张贴图`。
+- 上传含 `Hatsune Miku.pmx` 的 MMD 压缩包 -> **HTTP 201 / 0.86s**、`format=glb`、
+  `status=pending`、`conversionNote=Hatsune Miku.pmx -> GLB，已内嵌 2 张贴图`。
   分析结果：`vertices=7155 triangles=9071 materials=3 textures=2 images=2 nodes=240
   bones=238 skins=1 morphTargets=0 humanoidMapped=0/22 drivable=false maxBoneDepth=23`；
   `missingRequiredBones` 为**全部 16 根**（日文 MMD 骨名无法映射到 humanoid）。
-- 直接上传 `.glb` → **HTTP 201 / 0.36s**、`conversionNote=直接导入（GLB，未做重编码）`，
+- 直接上传 `.glb` -> **HTTP 201 / 0.36s**、`conversionNote=直接导入（GLB，未做重编码）`，
   入库文件 sha256 与源文件**一致**（不重编码）。
 - 缩略图：512×512 PNG / 15,043 字节，服务端纯 TS 光栅化（含蒙皮），目视确认为居中的
-  T-pose 角色图；真实 10MB VRM（83 关节、5307 顶点）单张耗时 60–121ms（中位 79ms）。
-- 审核：`POST /api/reviews/model/22/approve` 带 `setPrimary:true` → 200，
-  模型 `status=published`、`isPrimary=true`，源码种子写入 `sourceSha256=72eb6882…`；
+  T-pose 角色图；真实 10MB VRM（83 关节、5307 顶点）单张耗时 60-121ms（中位 79ms）。
+- 审核：`POST /api/reviews/model/22/approve` 带 `setPrimary:true` -> 200，
+  模型 `status=published`、`isPrimary=true`，源码种子写入 `sourceSha256=72eb6882...`；
   重建后 `GET /api/catalog/export` 的 `defaultModelId` 由 VRM 变为 **22**
   （库中另有 2 个已发布 VRM）。
 
@@ -146,7 +146,7 @@ cd web-server
 node scripts/import-default-model.mjs 模型.zip --url http://127.0.0.1:3000 \
   --name "初音未来 Hatsune Miku" --author "Boku Wa Luka" \
   --license "MMD 模型使用条款（见压缩包内说明）" --source-type other
-# 上传 → 服务端转换入库（pending）→ 把身份写进 src/config/default-model.ts
+# 上传 -> 服务端转换入库（pending）-> 把身份写进 src/config/default-model.ts
 
 node scripts/import-default-model.mjs --write-source-only --model-id 22   # 只补写源码
 node scripts/import-default-model.mjs --write-source-only --model-id 22 --dry-run
@@ -165,18 +165,18 @@ npm run test:smoke    # 冒烟 [4] 段落
 ```
 
 | 验收项 | 状态 |
-|---|---|
+|--|--|
 | `.glb`/`.vrm`/`.gltf` 直接导入不重编码 | ✅ 实测 GLB 上传 201、`conversionNote=直接导入（GLB，未做重编码）`、入库 sha256 与源文件一致 |
-| `.zip` 自动搜索包内模型 | ✅ 优先级 `.vrm`>`glb`>`.gltf`>`.pmx`>`.fbx`；同优先级按指名字→目录最浅→文件最大 |
+| `.zip` 自动搜索包内模型 | ✅ 优先级 `.vrm`>`glb`>`.gltf`>`.pmx`>`.fbx`；同优先级按指名字->目录最浅->文件最大 |
 | `.pmx` 转换优先 GLB | ✅ 实测 201 / 0.86s、`format=glb`、2 张贴图内嵌 |
-| GLB 失败回退 glTF→GLB 打包 | ✅ GLB 直出失败时 `gltf-packer.ts` 自行打包；每步 `assimp info` 回读校验 |
+| GLB 失败回退 glTF->GLB 打包 | ✅ GLB 直出失败时 `gltf-packer.ts` 自行打包；每步 `assimp info` 回读校验 |
 | `MODEL_CONVERT_FORMAT=vrm` 封装 | ✅ `vrm-writer.ts` 补 `VRMC_vrm`；humanoid 不全回退 GLB |
 | 自动分析写入 `models.stats` | ✅ 实测 `triangles=9071 bones=238 humanoidMapped=0/22 drivable=false` |
 | 缩略图生成且不影响入库 | ✅ 512×512 / 15,043 B；失败只告警 |
 | 上传一律 pending、不自动设默认 | ✅ `create()` 固定 `PublishStatus.Pending` + `isPrimary=false` |
-| `setPrimary` 审核通过时生效 | ✅ `POST /api/reviews/model/22/approve` + `setPrimary:true` → 200、`isPrimary=true` |
-| 非 published 设默认 | ✅ `POST /api/models/:id/primary` → 409 |
-| 失败语义 | ✅ 无可用模型 / Assimp 不可用 / 两条路径均失败 → HTTP 422，不产生模型记录 |
+| `setPrimary` 审核通过时生效 | ✅ `POST /api/reviews/model/22/approve` + `setPrimary:true` -> 200、`isPrimary=true` |
+| 非 published 设默认 | ✅ `POST /api/models/:id/primary` -> 409 |
+| 失败语义 | ✅ 无可用模型 / Assimp 不可用 / 两条路径均失败 -> HTTP 422，不产生模型记录 |
 | ZIP 安全 | ✅ 拒绝 zip-slip、加密条目、未知压缩方式（`model-archive.spec.ts` 24 项） |
 | humanoid 与客户端一致 | ✅ `model-inspector.spec.ts` 抽 `humanoid_map.gd` 逐键比对（25 项） |
 | VRM 版本识别 | ✅ `test/vrm-inspector.spec.ts`（6 例） |