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 实测可逆且数据无损恢复
65 lines
2.6 KiB
Markdown
65 lines
2.6 KiB
Markdown
# contracts/database.md — 数据库契约 v0.1.0
|
||
|
||
## 环境
|
||
|
||
- 类型：MySQL 兼容实例（外部提供）。**当前部署实际为 MariaDB 10.11.19**，TypeORM
|
||
使用 `mysql` driver（`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 一律通过环境变量注入，**不入库、不入仓**。
|
||
|
||
```bash
|
||
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` 记录
|