docs(web): 任务说明、DSH 约束与交付文档
This commit is contained in:
+149
@@ -0,0 +1,149 @@
|
||||
================================================================
|
||||
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/ 的「关于」页面。
|
||||
Reference in New Issue
Block a user