chore: 테스트 계약 생성 support

This commit is contained in:
DongHyeonka
2026-09-21 11:30:05 +09:00
parent 70d71008c6
commit 62bc656c08
28 changed files with 1989 additions and 164 deletions
+348
View File
@@ -0,0 +1,348 @@
# 수강신청 API 다관점 리뷰
- 작성일: 2026-09-20
- 대상: `course-registration` @ `main` (워킹트리 기준)
- 방법: 14개 관점 에이전트가 각각 독립적으로 전면 리뷰. 공통 렌즈는 `.claude/review-lens.md`
- 전제: **Pod 3개 이상 / 롤링 배포 / 오픈 순간 트래픽 집중**. 단일 인스턴스에서만 성립하는 성질은 결함으로 취급했다
- 리뷰 중 코드는 **수정하지 않았다**. 기준선 `./gradlew test` → 56 tests, 0 failures
---
## 0. 이 문서를 읽는 법
발견은 두 종류다. 섞어 읽으면 안 된다.
| 표시 | 뜻 |
|---|---|
| **[실측]** | 앱을 실제로 띄우거나, SQL을 돌리거나, 라이브러리 바이트코드를 열어 확인함 |
| **[추론]** | 코드를 읽고 논리적으로 도출함. 맞을 가능성은 높지만 재현은 안 해봄 |
수치(초당 처리량 등)는 대부분 **[추론]**이다. 가정이 명시된 계산이지 실측이 아니다.
---
## 1. 한 줄 판정
**동시성 설계의 뼈대는 제대로 잡혀 있다. 그런데 그 뼈대를 지키는 장치가 주석과 관습뿐이고, 운영 환경으로 나가는 경로가 막혀 있다.**
- 잘 된 것: `@ManyToOne` 전용 정책, 락 순서 일관성, `open-in-view: false`, 트랜잭션 안 외부 호출 0건, Pod-local 상태 0건
- 막힌 것: **prod는 지금 기동조차 안 된다** (§5)
- 위험한 것: 설계 목표 대부분이 테스트로 고정돼 있지 않다 (§2)
---
## 2. 가장 중요한 결과 — 변조 실험
`test-strategy` 렌즈가 저장소를 샌드박스에 복사해 **설계 목표를 하나씩 고의로 깨고** 테스트를 돌렸다. **[실측]**
기준선: 56개 전부 통과.
| # | 깨뜨린 것 | 결과 |
|---|---|---|
| M1 | `register()`의 락 순서를 Lesson→User로 교환 | **56/56 통과** |
| M2 | `cancel()`만 반대 순서로 (신청≠취소) | **56/56 통과** |
| M3 | User 비관적 락 제거 | 2개 실패 ✅ |
| M4 | 벌크 로딩 → 강의당 1쿼리 (N+1 복원) | **56/56 통과** |
| M5 | R6→R7→R8 판정 순서 역전 | **56/56 통과** |
| M6 | `registrationStartAt` 검사 삭제 | **56/56 통과** |
| M7 | 유효신청 조회에서 학기 스코프 삭제 | **56/56 통과** |
| M8 | 응답 필드명 변경 (`registeredAt`→`createdAt`) | **56/56 통과** |
| M9 | `register()`의 `@Transactional` 제거 | 18개 실패 ✅ |
| M10 | 필터·페이지네이션·정렬 전부 무시 | **56/56 통과** |
| M11 | 성공 상태코드 201→200, 204→200 | **56/56 통과** |
| M12 | 시간표를 아예 안 불러오게 (R6 무력화) | 1개 실패 (동시성 테스트 1개뿐) |
| M13 | `Clock` 빈 우회 (`Instant.now()`) | **56/56 통과** |
**13개 중 10개가 아무 경보도 울리지 않았다.**
이 문서가 지적하는 가장 중요한 것이 이거다. 테스트 56개가 초록인 것과 설계가 지켜지는 것은 **별개의 사실**이다.
특히 M1·M2가 통과한다는 건, 문서 §5.3이 "순서를 섞으면 데드락"이라고 못 박은 불변식을 **주석 한 줄이 지키고 있다**는 뜻이다.
---
## 3. 여러 렌즈가 독립적으로 도달한 결론
서로 다른 관점에서 같은 결론이 나온 항목이다. **교차 확인된 만큼 신뢰도가 높다.**
| 항목 | 렌즈 수 | 검증 |
|---|---|---|
| 마이그레이션 도구 부재 → prod 기동 불가 | **7** | [실측] |
| `DataSeeder` check-then-act → Pod 다중 기동 실패 | **6** | [추론] |
| `@ExceptionHandler(Exception.class)` 부재 → 에러 바디 2종 | **5** | [실측] |
| `user_lessons` 인덱스 0개 → 락 쥔 채 Seq Scan | **5** | [추론] |
| `@EnableJpaAuditing`이 `Clock` 빈을 안 탐 | **4** + 본인 확인 | [실측] |
| 헬스체크가 집계 `/actuator/health`, readiness에 `db` 없음 | **4** | [실측] |
| `server.address` 기본값 `127.0.0.1` | **4** | [추론] |
| 락 타임아웃이 H2/PG에서 다른 메커니즘 | **4** | [실측] |
| `spring.profiles.default: local` → 프로필 누락 시 H2로 조용히 기동 | **3** | [실측] |
| `findByIdForUpdate`가 **락 이전 값**을 반환 | **3** | [실측] |
| graceful shutdown 유예 시간 미정렬 | **3** | [실측] |
### 3-1. 특히 짚어야 할 것 — `findByIdForUpdate`가 락 이전 값을 준다
세 렌즈가 각각 다른 방법으로 같은 결론에 도달했다.
```java
Lesson lesson = lessonRepository.findById(id); // :64 1차 캐시에 적재
Lesson lockedLesson = lessonRepository.findByIdForUpdate(id); // :73 FOR UPDATE SQL은 나감
// lockedLesson == lesson (같은 객체)
```
Hibernate는 이미 영속성 컨텍스트에 있는 엔티티를 만나면 **락 모드만 올리고 방금 읽은 컬럼 값은 버린다**(`EntityInitializerImpl.upgradeLockMode()`). `@Version`이 0건이라 버전 검사조차 없다.
결과: `RegistrationValidator`가 보는 `getCapacity()`, `getMaxCredits()`는 **락을 잡기 전에 읽은 값**이다. 변수 이름이 `lockedLesson`이라 아무도 의심하지 않는다.
지금은 강의 CRUD API가 없어서 이 창이 안 열린다. **그래서 더 위험하다** — "락을 잡았으니 최신"이라는 성질이 *대체로* 성립하고, 다음 사람이 그 위에 코드를 쌓는다.
---
## 4. 설계 문서와 코드가 어긋난 지점
`docs/Requirements.md`의 명시적 주장 중 **사실이 아닌 것**들이다.
### §5.4 "R1(기간)은 락 밖에서 검증해도 안전"
근거가 "다른 트랜잭션의 영향을 받지 않는 값"인데, **변하는 건 다른 트랜잭션이 아니라 시간**이다.
```
마감 3ms 전 → R1 통과 → 락 대기 최대 3초 → 마감 이후에 INSERT·COMMIT
```
레이스가 아니라 **결정론적으로 재현되는 동작**이다. 그리고 `cancel()`은 락을 먼저 잡고 R1을 검사한다 — **같은 규칙이 두 경로에서 반대 위치에 있다.**
### §5.5 "H2와 PostgreSQL 모두 지원한다. local/prod 동작이 같다" — **[실측]**
락 타임아웃에 관해 사실이 아니다. Hibernate 7.4.5 바이트코드 확인:
| | H2 (local/test) | PostgreSQL (dev/prod) |
|---|---|---|
| `@QueryHints(lock.timeout=3000)` | **`LockTimeoutType.NONE` — 무시됨** | `CONNECTION` → `set local lock_timeout` |
| 실제 타임아웃 출처 | JDBC URL의 `LOCK_TIMEOUT=3000` | Hibernate가 락 쿼리마다 설정/원복 |
| 적용 범위 | **세션 전체** | **해당 트랜잭션만** |
| 락 SQL | `for update wait 3` | `for no key update` |
| 추가 왕복 | 0 | 락 1회당 **+2~3회** |
**애노테이션의 `3000`은 어떤 테스트도 지나가지 않는 코드다.** 테스트가 통과하는 건 URL 설정 덕분이다.
### §7.2 "부분 유니크 인덱스는 H2에 없어서 락에 의존한다" — **[실측, 직접 검증]**
전제는 맞고 결론이 틀렸다. H2 2.3.232에서 직접 돌렸다.
```sql
-- C) 문서가 말한 방식 → H2 미지원 확인
CREATE UNIQUE INDEX uk ON ul (user_id, lesson_id) WHERE canceled_at IS NULL;
→ Syntax error ... [*]WHERE canceled_at IS NULL
-- A) 생성 컬럼 방식 → H2에서 동작
ALTER TABLE ul ADD COLUMN active_lesson_id varchar(36)
GENERATED ALWAYS AS (CASE WHEN canceled_at IS NULL THEN lesson_id END);
ALTER TABLE ul ADD CONSTRAINT uk UNIQUE (user_id, active_lesson_id);
→ 신청 → 취소 → 재신청 : 성공 ✅
→ 유효 신청 중복 시도 : Unique index or primary key violation ✅
```
**"H2 때문에 DB 제약을 포기한다"는 판단은 재검토 대상이다.** 우회로가 있고 양쪽 DB에서 같게 동작한다.
### §4.5 "애플리케이션이 검증하지는 않지만"
5개 규칙 중 **4개는 이미 엔티티 생성자에서 검증되고 있다**(문서가 낡음). 남은 1개 "같은 Lesson 안의 시간 블록끼리 겹치지 않는다"는 정말로 **어디에서도 검증되지 않는다.**
---
## 5. 지금 운영 배포가 불가능한 이유 — **[실측]**
빈 DB에 `ddl-auto: validate`로 기동한 결과:
```
SchemaManagementException: Schema validation: missing table [lesson_schedules]
프로세스 exit=1
```
`validate`는 **검사만 하고 테이블을 만들지 않는다.** 그리고 이 저장소에는 스키마를 만들 수단이 없다 — Flyway도 Liquibase도 `.sql` 파일도 0개.
**첫 배포라 구 Pod가 없으므로 롤백할 대상도 없다.**
### 그리고 `validate`가 무엇을 안 보는지 — **[실측]**
아래를 전부 심어놓은 DB에 앱을 붙였더니 **정상 기동했다**:
| DB 실제 상태 | 엔티티 선언 | validate |
|---|---|---|
| `nickname NOT NULL` 컬럼 추가 | 그런 필드 없음 | 통과 |
| `users.name`을 NULL 허용으로 완화 | `nullable=false` | 통과 |
| `description`을 varchar(4000)로 확대 | `length=1000` | 통과 |
| `role` CHECK을 `('STUDENT')`로 축소 | 값 2개 | 통과 |
`validate`는 **테이블·컬럼·대략적 타입**만 본다. NOT NULL, CHECK, UNIQUE, 인덱스, FK는 검증 대상이 아니다.
실제로 터지는 모습도 재현했다 — `user_lessons`에 `note NOT NULL`을 추가하니:
```
Started CourseRegistrationApplication ← 기동 성공
/actuator/health/readiness → {"status":"UP"} ← Ready
POST /registrations → HTTP 500 ← 수강신청 100% 실패
```
**DBA가 컬럼 하나 추가하는 순간, 전 Pod가 Ready를 유지한 채 수강신청이 전량 죽는다.**
---
## 6. 통합 우선순위
### P0 — 운영 배포 전 필수
| # | 항목 | 근거 |
|---|---|---|
| 1 | **Flyway 도입 + 전 프로필 `ddl-auto: validate`** | §5. 지금 prod 기동 불가. 아래 3·4가 전부 이 위에 선다 |
| 2 | **`spring.profiles.default: local` 제거** | 한 줄 삭제. 투입 대비 효과 최대 |
| 3 | **`user_lessons` 제약·인덱스** — 생성 컬럼 + UNIQUE + 조회 인덱스 | §4-§7.2. 락 안 Seq Scan 제거 + R4를 DB가 막음 |
| 4 | **§4.5 CHECK 제약 + `lesson_schedules` UNIQUE** | 문서가 "깨진다"고 적은 것을 DB로 |
| 5 | **`git rm --cached .env`** | 5분. 진짜 비밀번호가 들어간 뒤엔 history rewrite |
| 6 | **`@ExceptionHandler(Exception.class)` 폴백 + 로그** | 에러 바디 2종을 1종으로 |
| 7 | **`page`에 `@Max`** | 인증 없는 GET 한 방으로 500 |
| 8 | **커넥션 풀·타임아웃 명시 + 순서 정렬** | 지금 커넥션 30초 > 락 3초로 뒤집혀 있음 |
| 9 | **락 안에서 R1 재검증** | §5.4. 한 줄 |
| 10 | **readiness에 `db` 포함, liveness엔 절대 넣지 않음** | 설정 2줄 |
### P1 — 트래픽 붙기 전
- 동시성·통합 테스트를 **Testcontainers PostgreSQL**로 이전 (H2 결과는 prod 동작의 근거가 못 됨)
- 락 획득을 **단일 컴포넌트**로 좁히고 호출 순서를 단언 + ArchUnit (M1·M2 대응)
- 학기 2개짜리 픽스처로 **§4.2 스코프 고정** (M7 대응)
- 성공 응답 **전체 JSON 비교** + 상태코드 단언 (M8·M11 대응)
- 쿼리 수 단언으로 **N+1 회피 고정** (M4 대응)
- 규칙 **우선순위 인접 쌍 테스트** (M5 대응)
- `Clock.fixed` `@TestConfiguration` (M13 대응)
- `@EnableJpaAuditing(dateTimeProviderRef = ...)`로 시각 출처 일원화
- 락 대상은 **락 쿼리로 처음 읽기** + `@Version` (§3-1 대응)
- `Idempotency-Key` + DELETE 재호출을 204로
- `graceful shutdown` 유예 시간과 컨테이너 유예 시간 **둘 다 명시**
- 503에 `Retry-After` + 지터
- `@Enumerated` → `AttributeConverter` (enum 값 추가를 무중단으로)
- Dockerfile `USER` 추가 + `MaxRAMPercentage`
### P2 — 알고만 있을 것
- PK `varchar(36)` → `uuid` 타입 (**데이터 없는 지금이 아니면 무중단으로 못 바꾼다**)
- `/api/v1/me/registrations` 별칭 미리 열기 (인증 도입 시 배포 3번 → 1번)
- `BaseDeleteEntity` 삭제, `BaseTimeZoneEntity` 개명
- `@NoArgsConstructor(access = PROTECTED)` (지금 public이라 `new Lesson()`이 컴파일됨)
- JUnit/Spock 중복 정리
- `day_of_week` 정렬이 문자열 순서 (월/금 강의에서 드러남)
---
## 7. 렌즈별 핵심 발견 (각 1~2개만)
| 렌즈 | 핵심 |
|---|---|
| `jpa-persistence` | `save()`가 merge다 — id 받는 생성자 때문. 테스트·시드는 merge, 운영은 persist **[실측]** |
| `rdb-schema` | 락 안에서 `user_lessons` Seq Scan 2회. 락 보유 시간이 테이블 크기에 비례 |
| `transaction-locking` | 락 순서 위반 경로 **0건** (검증됨). 다만 지키는 장치가 주석뿐 |
| `distributed-runtime` | 시더가 신청 기간을 **부팅 시각 상대값**으로 심는다. 7일 뒤 전 요청 차단, 근거는 코드에 안 남음 |
| `zero-downtime-evolution` | enum 값이 **DB CHECK 제약**으로 박힌다. 값 추가 = 배포 3번 + DB 변경 1번 **[실측]** |
| `http-contract` | 에러 바디가 **4가지 모양**. `/api/v1/lessons/%00`은 HTML을 뱉는다 **[실측]** |
| `layering-domain` | "현재 학기"를 학기 기간으로 고르는데, **수강신청은 학기 시작 전에 일어난다** |
| `capacity-resilience` | `register()` 1회 = DB 왕복 **18회**. 경쟁 시 Pod당 초당 3.3건 **[추론]** |
| `observability-ops` | 프로덕션 코드 로거 호출 **0건**. 설계한 실패는 무음, 안 만든 실패(500)만 스택트레이스 **[실측]** |
| `config-secrets` | 프로필 오타 → 무작위 이름 인메모리 H2로 조용히 기동, health UP **[실측]** |
| `security-boundary` | `cancel()`의 소유권 검증이 **클라이언트 입력끼리 비교**한다. 인증 붙여도 통과 |
| `error-design` | 시간표 데이터가 없는 강의는 **R6를 조용히 통과**한다 |
| `validation-layering` | 같은 400이 세 가지 바디로 나간다. 엔티티 예외 12곳은 전부 500 |
| `test-strategy` | §2의 변조 실험 |
---
## 8. 에이전트 간 의견이 갈린 지점과 판정
### 8-1. graceful shutdown 기본값 — **판정 완료**
- `capacity-resilience`, `zero-downtime-evolution`: "Boot 기본값은 `immediate`"
- `config-secrets`: "Boot 4는 `graceful`이 기본" + 실측 로그 제시
**바이트코드로 판정 [실측]:**
```
AbstractConfigurableWebServerFactory shutdown = IMMEDIATE ← 팩토리 원시 기본값
ServerProperties (autoconfigure) shutdown = GRACEFUL ← Boot 4가 덮어씀
```
`config-secrets`가 맞다. **다만 처방은 같다** — Spring은 30초를 기다릴 준비가 됐는데 `docker-compose`가 10초 만에 SIGKILL한다. 두 숫자 다 설정 파일에 없어서 서로를 모른다.
### 8-2. R4를 DB 제약으로 옮기는 방법 — **판정 완료**
세 가지 제안이 나왔고 직접 H2에서 돌려 검증했다. §4-§7.2 참조.
**생성 컬럼 방식(A)을 택한다** — 컬럼 하나가 유일성 제약 + 인덱스 + "유효 신청" 개념 표현을 동시에 해결한다.
### 8-3. 아직 판정 안 한 것
- **읽기/쓰기 커넥션 풀 분리**: `capacity-resilience`는 DataSource 분리, `security-boundary`는 세마포어를 권했다. 후자가 이 규모에 맞다고 보지만 부하 테스트 전엔 결정 보류
- **PK를 `uuid` 타입으로 바꿀지**: 바꿀 거면 지금이 유일한 기회. 안 바꾸면 인덱스 크기를 영구히 감수. 결정 필요
---
## 9. 실측된 것 vs 추론인 것
### 실측 (재현 가능)
- prod 첫 배포 실패 (`SchemaManagementException`, exit 1)
- 프로필 폴백 → 인메모리 H2, readiness UP, 200 응답
- `validate`가 NOT NULL·CHECK·길이·잉여 컬럼을 무시
- `NOT NULL` 컬럼 추가 → 신청 전량 500, readiness는 UP
- 에러 바디 4종 (curl로 전 엔드포인트 확인)
- `page=99999999` → 500 (`Page offset exceeds Integer.MAX_VALUE`)
- 변조 실험 13건
- H2에서 생성 컬럼 방식 동작 / 부분 인덱스 미지원
- Hibernate 락 타임아웃 처리 경로 (바이트코드)
- Boot 4 graceful shutdown 기본값 (바이트코드)
- `save()`가 merge (SQL 트레이스)
- 프로덕션 로거 호출 0건 (grep)
- `.env` git 추적 중 (`git ls-files`)
### 추론 (가정 위의 계산)
- 초당 처리량 수치 (왕복 0.4ms RTT, Seq Scan 25~40ms, fsync 1~5ms 가정)
- Pod 10개에서 `max_connections` 초과 (컨테이너 실측 아님)
- 데드락 시나리오 (현재 코드엔 순서 위반 경로가 없어 재현 불가)
- 학기 2개일 때 §4.2 위반 영향
---
## 10. 이 리뷰가 못 본 것
- **실제 부하 테스트 없음.** §9의 추론 수치는 k6 등으로 확인해야 한다
- **PostgreSQL 실환경 검증 없음.** 대부분 H2 또는 정적 분석. `for no key update` 동작, `lock_timeout` 실제 적용은 미검증
- **다중 Pod 실환경 검증 없음.** Pod 간 시계 어긋남, 롤링 중 공존은 단일 JVM에서 재현 불가
- **k8s 매니페스트가 저장소에 없다.** `SERVER_ADDRESS`, `terminationGracePeriodSeconds` 같은 지식이 어디에도 안 남는다
- 프런트엔드·클라이언트 쪽 영향은 보지 않았다
---
## 부록: 리뷰에 쓴 에이전트
`.claude/agents/` 14개. 공통 규약은 `.claude/review-lens.md`.
발견마다 다섯 칸을 채우게 했다 — **현상 / 분산에서 / 제안 규칙 / 드러나는 것 / 버리는 것**.
뒤의 세 칸이 이 리뷰의 형식적 핵심이다. "더 좋은 것을 고른다"가 아니라 **"문제가 숨을 자리를 없앤다"**를 강제한다. 기준이 된 예시는 이 팀이 이미 쓰는 규칙이다:
```
제안 규칙 연관관계는 @ManyToOne만 쓴다
드러나는 것 N+1이 lesson.getSchedules() 한 줄에 숨지 못하고 코드에 드러난다
버리는 것 cascade 편의
```
그 규칙이 실제로 무엇을 막고 있는지도 이번에 확인됐다 — **"페이징 + 컬렉션 fetch join = 전 건 메모리 적재"**라는 JPA 최대 지뢰가 이 코드베이스에는 만들어질 수 없다.
---
## 다음에 읽을 것
렌즈별 전체 리포트는 이 문서에 요약만 실렸다. 특정 렌즈의 전체 발견이 필요하면 해당 에이전트를 다시 돌리면 된다:
```
Agent(subagent_type: "rdb-schema", prompt: "...")
```
단, 에이전트 정의는 세션 시작 시 로드되므로 **Claude Code를 재시작한 뒤**에 이름으로 호출할 수 있다.