# 수강신청 시스템 요구사항 - 작성일: 2026-09-16 - 대상 코드베이스: `course-registration` (Spring Boot 4.1.1 / Java 21 / JPA / H2(local) / PostgreSQL(prod)) - 상태: 구현·검증 완료, 2026-09-20 다관점 리뷰 반영 --- ## 1. 목표와 범위 ### 1.1 목표 학생이 개설된 강의에 수강신청하고 취소할 수 있는 API를 만든다. 이 문서의 핵심은 엔드포인트 개수가 아니라 **"어떤 신청을 거부해야 하는가"** 와 **"동시에 신청이 몰릴 때 어떻게 정확성을 지키는가"** 이다. ### 1.2 범위 안 (In scope) - 수강신청 / 취소 / 내 신청 목록 조회 - 개설 강의 목록 / 상세 조회 - 신청 거부 규칙 8종 (4절) - 동시 신청 시 정원·학점 정확성 보장 (5절) ### 1.3 범위 밖 (Non-goals) 아래는 **이번에 만들지 않는다.** 필요해지면 별도 문서로 다시 설계한다. | 항목 | 이유 | |---|---| | 인증 / 인가 (로그인, JWT) | 요청에 `userId`를 직접 담는다. 인증은 별도 프로젝트 크기의 일감이고, 수강신청 도메인 로직과 분리 가능하다 | | 강의 / 과목 / 교수 CRUD | 마스터 데이터는 `DataSeeder`로 투입한다 | | 신청 건 수정(U) API | 분반 변경은 "취소 후 재신청"이지 신청 건의 수정이 아니다 (7.3 참고) | | 대기열(waitlist), 장바구니 | 정원 초과 시 즉시 거부한다 | | 성적, 재수강, 선수과목 | 수강 이력 도메인이 따로 필요하다 | --- ## 2. 용어 | 용어 | 의미 | |---|---| | **Subject (과목)** | 교육과정상의 과목. "자료구조", 코드 `CS202`, 3학점. 학기와 무관한 정의 | | **Lesson (강의)** | 특정 학기에 특정 교수가 여는 Subject의 **분반**. "2026-1학기 자료구조 (최태영)" | | **LessonSchedule (시간 블록)** | Lesson이 매주 열리는 요일+시각 한 칸. "매주 월요일 09:00~11:00" | | **Registration (수강신청 건)** | 학생 한 명이 Lesson 하나를 신청한 기록. 엔티티 이름은 `UserLesson` | | **유효 신청** | `canceledAt IS NULL` 인 수강신청 건. 정원·학점·충돌 계산의 기준 | | **Semester (학기)** | 신청 기간과 학점 상한을 담는 단위 | --- ## 3. 도메인 모델 ### 3.1 관계도 ``` Semester 1 ──< N Lesson >── 1 Professor │ ├── 1 Subject │ ├──< N LessonSchedule │ └──< N UserLesson >── 1 User ``` ### 3.2 엔티티별 필드 기존 코드 대비 변경분을 `[신규] [추가] [삭제]`로 표시한다. #### Semester `[신규]` | 필드 | 타입 | 제약 | 설명 | |---|---|---|---| | id | String (UUID) | PK | `BaseTimeZoneEntity` 상속 | | name | String | not null, unique | `"2026-1"` | | startDate | LocalDate | not null | 학기 시작일 | | endDate | LocalDate | not null | 학기 종료일 | | registrationStartAt | Instant | not null | 수강신청 시작 시각 | | registrationEndAt | Instant | not null | 수강신청 마감 시각 | | maxCredits | Integer | not null | 이 학기 1인당 신청 학점 상한 (예: 18) | > 학점 상한을 Semester에 두는 이유: "이번 학기는 18학점까지"처럼 학기 단위 정책이기 때문이다. 역할별 차등(대학원생 12학점 등)이 필요해지면 `maxCredits`를 역할별 맵으로 확장한다. 이번엔 단일 값이다. #### Subject `[수정]` | 필드 | 타입 | 제약 | 비고 | |---|---|---|---| | id, name, code, description | | | 기존 유지 | | **credit** | Integer | not null, 1 이상 | `[추가]` 학점. 학점 상한 검증의 근거 | #### Professor 변경 없음. #### Lesson `[수정]` | 필드 | 타입 | 제약 | 비고 | |---|---|---|---| | id, name | | | 기존 유지 | | subject | ManyToOne | not null | 기존 유지 | | professor | ManyToOne | not null | 기존 유지 | | ~~startTime~~ | ~~Instant~~ | | `[삭제]` → `LessonSchedule`로 이동 | | ~~endTime~~ | ~~Instant~~ | | `[삭제]` → `LessonSchedule`로 이동 | | **semester** | ManyToOne | not null | `[추가]` 어느 학기 강의인가 | | **capacity** | Integer | not null, 1 이상 | `[추가]` 정원 | | **minGrade** | Long | nullable | `[추가]` 이 학년 **이상**만 수강 가능. `null` = 전 학년 | | **allowedRole** | UserRole | nullable | `[추가]` 이 역할만 수강 가능. `null` = 전체 | > `startTime/endTime`을 삭제하는 이유: `Instant`는 "2026-03-02T09:00Z"라는 **특정 시점 1회**를 뜻한다. "매주 월요일 9시"라는 반복을 표현할 수 없고, 강의 하나가 월·수 주 2회인 경우도 담을 수 없다. #### LessonSchedule `[신규]` | 필드 | 타입 | 제약 | 설명 | |---|---|---|---| | id | String (UUID) | PK | | | lesson | ManyToOne | not null | 소속 강의 | | dayOfWeek | java.time.DayOfWeek | not null | MONDAY ~ FRIDAY | | startTime | LocalTime | not null | `09:00` | | endTime | LocalTime | not null | `11:00`. `startTime`보다 커야 한다 | 예시 — "자료구조"가 월·수 주 2회인 경우 행 2개: ``` lesson_schedules id lesson_id day_of_week start_time end_time s1 l2 MONDAY 09:00 11:00 s2 l2 WEDNESDAY 09:00 11:00 ``` #### User `[수정]` | 필드 | 타입 | 비고 | |---|---|---| | id, name, grade, role | | 기존 유지 | 필드 변경은 없다. 다만 5절에서 **User 행에 비관적 락을 건다.** #### UserLesson `[수정]` | 필드 | 타입 | 제약 | 비고 | |---|---|---|---| | **id** | String (UUID) | PK | `[추가]` 복합키를 대리키로 교체 | | user | ManyToOne | not null | `user_id` FK, 기존 유지 | | lesson | ManyToOne | not null | `lesson_id` FK, 기존 유지 | | createdAt | Instant | not null | 신청 시각. `BaseCreateEntity` | | **canceledAt** | Instant | nullable | `[추가]` 취소 시각. `null` = 유효 신청 | 동반 변경: - `UserLessonId.java` **삭제** — 복합키를 쓰지 않는다 - `BaseCreateEntity`가 `BaseEntity`를 상속하도록 변경 (id + createdAt) - `UserLessonRepository`의 ID 타입: `UserLessonId` → `String` > `(user_id, lesson_id)` 자체에는 UNIQUE를 걸지 않는다. 취소 후 재신청 이력을 남겨야 하기 때문이다. 대신 `canceled_at IS NULL`일 때만 `lesson_id`를 노출하는 생성 컬럼 `active_lesson_id`를 두고 `(user_id, active_lesson_id)` UNIQUE를 건다. H2와 PostgreSQL에서 같은 제약을 사용하며, User 락과 함께 이중 방어한다. ### 3.3 ID 전략 애플리케이션 식별자는 현재 `String UUID`로 통일하고 DB 컬럼은 H2/PostgreSQL 모두 `VARCHAR(36)`을 사용한다. 신규 운영 데이터가 없는 시점이라 PostgreSQL native `uuid`로 바꿀 수는 있지만, 이번 범위에서는 JPA/API 타입과 양 DB migration을 동시에 흔드는 변경보다 동시성·배포 불변식 고정을 우선한다. native `uuid` 전환은 별도 스키마 변경으로 분리한다. 마스터 엔티티는 현재 런타임 CRUD API가 없고 Seeder/Flyway로만 투입한다. 향후 마스터 수정 기능을 추가하면 신청 transaction이 User/Lesson을 락 쿼리로 처음 읽는다는 전제를 깨지 않는지 함께 검토한다. --- ## 4. 비즈니스 규칙 ### 4.1 신청 거부 규칙 8종 아래 조건 중 하나라도 걸리면 신청을 거부하고, **가장 먼저 걸린 규칙의 에러 코드 하나만** 반환한다. | # | 규칙 | 판정 조건 | 에러 코드 | HTTP | |---|---|---|---|---| | R1 | 신청 기간 | `now`가 `[registrationStartAt, registrationEndAt]` 밖 | `REGISTRATION_PERIOD_CLOSED` | 409 | | R2 | 학년 제한 | `lesson.minGrade != null && user.grade < lesson.minGrade` | `NOT_ELIGIBLE_GRADE` | 403 | | R3 | 역할 제한 | `lesson.allowedRole != null && user.role != lesson.allowedRole` | `NOT_ELIGIBLE_ROLE` | 403 | | R4 | 중복 신청 | 같은 `lesson`의 유효 신청이 이미 있음 | `ALREADY_REGISTERED` | 409 | | R5 | 동일 과목 중복 | 같은 학기·같은 `subject`의 **다른 분반** 유효 신청이 있음 | `DUPLICATE_SUBJECT` | 409 | | R6 | 시간표 충돌 | 신청 강의의 시간 블록이 기존 유효 신청과 겹침 | `SCHEDULE_CONFLICT` | 409 | | R7 | 학점 상한 | `기존 유효 신청 학점 합 + 신청 강의 학점 > semester.maxCredits` | `CREDIT_LIMIT_EXCEEDED` | 409 | | R8 | 정원 초과 | `해당 강의 유효 신청 수 >= lesson.capacity` | `CAPACITY_EXCEEDED` | 409 | > R4는 R5에 포함되는 관계지만(같은 분반이면 같은 과목이므로) **분리한다.** "이미 신청한 강의입니다"와 "같은 과목의 다른 분반을 이미 신청했습니다"는 학생이 취해야 할 행동이 다르기 때문이다. ### 4.2 R5·R6·R7의 계산 범위 셋 다 "이 학생의 다른 신청"을 봐야 하는 규칙이다. 조회 범위를 명확히 한다. - 대상: `user_id = 신청자` AND `canceled_at IS NULL` AND `lesson.semester_id = 신청 강의의 학기` - **다른 학기 신청은 계산에 넣지 않는다.** 2026-1학기 18학점은 2026-2학기 신청과 무관하다. ### 4.3 시간표 충돌 판정 두 시간 블록 A, B가 겹친다는 것은: ``` A.dayOfWeek == B.dayOfWeek AND A.startTime < B.endTime AND B.startTime < A.endTime ``` **경계는 겹침이 아니다.** 09:00~11:00 강의와 11:00~13:00 강의는 신청 가능하다. (`A.end == B.start` 이면 두 번째 조건이 거짓) 신청 강의의 시간 블록이 여러 개이므로, **모든 조합**을 검사해서 하나라도 겹치면 거부한다. ### 4.4 취소 규칙 | 규칙 | 조건 | 에러 코드 | HTTP | |---|---|---|---| | C1 | 신청 건이 존재하지 않음 | `REGISTRATION_NOT_FOUND` | 404 | | C2 | 경로의 `userId`와 신청 건의 소유자가 다름 | `REGISTRATION_FORBIDDEN` | 403 | | C3 | 이미 취소된 건 (`canceledAt != null`) | 멱등 성공 | 204 | | C4 | 신청 기간이 지남 | `REGISTRATION_PERIOD_CLOSED` | 409 | 취소는 행을 삭제하지 않고 `canceledAt = now()`를 기록한다. 같은 DELETE를 재호출하면 이미 원하는 상태이므로 204를 그대로 반환한다. ### 4.5 데이터 무결성 규칙 마스터 데이터가 아래 규칙을 깨면 신청 판정이 잘못된다. 따라서 한 계층에만 맡기지 않고 중복 방어한다. - `Lesson.capacity >= 1` - `Subject.credit >= 1` - `LessonSchedule.startTime < endTime` - `Semester.registrationStartAt < registrationEndAt` - 같은 Lesson 안의 시간 블록끼리는 서로 겹치지 않는다 현재 구현은 단일 엔티티에서 판정 가능한 값은 생성자에서 거부하고, Seeder는 `LessonSchedulePolicy`로 같은 Lesson의 시간 블록 겹침까지 검증한다. Flyway에는 범위 `CHECK`, exact schedule `UNIQUE`, 유효 신청 `UNIQUE`를 두어 DB도 마지막 방어선이 된다. --- ## 5. 동시성 설계 — 이 문서에서 가장 중요한 부분 ### 5.1 문제 정원 30명, 현재 29명인 강의에 두 학생이 동시에 신청한다. ``` 시각 요청 A 요청 B t1 COUNT -> 29 (29 < 30 통과) t2 COUNT -> 29 (29 < 30 통과) t3 INSERT t4 INSERT 결과: 31명 ``` 단순 COUNT 검증으로는 막을 수 없다. 읽기와 쓰기 사이에 다른 트랜잭션이 끼어들기 때문이다. ### 5.2 Lesson 락만으로는 부족하다 "신청 시 Lesson 행을 `FOR UPDATE`로 잠근다"는 R8(정원)은 해결하지만, **R5·R6·R7은 여전히 뚫린다.** R5·R6·R7은 "이 학생의 다른 신청"을 보는 규칙이다. 한 학생이 **서로 다른 두 강의**를 동시에 신청하면 잠기는 Lesson 행이 서로 달라서 두 요청이 나란히 진행된다. ``` 학생 u1, 현재 15학점, 상한 18학점 t1 요청 A: lesson_X(3학점) 신청, lessons.X 잠금 t2 요청 B: lesson_Y(3학점) 신청, lessons.Y 잠금 <- 다른 행이라 안 막힘 t3 A: 15 + 3 = 18 <= 18 통과 t4 B: 15 + 3 = 18 <= 18 통과 <- B는 A의 INSERT를 아직 못 봄 t5 둘 다 INSERT -> 21학점 ``` 시간표 충돌(R6)도 같은 방식으로 뚫린다. ### 5.3 해결: User 락 → Lesson 락, 순서 고정 ``` BEGIN 1. SELECT * FROM users WHERE id = :userId FOR UPDATE -> 같은 학생의 신청 요청을 전부 직렬화한다. R5·R6·R7을 보장 2. SELECT * FROM lessons WHERE id = :lessonId FOR UPDATE -> 같은 강의의 신청 요청을 전부 직렬화한다. R8을 보장 3. 검증 R4 ~ R8 수행 4. INSERT INTO user_lessons (id, user_id, lesson_id, created_at, canceled_at) VALUES (:uuid, :userId, :lessonId, now(), NULL) COMMIT ``` **락 획득 순서를 항상 User → Lesson으로 고정한다.** 순서를 섞으면 데드락이 생긴다. > 예: 요청 A가 `user1 → lessonX` 순으로 잠그고, 요청 B가 `lessonX → user1` 순으로 잠그면, A는 lessonX를, B는 user1을 서로 기다리며 영원히 멈춘다. 항상 같은 순서로만 잠그면 이 상황이 만들어지지 않는다. ### 5.4 검증 위치 — 락 획득 후 최신 값으로 판정 신청 mutation은 User와 Lesson을 **락 쿼리로 처음 읽는다.** 일반 조회 후 같은 영속성 컨텍스트에서 `findByIdForUpdate`를 다시 호출하면 Hibernate가 락 모드만 올리고 이미 읽은 엔티티 값을 그대로 사용할 수 있기 때문이다. | 검증 | 위치 | 이유 | |---|---|---| | 사용자 존재 | User `FOR UPDATE` 조회 | 존재 확인과 락 획득을 한 쿼리로 묶는다 | | 강의 존재 | Lesson `FOR UPDATE` 조회 | 락 이전 stale entity를 만들지 않는다 | | R1 신청 기간 | **락 안 + INSERT 직전 재검증** | 락 대기 중 마감 시각을 지날 수 있다 | | R2 ~ R8 | **락 안** | 동일 학생·강의의 경쟁 요청과 같은 기준으로 판정한다 | R1은 `registrationEndAt` 정각까지 포함한다. 따라서 `now.isAfter(registrationEndAt)`일 때만 마감으로 본다. ### 5.5 구현 메모 - application은 `RegistrationExecutionScopeLoader.open()`으로 실행 범위를 확보한다. 실제 User → Lesson `FOR UPDATE`는 `JpaRegistrationExecutionScopeLoader`가 구현하고 application contract에는 lock 용어를 노출하지 않는다 - Spring Data Repository의 `@Lock(LockModeType.PESSIMISTIC_WRITE)`는 infrastructure adapter 뒤에서만 사용한다 - `RegisterCourseUseCase`/`CancelRegistrationUseCase` mutation 전체에 `@Transactional`을 건다. 락은 커밋 시점에 풀린다 - H2와 PostgreSQL 모두 `FOR UPDATE`를 지원하지만 **락 타임아웃 적용 방식은 같지 않다** - H2 local/test: JDBC URL의 `LOCK_TIMEOUT=3000` - PostgreSQL dev/prod: connection 초기 SQL `SET lock_timeout TO '3s'` - 락 타임아웃은 503 `LOCK_TIMEOUT`으로 변환하고 `Retry-After` 1~3초를 내려 재시도 동시화를 완화한다 - 엔티티에는 `@Version`을 둬 예상하지 못한 동시 갱신도 감지한다 - 수강신청 기간에는 판정에 쓰는 master policy data(`Subject.credit`, `Semester.maxCredits`, 신청 기간, `Lesson.capacity/minGrade/allowedRole`, `LessonSchedule`)를 수정하지 않는다. 향후 관리자 수정 기능이 생기면 이 전제를 대체할 snapshot/lock 전략을 먼저 정의한다. ### 5.6 이 설계의 비용 같은 학생의 신청 요청은 직렬화된다. 같은 강의의 신청 요청도 직렬화된다. **처리량은 떨어진다.** 수강신청은 초당 수만 건을 받아야 하는 도메인이 아니고, 정원 초과와 학점 초과가 실제 사고로 이어지는 도메인이므로 정확성을 택한다. --- ## 6. API 명세 공통: - Base path: `/api/v1` - Content-Type: `application/json` - 시각은 ISO-8601 UTC (`2026-03-02T00:00:00Z`) - 인증 없음. 신청자는 경로의 `{userId}`로 식별한다 ### 6.1 수강신청 ``` POST /api/v1/users/{userId}/registrations ``` Request ```json { "lessonId": "b2c4f1a0-..." } ``` Response `201 Created` ```json { "registrationId": "e8d1...", "userId": "a1b2...", "lessonId": "b2c4...", "lessonName": "자료구조", "subjectCode": "CS202", "credit": 3, "registeredAt": "2026-02-01T01:00:00Z", "totalCredits": 18 } ``` `totalCredits`는 신청 후 해당 학기 누적 학점이다. 클라이언트가 재조회 없이 남은 학점을 보여줄 수 있다. 선택적으로 `Idempotency-Key` 헤더를 받을 수 있다. 보존 기간은 **24시간**이다. - TTL 안에서 같은 사용자·같은 key·같은 lesson 재시도는 최초 신청 결과를 재사용한다. - 최초 신청을 취소한 뒤 같은 key로 다시 POST해도 TTL 안이면 새 신청을 만들지 않고 최초 POST 결과를 replay한다. - TTL 안에서 같은 key를 다른 lesson에 재사용하면 `IDEMPOTENCY_KEY_REUSED` 409를 반환한다. - 만료된 key 행은 주기적으로 삭제하며, 삭제 후 같은 key는 새 요청으로 다시 사용할 수 있다. 에러: R1~R8 (4.1절 표) ### 6.2 내 신청 목록 조회 ``` GET /api/v1/users/{userId}/registrations?semesterId={semesterId} ``` `semesterId` 생략 시 `SemesterSelectionPolicy`가 현재 시각이 신청 기간 `[registrationStartAt, registrationEndAt]`에 포함되는 학기를 우선 선택한다. 그런 학기가 없으면 오늘이 `[startDate, endDate]`에 포함되는 학기를 fallback으로 쓴다. 같은 기준에 맞는 학기가 2개 이상이면 임의로 하나를 고르지 않고 데이터 오류로 실패시킨다. Response `200 OK` ```json { "userId": "a1b2...", "semesterId": "s1...", "semesterName": "2026-1", "totalCredits": 18, "maxCredits": 18, "registrations": [ { "registrationId": "e8d1...", "lessonId": "b2c4...", "lessonName": "자료구조", "subjectCode": "CS202", "subjectName": "자료구조", "credit": 3, "professorName": "최태영", "schedules": [ { "dayOfWeek": "MONDAY", "startTime": "09:00", "endTime": "11:00" }, { "dayOfWeek": "WEDNESDAY", "startTime": "09:00", "endTime": "11:00" } ], "registeredAt": "2026-02-01T01:00:00Z" } ] } ``` **취소된 건은 포함하지 않는다.** (`canceledAt IS NULL`만 조회) ### 6.3 수강신청 취소 ``` DELETE /api/v1/users/{userId}/registrations/{registrationId} ``` Response `204 No Content` 이미 취소된 신청에 같은 DELETE를 다시 보내도 204를 반환한다. 에러: C1, C2, C4 (4.4절 표) ### 6.4 개설 강의 목록 ``` GET /api/v1/lessons?semesterId={id}&subjectId={id}&page=0&size=20 ``` `semesterId` 생략 시 신청 기간이 열린 학기를 우선하고, 없으면 진행 중인 학기로 fallback한다. `subjectId`는 선택 필터. Response `200 OK` ```json { "page": 0, "size": 20, "totalElements": 3, "lessons": [ { "lessonId": "b2c4...", "lessonName": "자료구조", "subjectCode": "CS202", "subjectName": "자료구조", "credit": 3, "professorName": "최태영", "capacity": 30, "enrolledCount": 29, "minGrade": 2, "allowedRole": null, "schedules": [ { "dayOfWeek": "MONDAY", "startTime": "09:00", "endTime": "11:00" }, { "dayOfWeek": "WEDNESDAY", "startTime": "09:00", "endTime": "11:00" } ] } ] } ``` > `enrolledCount`는 조회 시점의 스냅샷이다. 표시가 29여도 신청이 `CAPACITY_EXCEEDED`로 실패할 수 있다. 정원의 진짜 판정은 5.3절 락 안에서만 일어난다. 클라이언트는 이 값을 참고용으로만 써야 한다. **N+1 방지:** 페이지의 Lesson을 먼저 조회한 뒤 해당 `lessonId` 집합으로 시간표를 `IN` 벌크 조회하고, `enrolledCount`는 `GROUP BY lesson_id` 집계 한 번으로 가져온다. 컬렉션 fetch join과 pagination을 섞지 않는다. 쿼리 수 상한은 통합 테스트로 고정한다. ### 6.5 강의 상세 ``` GET /api/v1/lessons/{lessonId} ``` Response `200 OK` — 6.4의 항목 하나 + `subjectDescription`, `semesterName`, `registrationStartAt`, `registrationEndAt` 에러: `LESSON_NOT_FOUND` 404 ### 6.6 CRUD 매핑 | CRUD | 엔드포인트 | |---|---| | Create | 6.1 수강신청 | | Read | 6.2 내 신청 목록 / 6.4 강의 목록 / 6.5 강의 상세 | | Update | **없음** — 7.3 참고 | | Delete | 6.3 취소 (soft delete) | --- ## 7. 설계 판단 근거 설계 리뷰 시 다시 논의될 만한 결정들. 뒤집을 때 무엇을 감수해야 하는지 적어둔다. ### 7.1 왜 시간표를 별도 테이블로 뺐나 `Lesson`에 `Instant startTime/endTime` 한 쌍을 두면 "특정 날짜 1회"만 표현된다. 대학 강의는 (a) 학기 내내 매주 반복되고 (b) 주 2회로 쪼개지는 경우가 흔하다. 두 성질 모두 1:N 테이블이 아니면 담을 수 없다. 대안이었던 "요일 + 교시(정수)"는 겹침 판정이 정수 비교라 더 단순하지만, 교시↔실제 시각 매핑표가 따로 필요하고 30분 단위 변칙 강의를 담지 못한다. ### 7.2 유효 신청 중복을 DB와 락이 함께 막는 이유 `(user_id, lesson_id)` UNIQUE는 취소 후 재신청 이력을 막으므로 사용할 수 없다. PostgreSQL의 partial unique index만 사용하면 H2 local과 DDL이 달라진다. 현재는 `canceled_at IS NULL`일 때 `lesson_id`를 반환하고 취소된 행은 `NULL`을 반환하는 생성 컬럼 `active_lesson_id`를 둔다. 그 위에 `UNIQUE(user_id, active_lesson_id)`를 걸어 H2와 PostgreSQL에서 같은 방식으로 **유효 신청 중복만** 차단한다. User 락은 R5~R7 직렬화와 일관된 판정을 담당하고, DB UNIQUE는 R4 중복에 대한 최종 방어선이다. ### 7.3 왜 수정(U) API가 없나 수강신청에서 "A분반을 B분반으로 바꾼다"는 신청 건의 필드 수정이 아니다. **A를 취소해서 정원 1칸을 반납하고, B에 새로 신청해서 정원 1칸을 점유하는 두 개의 사건**이다. 이걸 하나의 UPDATE로 만들면 두 강의의 정원을 동시에 건드리게 되고, 락을 두 Lesson에 걸어야 해서 데드락 위험이 생긴다. 취소 + 신청 두 번의 호출로 두면 각 호출이 5.3절 절차를 그대로 따른다. 뒤집을 경우: "변경" 엔드포인트를 만들려면 Lesson 락을 `lessonId` 오름차순으로 두 개 잡는 규칙을 추가해야 한다. ### 7.4 왜 인증이 없나 이번 목표는 수강신청 도메인 규칙이다. 인증은 그 자체로 별도 설계가 필요하고, 나중에 붙일 때 서비스 계층을 건드리지 않는다(컨트롤러가 `userId`를 어디서 얻느냐만 바뀐다). 지금 넣으면 검증 로직에 도달하기 전에 시간을 다 쓴다. **보안상 주의:** 현재 설계는 누구든 남의 `userId`로 신청·취소할 수 있다. 학습용이라 허용하지만, 공개 배포 대상이 아니다. --- ## 8. 에러 응답 ### 8.1 공통 형식 ```json { "code": "CAPACITY_EXCEEDED", "message": "정원이 가득 찼습니다. (30/30)", "timestamp": "2026-02-01T01:00:00Z" } ``` `@RestControllerAdvice` 하나로 처리한다. ### 8.2 에러 코드 전체 | code | HTTP | 발생 조건 | |---|---|---| | `VALIDATION_ERROR` | 400 | 요청 바디 형식 오류 (`lessonId` 누락 등) | | `USER_NOT_FOUND` | 404 | `userId`에 해당하는 사용자 없음 | | `LESSON_NOT_FOUND` | 404 | `lessonId`에 해당하는 강의 없음 | | `SEMESTER_NOT_FOUND` | 404 | `semesterId` 없음 / 진행 중인 학기 없음 | | `REGISTRATION_NOT_FOUND` | 404 | `registrationId` 없음 | | `NOT_ELIGIBLE_GRADE` | 403 | R2 학년 미달 | | `NOT_ELIGIBLE_ROLE` | 403 | R3 역할 불일치 | | `REGISTRATION_FORBIDDEN` | 403 | C2 남의 신청 건 취소 시도 | | `REGISTRATION_PERIOD_CLOSED` | 409 | R1 / C4 신청 기간 밖 | | `ALREADY_REGISTERED` | 409 | R4 같은 강의 중복 | | `DUPLICATE_SUBJECT` | 409 | R5 같은 과목 다른 분반 | | `SCHEDULE_CONFLICT` | 409 | R6 시간표 충돌 | | `CREDIT_LIMIT_EXCEEDED` | 409 | R7 학점 상한 초과 | | `CAPACITY_EXCEEDED` | 409 | R8 정원 초과 | | `IDEMPOTENCY_KEY_REUSED` | 409 | 같은 Idempotency-Key를 다른 강의에 재사용 | | `LOCK_TIMEOUT` | 503 | 락 대기 타임아웃 (5.5절) | | `INTERNAL_SERVER_ERROR` | 500 | 예상하지 못한 서버 오류 / 필수 시간표 데이터 누락 | `message`는 한국어로, 가능하면 **숫자를 포함한다.** "정원이 찼습니다"보다 "정원이 가득 찼습니다. (30/30)"가, "학점 초과"보다 "신청 학점이 상한을 넘습니다. (18 + 3 > 18)"가 학생이 다음 행동을 정하는 데 쓸모 있다. --- ### 8.3 실패 taxonomy와 HTTP 경계 `RegistrationErrorCode`는 HTTP status를 알지 않는다. Application/Domain은 실패의 의미만 만들고, Web의 `FailureHttpMapper`가 기존 API status 계약으로 변환한다. | 분류 | 예 | 로그/복구 | |---|---|---| | Request validation | 잘못된 body, Idempotency-Key 길이 | 400, ERROR stacktrace 없음 | | Resource not found | 사용자/강의/학기/신청 없음 | 404, 정상 application failure | | Business rejection | 정원/학점/시간표/중복/기간 | 403/409, ERROR stacktrace 없음, metric 집계 | | Authorization failure | 다른 사용자 신청 취소 | 403 | | Retryable infrastructure | DB lock timeout | 503 + Retry-After, WARN | | System invariant violation | 활성 학기 중복, 필수 시간표 누락 | 500, ERROR + invariant metric | | Unexpected failure | 분류되지 않은 예외 | 500, ERROR | `SystemInvariantViolation`은 사용자의 입력을 바꿔 해결할 수 있는 실패가 아니다. 신청 가능한 강의에 시간표가 없으면 domain/application은 HTTP 500 표현을 직접 만들지 않고 invariant failure를 발생시키며, Web adapter가 외부 계약상 500으로 변환한다. --- ## 9. 시드 데이터 요구사항 `DataSeeder`는 `local/dev` profile에서만 존재하며 `app.seed.enabled=true`일 때 아래 demo 데이터를 넣는다. `prod`에서는 profile과 설정 양쪽에서 비활성화한다. 10절의 테스트 시나리오가 이 데이터를 전제한다. - Semester 1개: local/dev 샘플이 장기간 유지돼도 만료되지 않도록 넓은 고정 학기·신청 기간을 TSV에 명시, `maxCredits = 18` - Professor 3명 (기존 유지) - Subject 3개 + `credit` (예: 3, 3, 3) - Lesson 3개 이상, 아래 조건을 만족하도록 구성: - **시간표가 겹치는 강의 쌍**이 최소 1개 (R6 테스트용) - **같은 Subject의 다른 분반**이 최소 1쌍 (R5 테스트용) - **정원이 1인 강의**가 최소 1개 (R8 테스트용) - **`minGrade = 3`인 강의**가 최소 1개 (R2 테스트용) - **`allowedRole = POSTGRADUATE`인 강의**가 최소 1개 (R3 테스트용) - User 3명 (기존 유지: 1학년 학생, 2학년 학생, 대학원생) > seed 원본은 `src/main/resources/seed/demo/*.tsv`에 둔다. 데이터가 늘어나면 Java 코드를 수정하지 않고 행을 추가한다. `DataSeeder`는 TSV 파싱·관계 조립·도메인 정책 검증만 담당한다. 여러 인스턴스가 동시에 시작할 때는 `seed_locks` 행을 `FOR UPDATE`로 잠가 한 인스턴스만 데이터를 넣는다. --- ## 10. 테스트 시나리오 구현 시 이 목록이 테스트 케이스가 된다. 각 항목은 **하나의 규칙만** 검증한다. ### 10.1 정상 경로 | # | 시나리오 | 기대 | |---|---|---| | T1 | 조건을 모두 만족하는 신청 | 201, `user_lessons` 행 1개 생성 | | T2 | 신청 후 목록 조회 | 200, 해당 건 포함, `totalCredits` 일치 | | T3 | 신청 후 취소 | 204, `canceledAt` 세팅됨 | | T4 | 취소 후 같은 강의 재신청 | 201, 행이 2개(취소 1 + 유효 1) | | T5 | 취소 후 목록 조회 | 취소 건은 목록에 없음 | | T6 | 정원이 찬 강의를 누가 취소하면 | 다음 신청이 성공 | ### 10.2 거부 경로 — 규칙별 1개씩 | # | 시나리오 | 기대 | |---|---|---| | T7 | 신청 기간 전/후에 신청 | 409 `REGISTRATION_PERIOD_CLOSED` | | T8 | 1학년이 `minGrade=3` 강의 신청 | 403 `NOT_ELIGIBLE_GRADE` | | T9 | 학부생이 `allowedRole=POSTGRADUATE` 강의 신청 | 403 `NOT_ELIGIBLE_ROLE` | | T10 | 같은 강의 두 번 신청 | 409 `ALREADY_REGISTERED` | | T11 | 같은 과목의 다른 분반 신청 | 409 `DUPLICATE_SUBJECT` | | T12 | 시간이 겹치는 강의 신청 | 409 `SCHEDULE_CONFLICT` | | T13 | 상한을 넘는 학점 신청 | 409 `CREDIT_LIMIT_EXCEEDED` | | T14 | 정원 1인 강의에 두 번째 신청 | 409 `CAPACITY_EXCEEDED` | | T15 | 남의 신청 건 취소 | 403 `REGISTRATION_FORBIDDEN` | | T16 | 이미 취소한 건 또 취소 | 204 (멱등 성공) | ### 10.3 경계값 | # | 시나리오 | 기대 | |---|---|---| | T17 | 09:00~11:00 신청 후 11:00~13:00 신청 | 201 (경계는 충돌 아님) | | T18 | 정확히 상한 학점이 되는 신청 (15 + 3 = 18) | 201 | | T19 | 정원 마지막 1칸 신청 (29/30 → 30/30) | 201 | | T20 | `registrationEndAt` 정각에 신청 | 201 (경계 포함) | | T21 | 요일은 겹치는데 시간은 안 겹침 (월 09-11 vs 월 13-15) | 201 | | T22 | 시간은 겹치는데 요일이 다름 (월 09-11 vs 화 09-11) | 201 | ### 10.4 동시성 — 5절 검증 이게 이 프로젝트의 핵심 테스트다. `ExecutorService` + `CountDownLatch`로 동시 요청을 만든다. | # | 시나리오 | 기대 | |---|---|---| | T23 | 정원 1인 강의에 **동시 10명** 신청 | 성공 1건, 실패 9건, 유효 행 정확히 1개 | | T24 | 정원 30인 강의에 **동시 50명** 신청 | 성공 정확히 30건, 유효 행 30개 | | T25 | **한 학생**이 서로 다른 강의 2개를 **동시** 신청 (각 3학점, 잔여 3학점) | 성공 1건, 실패 1건 `CREDIT_LIMIT_EXCEEDED`. **5.2절의 구멍이 막혔는지 보는 테스트** | | T26 | **한 학생**이 시간이 겹치는 두 강의를 **동시** 신청 | 성공 1건, 실패 1건 `SCHEDULE_CONFLICT` | | T27 | **한 학생**이 같은 강의를 **동시** 2번 신청 | 성공 1건, 실패 1건 `ALREADY_REGISTERED` | > T25와 T26은 **User 락이 없으면 반드시 실패한다.** 5.2절에서 지적한 구멍을 그대로 재현하는 테스트이므로, 락 설계를 바꿀 때 회귀를 잡아주는 기준선이 된다. --- ## 11. 구현 구조 | 영역 | 주요 타입 | 책임 | |---|---|---| | `web/controller` | `CourseRegistrationController`, `LessonController` | HTTP input/output, DTO ↔ application command/result 변환 | | `web/error` | `ApiExceptionHandler`, `FailureHttpMapper`, `FailureMetrics` | failure → HTTP/log/metric 표현 | | `application/registration` | `RegisterCourseUseCase`, `CancelRegistrationUseCase`, `GetRegistrationsQuery` | transaction과 업무 흐름 orchestration | | `application/lesson` | `GetLessonsQuery`, `GetLessonQuery` | 강의 조회 UseCase | | `application/idempotency` | `IdempotencyCoordinator`, `CleanupIdempotencyUseCase` | normalize/TTL/replay 판정/record orchestration | | `application/*/port` | `RegistrationExecutionScopeLoader`, `RegistrationDecisionContextLoader`, `CancellationContextLoader`, `RegistrationReader`, `RegistrationWriter`, `LessonQueryPort`, `SemesterQueryPort`, `IdempotencyPort` | application이 요구하는 업무 capability | | `domain/registration` | `RegistrationContext`, snapshot, `RegistrationPolicy`, `RegistrationWindowGuard` | persistence와 독립된 신청 decision model/policy | | `domain/registration/rule` | R1~R8 rule | 한 규칙당 한 변경 이유 | | `domain/schedule` | `ScheduleSlot`, `LessonSchedulePolicy`, `ScheduleConflictChecker` | persistence와 독립된 시간표 invariant/충돌 | | `infrastructure/persistence` | `Jpa*Adapter`, `JpaRegistrationExecutionScopeLoader`, `JpaRegistrationDecisionContextLoader`, `JpaCancellationContextLoader`, `JpaSnapshotMapper` | JPA Entity ↔ snapshot/read model 변환, query, lock, pagination | | `infrastructure/scheduling` | `IdempotencyRetentionJob` | scheduler adapter | | `failure` | `ApplicationFailure`, `SystemInvariantViolation` | HTTP와 독립된 실패 의미 | | `infrastructure/persistence/repository` | Spring Data repository | JPA adapter가 사용하는 persistence mechanism | 의존 방향은 `web -> application -> domain/port <- infrastructure`를 유지한다. 아키텍처 정책은 **strict clean boundary**로 고정한다. - Application/Domain에는 JPA Entity가 전달되지 않는다. - Port는 snapshot/read model/command만 사용한다. - Domain은 Spring Framework/JPA annotation에 의존하지 않는다. - Spring wiring은 `config/DomainPolicyConfig`에서 수행한다. - Query는 `LessonListView`, `LessonDetailView`, `ActiveRegistrationView` 같은 read model을 infrastructure에서 조립한다. - `ArchitectureTest`가 위 의존 규칙을 자동 검증한다. --- ## 12. 열려 있는 항목 구현 중 결정해도 되는 것들. 지금 막히지 않는다. | 항목 | 메모 | |---|---| | 락 타임아웃 값 | 3초로 시작하고 T24에서 조정 | | 강의 목록 페이지 기본 size | 20 | | `maxCredits` 역할별 차등 | 단일 값으로 시작. 필요해지면 확장 | | `minGrade` vs 정확한 학년 지정 | "이 학년 이상"으로 시작. "2~3학년만" 같은 요구가 생기면 `maxGrade` 추가 | | Idempotency-Key 보존 기간 | 24시간, 1시간 주기 cleanup으로 시작 | | PostgreSQL native `uuid` PK | 현재 `String UUID + VARCHAR(36)` 유지. 별도 스키마 변경으로 분리 |