create-bubbles 0.1.26 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/access.guard.ts

@@ -0,0 +1,63 @@
+import { Injectable, type CanActivate, type ExecutionContext } from '@nestjs/common'
+import { Reflector } from '@nestjs/core'
+import type { FastifyRequest } from 'fastify'
+import {
+  ACCESS_POLICY_KEY,
+  type AccessPolicyDefinition,
+} from '@/common/decorators/access-policy.decorator'
+import { IS_PUBLIC_KEY } from '@/common/constants/auth'
+import { AppException } from '@/common/exceptions/app.exception'
+import { ACCESS_ERRORS } from './access.errors'
+import { AccessService } from './access.service'
+import { actor, ids, scopeFor } from './access-http'
+import type { AccessScope } from 'shared/types'
+
+@Injectable()
+export class AccessGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly access: AccessService,
+  ) {}
+  /**
+   * 读取路由访问策略并验证当前作用域权限；公开接口和预检请求直接放行。
+   *
+   * 仅要求登录的策略交由认证守卫处理，其余策略在只读事务中重新验证权限。
+   * 未声明访问策略的受保护接口默认拒绝访问。
+   * @returns 权限校验通过时返回 true，否则抛出对应业务异常。
+   */
+  async canActivate(context: ExecutionContext) {
+    const request = context.switchToHttp().getRequest<FastifyRequest>()
+    if (
+      request.method === 'OPTIONS' ||
+      this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+        context.getHandler(),
+        context.getClass(),
+      ])
+    )
+      return true
+    const policy = this.reflector.getAllAndOverride<AccessPolicyDefinition>(ACCESS_POLICY_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ])
+    if (!policy) throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+    if (policy.scope === 'authenticated') return true
+    const params = ids(request)
+    const scope: AccessScope =
+      policy.scope === 'route'
+        ? scopeFor(request)
+        : policy.scope === 'platform'
+          ? { type: 'platform' }
+          : policy.scope === 'company'
+            ? { type: 'company', companyId: params.companyId! }
+            : { type: 'project', companyId: params.companyId!, projectId: params.projectId! }
+    const permission =
+      typeof policy.permission === 'string'
+        ? policy.permission.replace('{scope}', scope.type)
+        : policy.permission?.map((p) => p.replace('{scope}', scope.type))
+    await this.access.read(
+      { actor: actor(request), scope, permission, adminOnly: policy.adminOnly },
+      async () => undefined,
+    )
+    return true
+  }
+}

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

@@ -0,0 +1,27 @@
+import { Module } from '@nestjs/common'
+import { APP_GUARD } from '@nestjs/core'
+import { AuthModule } from '../auth/auth.module'
+import { AccessService } from './access.service'
+import { AccessSeedService } from './seed/access-seed.service'
+import { RolesService } from './roles/roles.service'
+import { RolesController } from './roles/roles.controller'
+import { PermissionsCleanupService } from './maintenance/permissions-cleanup.service'
+import { PermissionsCleanupController } from './maintenance/permissions-cleanup.controller'
+import { WorkspacesController } from './workspaces/workspaces.controller'
+import { WorkspacesService } from './workspaces/workspaces.service'
+import { AccessGuard } from './access.guard'
+
+@Module({
+  imports: [AuthModule],
+  controllers: [RolesController, PermissionsCleanupController, WorkspacesController],
+  providers: [
+    AccessService,
+    AccessSeedService,
+    RolesService,
+    PermissionsCleanupService,
+    WorkspacesService,
+    { provide: APP_GUARD, useClass: AccessGuard },
+  ],
+  exports: [AccessService, AccessSeedService],
+})
+export class AccessModule {}

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

