feat(upload): add programmatic Ingest service and file-upload skill

Introduce upload/ingest as the single domain entry for storing files,
writing w_uploads records, and maintaining incremental stats. Refactor
HTTP UploadFile and delete handlers to delegate to ingest, fix stats
decrement ordering on Remove, and document usage in the file-upload skill.

internal/apps/upload/handler/file_management.go

@@ -8,6 +8,7 @@ import (
 	"strconv"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/apps/upload/ingest"
 	"github.com/Rain-kl/Wavelet/internal/apps/upload/shared"
 	uploadstorage "github.com/Rain-kl/Wavelet/internal/apps/upload/storage"
 	"github.com/Rain-kl/Wavelet/internal/common/response"
@@ -235,7 +236,7 @@ func DeleteMyFile(c *gin.Context) {
 			c.AbortWithStatus(http.StatusNotFound)
 			return
 		}
-		if err == errUploadForbidden {
+		if err == ingest.ErrForbidden {
 			c.AbortWithStatus(http.StatusForbidden)
 			return
 		}
@@ -289,7 +290,7 @@ func UpdateMyFile(c *gin.Context) {
 			c.AbortWithStatus(http.StatusNotFound)
 			return
 		}
-		if err == errUploadForbidden {
+		if err == ingest.ErrForbidden {
 			c.AbortWithStatus(http.StatusForbidden)
 			return
 		}

internal/apps/upload/handler/logics.go

@@ -4,20 +4,13 @@
 package handler
 
 import (
-	"bytes"
 	"context"
 	"errors"
 	"sort"
-	"strings"
 
-	"github.com/Rain-kl/Wavelet/internal/apps/upload/shared"
-	uploadstats "github.com/Rain-kl/Wavelet/internal/apps/upload/stats"
-	uploadstorage "github.com/Rain-kl/Wavelet/internal/apps/upload/storage"
-	"github.com/Rain-kl/Wavelet/internal/db/idgen"
+	"github.com/Rain-kl/Wavelet/internal/apps/upload/ingest"
 	"github.com/Rain-kl/Wavelet/internal/model"
 	"github.com/Rain-kl/Wavelet/internal/repository"
-	"github.com/Rain-kl/Wavelet/internal/storage"
-	"github.com/Rain-kl/Wavelet/pkg/logger"
 	"gorm.io/gorm"
 )
 
@@ -31,30 +24,11 @@ func listMyUploadFiles(ctx context.Context, userID uint64, filter repository.Upl
 }
 
 func softDeleteUpload(ctx context.Context, uploadID uint64) (model.Upload, error) {
-	upload, err := repository.GetActiveUploadByID(ctx, uploadID)
-	if err != nil {
-		return model.Upload{}, err
-	}
-	if err := repository.SoftDeleteUpload(ctx, &upload); err != nil {
-		return model.Upload{}, err
-	}
-	uploadstats.RecordUploadStatsRemove(ctx, &upload)
-	return upload, nil
+	return ingest.Remove(ctx, uploadID)
 }
 
 func softDeleteOwnedUpload(ctx context.Context, userID, uploadID uint64) (model.Upload, error) {
-	upload, err := repository.GetActiveUploadByID(ctx, uploadID)
-	if err != nil {
-		return model.Upload{}, err
-	}
-	if upload.UserID != userID {
-		return model.Upload{}, errUploadForbidden
-	}
-	if err := repository.SoftDeleteUpload(ctx, &upload); err != nil {
-		return model.Upload{}, err
-	}
-	uploadstats.RecordUploadStatsRemove(ctx, &upload)
-	return upload, nil
+	return ingest.RemoveOwned(ctx, userID, uploadID)
 }
 
 func listDistinctUploadTypes(ctx context.Context) ([]string, error) {
@@ -77,7 +51,7 @@ func updateOwnedUpload(ctx context.Context, userID, uploadID uint64, input updat
 		return model.Upload{}, err
 	}
 	if upload.UserID != userID {
-		return model.Upload{}, errUploadForbidden
+		return model.Upload{}, ingest.ErrForbidden
 	}
 
 	updates := make(map[string]any)
@@ -103,96 +77,10 @@ func listUploadsForBatchDownload(ctx context.Context, ids []uint64) ([]model.Upl
 	return repository.ListUploadsByIDs(ctx, ids)
 }
 
-type instantUploadInput struct {
-	UserID     uint64
-	FileHash   string
-	Size       int64
-	MimeType   string
-	Extension  string
-	OrigName   string
-	UploadType string
-	AccessMode int
-}
-
-func createInstantUpload(ctx context.Context, existing model.Upload, input instantUploadInput) (model.Upload, error) {
-	newUpload := model.Upload{
-		ID:            idgen.NextUint64ID(),
-		UserID:        input.UserID,
-		FileName:      input.OrigName,
-		FilePath:      existing.FilePath,
-		FileSize:      input.Size,
-		MimeType:      input.MimeType,
-		Extension:     input.Extension,
-		Hash:          input.FileHash,
-		Type:          input.UploadType,
-		Status:        model.UploadStatusUsed,
-		AccessMode:    input.AccessMode,
-		Metadata:      existing.Metadata,
-	}
-	if err := repository.CreateUpload(ctx, &newUpload); err != nil {
-		return model.Upload{}, err
-	}
-	uploadstats.RecordUploadStatsAdd(ctx, &newUpload)
-	logger.InfoF(ctx, "文件触发秒传成功! ID: %d, Path: %s", newUpload.ID, existing.FilePath)
-	return newUpload, nil
-}
-
-func findReusableUpload(ctx context.Context, hash string, size int64) (model.Upload, error) {
-	return repository.FindReusableUploadByHash(ctx, hash, size)
-}
-
-func saveNewUploadRecord(ctx context.Context, upload *model.Upload, filePath string) error {
-	if err := repository.CreateUpload(ctx, upload); err != nil {
-		_, backend, backendErr := storage.Active(ctx)
-		if backendErr == nil {
-			if deleteErr := backend.Delete(ctx, filePath); deleteErr != nil {
-				logger.WarnF(ctx, "清理未写入数据库的上传对象失败: %v", deleteErr)
-			}
-		}
-		return err
-	}
-	uploadstats.RecordUploadStatsAdd(ctx, upload)
-	return nil
-}
-
 func loadUploadStats(ctx context.Context) ([]model.UploadStat, error) {
 	return repository.ListUploadStats(ctx)
 }
 
-var errUploadForbidden = errors.New("upload forbidden")
-
-func storeUploadObject(ctx context.Context, subPath string, size int64, mimeType string, buf *bytes.Buffer, meta *model.UploadMetadata) (string, error) {
-	if uploadstorage.ReadOnly(ctx) {
-		return "", errors.New(shared.ErrStorageReadOnly)
-	}
-	driver, backend, err := storage.Active(ctx)
-	if err != nil {
-		logger.ErrorF(ctx, "初始化活动存储失败: %v", err)
-		return "", errors.New(shared.ErrSaveFileFailed)
-	}
-	result, err := backend.Put(ctx, subPath, bytes.NewReader(buf.Bytes()), size, mimeType)
-	if err != nil {
-		logger.ErrorF(ctx, "写入 %s 存储失败: %v", driver, err)
-		return "", errors.New(shared.ErrSaveFileFailed)
-	}
-	meta.Bucket = result.Bucket
-	return result.Key, nil
-}
-
-func validateUploadAllowedExtension(ctx context.Context, ext string) string {
-	sc, err := repository.GetSystemConfigByKey(ctx, model.ConfigKeyUploadAllowedExtensions)
-	if err != nil || sc.Value == "" {
-		return ""
-	}
-	allowedExts := strings.Split(strings.ToLower(sc.Value), ",")
-	for _, allowedExt := range allowedExts {
-		if strings.TrimSpace(allowedExt) == ext {
-			return ""
-		}
-	}
-	return shared.ErrUnsupportedFormat
-}
-
 func isRecordNotFound(err error) bool {
 	return errors.Is(err, gorm.ErrRecordNotFound)
 }

internal/apps/upload/handler/routers.go

@@ -8,7 +8,6 @@ package handler
 import (
 	"archive/zip"
 	"bytes"
-	"context"
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
@@ -21,16 +20,15 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
-	"time"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
 	"github.com/Rain-kl/Wavelet/internal/apps/upload/filesrv"
+	"github.com/Rain-kl/Wavelet/internal/apps/upload/ingest"
 	"github.com/Rain-kl/Wavelet/internal/apps/upload/shared"
 	uploadstorage "github.com/Rain-kl/Wavelet/internal/apps/upload/storage"
 	"github.com/Rain-kl/Wavelet/internal/apps/upload/util"
 	"github.com/Rain-kl/Wavelet/internal/common"
 	"github.com/Rain-kl/Wavelet/internal/common/response"
-	"github.com/Rain-kl/Wavelet/internal/db/idgen"
 	"github.com/Rain-kl/Wavelet/internal/model"
 	"github.com/Rain-kl/Wavelet/pkg/logger"
 	"github.com/gin-gonic/gin"
@@ -91,11 +89,6 @@ func UploadFile(c *gin.Context) {
 		ext = "bin"
 	}
 
-	if errMsg := validateUploadAllowedExtension(ctx, ext); errMsg != "" {
-		response.AbortBadRequest(c, errMsg)
-		return
-	}
-
 	hashWriter := sha256.New()
 	var buf bytes.Buffer
 	size, err := io.Copy(&buf, io.TeeReader(file, hashWriter))
@@ -120,51 +113,43 @@ func UploadFile(c *gin.Context) {
 		return
 	}
 
-	handled, lookupErr := tryInstantUpload(ctx, c, currUser, fileHash, size, mimeType, ext, origName, accessMode)
-	if handled {
-		return
-	}
-	if lookupErr != nil && !errors.Is(lookupErr, gorm.ErrRecordNotFound) {
-		response.AbortBadRequest(c, shared.ErrFileValidationFailed)
-		return
-	}
-
 	meta, errMsg := parseUploadMetadata(c, mimeType)
 	if errMsg != "" {
 		response.AbortBadRequest(c, errMsg)
 		return
 	}
 
-	id := idgen.NextUint64ID()
-	subPath := fmt.Sprintf("uploads/%s/%d.%s", time.Now().Format("2006/01/02"), id, ext)
-
-	subPath, err = storeUploadObject(ctx, subPath, size, mimeType, &buf, &meta)
-	if err != nil {
-		response.AbortBadRequest(c, err.Error())
-		return
-	}
-
-	newUpload := model.Upload{
-		ID:         id,
+	result, err := ingest.Ingest(ctx, ingest.Request{
 		UserID:     currUser.ID,
+		Reader:     bytes.NewReader(buf.Bytes()),
+		Size:       size,
 		FileName:   origName,
-		FilePath:   subPath,
-		FileSize:   size,
 		MimeType:   mimeType,
 		Extension:  ext,
 		Hash:       fileHash,
 		Type:       uploadType,
-		Status:     model.UploadStatusUsed,
-		AccessMode: accessMode,
+		AccessMode: &accessMode,
 		Metadata:   meta,
-	}
-
-	if err := saveNewUploadRecord(ctx, &newUpload, subPath); err != nil {
+		Policy:     ingest.PolicyDedupNewRecord,
+	})
+	if err != nil {
+		if errors.Is(err, ingest.ErrStorageReadOnly) {
+			response.AbortConflict(c, shared.ErrStorageReadOnly)
+			return
+		}
+		if err.Error() == shared.ErrUnsupportedFormat {
+			response.AbortBadRequest(c, shared.ErrUnsupportedFormat)
+			return
+		}
+		if err.Error() == shared.ErrSaveFileFailed {
+			response.AbortBadRequest(c, shared.ErrSaveFileFailed)
+			return
+		}
 		response.AbortBadRequest(c, shared.ErrSaveUploadRecordFailed)
 		return
 	}
 
-	c.JSON(http.StatusOK, response.OK(newUpload))
+	c.JSON(http.StatusOK, response.OK(result.Upload))
 }
 
 // DownloadFile 通用单文件下载接口
@@ -320,34 +305,6 @@ func resolveUploadAccessMode(c *gin.Context, uploadType string) (int, string) {
 	return accessMode, ""
 }
 
-func tryInstantUpload(ctx context.Context, c *gin.Context, currUser *model.User, fileHash string, size int64, mimeType, ext, origName string, accessMode int) (bool, error) {
-	existing, err := findReusableUpload(ctx, fileHash, size)
-	if err != nil {
-		return false, err
-	}
-	if uploadstorage.ReadOnly(ctx) {
-		response.AbortConflict(c, shared.ErrStorageReadOnly)
-		return true, nil
-	}
-
-	newUpload, err := createInstantUpload(ctx, existing, instantUploadInput{
-		UserID:     currUser.ID,
-		FileHash:   fileHash,
-		Size:       size,
-		MimeType:   mimeType,
-		Extension:  ext,
-		OrigName:   origName,
-		UploadType: c.DefaultPostForm("type", "generic"),
-		AccessMode: accessMode,
-	})
-	if err != nil {
-		response.AbortBadRequest(c, shared.ErrSaveUploadRecordFailed)
-		return true, err
-	}
-	c.JSON(http.StatusOK, response.OK(newUpload))
-	return true, nil
-}
-
 func parseUploadMetadata(c *gin.Context, mimeType string) (model.UploadMetadata, string) {
 	var meta model.UploadMetadata
 	metadataStr := c.DefaultPostForm("metadata", "")