[STAGING] FAC-131 feat: add campus head role + local user provisioning (#331) (#332)

- Add CAMPUS_HEAD to UserRole enum and ScopeResolverService (Semester → Campus traversal)
- Add POST /admin/users for non-Moodle local user provisioning (bcrypt + reserved "local-" prefix)
- Add GET /admin/institutional-roles/campus-head-eligible-categories for depth-1 promotion
- Add User.campus_source column + migration, mirror departmentSource/programSource pattern
- Enforce local- namespace across Moodle inflows (sync skip guard, seed-users DTO rejection)
- Extend controller guards (analytics/faculty/reports/curriculum) to allow CAMPUS_HEAD
- Deny questionnaire submissions from CAMPUS_HEAD at service layer with clear message
- Emit admin.user.create audit event manually from AdminUserService

Author: y4nder

_bmad-output/implementation-artifacts/tech-spec-fac-131-campus-head-role.md

@@ -69,6 +69,9 @@ export class User extends CustomBaseEntity {
   @Property({ default: 'auto' })
   programSource!: string;
 
+  @Property({ default: 'auto' })
+  campusSource!: string;
+
   @OneToMany(() => MoodleToken, (token) => token.user)
   moodleTokens = new Collection<MoodleToken>(this);
 
@@ -99,6 +102,7 @@ export class User extends CustomBaseEntity {
     user.isActive = true;
     user.departmentSource = 'auto';
     user.programSource = 'auto';
+    user.campusSource = 'auto';
 
     return user;
   }

src/entities/user.entity.ts

@@ -8053,6 +8053,22 @@
           "comment": null,
           "enumItems": [],
           "mappedType": "string"
+        },
+        "campus_source": {
+          "name": "campus_source",
+          "type": "varchar(255)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": 255,
+          "precision": null,
+          "scale": null,
+          "default": "'auto'",
+          "comment": null,
+          "enumItems": [],
+          "mappedType": "string"
         }
       },
       "name": "user",