@@ -0,0 +1,441 @@
+import { Inject, Injectable } from '@nestjs/common'
+import { DRIZZLE, type DrizzleDB } from '@/database/db.module'
+import {
+  auditLogs,
+  companies,
+  companyMembers,
+  menus,
+  menuVersions,
+  projects,
+  projectMembers,
+  roles,
+  rolePermissions,
+  userRoles,
+  users,
+} from '@/database/schema'
+import { and, eq, exists, inArray, or, sql } from 'drizzle-orm'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AUTH_ERRORS } from '../auth/auth.errors'
+import { ACCESS_ERRORS } from './access.errors'
+import { lockAccess, scopeColumns, scopeFilter, type AccessDb, type AccessTx } from './access.store'
+import type {
+  AccessContext,
+  AccessScope,
+  AuditRecord,
+  MenuNode,
+  ScopeType,
+  UserSummary,
+} from 'shared/types'
+import {
+  ACCESS_PERMISSION_CATALOG as FUNCTION_CATALOG,
+  ACCESS_CATALOG_VERSION as CATALOG_VERSION,
+} from 'shared/utils'
+
+export interface AccessActor {
+  userId: string
+  requestId: string
+}
+export interface AccessRequirement {
+  actor: AccessActor
+  scope: AccessScope
+  permission?: string | string[]
+  adminOnly?: boolean
+}
+export interface VerifiedAccess {
+  user: UserSummary
+  scope: AccessScope
+  administrator: ScopeType | null
+  permissionKeys: string[]
+  allMenus: MenuNode[]
+  menuVersion: number
+}
+
+@Injectable()
+export class AccessService {
+  constructor(@Inject(DRIZZLE) readonly db: DrizzleDB) {}
+
+  /** 查询用户在指定作用域内直接分配的角色，不包含从上级公司继承的管理员身份。 */
+  async roleAssignments(db: AccessDb, scope: AccessScope, userId: string) {
+    return db
+      .select({ role: roles })
+      .from(userRoles)
+      .innerJoin(roles, eq(roles.id, userRoles.roleId))
+      .where(and(eq(userRoles.userId, userId), scopeFilter(scope)))
+  }
+
+  /** 判断用户在指定作用域内是否拥有有效管理员身份；项目支持继承公司管理员身份。 */
+  async isAdministrator(db: AccessDb, scope: AccessScope, userId: string): Promise<boolean> {
+    return this.hasAdministrator(db, scope, userId)
+  }
+
+  /**
+   * 检查作用域内是否存在满足账号状态、成员状态及角色约束的管理员。
+   *
+   * @param userId - 指定时只检查该用户，省略时用于判断是否仍存在任意有效管理员。
+   */
+  private async hasAdministrator(db: AccessDb, scope: AccessScope, userId?: string) {
+    const companyMembership =
+      scope.type === 'platform'
+        ? undefined
+        : exists(
+            db
+              .select({ value: sql`1` })
+              .from(companyMembers)
+              .where(
+                and(
+                  eq(companyMembers.companyId, scope.companyId),
+                  eq(companyMembers.userId, users.id),
+                  eq(companyMembers.status, 'active'),
+                ),
+              ),
+          )
+    const validRole =
+      scope.type !== 'project'
+        ? scopeFilter(scope)
+        : or(
+            scopeFilter({ type: 'company', companyId: scope.companyId }),
+            and(
+              scopeFilter(scope),
+              exists(
+                db
+                  .select({ value: sql`1` })
+                  .from(projectMembers)
+                  .where(
+                    and(
+                      eq(projectMembers.companyId, scope.companyId),
+                      eq(projectMembers.projectId, scope.projectId),
+                      eq(projectMembers.userId, users.id),
+                      eq(projectMembers.status, 'active'),
+                    ),
+                  ),
+              ),
+            ),
+          )
+    const [found] = await db
+      .select({ id: users.id })
+      .from(userRoles)
+      .innerJoin(roles, eq(roles.id, userRoles.roleId))
+      .innerJoin(users, eq(users.id, userRoles.userId))
+      .where(
+        and(
+          eq(users.status, 'active'),
+          eq(roles.builtin, 'administrator'),
+          userId ? eq(users.id, userId) : undefined,
+          companyMembership,
+          validRole,
+        ),
+      )
+      .limit(1)
+    return !!found
+  }
+
+  /**
+   * 枚举本次变更可能影响的作用域，并筛选仍存在有效管理员的作用域。
+   *
+   * 用户筛选用于缩小受影响公司范围，平台作用域始终纳入检查。
+   * @returns 待检查的作用域 scopes 与仍有有效管理员的作用域 effective。
+   */
+  async effectiveAdministratorScopes(
+    db: AccessDb,
+    options: {
+      companyId?: string
+      projectId?: string
+      userId?: string
+      platformOnly?: boolean
+    } = {},
+  ) {
+    const scopes: AccessScope[] = [{ type: 'platform' }]
+    if (!options.platformOnly) {
+      const affected = options.userId
+        ? await db.select().from(companyMembers).where(eq(companyMembers.userId, options.userId))
+        : null
+      const activeCompanies = await db
+        .select()
+        .from(companies)
+        .where(
+          and(
+            eq(companies.status, 'active'),
+            options.companyId ? eq(companies.id, options.companyId) : undefined,
+          ),
+        )
+      for (const company of activeCompanies.filter(
+        (c) => !affected || affected.some((m) => m.companyId === c.id),
+      )) {
+        if (!options.projectId) scopes.push({ type: 'company', companyId: company.id })
+        const activeProjects = await db
+          .select()
+          .from(projects)
+          .where(
+            and(
+              eq(projects.companyId, company.id),
+              eq(projects.status, 'active'),
+              options.projectId ? eq(projects.id, options.projectId) : undefined,
+            ),
+          )
+        for (const project of activeProjects)
+          scopes.push({ type: 'project', companyId: company.id, projectId: project.id })
+      }
+    }
+    const effective: AccessScope[] = []
+    for (const scope of scopes) if (await this.hasAdministrator(db, scope)) effective.push(scope)
+    return { scopes, effective }
+  }
+  /**
+   * 确保需要保留的作用域仍有有效管理员，防止成员或角色变更移除最后一位管理员。
+   *
+   * @param options - 可提供变更前的作用域快照 previous；未提供时检查当前全部候选作用域。
+   * @throws 任一目标作用域失去有效管理员时抛出 LAST_ADMINISTRATOR。
+   */
+  async assertAdministrators(
+    db: AccessDb,
+    options: {
+      companyId?: string
+      projectId?: string
+      userId?: string
+      platformOnly?: boolean
+      previous?: AccessScope[]
+    } = {},
+  ) {
+    const state = await this.effectiveAdministratorScopes(db, options)
+    const expected = options.previous ?? state.scopes
+    for (const scope of expected) {
+      if (!state.effective.some((current) => JSON.stringify(current) === JSON.stringify(scope)))
+        throw new AppException(ACCESS_ERRORS.LAST_ADMINISTRATOR)
+    }
+  }
+
+  /**
+   * 验证操作者、作用域和成员状态，并结合角色授权与启用菜单计算有效权限。
+   *
+   * 公司管理员可继承项目管理权限；操作权限还要求所属页面权限同时有效。
+   * 要求多个权限时，满足其中任意一个即可通过；adminOnly 额外要求管理员身份。
+   * @returns 已验证的用户、管理员身份、权限键及完整菜单树和版本。
+   */
+  async authorize(db: AccessDb, requirement: AccessRequirement): Promise<VerifiedAccess> {
+    const { actor, scope } = requirement
+    const [user] = await db
+      .select({ id: users.id, name: users.name, account: users.account, status: users.status })
+      .from(users)
+      .where(eq(users.id, actor.userId))
+    if (!user || user.status !== 'active') throw new AppException(AUTH_ERRORS.SESSION_INVALID)
+    const assignments = await this.roleAssignments(db, scope, user.id)
+    let administrator: ScopeType | null = assignments.some(
+      ({ role }) => role.builtin === 'administrator',
+    )
+      ? scope.type
+      : null
+    if (scope.type === 'platform') {
+      if (!assignments.length) throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+    } else {
+      const [company] = await db.select().from(companies).where(eq(companies.id, scope.companyId))
+      const [member] = await db
+        .select()
+        .from(companyMembers)
+        .where(
+          and(eq(companyMembers.companyId, scope.companyId), eq(companyMembers.userId, user.id)),
+        )
+      if (!company || !member) throw new AppException(ACCESS_ERRORS.NOT_FOUND)
+      if (company.status !== 'active' || member.status !== 'active')
+        throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+      if (scope.type === 'project') {
+        const [project] = await db
+          .select()
+          .from(projects)
+          .where(and(eq(projects.companyId, scope.companyId), eq(projects.id, scope.projectId)))
+        const companyAdmin = await this.isAdministrator(
+          db,
+          { type: 'company', companyId: scope.companyId },
+          user.id,
+        )
+        const [projectMember] = await db
+          .select()
+          .from(projectMembers)
+          .where(
+            and(
+              eq(projectMembers.companyId, scope.companyId),
+              eq(projectMembers.projectId, scope.projectId),
+              eq(projectMembers.userId, user.id),
+            ),
+          )
+        if (!project || (!companyAdmin && !projectMember))
+          throw new AppException(ACCESS_ERRORS.NOT_FOUND)
+        if (project.status !== 'active' || (!companyAdmin && projectMember?.status !== 'active'))
+          throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+        if (companyAdmin) administrator = 'company'
+      }
+    }
+    const catalog = FUNCTION_CATALOG.filter((p) => p.scopeType === scope.type && !p.deprecated)
+    const grants = assignments.length
+      ? await db
+          .select()
+          .from(rolePermissions)
+          .where(
+            inArray(
+              rolePermissions.roleId,
+              assignments.map(({ role }) => role.id),
+            ),
+          )
+      : []
+    const granted = new Set(
+      administrator ? catalog.map((p) => p.key) : grants.map((g) => g.permissionKey),
+    )
+    const menuRows = await db.select().from(menus).where(eq(menus.scopeType, scope.type))
+    const byId = new Map(menuRows.map((m) => [m.id, m]))
+    /** 沿菜单父链检查启用状态，遇到停用节点或循环引用时判定该菜单无效。 */
+    const enabled = (id: string): boolean => {
+      const visited = new Set<string>()
+      let node = byId.get(id)
+      while (node) {
+        if (visited.has(node.id) || node.status !== 'active') return false
+        visited.add(node.id)
+        node = node.parentId ? byId.get(node.parentId) : undefined
+      }
+      return true
+    }
+    const enabledKeys = new Set(
+      menuRows.filter((m) => m.permissionKey && enabled(m.id)).map((m) => m.permissionKey),
+    )
+    const permissionKeys = catalog
+      .filter(
+        (p) =>
+          granted.has(p.key) &&
+          enabledKeys.has(p.key) &&
+          (!p.pagePermissionKey ||
+            (granted.has(p.pagePermissionKey) && enabledKeys.has(p.pagePermissionKey))),
+      )
+      .map((p) => p.key)
+    if (requirement.adminOnly && !administrator) throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+    const needed =
+      typeof requirement.permission === 'string' ? [requirement.permission] : requirement.permission
+    if (needed && !needed.some((key) => permissionKeys.includes(key)))
+      throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+    const [version] = await db
+      .select()
+      .from(menuVersions)
+      .where(eq(menuVersions.scopeType, scope.type))
+    return {
+      user: { id: user.id, name: user.name, account: user.account },
+      scope,
+      administrator,
+      permissionKeys,
+      menuVersion: version?.version ?? 1,
+      allMenus: this.tree(menuRows),
+    }
+  }
+
+  /**
+   * 将菜单平铺记录递归组装为树，同级按 sort 和标识稳定排序。
+   *
+   * @param rows - 父子关系已经过校验的菜单记录。
+   */
+  tree(rows: Omit<MenuNode, 'children'>[]): MenuNode[] {
+    /** 递归构造指定父节点下的有序子树，null 表示从根菜单开始。 */
+    const build = (parentId: string | null): MenuNode[] =>
+      rows
+        .filter((m) => m.parentId === parentId)
+        .sort((a, b) => a.sort - b.sort || a.id.localeCompare(b.id))
+        .map((m) => ({
+          id: m.id,
+          scopeType: m.scopeType,
+          parentId: m.parentId,
+          type: m.type,
+          name: m.name,
+          icon: m.icon,
+          sort: m.sort,
+          hidden: m.hidden,
+          status: m.status,
+          routeKey: m.routeKey,
+          permissionKey: m.permissionKey,
+          protected: m.protected,
+          children: build(m.id),
+        }))
+    return build(null)
+  }
+
+  /**
+   * 生成客户端访问上下文，递归剔除停用、隐藏、无权限菜单及空目录。
+   *
+   * 完整有效权限键仍保留，用于页面操作鉴权和客户端权限判断。
+   */
+  context(access: VerifiedAccess): AccessContext {
+    /** 递归筛选当前用户可见的菜单，并移除过滤后不再包含子节点的目录。 */
+    const filter = (nodes: MenuNode[]): MenuNode[] =>
+      nodes
+        .filter(
+          (m) =>
+            m.status === 'active' &&
+            !m.hidden &&
+            (!m.permissionKey || access.permissionKeys.includes(m.permissionKey)),
+        )
+        .map((m) => ({ ...m, children: filter(m.children) }))
+        .filter((m) => m.type !== 'directory' || m.children.length > 0)
+    return {
+      user: access.user,
+      scope: access.scope,
+      administrator: access.administrator,
+      permissionKeys: access.permissionKeys,
+      menus: filter(access.allMenus),
+      menuVersion: access.menuVersion,
+      catalogVersion: CATALOG_VERSION,
+    }
+  }
+
+  /**
+   * 在可重复读的只读事务中先校验权限，再执行查询，保证权限与业务数据来自同一快照。
+   *
+   * @param operation - 接收当前事务和已验证访问上下文的查询。
+   * @returns 查询的返回结果。
+   */
+  read<T>(
+    requirement: AccessRequirement,
+    operation: (tx: AccessTx, access: VerifiedAccess) => Promise<T>,
+  ) {
+    return this.db.transaction(async (tx) => operation(tx, await this.authorize(tx, requirement)), {
+      isolationLevel: 'repeatable read',
+      accessMode: 'read only',
+    })
+  }
+  /**
+   * 在事务中获取权限写锁并重新鉴权，再执行业务变更；异常时回滚数据库修改。
+   *
+   * @param operation - 接收当前事务和已验证访问上下文的写操作。
+   * @returns 写操作的返回结果。
+   */
+  write<T>(
+    requirement: AccessRequirement,
+    operation: (tx: AccessTx, access: VerifiedAccess) => Promise<T>,
+  ) {
+    return this.db.transaction(async (tx) => {
+      await lockAccess(tx)
+      return operation(tx, await this.authorize(tx, requirement))
+    })
+  }
+  /**
+   * 在业务事务内写入审计记录，保存操作者快照、访问作用域及变更摘要。
+   *
+   * 请求标识最多保留 128 个字符；审计记录随业务事务一同提交或回滚。
+   */
+  async audit(
+    tx: AccessTx,
+    input: {
+      actor: AccessActor
+      access: VerifiedAccess
+      action: string
+      objectType: string
+      objectId: string
+      summary?: AuditRecord['summary']
+    },
+  ) {
+    await tx.insert(auditLogs).values({
+      ...scopeColumns(input.access.scope),
+      actorUserId: input.access.user.id,
+      actorAccount: input.access.user.account,
+      actorName: input.access.user.name,
+      action: input.action,
+      objectType: input.objectType,
+      objectId: input.objectId,
+      summary: input.summary ?? {},
+      requestId: input.actor.requestId.slice(0, 128),
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/access.store.ts

@@ -0,0 +1,68 @@
+import type { DrizzleDB } from '@/database/db.module'
+import { and, eq, ilike, isNull, or, sql, type SQLWrapper } from 'drizzle-orm'
+import { roles } from '@/database/schema'
+import type { AccessScope, PageQuery } from 'shared/types'
+import { AppException } from '@/common/exceptions/app.exception'
+import { ACCESS_ERRORS } from './access.errors'
+
+export type AccessTx = Parameters<Parameters<DrizzleDB['transaction']>[0]>[0]
+export type AccessDb = DrizzleDB | AccessTx
+/** 获取权限域的 PostgreSQL 事务级咨询锁，串行化权限相关写操作，事务结束时自动释放。 */
+export const lockAccess = (tx: AccessTx) => tx.execute(sql`select pg_advisory_xact_lock(7421, 1)`)
+/** 将访问作用域转换为数据库列，未适用的公司或项目标识写为 null。 */
+export const scopeColumns = (scope: AccessScope) => ({
+  scopeType: scope.type,
+  companyId: scope.type === 'platform' ? null : scope.companyId,
+  projectId: scope.type === 'project' ? scope.projectId : null,
+})
+/** 构造角色表的精确作用域条件，使用空值约束隔离平台、公司和项目角色。 */
+export const scopeFilter = (scope: AccessScope) =>
+  and(
+    eq(roles.scopeType, scope.type),
+    scope.type === 'platform' ? isNull(roles.companyId) : eq(roles.companyId, scope.companyId),
+    scope.type === 'project' ? eq(roles.projectId, scope.projectId) : isNull(roles.projectId),
+  )
+/** 将数据库中的作用域列还原为访问作用域对象，依赖行数据满足作用域完整性约束。 */
+export const toScope = (row: {
+  scopeType: 'platform' | 'company' | 'project'
+  companyId: string | null
+  projectId: string | null
+}): AccessScope =>
+  row.scopeType === 'platform'
+    ? { type: 'platform' }
+    : row.scopeType === 'company'
+      ? { type: 'company', companyId: row.companyId! }
+      : { type: 'project', companyId: row.companyId!, projectId: row.projectId! }
+/** 要求资源存在并返回原值；查询未命中时抛出统一资源不存在异常。 */
+export function requireFound<T>(value: T | undefined | null): T {
+  if (!value) throw new AppException(ACCESS_ERRORS.NOT_FOUND)
+  return value
+}
+/**
+ * 比较数据库版本与客户端预期版本，阻止过期数据覆盖后续修改。
+ *
+ * @throws 版本不一致时抛出版本冲突异常。
+ */
+export function checkVersion(actual: number, expected: number) {
+  if (actual !== expected) throw new AppException(ACCESS_ERRORS.VERSION_CONFLICT)
+}
+/**
+ * 构造多列忽略大小写的包含搜索条件，并转义关键词中的 SQL 通配符。
+ *
+ * @returns 各列之间以 OR 连接的条件；没有关键词时返回 undefined。
+ */
+export function searchSql(columns: SQLWrapper[], query?: string) {
+  return query
+    ? or(...columns.map((column) => ilike(sql`${column}`, `%${query.replace(/[\\%_]/g, '\\$&')}%`)))
+    : undefined
+}
+/**
+ * 根据分页参数计算查询窗口，缺省使用第 1 页、每页 20 条。
+ *
+ * @returns 页码、每页数量及数据库查询偏移量。
+ */
+export function pageWindow(query: PageQuery) {
+  const page = query.page ?? 1
+  const pageSize = query.pageSize ?? 20
+  return { page, pageSize, offset: (page - 1) * pageSize }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/access.validation.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+import { ZodValidationException } from 'nestjs-zod'
+
+export const idSchema = z.uuid()
+export const versionSchema = z.number().int().positive()
+export const accountSchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .regex(/^[a-z0-9_]{4,32}$/)
+export const nameSchema = z.string().trim().min(2).max(100)
+export const descriptionSchema = z.string().trim().max(500)
+export const roleIdsSchema = z
+  .array(idSchema)
+  .max(500)
+  .refine((a) => new Set(a).size === a.length)
+export const permissionKeysSchema = z
+  .array(z.string().min(1).max(150))
+  .max(500)
+  .refine((a) => new Set(a).size === a.length)
+export const scopeTypeSchema = z.enum(['platform', 'company', 'project'])
+export const pageSchema = z.strictObject({
+  page: z.coerce.number().int().positive().default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(20),
+  query: z.string().trim().max(100).optional(),
+})
+export const entityListSchema = pageSchema.extend({
+  status: z.enum(['active', 'disabled']).optional(),
+})
+export const statusSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  status: z.enum(['active', 'disabled']),
+})
+export const deleteSchema = z.strictObject({ expectedVersion: z.coerce.number().int().positive() })
+/**
+ * 按照给定 Zod 规则校验并转换请求数据，将失败结果交给统一参数异常处理。
+ *
+ * @returns 通过校验且已应用默认值、规范化等转换的数据。
+ */
+export function parse<T>(schema: z.ZodType<T>, input: unknown): T {
+  const result = schema.safeParse(input)
+  if (!result.success) throw new ZodValidationException(result.error)
+  return result.data
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/maintenance/permissions-cleanup.controller.ts

@@ -0,0 +1,27 @@
+import { Body, Controller, Get, HttpCode, Post, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { actor } from '../access-http'
+import { parse } from '../access.validation'
+import { PermissionsCleanupService } from './permissions-cleanup.service'
+import { cleanupSchema } from './permissions-cleanup.validation'
+
+@Controller('platform/permissions')
+export class PermissionsCleanupController {
+  constructor(private readonly cleanup: PermissionsCleanupService) {}
+
+  /** 向具备清理权限的平台管理员返回废弃权限清理预览及部署证明摘要。 */
+  @Get('cleanup-preview')
+  @AccessPolicy({ scope: 'platform', permission: 'platform.menus.cleanup', adminOnly: true })
+  preview(@Req() req: FastifyRequest) {
+    return this.cleanup.preview(actor(req))
+  }
+
+  /** 校验权限键和部署证明摘要，执行平台管理员确认的废弃权限清理。 */
+  @Post('cleanup')
+  @HttpCode(200)
+  @AccessPolicy({ scope: 'platform', permission: 'platform.menus.cleanup', adminOnly: true })
+  execute(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.cleanup.cleanup(actor(req), parse(cleanupSchema, body))
+  }
+}