zijunchiang
e4351c5062
需求 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 实测可逆且数据无损恢复
OpenDance Studio 管理端（opendance-admin）
基于 React 18 + TypeScript + Vite 的管理后台，对接 web-server 的 NestJS API。
接口契约以 ../contracts/rest-api.yaml（rest-api 0.1.0）为准，
字段语义见 ../contracts/data-models.md。
界面语言为简体中文；无任何 UI 组件框架，全部样式集中在 src/styles.css。
快速开始
npm install # 或 pnpm install
npm run dev # 开发服务器 http://localhost:5173
npm run build # 生产构建（tsc -b && vite build）→ dist/
npm run preview # 本地预览 dist/
npm run typecheck # 只做类型检查（tsc --noEmit）
管理端请求的是同源的
/api/**与/health，不含任何硬编码域名。
开发代理（dev proxy）
vite.config.ts 已把 /api 与 /health 代理到 http://localhost:3000：
server: {
port: 5173,
proxy: {
'/api': { target: 'http://localhost:3000', changeOrigin: true },
'/health': { target: 'http://localhost:3000', changeOrigin: true },
},
}
因此本地只需先启动服务端，再 npm run dev 即可，无需配置 CORS。
VITE_API_BASE
src/api/client.ts 的基址取自：
const BASE_URL = import.meta.env.VITE_API_BASE ?? '';
-
不设置（默认，空串）：同源请求 —— 开发期走上面的 vite 代理，生产期走 nginx 反代。推荐。
-
设置：例如服务端在另一台机器上：
# .env.local（不要提交） VITE_API_BASE=http://192.168.1.10:3000此时浏览器会直接跨域请求该地址，需要服务端开启 CORS。 构建期注入：
VITE_API_BASE=https://api.example.com npm run build。
生产构建与部署
npm run build # 产物在 dist/
vite.config.ts 使用 base: './'，产物使用相对路径引用，可挂在任意子路径下。
生产部署（业务服务自带管理端，不需要反代托管静态文件）
构建产物 dist/ 会被安装到 $APP_DIR/admin，并由 NestJS 服务自身托管
（含 SPA 深链接回退）。因此反向代理只需要把请求整体转发到后端端口即可，
不需要在代理层再配置静态站点或 try_files。
# 仓库根目录，一键部署后端（含管理端）
bash deploy/install.sh
- 后端通过
ADMIN_DIR定位管理端产物，默认../admin - 反代配置样例：
deploy/proxy/nginx.conf.example（nginx）、deploy/proxy/web.config.example（IIS） - 完整说明：
deploy/proxy/README.md
目录结构
src/
main.tsx 入口（BrowserRouter）
App.tsx 路由表
styles.css 全部样式
api/
client.ts fetch 封装（ApiError / 分页 / multipart）
types.ts 契约类型（与 rest-api.yaml 一一对应）
endpoints.ts 契约端点封装
components/
Layout.tsx 左侧导航骨架
ui.tsx 通用组件（表格/弹窗/分页/来源五元组展示与表单…）
VrmPreview.tsx three + @pixiv/three-vrm 的 3D 预览（懒加载分包）
lib/
labels.ts 枚举中文文案
format.ts 时间/字节/时长格式化
validation.ts 客户端校验（来源五元组等）
useAsync.ts 加载/错误/重试 hook
pages/
Dashboard.tsx 概览
Songs.tsx 歌曲管理 T-WEB-008
Models.tsx 模型管理 T-WEB-009
Motions.tsx 动作管理 T-WEB-004/006
Reviews.tsx 审核 T-WEB-007
页面与任务对照
| 路由 | 说明 | 任务 |
|---|---|---|
/ |
概览：三类资产按状态计数、契约版本与目录指纹、健康检查、API 不可达告警 | — |
/songs |
歌曲管理：分页/搜索/筛选、来源五元组必填、音频上传、软删除 | T-WEB-008 |
/models |
模型管理：VRM 优先、来源五元组完整展示、设为默认、3D 预览 | T-WEB-009 |
/motions |
动作管理：上传、预处理、关键点 NDJSON 下载 | T-WEB-004/006 |
/reviews |
审核：待审列表 + 审核流水，通过/驳回（驳回必填意见） | T-WEB-007 |
所有页面都显式处理加载中 / 空数据 / 请求失败三种状态，请求失败不会白屏。
3D 预览说明
src/components/VrmPreview.tsx：GLTFLoader + VRMLoaderPlugin（来自 @pixiv/three-vrm），
- 依据
vrm.meta.metaVersion区分 VRM 0.x / 1.0，0.x 自动执行VRMUtils.rotateVRM0； - 自实现鼠标拖拽旋转与滚轮缩放（未引入 OrbitControls）；
requestAnimationFrame循环内调用vrm.update(delta)，并按包围盒自动取景；- 卸载时取消 RAF、断开 ResizeObserver、释放 renderer / geometry / material / texture；
- 无 WebGL 上下文时降级为错误提示，不会让页面崩溃。
three + @pixiv/three-vrm（约 750 kB）通过 React.lazy 单独分包，仅进入模型页时加载。