src/migrations/.snapshot-faculytics_db.json

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260413225718_fac131aCampusSource extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(
+      `alter table "user" add column "campus_source" varchar(255) not null default 'auto';`,
+    );
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "user" drop column "campus_source";`);
+  }
+}

src/migrations/Migration20260413225718_fac-131a-campus-source.ts

@@ -3,18 +3,23 @@ import { Test, TestingModule } from '@nestjs/testing';
 import { AuthGuard } from '@nestjs/passport';
 import { RolesGuard } from 'src/security/guards/roles.guard';
 import { CurrentUserInterceptor } from 'src/modules/common/interceptors/current-user.interceptor';
+import { MetaDataInterceptor } from 'src/modules/common/interceptors/metadata.interceptor';
 import { AdminController } from './admin.controller';
 import { AdminService } from './services/admin.service';
+import { AdminUserService } from './services/admin-user.service';
 import { ListUsersQueryDto } from './dto/requests/list-users-query.dto';
 import { UpdateScopeAssignmentDto } from './dto/requests/update-scope-assignment.request.dto';
+import { CreateLocalUserRequestDto } from './dto/requests/create-user.request.dto';
 
 describe('AdminController', () => {
   let controller: AdminController;
   let adminService: {
     ListUsers: jest.Mock;
     GetUserDetail: jest.Mock;
     UpdateUserScopeAssignment: jest.Mock;
+    GetCampusHeadEligibleCategories: jest.Mock;
   };
+  let adminUserService: { CreateLocalUser: jest.Mock };
 
   async function buildModule(
     overrides: {
@@ -29,6 +34,10 @@ describe('AdminController', () => {
           provide: AdminService,
           useValue: adminService,
         },
+        {
+          provide: AdminUserService,
+          useValue: adminUserService,
+        },
       ],
     })
       .overrideGuard(AuthGuard('jwt'))
@@ -44,6 +53,11 @@ describe('AdminController', () => {
         intercept: (_ctx: unknown, next: { handle: () => unknown }) =>
           next.handle(),
       })
+      .overrideInterceptor(MetaDataInterceptor)
+      .useValue({
+        intercept: (_ctx: unknown, next: { handle: () => unknown }) =>
+          next.handle(),
+      })
       .compile();
   }
 
@@ -67,6 +81,19 @@ describe('AdminController', () => {
         departmentSource: 'auto',
         programSource: 'auto',
       }),
+      GetCampusHeadEligibleCategories: jest.fn().mockResolvedValue([]),
+    };
+    adminUserService = {
+      CreateLocalUser: jest.fn().mockResolvedValue({
+        id: 'user-1',
+        username: 'local-kmartinez',
+        firstName: 'K',
+        lastName: 'Martinez',
+        fullName: 'K Martinez',
+        campus: null,
+        defaultPasswordAssigned: false,
+        createdAt: '2026-01-01T00:00:00.000Z',
+      }),
     };
 
     const module = await buildModule();
@@ -104,6 +131,33 @@ describe('AdminController', () => {
     );
   });
 
+  it('should delegate POST /admin/users to the admin-user service', async () => {
+    const dto: CreateLocalUserRequestDto = {
+      username: 'local-kmartinez',
+      firstName: 'K',
+      lastName: 'Martinez',
+      password: 'TempPass1',
+    };
+
+    const result = await controller.CreateLocalUser(dto);
+
+    expect(adminUserService.CreateLocalUser).toHaveBeenCalledWith(dto);
+    expect(result).toMatchObject({
+      id: 'user-1',
+      username: 'local-kmartinez',
+      fullName: 'K Martinez',
+      defaultPasswordAssigned: false,
+    });
+  });
+
+  it('should delegate campus-head eligible categories lookup to the admin service', async () => {
+    await controller.GetCampusHeadEligibleCategories({ userId: 'user-1' });
+
+    expect(adminService.GetCampusHeadEligibleCategories).toHaveBeenCalledWith(
+      'user-1',
+    );
+  });
+
   describe('authorization', () => {
     it('rejects unauthenticated requests via JwtAuthGuard', async () => {
       const module = await buildModule({

src/modules/admin/admin.controller.spec.ts

@@ -20,25 +20,52 @@ import {
 } from '@nestjs/swagger';
 import { UseJwtGuard } from 'src/security/decorators';
 import { CurrentUserInterceptor } from 'src/modules/common/interceptors/current-user.interceptor';
+import { MetaDataInterceptor } from 'src/modules/common/interceptors/metadata.interceptor';
 import { UserRole } from '../auth/roles.enum';
 import { AdminService } from './services/admin.service';
+import { AdminUserService } from './services/admin-user.service';
 import { AssignInstitutionalRoleDto } from './dto/requests/assign-institutional-role.request.dto';
 import { RemoveInstitutionalRoleDto } from './dto/requests/remove-institutional-role.request.dto';
 import { ListUsersQueryDto } from './dto/requests/list-users-query.dto';
 import { DeanEligibleCategoriesQueryDto } from './dto/requests/dean-eligible-categories-query.dto';
+import { CampusHeadEligibleCategoriesQueryDto } from './dto/requests/campus-head-eligible-categories-query.dto';
 import { UpdateScopeAssignmentDto } from './dto/requests/update-scope-assignment.request.dto';
+import { CreateLocalUserRequestDto } from './dto/requests/create-user.request.dto';
 import { AdminUserDetailResponseDto } from './dto/responses/admin-user-detail.response.dto';
 import { AdminUserListResponseDto } from './dto/responses/admin-user-list.response.dto';
 import { AdminUserScopeAssignmentResponseDto } from './dto/responses/admin-user-scope-assignment.response.dto';
 import { DeanEligibleCategoryResponseDto } from './dto/responses/dean-eligible-category.response.dto';
+import { CampusHeadEligibleCategoryResponseDto } from './dto/responses/campus-head-eligible-category.response.dto';
+import { CreateLocalUserResponseDto } from './dto/responses/create-user.response.dto';
 
 @ApiTags('Admin')
 @Controller('admin')
 @UseJwtGuard(UserRole.SUPER_ADMIN)
 @UseInterceptors(CurrentUserInterceptor)
 @ApiBearerAuth()
 export class AdminController {
-  constructor(private readonly adminService: AdminService) {}
+  constructor(
+    private readonly adminService: AdminService,
+    private readonly adminUserService: AdminUserService,
+  ) {}
+
+  @Post('users')
+  @UseInterceptors(MetaDataInterceptor)
+  @ApiOperation({
+    summary:
+      'Create a Faculytics-local user (non-Moodle, bcrypt-authenticated)',
+  })
+  @ApiResponse({ status: 201, type: CreateLocalUserResponseDto })
+  @ApiResponse({
+    status: 400,
+    description: 'Invalid username, password, or campusId',
+  })
+  @ApiResponse({ status: 409, description: 'Username already exists' })
+  async CreateLocalUser(
+    @Body() dto: CreateLocalUserRequestDto,
+  ): Promise<CreateLocalUserResponseDto> {
+    return this.adminUserService.CreateLocalUser(dto);
+  }
 
   @Get('users')
   @ApiOperation({ summary: 'List users for the admin console' })
@@ -158,9 +185,32 @@ export class AdminController {
     return this.adminService.GetDeanEligibleCategories(query.userId);
   }
 
+  @Get('institutional-roles/campus-head-eligible-categories')
+  @ApiOperation({
+    summary:
+      'List depth-1 Moodle categories a user can be promoted to as Campus Head',
+  })
+  @ApiQuery({
+    name: 'userId',
+    required: true,
+    type: String,
+    description: 'UUID of the user to check eligibility for',
+  })
+  @ApiResponse({
+    status: 200,
+    type: [CampusHeadEligibleCategoryResponseDto],
+  })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  async GetCampusHeadEligibleCategories(
+    @Query() query: CampusHeadEligibleCategoriesQueryDto,
+  ): Promise<CampusHeadEligibleCategoryResponseDto[]> {
+    return this.adminService.GetCampusHeadEligibleCategories(query.userId);
+  }
+
   @Post('institutional-roles')
   @ApiOperation({
-    summary: 'Assign an institutional role (DEAN/CHAIRPERSON) to a user',
+    summary:
+      'Assign an institutional role (DEAN/CHAIRPERSON/CAMPUS_HEAD) to a user',
   })
   @ApiResponse({ status: 200, description: 'Role assigned successfully' })
   @ApiResponse({ status: 404, description: 'User or category not found' })

src/modules/admin/admin.controller.ts

@@ -21,6 +21,7 @@ import { AdminGenerateController } from './admin-generate.controller';
 import { AdminService } from './services/admin.service';
 import { AdminFiltersService } from './services/admin-filters.service';
 import { AdminGenerateService } from './services/admin-generate.service';
+import { AdminUserService } from './services/admin-user.service';
 import { CommentGeneratorService } from './services/comment-generator.service';
 
 @Module({
@@ -52,6 +53,7 @@ import { CommentGeneratorService } from './services/comment-generator.service';
     AdminService,
     AdminFiltersService,
     AdminGenerateService,
+    AdminUserService,
     CommentGeneratorService,
   ],
 })

src/modules/admin/admin.module.ts

@@ -8,8 +8,9 @@ export class AssignInstitutionalRoleDto {
   userId: string;
 
   @ApiProperty({
-    enum: [UserRole.DEAN, UserRole.CHAIRPERSON],
-    description: 'The institutional role to assign',
+    enum: [UserRole.DEAN, UserRole.CHAIRPERSON, UserRole.CAMPUS_HEAD],
+    description:
+      'The institutional role to assign (DEAN at depth 3, CHAIRPERSON at depth 4, CAMPUS_HEAD at depth 1)',
   })
   @IsEnum(UserRole)
   role: UserRole;

src/modules/admin/dto/requests/assign-institutional-role.request.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsUUID } from 'class-validator';
+
+export class CampusHeadEligibleCategoriesQueryDto {
+  @ApiProperty({
+    description: 'UUID of the user to check campus-head eligibility for',
+  })
+  @IsUUID()
+  userId: string;
+}

src/modules/admin/dto/requests/campus-head-eligible-categories-query.dto.ts

@@ -0,0 +1,48 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsOptional,
+  IsString,
+  IsUUID,
+  Matches,
+  MinLength,
+} from 'class-validator';
+
+export class CreateLocalUserRequestDto {
+  @ApiProperty({
+    example: 'local-kmartinez',
+    description: 'Username — must start with reserved "local-" prefix',
+  })
+  @IsString()
+  @Matches(/^local-[a-z0-9][a-z0-9._-]*$/, {
+    message:
+      'username must start with "local-" prefix and contain only lowercase alphanumerics, dots, dashes, or underscores',
+  })
+  username: string;
+
+  @ApiProperty({ example: 'K' })
+  @IsString()
+  @MinLength(1)
+  firstName: string;
+
+  @ApiProperty({ example: 'Martinez' })
+  @IsString()
+  @MinLength(1)
+  lastName: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Password (min 6 chars). Omit to assign default "Head123#" seed.',
+  })
+  @IsOptional()
+  @IsString()
+  @MinLength(6, { message: 'password must be at least 6 characters' })
+  password?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Optional UUID of the campus to assign. Sets campusSource="manual".',
+  })
+  @IsOptional()
+  @IsUUID()
+  campusId?: string;
+}