async task framework

internal/apps/admin/task/errs.go

@@ -1,5 +1,5 @@
 /*
-Copyright 2025 linux.do
+Copyright 2025-2026 linux.do
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -17,8 +17,13 @@ limitations under the License.
 package task
 
 const (
-	InvalidTaskType    = "无效的任务类型"
-	InvalidTimeRange   = "无效的时间范围"
-	TaskDispatchFailed = "任务下发失败"
-	UserIDRequired     = "用户ID必填"
+	InvalidTaskType      = "无效的任务类型"
+	InvalidTimeRange     = "无效的时间范围"
+	TaskDispatchFailed   = "任务下发失败"
+	UserIDRequired       = "用户ID必填"
+	TaskNotFound         = "任务执行记录不存在"
+	TaskNotRetryable     = "该任务不支持重试"
+	TaskNotFailed        = "只有失败的任务才能重试"
+	TaskMaxRetryExceeded = "已达到最大重试次数"
+	TaskRetryFailed      = "任务重试失败"
 )

internal/apps/admin/task/routers.go

@@ -1,5 +1,5 @@
 /*
-Copyright 2025 linux.do
+Copyright 2025-2026 linux.do
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -19,12 +19,13 @@ package task
 import (
 	"fmt"
 	"net/http"
+	"strconv"
+	"strings"
 	"time"
 
 	"github.com/gin-gonic/gin"
-	"github.com/hibiken/asynq"
+	"github.com/linux-do/credit/internal/model"
 	"github.com/linux-do/credit/internal/task"
-	"github.com/linux-do/credit/internal/task/scheduler"
 	"github.com/linux-do/credit/internal/util"
 )
 
@@ -57,7 +58,7 @@ type DispatchTaskRequest struct {
 // @Accept json
 // @Produce json
 // @Security SessionCookie
-// @Param request body task.DispatchTaskRequest true "任务请求参数"
+// @Param request body DispatchTaskRequest true "任务请求参数"
 // @Success 200 {object} util.ResponseAny{data=string} "任务已入队"
 // @Failure 400 {object} util.ResponseAny "任务类型不存在或参数错误"
 // @Failure 401 {object} util.ResponseAny "未登录"
@@ -77,22 +78,113 @@ func DispatchTask(c *gin.Context) {
 		return
 	}
 
-	var taskInfo *asynq.Task
-	var taskID string
-
-	taskInfo = asynq.NewTask(meta.AsynqTask, nil)
-	taskID = fmt.Sprintf("manual_%s", req.TaskType)
-
-	_, err := scheduler.AsynqClient.Enqueue(
-		taskInfo,
-		asynq.TaskID(taskID),
-		asynq.MaxRetry(meta.MaxRetry),
-		asynq.Queue(meta.Queue),
-	)
+	taskID, err := task.DispatchTask(c.Request.Context(), req.TaskType, nil, "manual")
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, util.Err(fmt.Sprintf("%s: %v", TaskDispatchFailed, err)))
 		return
 	}
 
-	c.JSON(http.StatusOK, util.OKNil())
+	c.JSON(http.StatusOK, util.OK(taskID))
+}
+
+// ListTaskExecutions 查询任务执行记录列表
+// @Summary 查询任务执行记录
+// @Description 分页查询任务执行记录，支持按状态和任务类型筛选，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param status query string false "状态筛选 (pending/running/succeeded/failed)"
+// @Param task_type query string false "任务类型筛选"
+// @Param page query int false "页码" default(1)
+// @Param page_size query int false "每页条数" default(20)
+// @Success 200 {object} util.ResponseAny{data=object} "任务执行记录列表"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Router /api/v1/admin/tasks/executions [get]
+func ListTaskExecutions(c *gin.Context) {
+	var req model.ListTaskExecutionsRequest
+	if err := c.ShouldBindQuery(&req); err != nil {
+		c.JSON(http.StatusBadRequest, util.Err(err.Error()))
+		return
+	}
+
+	executions, total, err := model.ListTaskExecutions(c.Request.Context(), req)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, util.Err(err.Error()))
+		return
+	}
+
+	c.JSON(http.StatusOK, util.OK(gin.H{
+		"items":     executions,
+		"total":     total,
+		"page":      req.Page,
+		"page_size": req.PageSize,
+	}))
+}
+
+// GetTaskExecution 查询单条任务执行详情
+// @Summary 查询任务执行详情
+// @Description 根据 ID 查询任务执行记录详情，包含完整执行日志，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "任务执行记录 ID"
+// @Success 200 {object} util.ResponseAny{data=model.TaskExecution} "任务执行详情"
+// @Failure 400 {object} util.ResponseAny "参数错误"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 404 {object} util.ResponseAny "记录不存在"
+// @Router /api/v1/admin/tasks/executions/{id} [get]
+func GetTaskExecution(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, util.Err("无效的任务执行记录 ID"))
+		return
+	}
+
+	execution, err := model.GetTaskExecutionByID(c.Request.Context(), id)
+	if err != nil {
+		c.JSON(http.StatusNotFound, util.Err(TaskNotFound))
+		return
+	}
+
+	c.JSON(http.StatusOK, util.OK(execution))
+}
+
+// RetryTask 重试失败的任务
+// @Summary 重试失败任务
+// @Description 重新下发一条失败的任务，创建新的执行记录，需要管理员权限
+// @Tags admin
+// @Produce json
+// @Security SessionCookie
+// @Param id path int true "任务执行记录 ID"
+// @Success 200 {object} util.ResponseAny{data=string} "新任务的 TaskID"
+// @Failure 400 {object} util.ResponseAny "任务不支持重试或参数错误"
+// @Failure 401 {object} util.ResponseAny "未登录"
+// @Failure 403 {object} util.ResponseAny "无管理员权限"
+// @Failure 404 {object} util.ResponseAny "记录不存在"
+// @Failure 500 {object} util.ResponseAny "重试失败"
+// @Router /api/v1/admin/tasks/executions/{id}/retry [post]
+func RetryTask(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, util.Err("无效的任务执行记录 ID"))
+		return
+	}
+
+	newTaskID, err := task.RetryTask(c.Request.Context(), id)
+	if err != nil {
+		errMsg := err.Error()
+		switch {
+		case strings.Contains(errMsg, "不存在"):
+			c.JSON(http.StatusNotFound, util.Err(errMsg))
+		case strings.Contains(errMsg, "只有失败") || strings.Contains(errMsg, "不支持重试") || strings.Contains(errMsg, "已达到最大重试"):
+			c.JSON(http.StatusBadRequest, util.Err(errMsg))
+		default:
+			c.JSON(http.StatusInternalServerError, util.Err(fmt.Sprintf("%s: %v", TaskRetryFailed, err)))
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, util.OK(newTaskID))
 }

internal/apps/admin/task/routers_test.go

@@ -18,10 +18,13 @@ package task
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"testing"
+	"time"
 
 	"github.com/gin-gonic/gin"
 	"github.com/linux-do/credit/internal/apps/oauth"
@@ -29,6 +32,8 @@ import (
 	"github.com/linux-do/credit/internal/task"
 	"github.com/linux-do/credit/internal/testhelper"
 	"github.com/linux-do/credit/internal/util"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func setupTestRouter(authUser *model.User) *gin.Engine {
@@ -46,6 +51,9 @@ func setupTestRouter(authUser *model.User) *gin.Engine {
 
 	adminGroup.GET("/tasks/types", ListTaskTypes)
 	adminGroup.POST("/tasks/dispatch", DispatchTask)
+	adminGroup.GET("/tasks/executions", ListTaskExecutions)
+	adminGroup.GET("/tasks/executions/:id", GetTaskExecution)
+	adminGroup.POST("/tasks/executions/:id/retry", RetryTask)
 	return r
 }
 
@@ -104,9 +112,17 @@ func TestDispatchTask(t *testing.T) {
 		w := httptest.NewRecorder()
 		router.ServeHTTP(w, req)
 
-		if w.Code != http.StatusOK {
-			t.Errorf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
-		}
+		assert.Equal(t, http.StatusOK, w.Code, "Body: %s", w.Body.String())
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.Empty(t, resp.ErrorMsg)
+		assert.NotNil(t, resp.Data)
+
+		// 返回的 data 应该是 taskID
+		taskID, ok := resp.Data.(string)
+		assert.True(t, ok)
+		assert.NotEmpty(t, taskID)
 	})
 
 	t.Run("dispatch invalid task type failure", func(t *testing.T) {
@@ -119,14 +135,307 @@ func TestDispatchTask(t *testing.T) {
 		w := httptest.NewRecorder()
 		router.ServeHTTP(w, req)
 
-		if w.Code != http.StatusBadRequest {
-			t.Errorf("expected 400 Bad Request, got %d", w.Code)
-		}
+		assert.Equal(t, http.StatusBadRequest, w.Code)
 
 		var resp util.ResponseAny
 		json.Unmarshal(w.Body.Bytes(), &resp)
-		if resp.ErrorMsg != InvalidTaskType {
-			t.Errorf("expected error message '%s', got '%s'", InvalidTaskType, resp.ErrorMsg)
-		}
+		assert.Equal(t, InvalidTaskType, resp.ErrorMsg)
+	})
+
+	t.Run("dispatch with empty body failure", func(t *testing.T) {
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/dispatch", bytes.NewBuffer([]byte("{}")))
+		req.Header.Set("Content-Type", "application/json")
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
 	})
 }
+
+func TestListTaskExecutions(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+	ctx := context.Background()
+
+	// 准备测试数据
+	now := time.Now()
+	records := []*model.TaskExecution{
+		{TaskID: "exec_001", TaskType: "upload:cleanup_unused", TaskName: "清理上传", Status: model.TaskExecutionStatusSucceeded, TriggeredBy: "manual", Duration: 1500, Result: "清理完成", StartedAt: &now, FinishedAt: &now},
+		{TaskID: "exec_002", TaskType: "upload:cleanup_unused", TaskName: "清理上传", Status: model.TaskExecutionStatusFailed, TriggeredBy: "system", ErrorMessage: "连接超时", StartedAt: &now, FinishedAt: &now},
+		{TaskID: "exec_003", TaskType: "upload:cleanup_unused", TaskName: "清理上传", Status: model.TaskExecutionStatusPending, TriggeredBy: "manual", Retryable: true, MaxRetry: 3},
+	}
+	for _, r := range records {
+		err := model.CreateTaskExecution(ctx, r)
+		require.NoError(t, err)
+	}
+
+	t.Run("list all executions", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(3), data["total"])
+	})
+
+	t.Run("filter by status", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions?status=failed", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(1), data["total"])
+	})
+
+	t.Run("filter by task_type", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions?task_type=upload:cleanup_unused", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(3), data["total"])
+	})
+
+	t.Run("pagination", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions?page=1&page_size=2", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var data map[string]interface{}
+		json.Unmarshal(dataBytes, &data)
+
+		assert.Equal(t, float64(3), data["total"])
+	})
+}
+
+func TestGetTaskExecution(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+	ctx := context.Background()
+
+	// 创建测试记录
+	execution := &model.TaskExecution{
+		TaskID:      "detail_001",
+		TaskType:    "upload:cleanup_unused",
+		TaskName:    "清理上传",
+		Status:      model.TaskExecutionStatusSucceeded,
+		Log:         "[10:00:01] 开始扫描\n[10:00:02] 找到 50 个文件\n[10:00:03] 清理完成",
+		Result:      "共清理 50 个文件",
+		Duration:    2000,
+		Retryable:   true,
+		MaxRetry:    3,
+		TriggeredBy: "manual",
+	}
+	err := model.CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	t.Run("get existing execution", func(t *testing.T) {
+		url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d", execution.ID)
+		req, _ := http.NewRequest("GET", url, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+
+		dataBytes, _ := json.Marshal(resp.Data)
+		var detail model.TaskExecution
+		json.Unmarshal(dataBytes, &detail)
+
+		assert.Equal(t, "detail_001", detail.TaskID)
+		assert.Equal(t, model.TaskExecutionStatusSucceeded, detail.Status)
+		assert.Contains(t, detail.Log, "开始扫描")
+		assert.Contains(t, detail.Log, "清理完成")
+		assert.Equal(t, int64(2000), detail.Duration)
+	})
+
+	t.Run("get non-existent execution", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions/99999999", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusNotFound, w.Code)
+	})
+
+	t.Run("invalid ID format", func(t *testing.T) {
+		req, _ := http.NewRequest("GET", "/api/v1/admin/tasks/executions/invalid", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+}
+
+func TestRetryTask(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+	ctx := context.Background()
+
+	t.Run("retry failed task successfully", func(t *testing.T) {
+		now := time.Now()
+		execution := &model.TaskExecution{
+			TaskID:       "retry_api_001",
+			TaskType:     "upload:cleanup_unused",
+			TaskName:     "清理上传",
+			Status:       model.TaskExecutionStatusFailed,
+			ErrorMessage: "S3 连接超时",
+			Retryable:    true,
+			MaxRetry:     3,
+			RetryCount:   0,
+			TriggeredBy:  "manual",
+			StartedAt:    &now,
+			FinishedAt:   &now,
+		}
+		err := model.CreateTaskExecution(ctx, execution)
+		require.NoError(t, err)
+
+		url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d/retry", execution.ID)
+		req, _ := http.NewRequest("POST", url, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusOK, w.Code)
+
+		var resp util.ResponseAny
+		json.Unmarshal(w.Body.Bytes(), &resp)
+		assert.Empty(t, resp.ErrorMsg)
+		assert.NotNil(t, resp.Data)
+
+		// 验证新记录
+		newTaskID, ok := resp.Data.(string)
+		assert.True(t, ok)
+		assert.NotEmpty(t, newTaskID)
+
+		newExecution, err := model.GetTaskExecutionByTaskID(ctx, newTaskID)
+		require.NoError(t, err)
+		assert.Equal(t, 1, newExecution.RetryCount)
+		assert.Equal(t, "retry", newExecution.TriggeredBy)
+	})
+
+	t.Run("retry succeeded task fails", func(t *testing.T) {
+		execution := &model.TaskExecution{
+			TaskID:      "retry_succeeded_001",
+			TaskType:    "upload:cleanup_unused",
+			TaskName:    "清理上传",
+			Status:      model.TaskExecutionStatusSucceeded,
+			Retryable:   true,
+			MaxRetry:    3,
+			TriggeredBy: "manual",
+		}
+		err := model.CreateTaskExecution(ctx, execution)
+		require.NoError(t, err)
+
+		url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d/retry", execution.ID)
+		req, _ := http.NewRequest("POST", url, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+
+	t.Run("retry non-retryable task fails", func(t *testing.T) {
+		execution := &model.TaskExecution{
+			TaskID:      "retry_not_allowed_001",
+			TaskType:    "upload:cleanup_unused",
+			TaskName:    "清理上传",
+			Status:      model.TaskExecutionStatusFailed,
+			Retryable:   false,
+			TriggeredBy: "manual",
+		}
+		err := model.CreateTaskExecution(ctx, execution)
+		require.NoError(t, err)
+
+		url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d/retry", execution.ID)
+		req, _ := http.NewRequest("POST", url, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+
+	t.Run("retry non-existent task", func(t *testing.T) {
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/executions/99999999/retry", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusNotFound, w.Code)
+	})
+
+	t.Run("retry with invalid ID", func(t *testing.T) {
+		req, _ := http.NewRequest("POST", "/api/v1/admin/tasks/executions/invalid/retry", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusBadRequest, w.Code)
+	})
+}
+
+func TestRetryTaskMaxRetryExceeded(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	adminUser := &model.User{ID: 1001, Username: "admin", IsAdmin: true, SignKey: "admin_key"}
+	router := setupTestRouter(adminUser)
+	ctx := context.Background()
+
+	execution := &model.TaskExecution{
+		TaskID:      "retry_max_api_001",
+		TaskType:    "upload:cleanup_unused",
+		TaskName:    "清理上传",
+		Status:      model.TaskExecutionStatusFailed,
+		Retryable:   true,
+		MaxRetry:    1,
+		RetryCount:  1,
+		TriggeredBy: "retry",
+	}
+	err := model.CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	url := fmt.Sprintf("/api/v1/admin/tasks/executions/%d/retry", execution.ID)
+	req, _ := http.NewRequest("POST", url, nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}

internal/apps/upload/tasks.go

@@ -1,5 +1,5 @@
 /*
-Copyright 2025 linux.do
+Copyright 2025-2026 linux.do
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -18,34 +18,31 @@ package upload
 
 import (
 	"context"
+	"fmt"
 	"time"
 
-	"github.com/hibiken/asynq"
 	"github.com/linux-do/credit/internal/db"
-	"github.com/linux-do/credit/internal/logger"
 	"github.com/linux-do/credit/internal/model"
 	"github.com/linux-do/credit/internal/storage"
+	"github.com/linux-do/credit/internal/task"
 	"gorm.io/gorm"
 )
 
-// HandleCleanupUnusedUploads 处理清理未使用上传文件的定时任务
-func HandleCleanupUnusedUploads(ctx context.Context, t *asynq.Task) error {
-	logger.InfoF(ctx, "开始清理未使用的上传文件任务")
-	cleanupUnusedUploads(ctx)
-	logger.InfoF(ctx, "未使用上传文件清理任务完成")
-	return nil
-}
+// CleanupUnusedUploadsHandler 清理未使用上传文件的异步任务处理器
+type CleanupUnusedUploadsHandler struct{}
 
-// cleanupUnusedUploads 清理超过1小时未使用的上传文件
-func cleanupUnusedUploads(ctx context.Context) {
+// Execute 执行清理未使用上传文件的业务逻辑
+func (h *CleanupUnusedUploadsHandler) Execute(ctx context.Context, payload []byte) (*task.TaskResult, error) {
 	const batchSize = 100 // 每批处理100个文件
 	var lastID uint64 = 0
-	var totalProcessed int = 0
-	var totalDeleted int = 0
+	var totalProcessed int
+	var totalDeleted int
 
 	// 计算1小时前的时间
 	oneHourAgo := time.Now().Add(-1 * time.Hour)
 
+	task.AppendLog(ctx, "开始扫描未使用上传文件，阈值: %s", oneHourAgo.Format(time.RFC3339))
+
 	for {
 		// 使用游标分页查询未使用且超过1小时的上传记录
 		var unusedUploads []model.Upload
@@ -54,8 +51,8 @@ func cleanupUnusedUploads(ctx context.Context) {
 			Order("id ASC").
 			Limit(batchSize).
 			Find(&unusedUploads).Error; err != nil {
-			logger.ErrorF(ctx, "查询未使用的上传文件失败: %v", err)
-			return
+			task.AppendLog(ctx, "查询未使用的上传文件失败: %v", err)
+			return nil, fmt.Errorf("查询未使用的上传文件失败: %w", err)
 		}
 
 		// 没有更多数据，退出循环
@@ -63,7 +60,7 @@ func cleanupUnusedUploads(ctx context.Context) {
 			break
 		}
 
-		logger.InfoF(ctx, "本批次找到 %d 个需要清理的上传文件", len(unusedUploads))
+		task.AppendLog(ctx, "本批次找到 %d 个需要清理的上传文件", len(unusedUploads))
 
 		// 处理每个未使用的上传文件
 		for _, upload := range unusedUploads {
@@ -84,22 +81,17 @@ func cleanupUnusedUploads(ctx context.Context) {
 
 				return nil
 			}); err != nil {
-				logger.ErrorF(ctx, "清理上传文件失败 [ID:%d]: %v", upload.ID, err)
+				task.AppendLog(ctx, "清理上传文件失败 [ID:%d]: %v", upload.ID, err)
 				lastID = upload.ID
 				continue
 			}
 
 			totalDeleted++
-			logger.InfoF(ctx, "成功清理上传文件 [ID:%d, Path:%s, Size:%d bytes]", upload.ID, upload.FilePath, upload.FileSize)
-
-			// 更新游标
 			lastID = upload.ID
 		}
 	}
 
-	if totalDeleted > 0 {
-		logger.InfoF(ctx, "清理任务完成，共处理 %d 个文件，成功删除 %d 个", totalProcessed, totalDeleted)
-	} else {
-		logger.InfoF(ctx, "没有需要清理的上传文件")
-	}
+	msg := fmt.Sprintf("共处理 %d 个文件，成功删除 %d 个", totalProcessed, totalDeleted)
+	task.AppendLog(ctx, msg)
+	return &task.TaskResult{Message: msg}, nil
 }

internal/apps/upload/tasks_test.go

@@ -0,0 +1,139 @@
+/*
+Copyright 2025-2026 linux.do
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package upload
+
+import (
+	"context"
+	"io"
+	"testing"
+	"time"
+
+	"github.com/linux-do/credit/internal/db"
+	"github.com/linux-do/credit/internal/model"
+	"github.com/linux-do/credit/internal/storage"
+	"github.com/linux-do/credit/internal/task"
+	"github.com/linux-do/credit/internal/testhelper"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCleanupUnusedUploadsHandler_Execute(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Mock S3 存储（让 DeleteObject 总是成功）
+	storageMock := storage.MockStorage(
+		func(ctx context.Context, key string, body io.Reader, size int64, contentType string) error {
+			return nil
+		},
+		func(ctx context.Context, key string) (*storage.ObjectInfo, error) { return nil, nil },
+		func(ctx context.Context, key string) error { return nil },
+	)
+	defer storageMock()
+
+	ctx := context.Background()
+
+	// 准备测试数据：创建一些上传记录
+	now := time.Now()
+	twoHoursAgo := now.Add(-2 * time.Hour)
+
+	records := []*model.Upload{
+		// 超过1小时且状态为 pending 的记录 —— 应被清理
+		{
+			UserID: 1001, FileName: "old_file_1.jpg", FilePath: "uploads/old_1.jpg",
+			FileSize: 1024, MimeType: "image/jpeg", Extension: "jpg", Hash: "hash1",
+			StorageDriver: "s3", Type: "attachment", Status: model.UploadStatusPending,
+			CreatedAt: twoHoursAgo,
+		},
+		{
+			UserID: 1001, FileName: "old_file_2.png", FilePath: "uploads/old_2.png",
+			FileSize: 2048, MimeType: "image/png", Extension: "png", Hash: "hash2",
+			StorageDriver: "s3", Type: "attachment", Status: model.UploadStatusPending,
+			CreatedAt: twoHoursAgo,
+		},
+		// 状态为 used 的记录 —— 不应被清理
+		{
+			UserID: 1001, FileName: "used_file.jpg", FilePath: "uploads/used.jpg",
+			FileSize: 512, MimeType: "image/jpeg", Extension: "jpg", Hash: "hash3",
+			StorageDriver: "s3", Type: "attachment", Status: model.UploadStatusUsed,
+			CreatedAt: twoHoursAgo,
+		},
+		// 不到1小时的 pending 记录 —— 不应被清理
+		{
+			UserID: 1001, FileName: "recent_file.jpg", FilePath: "uploads/recent.jpg",
+			FileSize: 256, MimeType: "image/jpeg", Extension: "jpg", Hash: "hash4",
+			StorageDriver: "s3", Type: "attachment", Status: model.UploadStatusPending,
+			CreatedAt: now.Add(-10 * time.Minute),
+		},
+	}
+	for _, r := range records {
+		err := db.DB(ctx).Create(r).Error
+		require.NoError(t, err)
+	}
+
+	// 执行 handler
+	handler := &CleanupUnusedUploadsHandler{}
+	result, err := handler.Execute(ctx, nil)
+
+	// 验证结果
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.Contains(t, result.Message, "共处理 2 个文件，成功删除 2 个")
+
+	// 验证数据库状态：pending 且超过1小时的应被标记为 deleted
+	var pendingCount int64
+	db.DB(ctx).Model(&model.Upload{}).Where("status = ?", model.UploadStatusPending).Count(&pendingCount)
+	assert.Equal(t, int64(1), pendingCount, "应只剩1条 pending 记录（最近的文件）")
+
+	var deletedCount int64
+	db.DB(ctx).Model(&model.Upload{}).Where("status = ?", model.UploadStatusDeleted).Count(&deletedCount)
+	assert.Equal(t, int64(2), deletedCount, "应有2条被标记为 deleted")
+
+	var usedCount int64
+	db.DB(ctx).Model(&model.Upload{}).Where("status = ?", model.UploadStatusUsed).Count(&usedCount)
+	assert.Equal(t, int64(1), usedCount, "used 状态的文件不应受影响")
+}
+
+func TestCleanupUnusedUploadsHandler_ExecuteNoFiles(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	// Mock S3 存储
+	storageMock := storage.MockStorage(
+		func(ctx context.Context, key string, body io.Reader, size int64, contentType string) error {
+			return nil
+		},
+		func(ctx context.Context, key string) (*storage.ObjectInfo, error) { return nil, nil },
+		func(ctx context.Context, key string) error { return nil },
+	)
+	defer storageMock()
+
+	ctx := context.Background()
+
+	// 没有任何上传记录
+	handler := &CleanupUnusedUploadsHandler{}
+	result, err := handler.Execute(ctx, nil)
+
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.Contains(t, result.Message, "共处理 0 个文件，成功删除 0 个")
+}
+
+func TestCleanupUnusedUploadsHandler_ImplementsTaskHandler(t *testing.T) {
+	// 编译期验证 CleanupUnusedUploadsHandler 实现了 TaskHandler 接口
+	var _ task.TaskHandler = (*CleanupUnusedUploadsHandler)(nil)
+}