feat(cron-task): implement cron task module with business logic and scheduling

- Added a new CronTaskModule to manage scheduled tasks, including cleaning access records, resetting IP access, and pushing to search engines.
- Implemented CronBusinessService for task execution logic and CronTaskService for task management and scheduling.
- Introduced CronTaskController for handling API requests related to cron tasks.
- Created CronTaskScheduler to define and schedule cron jobs using NestJS's scheduling capabilities.
- Defined cron task types and metadata for better organization and management of scheduled tasks.

These changes enhance the application's ability to perform background tasks efficiently and improve overall system maintenance.

Signed-off-by: Innei <tukon479@gmail.com>

Author: Innei

apps/core/src/app.module.ts

@@ -29,6 +29,7 @@ import { BackupModule } from './modules/backup/backup.module'
 import { CategoryModule } from './modules/category/category.module'
 import { CommentModule } from './modules/comment/comment.module'
 import { ConfigsModule } from './modules/configs/configs.module'
+import { CronTaskModule } from './modules/cron-task/cron-task.module'
 import { DebugModule } from './modules/debug/debug.module'
 import { DependencyModule } from './modules/dependency/dependency.module'
 import { DraftModule } from './modules/draft/draft.module'
@@ -87,6 +88,7 @@ import { TaskQueueModule } from './processors/task-queue/task-queue.module'
     CategoryModule,
     CommentModule,
     ConfigsModule,
+    CronTaskModule,
 
     DependencyModule,
     DraftModule,

…processors/helper/helper.cron.service.ts …dules/cron-task/cron-business.service.tsapps/core/src/processors/helper/helper.cron.service.ts renamed to apps/core/src/modules/cron-task/cron-business.service.ts apps/core/src/processors/helper/helper.cron.service.ts renamed to apps/core/src/modules/cron-task/cron-business.service.ts

@@ -1,25 +1,28 @@
 import { rm } from 'node:fs/promises'
 import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common'
-import { CronExpression } from '@nestjs/schedule'
-import { CronDescription } from '~/common/decorators/cron-description.decorator'
-import { CronOnce } from '~/common/decorators/cron-once.decorator'
 import { RedisKeys } from '~/constants/cache.constant'
 import { STATIC_FILE_TRASH_DIR, TEMP_DIR } from '~/constants/path.constant'
 import { AggregateService } from '~/modules/aggregate/aggregate.service'
 import { AnalyzeModel } from '~/modules/analyze/analyze.model'
 import { ConfigsService } from '~/modules/configs/configs.service'
 import { FileReferenceService } from '~/modules/file/file-reference.service'
+import { HttpService } from '~/processors/helper/helper.http.service'
+import type { StoreJWTPayload } from '~/processors/helper/helper.jwt.service'
+import { JWTService } from '~/processors/helper/helper.jwt.service'
+import { RedisService } from '~/processors/redis/redis.service'
 import { InjectModel } from '~/transformers/model.transformer'
 import { getRedisKey } from '~/utils/redis.util'
 import dayjs from 'dayjs'
 import { mkdirp } from 'mkdirp'
-import { RedisService } from '../redis/redis.service'
-import { HttpService } from './helper.http.service'
-import type { StoreJWTPayload } from './helper.jwt.service'
-import { JWTService } from './helper.jwt.service'
 
+/**
+ * CronBusinessService - Cron 任务业务逻辑层
+ *
+ * 本服务仅保留业务方法的实现，供 CronTaskService 调用
+ * 调度逻辑在 CronTaskScheduler 中
+ */
 @Injectable()
