create-bubbles 0.1.26 → 0.1.28

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

@@ -0,0 +1,260 @@
+import { Injectable } from '@nestjs/common'
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { z } from 'zod'
+import { eq, inArray, sql } from 'drizzle-orm'
+import {
+  cleanupTombstones,
+  menus,
+  menuVersions,
+  permissions,
+  rolePermissions,
+  roles,
+} from '@/database/schema'
+import type { CleanupPreview, CleanupRequest, CleanupResult } from 'shared/types'
+import { ACCESS_CATALOG_VERSION, ACCESS_PERMISSION_CATALOG } from 'shared/utils'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AccessService, type AccessActor } from '../access.service'
+import { ACCESS_ERRORS } from '../access.errors'
+import type { AccessDb } from '../access.store'
+
+const proofSchema = z.strictObject({
+  deploymentId: z.string().min(1).max(150),
+  completed: z.literal(true),
+  verifiedAt: z.iso.datetime(),
+  expiresAt: z.iso.datetime(),
+  serviceVersions: z
+    .array(
+      z.strictObject({
+        version: z.string().min(1),
+        instanceIds: z.array(z.string().min(1)).min(1),
+        requiredPermissionKeys: z.array(z.string().min(1)),
+      }),
+    )
+    .min(1),
+})
+@Injectable()
+export class PermissionsCleanupService {
+  constructor(private readonly access: AccessService) {}
+  /**
+   * 读取并验证部署证明的时间窗口、服务版本、实例唯一性及当前权限目录完整性。
+   *
+   * @returns 有效证明及原文件 SHA-256 摘要；证明缺失、格式无效或校验未通过时返回 null。
+   * 未知文件读取异常继续上抛，交给全局异常处理。
+   */
+  async proof() {
+    const path = process.env.ACCESS_DEPLOYMENT_PROOF_FILE
+    if (!path) return null
+    // 证明缺失/格式失效是明确的维护阻断，不能降级为允许清理。
+    try {
+      const raw = await readFile(path, 'utf8')
+      const proof = proofSchema.parse(JSON.parse(raw))
+      const now = Date.now()
+      if (
+        Date.parse(proof.verifiedAt) > now ||
+        Date.parse(proof.expiresAt) <= now ||
+        Date.parse(proof.expiresAt) - Date.parse(proof.verifiedAt) > 86_400_000
+      )
+        return null
+      const versions = proof.serviceVersions.map((v) => v.version)
+      const instances = proof.serviceVersions.flatMap((v) => v.instanceIds)
+      if (
+        new Set(versions).size !== versions.length ||
+        new Set(instances).size !== instances.length
+      )
+        return null
+      const current = proof.serviceVersions.find(
+        (v) => v.version === (process.env.ACCESS_RELEASE_VERSION ?? ACCESS_CATALOG_VERSION),
+      )
+      const expected = ACCESS_PERMISSION_CATALOG.filter((p) => !p.deprecated)
+        .map((p) => p.key)
+        .sort()
+      if (
+        !current ||
+        JSON.stringify([...current.requiredPermissionKeys].sort()) !== JSON.stringify(expected)
+      )
+        return null
+      if (
+        proof.serviceVersions.some(
+          (v) =>
+            new Set(v.requiredPermissionKeys).size !== v.requiredPermissionKeys.length ||
+            v.requiredPermissionKeys.some(
+              (k) => !ACCESS_PERMISSION_CATALOG.some((p) => p.key === k),
+            ),
+        )
+      )
+        return null
+      return { proof, digest: createHash('sha256').update(raw).digest('hex') }
+    } catch (error) {
+      if (
+        error instanceof SyntaxError ||
+        error instanceof z.ZodError ||
+        (error instanceof Error &&
+          'code' in error &&
+          ['ENOENT', 'EACCES'].includes(String(error.code)))
+      )
+        return null
+      throw error
+    }
+  }
+  /**
+   * 检查尚未清理的废弃权限及其菜单、角色引用，汇总部署依赖与结构上的清理阻断原因。
+   *
+   * @returns 只读清理预览，包含证明摘要、候选项、阻断原因和预计移除数量。
+   */
+  async inspect(db: AccessDb): Promise<CleanupPreview> {
+    const proof = await this.proof()
+    const tombstones = new Set(
+      (await db.select().from(cleanupTombstones)).map((t) => t.permissionKey),
+    )
+    const candidates = ACCESS_PERMISSION_CATALOG.filter(
+      (p) => p.deprecated && !tombstones.has(p.key),
+    )
+    const rows = await db.select().from(menus)
+    const grants = await db.select().from(rolePermissions)
+    const candidateKeys = new Set(candidates.map((p) => p.key))
+    /** 汇总单个废弃权限的菜单、授权引用及部署阻断原因，供清理确认使用。 */
+    const items = candidates.map((p) => {
+      const bound = rows.filter((m) => m.permissionKey === p.key)
+      const blockedReasons: string[] = []
+      if (bound.some((m) => m.status === 'active')) blockedReasons.push('功能尚未停用')
+      if (bound.some((m) => m.protected)) blockedReasons.push('属于受保护管理入口')
+      /** 递归判断菜单是否包含不在本轮废弃候选集合中的后代，避免清理时误删保留节点。 */
+      const hasActiveDescendant = (id: string): boolean =>
+        rows
+          .filter((m) => m.parentId === id)
+          .some(
+            (m) =>
+              !m.permissionKey || !candidateKeys.has(m.permissionKey) || hasActiveDescendant(m.id),
+          )
+      if (bound.some((m) => hasActiveDescendant(m.id))) blockedReasons.push('存在非废弃子节点')
+      if (proof?.proof.serviceVersions.some((v) => v.requiredPermissionKeys.includes(p.key)))
+        blockedReasons.push('在用服务版本仍依赖此权限')
+      return {
+        permissionKey: p.key,
+        title: p.title,
+        menuIds: bound.map((m) => m.id),
+        roleCount: grants.filter((g) => g.permissionKey === p.key).length,
+        blockedReasons,
+      }
+    })
+    const blockedReasons = proof ? [] : ['缺少有效且完整的部署证明']
+    return {
+      catalogVersion: ACCESS_CATALOG_VERSION,
+      deploymentId: proof?.proof.deploymentId ?? null,
+      proofDigest: proof?.digest ?? null,
+      eligible:
+        items.length > 0 && !blockedReasons.length && items.every((i) => !i.blockedReasons.length),
+      blockedReasons,
+      items,
+      totals: {
+        permissions: items.length,
+        menus: items.reduce((n, i) => n + i.menuIds.length, 0),
+        roleAssignments: items.reduce((n, i) => n + i.roleCount, 0),
+      },
+    }
+  }
+  /** 要求平台管理员具备清理权限，在只读事务内生成废弃权限清理预览。 */
+  preview(actor: AccessActor) {
+    return this.access.read(
+      { actor, scope: { type: 'platform' }, permission: 'platform.menus.cleanup', adminOnly: true },
+      (tx) => this.inspect(tx),
+    )
+  }
+  /**
+   * 在权限写锁保护下复核部署证明和引用关系，清理指定废弃权限及其菜单、角色授权。
+   *
+   * 写入清理墓碑以保证重复请求幂等，递增受影响版本并记录审计；任何阻断均使事务回滚。
+   * @param body - 待清理权限键及用户预览时确认的部署证明摘要。
+   * @returns 实际移除和此前已清理的权限键，以及受影响菜单、角色授权数量。
+   */
+  cleanup(actor: AccessActor, body: CleanupRequest) {
+    return this.access.write(
+      { actor, scope: { type: 'platform' }, permission: 'platform.menus.cleanup', adminOnly: true },
+      /** 在锁内复核证明和清理范围，按叶节点顺序删除菜单并同步版本、墓碑和审计。 */
+      async (tx, access): Promise<CleanupResult> => {
+        const preview = await this.inspect(tx)
+        if (preview.proofDigest !== body.proofDigest || preview.blockedReasons.length)
+          throw new AppException(ACCESS_ERRORS.CLEANUP_BLOCKED)
+        const cleaned = new Set(
+          (await tx.select().from(cleanupTombstones)).map((t) => t.permissionKey),
+        )
+        const requested = body.permissionKeys.filter((k) => !cleaned.has(k))
+        for (const key of requested) {
+          const item = preview.items.find((i) => i.permissionKey === key)
+          if (!item || item.blockedReasons.length)
+            throw new AppException(ACCESS_ERRORS.CLEANUP_BLOCKED)
+        }
+        const rows = requested.length
+          ? await tx.select().from(menus).where(inArray(menus.permissionKey, requested))
+          : []
+        const allRows = await tx.select().from(menus)
+        if (
+          rows.some((row) =>
+            allRows.some(
+              (child) => child.parentId === row.id && !rows.some((r) => r.id === child.id),
+            ),
+          )
+        )
+          throw new AppException(ACCESS_ERRORS.RESOURCE_IN_USE)
+        const grants = requested.length
+          ? await tx
+              .select()
+              .from(rolePermissions)
+              .where(inArray(rolePermissions.permissionKey, requested))
+          : []
+        if (requested.length) {
+          if (grants.length)
+            await tx
+              .update(roles)
+              .set({ version: sql`${roles.version} + 1`, updatedAt: new Date() })
+              .where(inArray(roles.id, [...new Set(grants.map((g) => g.roleId))]))
+          await tx.delete(rolePermissions).where(inArray(rolePermissions.permissionKey, requested))
+          const remaining = [...rows]
+          while (remaining.length) {
+            const leaf = remaining.find((r) => !remaining.some((child) => child.parentId === r.id))
+            if (!leaf) throw new AppException(ACCESS_ERRORS.RESOURCE_IN_USE)
+            await tx.delete(menus).where(eq(menus.id, leaf.id))
+            remaining.splice(remaining.indexOf(leaf), 1)
+          }
+          await tx.delete(permissions).where(inArray(permissions.key, requested))
+          await tx.insert(cleanupTombstones).values(
+            requested.map((permissionKey) => ({
+              permissionKey,
+              deploymentId: preview.deploymentId!,
+            })),
+          )
+          const scopes = [
+            ...new Set(
+              ACCESS_PERMISSION_CATALOG.filter((p) => requested.includes(p.key)).map(
+                (p) => p.scopeType,
+              ),
+            ),
+          ]
+          await tx
+            .update(menuVersions)
+            .set({ version: sql`${menuVersions.version} + 1` })
+            .where(inArray(menuVersions.scopeType, scopes))
+          await this.access.audit(tx, {
+            actor,
+            access,
+            action: 'permission.cleanup',
+            objectType: 'permission',
+            objectId: preview.deploymentId!,
+            summary: {
+              permissionKeys: requested,
+              removedMenus: rows.length,
+              removedRoleAssignments: grants.length,
+            },
+          })
+        }
+        return {
+          removedPermissionKeys: requested,
+          alreadyCleanedPermissionKeys: body.permissionKeys.filter((k) => cleaned.has(k)),
+          removedMenuCount: rows.length,
+          removedRoleAssignmentCount: grants.length,
+        }
+      },
+    )
+  }
+}

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

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+import { permissionKeysSchema } from '../access.validation'
+
+export const cleanupSchema = z.strictObject({
+  permissionKeys: permissionKeysSchema.min(1),
+  proofDigest: z.string().regex(/^[a-f0-9]{64}$/),
+})

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

