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

This commit is contained in:
donghyeon-ka
2026-09-21 15:40:21 +09:00
parent 1bbc6a6f76
commit d63cebae36
10 changed files with 235 additions and 22 deletions
+47
View File
@@ -8,6 +8,53 @@
---
## 2026-09-21 반영 상태
이 리뷰 이후 코드에 적용한 상태다. 원래 리뷰의 발견/근거는 아래에 그대로 남기고, 이 표만 현재 상태를 나타낸다.
### P0
| # | 항목 | 상태 |
|---|---|---|
| 1 | Flyway + 전 profile `ddl-auto=validate` | **완료** — H2/PostgreSQL baseline migration 분리 |
| 2 | 기본 local profile 제거 | **완료** — 런타임 `local/dev/prod` 정확히 하나를 guard |
| 3 | `user_lessons` 제약·인덱스 | **완료** — `active_lesson_id` 생성 컬럼 + UNIQUE + 조회 인덱스 |
| 4 | CHECK + schedule UNIQUE | **완료** — migration과 entity/seeder policy 이중 방어 |
| 5 | `.env` 추적 제거 | **완료** — `.env` ignore, `.env.example`만 유지 |
| 6 | 공통 500 fallback + log | **완료** |
| 7 | page 상한 | **완료** — `@Max` 적용 및 API 테스트 |
| 8 | pool/timeout 명시 | **완료** — connection 획득 2초, DB lock 3초, pool size 명시 |
| 9 | 락 안 R1 재검증 | **완료** — INSERT 직전 재검증 |
| 10 | readiness DB / liveness 분리 | **완료** |
### P1
| 항목 | 상태 |
|---|---|
| PostgreSQL Testcontainers 통합/동시성 테스트 | **완료** |
| User → Lesson 락 단일 경계 + 순서 테스트 + ArchUnit | **완료** |
| R5/R6/R7 학기 scope | **완료** — 다른 학기 동일 과목·시간표·학점 회귀 테스트 |
| 성공 HTTP 계약/상태코드 | **완료** — 필드 집합과 값, 201/204를 API 테스트로 고정 |
| N+1 쿼리 수 상한 | **완료** |
| R1~R8 우선순위 인접 쌍 | **완료** |
| 고정 Clock + JPA auditing 시각 일원화 | **완료** |
| 락 대상으로 첫 조회 + `@Version` | **완료** |
| Idempotency-Key + DELETE 멱등 | **완료** — 추가로 24시간 TTL/cleanup/replay 정책 고정 |
| graceful shutdown 유예 정렬 | **완료** — Spring 30초 / container 35초 |
| 503 Retry-After jitter | **완료** |
| enum AttributeConverter | **완료** |
| Docker non-root + MaxRAMPercentage | **완료** |
### P2
- PostgreSQL native `uuid` PK 전환: **보류**. 현재 `String UUID + VARCHAR(36)`을 유지하고 별도 스키마 변경으로 분리한다.
- `/api/v1/me/registrations`: **보류**. 인증이 현재 non-goal이므로 인증 도입 작업과 함께 연다.
- `BaseDeleteEntity` 삭제: **완료**.
- JPA no-arg constructor protected: **완료**.
- JUnit/Spock 중복: **정리됨** — 현재 테스트는 JUnit 기준.
- `day_of_week` 정렬: **완료** — 숫자 AttributeConverter로 요일 순서를 DB 정렬과 일치시킨다.
- `BaseTimeZoneEntity` 개명: 기능/안전성 이득이 없어 이번 변경에서는 보류한다.
## 0. 이 문서를 읽는 법
발견은 두 종류다. 섞어 읽으면 안 된다.
+22 -6
View File
@@ -150,6 +150,12 @@ lesson_schedules
> `(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. 비즈니스 규칙
@@ -205,7 +211,7 @@ AND B.startTime < A.endTime
### 4.5 데이터 무결성 규칙
마스터 데이터 투입(Seeder) 시 지켜야 할 것. 애플리케이션이 검증하지는 않지만 위반 시 동작이 깨진다.
마스터 데이터가 아래 규칙을 깨면 신청 판정이 잘못된다. 따라서 한 계층에만 맡기지 않고 중복 방어한다.
- `Lesson.capacity >= 1`
- `Subject.credit >= 1`
@@ -213,6 +219,8 @@ AND B.startTime < A.endTime
- `Semester.registrationStartAt < registrationEndAt`
- 같은 Lesson 안의 시간 블록끼리는 서로 겹치지 않는다
현재 구현은 단일 엔티티에서 판정 가능한 값은 생성자에서 거부하고, Seeder는 `LessonSchedulePolicy`로 같은 Lesson의 시간 블록 겹침까지 검증한다. Flyway에는 범위 `CHECK`, exact schedule `UNIQUE`, 유효 신청 `UNIQUE`를 두어 DB도 마지막 방어선이 된다.
---
## 5. 동시성 설계 — 이 문서에서 가장 중요한 부분
@@ -342,7 +350,13 @@ Response `201 Created`
`totalCredits`는 신청 후 해당 학기 누적 학점이다. 클라이언트가 재조회 없이 남은 학점을 보여줄 수 있다.
선택적으로 `Idempotency-Key` 헤더를 받을 수 있다. 같은 사용자·같은 key·같은 lesson 재시도는 최초 신청 결과를 재사용하고, 같은 key를 다른 lesson에 재사용하면 `IDEMPOTENCY_KEY_REUSED` 409를 반환한다.
선택적으로 `Idempotency-Key` 헤더를 받을 수 있다. 보존 기간은 **24시간**이다.
- TTL 안에서 같은 사용자·같은 key·같은 lesson 재시도는 최초 신청 결과를 재사용한다.
- 최초 신청을 취소한 뒤 같은 key로 다시 POST해도 TTL 안이면 새 신청을 만들지 않고 최초 POST 결과를 replay한다.
- TTL 안에서 같은 key를 다른 lesson에 재사용하면 `IDEMPOTENCY_KEY_REUSED` 409를 반환한다.
- 만료된 key 행은 주기적으로 삭제하며, 삭제 후 같은 key는 새 요청으로 다시 사용할 수 있다.
에러: R1~R8 (4.1절 표)
@@ -352,7 +366,7 @@ Response `201 Created`
GET /api/v1/users/{userId}/registrations?semesterId={semesterId}
```
`semesterId` 생략 시 현재 시각이 신청 기간 `[registrationStartAt, registrationEndAt]`에 포함되는 학기를 우선 선택한다. 그런 학기가 없으면 오늘이 `[startDate, endDate]`에 포함되는 학기를 fallback으로 쓴다.
`semesterId` 생략 시 `SemesterResolver`가 현재 시각이 신청 기간 `[registrationStartAt, registrationEndAt]`에 포함되는 학기를 우선 선택한다. 그런 학기가 없으면 오늘이 `[startDate, endDate]`에 포함되는 학기를 fallback으로 쓴다. 같은 기준에 맞는 학기가 2개 이상이면 임의로 하나를 고르지 않고 데이터 오류로 실패시킨다.
Response `200 OK`
@@ -531,7 +545,7 @@ User 락은 R5~R7 직렬화와 일관된 판정을 담당하고, DB UNIQUE는 R4
## 9. 시드 데이터 요구사항
`DataSeeder`(profile: `local`)가 아래를 만들어야 한다. 10절의 테스트 시나리오가 이 데이터를 전제한다.
`DataSeeder`는 `local/dev` profile에서만 존재하며 `app.seed.enabled=true`일 때 아래 demo 데이터를 넣는다. `prod`에서는 profile과 설정 양쪽에서 비활성화한다. 10절의 테스트 시나리오가 이 데이터를 전제한다.
- Semester 1개: local/dev 샘플이 장기간 유지돼도 만료되지 않도록 넓은 고정 학기·신청 기간을 TSV에 명시, `maxCredits = 18`
- Professor 3명 (기존 유지)
@@ -544,7 +558,7 @@ User 락은 R5~R7 직렬화와 일관된 판정을 담당하고, DB UNIQUE는 R4
- **`allowedRole = POSTGRADUATE`인 강의**가 최소 1개 (R3 테스트용)
- User 3명 (기존 유지: 1학년 학생, 2학년 학생, 대학원생)
> seed 원본은 `src/main/resources/seed/local/*.tsv`에 둔다. 데이터가 늘어나면 Java 코드를 수정하지 않고 행을 추가한다. `DataSeeder`는 TSV 파싱·관계 조립·도메인 정책 검증만 담당한다. 여러 인스턴스가 동시에 시작할 때는 `seed_locks` 행을 `FOR UPDATE`로 잠가 한 인스턴스만 데이터를 넣는다.
> seed 원본은 `src/main/resources/seed/demo/*.tsv`에 둔다. 데이터가 늘어나면 Java 코드를 수정하지 않고 행을 추가한다. `DataSeeder`는 TSV 파싱·관계 조립·도메인 정책 검증만 담당한다. 여러 인스턴스가 동시에 시작할 때는 `seed_locks` 행을 `FOR UPDATE`로 잠가 한 인스턴스만 데이터를 넣는다.
---
@@ -626,7 +640,7 @@ User 락은 R5~R7 직렬화와 일관된 판정을 담당하고, DB UNIQUE는 R4
| `dto/` | `RequestDto`/`ResponseDto` 삭제하고 용도별 DTO로 분리 |
| `exception/` | 신규 — 도메인 예외 + `@RestControllerAdvice` |
| `enums/` | `RegistrationErrorCode` 신규 |
| `seeder/DataSeeder.java` | 9절 데이터로 교체, 신청 기간을 상대 시각으로 |
| `seeder/DataSeeder.java` | 9절 demo TSV 조립, 고정 기간 사용, `seed_locks FOR UPDATE`로 다중 Pod 직렬화 |
---
@@ -640,3 +654,5 @@ User 락은 R5~R7 직렬화와 일관된 판정을 담당하고, DB UNIQUE는 R4
| 강의 목록 페이지 기본 size | 20 |
| `maxCredits` 역할별 차등 | 단일 값으로 시작. 필요해지면 확장 |
| `minGrade` vs 정확한 학년 지정 | "이 학년 이상"으로 시작. "2~3학년만" 같은 요구가 생기면 `maxGrade` 추가 |
| Idempotency-Key 보존 기간 | 24시간, 1시간 주기 cleanup으로 시작 |
| PostgreSQL native `uuid` PK | 현재 `String UUID + VARCHAR(36)` 유지. 별도 스키마 변경으로 분리 |