feat: Introduce MediaAssetVariant for better asset management

- Added MediaAssetVariant enum with values 'main' and 'preview'. - Updated media asset service logic to utilize MediaAssetVariant for variant handling. - Refactored database models and queries to include variant and source_asset_id fields. - Enhanced validation for asset variants in upload and processing functions. - Updated Swagger documentation to reflect new variant structure and descriptions. - Implemented necessary database migrations to support the new variant constraints.
2025-12-22 19:27:31 +08:00
parent d04e2ee693
commit 2cc823d3a8
14 changed files with 439 additions and 171 deletions
--- a/backend/app/services/media_asset.go
+++ b/backend/app/services/media_asset.go
@@ -31,11 +31,6 @@ import (
 //	@provider
 type mediaAsset struct{}

-const (
-	mediaAssetVariantMain    = "main"
-	mediaAssetVariantPreview = "preview"
-)
-
 func mediaAssetTransitionAllowed(from, to consts.MediaAssetStatus) bool {
 	switch from {
 	case consts.MediaAssetStatusUploaded:
@@ -82,11 +77,11 @@ func (s *mediaAsset) AdminUploadInit(ctx context.Context, tenantID, operatorUser
 		return nil, errorx.ErrInvalidParameter.WithMsg("invalid type")
 	}

-	variant := strings.TrimSpace(strings.ToLower(form.Variant))
-	if variant == "" {
-		variant = mediaAssetVariantMain
+	variant := consts.MediaAssetVariantMain
+	if form.Variant != nil {
+		variant = *form.Variant
 	}
-	if variant != mediaAssetVariantMain && variant != mediaAssetVariantPreview {
+	if variant == "" || !variant.IsValid() {
 		return nil, errorx.ErrInvalidParameter.WithMsg("invalid variant")
 	}

@@ -94,7 +89,7 @@ func (s *mediaAsset) AdminUploadInit(ctx context.Context, tenantID, operatorUser
 	if form.SourceAssetID != nil {
 		sourceAssetID = *form.SourceAssetID
 	}
-	if variant == mediaAssetVariantMain {
+	if variant == consts.MediaAssetVariantMain {
 		if sourceAssetID != 0 {
 			return nil, errorx.ErrInvalidParameter.WithMsg("source_asset_id is only allowed for preview variant")
 		}
@@ -104,24 +99,23 @@ func (s *mediaAsset) AdminUploadInit(ctx context.Context, tenantID, operatorUser
 			return nil, errorx.ErrInvalidParameter.WithMsg("source_asset_id is required for preview variant")
 		}
 		// 校验来源资源存在、同租户、未删除、且为 main 产物。
-		var srcRow struct {
-			Variant string `gorm:"column:variant"`
-		}
-		if err := _db.WithContext(ctx).
-			Table(models.TableNameMediaAsset).
-			Select("variant").
-			Where("tenant_id = ? AND id = ? AND deleted_at IS NULL", tenantID, sourceAssetID).
-			Take(&srcRow).Error; err != nil {
+		tbl, query := models.MediaAssetQuery.QueryContext(ctx)
+		src, err := query.Where(
+			tbl.TenantID.Eq(tenantID),
+			tbl.ID.Eq(sourceAssetID),
+			tbl.DeletedAt.IsNull(),
+		).First()
+		if err != nil {
 			if errors.Is(err, gorm.ErrRecordNotFound) {
 				return nil, errorx.ErrRecordNotFound.WithMsg("source media asset not found")
 			}
 			return nil, err
 		}
-		srcVariant := srcRow.Variant
+		srcVariant := src.Variant
 		if srcVariant == "" {
-			srcVariant = mediaAssetVariantMain
+			srcVariant = consts.MediaAssetVariantMain
 		}
-		if srcVariant != mediaAssetVariantMain {
+		if srcVariant != consts.MediaAssetVariantMain {
 			return nil, errorx.ErrPreconditionFailed.WithMsg("source asset must be main variant")
 		}
 	}
@@ -163,16 +157,18 @@ func (s *mediaAsset) AdminUploadInit(ctx context.Context, tenantID, operatorUser
 	}

 	// variant/source_asset_id 目前为 DB 新增字段；由于 models 为 gen 产物，这里用 SQL 更新列值。
-	updates := map[string]any{
-		"variant": variant,
+	tbl, query := models.MediaAssetQuery.QueryContext(ctx)
+	// variant/source_asset_id 已生成模型字段，使用 UpdateSimple 保持类型安全。
+	assigns := []field.AssignExpr{
+		tbl.Variant.Value(variant),
 	}
 	if sourceAssetID > 0 {
-		updates["source_asset_id"] = sourceAssetID
+		assigns = append(assigns, tbl.SourceAssetID.Value(sourceAssetID))
 	}
-	if err := _db.WithContext(ctx).
-		Model(&models.MediaAsset{}).
-		Where("id = ? AND tenant_id = ?", m.ID, tenantID).
-		Updates(updates).Error; err != nil {
+	if _, err := query.Where(
+		tbl.ID.Eq(m.ID),
+		tbl.TenantID.Eq(tenantID),
+	).UpdateSimple(assigns...); err != nil {
 		return nil, pkgerrors.Wrap(err, "update media asset variant/source_asset_id failed")
 	}

@@ -224,12 +220,16 @@ func (s *mediaAsset) AdminUploadComplete(

 	var out models.MediaAsset

-	err := _db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		var m models.MediaAsset
-		if err := tx.
+	err := models.Q.Transaction(func(tx *models.Query) error {
+		tbl, query := tx.MediaAsset.QueryContext(ctx)
+		m, err := query.
 			Clauses(clause.Locking{Strength: "UPDATE"}).
-			Where("tenant_id = ? AND id = ?", tenantID, assetID).
-			First(&m).Error; err != nil {
+			Where(
+				tbl.TenantID.Eq(tenantID),
+				tbl.ID.Eq(assetID),
+			).
+			First()
+		if err != nil {
 			if errors.Is(err, gorm.ErrRecordNotFound) {
 				return errorx.ErrRecordNotFound.WithMsg("media asset not found")
 			}
@@ -244,7 +244,7 @@ func (s *mediaAsset) AdminUploadComplete(
 		// 幂等：重复 upload_complete 时返回现态。
 		switch m.Status {
 		case consts.MediaAssetStatusProcessing, consts.MediaAssetStatusReady, consts.MediaAssetStatusFailed:
-			out = m
+			out = *m
 			return nil
 		case consts.MediaAssetStatusUploaded:
 			// allowed
@@ -281,20 +281,18 @@ func (s *mediaAsset) AdminUploadComplete(
 		if !mediaAssetTransitionAllowed(m.Status, consts.MediaAssetStatusProcessing) {
 			return errorx.ErrStatusConflict.WithMsg("invalid media asset status transition")
 		}
-		if err := tx.Model(&models.MediaAsset{}).
-			Where("id = ?", m.ID).
-			Updates(map[string]any{
-				"status":     consts.MediaAssetStatusProcessing,
-				"meta":       types.JSON(metaBytes),
-				"updated_at": now,
-			}).Error; err != nil {
+		if _, err := query.Where(tbl.ID.Eq(m.ID)).Updates(map[string]any{
+			"status":     consts.MediaAssetStatusProcessing,
+			"meta":       types.JSON(metaBytes),
+			"updated_at": now,
+		}); err != nil {
 			return err
 		}

 		m.Status = consts.MediaAssetStatusProcessing
 		m.Meta = types.JSON(metaBytes)
 		m.UpdatedAt = now
-		out = m
+		out = *m

 		// 触发异步处理（当前为 stub）：后续接入队列/任务系统时在此处落任务并保持幂等。
 		logrus.WithFields(logrus.Fields{
@@ -328,12 +326,16 @@ func (s *mediaAsset) ProcessSuccess(
 	}

 	var out models.MediaAsset
-	err := _db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		var m models.MediaAsset
-		if err := tx.
+	err := models.Q.Transaction(func(tx *models.Query) error {
+		tbl, query := tx.MediaAsset.QueryContext(ctx)
+		m, err := query.
 			Clauses(clause.Locking{Strength: "UPDATE"}).
-			Where("tenant_id = ? AND id = ?", tenantID, assetID).
-			First(&m).Error; err != nil {
+			Where(
+				tbl.TenantID.Eq(tenantID),
+				tbl.ID.Eq(assetID),
+			).
+			First()
+		if err != nil {
 			if errors.Is(err, gorm.ErrRecordNotFound) {
 				return errorx.ErrRecordNotFound.WithMsg("media asset not found")
 			}
@@ -343,7 +345,7 @@ func (s *mediaAsset) ProcessSuccess(
 			return errorx.ErrPreconditionFailed.WithMsg("media asset deleted")
 		}
 		if m.Status == consts.MediaAssetStatusReady {
-			out = m
+			out = *m
 			return nil
 		}
 		if !mediaAssetTransitionAllowed(m.Status, consts.MediaAssetStatusReady) {
@@ -366,19 +368,17 @@ func (s *mediaAsset) ProcessSuccess(
 			metaBytes = []byte("{}")
 		}

-		if err := tx.Model(&models.MediaAsset{}).
-			Where("id = ?", m.ID).
-			Updates(map[string]any{
-				"status":     consts.MediaAssetStatusReady,
-				"meta":       types.JSON(metaBytes),
-				"updated_at": now,
-			}).Error; err != nil {
+		if _, err := query.Where(tbl.ID.Eq(m.ID)).Updates(map[string]any{
+			"status":     consts.MediaAssetStatusReady,
+			"meta":       types.JSON(metaBytes),
+			"updated_at": now,
+		}); err != nil {
 			return err
 		}
 		m.Status = consts.MediaAssetStatusReady
 		m.Meta = types.JSON(metaBytes)
 		m.UpdatedAt = now
-		out = m
+		out = *m
 		return nil
 	})
 	if err != nil {
@@ -403,12 +403,16 @@ func (s *mediaAsset) ProcessFailed(
 	}

 	var out models.MediaAsset
-	err := _db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		var m models.MediaAsset
-		if err := tx.
+	err := models.Q.Transaction(func(tx *models.Query) error {
+		tbl, query := tx.MediaAsset.QueryContext(ctx)
+		m, err := query.
 			Clauses(clause.Locking{Strength: "UPDATE"}).
-			Where("tenant_id = ? AND id = ?", tenantID, assetID).
-			First(&m).Error; err != nil {
+			Where(
+				tbl.TenantID.Eq(tenantID),
+				tbl.ID.Eq(assetID),
+			).
+			First()
+		if err != nil {
 			if errors.Is(err, gorm.ErrRecordNotFound) {
 				return errorx.ErrRecordNotFound.WithMsg("media asset not found")
 			}
@@ -418,7 +422,7 @@ func (s *mediaAsset) ProcessFailed(
 			return errorx.ErrPreconditionFailed.WithMsg("media asset deleted")
 		}
 		if m.Status == consts.MediaAssetStatusFailed {
-			out = m
+			out = *m
 			return nil
 		}
 		if !mediaAssetTransitionAllowed(m.Status, consts.MediaAssetStatusFailed) {
@@ -438,19 +442,17 @@ func (s *mediaAsset) ProcessFailed(
 			metaBytes = []byte("{}")
 		}

-		if err := tx.Model(&models.MediaAsset{}).
-			Where("id = ?", m.ID).
-			Updates(map[string]any{
-				"status":     consts.MediaAssetStatusFailed,
-				"meta":       types.JSON(metaBytes),
-				"updated_at": now,
-			}).Error; err != nil {
+		if _, err := query.Where(tbl.ID.Eq(m.ID)).Updates(map[string]any{
+			"status":     consts.MediaAssetStatusFailed,
+			"meta":       types.JSON(metaBytes),
+			"updated_at": now,
+		}); err != nil {
 			return err
 		}
 		m.Status = consts.MediaAssetStatusFailed
 		m.Meta = types.JSON(metaBytes)
 		m.UpdatedAt = now
-		out = m
+		out = *m
 		return nil
 	})
 	if err != nil {
@@ -475,12 +477,16 @@ func (s *mediaAsset) AdminDelete(ctx context.Context, tenantID, operatorUserID,
 	}).Info("services.media_asset.admin.delete")

 	var out models.MediaAsset
-	err := _db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		var m models.MediaAsset
-		if err := tx.
+	err := models.Q.Transaction(func(tx *models.Query) error {
+		tbl, query := tx.MediaAsset.QueryContext(ctx)
+		m, err := query.
 			Clauses(clause.Locking{Strength: "UPDATE"}).
-			Where("tenant_id = ? AND id = ?", tenantID, assetID).
-			First(&m).Error; err != nil {
+			Where(
+				tbl.TenantID.Eq(tenantID),
+				tbl.ID.Eq(assetID),
+			).
+			First()
+		if err != nil {
 			if errors.Is(err, gorm.ErrRecordNotFound) {
 				return errorx.ErrRecordNotFound.WithMsg("media asset not found")
 			}
@@ -489,7 +495,7 @@ func (s *mediaAsset) AdminDelete(ctx context.Context, tenantID, operatorUserID,

 		// 幂等：已删除直接返回。
 		if m.DeletedAt.Valid || m.Status == consts.MediaAssetStatusDeleted {
-			out = m
+			out = *m
 			return nil
 		}

@@ -497,22 +503,20 @@ func (s *mediaAsset) AdminDelete(ctx context.Context, tenantID, operatorUserID,
 			return errorx.ErrStatusConflict.WithMsg("invalid media asset status transition")
 		}

-		if err := tx.Model(&models.MediaAsset{}).
-			Where("id = ?", m.ID).
-			Updates(map[string]any{
-				"status":     consts.MediaAssetStatusDeleted,
-				"updated_at": now,
-			}).Error; err != nil {
+		if _, err := query.Where(tbl.ID.Eq(m.ID)).Updates(map[string]any{
+			"status":     consts.MediaAssetStatusDeleted,
+			"updated_at": now,
+		}); err != nil {
 			return err
 		}

-		if err := tx.Delete(&m).Error; err != nil {
+		if _, err := query.Where(tbl.ID.Eq(m.ID)).Delete(); err != nil {
 			return err
 		}

 		m.Status = consts.MediaAssetStatusDeleted
 		m.UpdatedAt = now
-		out = m
+		out = *m
 		return nil
 	})
 	if err != nil {