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 实测可逆且数据无损恢复
2.6 KiB
2.6 KiB
contracts/database.md — 数据库契约 v0.1.0
环境
- 类型：MySQL 兼容实例（外部提供）。当前部署实际为 MariaDB 10.11.19，TypeORM
使用
mysqldriver（mysql2）连接，SQL 语法限制在 MySQL 5.7 / MariaDB 10.5+ 共同子集内，不使用 MySQL 8 专有语法（窗口函数 CTE 递归除外）。 - 数据库名：
dpendance（由部署方提供，通过DB_NAME注入；文档默认值opendance可覆盖） - 字符集：
utf8mb4/utf8mb4_general_ci（沿用现有实例默认排序规则） - 迁移工具：TypeORM migration，不使用
DB_SYNCHRONIZE
连接信息（由部署方提供）
host / port / user / password 一律通过环境变量注入，不入库、不入仓。
DB_HOST=192.168.150.10
DB_PORT=3306
DB_USER=dpendance
DB_PASS=<部署方提供>
DB_NAME=dpendance
DB_SYNCHRONIZE=false
DB_LOGGING=false
约定
- 所有表名使用
snake_case，复数形式（songs/motions/models） - 主键统一为
BIGINT AUTO_INCREMENT，字段名id - 时间字段统一
DATETIME，created_at/updated_at，updated_at由应用层维护 - 软删除统一使用
deleted_at DATETIME NULL（@DeleteDateColumn） - 布尔字段使用
TINYINT(1) - 来源（出处）字段为 5 元组，任何资产入库必须齐备：
source_type/source_name/source_url/license/author - 不使用
DB_SYNCHRONIZE，所有表结构变更走 migration - 每个 migration 必须可逆（提供
down方法） - 迁移文件名格式：
<timestamp>-<kebab-name>.ts
增量迁移（v0.2.0）
| 迁移 | 变更 |
|---|---|
AddModelConversionFields |
models 增加 source_asset_id BIGINT NULL（上传的压缩包，用于溯源）与 conversion_note VARCHAR(500) NULL（转换说明，见 model-formats.md §1.1） |
表清单（v0.1.0）
| 表 | 用途 | 任务 |
|---|---|---|
songs |
曲目元数据 | T-WEB-003 |
assets |
上传文件元数据（去重、sha256、物理路径） | T-WEB-004 |
motions |
动作数据（BVH/FBX…）+ 来源 + 预处理产物 | T-WEB-004 / 006 |
models |
角色模型（VRM 优先）+ 来源 + 压缩包转换溯源 | T-WEB-005 |
review_records |
上传审核流水 | T-WEB-007 |
状态机（status 列，v0.1.0）
draft ──submit──▶ pending ──approve──▶ published
│
└──reject──▶ rejected ──submit──▶ pending
published才可被 Windows 客户端 / Android App 消费/api/catalog/export只导出published记录