opendance-web/tasks/001-scaffold.md

T-WEB-001 骨架 + 连接现有 MySQL

• 状态：done
• 依赖：无

目标

建立 NestJS 服务端骨架，并连接部署方提供的现有 MySQL 实例。本项目不部署、 不管理 MySQL。

load

DSH.md
contracts/database.md
web-server/package.json
web-server/src/main.ts
web-server/src/app.module.ts
web-server/src/config/configuration.ts
web-server/src/db/data-source.ts

交付物

文件	说明
web-server/package.json	NestJS 11 + TypeORM 0.3 + mysql2 依赖与脚本
web-server/src/main.ts	启动引导：环境校验、全局校验管道、CORS、静态资源、优雅关闭
web-server/src/app.module.ts	根模块，TypeOrmModule.forRootAsync 由 AppConfig 注入连接信息
web-server/src/config/configuration.ts	类型化配置层，唯一读取 process.env 的位置
web-server/src/config/config.module.ts	全局配置模块
web-server/src/db/data-source.ts	TypeORM DataSource（CLI + 运行期共用），synchronize: false
web-server/src/health/health.controller.ts	GET /health，真实探测数据库连通性
web-server/.env.example	环境变量样例

关键实现

• synchronize 在代码中恒为 false，不读取环境变量覆盖，从结构上杜绝生产误开。
• validateEnv() 在启动时检查必填项，生产环境检测到 DB_SYNCHRONIZE=true 直接 以退出码 1 中止。
• /health 返回数据库版本、库名、待执行迁移数、存储目录、Assimp 可用性、契约版本； 数据库不可用时返回 503。

验收

cd web-server
cp .env.example .env    # 填写 DB_* 后
npm install
npm run start:prod
curl -s http://localhost:3000/health

期望：status=ok、database.connected=true、database.server 形如 10.11.19-MariaDB-...。

环境差异记录：文档假设 MySQL 8.x，实际部署实例为 MariaDB 10.11.19。 已确认 TypeORM mysql 驱动（mysql2）兼容，SQL 限制在两者共同子集内， 详见 contracts/database.md。

结果

• 已连通 192.168.150.10:3306/dpendance，/health 返回 200 且 connected=true。