create-bubbles 0.1.24 → 0.1.26

package/template-vp-monorepo-react-nestjs/.spaces/server/06./345/205/254/345/205/261/351/230/237/345/210/227/346/216/245/345/205/245/346/226/271/346/241/210//344/270/212/344/274/240/346/270/205/347/220/206.md

@@ -0,0 +1,1465 @@
+# 上传文件定时清理：给前端开发者的 NestJS + BullMQ 实现教程
+
+> 本文是动手实现教程，代码需要你按步骤写入项目；更新本文不代表业务代码已经实现。
+> 基线：2026-09-05 的 `apps/server`，PostgreSQL + Drizzle + MinIO，公共队列沿用 [README](./README.md)。
+> 最终效果：后端每分钟自动扫描，找到过期且没有分片正在上传的会话，逐个释放 MinIO 中的未完成分片，并保存清理结果。
+
+## 先理解最终效果
+
+用户上传大文件，只上传了两片就关闭页面。数据库留下一个上传会话，MinIO 保存着这两片。即使用户不再打开页面，后端也应该在会话过期后回收它们。
+
+这件事由后端定时完成。前端不用加定时器，也不用定期调用“清理接口”。本教程选定 **BullMQ Job Scheduler** 作为定时器；项目已经选择 BullMQ，它自带周期调度能力，不需要再安装 `@nestjs/schedule`。
+
+```text
+NestJS 启动：向 Redis 注册一条固定的周期规则
+                    │
+                    ▼ 每 60 秒产生扫描任务
+         upload.cleanup-scan.v1
+                    │
+                    ▼ 公共 TaskQueueProcessor 分发
+         UploadCleanupScanner
+                    │
+                    ├── 查询最多 100 个候选会话
+                    └── 每个会话投递一个小任务
+                                  │
+                                  ▼
+                     upload.multipart-expire.v1
+                                  │
+                                  ▼
+                       UploadCleanupHandler
+                                  ├── 重新检查数据库
+                                  ├── 领取清理权
+                                  ├── 调用 MinIO Abort
+                                  └── 确认后写入 cleanedAt
+```
+
+扫描和清理拆开，一条记录失败时就只重试那条记录。`await enqueue()` 只表示写入 Redis 成功，不表示清理完成。队列繁忙时实际执行会延后，定时扫描不保证精确到秒。
+
+阅读路线：第 0～3 步准备配置和数据；第 4～6 步解决“哪些记录允许清理”；第 7～10 步把任务和定时器接起来；第 11～12 步验证结果；最后两步用于排障和部署。第一次可以先读第 9、12 步了解效果，真正写代码时按顺序进行。
+
+### 前端概念对照
+
+| 后端概念           | 可以怎样理解                   | 本文用途                       |
+| ------------------ | ------------------------------ | ------------------------------ |
+| Scheduler          | 保存在服务器的重复执行规则     | 每分钟产生一个扫描 Job         |
+| Job / Payload      | 一次任务及其参数               | 清理某个 `uploadSessionId`     |
+| Queue              | Redis 中的待办列表             | 沿用 `server-tasks`            |
+| Worker / Processor | 从列表取任务的执行者           | 校验参数，再调用业务方法       |
+| Repository         | 封装数据库读写的模块           | 查询、领取、保存结果           |
+| 依赖注入           | Nest 创建并传入 Service 实例   | 构造函数参数由 Module 配置提供 |
+| 幂等               | 同一操作重复执行仍得到正确结果 | 避免重试导致误处理             |
+| 租约 Lease         | 有到期时间的占用凭证           | 标记分片在途、Worker 正在清理  |
+
+### 这篇教程清理哪些数据
+
+| 状态                                     | 处理方式                             |
+| ---------------------------------------- | ------------------------------------ |
+| `uploading`，未过期                      | 保留                                 |
+| `uploading`，已过期                      | 等活动分片租约结束，再封口并回收     |
+| `expired`，`cleanedAt` 为空              | 继续回收，不能当成已经清理成功       |
+| `aborting` / `aborted`，`cleanedAt` 为空 | 对取消操作做幂等补偿，确认分片已释放 |
+| `completed`                              | 保留正式文件                         |
+| `completing`                             | 不 Abort，交给完成结果恢复流程       |
+
+统一规定：`expired` 表示“会话关闭，不能继续上传”；**`cleanedAt` 非空才表示确认 Multipart 已释放**。清理任务不会调用 `DeleteObject`，不会删除已完成的正式文件，也不删除上传会话记录。
+
+`completing` 可能是 MinIO 已合并成功、数据库还没写回。现有 `getStatus()` 会通过 `recoverCompletedObject()` 检查最终对象并补写 `completed`。长期无法恢复的记录需要单独对账，不能因为过期就 Abort。本篇实现未完成上传的定时回收，不承诺恢复所有上传异常。
+
+## 第 0 步：先跑通公共队列
+
+当前仓库已声明 `bullmq` 和 `@nestjs/bullmq` 依赖，并已有公共队列文件。开始前先检查基础能力是否跑通；如果你还在较早的代码版本上，按基础篇补齐即可，不必重复创建已有文件。
+
+对照 [公共队列 README](./README.md)，确认下面这些文件存在，并看到 `system.queue-smoke.v1` 被 Worker 成功处理，再继续本篇：
+
+```text
+apps/server/src/config/queue.config.ts
+apps/server/src/modules/task-queue/task-queue.constants.ts
+apps/server/src/modules/task-queue/task-queue.contracts.ts
+apps/server/src/modules/task-queue/task-queue.service.ts
+apps/server/src/modules/task-queue/task-queue.processor.ts
+apps/server/src/modules/task-queue/task-queue.module.ts
+apps/server/src/modules/task-queue/queue-worker.bootstrap.ts
+```
+
+README 的“暂不实现定时任务”是基础篇范围。本篇就是接着基础篇实现定时清理。
+
+本文所有 `vp`、`docker compose` 命令在模板根目录执行，即同时包含 `apps/`、`pnpm-workspace.yaml`、`docker-compose.yml` 的目录：
+
+```powershell
+docker compose up -d postgres redis minio
+vp run --filter server build
+```
+
+Bucket、访问账号沿用已经配置好的上传环境。上传表已迁移，初始化和上传分片接口应能正常使用。
+
+注意：当前上传 Repository 文件真实拼写是 **`upload.reponsitory.ts`**，本文按这个路径引用。
+
+## 第 1 步：了解文件分工
+
+后续新增这些文件，现在先看职责，不必一次性创建空文件：
+
+```text
+apps/server/src/config/
+└── upload-cleanup.config.ts       # 频率、批量大小、预览开关
+
+apps/server/src/modules/task-queue/
+└── task-queue-worker.module.ts    # 组装公共 Worker 与上传业务
+
+apps/server/src/modules/upload/
+├── upload-session-lock.ts        # 同一会话的短事务互斥
+├── upload-part-lease.service.ts   # 登记并续租正在上传的分片
+├── upload-cleanup.repository.ts   # 候选查询、领取、写回
+├── upload-cleanup.scanner.ts      # 投递候选 ID
+├── upload-cleanup.handler.ts      # 真正调用 MinIO
+└── upload-cleanup.scheduler.ts    # 注册周期规则
+```
+
+还会修改 Schema、原上传 Service/Repository、任务契约、Processor 和 Module。涉及原上传流程，是因为后台必须知道有没有分片正在写入，不能只看过期时间。
+
+## 第 2 步：增加配置，默认先预览
+
+在 `apps/server/.env.development` 增加：
+
+```dotenv
+UPLOAD_CLEANUP_ENABLED=true
+UPLOAD_CLEANUP_DRY_RUN=true
+UPLOAD_CLEANUP_INTERVAL_MS=60000
+UPLOAD_CLEANUP_BATCH_SIZE=100
+```
+
+| 配置          | 含义                                                        |
+| ------------- | ----------------------------------------------------------- |
+| `ENABLED`     | 是否允许扫描及清理                                          |
+| `DRY_RUN`     | `true` 时只打印候选，不投递实际清理；已排队任务也检查此开关 |
+| `INTERVAL_MS` | 扫描间隔，毫秒；`60000` 是一分钟                            |
+| `BATCH_SIZE`  | 每轮最多扫描条数，不是 Worker 并发数                        |
+
+上传有效期仍由原来的 `storage.sessionTtlMs` 和记录中的 `expiresAt` 决定。每分钟扫描，不等于文件只能上传一分钟。
+
+新建 `apps/server/src/config/upload-cleanup.config.ts`：
+
+```ts
+import { registerAs } from '@nestjs/config'
+import { z } from 'zod'
+
+const BooleanText = z.enum(['true', 'false']).transform((value) => value === 'true')
+const CleanupEnv = z.object({
+  UPLOAD_CLEANUP_ENABLED: BooleanText.default(true),
+  UPLOAD_CLEANUP_DRY_RUN: BooleanText.default(true),
+  UPLOAD_CLEANUP_INTERVAL_MS: z.coerce.number().int().min(5_000).max(86_400_000).default(60_000),
+  UPLOAD_CLEANUP_BATCH_SIZE: z.coerce.number().int().min(1).max(1_000).default(100),
+})
+
+export default registerAs('uploadCleanup', () => {
+  const env = CleanupEnv.parse(process.env)
+  return {
+    enabled: env.UPLOAD_CLEANUP_ENABLED,
+    dryRun: env.UPLOAD_CLEANUP_DRY_RUN,
+    intervalMs: env.UPLOAD_CLEANUP_INTERVAL_MS,
+    batchSize: env.UPLOAD_CLEANUP_BATCH_SIZE,
+  }
+})
+```
+
+沿用项目的 Zod 4，`.default(true)` 是 `transform` 后的布尔默认值。不能用 `Boolean('false')` 解析环境变量，那样仍得到 `true`。
+
+在 `apps/server/src/config/index.ts` 增加：
+
+```ts
+export { default as uploadCleanupConfig } from './upload-cleanup.config'
+```
+
+在 `apps/server/src/app.module.ts` 从 `@/config` 导入 `uploadCleanupConfig`，追加到 `ConfigModule.forRoot({ load: [...] })`，保留现有配置和基础篇的 `queueConfig`。
+
+以后 `config.getOrThrow<boolean>('uploadCleanup.enabled')` 读到的就是布尔值。
+
+## 第 3 步：增加清理字段和分片租约表
+
+### 3.1 上传会话字段
+
+修改 `apps/server/src/database/schema.ts`，在 `uploadSessions` 的字段对象追加：
+
+```ts
+cleanedAt: timestamp('cleaned_at', { withTimezone: true }),
+cleanupClaimId: uuid('cleanup_claim_id'),
+cleanupLeaseUntil: timestamp('cleanup_lease_until', { withTimezone: true }),
+nextCleanupAt: timestamp('next_cleanup_at', { withTimezone: true }).defaultNow().notNull(),
+lastCleanupError: varchar('last_cleanup_error', { length: 100 }),
+```
+
+在同一个表的索引数组追加：
+
+```ts
+index('upload_sessions_cleanup_due_idx')
+  .on(table.nextCleanupAt, table.id)
+  .where(sql`${table.cleanedAt} is null and ${table.status} in ('uploading', 'expired', 'aborting', 'aborted')`),
+```
+
+为此在 Schema 顶部增加 `import { sql } from 'drizzle-orm'`。这是部分索引：只为仍可能需要清理的记录建立扫描入口，避免历史已完成记录越来越多时，每轮都从它们中间筛选。
+
+| 字段                | 作用                                               |
+| ------------------- | -------------------------------------------------- |
+| `cleanedAt`         | 区分“过期”和“确实清完”                             |
+| `cleanupClaimId`    | 本次 Worker 的随机 UUID，旧 Worker 不能覆盖新结果  |
+| `cleanupLeaseUntil` | Worker 崩溃后，允许其他实例在到期后接手            |
+| `nextCleanupAt`     | 下一次允许扫描投递的时间，避免失败记录一直挤在队首 |
+| `lastCleanupError`  | 固定的失败分类，不保存原始 SQL、SDK 错误或密钥     |
+
+历史 `expired/aborted` 记录也会被重新确认一次，因为新增的 `cleanedAt` 为空。已经不存在的 Multipart 可以按幂等成功处理。
+
+### 3.2 活动分片租约表
+
+在同一个 Schema 文件末尾追加：
+
+```ts
+export const uploadPartLeases = pgTable(
+  'upload_part_leases',
+  {
+    id: uuid('id').primaryKey(),
+    uploadSessionId: uuid('upload_session_id')
+      .notNull()
+      .references(() => uploadSessions.id, { onDelete: 'cascade' }),
+    partNumber: integer('part_number').notNull(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+  },
+  (table) => [
+    uniqueIndex('upload_part_leases_session_part_uq').on(table.uploadSessionId, table.partNumber),
+    index('upload_part_leases_session_expires_idx').on(table.uploadSessionId, table.expiresAt),
+  ],
+)
+```
+
+一片正在上传，就有一条租约。唯一索引保证同一会话同一分片不会被两次请求同时占用。不同分片仍能并行。现有 Service 已检查 `partNumber` 范围，登记租约放在参数校验之后。
+
+### 3.3 生成并执行迁移
+
+```powershell
+vp run --filter server db:generate
+```
+
+打开新生成的 `apps/server/drizzle/*.sql`，确认包含新增字段、表和索引，没有意外删除旧字段。然后在本地开发数据库执行：
+
+```powershell
+vp run --filter server db:migrate
+vp run --filter server db:studio
+```
+
+Studio 应能看到新结构。`db:generate` 只生成 SQL，`db:migrate` 才修改数据库；只改 TypeScript 不会自动建表。
+
+## 第 4 步：共用一把短事务锁
+
+后台刚查到“没有分片”，另一个请求就登记了分片，这两个操作可能交错。因此“登记分片”和“封口清理”必须对同一个会话串行判断。
+
+新建 `apps/server/src/modules/upload/upload-session-lock.ts`：
+
+```ts
+import type { DrizzleDB } from '@/database/db.module'
+import { uploadPartLeases } from '@/database/schema'
+import { and, eq, gt, sql } from 'drizzle-orm'
+
+export type UploadTransaction = Parameters<Parameters<DrizzleDB['transaction']>[0]>[0]
+
+export async function withUploadSessionLock<T>(
+  db: DrizzleDB,
+  uploadSessionId: string,
+  operation: (tx: UploadTransaction) => Promise<T>,
+): Promise<T> {
+  return db.transaction(async (tx) => {
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${uploadSessionId}, 0))`)
+    return operation(tx)
+  })
+}
+
+export async function hasActiveParts(tx: UploadTransaction, uploadSessionId: string) {
+  const rows = await tx
+    .select({ id: uploadPartLeases.id })
+    .from(uploadPartLeases)
+    .where(
+      and(
+        eq(uploadPartLeases.uploadSessionId, uploadSessionId),
+        gt(uploadPartLeases.expiresAt, sql`clock_timestamp()`),
+      ),
+    )
+    .limit(1)
+  return rows.length > 0
+}
+```
+
+这是 PostgreSQL 的事务级 advisory lock：相同会话 ID 对应同一把锁，事务结束自动释放；不同会话通常互不影响。哈希碰撞最多增加排队，不会使应该互斥的操作绕过锁。
+
+`sql` 模板的变量会作为数据库参数传入，不要自己拼接 SQL。**锁内只做数据库操作，事务提交后才调用 MinIO。** 不能拿着数据库连接等待整个文件上传。
+
+## 第 5 步：让正在上传的分片拥有租约
+
+### 5.1 新建租约 Service
+
+新建 `apps/server/src/modules/upload/upload-part-lease.service.ts`：
+
+```ts
+import { randomUUID } from 'node:crypto'
+import { Inject, Injectable } from '@nestjs/common'
+import { and, eq, gt, lte, sql } from 'drizzle-orm'
+import { DRIZZLE, type DrizzleDB } from '@/database/db.module'
+import { uploadPartLeases, uploadSessions } from '@/database/schema'
+import { AppException } from '@/common/exceptions/app.exception'
+import { UPLOAD_ERRORS } from './upload.errors'
+import { withUploadSessionLock } from './upload-session-lock'
+
+@Injectable()
+export class UploadPartLeaseService {
+  constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
+
+  private async begin(ownerId: string, uploadSessionId: string, partNumber: number) {
+    return withUploadSessionLock(this.db, uploadSessionId, async (tx) => {
+      const [session] = await tx
+        .select()
+        .from(uploadSessions)
+        .where(
+          and(
+            eq(uploadSessions.id, uploadSessionId),
+            eq(uploadSessions.ownerId, ownerId),
+            eq(uploadSessions.status, 'uploading'),
+            gt(uploadSessions.expiresAt, sql`clock_timestamp()`),
+          ),
+        )
+        .limit(1)
+      if (!session) throw new AppException(UPLOAD_ERRORS.INVALID_STATE)
+
+      await tx
+        .delete(uploadPartLeases)
+        .where(
+          and(
+            eq(uploadPartLeases.uploadSessionId, uploadSessionId),
+            lte(uploadPartLeases.expiresAt, sql`clock_timestamp()`),
+          ),
+        )
+      const leaseId = randomUUID()
+      const inserted = await tx
+        .insert(uploadPartLeases)
+        .values({
+          id: leaseId,
+          uploadSessionId,
+          partNumber,
+          expiresAt: sql`clock_timestamp() + interval '2 minutes'`,
+        })
+        .onConflictDoNothing()
+        .returning({ id: uploadPartLeases.id })
+      if (inserted.length === 0) throw new AppException(UPLOAD_ERRORS.PARTS_STILL_ACTIVE)
+      return leaseId
+    })
+  }
+
+  private async renew(leaseId: string, uploadSessionId: string) {
+    const rows = await this.db
+      .update(uploadPartLeases)
+      .set({
+        expiresAt: sql`clock_timestamp() + interval '2 minutes'`,
+      })
+      .where(
+        and(
+          eq(uploadPartLeases.id, leaseId),
+          eq(uploadPartLeases.uploadSessionId, uploadSessionId),
+          gt(uploadPartLeases.expiresAt, sql`clock_timestamp()`),
+        ),
+      )
+      .returning({ id: uploadPartLeases.id })
+    if (rows.length === 0) throw new Error('Upload part lease lost')
+  }
+
+  async run<T>(
+    input: {
+      ownerId: string
+      uploadSessionId: string
+      partNumber: number
+      abortSignal?: AbortSignal
+    },
+    operation: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
+    const leaseStartedAt = performance.now()
+    const leaseId = await this.begin(input.ownerId, input.uploadSessionId, input.partNumber)
+    const controller = new AbortController()
+    const abort = () => controller.abort()
+    input.abortSignal?.addEventListener('abort', abort, { once: true })
+    if (input.abortSignal?.aborted) controller.abort()
+
+    let stopped = false
+    let succeeded = false
+    let renewalFailed = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let pending: Promise<void> = Promise.resolve()
+    // 数据库续租请求如果一直没返回，也不能让分片超过租约继续写入。
+    // 90 秒小于数据库的 2 分钟 TTL，留出网络中止的时间。
+    let watchdog = setTimeout(
+      () => {
+        renewalFailed = true
+        controller.abort()
+      },
+      Math.max(1, 90_000 - (performance.now() - leaseStartedAt)),
+    )
+    const scheduleRenewal = () => {
+      timer = setTimeout(() => {
+        pending = (async () => {
+          try {
+            const renewalStartedAt = performance.now()
+            await this.renew(leaseId, input.uploadSessionId)
+            if (!stopped && !renewalFailed) {
+              clearTimeout(watchdog)
+              watchdog = setTimeout(
+                () => {
+                  renewalFailed = true
+                  controller.abort()
+                },
+                Math.max(1, 90_000 - (performance.now() - renewalStartedAt)),
+              )
+            }
+          } catch {
+            renewalFailed = true
+            controller.abort()
+          }
+          if (!stopped && !renewalFailed) scheduleRenewal()
+        })()
+      }, 30_000)
+    }
+
+    scheduleRenewal()
+    try {
+      const result = await operation(controller.signal)
+      if (renewalFailed) throw new Error('Upload part lease lost')
+      succeeded = true
+      return result
+    } finally {
+      stopped = true
+      if (timer) clearTimeout(timer)
+      clearTimeout(watchdog)
+      await pending
+      input.abortSignal?.removeEventListener('abort', abort)
+      // 失败时保留租约到期，给已发出的存储请求留出收敛时间。
+      if (succeeded && !renewalFailed) {
+        await this.db
+          .delete(uploadPartLeases)
+          .where(
+            and(
+              eq(uploadPartLeases.id, leaseId),
+              eq(uploadPartLeases.uploadSessionId, input.uploadSessionId),
+            ),
+          )
+      }
+    }
+  }
+}
+```
+
+每 30 秒续租到未来 2 分钟。续租失败就中止 MinIO 请求；进程崩溃后租约自行到期。不要只用一个永久的 `isUploading=true`，崩溃后它可能永远不恢复。
+
+租约协调正常并发，但数据库不能撤回已经到达 MinIO 的网络请求。因此后面还会在 Abort 后检查 `ListParts`，保留重试和存储生命周期兜底。
+
+### 5.2 接入原来的上传 Service
+
+在 `apps/server/src/modules/upload/upload.service.ts` 导入 `UploadPartLeaseService`，构造函数追加：
+
+```ts
+private readonly partLeases: UploadPartLeaseService,
+```
+
+在 `uploadPart()` 中找到原 `const result = await this.callStorage(...)`，保留前面的校验、`ExactSizeTransform` 和外层流清理，只替换调用存储的那一段：
+
+```ts
+const result = await this.partLeases.run(input, (signal) =>
+  this.callStorage(() =>
+    this.storage.uploadPart({
+      ...this.toMultipartIdentity(session),
+      partNumber: input.partNumber,
+      body: guardedBody,
+      contentLength: expectedSize,
+      abortSignal: signal,
+    }),
+  ),
+)
+```
+
+必须传这里的 `signal`，它同时处理客户端断开和租约丢失。
+
+### 5.3 Complete 和取消也遵守同一把锁
+
+修改 `apps/server/src/modules/upload/upload.reponsitory.ts`。在现有 `drizzle-orm` 导入中补入 `gt, isNull, lte, or, sql`，再增加：
+
+```ts
+import { AppException } from '@/common/exceptions/app.exception'
+import { UPLOAD_ERRORS } from './upload.errors'
+import { hasActiveParts, withUploadSessionLock } from './upload-session-lock'
+```
+
+在类内新增私有方法，替换原 `claimCompleting()`、`claimAborting()`：
+
+```ts
+private async claimIdleState(
+  ownerId: string,
+  uploadSessionId: string,
+  target: 'completing' | 'aborting',
+): Promise<UploadSession | null> {
+  return withUploadSessionLock(this.db, uploadSessionId, async (tx) => {
+    if (await hasActiveParts(tx, uploadSessionId)) {
+      throw new AppException(UPLOAD_ERRORS.PARTS_STILL_ACTIVE)
+    }
+    const [session] = await tx.update(uploadSessions).set({
+      status: target,
+      updatedAt: new Date(),
+    }).where(and(
+      eq(uploadSessions.id, uploadSessionId),
+      eq(uploadSessions.ownerId, ownerId),
+      target === 'completing'
+        ? and(eq(uploadSessions.status, 'uploading'), gt(uploadSessions.expiresAt, sql`clock_timestamp()`))
+        : inArray(uploadSessions.status, ['uploading', 'aborting', 'expired']),
+      or(isNull(uploadSessions.cleanupLeaseUntil), lte(uploadSessions.cleanupLeaseUntil, sql`clock_timestamp()`)),
+    )).returning()
+    return session ?? null
+  })
+}
+
+async claimCompleting(ownerId: string, uploadSessionId: string) {
+  return this.claimIdleState(ownerId, uploadSessionId, 'completing')
+}
+
+async claimAborting(ownerId: string, uploadSessionId: string) {
+  return this.claimIdleState(ownerId, uploadSessionId, 'aborting')
+}
+```
+
+`PARTS_STILL_ACTIVE` 已在当前错误目录定义。前端收到后先停止并等待分片结束，再重试完成或取消。失败分片保留的短租约会让操作多等一段时间，这是保护窗口。
+
+### 5.4 移除 HTTP 请求中的过期清理
+
+把 `upload.service.ts` 的 `ensureNotExpired()` 替换为：
+
+```ts
+private async ensureNotExpired(session: UploadSession): Promise<void> {
+  if (session.expiresAt.getTime() > Date.now()) return
+  await this.uploadRepository.markExpired(session.ownerId, session.id)
+  throw new AppException(UPLOAD_ERRORS.UPLOAD_EXPIRED)
+}
+```
+
+这里仅关闭会话，释放分片交给定时任务。现有 `markExpired()` 是带 `status = uploading` 条件的 UPDATE，它不调用 MinIO，活动分片可在自身租约保护下结束。
+
+保留 `safeAbort()` 在初始化失败时的补偿用途，不能删除整个方法。用户主动取消仍然及时 Abort，后台再确认结果。不要只给后台加锁，却保留旧的 `claimCompleting()`。
+
+## 第 6 步：实现清理 Repository
+
+新建 `apps/server/src/modules/upload/upload-cleanup.repository.ts`：
+
+```ts
+import { randomUUID } from 'node:crypto'
+import { Inject, Injectable } from '@nestjs/common'
+import { and, asc, eq, gt, inArray, isNull, lte, or, sql } from 'drizzle-orm'
+import { DRIZZLE, type DrizzleDB } from '@/database/db.module'
+import { uploadPartLeases, uploadSessions } from '@/database/schema'
+import { hasActiveParts, withUploadSessionLock } from './upload-session-lock'
+
+@Injectable()
+export class UploadCleanupRepository {
+  constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
+
+  private eligible() {
+    return and(
+      isNull(uploadSessions.cleanedAt),
+      or(
+        and(
+          eq(uploadSessions.status, 'uploading'),
+          lte(uploadSessions.expiresAt, sql`clock_timestamp()`),
+        ),
+        inArray(uploadSessions.status, ['expired', 'aborting', 'aborted']),
+      ),
+      or(
+        isNull(uploadSessions.cleanupLeaseUntil),
+        lte(uploadSessions.cleanupLeaseUntil, sql`clock_timestamp()`),
+      ),
+    )
+  }
+
+  async findCandidates(limit: number) {
+    return this.db
+      .select({ id: uploadSessions.id, status: uploadSessions.status })
+      .from(uploadSessions)
+      .where(and(this.eligible(), lte(uploadSessions.nextCleanupAt, sql`clock_timestamp()`)))
+      .orderBy(asc(uploadSessions.nextCleanupAt), asc(uploadSessions.id))
+      .limit(limit)
+  }
+
+  async reserveForEnqueue(uploadSessionId: string) {
+    const rows = await this.db
+      .update(uploadSessions)
+      .set({
+        nextCleanupAt: sql`clock_timestamp() + interval '5 minutes'`,
+      })
+      .where(
+        and(
+          eq(uploadSessions.id, uploadSessionId),
+          this.eligible(),
+          lte(uploadSessions.nextCleanupAt, sql`clock_timestamp()`),
+        ),
+      )
+      .returning({ id: uploadSessions.id })
+    return rows.length > 0
+  }
+
+  async claim(uploadSessionId: string) {
+    return withUploadSessionLock(this.db, uploadSessionId, async (tx) => {
+      if (await hasActiveParts(tx, uploadSessionId)) return null
+
+      const cleanupClaimId = randomUUID()
+      const [session] = await tx
+        .update(uploadSessions)
+        .set({
+          // 在短事务内封口，后来的分片与 Complete 都不能再进入。
+          status: sql`case when ${uploadSessions.status} = 'uploading'
+          then 'expired'::upload_status else ${uploadSessions.status} end`,
+          cleanupClaimId,
+          cleanupLeaseUntil: sql`clock_timestamp() + interval '2 minutes'`,
+          updatedAt: new Date(),
+        })
+        .where(and(eq(uploadSessions.id, uploadSessionId), this.eligible()))
+        .returning()
+
+      if (!session) return null
+
+      await tx
+        .delete(uploadPartLeases)
+        .where(
+          and(
+            eq(uploadPartLeases.uploadSessionId, uploadSessionId),
+            lte(uploadPartLeases.expiresAt, sql`clock_timestamp()`),
+          ),
+        )
+      return { session, cleanupClaimId }
+    })
+  }
+
+  private ownsClaim(uploadSessionId: string, cleanupClaimId: string) {
+    return and(
+      eq(uploadSessions.id, uploadSessionId),
+      eq(uploadSessions.cleanupClaimId, cleanupClaimId),
+      gt(uploadSessions.cleanupLeaseUntil, sql`clock_timestamp()`),
+      inArray(uploadSessions.status, ['expired', 'aborting', 'aborted']),
+    )
+  }
+
+  async finish(uploadSessionId: string, cleanupClaimId: string) {
+    const rows = await this.db
+      .update(uploadSessions)
+      .set({
+        status: sql`case when ${uploadSessions.status} = 'expired'
+        then 'expired'::upload_status else 'aborted'::upload_status end`,
+        cleanedAt: sql`clock_timestamp()`,
+        cleanupClaimId: null,
+        cleanupLeaseUntil: null,
+        lastCleanupError: null,
+        updatedAt: new Date(),
+      })
+      .where(this.ownsClaim(uploadSessionId, cleanupClaimId))
+      .returning({ id: uploadSessions.id })
+    return rows.length > 0
+  }
+
+  async recordFailure(uploadSessionId: string, cleanupClaimId: string) {
+    await this.db
+      .update(uploadSessions)
+      .set({
+        cleanupClaimId: null,
+        cleanupLeaseUntil: null,
+        nextCleanupAt: sql`clock_timestamp() + interval '1 minute'`,
+        lastCleanupError: 'STORAGE_OR_DATABASE_FAILURE',
+        updatedAt: new Date(),
+      })
+      .where(this.ownsClaim(uploadSessionId, cleanupClaimId))
+  }
+}
+```
+
+### 按方法理解这段代码
+
+`findCandidates()` 只是找候选，排序后最多取一批，不把全表一次读进内存。扫描结果可能马上过时，所以 Worker 必须再次检查。
+
+`reserveForEnqueue()` 把下次扫描时间推后 5 分钟。两个扫描任务同时看见一条记录，只有一个能成功更新并投递。最早失败的记录也会暂时让开，让后面的记录有机会被处理。
+
+数据库更新和 Redis 投递不是一个事务。如果预约成功后进程崩溃，记录不会永久丢失，5 分钟后又会被扫描。这里接受有限延迟，通过后续扫描补偿。5 分钟是防重复投递的窗口，不是任务有效期。
+
+`claim()` 才是领取真正的执行权。它忽略扫描预约时间，但再次检查状态、过期时间、活动分片和其他 Worker 的租约；因此“预约了任务”不等于“允许删分片”。返回 `null` 表示当前不需要或暂时不能处理。
+
+`finish()` 同时匹配会话 ID、Claim UUID、租约仍有效。即使旧 Worker 在网络恢复后继续运行，也不能把新 Worker 的结果覆盖掉。清理超过 2 分钟导致租约失效时，旧任务不写成功；后续扫描会重新确认结果。针对更慢的存储应加入清理租约续租及请求超时，不能只无限加长租约。
+
+## 第 7 步：定义两种任务协议
+
+修改基础篇创建的 `apps/server/src/modules/task-queue/task-queue.constants.ts`，保留队列名、并发常量，替换任务名对象：
+
+```ts
+export const TASK_JOB_NAMES = {
+  QUEUE_SMOKE: 'system.queue-smoke.v1',
+  UPLOAD_CLEANUP_SCAN: 'upload.cleanup-scan.v1',
+  UPLOAD_MULTIPART_EXPIRE: 'upload.multipart-expire.v1',
+} as const
+```
+
+在 `task-queue.contracts.ts` 保留原来的 `QueueSmokePayloadSchema`、解析函数、投递选项和返回类型，新增两个 Schema，并替换两张映射表：
+
+```ts
+export const UploadCleanupScanPayloadSchema = z.object({}).strict()
+export const UploadMultipartExpirePayloadSchema = z
+  .object({
+    uploadSessionId: z.string().uuid(),
+  })
+  .strict()
+
+export interface TaskPayloadMap {
+  [TASK_JOB_NAMES.QUEUE_SMOKE]: z.infer<typeof QueueSmokePayloadSchema>
+  [TASK_JOB_NAMES.UPLOAD_CLEANUP_SCAN]: z.infer<typeof UploadCleanupScanPayloadSchema>
+  [TASK_JOB_NAMES.UPLOAD_MULTIPART_EXPIRE]: z.infer<typeof UploadMultipartExpirePayloadSchema>
+}
+
+export const TASK_PAYLOAD_SCHEMAS = {
+  [TASK_JOB_NAMES.QUEUE_SMOKE]: QueueSmokePayloadSchema,
+  [TASK_JOB_NAMES.UPLOAD_CLEANUP_SCAN]: UploadCleanupScanPayloadSchema,
+  [TASK_JOB_NAMES.UPLOAD_MULTIPART_EXPIRE]: UploadMultipartExpirePayloadSchema,
+} satisfies Record<TaskName, z.ZodType>
+```
+
+扫描任务不需要参数，使用 `{}`；单条清理只传会话 UUID。Bucket、Object Key、MinIO UploadId 从数据库读取，不从队列参数接收。
+
+TypeScript 在开发时检查，Zod 在运行时检查 Redis 中实际拿到的数据。两者用途不同，都要保留。
+
+## 第 8 步：实现扫描器和清理 Handler
+
+### 8.1 扫描器：找候选并投递
+
+新建 `apps/server/src/modules/upload/upload-cleanup.scanner.ts`：
+
+```ts
+import { Injectable, Logger } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import { TASK_JOB_NAMES } from '../task-queue/task-queue.constants'
+import { TaskQueueService } from '../task-queue/task-queue.service'
+import { UploadCleanupRepository } from './upload-cleanup.repository'
+
+@Injectable()
+export class UploadCleanupScanner {
+  private readonly logger = new Logger(UploadCleanupScanner.name)
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly repository: UploadCleanupRepository,
+    private readonly taskQueue: TaskQueueService,
+  ) {}
+
+  async scan() {
+    if (!this.config.getOrThrow<boolean>('uploadCleanup.enabled')) {
+      return { skipped: 'disabled' }
+    }
+    const dryRun = this.config.getOrThrow<boolean>('uploadCleanup.dryRun')
+    const limit = this.config.getOrThrow<number>('uploadCleanup.batchSize')
+    const candidates = await this.repository.findCandidates(limit)
+    let enqueued = 0
+
+    for (const candidate of candidates) {
+      if (dryRun) {
+        this.logger.log({ event: 'upload_cleanup_candidate', ...candidate })
+        continue
+      }
+      if (!(await this.repository.reserveForEnqueue(candidate.id))) continue
+
+      await this.taskQueue.enqueue(TASK_JOB_NAMES.UPLOAD_MULTIPART_EXPIRE, {
+        uploadSessionId: candidate.id,
+      })
+      enqueued += 1
+    }
+
+    const result = { dryRun, candidates: candidates.length, enqueued }
+    this.logger.log({ event: 'upload_cleanup_scan', ...result })
+    return result
+  }
+}
+```
+
+预览不会预约、不会投递、不会 Abort。因此预览模式反复看到相同一批候选是正常的，它只展示当前最早的一批。
+
+投递失败让异常继续抛出，扫描 Job 会重试，数据库预约窗口也会最终到期。这里不手写永久固定的 `jobId`，避免旧失败 Job 仍保留时阻止后续补偿。
+
+### 8.2 Handler：执行真正的清理
+
+新建 `apps/server/src/modules/upload/upload-cleanup.handler.ts`：
+
+```ts
+import { Inject, Injectable, Logger } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import {
+  STORAGE_PORT,
+  StorageMultipartNotFoundError,
+  type StoragePort,
+} from './storage/storage.port'
+import { UploadCleanupRepository } from './upload-cleanup.repository'
+
+@Injectable()
+export class UploadCleanupHandler {
+  private readonly logger = new Logger(UploadCleanupHandler.name)
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly repository: UploadCleanupRepository,
+    @Inject(STORAGE_PORT) private readonly storage: StoragePort,
+  ) {}
+
+  async handle(input: { uploadSessionId: string }) {
+    if (
+      !this.config.getOrThrow<boolean>('uploadCleanup.enabled') ||
+      this.config.getOrThrow<boolean>('uploadCleanup.dryRun')
+    )
+      return { skipped: 'disabled-or-dry-run' }
+
+    const claim = await this.repository.claim(input.uploadSessionId)
+    if (!claim) return { skipped: 'not-eligible-or-busy' }
+
+    const { session, cleanupClaimId } = claim
+    const identity = {
+      bucket: session.bucket,
+      objectKey: session.objectKey,
+      storageUploadId: session.storageUploadId,
+    }
+
+    try {
+      // 异常状态下如果已有正式对象，保留现场，交给对账。
+      const object = await this.storage.headObject(identity)
+      if (object) throw new Error('Final object exists; reconciliation required')
+
+      await this.storage.abortMultipartUpload(identity)
+
+      // 一次 Abort 返回成功不等于可以忽略存储端的并发和不确定性。
+      let missing = false
+      try {
+        await this.storage.listParts(identity)
+      } catch (error) {
+        if (!(error instanceof StorageMultipartNotFoundError)) throw error
+        missing = true
+      }
+      if (!missing) throw new Error('Multipart still exists after abort')
+
+      const persisted = await this.repository.finish(session.id, cleanupClaimId)
+      if (!persisted) return { skipped: 'cleanup-lease-lost' }
+
+      this.logger.log({ event: 'upload_cleanup_completed', uploadSessionId: session.id })
+      return { cleaned: true, uploadSessionId: session.id }
+    } catch (error) {
+      await this.repository.recordFailure(session.id, cleanupClaimId)
+      throw error
+    }
+  }
+}
+```
+
+这些存储方法已经在当前 `StoragePort` 和 `MinioStorageAdapter` 中存在。当前适配器把 Abort 的 `NoSuchUpload` 当作成功，把 ListParts 的 `NoSuchUpload` 转成 `StorageMultipartNotFoundError`，所以不需要另写一套 S3 客户端。
+
+普通权限错误、Bucket 错误和网络超时都不能伪装成“对象不存在”。现有适配器的错误映射要保留。
+
+为什么先调用 MinIO、后写 `cleanedAt`：先写数据库再 Abort，一旦 Abort 失败，就会把“未清完”误记成“成功”。反过来，即使 Abort 成功后数据库失败，下次重试再次 Abort，再得到 NoSuchUpload，就能补上结果。
+
+为什么 `catch` 后还要 `throw`：BullMQ 用 Promise 是否 reject 判断失败。返回 `{ ok: false }` 会被它当成 completed，重试就失效了。这里的 catch 用于记录补偿状态；HTTP 全局异常过滤器不会处理 Worker 异常，Worker 的事件日志沿用公共 Processor。
+
+租约记录失败时数据库也可能不可用，此时仍然让 Job 失败。Claim 到期后下一轮会重新领取。所有权丢失的旧 Worker 不写回结果。
+
+## 第 9 步：真正注册“每分钟执行一次”
+
+### 9.1 扩展公共队列 Service
+
+修改 `apps/server/src/modules/task-queue/task-queue.service.ts`，在现有 `TaskQueueService` 类中新增以下方法。所用 `TaskName`、`TaskPayloadMap`、`parseTaskPayload` 已由基础篇导入：
+
+```ts
+async upsertSchedule<Name extends TaskName>(
+  schedulerId: string,
+  everyMs: number,
+  name: Name,
+  payload: TaskPayloadMap[Name],
+) {
+  if (!Number.isSafeInteger(everyMs) || everyMs < 5_000) {
+    throw new Error('Schedule interval must be at least 5000 milliseconds')
+  }
+  await this.queue.upsertJobScheduler(
+    schedulerId,
+    { every: everyMs },
+    { name, data: parseTaskPayload(name, payload) },
+  )
+}
+
+async removeSchedule(schedulerId: string) {
+  return this.queue.removeJobScheduler(schedulerId)
+}
+```
+
+`upsert` 就是“存在则更新，不存在则创建”。它保存的是调度规则，不是立即循环执行的方法调用。调度规则 ID 必须稳定，服务重启时再次调用仍更新同一条规则。
+
+当前安装的 BullMQ 提供 `upsertJobScheduler()`；不要复制旧文章使用 `QueueScheduler`，也不要再加一个 Nest `@Cron` 重复扫描。
+
+### 9.2 新建启动注册器
+
+新建 `apps/server/src/modules/upload/upload-cleanup.scheduler.ts`：
+
+```ts
+import { Injectable, Logger, type OnApplicationBootstrap } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import { TASK_JOB_NAMES } from '../task-queue/task-queue.constants'
+import { TaskQueueService } from '../task-queue/task-queue.service'
+
+const SCHEDULER_ID = 'upload-cleanup-scan-v1'
+
+@Injectable()
+export class UploadCleanupScheduler implements OnApplicationBootstrap {
+  private readonly logger = new Logger(UploadCleanupScheduler.name)
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly taskQueue: TaskQueueService,
+  ) {}
+
+  async onApplicationBootstrap() {
+    // 只让承担 Worker 的进程管理调度规则；纯 API 副本跳过。
+    if (!this.config.getOrThrow<boolean>('queue.workerEnabled')) return
+
+    if (!this.config.getOrThrow<boolean>('uploadCleanup.enabled')) {
+      await this.taskQueue.removeSchedule(SCHEDULER_ID)
+      this.logger.log({ event: 'upload_cleanup_schedule_removed' })
+      return
+    }
+
+    const intervalMs = this.config.getOrThrow<number>('uploadCleanup.intervalMs')
+    await this.taskQueue.upsertSchedule(
+      SCHEDULER_ID,
+      intervalMs,
+      TASK_JOB_NAMES.UPLOAD_CLEANUP_SCAN,
+      {},
+    )
+    this.logger.log({ event: 'upload_cleanup_schedule_ready', intervalMs })
+  }
+}
+```
+
+`OnApplicationBootstrap` 是 Nest 的启动生命周期，类似组件初始化，但它属于整个后端应用。这里只在启动时注册一次，后续重复由 BullMQ 驱动，不需要写 `setInterval()`。
+
+### 9.3 调度行为要理解清楚
+
+| 问题                         | 实际行为                                                                            |
+| ---------------------------- | ----------------------------------------------------------------------------------- |
+| 服务重启会多注册一条吗       | 相同 Redis、DB、Prefix、队列和稳定 Scheduler ID 下，更新同一条规则                  |
+| 部署两个 Worker 会重复规则吗 | 同配置、同 ID 的 upsert 不创建两条规则；Job 仍可能重复执行，靠数据库幂等保护        |
+| 第一轮一定等一分钟吗         | 当前 BullMQ 的 `every` 调度新建时可能立即产生首轮任务，不依赖“先等完整一分钟”的假设 |
+| 服务停了还能自动清理吗       | 规则在 Redis 中保留，但必须有运行中的 Worker 才能执行                               |
+| 停机一小时会补跑 60 次吗     | 不按停机期间每个时间点补齐历史扫描；恢复后的扫描会处理仍到期的数据库记录            |
+| 扫描积压怎么办               | Scheduler 的后续产生与消费有关，繁忙时频率会低于配置值；需要监控队列延迟            |
+| 停用时只不调用 upsert 可以吗 | 不可以，旧规则仍在 Redis；要调用 `removeJobScheduler`                               |
+
+同一环境的所有 Worker 必须使用一致的 enabled、dryRun、扫描间隔、Prefix。不要一个副本删除规则、另一个副本重新注册。
+
+修改 `.env` 后重启 Server 才会应用新配置。关闭 `UPLOAD_CLEANUP_ENABLED` 并重启负责调度的 Worker，会删除未来规则；Scanner 和 Handler 的开关检查会让已有排队任务跳过。已经开始的 MinIO 请求不会被配置变更瞬间撤销，应等待正常停机完成。
+
+不要在 `onModuleDestroy()` 中删除调度规则。一个副本重启，不应该撤掉其他副本还在使用的周期任务。
+
+### 9.4 如果想每天凌晨清理
+
+本教程主线是固定间隔。如果确定要每天北京时间 03:00 扫描，把 `upsertJobScheduler` 的第二个参数替换成：
+
+```ts
+{ pattern: '0 0 3 * * *', tz: 'Asia/Shanghai' }
+```
+
+这里六位依次是“秒、分、时、日、月、周”。`every` 和 `pattern` 二选一，不能同时传；改成 pattern 后应同步去掉该方法中无效的 `everyMs` 参数及校验，并调整调用者，避免留下看似生效的间隔配置。
+
+每天仅扫 100 条，积压时最多也只处理这个量，因此大量上传通常更适合每分钟小批扫描。
+
+## 第 10 步：组装模块，避免循环依赖
+
+上传 Scanner 需要队列 Service，队列 Processor 又需要上传 Handler。如果互相导入整个模块，会变成循环依赖。这里把“队列基础设施”和“消费组装”拆开。
+
+```text
+TaskQueueModule
+  └── BullMQ 配置 + Queue + TaskQueueService
+
+UploadModule ──导入──> TaskQueueModule
+  └── 上传 API + Scanner + Handler + Scheduler
+
+TaskQueueWorkerModule
+  ├── 导入 TaskQueueModule
+  ├── 导入 UploadModule
+  └── QueueWorkerBootstrap + 唯一 TaskQueueProcessor
+```
+
+### 10.1 修改基础队列模块
+
+修改 `apps/server/src/modules/task-queue/task-queue.module.ts`：保留基础篇全部 `BullModule.forRootAsync(...)`、`registerQueue(...)` 配置，包括 `manualRegistration: true`。移除 `QueueWorkerBootstrap`、`TaskQueueProcessor` 的导入和 provider 注册。
+
+装饰器中的这两个属性改为：
+
+```ts
+providers: [TaskQueueService],
+exports: [TaskQueueService, BullModule],
+```
+
+导出 `BullModule`，让消费组装模块可以取得队列及注册能力。不要再创建第二套 `forRootAsync`。
+
+### 10.2 替换 UploadModule
+
+将 `apps/server/src/modules/upload/upload.module.ts` 改为：
+
+```ts
+import { Module } from '@nestjs/common'
+import { TaskQueueModule } from '../task-queue/task-queue.module'
+import { MinioStorageAdapter } from './storage/minio-storage.adapter'
+import { STORAGE_PORT } from './storage/storage.port'
+import { UploadController } from './upload.controller'
+import { UploadRepository } from './upload.reponsitory'
+import { UploadService } from './upload.service'
+import { UploadPartLeaseService } from './upload-part-lease.service'
+import { UploadCleanupRepository } from './upload-cleanup.repository'
+import { UploadCleanupScanner } from './upload-cleanup.scanner'
+import { UploadCleanupHandler } from './upload-cleanup.handler'
+import { UploadCleanupScheduler } from './upload-cleanup.scheduler'
+
+@Module({
+  imports: [TaskQueueModule],
+  controllers: [UploadController],
+  providers: [
+    UploadRepository,
+    UploadService,
+    UploadPartLeaseService,
+    MinioStorageAdapter,
+    { provide: STORAGE_PORT, useExisting: MinioStorageAdapter },
+    UploadCleanupRepository,
+    UploadCleanupScanner,
+    UploadCleanupHandler,
+    UploadCleanupScheduler,
+  ],
+  exports: [UploadCleanupScanner, UploadCleanupHandler],
+})
+export class UploadModule {}
+```
+
+`providers` 表示“由当前模块创建这些实例”；`exports` 表示“允许导入此模块的其他模块使用”。数据库和 Config 已由当前项目的全局模块提供。
+
+### 10.3 新建消费组装模块
+
+新建 `apps/server/src/modules/task-queue/task-queue-worker.module.ts`：
+
+```ts
+import { Module } from '@nestjs/common'
+import { UploadModule } from '../upload/upload.module'
+import { QueueWorkerBootstrap } from './queue-worker.bootstrap'
+import { TaskQueueModule } from './task-queue.module'
+import { TaskQueueProcessor } from './task-queue.processor'
+
+@Module({
+  imports: [TaskQueueModule, UploadModule],
+  providers: [QueueWorkerBootstrap, TaskQueueProcessor],
+})
+export class TaskQueueWorkerModule {}
+```
+
+基础篇的 `QueueWorkerBootstrap` 内容保留，它仍通过 `QUEUE_WORKER_ENABLED` 和 `BullRegistrar.register()` 控制消费者启动。
+
+### 10.4 Processor 增加分发
+
+修改 `apps/server/src/modules/task-queue/task-queue.processor.ts`，新增导入：
+
+```ts
+import { UploadCleanupScanner } from '../upload/upload-cleanup.scanner'
+import { UploadCleanupHandler } from '../upload/upload-cleanup.handler'
+import {
+  UploadCleanupScanPayloadSchema,
+  UploadMultipartExpirePayloadSchema,
+} from './task-queue.contracts'
+```
+
+与原 contracts 导入合并。类中增加构造函数，`WorkerHost` 子类必须调用 `super()`：
+
+```ts
+constructor(
+  private readonly uploadCleanupScanner: UploadCleanupScanner,
+  private readonly uploadCleanupHandler: UploadCleanupHandler,
+) {
+  super()
+}
+```
+
+在 `process()` 的 `switch` 内、原 `default` 之前增加分支。保留冒烟分支和全部 Worker 事件日志：
+
+```ts
+case TASK_JOB_NAMES.UPLOAD_CLEANUP_SCAN: {
+  const parsed = UploadCleanupScanPayloadSchema.safeParse(job.data)
+  if (!parsed.success) throw new UnrecoverableError('Invalid cleanup scan payload')
+  return this.uploadCleanupScanner.scan()
+}
+
+case TASK_JOB_NAMES.UPLOAD_MULTIPART_EXPIRE: {
+  const parsed = UploadMultipartExpirePayloadSchema.safeParse(job.data)
+  if (!parsed.success) throw new UnrecoverableError('Invalid upload cleanup payload')
+  return this.uploadCleanupHandler.handle(parsed.data)
+}
+```
+
+非法参数使用 `UnrecoverableError`，重试不会把错误 UUID 修好。普通数据库、存储故障让异常继续抛出，沿用公共队列的 3 次尝试和指数退避。
+
+**同一个 `server-tasks` 不再新增 `@Processor`。** 多个只认识部分任务的 Processor 会竞争整个队列，无法按任务名自动各取所需。
+
+### 10.5 AppModule 接入
+
+在 `apps/server/src/app.module.ts` 增加导入并把它加入 `imports`：
+
+```ts
+import { TaskQueueWorkerModule } from './modules/task-queue/task-queue-worker.module'
+```
+
+保留 `DatabaseModule`、`ConfigModule`、`AuthModule`、`UploadModule` 等原有模块。原 AppModule 对 `TaskQueueModule` 的直接导入可以移除，由 WorkerModule 和 UploadModule 明确导入即可。
+
+确认第 2 步已经把 `uploadCleanupConfig` 加入 `load`；确认基础篇已经在 `main.ts` 调用 `app.enableShutdownHooks()`。
+
+至此文件才全部组装完成，执行：
+
+```powershell
+vp run --filter server build
+```
+
+如果出现 `Nest can't resolve dependencies`，先核对 providers、imports、exports；不要把缺少的 Service 随手在多个模块重复注册。
+
+### 10.6 同步调整基础篇的队列测试
+
+基础篇集成测试只导入 `TaskQueueModule`，拆分后那里已不再提供 Worker，原测试会等待超时。
+
+保留公共队列冒烟测试只依赖 Redis的目标：在该测试文件中直接导入 `QueueWorkerBootstrap`、`TaskQueueProcessor`、`UploadCleanupScanner`、`UploadCleanupHandler`，并给 `Test.createTestingModule()` 增加以下 providers，原 imports 保留：
+
+```ts
+providers: [
+  QueueWorkerBootstrap,
+  TaskQueueProcessor,
+  { provide: UploadCleanupScanner, useValue: { scan: async () => ({ skipped: 'smoke-test' }) } },
+  { provide: UploadCleanupHandler, useValue: { handle: async () => ({ skipped: 'smoke-test' }) } },
+],
+```
+
+原来的 `testingModule.init()` 也要保留。这样只验证真实 Redis 和公共 Worker，上传业务用替身，不会注册真实清理 Scheduler。
+
+如果已有直接 `new TaskQueueProcessor()` 的单元测试，也要传入 Scanner 和 Handler 的测试替身。真正的上传清理需要后面单独联调，不能把此处替身的成功当作清理验收。
+
+## 第 11 步：先加几个关键测试
+
+新建 `apps/server/test/upload-cleanup.handler.spec.ts`。当前测试配置只匹配 `test/**/*.spec.ts`，不要放进 `src/`。
+
+```ts
+import { ConfigService } from '@nestjs/config'
+import { describe, expect, it, vi } from 'vite-plus/test'
+import { UploadCleanupHandler } from '@/modules/upload/upload-cleanup.handler'
+import { UploadCleanupRepository } from '@/modules/upload/upload-cleanup.repository'
+import {
+  StorageMultipartNotFoundError,
+  type StoragePort,
+} from '@/modules/upload/storage/storage.port'
+
+function setup(dryRun = false) {
+  const uploadSessionId = '11111111-1111-4111-8111-111111111111'
+  const repository = {
+    claim: vi.fn().mockResolvedValue({
+      cleanupClaimId: '22222222-2222-4222-8222-222222222222',
+      session: {
+        id: uploadSessionId,
+        bucket: 'test-bucket',
+        objectKey: 'test-object',
+        storageUploadId: 'test-multipart',
+      },
+    }),
+    finish: vi.fn().mockResolvedValue(true),
+    recordFailure: vi.fn().mockResolvedValue(undefined),
+  }
+  const storage = {
+    headObject: vi.fn().mockResolvedValue(null),
+    abortMultipartUpload: vi.fn().mockResolvedValue(undefined),
+    listParts: vi.fn().mockRejectedValue(new StorageMultipartNotFoundError(undefined)),
+  }
+  const config = {
+    getOrThrow: (key: string) => (key === 'uploadCleanup.dryRun' ? dryRun : true),
+  }
+  const handler = new UploadCleanupHandler(
+    config as unknown as ConfigService,
+    repository as unknown as UploadCleanupRepository,
+    storage as unknown as StoragePort,
+  )
+  return { handler, repository, storage, input: { uploadSessionId } }
+}
+
+describe('UploadCleanupHandler', () => {
+  it('预览时不领取任务、不操作存储', async () => {
+    const context = setup(true)
+    await context.handler.handle(context.input)
+    expect(context.repository.claim).not.toHaveBeenCalled()
+    expect(context.storage.abortMultipartUpload).not.toHaveBeenCalled()
+  })
+
+  it('无法领取时不操作存储', async () => {
+    const context = setup()
+    context.repository.claim.mockResolvedValue(null)
+    await context.handler.handle(context.input)
+    expect(context.storage.abortMultipartUpload).not.toHaveBeenCalled()
+  })
+
+  it('确认 Multipart 不存在以后才写成功', async () => {
+    const context = setup()
+    await expect(context.handler.handle(context.input)).resolves.toMatchObject({ cleaned: true })
+    expect(context.storage.abortMultipartUpload).toHaveBeenCalledOnce()
+    expect(context.storage.listParts).toHaveBeenCalledOnce()
+    expect(context.repository.finish).toHaveBeenCalledOnce()
+    expect(context.repository.recordFailure).not.toHaveBeenCalled()
+  })
+
+  it('存储暂时失败时保留失败，并抛出给 BullMQ 重试', async () => {
+    const context = setup()
+    const error = new Error('Temporary storage failure')
+    context.storage.abortMultipartUpload.mockRejectedValue(error)
+    await expect(context.handler.handle(context.input)).rejects.toThrow(error)
+    expect(context.repository.finish).not.toHaveBeenCalled()
+    expect(context.repository.recordFailure).toHaveBeenCalledOnce()
+  })
+
+  it('存在正式对象时不 Abort', async () => {
+    const context = setup()
+    context.storage.headObject.mockResolvedValue({ etag: 'test-etag' })
+    await expect(context.handler.handle(context.input)).rejects.toThrow('reconciliation required')
+    expect(context.storage.abortMultipartUpload).not.toHaveBeenCalled()
+  })
+
+  it('Abort 后 Multipart 仍存在时不记成功', async () => {
+    const context = setup()
+    context.storage.listParts.mockResolvedValue([])
+    await expect(context.handler.handle(context.input)).rejects.toThrow('still exists')
+    expect(context.repository.finish).not.toHaveBeenCalled()
+  })
+})
+```
+
+执行：
+
+```powershell
+vp run --filter server test
+vp run --filter server build
+```
+
+这些测试证明 Handler 的分支行为，但没有验证真实数据库锁和 MinIO。后续还要针对 Repository 增加真实 PostgreSQL 测试，覆盖“未过期、活动租约、两个 Worker 抢同一条记录、旧 Claim 无法写回”。不要只 Mock `claim()` 返回 `null` 就声称已经验证并发安全。
+
+## 第 12 步：本地走通完整链路
+
+### 12.1 启动预览模式
+
+在本机开发环境保持：
+
+```dotenv
+QUEUE_WORKER_ENABLED=true
+UPLOAD_CLEANUP_ENABLED=true
+UPLOAD_CLEANUP_DRY_RUN=true
+UPLOAD_CLEANUP_INTERVAL_MS=10000
+```
+
+临时改为 10 秒是为了不用等一分钟，验收后再改回 60000。确认 `.env.development.local`、`.env.local` 或外部环境变量没有覆盖它们。
+
+启动后端：
+
+```powershell
+vp run --filter server dev
+```
+
+先观察启动日志中的事件：
+
+```text
+upload_cleanup_schedule_ready
+```
+
+随后应周期性看到类似结果：
+
+```json
+{
+  "event": "upload_cleanup_scan",
+  "dryRun": true,
+  "candidates": 0,
+  "enqueued": 0
+}
+```
+
+日志实际可能由 Nest 包装成多行文本，重点看字段和值。候选数是 0 也证明扫描执行了，只是还没有到期数据。
+
+### 12.2 制造一个真正的未完成测试上传
+
+用现有上传页面或 Swagger 的 `POST /uploads/multipart` 创建一个测试会话，上传一片后暂停并等待所有请求结束。不要调用 Complete，也不要点“取消并释放”，否则前端已经主动清理，无法证明后台在起作用。
+
+复制接口返回的 `uploadSessionId`。浏览器 Network 可以确认请求完成；租约表中这个会话正常情况下应没有活动租约。
+
+另开终端执行 `vp run --filter server db:studio`。在 `upload_sessions` 中按这个 ID 找到唯一一条测试记录，仅把它的 `expiresAt` 改为几分钟前，其他字段保留。若之前已经预约过投递，再把这条记录的 `nextCleanupAt` 改到过去。
+
+这是为本地验收缩短等待时间。不要批量修改所有上传记录，也不要把它作为线上管理方式。
+
+### 12.3 预览应出现候选，但不释放分片
+
+等待下一轮扫描，应看到：
+
+```json
+{
+  "event": "upload_cleanup_candidate",
+  "id": "你刚创建的会话 UUID",
+  "status": "uploading"
+}
+```
+
+此时 `enqueued` 仍是 0，`cleanedAt` 仍为空，MinIO 的未完成上传仍在。
+
+普通 MinIO 对象列表通常不会展示未完成的 Multipart。需要使用已有 `mc` 环境的 `mc ls --incomplete --recursive`，不能因为普通文件列表为空就判断清完了。
+
+当前模板有 `minio-init` 工具服务，可以另开终端进入临时工具容器：
+
+```powershell
+docker compose run --rm --no-deps --entrypoint /bin/sh minio-init
+```
+
+进入容器后，在它的 Shell 中逐行执行：
+
+```sh
+mc alias set inspect http://minio:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"
+mc ls --incomplete --recursive "inspect/$MINIO_BUCKET"
+exit
+```
+
+这复用本地 Compose 配置，只列举状态，不删除 Bucket 或文件。用测试会话的 Object Key 对照这一条上传；这些内部存储标识只在本机排查，不写进前端接口或公共日志。
+
+### 12.4 开启实际清理
+
+确认候选只包含应回收的测试上传后，在本机配置修改：
+
+```dotenv
+UPLOAD_CLEANUP_DRY_RUN=false
+```
+
+重启 Server，等待扫描和单条任务处理完成。预期看到：
+
+```text
+upload_cleanup_scan            enqueued: 1
+upload_cleanup_completed       uploadSessionId: 测试会话 UUID
+queue_job_completed             jobName: upload.multipart-expire.v1
+```
+
+回到 Studio，检查这条记录：
+
+| 字段                | 预期      |
+| ------------------- | --------- |
+| `status`            | `expired` |
+| `cleanedAt`         | 非空时间  |
+| `cleanupClaimId`    | 空        |
+| `cleanupLeaseUntil` | 空        |
+| `lastCleanupError`  | 空        |
+
+再次运行 `mc ls --incomplete --recursive`，同一个未完成上传应已消失。Handler 也已通过 `ListParts → NoSuchUpload` 确认这一点。
+
+继续等待两轮扫描，已清理记录不会反复成为候选，因为 `cleanedAt` 非空。
+
+### 12.5 验证不能清理的情况
+
+逐个创建不同的测试会话，避免一个测试的数据影响另一个：
+
+| 场景         | 操作                                           | 必须看到的结果                                                     |
+| ------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
+| 未过期       | 正常初始化后等待扫描                           | 不 Abort，`cleanedAt` 为空                                         |
+| 有活动分片   | 限速上传一片，确认租约有效，再让该测试会话到期 | 在租约有效期间不 Abort；停止请求、租约结束并到下次预约时间后才清理 |
+| 已完成       | 正常完成一个测试文件                           | 正式文件仍能读取，清理不操作它                                     |
+| `completing` | 对照现有完成恢复流程                           | 不被本教程扫描选中                                                 |
+| 重复处理     | 观察失败重试或重复投递同一会话                 | 已确认完成的记录幂等跳过                                           |
+| 多实例       | 在不同 HTTP 端口启动两个同配置后端             | 同一时刻只有一个有效清理 Claim；所有权校验阻止旧 Claim 写回        |
+
+在途分片测试必须真实观察到有效租约；只在前端界面看见“上传中”文字不算验证。租约结束后，先前已预约过的记录可能等待最多 5 分钟再被扫描，测试时要结合 `nextCleanupAt` 判断。
+
+### 12.6 验证失败重试和后续补偿
+
+在本地 Server 已启动、初始化测试上传已成功之后，临时停止 MinIO：
+
+```powershell
+docker compose stop minio
+```
+
+把该测试会话设为到期，观察单条清理失败，`cleanedAt` 保持为空。BullMQ 默认 `attempts: 3` 是总共最多尝试 3 次，重试间隔沿用公共队列配置；不是首次之外再试 3 次。
+
+恢复 MinIO：
+
+```powershell
+docker compose start minio
+```
+
+即使旧 Job 已耗尽尝试次数，后续扫描也会为仍待处理的记录投递新 Job。数据库恢复需要等待 MinIO 请求失败返回及 `nextCleanupAt`/Claim 到期，并非一定在下一秒完成。
+
+当前 MinIO Adapter 启动时会 HeadBucket，所以不要在 MinIO 停止时重启 Server，否则你验证到的是“应用启动失败”，而不是“运行中的队列重试”。
+
+### 12.7 验证重启和停用
+
+重启后观察同一 Scheduler 继续工作，不要求补齐停机期间每一次扫描。把 `UPLOAD_CLEANUP_ENABLED=false` 后重启承担 Worker 的实例，应该看到 `upload_cleanup_schedule_removed`，后续不再周期扫描。
+
+多实例时全部 Worker 配置一致再重启。仅关闭一个实例的 Worker 开关，不会停止其他实例，也不会自动删除 Redis 里的调度规则。
+
+验收结束恢复需要的频率及开关，再执行：
+
+```powershell
+vp check
+vp run --filter server test
+vp run --filter server build
+```
+
+## 第 13 步：排查常见问题
+
+| 现象                             | 优先检查                                                                                 |
+| -------------------------------- | ---------------------------------------------------------------------------------------- |
+| 有注册日志，没有扫描日志         | `QUEUE_WORKER_ENABLED`、WorkerModule 是否导入、Redis 的 DB/Prefix 是否一致、队列是否暂停 |
+| 有扫描日志，始终 0 条            | `expiresAt`、`nextCleanupAt`、`cleanedAt`、候选状态是否符合                              |
+| 看到候选，没有实际清理           | 是否仍在 `DRY_RUN=true`，本机 local 环境文件是否覆盖                                     |
+| Job completed，但没有 cleanedAt  | 可能返回了 skipped；检查活动租约、状态、旧 Claim 和开关，Job 完成不等于业务清理成功      |
+| 长时间保持 expired               | `lastCleanupError`、Worker failed 日志、MinIO 是否可用、有效分片租约是否一直续期         |
+| NoSuchUpload 后仍失败            | 是否沿用当前 Adapter 的错误映射；其他 403/超时不能按 NoSuchUpload 处理                   |
+| 报 reconciliation required       | 异常状态下发现正式对象；保留对象，核对会话元数据和完成流程                               |
+| 完成/取消返回 PARTS_STILL_ACTIVE | 先等分片结束；失败请求可能保留最多 2 分钟的短租约                                        |
+| 基础 Redis 冒烟测试超时          | 拆分模块后是否按第 10.6 节提供 Worker 和业务替身                                         |
+| 关闭开关仍有扫描                 | 是否重启、是否删除旧 Scheduler、其他副本是否又注册了规则                                 |
+| 单次清理超过 2 分钟              | 检查存储请求时长，补超时和续租；租约失效后本次不能写成功                                 |
+| 大量过期数据积压                 | 看每轮批量、扫描耗时、Worker 并发和最老 nextCleanupAt，再调整吞吐                        |
+
+按扫描间隔 60 秒、批量 100 粗算，顺利情况下扫描投递能力约为每分钟 100 条；实际完成速度还受 Worker 和 MinIO 限制。不要一开始就把批量和并发同时放大。
+
+## 第 14 步：部署时保留存储兜底和监控
+
+应用扫描依赖数据库保留的 UploadId。初始化 MinIO 成功但数据库插入失败、服务长期停机等情况，可能留下数据库里找不到的孤儿 Multipart。因此还要由 MinIO 生命周期兜底。
+
+在 Bucket 已有生命周期规则中**合并**下面这一条，例如 7 天后终止未完成上传：
+
+```json
+{
+  "ID": "abort-incomplete-multipart-after-7-days",
+  "Status": "Enabled",
+  "Filter": { "Prefix": "" },
+  "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 7 }
+}
+```
+
+上面是一个 Rule，不是完整配置文件。完整配置使用 `{"Rules": [...]}`，先读取 Bucket 当前规则，把此 Rule 加入或按 ID 更新，再保存，避免覆盖其他保留策略。兜底时间要大于业务允许的上传时长，并留出排障时间；生命周期不会帮数据库写 `cleanedAt`。
+
+至少持续观察扫描次数、候选数、清理成功数、最终失败 Job、最老未处理记录和长期 `completing` 记录。原始 SDK 错误可能包含连接和存储信息，公共日志只记录安全元数据；Redis 内的失败 Job 也应限权访问并按基础篇设置保留上限。
+
+上线已有服务时，先迁移数据库，保持清理预览模式，部署完所有支持分片租约的新 API/Worker，排空旧实例及旧在途上传，再启用实际清理。新旧版本混跑时，旧 API 不登记租约，后台无法知道它正在上传，不能提前打开实际清理。
+
+本教程使用租约、封口、结果确认和重复补偿处理常见并发与故障。生产还需验证数据库断连、进程暂停超过租约、存储慢请求及实例强杀等情况，并配置请求超时和告警，不能仅凭一次本地成功宣称所有故障已覆盖。
+
+## 完成检查
+
+- [ ] 公共队列冒烟任务已经跑通。
+- [ ] Scheduler 使用固定 ID，按配置周期自动扫描。
+- [ ] 前端关闭后仍然自动处理过期会话。
+- [ ] 预览模式只看候选，不操作存储。
+- [ ] 分片上传、Complete、取消和清理遵守同一套租约与封口规则。
+- [ ] 活动分片、未过期会话和正式文件不会被误清理。
+- [ ] MinIO 确认处理后才写 cleanedAt。
+- [ ] 单个 Job 失败能重试，次数耗尽后还有后续扫描补偿。
+- [ ] 多实例仍由数据库 Claim 控制清理权。
+- [ ] 重启不会累积重复规则，停用能删除已有规则。
+- [ ] 完成了测试及 PostgreSQL、Redis、MinIO 实际联调。
+
+参考：[公共队列基础篇](./README.md)、[上传教程的过期清理说明](../04.upload.md#第-18-步过期清理和生产安全)、[BullMQ Job Schedulers](https://docs.bullmq.io/guide/job-schedulers)。如果以后实施了 [files 表上传改造](../05.上传改造方案/README.md)，还需同步该新模型的文件状态；本文代码以当前只有 upload_sessions 的实现为准。