-export class CronService {
+export class CronBusinessService {
   private logger: Logger
   constructor(
     private readonly http: HttpService,
@@ -32,42 +35,38 @@ export class CronService {
     @Inject(forwardRef(() => AggregateService))
     private readonly aggregateService: AggregateService,
   ) {
-    this.logger = new Logger(CronService.name)
+    this.logger = new Logger(CronBusinessService.name)
   }
 
-  @CronOnce(CronExpression.EVERY_1ST_DAY_OF_MONTH_AT_MIDNIGHT, {
-    name: 'cleanAccessRecord',
-  })
-  @CronDescription('清理访问记录')
+  /**
+   * 清理 7 天前的访问记录
+   */
   async cleanAccessRecord() {
     const cleanDate = dayjs().add(-7, 'd')
 
-    await this.analyzeModel.deleteMany({
+    const result = await this.analyzeModel.deleteMany({
       timestamp: {
         $lte: cleanDate.toDate(),
       },
     })
 
     this.logger.log('--> 清理访问记录成功')
+    return { deletedCount: result.deletedCount }
   }
+
   /**
-   * @description 每天凌晨删除缓存
+   * 每天凌晨删除 IP 访问缓存
    */
-  @CronOnce(CronExpression.EVERY_DAY_AT_MIDNIGHT, { name: 'resetIPAccess' })
-  @CronDescription('清理 IP 访问记录')
   async resetIPAccess() {
     await this.redisService.getClient().del(getRedisKey(RedisKeys.AccessIp))
 
     this.logger.log('--> 清理 IP 访问记录成功')
+    return { success: true }
   }
 
   /**
-   * @description 每天凌晨删除缓存
+   * 每天凌晨删除喜欢/阅读记录缓存
    */
-  @CronOnce(CronExpression.EVERY_DAY_AT_MIDNIGHT, {
-    name: 'resetLikedOrReadArticleRecord',
-  })
-  @CronDescription('清理喜欢数')
   async resetLikedOrReadArticleRecord() {
     const redis = this.redisService.getClient()
 
@@ -81,18 +80,22 @@ export class CronService {
     )
 
     this.logger.log('--> 清理喜欢数成功')
+    return { success: true }
   }
 
-  @CronOnce(CronExpression.EVERY_DAY_AT_3AM, { name: 'cleanTempDirectory' })
-  @CronDescription('清理临时文件')
+  /**
+   * 清理临时文件目录
+   */
   async cleanTempDirectory() {
     await rm(TEMP_DIR, { recursive: true })
     mkdirp.sync(STATIC_FILE_TRASH_DIR)
     this.logger.log('--> 清理临时文件成功')
+    return { success: true }
   }
 
-  @CronOnce(CronExpression.EVERY_DAY_AT_1AM, { name: 'pushToBaiduSearch' })
-  @CronDescription('推送到百度搜索')
+  /**
+   * 推送站点地图到百度搜索
+   */
   async pushToBaiduSearch() {
     const {
       url: { webUrl },
@@ -103,7 +106,7 @@ export class CronService {
       const token = configs.token
       if (!token) {
         this.logger.error('[BaiduSearchPushTask] token 为空')
-        return
+        return { skipped: true, reason: 'token is empty' }
       }
 
       const pushUrls = await this.aggregateService.getSiteMapContent()
@@ -124,30 +127,31 @@ export class CronService {
           },
         )
         this.logger.log(`百度站长提交结果：${JSON.stringify(res.data)}`)
-        return res.data
+        return { response: res.data }
       } catch (error) {
         this.logger.error(`百度推送错误：${error.message}`)
         throw error
       }
     }
-    return null
+    return { skipped: true, reason: 'Baidu search push is disabled' }
   }
 
-  @CronOnce(CronExpression.EVERY_DAY_AT_1AM, { name: 'pushToBingSearch' })
-  @CronDescription('推送到 Bing')
+  /**
+   * 推送站点地图到 Bing 搜索
+   */
   async pushToBingSearch() {
     const {
       url: { webUrl },
       bingSearchOptions: configs,
     } = await this.configs.waitForConfigReady()
 
     if (!configs.enable) {
-      return
+      return { skipped: true, reason: 'Bing search push is disabled' }
     }
     const apiKey = configs.token
     if (!apiKey) {
       this.logger.error('[BingSearchPushTask] API key 为空')
-      return
+      return { skipped: true, reason: 'API key is empty' }
     }
 
     const pushUrls = await this.aggregateService.getSiteMapContent()
@@ -172,17 +176,16 @@ export class CronService {
       } else {
         this.logger.log(`Bing 站长提交结果：${JSON.stringify(res.data)}`)
       }
-      return res.data
+      return { response: res.data }
     } catch (error) {
       this.logger.error(`Bing 推送错误：${error.message}`)
+      throw error
     }
-    return null
   }
 
-  @CronDescription('扫表：删除过期 JWT')
-  @CronOnce(CronExpression.EVERY_DAY_AT_1AM, {
-    name: 'deleteExpiredJWT',
-  })
+  /**
+   * 扫表删除过期的 JWT
+   */
   async deleteExpiredJWT() {
     this.logger.log('--> 开始扫表，清除过期的 token')
     const redis = this.redisService.getClient()
@@ -218,18 +221,19 @@ export class CronService {
     )
 
     this.logger.log(`--> 删除了 ${deleteCount} 个过期的 token`)
+    return { deletedCount: deleteCount }
   }
 
-  @CronDescription('清理孤儿图片')
-  @CronOnce(CronExpression.EVERY_HOUR, {
-    name: 'cleanupOrphanImages',
-  })
+  /**
+   * 清理孤儿图片
+   */
   async cleanupOrphanImages() {
     this.logger.log('--> 开始清理孤儿图片')
     const { deletedCount, totalOrphan } =
       await this.fileReferenceService.cleanupOrphanFiles(60)
     this.logger.log(
       `--> 清理孤儿图片完成：删除了 ${deletedCount}/${totalOrphan} 个文件`,
     )
+    return { deletedCount, totalOrphan }
   }
 }

apps/core/src/modules/cron-task/cron-task.controller.ts

@@ -0,0 +1,119 @@
+import { Body, Delete, Get, Param, Post, Query } from '@nestjs/common'
+import { ApiController } from '~/common/decorators/api-controller.decorator'
+import { Auth } from '~/common/decorators/auth.decorator'
+import { HTTPDecorators } from '~/common/decorators/http.decorator'
+import { BizException } from '~/common/exceptions/biz.exception'
+import { ErrorCodeEnum } from '~/constants/error-code.constant'
+import { TaskStatus } from '~/processors/task-queue/task-queue.types'
+import { isString } from '~/utils/validator.util'
+import { CronTaskService } from './cron-task.service'
+import { CronTaskType, type CronTaskTypeValue } from './cron-task.types'
+
+@ApiController('cron-task')
+@Auth()
+export class CronTaskController {
+  constructor(private readonly cronTaskService: CronTaskService) {}
+
+  @Get('/')
+  @HTTPDecorators.Bypass
+  async getCronDefinitions() {
+    return this.cronTaskService.getCronDefinitions()
+  }
+
+  @Get('/tasks')
+  @HTTPDecorators.Bypass
+  async getTasks(
+    @Query('status') status?: TaskStatus,
+    @Query('type') type?: CronTaskTypeValue,
+    @Query('page') page?: string,
+    @Query('size') size?: string,
+  ) {
+    return this.cronTaskService.getTasks({
+      status,
+      type,
+      page: page ? Number.parseInt(page, 10) : 1,
+      size: size ? Number.parseInt(size, 10) : 50,
+    })
+  }
+
+  @Get('/tasks/:taskId')
+  @HTTPDecorators.Bypass
+  async getTask(@Param('taskId') taskId: string) {
+    if (!isString(taskId)) {
+      throw new BizException(
+        ErrorCodeEnum.InvalidParameter,
+        'taskId must be string',
+      )
+    }
+    const task = await this.cronTaskService.getTask(taskId)
+    if (!task) {
+      throw new BizException(ErrorCodeEnum.AITaskNotFound)
+    }
+    return task
+  }
+
+  @Post('/run/:type')
+  async runCronTask(@Param('type') type: string) {
+    if (!isString(type)) {
+      throw new BizException(
+        ErrorCodeEnum.InvalidParameter,
+        'type must be string',
+      )
+    }
+
+    const validTypes = Object.values(CronTaskType) as string[]
+    if (!validTypes.includes(type)) {
+      throw new BizException(ErrorCodeEnum.CronNotFound, type)
+    }
+
+    return this.cronTaskService.createCronTask(type as CronTaskTypeValue)
+  }
+
+  @Post('/tasks/:taskId/cancel')
+  async cancelTask(@Param('taskId') taskId: string) {
+    if (!isString(taskId)) {
+      throw new BizException(
+        ErrorCodeEnum.InvalidParameter,
+        'taskId must be string',
+      )
+    }
+    const success = await this.cronTaskService.cancelTask(taskId)
+    return { success }
+  }
+
+  @Post('/tasks/:taskId/retry')
+  async retryTask(@Param('taskId') taskId: string) {
+    if (!isString(taskId)) {
+      throw new BizException(
+        ErrorCodeEnum.InvalidParameter,
+        'taskId must be string',
+      )
+    }
+    return this.cronTaskService.retryTask(taskId)
+  }
+
+  @Delete('/tasks/:taskId')
+  async deleteTask(@Param('taskId') taskId: string) {
+    if (!isString(taskId)) {
+      throw new BizException(
+        ErrorCodeEnum.InvalidParameter,
+        'taskId must be string',
+      )
+    }
+    await this.cronTaskService.deleteTask(taskId)
+    return { success: true }
+  }
+
+  @Delete('/tasks')
+  async deleteTasks(
+    @Body()
+    body: {
+      status?: TaskStatus
+      type?: CronTaskTypeValue
+      before: number
+    },
+  ) {
+    const deleted = await this.cronTaskService.deleteTasks(body)
+    return { deleted }
+  }
+}

apps/core/src/modules/cron-task/cron-task.module.ts

@@ -0,0 +1,14 @@
+import { forwardRef, Module } from '@nestjs/common'
+import { AggregateModule } from '~/modules/aggregate/aggregate.module'
+import { CronBusinessService } from './cron-business.service'
+import { CronTaskController } from './cron-task.controller'
+import { CronTaskScheduler } from './cron-task.scheduler'
+import { CronTaskService } from './cron-task.service'
+
+@Module({
+  imports: [forwardRef(() => AggregateModule)],
+  controllers: [CronTaskController],
+  providers: [CronBusinessService, CronTaskService, CronTaskScheduler],
+  exports: [CronTaskService, CronBusinessService],
+})
+export class CronTaskModule {}