opendance-android/contracts/database.md

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 一律通过环境变量注入，不入库、不入仓。

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.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 记录