chore: 테스트 인프라·테스트 케이스 보강 및 API 확장 (#58)

- API: Testcontainers(Redis) 적용, RegistrationConcurrencyTest 활성화
- Schedule/User API 확장, .cursorrules 테크 스택·필수 테스트 범위 갱신
- Web: SignInForm/SignUpForm, useRegistrationStore, parseVtt 등 단위·통합 테스트 추가
- test-utils.tsx, jest.setup 보완

Author: junotb

.cursorrules

@@ -12,22 +12,29 @@
 # Tech Stack & Versions
 ## Backend (Java/Spring Boot)
 - **Framework**: Spring Boot 3.3.3
-- **Language**: Java 17 (Use Records for DTOs if applicable, strictly typed)
+- **Language**: Java 21 (Use Records for DTOs if applicable, strictly typed)
 - **Build Tool**: Gradle (Kotlin DSL)
 - **Database**: PostgreSQL (Production), H2 (Test)
 - **ORM**: JPA / Hibernate
 - **API Docs**: SpringDoc OpenAPI (Swagger)
 - **Utils**: Lombok, Commons Lang3
+- **Config**: spring-dotenv (.env 로드)
+- **Concurrency**: Redisson (Redis 분산 락)
+- **SQL Logging**: p6spy
+- **AI/STT**: Google Cloud Speech, Google GenAI (Gemini)
 
 ## Frontend (Next.js)
 - **Framework**: Next.js 15.5.6 (App Router)
 - **Library**: React 19.1.0
 - **Language**: TypeScript
 - **Styling**: Tailwind CSS v4 (No config file, strictly utility classes)
 - **State Management**: Zustand (Client), TanStack Query v5 (Server)
-- **Forms**: React Hook Form + Zod
+- **Forms**: React Hook Form + Zod + @hookform/resolvers
+- **UI**: Radix UI (shadcn/ui 기반), lucide-react (아이콘)
 - **Auth**: Better-Auth (Do NOT suggest NextAuth)
 - **HTTP Client**: Axios
+- **Toast**: Sonner
+- **Date**: date-fns
 - **Testing**: Jest, React Testing Library (RTL)
 
 # Coding Guidelines
@@ -67,7 +74,8 @@
 - **Type Safety**: Share types with Backend or define strictly in `types/`. Use Zod for validation.
 - **Testing**:
   - Use **Jest** and **React Testing Library** for Unit/Integration tests.
-  - Test complex hooks and critical form flows (Login, Registration).
+  - **필수**: Login(SignInForm), Registration(SignUpForm), 수강 신청 플로우(CourseRegistrationSchema, useRegistrationStore).
+  - **권장**: TanStack Query 훅(useCourseList, useFindCandidates, useRegisterCourse), 관리자 폼(UserCreateForm), 유틸(parseVtt, parseFeedbackContent), 훅(useCountdown).
 - **Auth**: Implement authentication flows using `better-auth`.
 
 ## 4. General Workflow

api/build.gradle.kts

@@ -34,6 +34,8 @@ dependencies {
     annotationProcessor("org.projectlombok:lombok")
 
     testImplementation("org.springframework.boot:spring-boot-starter-test")
+    testImplementation("org.testcontainers:testcontainers:1.20.4")
+    testImplementation("org.testcontainers:junit-jupiter:1.20.4")
     testRuntimeOnly("com.h2database:h2")
     testCompileOnly("org.projectlombok:lombok")
     testAnnotationProcessor("org.projectlombok:lombok")

api/src/main/java/org/junotb/api/schedule/ScheduleController.java

@@ -1,5 +1,7 @@
 package org.junotb.api.schedule;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.junotb.api.common.web.PageResponse;
@@ -16,13 +18,24 @@
 import java.util.Map;
 import java.util.Objects;
 
+/**
+ * 수업 스케줄 관리 API. 강사는 본인 스케줄 생성·수정·삭제, Meet 링크 등록.
+ */
+@Tag(name = "Schedule", description = "수업 스케줄 관리 API")
 @RestController
 @RequestMapping("/api/v1/schedule")
 @RequiredArgsConstructor
 public class ScheduleController {
     private final ScheduleService scheduleService;
 
-    // 스케줄 목록 조회
+    /**
+     * 스케줄 목록을 페이징하여 조회. 강사·코스·상태로 필터링 가능.
+     *
+     * @param request  필터 조건 (userId, courseId, status)
+     * @param pageable 페이징
+     * @return 페이징된 스케줄 목록
+     */
+    @Operation(summary = "스케줄 목록 조회", description = "강사·코스·상태로 필터링하여 페이징 조회합니다.")
     @GetMapping("")
     public PageResponse<ScheduleResponse> list(@ModelAttribute ScheduleListRequest request, Pageable pageable) {
         ScheduleListRequest safeRequest = Objects.requireNonNullElse(request, ScheduleListRequest.empty());
@@ -32,13 +45,27 @@ public PageResponse<ScheduleResponse> list(@ModelAttribute ScheduleListRequest r
         );
     }
 
-    // 스케줄 조회
+    /**
+     * ID로 스케줄 조회.
+     *
+     * @param id 스케줄 ID
+     * @return 스케줄 정보 (없으면 404)
+     */
+    @Operation(summary = "스케줄 조회", description = "ID로 스케줄을 조회합니다.")
     @GetMapping("/{id}")
     public ResponseEntity<ScheduleResponse> get(@PathVariable Long id) {
         return ResponseEntity.of(scheduleService.findById(id).map(ScheduleResponse::from));
     }
 
-    // 스케줄 생성
+    /**
+     * 새 수업 스케줄 생성. 인증된 사용자(강사)가 자신의 스케줄로 등록.
+     *
+     * @param userId  인증된 강사 ID
+     * @param request 생성 요청 (courseId, startsAt, endsAt, status)
+     * @return 생성된 스케줄
+     * @throws ResourceNotFoundException 강사 또는 코스 미존재 시
+     */
+    @Operation(summary = "스케줄 생성", description = "강사가 수업 일정을 등록합니다.")
     @PostMapping
     public ResponseEntity<ScheduleResponse> create(
         @AuthenticationPrincipal String userId,
@@ -48,7 +75,15 @@ public ResponseEntity<ScheduleResponse> create(
         return ResponseEntity.ok(ScheduleResponse.from(schedule));
     }
 
-    // 스케줄 수정
+    /**
+     * 스케줄 수정. null이 아닌 필드만 업데이트.
+     *
+     * @param id      스케줄 ID
+     * @param request 수정 요청 (startsAt, endsAt, status)
+     * @return 수정된 스케줄
+     * @throws ResourceNotFoundException 스케줄 미존재 시
+     */
+    @Operation(summary = "스케줄 수정", description = "null이 아닌 필드만 부분 수정합니다.")
     @PatchMapping("/{id}")
     public ResponseEntity<ScheduleResponse> update(
         @PathVariable Long id,
@@ -59,8 +94,16 @@ public ResponseEntity<ScheduleResponse> update(
     }
 
     /**
-     * 강사 전용. Meet 링크 등록/수정.
+     * 강사 전용. 해당 스케줄의 Google Meet 링크 등록/수정.
+     *
+     * @param id      스케줄 ID
+     * @param userId  인증된 강사 ID (본인 확인용)
+     * @param request meet 링크 요청
+     * @return 수정된 스케줄
+     * @throws ResourceNotFoundException 스케줄 미존재 시
+     * @throws IllegalStateException      요청자가 해당 스케줄의 강사가 아님
      */
+    @Operation(summary = "Meet 링크 등록/수정", description = "강사 전용. 수업의 Meet 링크를 등록하거나 수정합니다.")
     @PatchMapping("/{id}/meet-link")
     public ResponseEntity<ScheduleResponse> updateMeetLink(
         @PathVariable Long id,
@@ -71,14 +114,27 @@ public ResponseEntity<ScheduleResponse> updateMeetLink(
         return ResponseEntity.ok(ScheduleResponse.from(schedule));
     }
 
-    // 스케줄 삭제
+    /**
+     * 스케줄 삭제(취소). 논리 삭제로 상태를 CANCELED로 변경.
+     *
+     * @param id 스케줄 ID
+     * @return 204 No Content
+     * @throws ResourceNotFoundException 스케줄 미존재 시
+     */
+    @Operation(summary = "스케줄 삭제", description = "논리 삭제로 취소 처리합니다.")
     @DeleteMapping("/{id}")
     public ResponseEntity<Void> delete(@PathVariable Long id) {
         scheduleService.delete(id);
         return ResponseEntity.noContent().build();
     }
 
-    // 스케줄 상태별 통계 조회
+    /**
+     * 강사별 스케줄 상태 통계. 대시보드용.
+     *
+     * @param userId 인증된 강사 ID
+     * @return 상태(ScheduleStatus)별 건수
+     */
+    @Operation(summary = "상태별 통계", description = "강사의 스케줄 상태별 건수를 반환합니다.")
     @GetMapping("/stats/status")
     public ResponseEntity<Map<ScheduleStatus, Long>> countByStatus(@AuthenticationPrincipal String userId) {
         Map<ScheduleStatus, Long> stats = scheduleService.countByStatus(userId);

api/src/main/java/org/junotb/api/schedule/ScheduleService.java

@@ -1,6 +1,5 @@
 package org.junotb.api.schedule;
 
-import jakarta.persistence.EntityExistsException;
 import jakarta.persistence.criteria.Predicate;
 import lombok.RequiredArgsConstructor;
 import org.junotb.api.common.exception.ResourceNotFoundException;
@@ -20,6 +19,9 @@
 
 import java.util.*;
 
+/**
+ * 수업 스케줄 CRUD 및 통계 서비스.
+ */
 @Service
 @Transactional(readOnly = true)
 @RequiredArgsConstructor
@@ -28,31 +30,39 @@ public class ScheduleService {
     private final UserRepository userRepository;
     private final CourseRepository courseRepository;
 
-    // 스케줄 조회
+    /**
+     * ID로 스케줄 조회.
+     *
+     * @param id 스케줄 ID
+     * @return 스케줄 (없으면 Optional.empty())
+     */
     public Optional<Schedule> findById(Long id) {
         return scheduleRepository.findById(id);
     }
 
-    // 스케줄 목록 조회
+    /**
+     * 스케줄 목록 조회. Specification으로 동적 필터 적용.
+     *
+     * @param request  필터 (userId, courseId, status)
+     * @param pageable 페이징
+     * @return 페이징된 목록
+     */
     public Page<Schedule> findList(ScheduleListRequest request, Pageable pageable) {
         Specification<Schedule> spec = (root, query, cb) -> {
             List<Predicate> predicates = new ArrayList<>();
 
-            // 사용자 번호로 필터링
             if (request.userId() != null) {
                 predicates.add(
                     cb.equal(root.get("user").get("id"), request.userId())
                 );
             }
 
-            // 코스 번호로 필터링
             if (request.courseId() != null) {
                 predicates.add(
                     cb.equal(root.get("course").get("id"), request.courseId())
                 );
             }
 
-            // 스케줄 상태로 필터링
             if (request.status() != null) {
                 predicates.add(
                     cb.equal(root.get("status"), request.status())
@@ -65,15 +75,20 @@ public Page<Schedule> findList(ScheduleListRequest request, Pageable pageable) {
         return scheduleRepository.findAll(spec, pageable);
     }
 
-    // 스케줄 생성
+    /**
+     * 스케줄 생성. 강사·코스 존재 검증 후 저장.
+     *
+     * @param userId  강사(사용자) ID
+     * @param request 생성 요청
+     * @return 저장된 스케줄
+     * @throws ResourceNotFoundException 강사 또는 코스 미존재 시
+     */
     @Transactional
     public Schedule create(String userId, ScheduleCreateRequest request) {
-        // 강사(사용자) 존재 여부 확인
         User user = userRepository.findById(userId).orElseThrow(() ->
             new ResourceNotFoundException("User", userId)
         );
 
-        // 과목(코스) 존재 여부 확인
         Course course = courseRepository.findById(request.courseId()).orElseThrow(() ->
             new ResourceNotFoundException("Course", request.courseId().toString())
         );
@@ -89,15 +104,20 @@ public Schedule create(String userId, ScheduleCreateRequest request) {
         return scheduleRepository.save(schedule);
     }
 
-    // 스케줄 수정
+    /**
+     * 스케줄 수정. null이 아닌 필드만 업데이트.
+     *
+     * @param id      스케줄 ID
+     * @param request 수정 요청
+     * @return 수정된 스케줄
+     * @throws ResourceNotFoundException 스케줄 미존재 시
+     */
     @Transactional
     public Schedule update(Long id, ScheduleUpdateRequest request) {
-        // 스케줄 번호에 해당하는 스케줄 존재 여부 확인
         Schedule schedule = scheduleRepository.findById(id).orElseThrow(() ->
-            new EntityExistsException("Schedule not found with id: " + id)
+            new ResourceNotFoundException("Schedule", id.toString())
         );
 
-        // 수정할 필드만 업데이트
         if (request.startsAt() != null) schedule.setStartsAt(request.startsAt());
         if (request.endsAt() != null) schedule.setEndsAt(request.endsAt());
         if (request.status() != null) schedule.setStatus(request.status());
@@ -128,25 +148,32 @@ public Schedule updateMeetLink(Long scheduleId, String teacherId, ScheduleMeetLi
         return schedule;
     }
 
-    // 스케줄 삭제 (취소 처리)
+    /**
+     * 스케줄 삭제(취소). 이미 CANCELED면 idempotent로 조기 반환.
+     *
+     * @param id 스케줄 ID
+     * @throws ResourceNotFoundException 스케줄 미존재 시
+     */
     @Transactional
     public void delete(Long id) {
-        // 스케줄 번호에 해당하는 스케줄 존재 여부 확인
         Schedule schedule = scheduleRepository.findById(id).orElseThrow(
-            () -> new EntityExistsException("Schedule not found with id: " + id)
+            () -> new ResourceNotFoundException("Schedule", id.toString())
         );
 
-        // 이미 취소된 스케줄인 경우 처리하지 않음
         if (schedule.getStatus() == ScheduleStatus.CANCELED) return;
         schedule.setStatus(ScheduleStatus.CANCELED);
     }
 
-    // 상태별 스케줄 개수 조회
+    /**
+     * 강사별 상태별 스케줄 개수. countByStatus()가 반환하지 않는 상태는 0으로 초기화.
+     *
+     * @param userId 강사 ID
+     * @return 상태별 건수
+     */
     @Transactional(readOnly = true)
     public Map<ScheduleStatus, Long> countByStatus(String userId) {
         EnumMap<ScheduleStatus, Long> result = new EnumMap<>(ScheduleStatus.class);
 
-        // 모든 상태를 0으로 초기화
         for (ScheduleStatus status : ScheduleStatus.values()) {
             result.put(status, 0L);
         }

api/src/main/java/org/junotb/api/user/TeacherAvailabilityController.java

@@ -1,5 +1,7 @@
 package org.junotb.api.user;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.junotb.api.user.web.TeacherAvailabilityRequest;
@@ -10,19 +12,24 @@
 
 import java.util.List;
 
+/**
+ * 강사 가용 시간 설정 API. Time Block 사전 INSERT 대신 조회 시점 계산에 사용.
+ */
+@Tag(name = "Teacher Availability", description = "강사 가용 시간 설정 API")
 @RestController
 @RequestMapping("/api/v1/teachers")
 @RequiredArgsConstructor
 public class TeacherAvailabilityController {
     private final TeacherAvailabilityService teacherAvailabilityService;
 
     /**
-     * 강사의 가용 시간 설정을 업데이트합니다.
+     * 강사의 가용 시간 설정을 업데이트합니다. 기존 설정을 전체 교체.
      *
-     * @param userId 인증된 사용자 ID (강사)
+     * @param userId   인증된 사용자 ID (강사)
      * @param requests 가용 시간 설정 요청 목록
      * @return 업데이트된 가용 시간 설정 목록
      */
+    @Operation(summary = "가용 시간 업데이트", description = "강사의 요일별 가용 시간을 전체 교체합니다.")
     @PutMapping("/me/availability")
     public ResponseEntity<List<TeacherAvailabilityResponse>> updateAvailability(
             @AuthenticationPrincipal String userId,
@@ -39,6 +46,7 @@ public ResponseEntity<List<TeacherAvailabilityResponse>> updateAvailability(
      * @param userId 인증된 사용자 ID (강사)
      * @return 가용 시간 설정 목록
      */
+    @Operation(summary = "가용 시간 조회", description = "강사의 요일별 가용 시간을 조회합니다.")
     @GetMapping("/me/availability")
     public ResponseEntity<List<TeacherAvailabilityResponse>> getAvailability(
             @AuthenticationPrincipal String userId