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,57 @@
+# T-WEB-002 TypeORM 迁移生成表结构
+
+- **状态**：done
+- **依赖**：T-WEB-001
+
+## 目标
+
+用 TypeORM migration 在现有实例的 `dpendance` 库中建立全部表结构。不使用
+`DB_SYNCHRONIZE`，迁移必须可逆。
+
+## load
+
+```
+DSH.md
+contracts/database.md
+contracts/data-models.md
+web-server/src/entities/*.entity.ts
+web-server/src/migrations/*.ts
+web-server/src/db/data-source.ts
+```
+
+## 表结构
+
+| 表 | 用途 | 关键列 |
+|---|---|---|
+| `assets` | 上传文件元数据 | `sha256` 唯一索引（去重）、`stored_path`、`size` |
+| `songs` | 曲目 | 来源五元组、`status`、`deleted_at` |
+| `motions` | 动作数据 | `song_id` FK（ON DELETE SET NULL）、预处理产物列 |
+| `models` | 角色模型 | `format`、`vrm_version`、`is_primary` |
+| `review_records` | 审核流水 | `(target_type, target_id)` 复合索引 |
+
+统一约定（`contracts/database.md`）：
+
+- 表名 `snake_case` 复数；主键 `BIGINT AUTO_INCREMENT`
+- 时间列 `DATETIME`；软删除 `deleted_at`
+- Tags 使用 `simple-json`（MariaDB 下落 LONGTEXT，规避 JSON 类型差异）
+
+## 交付物
+
+- `web-server/src/entities/{asset,song,motion,model,review-record}.entity.ts`
+- `web-server/src/migrations/1789382903060-InitSchema.ts`（由 `migration:generate`
+  对真实库生成，保证与实体零漂移）
+- `web-server/src/db/data-source.ts` 的 `migrations` 通配配置
+
+## 验收
+
+```bash
+cd web-server
+npm run migration:run      # 1 migrations were executed successfully
+npm run migration:show     # [X] 1 InitSchema1789382903060
+npm run migration:revert && npm run migration:run   # 验证可逆
+```
+
+## 结果
+
+- 迁移已在 `dpendance` 库执行成功，创建 5 张业务表 + `typeorm_migrations`。
+- `down()` 完整删除索引、外键与表，可逆性通过 `migration:revert` 验证。