opendance-windows/contracts/database.md

contracts/database.md - 数据库契约 v0.1.0

环境

• 类型：MySQL 兼容实例（外部提供，含 MariaDB 10.5+），TypeORM 使用 mysql driver（mysql2）连接，SQL 语法限制在 MySQL 5.7 / MariaDB 10.5+ 共同子集内，不使用 MySQL 8 专有语法（窗口函数 CTE 递归除外）。
• 数据库名：由部署方提供，通过 DB_NAME 注入（本文档示例统一用 opendance）
• 字符集：utf8mb4 / utf8mb4_general_ci（沿用现有实例默认排序规则）
• 迁移工具：TypeORM migration，不使用 DB_SYNCHRONIZE

连接信息（由部署方提供）

host / port / user / password 一律通过环境变量注入，不入库、不入仓。

DB_HOST=<数据库主机>
DB_PORT=3306
DB_USER=opendance_app
DB_PASS=<数据库口令>
DB_NAME=opendance
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 / v0.3.0）

迁移	变更
AddModelConversionFields	models 增加 source_asset_id BIGINT NULL（上传的压缩包，用于溯源）与 conversion_note VARCHAR(500) NULL（转换说明，见 model-formats.md 1.1）
AddModelStats	models 增加 stats TEXT NULL（模型分析结果：面数、骨骼树、humanoid 覆盖、可驱动性），供审核界面展示

表清单（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 记录