docs(web): 任务说明、DSH 约束与交付文档

2026-09-14 19:00:55 +08:00
parent 5a8b77b0a4
commit b9215d4190
16 changed files with 1461 additions and 0 deletions
@@ -0,0 +1,63 @@
+# 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**。
+
+## 验收
+
+```bash
+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`。