FAC-120 feat: enhance bulk course provisioning with cascading dropdowns (#286)

* FAC-120 feat: enhance bulk course provisioning with cascading dropdowns

Replace free-text inputs and CSV upload with cascading dropdown selectors
(Semester → Department → Program) and JSON-based bulk preview/execute
endpoints for course provisioning.

* FAC-120 chore: add tech spec for bulk course provisioning enhancement

Author: y4nder

_bmad-output/implementation-artifacts/tech-spec-moodle-course-bulk-enhancement.md

@@ -9,6 +9,7 @@ describe('AdminFiltersController', () => {
   let controller: AdminFiltersController;
   let filtersService: {
     GetCampuses: jest.Mock;
+    GetSemesters: jest.Mock;
     GetDepartments: jest.Mock;
     GetPrograms: jest.Mock;
     GetRoles: jest.Mock;
@@ -17,6 +18,7 @@ describe('AdminFiltersController', () => {
   beforeEach(async () => {
     filtersService = {
       GetCampuses: jest.fn().mockResolvedValue([]),
+      GetSemesters: jest.fn().mockResolvedValue([]),
       GetDepartments: jest.fn().mockResolvedValue([]),
       GetPrograms: jest.fn().mockResolvedValue([]),
       GetRoles: jest.fn().mockReturnValue(Object.values(UserRole)),
@@ -59,14 +61,29 @@ describe('AdminFiltersController', () => {
 
     const result = await controller.GetDepartments({ campusId: 'c-1' });
 
-    expect(filtersService.GetDepartments).toHaveBeenCalledWith('c-1');
+    expect(filtersService.GetDepartments).toHaveBeenCalledWith(
+      'c-1',
+      undefined,
+    );
     expect(result).toEqual(departments);
   });
 
   it('should pass undefined campusId when not provided', async () => {
     await controller.GetDepartments({});
 
-    expect(filtersService.GetDepartments).toHaveBeenCalledWith(undefined);
+    expect(filtersService.GetDepartments).toHaveBeenCalledWith(
+      undefined,
+      undefined,
+    );
+  });
+
+  it('should pass semesterId to the filters service', async () => {
+    await controller.GetDepartments({ semesterId: 's-1' });
+
+    expect(filtersService.GetDepartments).toHaveBeenCalledWith(
+      undefined,
+      's-1',
+    );
   });
 
   it('should delegate program listing to the filters service', async () => {

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

@@ -17,6 +17,7 @@ import { FilterOptionResponseDto } from './dto/responses/filter-option.response.
 import { FilterFacultyResponseDto } from './dto/responses/filter-faculty.response.dto';
 import { FilterCourseResponseDto } from './dto/responses/filter-course.response.dto';
 import { FilterVersionResponseDto } from './dto/responses/filter-version.response.dto';
+import { SemesterFilterResponseDto } from './dto/responses/semester-filter.response.dto';
 
 @ApiTags('Admin')
 @Controller('admin/filters')
@@ -32,6 +33,16 @@ export class AdminFiltersController {
     return this.filtersService.GetCampuses();
   }
 
+  @Get('semesters')
+  @ApiOperation({
+    summary:
+      'List all semesters with computed date ranges for filter dropdowns',
+  })
+  @ApiResponse({ status: 200, type: [SemesterFilterResponseDto] })
+  async GetSemesters(): Promise<SemesterFilterResponseDto[]> {
+    return this.filtersService.GetSemesters();
+  }
+
   @Get('departments')
   @ApiOperation({ summary: 'List departments for filter dropdowns' })
   @ApiQuery({
@@ -40,11 +51,17 @@ export class AdminFiltersController {
     type: String,
     description: 'Filter by campus UUID',
   })
+  @ApiQuery({
+    name: 'semesterId',
+    required: false,
+    type: String,
+    description: 'Filter by semester UUID',
+  })
   @ApiResponse({ status: 200, type: [FilterOptionResponseDto] })
   async GetDepartments(
     @Query() query: FilterDepartmentsQueryDto,
   ): Promise<FilterOptionResponseDto[]> {
-    return this.filtersService.GetDepartments(query.campusId);
+    return this.filtersService.GetDepartments(query.campusId, query.semesterId);
   }
 
   @Get('programs')

src/modules/admin/admin-filters.controller.ts

@@ -6,4 +6,9 @@ export class FilterDepartmentsQueryDto {
   @IsUUID()
   @IsOptional()
   campusId?: string;
+
+  @ApiPropertyOptional({ description: 'Filter departments by semester UUID' })
+  @IsUUID()
+  @IsOptional()
+  semesterId?: string;
 }

src/modules/admin/dto/requests/filter-departments-query.dto.ts

@@ -0,0 +1,30 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class SemesterFilterResponseDto {
+  @ApiProperty({ description: 'Semester UUID' })
+  id: string;
+
+  @ApiProperty({ description: 'Semester code', example: 'S12526' })
+  code: string;
+
+  @ApiProperty({ description: 'Semester label', example: 'Semester 1' })
+  label: string;
+
+  @ApiProperty({ description: 'Academic year', example: '2025-2026' })
+  academicYear: string;
+
+  @ApiProperty({ description: 'Campus code', example: 'UCMN' })
+  campusCode: string;
+
+  @ApiProperty({
+    description: 'Computed start date (ISO 8601)',
+    example: '2025-08-01',
+  })
+  startDate: string;
+
+  @ApiProperty({
+    description: 'Computed end date (ISO 8601)',
+    example: '2025-12-18',
+  })
+  endDate: string;
+}

src/modules/admin/dto/responses/semester-filter.response.dto.ts

@@ -1,10 +1,11 @@
 import { FilterQuery } from '@mikro-orm/core';
 import { EntityManager } from '@mikro-orm/postgresql';
-import { Injectable, NotFoundException } from '@nestjs/common';
+import { Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { Campus } from 'src/entities/campus.entity';
 import { Department } from 'src/entities/department.entity';
 import { Enrollment } from 'src/entities/enrollment.entity';
 import { Program } from 'src/entities/program.entity';
+import { Semester } from 'src/entities/semester.entity';
 import { QuestionnaireType } from 'src/entities/questionnaire-type.entity';
 import { QuestionnaireVersion } from 'src/entities/questionnaire-version.entity';
 import { User } from 'src/entities/user.entity';
@@ -14,9 +15,12 @@ import { FilterOptionResponseDto } from '../dto/responses/filter-option.response
 import { FilterFacultyResponseDto } from '../dto/responses/filter-faculty.response.dto';
 import { FilterCourseResponseDto } from '../dto/responses/filter-course.response.dto';
 import { FilterVersionResponseDto } from '../dto/responses/filter-version.response.dto';
+import { SemesterFilterResponseDto } from '../dto/responses/semester-filter.response.dto';
 
 @Injectable()
 export class AdminFiltersService {
+  private readonly logger = new Logger(AdminFiltersService.name);
+
   constructor(private readonly em: EntityManager) {}
 
   async GetCampuses(): Promise<FilterOptionResponseDto[]> {
@@ -28,9 +32,60 @@ export class AdminFiltersService {
     return campuses.map((c) => FilterOptionResponseDto.Map(c));
   }
 
-  async GetDepartments(campusId?: string): Promise<FilterOptionResponseDto[]> {
+  async GetSemesters(): Promise<SemesterFilterResponseDto[]> {
+    const semesters = await this.em.find(
+      Semester,
+      {},
+      { populate: ['campus'], orderBy: { code: 'DESC' } },
+    );
+
+    const results: SemesterFilterResponseDto[] = [];
+
+    for (const sem of semesters) {
+      const match = sem.code.match(/^S([12])(\d{2})(\d{2})$/);
+      if (!match) {
+        this.logger.warn(
+          `Skipping semester with malformed code: "${sem.code}" (id=${sem.id})`,
+        );
+        continue;
+      }
+
+      const semesterNum = match[1];
+      const fullStartYear = '20' + match[2];
+      const fullEndYear = '20' + match[3];
+
+      let startDate: string;
+      let endDate: string;
+      if (semesterNum === '1') {
+        startDate = `${fullStartYear}-08-01`;
+        endDate = `${fullStartYear}-12-18`;
+      } else {
+        startDate = `${fullEndYear}-01-20`;
+        endDate = `${fullEndYear}-06-01`;
+      }
+
+      results.push({
+        id: sem.id,
+        code: sem.code,
+        label: sem.label ?? `Semester ${semesterNum}`,
+        academicYear: sem.academicYear ?? `${fullStartYear}-${fullEndYear}`,
+        campusCode: sem.campus.code,
+        startDate,
+        endDate,
+      });
+    }
+
+    return results;
+  }
+
+  async GetDepartments(
+    campusId?: string,
+    semesterId?: string,
+  ): Promise<FilterOptionResponseDto[]> {
     const filter: FilterQuery<Department> = {};
-    if (campusId) {
+    if (semesterId) {
+      filter.semester = semesterId;
+    } else if (campusId) {
       filter.semester = { campus: campusId };
     }
     const departments = await this.em.find(Department, filter, {

src/modules/admin/services/admin-filters.service.ts

@@ -15,6 +15,7 @@ export const AuditAction = {
   MOODLE_PROVISION_COURSES: 'moodle.provision.courses',
   MOODLE_PROVISION_QUICK_COURSE: 'moodle.provision.quick-course',
   MOODLE_PROVISION_USERS: 'moodle.provision.users',
+  MOODLE_BULK_PROVISION_COURSES: 'moodle.provision.bulk-courses',
 } as const;
 
 export type AuditAction = (typeof AuditAction)[keyof typeof AuditAction];

src/modules/audit/audit-action.enum.ts

@@ -35,6 +35,8 @@ import { MoodleProvisioningService } from '../services/moodle-provisioning.servi
 import { ProvisionCategoriesRequestDto } from '../dto/requests/provision-categories.request.dto';
 import { SeedCoursesContextDto } from '../dto/requests/seed-courses.request.dto';
 import { ExecuteCoursesRequestDto } from '../dto/requests/execute-courses.request.dto';
+import { BulkCoursePreviewRequestDto } from '../dto/requests/bulk-course-preview.request.dto';
+import { BulkCourseExecuteRequestDto } from '../dto/requests/bulk-course-execute.request.dto';
 import { QuickCourseRequestDto } from '../dto/requests/quick-course.request.dto';
 import { SeedUsersRequestDto } from '../dto/requests/seed-users.request.dto';
 import { ProvisionResultDto } from '../dto/responses/provision-result.response.dto';
@@ -192,6 +194,46 @@ export class MoodleProvisioningController {
     );
   }
 
+  @Post('courses/bulk/preview')
+  @HttpCode(HttpStatus.OK)
+  @UseJwtGuard(UserRole.SUPER_ADMIN)
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Preview bulk course creation from JSON input' })
+  @ApiResponse({ status: 200, type: CoursePreviewResultDto })
+  async PreviewBulkCourses(
+    @Body() dto: BulkCoursePreviewRequestDto,
+  ): Promise<CoursePreviewResultDto> {
+    return await this.provisioningService.PreviewBulkCourses(dto);
+  }
+
+  @Post('courses/bulk/execute')
+  @HttpCode(HttpStatus.OK)
+  @UseJwtGuard(UserRole.SUPER_ADMIN)
+  @ApiBearerAuth()
+  @Audited({
+    action: AuditAction.MOODLE_BULK_PROVISION_COURSES,
+    resource: 'MoodleCourse',
+  })
+  @UseInterceptors(
+    MetaDataInterceptor,
+    CurrentUserInterceptor,
+    AuditInterceptor,
+  )
+  @ApiOperation({ summary: 'Execute bulk course creation in Moodle' })
+  @ApiResponse({ status: 200, type: ProvisionResultDto })
+  async ExecuteBulkCourses(
+    @Body() dto: BulkCourseExecuteRequestDto,
+  ): Promise<ProvisionResultDto> {
+    try {
+      return await this.provisioningService.ExecuteBulkCourses(dto);
+    } catch (e) {
+      if (e instanceof MoodleConnectivityError) {
+        throw new BadGatewayException('Moodle is unreachable');
+      }
+      throw e;
+    }
+  }
+
   @Post('courses/quick/preview')
   @HttpCode(HttpStatus.OK)
   @UseJwtGuard(UserRole.SUPER_ADMIN)

src/modules/moodle/controllers/moodle-provisioning.controller.ts

@@ -0,0 +1,79 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  IsArray,
+  IsDateString,
+  IsInt,
+  IsNotEmpty,
+  IsString,
+  IsUUID,
+  Min,
+  ArrayNotEmpty,
+  ArrayMaxSize,
+  ValidateNested,
+  Validate,
+} from 'class-validator';
+import { IsBeforeEndDate } from '../validators/is-before-end-date.validator';
+
+export class ConfirmedCourseEntryDto {
+  @ApiProperty({ description: 'Course code', example: 'CS101' })
+  @IsString()
+  @IsNotEmpty()
+  courseCode: string;
+
+  @ApiProperty({
+    description: 'Descriptive title',
+    example: 'Introduction to Computer Science',
+  })
+  @IsString()
+  @IsNotEmpty()
+  descriptiveTitle: string;
+
+  @ApiProperty({
+    description: 'Moodle category ID from preview',
+    example: 42,
+  })
+  @IsInt()
+  @Min(1)
+  categoryId: number;
+}
+
+export class BulkCourseExecuteRequestDto {
+  @ApiProperty({ description: 'Semester UUID' })
+  @IsUUID()
+  semesterId: string;
+
+  @ApiProperty({ description: 'Department UUID' })
+  @IsUUID()
+  departmentId: string;
+
+  @ApiProperty({ description: 'Program UUID' })
+  @IsUUID()
+  programId: string;
+
+  @ApiProperty({
+    description: 'Course start date (ISO 8601)',
+    example: '2025-08-01',
+  })
+  @IsDateString()
+  @Validate(IsBeforeEndDate)
+  startDate: string;
+
+  @ApiProperty({
+    description: 'Course end date (ISO 8601)',
+    example: '2025-12-18',
+  })
+  @IsDateString()
+  endDate: string;
+
+  @ApiProperty({
+    type: [ConfirmedCourseEntryDto],
+    description: 'Confirmed courses to create',
+  })
+  @IsArray()
+  @ArrayNotEmpty()
+  @ArrayMaxSize(500)
+  @ValidateNested({ each: true })
+  @Type(() => ConfirmedCourseEntryDto)
+  courses: ConfirmedCourseEntryDto[];
+}