create-bubbles 0.1.26 → 0.1.28

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/projects/projects.controller.ts

@@ -0,0 +1,94 @@
+import { Body, Controller, Get, HttpCode, Patch, Post, Query, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { actor, ids } from '@/modules/access/access-http'
+import { entityListSchema, parse, statusSchema } from '@/modules/access/access.validation'
+import {
+  createProjectSchema,
+  profileSchema,
+} from '@/modules/access/workspaces/workspaces.validation'
+import { administratorSchema } from '@/modules/members/administrators/administrators.validation'
+import { ProjectsService } from './projects.service'
+
+@Controller()
+export class ProjectsController {
+  constructor(private readonly projectsService: ProjectsService) {}
+  /** 校验公司、项目标识和资料字段，提交项目资料更新及预期版本。 */
+  @Patch('companies/:companyId/projects/:projectId')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.profile.update' })
+  updateProfile(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.projectsService.profile({
+      actor: actor(req),
+      companyId: ids(req).companyId!,
+      projectId: ids(req).projectId!,
+      body: parse(profileSchema, body),
+    })
+  }
+  /** 校验公司标识与分页筛选参数，读取当前用户可查询的公司项目列表。 */
+  @Get('companies/:companyId/projects')
+  @AccessPolicy({ scope: 'company', permission: 'company.projects.read' })
+  projects(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.projectsService.listProjects({
+      actor: actor(req),
+      companyId: ids(req).companyId!,
+      query: parse(entityListSchema, query),
+    })
+  }
+  /** 校验公司标识、项目资料和初始管理员 userId，提交公司管理员创建项目操作。 */
+  @Post('companies/:companyId/projects')
+  @AccessPolicy({ scope: 'company', permission: 'company.projects.create', adminOnly: true })
+  createProject(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.projectsService.create({
+      actor: actor(req),
+      companyId: ids(req).companyId!,
+      body: parse(createProjectSchema, body),
+    })
+  }
+  /** 校验公司和项目标识，读取项目资料及管理员详情。 */
+  @Get('companies/:companyId/projects/:projectId')
+  @AccessPolicy({ scope: 'project', permission: 'project.profile.read' })
+  projectDetail(@Req() req: FastifyRequest) {
+    const params = ids(req)
+    return this.projectsService.get({
+      actor: actor(req),
+      companyId: params.companyId!,
+      projectId: params.projectId!,
+    })
+  }
+  /** 校验公司、项目标识及预期版本，提交公司权限下的项目启停操作。 */
+  @Patch('companies/:companyId/projects/:projectId/status')
+  @AccessPolicy({ scope: 'company', permission: 'company.projects.status' })
+  projectStatus(@Req() req: FastifyRequest, @Body() body: unknown) {
+    const params = ids(req)
+    return this.projectsService.status({
+      actor: actor(req),
+      companyId: params.companyId!,
+      projectId: params.projectId!,
+      body: parse(statusSchema, body),
+    })
+  }
+  /** 校验公司、项目标识及管理员 userId，提交追加或替换项目管理员操作。 */
+  @Post('companies/:companyId/projects/:projectId/administrator')
+  @HttpCode(200)
+  @AccessPolicy({ scope: 'company', permission: 'company.projects.administrator', adminOnly: true })
+  projectAdministrator(@Req() req: FastifyRequest, @Body() body: unknown) {
+    const params = ids(req)
+    return this.projectsService.setAdministrator({
+      actor: actor(req),
+      companyId: params.companyId!,
+      projectId: params.projectId!,
+      body: parse(administratorSchema, body),
+    })
+  }
+  /** 校验公司和项目标识，返回公司管理员可管理的项目管理员列表。 */
+  @Get('companies/:companyId/projects/:projectId/administrators')
+  @AccessPolicy({ scope: 'company', permission: 'company.projects.administrator', adminOnly: true })
+  projectAdministrators(@Req() req: FastifyRequest) {
+    const params = ids(req)
+    return this.projectsService.projectAdministrators({
+      actor: actor(req),
+      companyId: params.companyId!,
+      projectId: params.projectId!,
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/projects/projects.module.ts

@@ -0,0 +1,13 @@
+import { Module } from '@nestjs/common'
+import { AccessModule } from '../access/access.module'
+import { MembersModule } from '../members/members.module'
+import { OrganizationModule } from '../organization/organization.module'
+import { ProjectsController } from './projects.controller'
+import { ProjectsService } from './projects.service'
+
+@Module({
+  imports: [AccessModule, MembersModule, OrganizationModule],
+  controllers: [ProjectsController],
+  providers: [ProjectsService],
+})
+export class ProjectsModule {}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/projects/projects.service.ts

@@ -0,0 +1,369 @@
+import { Injectable } from '@nestjs/common'
+import { and, count, desc, eq, inArray, ne, sql } from 'drizzle-orm'
+import { projects, projectMembers } from '@/database/schema'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AccessService, type AccessActor } from '@/modules/access/access.service'
+import { ACCESS_ERRORS } from '@/modules/access/access.errors'
+import {
+  checkVersion,
+  pageWindow,
+  requireFound,
+  searchSql,
+  type AccessDb,
+} from '@/modules/access/access.store'
+import { MembersService } from '@/modules/members/members.service'
+import { AdministratorsService } from '@/modules/members/administrators/administrators.service'
+import { ProjectOrganizationInitializationService } from '@/modules/organization/initialization/project-organization-initialization.service'
+import type {
+  AccessScope,
+  CreateProjectRequest,
+  EntityPageQuery,
+  ProjectDetail,
+  ProjectRecord,
+  SetAdministratorRequest,
+  SetAdministratorResult,
+  StatusRequest,
+  UpdateProfileRequest,
+} from 'shared/types'
+import { normalizeOrganizationCode, toTimestampRecord } from 'shared/utils'
+
+@Injectable()
+export class ProjectsService {
+  constructor(
+    private readonly access: AccessService,
+    private readonly members: MembersService,
+    private readonly administrators: AdministratorsService,
+    private readonly organizationInitialization: ProjectOrganizationInitializationService,
+  ) {}
+
+  /** 拒绝当前企业内与既有项目规范化编码冲突的创建或更新。 */
+  private async assertUniqueCode(
+    db: AccessDb,
+    input: { companyId: string; code: string; excludeProjectId?: string },
+  ) {
+    const [duplicate] = await db
+      .select({ id: projects.id })
+      .from(projects)
+      .where(
+        and(
+          eq(projects.companyId, input.companyId),
+          eq(
+            sql<string>`lower(normalize(btrim(${projects.code}), NFKC))`,
+            normalizeOrganizationCode(input.code),
+          ),
+          input.excludeProjectId ? ne(projects.id, input.excludeProjectId) : undefined,
+        ),
+      )
+      .limit(1)
+    if (duplicate) throw new AppException(ACCESS_ERRORS.DUPLICATE_RESOURCE)
+  }
+
+  /** 按公司和项目标识共同查找项目，隔离跨公司访问并转换时间字段。 */
+  async project(
+    db: AccessDb,
+    scope: { companyId: string; projectId: string },
+  ): Promise<ProjectRecord> {
+    const [row] = await db
+      .select()
+      .from(projects)
+      .where(and(eq(projects.companyId, scope.companyId), eq(projects.id, scope.projectId)))
+    return toTimestampRecord(requireFound(row))
+  }
+
+  /** 读取公司内指定项目的资料，以及该项目直接分配的管理员状态。 */
+  async projectDetail(
+    db: AccessDb,
+    scope: { companyId: string; projectId: string },
+  ): Promise<ProjectDetail> {
+    return {
+      ...(await this.project(db, scope)),
+      administrators: await this.administrators.administrators(db, { type: 'project', ...scope }),
+    }
+  }
+
+  /**
+   * 在公司项目读取权限下分页查询项目，普通成员仅能查询具有成员关系的项目。
+   *
+   * 公司管理员可查询公司内全部项目，支持状态、名称和编码筛选。
+   */
+  listProjects(input: { actor: AccessActor; companyId: string; query: EntityPageQuery }) {
+    return this.access.read(
+      {
+        actor: input.actor,
+        scope: { type: 'company', companyId: input.companyId },
+        permission: 'company.projects.read',
+      },
+      /** 按操作者管理员身份限定项目可见范围，并在同一快照内读取总数和分页记录。 */
+      async (tx, access) => {
+        const { page, pageSize, offset } = pageWindow(input.query)
+        const joined = tx
+          .select({ id: projectMembers.projectId })
+          .from(projectMembers)
+          .where(
+            and(
+              eq(projectMembers.companyId, input.companyId),
+              eq(projectMembers.userId, input.actor.userId),
+            ),
+          )
+        const condition = and(
+          eq(projects.companyId, input.companyId),
+          input.query.status ? eq(projects.status, input.query.status) : undefined,
+          access.administrator ? undefined : inArray(projects.id, joined),
+          searchSql([projects.name, projects.code], input.query.query),
+        )
+        const [total] = await tx.select({ value: count() }).from(projects).where(condition)
+        const rows = await tx
+          .select()
+          .from(projects)
+          .where(condition)
+          .orderBy(desc(projects.createdAt), desc(projects.id))
+          .limit(pageSize)
+          .offset(offset)
+        return { items: rows.map(toTimestampRecord), total: total!.value, page, pageSize }
+      },
+    )
+  }
+
+  /**
+   * 要求公司管理员具备创建权限，验证公司内编码唯一性和管理员成员资格后创建项目并记录审计。
+   *
+   * 同时初始化项目内置角色、首位管理员及显式选择的空白／模板组织快照，返回项目详情。
+   */
+  create(input: { actor: AccessActor; companyId: string; body: CreateProjectRequest }) {
+    return this.access.write(
+      {
+        actor: input.actor,
+        scope: { type: 'company', companyId: input.companyId },
+        permission: 'company.projects.create',
+        adminOnly: true,
+      },
+      /** 校验初始管理员公司成员资格，原子创建项目、权限基线、组织快照及对应审计。 */
+      async (tx, access) => {
+        const user = await this.members.userForAdministrator(tx, {
+          userId: input.body.administratorUserId,
+          companyId: input.companyId,
+        })
+        await this.assertUniqueCode(tx, {
+          companyId: input.companyId,
+          code: input.body.code,
+        })
+        const [created] = await tx
+          .insert(projects)
+          .values({
+            companyId: input.companyId,
+            name: input.body.name,
+            code: input.body.code,
+            description: input.body.description ?? '',
+          })
+          .returning()
+        const scope: AccessScope = {
+          type: 'project',
+          companyId: input.companyId,
+          projectId: created!.id,
+        }
+        await this.administrators.initialize(tx, scope, user.id)
+        const initialization = await this.organizationInitialization.initializeProject(tx, {
+          companyId: input.companyId,
+          projectId: created!.id,
+          initialization: input.body.organizationInitialization,
+          actor: input.actor,
+          access,
+        })
+        await this.access.audit(tx, {
+          actor: input.actor,
+          access,
+          action: 'project.create',
+          objectType: 'project',
+          objectId: created!.id,
+          summary: {
+            targetUserId: user.id,
+            organizationInitializationMode: initialization.mode,
+            organizationTemplateId: initialization.templateId,
+            organizationTemplateVersion: initialization.templateVersion,
+            organizationUnitCount: initialization.unitCount,
+            positionCount: initialization.positionCount,
+          },
+        })
+        return this.projectDetail(tx, scope)
+      },
+    )
+  }
+
+  /** 使用项目资料读取权限验证目标项目访问资格，返回项目资料及管理员列表。 */
+  get(input: { actor: AccessActor; companyId: string; projectId: string }) {
+    return this.access.read(
+      {
+        actor: input.actor,
+        scope: { type: 'project', companyId: input.companyId, projectId: input.projectId },
+        permission: 'project.profile.read',
+      },
+      (tx) => this.projectDetail(tx, { companyId: input.companyId, projectId: input.projectId }),
+    )
+  }
+
+  /** 在项目作用域中校验修改权限、数据版本及公司内编码唯一性，更新项目资料并记录审计。 */
+  profile(input: {
+    actor: AccessActor
+    companyId: string
+    projectId: string
+    body: UpdateProfileRequest
+  }) {
+    return this.access.write(
+      {
+        actor: input.actor,
+        scope: { type: 'project', companyId: input.companyId, projectId: input.projectId },
+        permission: 'project.profile.update',
+      },
+      /** 读取项目版本并检查公司内编码唯一性，资料更新与审计同步提交。 */
+      async (tx, access) => {
+        const existing = await this.project(tx, input)
+        checkVersion(existing.version, input.body.expectedVersion)
+        if (input.body.code)
+          await this.assertUniqueCode(tx, {
+            companyId: input.companyId,
+            code: input.body.code,
+            excludeProjectId: existing.id,
+          })
+        const { expectedVersion: _, ...changes } = input.body
+        await tx
+          .update(projects)
+          .set({ ...changes, version: sql`${projects.version} + 1`, updatedAt: new Date() })
+          .where(and(eq(projects.companyId, input.companyId), eq(projects.id, existing.id)))
+        await this.access.audit(tx, {
+          actor: input.actor,
+          access,
+          action: 'project.update',
+          objectType: 'project',
+          objectId: existing.id,
+          summary: { changedFields: Object.keys(changes) },
+        })
+        return this.project(tx, input)
+      },
+    )
+  }
+
+  /**
+   * 使用公司项目状态权限启停项目，普通操作者还必须具备目标项目成员关系。
+   *
+   * 校验客户端版本，启用时检查管理员完整性，并在事务内写入审计。
+   */
+  status(input: { actor: AccessActor; companyId: string; projectId: string; body: StatusRequest }) {
+    return this.access.write(
+      {
+        actor: input.actor,
+        scope: { type: 'company', companyId: input.companyId },
+        permission: 'company.projects.status',
+      },
+      /** 检查普通操作者的项目成员关系，变更状态后验证启用项目的管理员并写入审计。 */
+      async (tx, access) => {
+        const target = await this.project(tx, input)
+        if (!access.administrator) {
+          const [member] = await tx
+            .select()
+            .from(projectMembers)
+            .where(
+              and(
+                eq(projectMembers.companyId, input.companyId),
+                eq(projectMembers.projectId, input.projectId),
+                eq(projectMembers.userId, input.actor.userId),
+              ),
+            )
+          requireFound(member)
+        }
+        checkVersion(target.version, input.body.expectedVersion)
+        await tx
+          .update(projects)
+          .set({
+            status: input.body.status,
+            version: sql`${projects.version} + 1`,
+            updatedAt: new Date(),
+          })
+          .where(and(eq(projects.companyId, input.companyId), eq(projects.id, target.id)))
+        if (input.body.status === 'active')
+          await this.access.assertAdministrators(tx, {
+            companyId: input.companyId,
+            projectId: input.projectId,
+          })
+        await this.access.audit(tx, {
+          actor: input.actor,
+          access,
+          action: 'project.status',
+          objectType: 'project',
+          objectId: target.id,
+          summary: { fromStatus: target.status, toStatus: input.body.status },
+        })
+        return this.project(tx, input)
+      },
+    )
+  }
+
+  /**
+   * 要求公司管理员具备项目管理员设置权限，为公司内指定项目追加或替换管理员并记录审计。
+   *
+   * @returns 新管理员状态及被替换用户标识。
+   */
+  setAdministrator(input: {
+    actor: AccessActor
+    companyId: string
+    projectId: string
+    body: SetAdministratorRequest
+  }) {
+    return this.access.write(
+      {
+        actor: input.actor,
+        scope: { type: 'company', companyId: input.companyId },
+        permission: 'company.projects.administrator',
+        adminOnly: true,
+      },
+      /** 先确认项目属于指定公司，再调整管理员关系并记录替换目标。 */
+      async (tx, access): Promise<SetAdministratorResult> => {
+        await this.project(tx, input)
+        const scope: AccessScope = {
+          type: 'project',
+          companyId: input.companyId,
+          projectId: input.projectId,
+        }
+        const user = await this.administrators.assign(tx, { scope, body: input.body })
+        await this.access.audit(tx, {
+          actor: input.actor,
+          access,
+          action: 'project.administrator.set',
+          objectType: 'project',
+          objectId: input.projectId,
+          summary: {
+            targetUserId: user.id,
+            companyId: input.companyId,
+            replacedUserId: input.body.replaceUserId ?? null,
+          },
+        })
+        return {
+          administrator: (await this.administrators.administrators(tx, scope)).find(
+            (item) => item.id === user.id,
+          )!,
+          replacedUserId: input.body.replaceUserId ?? null,
+        }
+      },
+    )
+  }
+
+  /** 要求公司管理员具备项目管理员设置权限，返回目标项目直接分配的管理员及其有效状态。 */
+  projectAdministrators(input: { actor: AccessActor; companyId: string; projectId: string }) {
+    return this.access.read(
+      {
+        actor: input.actor,
+        scope: { type: 'company', companyId: input.companyId },
+        permission: 'company.projects.administrator',
+        adminOnly: true,
+      },
+      /** 确认项目存在且属于指定公司后读取其直接分配的管理员。 */
+      async (tx) => {
+        await this.project(tx, input)
+        return this.administrators.administrators(tx, {
+          type: 'project',
+          companyId: input.companyId,
+          projectId: input.projectId,
+        })
+      },
+    )
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/task-queue/queue-worker.bootstrap.ts

@@ -11,6 +11,9 @@ export class QueueWorkerBootstrap implements OnApplicationBootstrap {
     private readonly registrar: BullRegistrar,
   ) {}
 
+  /**
+   * 仅在配置启用消费者且尚未注册时启动 Worker，避免同一实例重复注册。
+   */
   onApplicationBootstrap() {
     const workerEnabled = this.config.getOrThrow<boolean>('queue.workerEnabled')
 

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/task-queue/task-queue.contracts.ts

@@ -16,6 +16,10 @@ export const TASK_PAYLOAD_SCHEMAS = {
   [TASK_JOB_NAMES.QUEUE_SMOKE]: QueueSmokePayloadSchema,
 } satisfies Record<TaskName, z.ZodType>
 
+/**
+ * 按任务名称选择对应的 Zod 模式，校验并返回可入队的负载。
+ * @throws 负载不满足对应任务契约时抛出 Zod 校验异常。
+ */
 export function parseTaskPayload<Name extends TaskName>(
   name: Name,
   payload: unknown,

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/task-queue/task-queue.module.ts

@@ -12,11 +12,16 @@ import { TaskQueueService } from './task-queue.service'
     BullModule.forRootAsync({
       imports: [ConfigModule],
       inject: [ConfigService],
+      /**
+       * 根据队列专属配置创建 Redis 连接、指数退避和任务保留策略。
+       */
       useFactory: (config: ConfigService) => {
         const queue = config.getOrThrow<QueueConfig>('queue')
 
         return {
           connection: {
+            // ioredis 6 默认使用 RESP3，显式保留升级前的 RESP2 连接协议。
+            protocol: 2,
             host: queue.host,
             port: queue.port,
             username: queue.username,

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/task-queue/task-queue.processor.ts

@@ -8,6 +8,10 @@ import { QueueSmokePayloadSchema } from './task-queue.contracts'
 export class TaskQueueProcessor extends WorkerHost {
   private readonly logger = new Logger(TaskQueueProcessor.name)
 
+  /**
+   * 按任务名称校验并执行队列任务，冒烟任务返回标记及处理时间。
+   * @throws 未知任务或无效负载抛出 UnrecoverableError，阻止无意义的自动重试。
+   */
   async process(job: Job): Promise<unknown> {
     switch (job.name) {
       case TASK_JOB_NAMES.QUEUE_SMOKE: {
@@ -28,6 +32,9 @@ export class TaskQueueProcessor extends WorkerHost {
     }
   }
 
+  /**
+   * 记录任务完成事件及任务标识，便于按队列和尝试次数追踪处理结果。
+   */
   @OnWorkerEvent('completed')
   onCompleted(job: Job) {
     this.logger.log({
@@ -39,6 +46,9 @@ export class TaskQueueProcessor extends WorkerHost {
     })
   }
 
+  /**
+   * 记录任务失败事件，允许任务记录缺失，并仅输出错误名称。
+   */
   @OnWorkerEvent('failed')
   onFailed(job: Job | undefined, error: Error) {
     this.logger.error({
@@ -51,6 +61,9 @@ export class TaskQueueProcessor extends WorkerHost {
     })
   }
 
+  /**
+   * 记录 Worker 运行错误的名称，便于定位消费者基础设施故障。
+   */
   @OnWorkerEvent('error')
   onWorkerError(error: Error) {
     this.logger.error({

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/task-queue/task-queue.service.ts

@@ -17,6 +17,12 @@ export class TaskQueueService {
     private readonly queue: Queue,
   ) {}
 
+  /**
+   * 校验任务负载与投递选项后，将任务写入 BullMQ 队列。
+   * @param options 可指定任务 ID 和延迟毫秒数。
+   * @returns 可用于跟踪任务的队列名、任务 ID 和任务名称。
+   * @throws 负载或选项无效、投递失败或队列未返回任务 ID 时抛出错误。
+   */
   async enqueue<Name extends TaskName>(
     name: Name,
     payload: TaskPayloadMap[Name],
@@ -43,6 +49,9 @@ export class TaskQueueService {
     }
   }
 
+  /**
+   * 检查任务 ID 不含冒号，且延迟为非负安全整数；不满足 BullMQ 约束时抛出错误。
+   */
   private validateOptions(options: EnqueueTaskOptions) {
     if (options.jobId?.includes(':')) {
       throw new Error('BullMQ jobId must not contain a colon')

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/db/db.controller.ts

@@ -8,18 +8,27 @@ import { CreateUserDto } from './dto/create-user.dto'
 export class DbController {
   constructor(private readonly dbService: DbService) {}
 
+  /**
+   * 返回数据库当前时间，供 HTTP 层验证数据库连通性。
+   */
   @ApiOperation({ summary: '测试数据库连接' })
   @Get()
   async ping() {
     return { time: await this.dbService.ping() }
   }
 
+  /**
+   * 返回数据库示例服务查询的全部用户记录。
+   */
   @ApiOperation({ summary: '获取所有用户' })
   @Get('users')
   async list() {
     return this.dbService.findAll()
   }
 
+  /**
+   * 将经 DTO 校验的请求体提交给数据库示例服务创建用户。
+   */
   @ApiOperation({ summary: '创建用户' })
   @Post('user')
   async create(@Body() body: CreateUserDto) {

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/db/db.service.ts

@@ -6,15 +6,24 @@ import { users } from '@/database/schema'
 export class DbService {
   constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
 
+  /**
+   * 查询数据库当前时间以验证 PostgreSQL 连接可用。
+   */
   async ping() {
     const res = await this.db.execute('SELECT now() AS now')
     return res.rows[0]
   }
 
+  /**
+   * 读取全部用户记录，供数据库示例接口联调使用。
+   */
   async findAll() {
     return this.db.query.users.findMany()
   }
 
+  /**
+   * 插入示例用户资料并返回数据库生成的完整记录。
+   */
   async create(data: Omit<typeof users.$inferInsert, 'id' | 'createdAt'>) {
     const [row] = await this.db.insert(users).values(data).returning()
     return row

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/test/redis/redis.controller.ts

@@ -8,6 +8,9 @@ import { GetQueryDto, SetQueryDto } from './dto/redis-quary.dto'
 export class RedisController {
   constructor(private readonly redisService: RedisService) {}
 
+  /**
+   * 调用 Redis 连通性探测并将结果包装为 HTTP 响应。
+   */
   @ApiOperation({ summary: '测试 Redis 连接' })
   @Get('ping')
   async ping() {
@@ -15,6 +18,9 @@ export class RedisController {
   }
 
   // GET /redis/set?key=name&value=tom&ttl=60
+  /**
+   * 接收 Redis 测试键值和可选有效期，写入后返回提交的信息。
+   */
   @ApiOperation({ summary: '设置键值对' })
   @Post('set')
   async set(@Body() body: SetQueryDto) {
@@ -23,6 +29,9 @@ export class RedisController {
   }
 
   // GET /redis/get?key=name
+  /**
+   * 读取测试查询指定的 Redis 键，并返回键名及当前值。
+   */
   @ApiOperation({ summary: '获取键值对' })
   @Get('get')
   async get(@Query('key') query: GetQueryDto) {