feat: 수강신청 연습 API 추가

src/main/java/in/koreatech/koin/domain/course_registration/controller/CourseRegistrationApi.java

@@ -0,0 +1,82 @@
+package in.koreatech.koin.domain.course_registration.controller;
+
+import static in.koreatech.koin.domain.user.model.UserType.COUNCIL;
+import static in.koreatech.koin.domain.user.model.UserType.STUDENT;
+
+import java.util.List;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+import in.koreatech.koin.domain.course_registration.dto.CourseRegistrationLectureResponse;
+import in.koreatech.koin.domain.course_registration.dto.PreCourseRegistrationLectureResponse;
+import in.koreatech.koin.global.auth.Auth;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+@Tag(name = "(Normal) Course Registration: 수강 신청 연습", description = "수강 신청 연습 정보를 관리한다")
+public interface CourseRegistrationApi {
+
+    @ApiResponses(
+        value = {
+            @ApiResponse(responseCode = "200"),
+            @ApiResponse(responseCode = "400", content = @Content(schema = @Schema(hidden = true))),
+            @ApiResponse(responseCode = "401", content = @Content(schema = @Schema(hidden = true))),
+        }
+    )
+    @Operation(summary = "예비 수강 신청 과목 조회", description = """
+        ### 예비 수강 신청 과목 조회 (로그인 필요)
+        - **timetable_frame_id**: 시간표 프레임 ID
+        - **department**: 학과 (커스텀 수업인 경우 "-")
+        - **class_number**: 분반 (커스텀 수업인 경우 null)
+        - **lecture_info.lecture_code**: 과목 코드 (커스텀 수업인 경우 null)
+        - **grades**: 학점 (커스텀 수업인 경우 0)
+        - **class_time_raw**: 수업 교시 원본 데이터 (int 배열)
+        """)
+    @GetMapping("/course/registration/precourse")
+    ResponseEntity<List<PreCourseRegistrationLectureResponse>> getPreRegistrationLecture(
+        @RequestParam(value = "timetable_frame_id") Integer timetableFrameId,
+        @Auth(permit = {STUDENT, COUNCIL}) Integer userId
+    );
+
+    @ApiResponses(
+        value = {
+            @ApiResponse(responseCode = "200"),
+            @ApiResponse(responseCode = "400", content = @Content(schema = @Schema(hidden = true))),
+        }
+    )
+    @Operation(summary = "전체 수강 신청 가능 과목 조회", description = """
+        ### 수강 신청 가능 과목 조회
+        - **name**: 과목 이름
+        - **department**: 학과
+            - HRD학과
+            - 전기ㆍ전자ㆍ통신공학부
+            - 산업경영학부
+            - 교양학부
+            - 기계공학부
+            - 컴퓨터공학부
+            - 메카트로닉스공학부
+            - 에너지신소재화학공학부
+            - 디자인ㆍ건축공학부
+            - 미래융합학부
+            - 고용서비스정책학과
+        - **year**: 학년도 ex) 2024, 2025 ...
+        - **semester**: 학기
+            - **1학기**
+            - **여름학기**
+            - **2학기**
+            - **겨울학기**
+        """)
+    @GetMapping("/course/registration/search")
+    ResponseEntity<List<CourseRegistrationLectureResponse>> searchLectures(
+        @RequestParam(required = false) String name,
+        @RequestParam(required = false) String department,
+        @RequestParam(required = false) Integer year,
+        @RequestParam(required = false) String semester
+    );
+}

src/main/java/in/koreatech/koin/domain/course_registration/controller/CourseRegistrationController.java

@@ -0,0 +1,46 @@
+package in.koreatech.koin.domain.course_registration.controller;
+
+import static in.koreatech.koin.domain.user.model.UserType.COUNCIL;
+import static in.koreatech.koin.domain.user.model.UserType.STUDENT;
+
+import java.util.List;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import in.koreatech.koin.domain.course_registration.dto.CourseRegistrationLectureResponse;
+import in.koreatech.koin.domain.course_registration.dto.PreCourseRegistrationLectureResponse;
+import in.koreatech.koin.domain.course_registration.service.CourseRegistrationService;
+import in.koreatech.koin.global.auth.Auth;
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequiredArgsConstructor
+public class CourseRegistrationController implements CourseRegistrationApi {
+
+    private final CourseRegistrationService courseRegistrationService;
+
+    @GetMapping("/course/registration/precourse")
+    public ResponseEntity<List<PreCourseRegistrationLectureResponse>> getPreRegistrationLecture(
+        @RequestParam(value = "timetable_frame_id") Integer timetableFrameId,
+        @Auth(permit = {STUDENT, COUNCIL}) Integer userId
+    ) {
+        List<PreCourseRegistrationLectureResponse> response = courseRegistrationService.getUserPreRegistrationCourses(
+            timetableFrameId, userId);
+        return ResponseEntity.ok(response);
+    }
+
+    @GetMapping("/course/registration/search")
+    public ResponseEntity<List<CourseRegistrationLectureResponse>> searchLectures(
+        @RequestParam(required = false) String name,
+        @RequestParam(required = false) String department,
+        @RequestParam(required = false) Integer year,
+        @RequestParam(required = false) String semester
+    ) {
+        List<CourseRegistrationLectureResponse> lectures = courseRegistrationService.searchCourseRegistrationLecture(
+            name, department, year, semester);
+        return ResponseEntity.ok(lectures);
+    }
+}