@@ -0,0 +1,80 @@
+import { Body, Controller, Delete, Get, Patch, Post, Put, Query, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { RolesService } from './roles.service'
+import { actor, ids, scopeFor } from '../access-http'
+import { deleteSchema, pageSchema, parse } from '../access.validation'
+import { createRoleSchema, permissionsSchema, updateRoleSchema } from './roles.validation'
+
+@Controller(['platform', 'companies/:companyId', 'companies/:companyId/projects/:projectId'])
+export class RolesController {
+  constructor(private readonly roles: RolesService) {}
+  /** 校验分页查询参数，按路由作用域返回可读取的角色列表。 */
+  @Get('roles')
+  @AccessPolicy({ scope: 'route' })
+  list(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.roles.list({
+      actor: actor(req),
+      scope: scopeFor(req),
+      query: parse(pageSchema, query),
+    })
+  }
+  /** 校验路由标识，读取当前作用域中的指定角色详情。 */
+  @Get('roles/:roleId')
+  @AccessPolicy({ scope: 'route' })
+  get(@Req() req: FastifyRequest) {
+    return this.roles.get({ actor: actor(req), scope: scopeFor(req), roleId: ids(req).roleId! })
+  }
+  /** 按路由作用域获取角色授权页面所需的权限树和可授权权限键。 */
+  @Get('permissions')
+  @AccessPolicy({ scope: 'route' })
+  permissions(@Req() req: FastifyRequest) {
+    return this.roles.permissions({ actor: actor(req), scope: scopeFor(req) })
+  }
+  /** 校验创建请求并在路由对应作用域创建自定义角色。 */
+  @Post('roles')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.roles.create' })
+  create(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.roles.create({
+      actor: actor(req),
+      scope: scopeFor(req),
+      body: parse(createRoleSchema, body),
+    })
+  }
+  /** 校验角色标识、预期版本和资料字段，提交当前作用域的角色更新。 */
+  @Patch('roles/:roleId')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.roles.update' })
+  update(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.roles.change({
+      actor: actor(req),
+      scope: scopeFor(req),
+      roleId: ids(req).roleId!,
+      action: 'update',
+      body: parse(updateRoleSchema, body),
+    })
+  }
+  /** 校验预期版本与权限键集合，提交当前作用域的角色权限全量替换。 */
+  @Put('roles/:roleId/permissions')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.roles.permissions' })
+  permissionsUpdate(@Req() req: FastifyRequest, @Body() body: unknown) {
+    return this.roles.change({
+      actor: actor(req),
+      scope: scopeFor(req),
+      roleId: ids(req).roleId!,
+      action: 'permissions',
+      body: parse(permissionsSchema, body),
+    })
+  }
+  /** 从查询参数校验预期版本，提交当前作用域的自定义角色删除。 */
+  @Delete('roles/:roleId')
+  @AccessPolicy({ scope: 'route', permission: '{scope}.roles.delete' })
+  remove(@Req() req: FastifyRequest, @Query() query: unknown) {
+    return this.roles.change({
+      actor: actor(req),
+      scope: scopeFor(req),
+      roleId: ids(req).roleId!,
+      action: 'delete',
+      body: parse(deleteSchema, query),
+    })
+  }
+}

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

@@ -0,0 +1,249 @@
+import { Injectable } from '@nestjs/common'
+import { and, count, desc, eq, sql } from 'drizzle-orm'
+import { rolePermissions, roles, userRoles } from '@/database/schema'
+import type {
+  AccessScope,
+  CreateRoleRequest,
+  PageQuery,
+  PermissionTreeResult,
+  RoleRecord,
+  SetRolePermissionsRequest,
+  UpdateRoleRequest,
+} from 'shared/types'
+import { ACCESS_CATALOG_VERSION, ACCESS_PERMISSION_CATALOG } from 'shared/utils'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AccessService, type AccessActor, type VerifiedAccess } from '../access.service'
+import { ACCESS_ERRORS } from '../access.errors'
+import {
+  checkVersion,
+  pageWindow,
+  requireFound,
+  scopeColumns,
+  scopeFilter,
+  searchSql,
+  toScope,
+  type AccessDb,
+  type AccessTx,
+} from '../access.store'
+
+@Injectable()
+export class RolesService {
+  constructor(private readonly access: AccessService) {}
+  /** 返回角色读取允许的权限集合，同时支持角色管理和成员角色分配界面读取角色。 */
+  readPermissions(scope: AccessScope) {
+    return [
+      `${scope.type}.roles.read`,
+      scope.type === 'platform' ? 'platform.accounts.roles' : `${scope.type}.members.roles`,
+    ]
+  }
+  /**
+   * 读取当前作用域的角色详情，聚合权限、成员数量并计算操作者是否可以分配该角色。
+   *
+   * 管理员角色仅允许管理员分配，其他角色的权限不得超出操作者有效权限。
+   */
+  async record(db: AccessDb, access: VerifiedAccess, id: string): Promise<RoleRecord> {
+    const [row] = await db
+      .select()
+      .from(roles)
+      .where(and(scopeFilter(access.scope), eq(roles.id, id)))
+    const role = requireFound(row)
+    const grants = await db
+      .select()
+      .from(rolePermissions)
+      .where(eq(rolePermissions.roleId, role.id))
+    const members = await db.select().from(userRoles).where(eq(userRoles.roleId, role.id))
+    const permissionKeys = grants.map((p) => p.permissionKey)
+    return {
+      id: role.id,
+      name: role.name,
+      description: role.description,
+      scope: toScope(role),
+      builtin: role.builtin,
+      permissionKeys,
+      version: role.version,
+      memberCount: members.length,
+      assignable:
+        role.builtin === 'administrator'
+          ? !!access.administrator
+          : permissionKeys.every((p) => access.permissionKeys.includes(p)),
+      createdAt: role.createdAt.toISOString(),
+      updatedAt: role.updatedAt.toISOString(),
+    }
+  }
+  /**
+   * 校验角色权限属于当前作用域且可授权，并确保页面依赖完整、未超过操作者权限。
+   *
+   * 管理员专属或已废弃权限不可写入自定义角色。
+   */
+  validatePermissions(access: VerifiedAccess, keys: string[]) {
+    for (const key of keys) {
+      const p = ACCESS_PERMISSION_CATALOG.find((p) => p.key === key)
+      if (
+        !p ||
+        p.scopeType !== access.scope.type ||
+        p.adminOnly ||
+        p.deprecated ||
+        (p.pagePermissionKey && !keys.includes(p.pagePermissionKey))
+      )
+        throw new AppException(ACCESS_ERRORS.INVALID_PERMISSION_SET)
+      if (!access.permissionKeys.includes(key)) throw new AppException(ACCESS_ERRORS.FORBIDDEN)
+    }
+  }
+  /** 在当前事务内全量替换角色权限；调用方负责校验权限集合并维护角色版本。 */
+  async replacePermissions(tx: AccessTx, roleId: string, permissionKeys: string[]) {
+    await tx.delete(rolePermissions).where(eq(rolePermissions.roleId, roleId))
+    if (permissionKeys.length)
+      await tx
+        .insert(rolePermissions)
+        .values(permissionKeys.map((permissionKey) => ({ roleId, permissionKey })))
+  }
+  /** 校验角色读取权限后，按名称分页查询当前作用域角色及其可分配状态。 */
+  list(input: { actor: AccessActor; scope: AccessScope; query: PageQuery }) {
+    return this.access.read(
+      { ...input, permission: this.readPermissions(input.scope) },
+      /** 在同一快照内计算角色总数、读取当前页并聚合角色授权详情。 */
+      async (tx, access) => {
+        const { page, pageSize, offset } = pageWindow(input.query)
+        const condition = and(scopeFilter(input.scope), searchSql([roles.name], input.query.query))
+        const [total] = await tx.select({ value: count() }).from(roles).where(condition)
+        const selected = await tx
+          .select()
+          .from(roles)
+          .where(condition)
+          .orderBy(desc(roles.createdAt), desc(roles.id))
+          .limit(pageSize)
+          .offset(offset)
+        return {
+          page,
+          pageSize,
+          total: total!.value,
+          items: await Promise.all(selected.map((r) => this.record(tx, access, r.id))),
+        }
+      },
+    )
+  }
+  /** 校验角色读取权限后，返回当前作用域内指定角色的完整记录。 */
+  get(input: { actor: AccessActor; scope: AccessScope; roleId: string }) {
+    return this.access.read(
+      { ...input, permission: this.readPermissions(input.scope) },
+      (tx, access) => this.record(tx, access, input.roleId),
+    )
+  }
+  /** 返回作用域的菜单树、权限目录及操作者可授予的权限键，供角色授权界面使用。 */
+  permissions(input: { actor: AccessActor; scope: AccessScope }) {
+    return this.access.read(
+      { ...input, permission: this.readPermissions(input.scope) },
+      async (_tx, access): Promise<PermissionTreeResult> => ({
+        catalogVersion: ACCESS_CATALOG_VERSION,
+        items: access.allMenus,
+        permissions: ACCESS_PERMISSION_CATALOG.filter((p) => p.scopeType === input.scope.type).map(
+          (p) => ({ ...p }),
+        ),
+        grantablePermissionKeys: ACCESS_PERMISSION_CATALOG.filter(
+          (p) =>
+            p.scopeType === input.scope.type &&
+            !p.adminOnly &&
+            !p.deprecated &&
+            access.permissionKeys.includes(p.key),
+        ).map((p) => p.key),
+      }),
+    )
+  }
+  /** 验证权限集合与名称唯一性后创建自定义角色，写入权限和审计记录并返回角色详情。 */
+  create(input: { actor: AccessActor; scope: AccessScope; body: CreateRoleRequest }) {
+    return this.access.write(
+      { ...input, permission: `${input.scope.type}.roles.create` },
+      /** 将名称检查、角色创建、权限绑定和审计写入作为一个原子操作。 */
+      async (tx, access) => {
+        this.validatePermissions(access, input.body.permissionKeys ?? [])
+        const [existing] = await tx
+          .select()
+          .from(roles)
+          .where(and(scopeFilter(input.scope), eq(roles.name, input.body.name)))
+        if (existing) throw new AppException(ACCESS_ERRORS.DUPLICATE_RESOURCE)
+        const [role] = await tx
+          .insert(roles)
+          .values({
+            ...scopeColumns(input.scope),
+            name: input.body.name,
+            description: input.body.description ?? '',
+          })
+          .returning()
+        await this.replacePermissions(tx, role!.id, input.body.permissionKeys ?? [])
+        await this.access.audit(tx, {
+          ...input,
+          access,
+          action: 'role.create',
+          objectType: 'role',
+          objectId: role!.id,
+          summary: { permissionKeys: input.body.permissionKeys ?? [] },
+        })
+        return this.record(tx, access, role!.id)
+      },
+    )
+  }
+  /**
+   * 按操作类型修改、替换权限或删除自定义角色，并校验权限、版本与资源引用。
+   *
+   * 内置角色不可修改；已分配给成员的角色不可删除。成功后记录审计，修改时递增版本。
+   * @returns 删除标记或变更后的角色详情。
+   */
+  change(input: {
+    actor: AccessActor
+    scope: AccessScope
+    roleId: string
+    body: UpdateRoleRequest | SetRolePermissionsRequest | { expectedVersion: number }
+    action: 'update' | 'permissions' | 'delete'
+  }) {
+    return this.access.write(
+      { ...input, permission: `${input.scope.type}.roles.${input.action}` },
+      /** 基于锁内角色版本执行目标变更，保证角色资料、权限和审计一起提交。 */
+      async (tx, access) => {
+        const role = await this.record(tx, access, input.roleId)
+        if (role.builtin) throw new AppException(ACCESS_ERRORS.BUILTIN_ROLE_IMMUTABLE)
+        checkVersion(role.version, input.body.expectedVersion)
+        if (input.action === 'delete') {
+          if (role.memberCount) throw new AppException(ACCESS_ERRORS.RESOURCE_IN_USE)
+          await tx.delete(rolePermissions).where(eq(rolePermissions.roleId, role.id))
+          await tx.delete(roles).where(and(scopeFilter(input.scope), eq(roles.id, role.id)))
+        } else {
+          if ('permissionKeys' in input.body) {
+            this.validatePermissions(access, input.body.permissionKeys)
+            await this.replacePermissions(tx, role.id, input.body.permissionKeys)
+          }
+          if ('name' in input.body && input.body.name !== undefined) {
+            const [existing] = await tx
+              .select()
+              .from(roles)
+              .where(and(scopeFilter(input.scope), eq(roles.name, input.body.name)))
+            if (existing && existing.id !== role.id)
+              throw new AppException(ACCESS_ERRORS.DUPLICATE_RESOURCE)
+          }
+          const body = input.body as UpdateRoleRequest
+          await tx
+            .update(roles)
+            .set({
+              ...(body.name !== undefined ? { name: body.name } : {}),
+              ...(body.description !== undefined ? { description: body.description } : {}),
+              version: sql`${roles.version} + 1`,
+              updatedAt: new Date(),
+            })
+            .where(and(scopeFilter(input.scope), eq(roles.id, role.id)))
+        }
+        await this.access.audit(tx, {
+          ...input,
+          access,
+          action: `role.${input.action}`,
+          objectType: 'role',
+          objectId: role.id,
+          summary: {
+            changedFields: Object.keys(input.body).filter((k) => k !== 'expectedVersion'),
+          },
+        })
+        return input.action === 'delete'
+          ? { deleted: true as const }
+          : this.record(tx, access, role.id)
+      },
+    )
+  }
+}

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

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import {
+  descriptionSchema,
+  nameSchema,
+  permissionKeysSchema,
+  versionSchema,
+} from '../access.validation'
+
+export const createRoleSchema = z.strictObject({
+  name: nameSchema,
+  description: descriptionSchema.optional(),
+  permissionKeys: permissionKeysSchema.optional(),
+})
+export const updateRoleSchema = z
+  .strictObject({
+    expectedVersion: versionSchema,
+    name: nameSchema.optional(),
+    description: descriptionSchema.optional(),
+  })
+  .refine((v) => v.name !== undefined || v.description !== undefined)
+export const permissionsSchema = z.strictObject({
+  expectedVersion: versionSchema,
+  permissionKeys: permissionKeysSchema,
+})