refactor: 테스트 GWT로 통일해서 사용할 수 있도록 구성 및 서브에이전트 파일 수정

This commit is contained in:
donghyeon-ka
2026-09-21 15:31:30 +09:00
parent 62bc656c08
commit 1bbc6a6f76
115 changed files with 4899 additions and 1857 deletions
+38 -27
View File
@@ -2,7 +2,7 @@
- 작성일: 2026-09-16
- 대상 코드베이스: `course-registration` (Spring Boot 4.1.1 / Java 21 / JPA / H2(local) / PostgreSQL(prod))
- 상태: 설계 확정, 구현 전
- 상태: 구현·검증 완료, 2026-09-20 다관점 리뷰 반영
---
@@ -148,7 +148,7 @@ lesson_schedules
- `BaseCreateEntity`가 `BaseEntity`를 상속하도록 변경 (id + createdAt)
- `UserLessonRepository`의 ID 타입: `UserLessonId` → `String`
> **`(user_id, lesson_id)`에 UNIQUE 제약을 걸지 않는다.** 취소 후 재신청하면 같은 조합의 행이 여러 개 생기기 때문이다. "유효한 행만 유일" 이라는 부분 유니크 인덱스는 H2가 지원하지 않는다. 중복 신청은 5절의 락이 보장한다.
> `(user_id, lesson_id)` 자체에는 UNIQUE를 걸지 않는다. 취소 후 재신청 이력을 남겨야 하기 때문이다. 대신 `canceled_at IS NULL`일 때만 `lesson_id`를 노출하는 생성 컬럼 `active_lesson_id`를 두고 `(user_id, active_lesson_id)` UNIQUE를 건다. H2와 PostgreSQL에서 같은 제약을 사용하며, User 락과 함께 이중 방어한다.
---
@@ -198,10 +198,10 @@ AND B.startTime < A.endTime
|---|---|---|---|
| C1 | 신청 건이 존재하지 않음 | `REGISTRATION_NOT_FOUND` | 404 |
| C2 | 경로의 `userId`와 신청 건의 소유자가 다름 | `REGISTRATION_FORBIDDEN` | 403 |
| C3 | 이미 취소된 건 (`canceledAt != null`) | `ALREADY_CANCELED` | 409 |
| C3 | 이미 취소된 건 (`canceledAt != null`) | 멱등 성공 | 204 |
| C4 | 신청 기간이 지남 | `REGISTRATION_PERIOD_CLOSED` | 409 |
취소는 행을 삭제하지 않고 `canceledAt = now()`를 기록한다.
취소는 행을 삭제하지 않고 `canceledAt = now()`를 기록한다. 같은 DELETE를 재호출하면 이미 원하는 상태이므로 204를 그대로 반환한다.
### 4.5 데이터 무결성 규칙
@@ -272,23 +272,29 @@ COMMIT
> 예: 요청 A가 `user1 → lessonX` 순으로 잠그고, 요청 B가 `lessonX → user1` 순으로 잠그면, A는 lessonX를, B는 user1을 서로 기다리며 영원히 멈춘다. 항상 같은 순서로만 잠그면 이 상황이 만들어지지 않는다.
### 5.4 검증 위치 — 락 밖 / 락 안
### 5.4 검증 위치 — 락 획득 후 최신 값으로 판정
신청 mutation은 User와 Lesson을 **락 쿼리로 처음 읽는다.** 일반 조회 후 같은 영속성 컨텍스트에서 `findByIdForUpdate`를 다시 호출하면 Hibernate가 락 모드만 올리고 이미 읽은 엔티티 값을 그대로 사용할 수 있기 때문이다.
| 검증 | 위치 | 이유 |
|---|---|---|
| 사용자·강의 존재 | 락 밖 | 없는 리소스에 락을 걸 이유가 없다 |
| R1 신청 기간 | 락 밖 | 다른 트랜잭션의 영향을 받지 않는 값이다 |
| R2 학년 / R3 역할 | 락 밖 | 마찬가지. 신청 중에 변하지 않는다 |
| R4 ~ R8 | **락 안** | 모두 "다른 신청 건의 존재 여부"에 의존한다 |
| 사용자 존재 | User `FOR UPDATE` 조회 | 존재 확인과 락 획득을 한 쿼리로 묶는다 |
| 강의 존재 | Lesson `FOR UPDATE` 조회 | 락 이전 stale entity를 만들지 않는다 |
| R1 신청 기간 | **락 안 + INSERT 직전 재검증** | 락 대기 중 마감 시각을 지날 수 있다 |
| R2 ~ R8 | **락 안** | 동일 학생·강의의 경쟁 요청과 같은 기준으로 판정한다 |
락 밖 검증을 먼저 하는 이유는 **락을 잡는 시간을 줄이기 위해서**다. 신청 기간이 아닌데 락을 잡고 줄 세울 이유가 없다.
R1은 `registrationEndAt` 정각까지 포함한다. 따라서 `now.isAfter(registrationEndAt)`일 때만 마감으로 본다.
### 5.5 구현 메모
- JPA에서는 Repository 메서드에 `@Lock(LockModeType.PESSIMISTIC_WRITE)`를 붙인다
- 서비스 메서드 전체에 `@Transactional`을 건다. 락은 커밋 시점에 풀린다
- H2와 PostgreSQL 모두 `SELECT ... FOR UPDATE`를 지원한다. local/prod 동작이 같다
- 락 대기 타임아웃을 설정한다 (`jakarta.persistence.lock.timeout`). 무한 대기를 피한다
- 락 획득은 `RegistrationLockManager` 한 곳으로 모으고 항상 User → Lesson 순서를 강제한다
- JPA Repository의 락 조회는 `@Lock(LockModeType.PESSIMISTIC_WRITE)`를 사용한다
- 서비스 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`을 둬 예상하지 못한 동시 갱신도 감지한다
### 5.6 이 설계의 비용
@@ -336,6 +342,8 @@ Response `201 Created`
`totalCredits`는 신청 후 해당 학기 누적 학점이다. 클라이언트가 재조회 없이 남은 학점을 보여줄 수 있다.
선택적으로 `Idempotency-Key` 헤더를 받을 수 있다. 같은 사용자·같은 key·같은 lesson 재시도는 최초 신청 결과를 재사용하고, 같은 key를 다른 lesson에 재사용하면 `IDEMPOTENCY_KEY_REUSED` 409를 반환한다.
에러: R1~R8 (4.1절 표)
### 6.2 내 신청 목록 조회
@@ -344,7 +352,7 @@ Response `201 Created`
GET /api/v1/users/{userId}/registrations?semesterId={semesterId}
```
`semesterId` 생략 시 현재 진행 중인 학기(오늘이 `[startDate, endDate]` 안인 학기)를 쓴다.
`semesterId` 생략 시 현재 시각이 신청 기간 `[registrationStartAt, registrationEndAt]`에 포함되는 학기를 우선 선택한다. 그런 학기가 없으면 오늘이 `[startDate, endDate]`에 포함되는 학기를 fallback으로 쓴다.
Response `200 OK`
@@ -384,7 +392,9 @@ DELETE /api/v1/users/{userId}/registrations/{registrationId}
Response `204 No Content`
에러: C1~C4 (4.4절 표)
이미 취소된 신청에 같은 DELETE를 다시 보내도 204를 반환한다.
에러: C1, C2, C4 (4.4절 표)
### 6.4 개설 강의 목록
@@ -392,7 +402,7 @@ Response `204 No Content`
GET /api/v1/lessons?semesterId={id}&subjectId={id}&page=0&size=20
```
`semesterId` 생략 시 현재 진행 중인 학기. `subjectId`는 선택 필터.
`semesterId` 생략 시 신청 기간이 열린 학기를 우선하고, 없으면 진행 중인 학기로 fallback한다. `subjectId`는 선택 필터.
Response `200 OK`
@@ -424,7 +434,7 @@ Response `200 OK`
> `enrolledCount`는 조회 시점의 스냅샷이다. 표시가 29여도 신청이 `CAPACITY_EXCEEDED`로 실패할 수 있다. 정원의 진짜 판정은 5.3절 락 안에서만 일어난다. 클라이언트는 이 값을 참고용으로만 써야 한다.
**N+1 주의:** 강의마다 `schedules`와 `enrolledCount`를 따로 조회하면 쿼리가 폭발한다. `schedules`는 fetch join, `enrolledCount`는 `GROUP BY lesson_id` 집계 한 방으로 가져온다.
**N+1 방지:** 페이지의 Lesson을 먼저 조회한 뒤 해당 `lessonId` 집합으로 시간표를 `IN` 벌크 조회하고, `enrolledCount`는 `GROUP BY lesson_id` 집계 한 번으로 가져온다. 컬렉션 fetch join과 pagination을 섞지 않는다. 쿼리 수 상한은 통합 테스트로 고정한다.
### 6.5 강의 상세
@@ -457,11 +467,13 @@ Response `200 OK` — 6.4의 항목 하나 + `subjectDescription`, `semesterName
대안이었던 "요일 + 교시(정수)"는 겹침 판정이 정수 비교라 더 단순하지만, 교시↔실제 시각 매핑표가 따로 필요하고 30분 단위 변칙 강의를 담지 못한다.
### 7.2 왜 UNIQUE 제약 대신 락에 의존하나
### 7.2 유효 신청 중복을 DB와 락이 함께 막는 이유
`(user_id, lesson_id)` UNIQUE는 취소 후 재신청을 막아버린다. "유효한 행만 유일"이라는 부분 유니크 인덱스는 PostgreSQL에는 있지만 **H2에는 없어서** local과 prod의 동작이 갈린다. 5.3절의 User 락이 같은 학생의 신청을 직렬화하므로 중복은 애플리케이션 레벨에서 확실히 막힌다.
`(user_id, lesson_id)` UNIQUE는 취소 후 재신청 이력을 막으므로 사용할 수 없다. PostgreSQL의 partial unique index만 사용하면 H2 local과 DDL이 달라진다.
뒤집을 경우: `status` 컬럼 방식(복합키 유지 + REGISTERED/CANCELED)으로 가면 DB가 중복을 구조적으로 막아주지만, 신청↔취소 이력이 최신 1건만 남는다.
현재는 `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가 없나
@@ -509,8 +521,9 @@ Response `200 OK` — 6.4의 항목 하나 + `subjectDescription`, `semesterName
| `SCHEDULE_CONFLICT` | 409 | R6 시간표 충돌 |
| `CREDIT_LIMIT_EXCEEDED` | 409 | R7 학점 상한 초과 |
| `CAPACITY_EXCEEDED` | 409 | R8 정원 초과 |
| `ALREADY_CANCELED` | 409 | C3 이미 취소된 건 |
| `IDEMPOTENCY_KEY_REUSED` | 409 | 같은 Idempotency-Key를 다른 강의에 재사용 |
| `LOCK_TIMEOUT` | 503 | 락 대기 타임아웃 (5.5절) |
| `INTERNAL_SERVER_ERROR` | 500 | 예상하지 못한 서버 오류 / 필수 시간표 데이터 누락 |
`message`는 한국어로, 가능하면 **숫자를 포함한다.** "정원이 찼습니다"보다 "정원이 가득 찼습니다. (30/30)"가, "학점 초과"보다 "신청 학점이 상한을 넘습니다. (18 + 3 > 18)"가 학생이 다음 행동을 정하는 데 쓸모 있다.
@@ -520,7 +533,7 @@ Response `200 OK` — 6.4의 항목 하나 + `subjectDescription`, `semesterName
`DataSeeder`(profile: `local`)가 아래를 만들어야 한다. 10절의 테스트 시나리오가 이 데이터를 전제한다.
- Semester 1개: `2026-1`, 신청 기간이 **현재 시각을 포함**하도록 (`now - 1일` ~ `now + 7일`), `maxCredits = 18`
- Semester 1개: local/dev 샘플이 장기간 유지돼도 만료되지 않도록 넓은 고정 학기·신청 기간을 TSV에 명시, `maxCredits = 18`
- Professor 3명 (기존 유지)
- Subject 3개 + `credit` (예: 3, 3, 3)
- Lesson 3개 이상, 아래 조건을 만족하도록 구성:
@@ -531,9 +544,7 @@ Response `200 OK` — 6.4의 항목 하나 + `subjectDescription`, `semesterName
- **`allowedRole = POSTGRADUATE`인 강의**가 최소 1개 (R3 테스트용)
- User 3명 (기존 유지: 1학년 학생, 2학년 학생, 대학원생)
> 기존 `DataSeeder`는 `2026년 3월`로 하드코딩된 `kst()` 헬퍼를 쓴다. 신청 기간은 **실행 시각 기준 상대값**으로 바꿔야 한다. 고정 날짜로 두면 시간이 지나면서 모든 신청이 `REGISTRATION_PERIOD_CLOSED`로 실패한다.
>
> `Instant base` 변수는 현재 선언만 되고 쓰이지 않는다. 정리 대상이다.
> seed 원본은 `src/main/resources/seed/local/*.tsv`에 둔다. 데이터가 늘어나면 Java 코드를 수정하지 않고 행을 추가한다. `DataSeeder`는 TSV 파싱·관계 조립·도메인 정책 검증만 담당한다. 여러 인스턴스가 동시에 시작할 때는 `seed_locks` 행을 `FOR UPDATE`로 잠가 한 인스턴스만 데이터를 넣는다.
---
@@ -565,7 +576,7 @@ Response `200 OK` — 6.4의 항목 하나 + `subjectDescription`, `semesterName
| T13 | 상한을 넘는 학점 신청 | 409 `CREDIT_LIMIT_EXCEEDED` |
| T14 | 정원 1인 강의에 두 번째 신청 | 409 `CAPACITY_EXCEEDED` |
| T15 | 남의 신청 건 취소 | 403 `REGISTRATION_FORBIDDEN` |
| T16 | 이미 취소한 건 또 취소 | 409 `ALREADY_CANCELED` |
| T16 | 이미 취소한 건 또 취소 | 204 (멱등 성공) |
### 10.3 경계값