================================================================
OpenDance Studio —— Web 管理服务端 v0.1.0  使用说明
================================================================

本服务端是 OpenDance Studio 三端中的第一端，负责管理歌曲、VRM 模型与
动作来源，是 Windows 客户端与 Android 辅助 App 的唯一数据源与契约权威。

重要：本服务端 **不部署、不管理 MySQL**。数据库为部署方提供的现有实例，
连接信息通过 .env 注入。

----------------------------------------------------------------
一、快速部署（Docker Compose）
----------------------------------------------------------------

前置要求
  - Linux 服务器，已安装 Docker 与 docker compose
  - 一个可连通的现有 MySQL / MariaDB 实例，并已创建数据库与账号：

      CREATE DATABASE IF NOT EXISTS dpendance
        CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
      CREATE USER IF NOT EXISTS 'dpendance'@'%' IDENTIFIED BY '<密码>';
      GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP, REFERENCES
        ON dpendance.* TO 'dpendance'@'%';
      FLUSH PRIVILEGES;

  （本项目不会创建数据库本身，也不需要 GRANT OPTION / FILE / SUPER 等管理权限）

部署步骤
  cd deploy
  cp .env.example .env
  vi .env                 # 填写 DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME
  ./install.sh

脚本会依次：校验 .env → 构建镜像 → 执行 TypeORM 迁移 → 启动服务 → 健康检查。

部署完成后
  API:    http://<host>:3000
  Admin:  http://<host>:8080
  健康检查: http://<host>:3000/health

停止服务
  ./uninstall.sh          # 保留上传数据卷
  ./uninstall.sh -v       # 连数据卷一起删除

----------------------------------------------------------------
二、本地开发
----------------------------------------------------------------

后端
  cd web-server
  cp .env.example .env    # 填写 DB_*
  npm install
  npm run migration:run   # 首次需要
  npm run start:dev       # http://localhost:3000

管理前端
  cd web-server/admin
  npm install
  npm run dev             # http://localhost:5173（/api 与 /health 代理到 3000）

----------------------------------------------------------------
三、验证
----------------------------------------------------------------

  cd web-server
  npm run contracts:check   # 契约版本一致性
  npm run typecheck         # TypeScript 严格检查
  npm run test              # 31 项单元测试
  npm run build             # 生产构建
  npm run start:prod &      # 启动
  npm run test:smoke        # 57 项端到端冒烟（需要数据库可连通）

  cd ../admin && npm run build   # 管理端构建

----------------------------------------------------------------
四、环境变量
----------------------------------------------------------------

  DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME
      现有 MySQL 实例连接信息（必填）

  DB_SYNCHRONIZE
      必须为 false。生产环境启动时若检测到 true 会直接中止启动。
      所有表结构变更通过 TypeORM migration 执行。

  DB_LOGGING            是否打印 SQL（默认 false）
  PORT                  API 监听端口（默认 3000）
  STORAGE_DIR           上传文件存储目录（默认 ./storage，容器内 /data/storage）
  UPLOAD_MAX_BYTES      单文件上限，默认 536870912（512 MiB）
  ASSIMP_BIN            可选：Assimp 可执行文件，FBX/glTF 动作预处理需要
  CONTRACTS_DIR         可选：契约目录，设置后 /health 反映实时契约版本

----------------------------------------------------------------
五、主要 API
----------------------------------------------------------------

  GET    /health                              健康检查（含数据库连通性）
  GET    /api/songs                           曲目列表（分页 / 检索）
  POST   /api/songs                           新建曲目
  GET    /api/songs/:id                       曲目详情
  PATCH  /api/songs/:id                       更新曲目
  DELETE /api/songs/:id                       删除曲目（软删除）
  POST   /api/songs/:id/audio                 上传音频
  GET    /api/motions                         动作列表
  POST   /api/motions                         上传动作 + 来源信息
  POST   /api/motions/:id/preprocess          BVH/FBX → MediaPipe33 关键点
  GET    /api/motions/:id/keypoints           下载关键点序列（NDJSON）
  GET    /api/models                          模型列表
  POST   /api/models                          上传模型 + 来源信息（VRM 优先）
  POST   /api/models/:id/primary              设为全局默认模型
  GET    /api/reviews                         审核流水 / 待审列表
  POST   /api/reviews/:type/:id/approve       审核通过
  POST   /api/reviews/:type/:id/reject        审核驳回（必须填意见）
  GET    /api/catalog/export                  客户端一次性拉取已发布目录
  GET    /api/catalog/version                 契约版本 + 目录指纹

完整契约（OpenAPI 3.0）见 contracts/rest-api.yaml。

上传文件通过 /static/<kind>/<yyyy>/<mm>/<sha256>.ext 访问，
相同内容只落盘一次（sha256 去重）。

----------------------------------------------------------------
六、目录结构
----------------------------------------------------------------

  project.yaml            任务清单与状态
  DSH.md                  本项目 DSH 执行约束
  tasks/                  单任务说明书（T-WEB-001 ~ 010）
  contracts/              跨端契约（权威，改接口先改这里）
  web-server/             NestJS 服务端源码
  web-server/admin/       React 管理端
  deploy/                 Docker Compose 部署（不含 MySQL）
  THIRD_PARTY.md          第三方开源项目声明

----------------------------------------------------------------
七、安全提示
----------------------------------------------------------------

1. .env 已被 .gitignore 忽略，禁止提交；仓库中只保留 .env.example。
2. 数据库账号使用最小权限，不授予 GRANT OPTION / FILE / SUPER。
3. 本版本未内置管理端登录认证，请部署在内网或由反向代理提供鉴权。
4. 上传的模型与动作必须填写来源五元组并通过审核后才对客户端可见。
5. 未使用 SMPL 拓扑，统一 MediaPipe 33 点，规避非商用许可限制。

----------------------------------------------------------------
八、第三方开源声明
----------------------------------------------------------------

见 THIRD_PARTY.md，或访问 http://<admin-host>:8080/ 的「关于」页面。
