feat: RBAC Rollen & Rechte (Phase 1 - Datenmodell, Roles-Verwaltung, Guard-Infrastruktur)

Replaces the fixed 5-value Role enum with a database-driven Role/Permission
model: admins can create custom roles with a precise per-resource/action
permission set (83-key code-owned catalog), instead of being locked to
ADMIN/BEEKEEPER/STAFF/READONLY/API_CLIENT.

- New Role/Permission/RolePermission tables; legacy Role enum renamed to
  LegacyRole and kept as User.legacyRole so all existing @Roles() call
  sites keep working unchanged during the migration.
- New RolesController/RolesService (CRUD, permission-set editing,
  deactivate/reactivate) with lockout-prevention invariants: system roles
  (ADMIN) can't be edited or deactivated, and a role still assigned to
  users can't be deactivated.
- New PermissionResolverService (30s-cached, DB-fresh per user) and
  PermissionsGuard + @RequirePermission(), registered as an additional
  APP_GUARD alongside the legacy RolesGuard so both systems run
  side-by-side until controllers are migrated in Phase 2.
- PermissionCatalogSyncService seeds any new catalog entries into the DB
  on boot, so future features only touch the TS catalog.
- New GET /auth/me returns the caller's role and effective permissions.
- Migration hand-written (destructive column rename) with grants derived
  from a fresh grep of every existing @Roles() call site, verified
  against 5 controllers read in full for STAFF's exact write boundary.
- test/roles.e2e-spec.ts covers the new endpoints and invariants end to
  end; test/authorization-coverage.e2e-spec.ts added but skipped until
  Phase 2 gives every controller a @RequirePermission.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

ApiCore-Backend/src/users/dto/create-user.dto.ts

@@ -1,6 +1,6 @@
 import { ApiProperty } from '@nestjs/swagger';
 import { IsEmail, IsEnum, IsString, MinLength } from 'class-validator';
-import { Role } from '../../../generated/prisma';
+import { LegacyRole as Role } from '../../../generated/prisma';
 
 export class CreateUserDto {
   @ApiProperty()

ApiCore-Backend/src/users/dto/update-user.dto.ts

@@ -1,6 +1,6 @@
 import { ApiPropertyOptional } from '@nestjs/swagger';
 import { IsEnum, IsOptional, IsString } from 'class-validator';
-import { Role } from '../../../generated/prisma';
+import { LegacyRole as Role } from '../../../generated/prisma';
 
 export class UpdateUserDto {
   @ApiPropertyOptional()

ApiCore-Backend/src/users/users.controller.ts

@@ -1,6 +1,6 @@
 import { Body, Controller, Get, Param, Patch, Post } from '@nestjs/common';
 import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
-import { Role } from '../../generated/prisma';
+import { LegacyRole as Role } from '../../generated/prisma';
 import { Roles } from '../auth/decorators/roles.decorator';
 import { CurrentUser } from '../auth/decorators/current-user.decorator';
 import type { AuthenticatedUser } from '../auth/types/authenticated-user';

ApiCore-Backend/src/users/users.service.spec.ts

@@ -12,6 +12,9 @@ describe('UsersService', () => {
       create: jest.Mock;
       update: jest.Mock;
     };
+    role: {
+      findUniqueOrThrow: jest.Mock;
+    };
   };
   let auditLog: { record: jest.Mock };
 
@@ -20,7 +23,8 @@ describe('UsersService', () => {
     email: '[email protected]',
     passwordHash: 'hashed',
     name: 'Existing User',
-    role: 'STAFF',
+    legacyRole: 'STAFF',
+    roleId: 'role-staff',
     isActive: true,
     createdAt: new Date(),
     deactivatedAt: null,
@@ -34,6 +38,11 @@ describe('UsersService', () => {
         create: jest.fn(),
         update: jest.fn(),
       },
+      role: {
+        findUniqueOrThrow: jest
+          .fn()
+          .mockResolvedValue({ id: 'role-staff', key: 'STAFF' }),
+      },
     };
     auditLog = { record: jest.fn().mockResolvedValue(undefined) };
     usersService = new UsersService(
@@ -52,7 +61,7 @@ describe('UsersService', () => {
         id: existingUser.id,
         email: existingUser.email,
         name: existingUser.name,
-        role: existingUser.role,
+        role: existingUser.legacyRole,
         isActive: existingUser.isActive,
         createdAt: existingUser.createdAt,
         deactivatedAt: existingUser.deactivatedAt,

ApiCore-Backend/src/users/users.service.ts

@@ -30,8 +30,29 @@ export class UsersService {
   ) {}
 
   private toSummary(user: User): UserSummary {
-    const { id, email, name, role, isActive, createdAt, deactivatedAt } = user;
-    return { id, email, name, role, isActive, createdAt, deactivatedAt };
+    const { id, email, name, legacyRole, isActive, createdAt, deactivatedAt } =
+      user;
+    return {
+      id,
+      email,
+      name,
+      role: legacyRole,
+      isActive,
+      createdAt,
+      deactivatedAt,
+    };
+  }
+
+  /**
+   * Resolves the RBAC roleId that corresponds to a legacy role key, so
+   * User.roleId stays in sync while callers still speak in terms of the
+   * legacy enum (Phase 1 of the RBAC rollout; see Role/Permission models).
+   */
+  private async resolveRoleId(legacyRole: string): Promise<string> {
+    const role = await this.prisma.role.findUniqueOrThrow({
+      where: { key: legacyRole },
+    });
+    return role.id;
   }
 
   async findAll(): Promise<UserSummary[]> {
@@ -66,8 +87,15 @@ export class UsersService {
       throw new ConflictException('Email already in use');
     }
     const passwordHash = await bcrypt.hash(dto.password, BCRYPT_SALT_ROUNDS);
+    const roleId = await this.resolveRoleId(dto.role);
     const user = await this.prisma.user.create({
-      data: { email: dto.email, passwordHash, name: dto.name, role: dto.role },
+      data: {
+        email: dto.email,
+        passwordHash,
+        name: dto.name,
+        legacyRole: dto.role,
+        roleId,
+      },
     });
     await this.auditLog.record({
       entityType: 'User',
@@ -85,9 +113,14 @@ export class UsersService {
     actingUserId?: string,
   ): Promise<UserSummary> {
     const before = await this.findById(id);
+    const roleId = dto.role ? await this.resolveRoleId(dto.role) : undefined;
     const user = await this.prisma.user.update({
       where: { id },
-      data: { ...dto },
+      data: {
+        name: dto.name,
+        legacyRole: dto.role,
+        roleId,
+      },
     });
     await this.auditLog.record({
       entityType: 'User',