src/main/java/in/koreatech/koin/domain/course_registration/dto/CourseRegistrationLectureResponse.java

@@ -0,0 +1,64 @@
+package in.koreatech.koin.domain.course_registration.dto;
+
+import static in.koreatech.koin.domain.course_registration.util.CourseClassTimeParser.extractRawClassTime;
+import static in.koreatech.koin.domain.course_registration.util.CourseClassTimeParser.parseClassTime;
+import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import com.fasterxml.jackson.databind.PropertyNamingStrategies.SnakeCaseStrategy;
+import com.fasterxml.jackson.databind.annotation.JsonNaming;
+
+import in.koreatech.koin.domain.timetable.model.Lecture;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@JsonNaming(value = SnakeCaseStrategy.class)
+public record CourseRegistrationLectureResponse(
+
+    @Schema(description = "학과", example = "기계공학부", requiredMode = REQUIRED)
+    String department,
+
+    @Schema(description = "과목 정보", requiredMode = REQUIRED)
+    InnerLectureInfo lectureInfo,
+
+    @Schema(description = "분반", example = "01", requiredMode = REQUIRED)
+    String classNumber,
+
+    @Schema(description = "학점", example = "3", requiredMode = REQUIRED)
+    String grades,
+
+    @Schema(description = "교수명", example = "홍길동", requiredMode = REQUIRED)
+    String professor,
+
+    @Schema(description = "수강 정원", example = "38", requiredMode = REQUIRED)
+    String regularNumber,
+
+    @Schema(description = "수업 교시", example = "월01A~03B,화01A~03B", requiredMode = REQUIRED)
+    String classTime,
+
+    @Schema(description = "수업 교시 원본 데이터", example = "[0,1,2,3,4,5,100,101,102,103,104,105]", requiredMode = REQUIRED)
+    List<Integer> classTimeRaw
+) {
+
+    public static CourseRegistrationLectureResponse from(Lecture lecture) {
+        List<Integer> classTimeRaw = extractRawClassTime(lecture.getClassTime());
+
+        return new CourseRegistrationLectureResponse(
+            lecture.getDepartment(),
+            new InnerLectureInfo(lecture.getCode(), lecture.getName()),
+            lecture.getLectureClass(),
+            lecture.getGrades(),
+            lecture.getProfessor(),
+            lecture.getRegularNumber(),
+            parseClassTime(classTimeRaw),
+            classTimeRaw
+        );
+    }
+
+    public static List<CourseRegistrationLectureResponse> fromList(List<Lecture> lectures) {
+        return lectures.stream()
+            .map(CourseRegistrationLectureResponse::from)
+            .collect(Collectors.toList());
+    }
+}

src/main/java/in/koreatech/koin/domain/course_registration/dto/InnerLectureInfo.java

@@ -0,0 +1,18 @@
+package in.koreatech.koin.domain.course_registration.dto;
+
+import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
+
+import com.fasterxml.jackson.databind.PropertyNamingStrategies.SnakeCaseStrategy;
+import com.fasterxml.jackson.databind.annotation.JsonNaming;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@JsonNaming(value = SnakeCaseStrategy.class)
+public record InnerLectureInfo(
+    @Schema(description = "과목코드", example = "MEB302", requiredMode = REQUIRED)
+    String lectureCode,
+
+    @Schema(description = "과목명", example = "정역학", requiredMode = REQUIRED)
+    String lectureName
+) {
+}

src/main/java/in/koreatech/koin/domain/course_registration/dto/LectureSearchCriteria.java

@@ -0,0 +1,28 @@
+package in.koreatech.koin.domain.course_registration.dto;
+
+public record LectureSearchCriteria(
+    String name,
+    String department,
+    Integer year,
+    String semester
+) {
+
+    /**
+     *  년도와 학기를 조합하여 semester_date 형식으로 변환
+     *  2025년 1학기 -> "20251"
+     *  2025년 겨울학기 -> "2025-겨울"
+     */
+    public String getSemesterDate() {
+        if (year == null || semester == null) {
+            return null;
+        }
+
+        return switch (semester) {
+            case "1학기" -> year + "1";
+            case "여름학기" -> year + "-여름";
+            case "2학기" -> year + "2";
+            case "겨울학기" -> year + "-겨울";
+            default -> null;
+        };
+    }
+}

src/main/java/in/koreatech/koin/domain/course_registration/dto/PreCourseRegistrationLectureResponse.java

@@ -0,0 +1,84 @@
+package in.koreatech.koin.domain.course_registration.dto;
+
+import static in.koreatech.koin.domain.course_registration.util.CourseClassTimeParser.extractRawClassTime;
+import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
+
+import java.util.List;
+import java.util.Objects;
+
+import com.fasterxml.jackson.databind.PropertyNamingStrategies.SnakeCaseStrategy;
+import com.fasterxml.jackson.databind.annotation.JsonNaming;
+
+import in.koreatech.koin.domain.timetable.model.Lecture;
+import in.koreatech.koin.domain.timetableV2.model.TimetableLecture;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@JsonNaming(value = SnakeCaseStrategy.class)
+public record PreCourseRegistrationLectureResponse (
+
+    @Schema(description = "학과", example = "컴퓨터공학부", requiredMode = REQUIRED)
+    String department,
+
+    @Schema(description = "교과목명", example = "1", requiredMode = REQUIRED)
+    InnerLectureInfo lectureInfo,
+
+    @Schema(description = "분반", example = "01", requiredMode = REQUIRED)
+    String classNumber,
+
+    @Schema(description = "학점", example = "3", requiredMode = REQUIRED)
+    String grades,
+
+    @Schema(description = "수업 교시 원본 데이터", example = "[0,1,2,3,4,5,100,101,102,103,104,105]", requiredMode = REQUIRED)
+    List<Integer> classTimeRaw
+) {
+
+    public static PreCourseRegistrationLectureResponse from(TimetableLecture timetableLecture) {
+        Lecture lecture = timetableLecture.getLecture();
+
+        String lectureCode;
+        String lectureName;
+        String classNumber;
+        String grades;
+        List<Integer> classTimeRaw;
+
+        // 커스텀 강의
+        if (lecture == null) {
+            lectureCode = null;
+            lectureName = timetableLecture.getClassTitle();
+            classNumber = null;
+            grades = timetableLecture.getGrades();
+            classTimeRaw = extractRawClassTime(timetableLecture.getClassTime());
+        } else { // 일반 강의
+            lectureCode = lecture.getCode();
+            lectureName = lecture.getName();
+            classNumber = lecture.getLectureClass();
+            grades = lecture.getGrades();
+            String classTime = timetableLecture.getClassTime() != null
+                ? timetableLecture.getClassTime()
+                : lecture.getClassTime();
+            classTimeRaw = extractRawClassTime(classTime);
+        }
+
+        return new PreCourseRegistrationLectureResponse(
+            getDepartment(timetableLecture),
+            new InnerLectureInfo(lectureCode, lectureName),
+            classNumber,
+            grades,
+            classTimeRaw
+        );
+    }
+
+    public static List<PreCourseRegistrationLectureResponse> fromList(List<TimetableLecture> timetableLectures) {
+        return timetableLectures.stream()
+            .map(PreCourseRegistrationLectureResponse::from)
+            .toList();
+    }
+
+    private static String getDepartment(TimetableLecture timetableLecture) {
+        if (timetableLecture.getLecture() == null ||
+            Objects.isNull(timetableLecture.getLecture().getDepartment())) {
+            return "-";
+        }
+        return timetableLecture.getLecture().getDepartment();
+    }
+}

src/main/java/in/koreatech/koin/domain/course_registration/repository/CourseCustomRepository.java

@@ -0,0 +1,45 @@
+package in.koreatech.koin.domain.course_registration.repository;
+
+import static in.koreatech.koin.domain.timetable.model.QLecture.lecture;
+
+import java.util.List;
+
+import org.springframework.stereotype.Repository;
+
+import com.querydsl.core.types.dsl.BooleanExpression;
+import com.querydsl.jpa.impl.JPAQueryFactory;
+
+import in.koreatech.koin.domain.timetable.model.Lecture;
+import in.koreatech.koin.domain.course_registration.dto.LectureSearchCriteria;
+import lombok.RequiredArgsConstructor;
+
+@Repository
+@RequiredArgsConstructor
+public class CourseCustomRepository {
+
+    private final JPAQueryFactory queryFactory;
+
+    public List<Lecture> searchLectures(LectureSearchCriteria condition) {
+        return queryFactory
+            .selectFrom(lecture)
+            .where(
+                nameContains(condition.name()),
+                departmentEq(condition.department()),
+                semesterDateEq(condition.getSemesterDate())
+            )
+            .orderBy(lecture.semester.desc(), lecture.code.asc())
+            .fetch();
+    }
+
+    private BooleanExpression nameContains(String name) {
+        return name != null ? lecture.name.containsIgnoreCase(name) : null;
+    }
+
+    private BooleanExpression departmentEq(String department) {
+        return department != null ? lecture.department.eq(department) : null;
+    }
+
+    private BooleanExpression semesterDateEq(String semesterDate) {
+        return semesterDate != null ? lecture.semester.eq(semesterDate) : null;
+    }
+}