diff --git a/docs/2026-09-21-multi-lens-review.md b/docs/2026-09-21-multi-lens-review.md new file mode 100644 index 0000000..007fdd8 --- /dev/null +++ b/docs/2026-09-21-multi-lens-review.md @@ -0,0 +1,741 @@ +# 수강신청 API 다관점 리뷰 (2차) + +- 작성일: 2026-09-21 +- 대상: `course-registration` @ `main` (`d63ceba` ~ `1dc0733`, 워킹트리 clean) +- 방법: 9개 관점 에이전트. `.claude/review-workflow.md`의 Phase 1(discovery) → Phase 2(specialist) 순서 +- **novelty gate: `docs/2026-09-20-multi-lens-review.md` 전문.** 1차 리뷰에 이미 적힌 발견은 제외했다 +- 전제: Pod 3개 이상 / 롤링 배포 / 오픈 순간 트래픽 집중 +- 원본 워킹트리는 **수정하지 않았다**. 모든 실험은 샌드박스 사본에서 했고 종료 후 `git status` clean 확인 + +--- + +## 0. 이 문서를 읽는 법 + +| 표시 | 뜻 | +|---|---| +| **[실측]** | 변조를 넣고 테스트를 돌렸거나, 앱을 띄워 curl로 확인했거나, DB에 DDL을 적용했거나, 바이트코드를 열어 확인함 | +| **[추론]** | 코드를 읽고 도출함. 재현은 안 해봄 | + +이번 리뷰는 실측 비중이 높다. 핵심 결론 대부분이 **실제로 코드를 깨뜨리거나 앱을 띄워 측정한 결과**다. + +에이전트 실행 중 HEAD가 `d63ceba` → `1dc0733`로 움직여 테스트 수가 보고마다 139/141/143으로 다르다. 전부 0 failures이고 결론에 영향을 주는 차이는 없다. + +--- + +## 1. 한 줄 판정 + +**물건은 만들었는데 책임자를 안 정했다. 그리고 1차 리뷰 권고를 구현하면서 검증 경로를 같이 만들지 않아, 고친 것이 새 문제를 만들었다.** + +이 문장이 아래 모든 발견의 공통 뿌리다. 두 축으로 나뉜다. + +### 축 1 — 소유자 없는 것들 + +| 만들어진 것 | 정해지지 않은 것 | 증거 | +|---|---|---| +| `RegistrationLockManager` | 락 경계의 소유자 | 우회 3종 전부 전체 테스트 통과 §4-1 | +| `RegistrationIdempotency` | 멱등 레코드가 무엇을 주장하는지 | §4-4, §4-8 | +| `error()` 헬퍼 3벌 | 예외를 만들 자격의 소유자 | 형태가 6곳 제각각 §4-5 | +| `UserLesson.cancel()` | 재취소 계약의 소유자 | 엔티티와 서비스가 **정반대** §4-6 | +| `RegistrationValidator:58-65` | "강의는 시간표 ≥1개"의 소유자 | prod 방어 0층 §4-2 | +| `LessonSchedulePolicy` | 시간블록 겹침 금지의 소유자 | prod에 빈 자체가 없음 §4-2 | + +### 축 2 — 1차 P0를 구현한 결과 + +| 1차 권고 | 구현됨 | 그 결과 새로 생긴 것 | +|---|---|---| +| P0 #6 `Exception.class` 폴백 + 로그 | O | **404·405·415·타입불일치가 전부 500**이 되고, 앱의 유일한 ERROR 로그가 노이즈로 덮임 §4-3 | +| P0 #8 커넥션 풀·타임아웃 명시 + **순서 정렬** | 명시만 | `connection-timeout 2s` < `lock_timeout 3s`. **원인(락)보다 증상(풀)이 먼저 터짐** §4-3 | +| P0 #10 readiness에 `db` 포함 | O | readiness가 **앱 트래픽과 같은 Hikari 풀**에 줄을 섬 → 락 폭주가 pod 퇴출로 번역 §4-7 | +| P0 #9 락 안 R1 재검증 | O | **지워도 139/139 통과.** 고정 시계라 원리적으로 테스트 불가 §4-9 | +| P1 `@ExceptionHandler` 에러 바디 1종화 | 시도 | 바디 모양은 **여전히 4종** §4-3 | + +셋 다 같은 모양이다 — **구현은 했고, 그 구현이 맞는지 묻는 테스트는 안 만들었다.** + +--- + +## 2. 변조 재측정 — 개편은 성공했다 **[실측]** + +1차 리뷰 변조를 현재 코드에 다시 적용하고 신규 기능 변조를 추가했다. 샌드박스에서 변조 → `./gradlew test` → 원복을 **23회 반복**. Testcontainers PostgreSQL 16-alpine 실제 기동. 기준선 `139 tests, 0 failures`. + +| # | 깨뜨린 것 | 판정 | +|---|---|---| +| M1 | `RegistrationLockManager.lock()` 락 순서 교환 | KILLED (1) | +| M2 | 락 경계 클래스에 `lockForCancel()`(역순) 추가, `cancel()`이 사용 | **SURVIVED** | +| M3 | `findByIdForUpdate`의 `@Lock` 제거 | KILLED (3) | +| M4 | `LessonQueryService` 벌크 로딩 → N+1 | KILLED (1) | +| M4b | `register()` 경로의 `@EntityGraph` 제거 | **SURVIVED** | +| M5 | 판정 우선순위 역전 | KILLED (2) | +| M6 | `registrationStartAt` 하한 검사 삭제 | **SURVIVED** | +| M7 | 유효신청 조회에서 학기 스코프 제거 | KILLED (3) | +| M8 | 응답 필드명 변경 (wire만) | KILLED (2) | +| M10 | 목록 API 필터·페이징·정렬 무시 | KILLED (2) | +| M10b | **정렬만** 제거 | **SURVIVED** | +| M11 | 201→200, 204→200 | KILLED (4) | +| M13a | 서비스의 `clock.instant()` → `Instant.now()` | KILLED (34) | +| M13b | `auditingDateTimeProvider` → `Instant.now()` | KILLED (5) | +| N1 | 멱등 조회를 락 획득 **이전**으로 | **SURVIVED** | +| N2 | 멱등 키 재사용 판정 제거 | KILLED (1) | +| N3 | TTL 필터 무력화 → 만료 키도 replay | **SURVIVED** | +| N4 | `IdempotencyRetentionJob.cleanup()` no-op | KILLED (1) | +| N5 | `requireValidProfiles()` 항상 통과 | KILLED (4) | +| N6 | h2 baseline에만 컬럼 추가 | **SURVIVED** | +| N7 | 락 안 `validateRegistrationPeriod` 재검증 삭제 | **SURVIVED** | +| W1 | 본문은 그대로 두고 **배선만** 끊기 | **SURVIVED** | +| V1 | `@Version` 제거 | KILLED (73) | + +| | 2026-09-20 | 2026-09-21 | +|---|---|---| +| 기준선 테스트 수 | 56 | 139 | +| M1~M13 중 재측정한 11개 | 검출 **1** | 검출 **9** | +| 1차 생존자 10개 | — | **8개 사망**, 2개 생존 | + +**개편은 성공했다.** 1차 P1 목록을 실제로 닫았다. + +### 곁다리 관찰 2개 + +- **V1이 73개를 깨뜨린 건 테스트가 낙관적 락을 고정해서가 아니다.** 마이그레이션의 `version BIGINT NOT NULL` 때문에 INSERT 자체가 실패한 것이다. 방어선은 테스트가 아니라 DDL이다. +- **M13a가 34개를 깨뜨린 이유**는 `DomainFixtures.openSemester()`가 신청 기간을 `TestData.NOW ± 3600초`로 잡기 때문이다. 시계가 매우 강하게 고정돼 있고, 그 강함이 §4-9의 원인이다. + +--- + +## 3. 1차 리뷰 이후 닫힌 것 + +공정하게 먼저 적는다. 반증 시도를 했고 **막혀 있음을 확인**한 것이다. + +| 1차 지적 | 현재 | 확인 | +|---|---|---| +| prod 기동 불가 | Flyway 도입, 전 프로필 `validate` | 두 baseline 실제 적용 [실측] | +| `spring.profiles.default: local` | `RuntimeProfileConfig`가 기동 차단 | N5 → 4개 실패 [실측] | +| `user_lessons` 인덱스 0개, R4 락 의존 | 생성 컬럼 + `uk_user_active_lesson` + 인덱스 4개 | PG/H2 제약 발동 확인 [실측] | +| `findByIdForUpdate` 락 이전 값 | 락 쿼리가 첫 조회 | 코드 경로 확인 | +| `save()`가 merge | `@Version Long`(nullable)로 해소. **`long`으로 바꾸면 되돌아간다** | 반증됨 | +| 새 에러 코드 HTTP 상태 암기 | `RegistrationErrorCode` 생성자가 강제 | 반증됨 | +| 락 순서 교환(메서드 **내부**) | `RegistrationLockManagerTest`가 잡음 | M1 [실측] | +| `page=99999999` → 500 | **400**으로 고쳐짐. `@Max(1_000_000)×@Max(100)` | [실측] | +| 페이지네이션 정렬 불안정 | `LessonQueryService:48`에 PK tiebreaker | 반증됨 | +| DELETE 재호출 | **진짜 멱등**. 3회 연속 204, 기간 종료 후도 204 | [실측] | +| keyless 재시도 → 중복 | 동시 150건, 중복 0 | [실측] | +| h2/postgresql baseline 불일치 | **현재 제약 24개 전부 일치** | PG16+H2 적용 후 비교 [실측] | + +--- + +## 4. 구조적 원인 + +### 4-1. [높음] 락 경계의 주어가 클래스 이름 문자열과 메서드 하나다 + +**세 에이전트가 서로 다른 방법으로 뚫었고, 셋 다 전체 테스트를 통과했다.** + +| 뚫은 방법 | 결과 | +|---|---| +| `lockManager` 필드는 그대로 두고 `EntityManager`로 역순 락 + `new LockedRegistration(...)` 위조 | **141/141 통과** [실측] | +| `..service..` **밖** 패키지에 역순 락 + `user_lessons` 직접 INSERT | **139/139 통과** [실측] | +| 락 경계 클래스 **안에** `lockForCancel()`(역순) 추가, `cancel()`이 사용 (M2) | **139/139 통과** [실측] | + +세 번째가 핵심이다. 우회가 아니라 **경계 안에 public 메서드를 하나 더 만든 것**인데, `RegistrationLockManagerTest`가 `lock()` 한 메서드의 호출 순서만 보므로 무관심하다. + +**Repository facts** + +- `architecture/ArchitectureTest.java:30-33` — 규칙의 주어가 `haveSimpleName("CourseRegistrationService")` 문자열과 `resideInAPackage("..service..")`. 새 패키지는 사정권 밖이다. +- `CourseRegistrationService.java:39` — `UserRepository`가 `existsById` 때문에 계속 주입돼 있는데, `UserRepository`의 커스텀 메서드는 `findByIdForUpdate` **하나뿐**이다. **Lesson 락은 막고 User 락은 안 막는다.** +- `service/lock/RegistrationLockManager.java:29` — `public record LockedRegistration(...)`. public record는 정식 생성자를 낮출 수 없다. **토큰이 될 모양인데 위조 가능해서 기능하지 않는다.** +- `ArchitectureTest.java:23` — `importPath("build/classes/java/main")`. 바이트코드만 본다. **JPQL 문자열·`setLockMode`·네이티브 SQL은 원리적으로 볼 수 없다.** +- `seeder/DataSeeder.java:59-61` — 프로덕션 소스에 이미 `jdbcTemplate`로 `select ... for update`가 있다. **ArchUnit이 못 보는 락 획득의 전례가 레포 안에 존재한다.** +- `ArchitectureTest.java:41-53` — 쓰기 보호 대상이 `UserLessonRepository`, `RegistrationIdempotencyRepository` 둘뿐. **`LessonRepository`·`LessonScheduleRepository` 규칙은 0개.** + +**같은 패턴이 락 말고도 반복된다** + +| 규칙 | 고정된 자리 | 생존 변조 | +|---|---|---| +| 쿼리 수 상한 | `getLessons` 한 경로만 | M4b — `register()` 안 `@EntityGraph` 제거. **락을 쥔 채** 왕복이 는다 | +| 배선(`@Scheduled`, guard bean) | 본문만(Mockito `verify`) | W1 — 본문 그대로, **호출을 끊으면** 통과 | +| 정렬 | 페이징 테스트의 부수 효과 | M10b — PG는 `LIMIT/OFFSET`에 안정 순서를 보장하지 않는다 | + +**제안 규칙** + +1. `LockedRegistration`을 `RegistrationLockManager` 안의 `public static final class` + **private 생성자**로 바꾸고, 등록 쓰기를 그 토큰을 첫 인자로 받는 메서드로만 노출한다. → **락 없이 쓰는 코드가 컴파일되지 않는다.** +2. ArchUnit을 클래스 이름 allow-list에서 **패키지 단위 + 전체 classpath**로 뒤집는다. `*ForUpdate` 호출자를 `..service.lock..`으로 제한한다. +3. `SourceStyleTest`를 확장해 `for update` / `setLockMode` / `LockModeType.PESSIMISTIC` 문자열이 `service/lock/` 밖에 나오면 실패시키고 `DataSeeder`를 명시적 예외로 둔다. +4. 락 경계 클래스의 public 메서드 개수를 ArchUnit으로 단언한다(M2 대응). + +**드러나는 것** — 락을 새로 잡는 시도가 파일 경로로 드러난다. "User 먼저"를 기억할 필요가 없어진다. + +**버리는 것** — 임시 스크립트성 코드에서 `EntityManager`로 빠르게 락 잡는 편의. 테스트 픽스처도 명시적 예외 경로를 거쳐야 한다. + +### 4-2. [높음] 강의 마스터 데이터 규칙의 prod 소유자가 0이다 + +**Repository facts** + +- `service/policy/LessonSchedulePolicy.java:20-33` — "같은 Lesson 안 시간블록 겹침 금지"의 유일한 구현. **주입받는 프로덕션 클래스는 `seeder/DataSeeder.java:48` 하나뿐이고**, 그 클래스는 `:31` `@Profile({"local","dev"})` + `:32` `@ConditionalOnProperty(app.seed.enabled)`. **prod에는 빈 자체가 생성되지 않는다.** +- `db/migration/*/V1__baseline.sql` — `uk_lesson_schedule UNIQUE (lesson_id, day_of_week, start_time, end_time)`은 **완전히 동일한 행**만 막는다. 부분 겹침은 통과한다. `lesson_schedules` 행이 0개인 강의를 막는 제약도 없다. +- `entity/Lesson.java` — 생성자에 시간표 검증이 없고, 구조적으로 불가능하다(`ArchitectureTest`가 엔티티의 `@OneToMany`를 금지). +- `service/LessonQueryService.java:58` — `getOrDefault(lesson.getId(), List.of())`. **시간표 0개 강의를 정상 목록 항목으로 노출한다.** +- `docs/Requirements.md:216-222` — 데이터 무결성 규칙 5개 목록에 "Lesson은 시간블록 ≥1개"가 **없다**. `:214`는 5개를 "한 계층에만 맡기지 않고 중복 방어한다"로 한 문단에 묶는다. + +**실측 — 우회 INSERT로 실제 계층 수를 쟀다** + +``` +거부 :: capacity=0, credit=0, grade=0, max_credits=0, start>=end, day_of_week=0 (CHECK 7종) +거부 :: 완전 동일 시간블록 재삽입 (uk_lesson_schedule) +통과 :: 같은 lesson MON 09-11 + MON 10-12 (부분 겹침) ← prod 0층 +통과 :: semester name = '' / subject name = '' / lesson name = '' ← 엔티티 1층뿐 +통과 :: role = 'GHOST' ← 0층 +``` + +`Requirements.md`가 "5개 모두 중복 방어"라고 묶어 서술한 규칙들의 실제 계층 수가 **2층 / 1층 / 0층**으로 갈린다. + +`role='GHOST'`가 가장 나쁘다. INSERT는 성공하고, 읽을 때 `UserRoleConverter`의 `UserRole.valueOf`가 터진다. 그 시점이 `RegistrationLockManager:22`가 엔티티를 hydrate하는 순간이라 **검증 계층에 도달조차 못 하고** 500 + `log.error`가 된다. `name=''`는 더 조용하다 — 이름 없는 강의가 그냥 목록에 나온다. + +**시간표 0개의 폭발 반경 [실측]** + +``` +1. 학생이 강의 A 신청 → 201 +2. A의 lesson_schedules 행이 사라짐 (배포 없음, 코드 변경 없음) +3. 학생이 무관한 강의 B 신청 + → 500 INTERNAL_SERVER_ERROR + → body.message = "기존 신청 강의 시간표가 없습니다." ← 내부 진단 문구가 클라이언트로 + → 앱 로그 이벤트 0건 ← 추적 불가 +4. GET /lessons, /lessons/{A}, /registrations 전부 200. A는 "schedules":[] 로 멀쩡히 보인다 +5. 복구는 A를 취소하는 것뿐 — 자리를 포기해야 다른 신청이 가능하다 +``` + +`RegistrationValidator:61-65`가 **기존 유효 신청 전부**에 시간표 존재를 요구한다. 그래서 강의 하나의 데이터 결함이 **그 강의를 수강 중인 모든 학생의 모든 후속 신청**을 막는다. 운영이 시간표를 DELETE+INSERT로 고치는 순간이 그 창이다. + +**반증 확인** — 이 500 자체는 의도로 고정돼 있다: `RegistrationValidatorTest:128,136`, `CourseRegistrationApiTest:242-261 missingSchedule500`. 그래서 "500이 난다"는 발견이 아니다. 살아남은 것은 ① 결함을 만들지 못하게 하는 장치가 prod에 0개 ② 로그 0건 ③ 폭발 반경이 결함 강의를 넘는다, 셋이다. + +**제안 규칙** — 겹침 규칙을 `DataSeeder`에서 떼어내 강의 쓰기 경계 컴포넌트로 옮기고, `ArchitectureTest`에 `LessonRepository`·`LessonScheduleRepository` 쓰기 규칙을 추가한다. "Lesson은 시간표 ≥1개"를 `Requirements.md` 4.5에 규칙으로 승격하거나, 허용하려면 `RegistrationValidator:58-60`을 `INTERNAL_SERVER_ERROR`가 아닌 도메인 코드(`LESSON_NOT_REGISTRABLE` 409)로 바꾼다. 엔티티에만 있는 규칙(name blank, role 도메인)은 DB에도 올린다. + +**버리는 것** — 운영 SQL로 강의·시간표를 빠르게 고치는 편의. enum 값 추가 시 마이그레이션 동반(무중단 배포에서는 CHECK를 먼저 넓혀야 한다). + +### 4-3. [치명] `Exception.class` 폴백이 Spring 표준 4xx를 전부 500으로 바꿨다 + +1차 P0 #6의 산출물이다. `GlobalExceptionHandler`가 `ResponseEntityExceptionHandler`를 **상속하지 않아서**, `@RestControllerAdvice`의 `ExceptionHandlerExceptionResolver`가 `DefaultHandlerExceptionResolver`보다 먼저 돈다. + +**실측 (앱을 띄워 curl)** + +| 요청 | 나와야 할 것 | 실제 | 앱 ERROR 로그 | +|---|---|---|---| +| `GET /api/v1/no-such-endpoint` | 404 | **500** | 1줄 | +| `GET /favicon.ico` | 404 | **500** | 1줄 | +| `POST /api/v1/lessons` | 405 | **500** (`Allow` 없음) | 1줄 | +| `Content-Type: text/plain` | 415 | **500** | 1줄 | +| `GET /api/v1/lessons?page=abc` | 400 | **500** | 1줄 | +| `GET /actuator/metrics`, `/prometheus`, `/info`, `/loggers`, `/threaddump`, `/scheduledtasks` | 404 | **500** | 1줄씩 | + +**미매핑 경로 30회 → 앱 ERROR 정확히 30줄**, 전부 같은 메시지 `Unhandled request failure`. + +**인증이 없으므로 누구나 `GET /api/v1/nope` 반복만으로 ERROR 로그와 로그 기반 알람을 채울 수 있다.** 그리고 경로에 `userId`가 들어가는 API라 오타 요청 하나가 사용자 식별자를 ERROR 로그에 남긴다(404 메시지가 경로를 품기 때문). + +에러 바디 모양도 **여전히 4종**이다 — JSON / Tomcat HTML / Whitelabel HTML / 빈 바디. 1차 §7의 "4가지 모양"은 줄지 않았다. 폴백이 고친 건 "핸들러 없는 예외가 Whitelabel로 나가는 것"뿐이고, 대신 상태 코드가 무너졌다. + +**왜 안 잡혔나** — `GlobalExceptionHandlerTest`가 `new GlobalExceptionHandler(...)`로 객체를 만들어 `handler.handleLockTimeout(...)`을 **직접 호출**한다. DispatcherServlet도 라우팅도 리졸버 순서도 타지 않는다. 그리고 나쁜 요청(405/415/타입변환/없는 경로)을 보내는 API 테스트가 **저장소 전체에 0건**이다. + +**제안 규칙** — `ResponseEntityExceptionHandler` 상속으로 바꾸고, "DispatcherServlet을 타는 나쁜 요청 5종이 5xx면 실패"를 API 테스트로 고정한다. + +**버리는 것** — 없음. 바디 스키마는 `{code,message,timestamp}`를 유지할 수 있다. + +### 4-4. [높음] 타임아웃 순서가 뒤집혀 있어 단일 원인이 500과 503으로 쪼개진다 + +1차 P0 #8은 "커넥션 풀·타임아웃 명시 + **순서 정렬**"이었다. 명시는 됐고 순서는 그대로다. + +``` +1초 deadlock_timeout → 503 + Retry-After (앱 로그 0줄) +2초 hikari connection → 500 (Retry-After 없음) ← 커넥션이 락보다 먼저 +3초 lock_timeout → 503 + Retry-After (앱 로그 0줄) +``` + +**락을 기다리는 스레드는 커넥션을 쥔 채 최대 3초 버티고, 뒤에 온 요청은 2초 만에 커넥션을 못 받고 죽는다. 원인(락)보다 증상(풀)이 먼저 터진다.** + +**실측 — 요청 8건 / 풀 4 / 외부 세션이 핫 lesson row를 9초 보유** + +``` +HTTP 500 retryAfter=null (2077ms) {"code":"INTERNAL_SERVER_ERROR"} x4 +HTTP 503 retryAfter=1~2 (3046ms) {"code":"LOCK_TIMEOUT"} x4 +HikariPoolMXBean @t+1.5s: active=4 idle=0 awaiting=6 total=4 +``` + +**하나의 원인이 두 상태코드로 나간다.** 클라이언트에게 500은 재시도 금지, 503은 재시도 권장이다. `CannotCreateTransactionException`은 `TransactionException` 계열이라 `GlobalExceptionHandler:38`의 세 타입에 안 걸린다. + +prod는 pool 20 / Tomcat 스레드 200이므로 오픈 순간에 180개가 커넥션 큐에 선다. **혼잡이 심해질수록 서버가 "재시도하라"고 말하는 비율이 줄어든다.** + +**제안 규칙** — `connection-timeout`을 `lock_timeout`보다 **크게** 두고, 두 숫자의 대소 관계를 설정 테스트로 고정한다. `CannotCreateTransactionException`/`SQLTransientConnectionException` 계열을 `LOCK_TIMEOUT`과 다른 코드로, 그러나 같은 503 + `Retry-After`로 내보낸다. + +### 4-5. [높음] "error 처리"는 세 가지가 섞인 말이고, 그중 하나에 소유자가 없다 + +이 절은 사용자가 직접 던진 질문에 대한 답이다. + +| 책임 | 지금 어디에 | 있어야 할 곳 | 판정 | +|---|---|---|---| +| **(a) 판정** — 던질지 결정 | validator 8건 + service 4건 + lock 2건 + resolver 2건 | 규칙마다 다름 | 소유자 **미정** | +| **(b) 생성** — 예외 객체를 만듦 | `error()` 3벌 + `notFound()` 1벌 + 직접 `new` 2곳 | **한 곳** | 소유자 **없음** | +| **(c) 번역** — HTTP 응답으로 | `GlobalExceptionHandler` | 그대로 | **올바름** | + +**(b)에 대한 답: 서비스에도 validator에도 있을 이유가 없다.** + +``` +error(code, msg) service/policy/RegistrationValidator.java:103 +error(code, msg) service/CourseRegistrationService.java:179 ← 완전히 동일 +error(code, msg) service/LessonQueryService.java:106 ← 완전히 동일 +notFound(msg) service/SemesterResolver.java:54 ← 코드를 하드코딩 +new RegistrationException() service/lock/RegistrationLockManager.java:23,25 +``` + +**결정적 증거는 개수가 아니라 형태가 제각각이라는 점이다.** 소유자가 있었다면 여섯 곳이 같은 모양이었을 것이다. `error()`는 `new RegistrationException(code, message)`를 1:1로 감쌀 뿐 로깅도 컨텍스트 주입도 하지 않는다 — 붙일 정책이 하나도 안 붙어 있다. `private static`이라 seam이 파일 밖으로 나갈 수 없어서 3벌로 복제됐다. + +**헬퍼가 코드를 소유하면 의미가 손실된다.** `SemesterResolver.notFound()`가 `SEMESTER_NOT_FOUND`를 하드코딩해서, `:28`(클라이언트가 보낸 `semesterId` 오타)과 `:51`(활성 학기 0개 = 전사 조회 불능)이 **같은 404 + 같은 코드**로 합쳐졌다. 호출부가 둘을 구분할 기회를 잃었다. + +**메시지 텍스트를 단언하는 테스트가 저장소에 0건이다.** `CourseRegistrationApiTest:257-261`은 필드 이름 집합만 보고 `Rejections`는 `RegistrationErrorCode`만 비교한다. 그래서 이미 복제된 3쌍이 **자유롭게 갈라질 수 있고 아무도 모른다**: + +``` +USER_NOT_FOUND "사용자를 찾을 수 없습니다." CourseRegistrationService:116, RegistrationLockManager:23 +LESSON_NOT_FOUND "강의를 찾을 수 없습니다." LessonQueryService:66, RegistrationLockManager:25 +REGISTRATION_NOT_FOUND "수강신청 건을 찾을 수 없습니다." CourseRegistrationService:137, :141 +``` + +**(a)에 대한 답: 경계는 이미 정해져 있는데 코드가 강제하지 않고 이미 4건이 이탈했다.** + +`Requirements.md:222`가 "단일 엔티티에서 판정 가능한 값은 생성자에서 거부"라고 적었다. 합리적이고 대체로 지켜지고 있다. 문제는 ① 그 문장을 강제하는 장치가 0개 ② 이미 validator 밖에 판정이 4건 있다는 것이다. + +| 위치 | 규칙 | 마땅한 소유자 | +|---|---|---| +| `CourseRegistrationService:164` 키 길이 100자 | 경계 형식 | **Controller** (`@Size`) — 지금은 락 2개를 쥔 채 판정한다 | +| `:83` 멱등키 재사용 | 멱등 프로토콜 | 멱등 전담 컴포넌트 | +| `:138` C2 타인 취소 금지 | 소유권 | **`UserLesson`** (`isOwnedBy(userId)`) | +| `:116` 사용자 존재 | 조회 전제 | service 유지 — 리포지토리 결과를 응답으로 번역하는 일 | + +**"각 검증 지점에서 메시지를 직접 쓰는 것"은 유지하는 게 맞다.** 17개 코드 중 15개는 throw 자리가 1~2곳이고, `Requirements.md:542`가 요구하는 숫자 포함 메시지(`"(15 + 3 > 18)"`, `"(30/30)"`)는 **throw 자리에 값이 있어서 가능하다**. 중앙화하면 이게 제일 먼저 죽는다. + +### 4-6. [높음] `RegistrationErrorCode`에 분류 축이 `HttpStatus` 하나뿐이다 + +**세 에이전트가 독립적으로 같은 처방에 도달했다** — `error-design`은 `clientFacing`, `validation-layering`은 `clientFacing`/`Layer`, `layering-domain`은 `category` + `retryable`. 전부 "enum 생성자에 축을 하나 더 넣어라"다. + +**근거가 이미 검증돼 있다.** 1차 리뷰가 "새 에러 코드의 HTTP 상태를 기억해야 함"을 지적했고, `RegistrationErrorCode` 생성자가 `HttpStatus`를 필수 인자로 요구하게 해서 해소됐다. **이건 새 장치가 아니라 작동이 확인된 장치의 확장이다.** + +**지금 이 축 하나로는 못 하는 것** + +`RegistrationValidator:59,:64`가 도메인 검증 도중 `INTERNAL_SERVER_ERROR`를 던진다. 그 결과 같은 500이 정반대로 처리된다 [실측]: + +``` +P1 POST (시간표 0행 강의) + → 500 {"code":"INTERNAL_SERVER_ERROR","message":"강의 시간표가 없습니다."} + → 앱 로그 0건 ← 마스킹 X, 로그 X + +P5 GET /lessons (학기 2행) + → 500 {"code":"INTERNAL_SERVER_ERROR","message":"서버 내부 오류가 발생했습니다."} + → ERROR 1건 + 스택트레이스 ← 마스킹 O, 로그 O +``` + +**로그 유무를 정하는 기준이 "예외 타입이 `RegistrationException`인가"이고, 이건 원인의 심각도와 무관하다.** 그리고 `GlobalExceptionHandler:26`이 `e.getMessage()`를 그대로 내보내므로 **사용자에게는 원인이 보이는데 운영자에게는 안 보인다.** + +그리고 `REGISTRATION_PERIOD_CLOSED`(영구 거절)·`CAPACITY_EXCEEDED`(자리 나면 가능)·`CREDIT_LIMIT_EXCEEDED`(뭘 취소하기 전엔 영구)가 **전부 409**다. 나중에 대기열 워커나 배치가 `register()`를 부르면 `getStatus()`로는 재시도/드롭/알람을 못 고르고 **enum Set을 자기 코드에 복제**하게 된다. 그 Set은 새 코드가 추가돼도 컴파일 오류를 안 낸다 — `HttpStatus`가 강제하는 것과 정반대다. + +**제안 규칙** — enum을 쪼개지 말고 축을 추가한다. `category`(RULE / NOT_FOUND / CLIENT / SYSTEM)를 생성자 필수 인자로 넣고, `GlobalExceptionHandler.registration()`이 SYSTEM이면 메시지를 치환하고 `log.error`를 남긴다. → **한 파일 두 줄로 "내부 문구 노출"과 "로그 공백"이 동시에 닫힌다.** 그 다음 `INTERNAL_SERVER_ERROR`를 도메인에서 던지는 두 자리를 전용 코드로 바꾼다. + +**버리는 것** — enum에 필드가 하나 늘고 17개 상수를 한 번 분류해야 한다. 도메인 코드가 5xx를 고르던 자유. + +### 4-7. [높음] 엔티티와 서비스가 정반대 계약을 갖고, 각각 테스트로 고정돼 있다 + +```java +// entity/UserLesson.java:43 — 이미 취소면 예외 +public void cancel(Instant canceledAt) { + if (this.canceledAt != null) throw new IllegalStateException("registration is already canceled"); + +// service/CourseRegistrationService.java:142 — 이미 취소면 조용히 성공 +if (registration.isCanceled()) return; +``` + +`Requirements.md:207`의 C3는 **"멱등 성공 204"**다. 엔티티는 정반대 결론이고, **서비스의 한 줄이 유일한 번역기**다. 실측: 그 한 줄을 지우면 `DELETE 재호출 → 204`가 **HTTP 500**이 된다(2개 실패). + +**두 결론이 각각 테스트로 고정돼 있고 두 테스트는 서로를 모른다.** + +- `entity/EntityInvariantTest.java:161 doubleCancel` → `IllegalStateException` 단언 (`@DisplayName("같은 신청 두 번 취소 → 도메인 거부")`) +- `controller/CourseRegistrationApiTest.java:174 repeatedCancel204` + `service/...IntegrationTest.java:108` → 성공 단언 + +두 번째 취소 경로(관리자 일괄 취소, 정정기간 되돌리기)가 생기면 그 경로는 서비스의 가드가 없어 500이 되는데, **`EntityInvariantTest`는 초록인 채로 리뷰어에게 "엔티티가 맞다"고 말한다.** + +**같은 구조가 멱등키에도 있다.** 서비스(`:160-167`)는 blank 키를 `null`로 바꿔 **멱등을 조용히 끄고**, 엔티티(`:60-62`)는 blank를 거부한다. 실측: + +``` +공백 키(" ")로 같은 신청 2회 → 201 → 409 ALREADY_REGISTERED +정상 키로 2회 → 201 → 201 (replay) +``` + +프록시가 헤더를 비우거나 클라이언트 템플릿이 빈 문자열을 만들면 **멱등이 꺼진 사실을 아무도 모른 채** 재시도가 진짜 중복 신청 시도가 된다. 그리고 `EntityInvariantTest:176`이 "공백 거부"를 고정하는데 **그 경로는 API로 도달할 수 없다.** + +**제안 규칙** — 멱등을 엔티티가 소유한다. `UserLesson.cancel()`을 이미 취소 시 no-op으로 바꾸고 `EntityInvariantTest:161`을 계약에 맞춘다. 서비스 가드를 지운다. → 새 취소 경로가 계약을 **자동으로** 따른다. 멱등키는 `IdempotencyKey` 값 타입으로 올려 blank/길이 판정을 한 곳에서 한다. blank를 "멱등 없음"으로 볼지 400으로 볼지 결정하고 문서에 적는다(지금은 결정된 적이 없다). + +**버리는 것** — "이중 취소는 프로그래밍 오류다"라는 엔티티의 방어. + +### 4-8. [높음] 멱등 레코드의 수명과 주장 범위가 정의되지 않았다 + +**TTL 안 — 과잉 성공.** replay는 `CourseRegistrationService:86`에서 **최초 성공 시점에 동결된 값**을 201로 돌려준다. `cancel()`은 멱등 테이블을 읽지도 쓰지도 않는다. + +``` +취소 후 같은 키로 재시도 + POST → 201, registrationId=R1, totalCredits=15 + GET → 그 강의 없음, totalCredits=12 +``` + +**같은 API의 두 엔드포인트가 서로 다른 답을 준다.** `CourseRegistrationResponse`에 `status`도 `canceledAt`도 `replayed`도 없어 클라이언트가 신규 생성과 replay를 구분할 수 없다 [실측: 최초 201과 replay 201의 바디가 `registeredAt`까지 바이트 동일]. + +**TTL 밖 — 과잉 실패.** 실측(`APP_IDEMPOTENCY_TTL_SECONDS=3`): + +``` +t+0s POST(K, L1) → 201 +t+4s POST(K, L1) → 409 ALREADY_REGISTERED ← replay가 사라짐 +t+4s POST(K, L3) → 409 SCHEDULE_CONFLICT ← 키-강의 바인딩도 사라짐 +``` + +**요청도, 클라이언트 상태도, 서버 데이터도 안 바뀌었다. 시간만 지났다.** 모바일 앱이 재시도 큐를 25시간 들고 있다가 재시도하면 409를 받고, 대부분의 재시도 프레임워크는 4xx를 terminal로 봐서 큐에서 지운다. 화면은 "신청 실패", 실제로는 25시간 전에 성공했다. + +**TTL 하나가 반대 방향의 두 보증을 조절한다. 늘리면 과잉 성공이, 줄이면 과잉 실패가 나빠진다. 튜닝으로 해결되지 않는다.** + +키의 의미 수명이 셋이다 — **성공 = 24시간 / 실패 = 0초(멱등행은 신청 저장 뒤에 INSERT되므로 거절은 키를 소비하지 않는다) / 강의 바인딩 = 24시간.** 클라이언트는 셋 중 어느 것도 관측할 수 없다. + +**결과 확정 경로가 순환 의존이다.** `ALREADY_REGISTERED` 409 바디는 `{code, message, timestamp}` 3필드 고정이라 **`registrationId`가 없다.** 그런데 키 없는 클라이언트에게 "성공했다"를 알리는 유일한 신호가 그 409다. `GET`으로 회수하려면 `semesterId`를 명시해야 안전한데, **`semesterId`를 담는 응답이 `GET /registrations` 하나뿐**이다 — 방어하려는 바로 그 엔드포인트다. `LessonDetailResponse`는 `semesterName`만 주고 이름→ID 변환 경로가 없으며 `GET /api/v1/semesters`도 없다. **신청 이력 0건인 신규 사용자는 방어를 시작할 수조차 없다.** + +**제안 규칙** — `ALREADY_REGISTERED` 409 바디에 기존 `registrationId`를 담는다. **이 변경 하나로 TTL 만료 문제와 결과 확정 경로가 둘 다 닫힌다.** 그리고 replay 시 저장된 응답을 그대로 돌려주지 않고 신청을 재조회해 취소 여부를 확인하거나, 응답에 `replayed` 표시를 넣는다. 모든 학기 관련 응답에 `semesterId`를 에코한다. + +**버리는 것** — replay의 "DB 재조회 0회" 이점. 응답 필드 몇 개 추가. + +### 4-9. [높음] 테스트에서 시간이 전진하지 않는다 + +`TestFixtureConfig.java:24`의 `Clock.fixed(TestData.NOW, UTC)` 하나로 전체 통합 테스트가 돈다. 시각을 전진시키는 헬퍼가 저장소에 없다. + +**1차 P0 #9의 산출물인 `CourseRegistrationService:98`을 지우면 139/139 통과한다** [실측]. 테스트를 안 써서가 아니다. 락 대기는 `:71`에서 끝나므로 `:74`의 `requestTime`은 이미 post-lock이고, `:98`이 잡을 수 있는 유일한 창은 `:76~:97` 구간이다. **고정 시계에서는 두 값이 정의상 같아서 두 검사를 구별하는 테스트를 만들 수 없다.** + +즉 **1차 리뷰가 P0로 고치라고 했고 고쳤다고 적힌 수정을, 지켜주는 장치가 0개다.** 주석조차 없어서 다음 사람은 중복 호출로 보고 지운다. 게다가 호출부 `:90`에는 `validatePreconditions`라고만 적혀 있어 **R1이 이미 한 번 돌았다는 사실이 호출부에서 보이지 않는다.** + +같은 원인의 생존자: N3(만료 키 무한 replay), M6(신청 오픈 전 통과), N1(같은 키 동시 2건). + +**한 요청 안에 "현재 시각"이 셋 있다** — 멱등 `expiresAt`은 `requestTime`(`:109`), R1 마감 검사는 `:98`, 응답 `registeredAt`은 JPA auditing. 고정 시계라 지금은 전부 같고, `CourseRegistrationServiceIntegrationTest:55`·`:270`이 `isEqualTo(TestData.NOW)`로 **그 우연을 단언하고 있다.** + +**제안 규칙** — 시간이 인자로 들어가는 규칙은 **경계 3점(before/at/after)**을 단언한다. TTL·재검증처럼 "두 시점 사이에 시계가 움직인다"가 전제인 코드는 전진 가능한 `MutableClock`으로 검증하고 "락 획득 후 마감이 지나는" 경계 테스트를 1건 둔다. + +**대안** — 팀이 `:98`이 불필요하다고 판단해도 괜찮다. 다만 **지금은 지킬 수 없는 규칙을 코드가 주장하는 상태**이므로, 지우지 않을 거면 최소한 주석으로 의도를 남겨야 한다. + +### 4-10. [높음] `validateRegistrationPeriod`가 서로 다른 세 규칙의 이름이다 + +`RegistrationValidator:37-42`의 호출부가 셋이다 — `:25`(`validatePreconditions` 첫 줄), `CourseRegistrationService:98`, `:144`(cancel). 셋 다 시그니처가 같고 같은 에러 코드·같은 메시지를 쓴다. + +`:25`/`:98`은 같은 규칙의 두 시점(의도된 중복)이지만 **`:144`는 다른 규칙(C4)이다.** + +`Requirements.md:208`의 C4는 신청 기간이 **"지남"**만 규정하는데, 구현은 양방향으로 판정한다. 실측: + +``` +신청 시작 전 취소 → 409 REGISTRATION_PERIOD_CLOSED / "수강신청 기간이 아닙니다." +``` + +**학생이 취소를 눌렀는데 "신청 기간이 아니다"라는 답을 받는다.** 마감 시각도 없어서 언제 다시 시도할지 모른다. + +정정기간을 넣는 순간 이건 규칙 추가가 아니라 **기존 창의 분할**이 되고, 세 호출부 중 어느 걸 바꿔야 하는지 컴파일러가 안 알려준다. `:25`는 다른 메서드 안에 숨어 있어 **호출부가 셋이라는 사실 자체가 안 보인다.** M6이 SURVIVED인 것이 이 창을 만지는 변경을 테스트가 못 잡는다는 직접 증거다. + +**제안 규칙** — `validateRegistrationOpen(lesson, now)`(R1, 양방향)과 `validateCancelAllowed(lesson, now)`(C4, 상한만)로 쪼개고 에러 코드도 나눈다. 메시지에 마감 시각을 넣는다. + +### 4-11. [높음] R2·R3가 락 2개를 잡고 판정하는데 락이 보호할 게 없다 + +R2(학년)·R3(역할)의 입력은 `user.grade`, `user.role`, `lesson.minGrade`, `lesson.allowedRole` 넷인데 **이 넷을 쓰는 코드가 레포에 하나도 없다.** 마스터 CRUD가 범위 밖이고 엔티티에 setter가 없다. 경쟁 쓰기가 없으니 락이 지킬 대상이 없다. + +그런데 자격 미달 요청(403이 될 요청)이 성공 요청과 **완전히 같은 비용**으로 핫 lesson row 락 큐에 선다. `seed/demo/lessons.tsv`에 `minGrade=3` 강의와 `allowedRole=POSTGRADUATE` 강의가 있어 자격 미달 요청이 정상적으로 발생하도록 설계된 데이터다. + +**같은 파일 안에서 비대칭이다.** `cancel()`은 소유권 403을 **락 앞에서** 끝낸다(`:138` → `:139`). `register()`는 자격 403을 **락 뒤에서** 한다. 둘 중 어느 쪽이 규칙인지 코드에도 문서에도 없다. + +**제안 규칙** — "락 안에서 판정해도 되는 것은 **다른 요청의 쓰기 결과에 의존하는 규칙뿐**"으로 정한다. 그러면 R1·R4~R8만 남고 R2·R3와 멱등키 길이 검증은 락 밖으로 나간다. + +**미확인** — 락 경합 비용은 **[추론]**이다. 부하 테스트를 하지 않았다. + +### 4-12. [중간] 판정과 표시 계산이 한 메서드에 묶여 있다 + +`RegistrationValidator.currentCredits` 본문을 바꾸고 전체 스위트를 돌린 결과 **5개 실패인데 R7 규칙 테스트 3개 + 조회 응답 테스트 2개가 동시**다 [실측]. + +지금 틀렸다는 게 아니라 **변경 이유 두 개를 한 장치가 지키고 있다**는 뜻이다. "재수강 과목은 화면 합계에는 표시하되 상한 계산에서는 제외" 같은 요구가 들어오면, 개발자가 `currentCredits`를 고치고 → R7 테스트 3개가 빨개지고 → **테스트가 경보가 아니라 수정 대상이 된다.** 기대값을 고쳐 통과시키는 순간 R7이 조용히 바뀐다. + +그리고 스코프를 validator가 소유하지 않는다. "유효 + 같은 학기"는 `UserLessonRepository:16-22`의 JPQL이 정하는데 `List` 타입은 그 조건을 담지 못한다. M7(스코프 쿼리 변조)은 검출됐지만 **새 호출자가 다르게 스코프된 리스트를 넘기는 경로는 테스트가 없다.** + +wire 필드 이름도 겹친다 — `CourseRegistrationResponse.totalCredits`는 신청 **후** 합계, `RegistrationListResponse.totalCredits`는 **현재** 합계다. + +**제안 규칙** — `creditsCountedTowardLimit(...)` / `creditsForDisplay(...)`로 이름을 가르고, 스코프를 `ActiveRegistrations` 래퍼 타입으로 올려 `currentCredits`가 그것만 받게 한다. + +### 4-13. [중간] GWT harness에 단언 없이 통과하는 경로가 있다 + +`support/Scenario.java:17-32` — `when`/`whenRunning`이 `RuntimeException`을 잡아 `Outcome`에 보관하고 다시 던지지 않는다. `Outcome`은 반환값 소비를 강제하지 않는다(`@CheckReturnValue` 없음). + +harness 3개 클래스만 뽑아 실행 [실측]: + +``` +A. Scenario.given(x).when(v -> boom()); -> GREEN ← 프로덕션 예외를 완전히 삼킴 +B. .then(r -> {}) -> GREEN ← 단언 0개 +C. dangling whenRunning() -> GREEN +D. .thenAccepted() -> AssertionError ← 대조군, 정상 +``` + +현재 약 110개 호출부는 전부 `.then*`으로 끝난다. **규칙은 지켜지고 있고, 지키는 장치가 작성자 습관뿐이다.** jacoco LINE 90% / BRANCH 75% 게이트는 "그 줄을 지나갔는가"만 보므로 단언 0개 테스트도 커버리지를 채운다. + +부수 사실: `Error`는 `catch (RuntimeException)`에 안 걸려 그대로 올라간다. `CourseRegistrationConcurrencyIntegrationTest:195,197,202`가 `when` 람다 안에서 AssertJ를 쓰는데 **안전한 이유가 그것이고, 그 사실이 코드 어디에도 안 적혀 있다.** + +**제안 규칙** — `SourceStyleTest.inspect()`에 규칙 1개 추가: `.when(` / `.whenRunning(`으로 시작한 statement는 `.then` 계열로 끝나야 한다. + +**버리는 것** — 없음. + +### 4-14. [중간] h2/postgresql baseline 두 파일이 서로를 모른다 + +**현재 두 파일은 일치한다** — PG 16-alpine과 H2에 각각 적용해 제약 24개·컬럼 정의가 모두 같음을 확인했다 [실측]. **지금이 고정 비용이 가장 싼 시점**이라는 발견이다. + +- **컬럼** 차이는 `ddl-auto: validate`가 반대편 스위트에서 기동을 막아 잡는다. +- **제약·인덱스** 차이는 **아무 데서도 안 잡힌다.** N6이 139/139 통과 [실측]. +- Flyway checksum은 같은 디렉터리 안에서만 유효하다. 버전 번호 드리프트(h2 `V2`, postgresql `V3`)도 안 잡힌다. +- 제약 계열 단언 3건이 전부 `PostgresIntegrationTest` 상속 클래스 안에 있고, 컨트롤러/API/시더/엔티티 테스트 약 20개 클래스는 H2로 돌면서 제약을 한 줄도 단언하지 않는다. + +알게 되는 시점: 로컬 아님, CI 아님, **prod 배포 후**. + +**제안 규칙** — 두 DB에 baseline을 적용해 `information_schema`의 테이블·컬럼·제약 이름 **집합**을 비교해 diff가 있으면 실패하는 테스트 1개. 타입 표기는 정규화하고, 방언별로 다르게 써야 하면 `-- DIALECT-ONLY: <사유>` 주석을 요구한다. 선례가 있다 — `architecture/SourceStyleTest.java`가 소스를 직접 훑는다. + +--- + +## 5. 관측 — 장애가 나도 재구성할 수 없다 + +1차 리뷰가 "프로덕션 로거 호출 0건"을 지적했다. 재측정 [실측]: + +| 항목 | 개수 | 위치 | +|---|---|---| +| Logger 선언 | **1** | `GlobalExceptionHandler.java:21` | +| `log.*()` 호출 | **1** | 같은 파일 `:47` | +| `logback*.xml` | **0** | — | +| `micrometer-tracing` | runtimeClasspath에 **없음** | — | +| `micrometer-registry-prometheus` | runtimeClasspath에 **없음** | — | + +**숫자는 0 → 1이 됐지만 결론은 바뀌지 않았다.** 그 1줄은 실패의 일부에만 찍히고, 찍히는 것의 대부분은 실패가 아니다(§4-3). + +### 주입한 장애와 운영자가 받는 신호 [실측] + +| 장애 | HTTP | 앱 ERROR 로그 | 원인 구분 | +|---|---|---|---| +| 핫 row 락 3초 초과 (혼잡) | 503 `LOCK_TIMEOUT` @3.05s | **0줄** | Hibernate WARN의 `SQLState: 55P03` 뿐 | +| 락 역순 교차 → **데드락** | 503 `LOCK_TIMEOUT` @1.09s | **0줄** | Hibernate WARN의 `SQLState: 40P01` 뿐 | +| 커넥션 풀 고갈 | **500** @2.07s, `Retry-After` 없음 | 1줄 | Hikari 메시지로만 | +| 시간표 없는 강의 | **500** | **0줄** | **불가 — 서버에 흔적 없음** | +| 학기 2행 (대조군) | 500 | 1줄 | 스택트레이스로 가능 | +| `cleanup()` 실행 | — | **0줄** | 불가 | + +**(a) 정상 혼잡과 (b) 데드락은 응답으로 절대 구분 불가**하고, 구분자는 `org.hibernate.orm.jdbc.error` WARN 한 줄의 SQLState뿐이다. 그 줄에는 userId도 lessonId도 요청 경로도 없어 같은 초의 다른 503과 짝지을 수 없다. + +**그 유일한 구분자마저 설정 한 줄로 사라진다** [실측]. `logging.level.org.hibernate=ERROR`를 준 컨텍스트에서 락 타임아웃 재현 → **WARN+ 로그 0건.** "로그가 시끄럽다"는 흔한 이유로 이 줄을 넣는 순간 락 진단 능력이 통째로 사라지는데, 그 의존성은 저장소 어디에도 적혀 있지 않다. + +### readiness가 앱 트래픽과 같은 커넥션 풀에 줄을 선다 + +1차 P0 #10의 산출물이다. `db` 헬스 인디케이터는 별도 DataSource 없이 같은 Hikari 풀에서 커넥션을 받는다. + +**실측 — 풀 2를 핫 lesson 락으로 포화** + +``` +t+400ms readiness = 503 DOWN (2035ms 소요) +t+400ms liveness = 200 UP (40ms) +t+1000ms readiness = 503 DOWN (2012ms) +t+1600ms readiness = 200 UP (1467ms) +t+2200ms readiness = 200 UP (424ms) +``` + +세 가지가 동시에 확인된다. + +1. **readiness가 DOWN이 되는 임계값이 `connection-timeout`(2000ms)이다.** 아무도 그 숫자를 헬스체크 기준으로 고른 적이 없다 — 요청 처리용으로 정한 값이다. +2. **바디가 `{"status":"DOWN"}` 뿐이다.** `show-details: never`라 `db` 때문인지 `readinessState` 때문인지 probe만 보고는 알 수 없다. +3. **readiness가 뒤집힌 사실을 앱이 로그로 남기지 않는다.** "이 pod가 몇 시에 endpoints에서 빠졌나"는 k8s 이벤트에만 있고 두 타임라인을 잇는 식별자가 없다. + +**[추론]** k8s `readinessProbe.timeoutSeconds` 기본값은 1초다. 위의 1467ms·1853ms는 **성공 응답이었는데도 kubelet에게는 실패**다. 전 pod가 같은 핫 row를 다투므로 상관 실패가 되고, `failureThreshold` 기본 3 → 약 30초면 전 pod가 Service endpoints에서 빠진다. 트래픽이 끊기면 락이 풀려 회복되고 다시 몰리면 반복 → **플래핑**. liveness는 6~40ms로 계속 UP이라 재시작은 안 되고(그 분리는 잘 돼 있다) **살아있지만 아무도 못 오는 pod**가 된다. 이때 클라이언트가 받는 503은 앱의 `LOCK_TIMEOUT` 503과 구분되지 않는다. + +k8s 매니페스트가 저장소에 없어 `timeoutSeconds`와 `connection-timeout`이 서로를 모른다. **1차 리뷰가 graceful shutdown에서 찾은 것과 같은 구조의 문제다.** + +### 500 한 건을 무엇으로도 좁힐 수 없다 + +| 물어볼 것 | 지금 답할 수 있나 | +|---|---| +| 이 500은 어느 요청인가 | **불가** — 응답·로그 어디에도 id 없음 | +| 어느 사용자/강의인가 | **불가** — MDC 비어 있음 | +| 어느 pod인가 | **불가** — 로그 패턴이 전 pod 동일 | +| 어느 빌드인가 | **불가** — `/actuator/info` → **500**, `build-info.properties` 없음 | +| 재시도인가 새 시도인가 | **불가** — `Idempotency-Key`가 응답에도 로그에도 없음 | + +롤링 배포 중 일부 pod만 500을 뱉으면 **어느 pod인지 알 수 없고 살아있는 pod에 "너 무슨 빌드냐"를 물을 수도 없다.** 남는 수단은 전부 롤백뿐이다. + +아이러니 하나 [실측]: **로그에 요청 경로가 등장하는 유일한 경우가 404다.** Spring의 `NoResourceFoundException` 메시지가 경로를 품고 있어서다. 진짜 장애에는 경로조차 없다. + +**반증 확인 (PII/시크릿)** — 실험 로그 전체에 `password`/`secret` 일치 **0건** [실측]. `show-sql`은 local에만 있다. **prod 로그 유출 문제는 현재 없다.** 다만 §4-3 때문에 404의 전체 요청 경로가 ERROR 로그에 들어가므로, 경로에 `userId`가 있는 이 API에서는 오타 요청 하나가 사용자 식별자를 ERROR 로그에 남긴다. + +**보려면 필요한 것 (전부 한 줄~몇 줄)** + +1. `logging.structured.format.console: ecs` — Boot 4가 이미 지원한다. **의존성 추가 없이** JSON 로그가 된다. +2. 요청 진입 필터에서 `requestId`를 만들어 MDC + 응답 헤더 + `ErrorResponse`에 싣는다. +3. `micrometer-registry-prometheus` 의존성 추가 + `exposure.include`에 `prometheus`. **지금은 의존성부터 없다.** +4. `cleanup()`이 삭제 건수를 `log.info`로 남긴다 — 이미 `int`를 반환하는데 버리고 있다. +5. 락 예외 핸들러를 데드락/타임아웃으로 분리하고 각각 `log.warn`으로 SQLState + userId + lessonId를 남긴다. +6. `management.endpoint.health.group.readiness.show-details: always`. + +**제안 규칙** — **"HTTP 5xx로 나가는 모든 경로는 로그를 남긴다"를 테스트로 강제한다.** `RegistrationErrorCode`를 순회해 `getStatus().is5xxServerError()`인 코드가 던져질 때 ERROR 로그가 나오는지 단언하면 된다(현재 `INTERNAL_SERVER_ERROR` 하나가 걸린다). + +--- + +## 6. 코드 변경 0으로 터지는 것 — 학기 개수 + +### 학기 2개 [실측] + +``` +신청기간 안 겹침 → GET /registrations = 200 + 빈 목록 + totalCredits:0/maxCredits:6 +신청기간 겹침 → GET /registrations = 500, GET /lessons = 500, POST = 201 (계속 성공) +``` + +`register()`가 `SemesterResolver`를 안 타고 `locked.lesson().getSemester()`를 쓰기 때문이다. **"신청은 되는데 무엇을 신청했는지 볼 수 없는" 상태**가 된다. `seed/demo/semesters.tsv`의 신청기간이 2000~2099라 local/dev에 두 번째 학기를 넣으면 무조건 겹치는 쪽으로 간다. + +### 학기 0개 [실측] + +``` +semesters 0행 + GET /lessons → 404 SEMESTER_NOT_FOUND "현재 수강 가능한 학기를 찾을 수 없습니다." + GET /lessons?semesterId=no-such-id → 404 SEMESTER_NOT_FOUND "학기를 찾을 수 없습니다." + 두 응답의 status·code 동일. 앱 로그 0건. +``` + +`resolve()`가 성공하려면 오늘이 어떤 학기의 신청기간 **또는** 학사기간 안이어야 한다. 실제 대학 일정이면 **6/22~7월 말은 두 조건 모두 밖**이다. 그 기간 내내 전 학생의 조회가 404이고, pod는 Ready이고, **에러율은 0%**(4xx니까)이고, 배포가 없었으니 롤백 대상도 없다. 그리고 `seed/demo/semesters.tsv`가 2000~2099라 **local/dev에서는 영원히 재현 안 되는 prod 전용 실패**다. + +`SemesterResolver.notFound()`가 코드를 하드코딩해서 "클라이언트 오타"와 "전사 조회 불능"이 같은 404로 합쳐졌다(§4-5). + +**제안 규칙** — "현재 학기"를 전역 단수로 해석하지 않는다. `resolve()`가 `List`를 반환하고, 학기가 2개 이상이면 500이 아니라 400으로 `semesterId`를 요구한다. 학기 0개는 입력 오류와 다른 코드로 내보내고 로그를 남긴다. + +--- + +## 7. 에이전트 간 의견이 갈린 지점과 판정 + +### 데드락은 500인가 503인가 — **판정 완료 [실측]** + +- `cognitive-load`, `test-strategy`: "`DeadlockLoserDataAccessException`은 `PessimisticLockingFailureException` 하위가 아니므로 500" +- `change-pressure`: "`CannotAcquireLockException` → 하위 → 503" + +spring-tx 6.2.11 바이트코드: + +``` +DeadlockLoserDataAccessException extends PessimisticLockingFailureException +CannotAcquireLockException extends PessimisticLockingFailureException +PessimisticLockingFailureException extends ConcurrencyFailureException +``` + +**`change-pressure`가 맞다. 그리고 결과적으로 더 나쁘다.** `GlobalExceptionHandler:38`이 잡으므로 데드락은 **503 `LOCK_TIMEOUT` + `Retry-After`로 나가고, 이 핸들러에만 `log` 호출이 없다.** 설계 결함인 데드락이 "혼잡"과 같은 응답 코드에 흔적 없이 흡수된다. + +PostgreSQL `deadlock_timeout` 기본값 1초 < 이 프로젝트의 `lock_timeout` 3초이므로 **데드락이 락 타임아웃보다 먼저 온다.** PG16에서 2세션 교차로 `ERROR: deadlock detected`를 확인했고, HTTP 끝단까지 실측으로 확인했다(503 @1093ms, SQLState 40P01). + +### 메시지를 중앙화할 것인가 — **판정: 하지 않는다** + +리뷰 중간에 "`RegistrationErrorCode`가 기본 메시지를 소유하게 하자"는 제안이 나왔고 **기각했다.** 근거: 17개 코드 중 15개는 throw 자리가 1~2곳이라 중복이 적고, `Requirements.md:542`가 요구하는 숫자 포함 메시지가 throw 자리에 값이 있어서 가능하며, `VALIDATION_ERROR`·`REGISTRATION_NOT_FOUND`처럼 **지금 서로 달라야 하는 메시지**가 강제로 합쳐진다. 대신 §4-6의 `category` 축을 넣는다. + +### `DataIntegrityViolationException` 번역은 언제 할 것인가 — **판정: cause 먼저** + +1차 판단은 "제약 이름별로 도메인 코드에 매핑하라"였다. **그대로 구현하면 관측성이 순감한다** [실측]. + +오늘 제약 이름을 알 수 있는 유일한 경로가 `handleUnexpected`의 스택트레이스다: + +``` +Hibernate :: HHH000247: ErrorCode: 23505, SQLState: 23505 +Hibernate :: Unique index violation: "PUBLIC.UK_USER_ACTIVE_LESSON ... VALUES ('0f59...','485e...')" +GlobalExceptionHandler :: Unhandled request failure (chain contains 'uk_user_active_lesson' = true) +``` + +409로 번역하면 이 경로에서 빠져나가고, `RegistrationException`에 **`cause` 생성자가 없어서** SQLState·제약 이름도 같이 사라진다. 결과는 409 + 앱 로그 0건이고, "§4-1의 락 우회가 실제로 발생하고 있는가"를 물을 방법이 사라진다. + +**순서:** ① `RegistrationException`에 `(code, message, Throwable cause)` 추가하고 번역된 예외는 cause 없이 못 만들게 한다 ② cause가 있으면 `log.warn` ③ **그다음** 번역. cause 유무가 "이건 번역된 실패다 = 하위 계층이 실제로 터졌다"의 표시가 된다. + +### 락 안에서 판정해도 되는 것의 기준 — **판정: R1~R8이 아니다** + +리뷰 중간 판단은 "락을 쥐고 판정해도 되는 것은 R1~R8뿐"이었다. **틀렸다.** 정확한 기준은 **"다른 요청의 쓰기 결과에 의존하는 규칙뿐"**이고, 그러면 R2·R3가 빠진다(§4-11). + +--- + +## 8. 결정이 필요한 것 + +여기부터는 팀이 골라야 한다. 리뷰가 정할 수 없다. + +| # | 결정 | 선택지 | 버리는 것 | +|---|---|---|---| +| 1 | 락 경계를 타입으로 닫을 것인가 | (a) private 생성자 토큰 → **컴파일 불가** (b) ArchUnit + 소스 스캔 → "잡아낸다" | (a)는 테스트 픽스처·스크립트 편의 | +| 2 | 테스트 Clock을 전진시킬 것인가 | (a) `MutableClock` (b) 안 바꾸고 `:98`에 주석 | (a)는 `isEqualTo(NOW)` 단언 2~3곳 | +| 3 | 멱등키 범위를 누가 정하나 | (a) 서버가 "시도마다 새 키"를 계약으로 문서화 (b) 서버가 replay 시 재조회로 방어 | (a)는 클라이언트를 믿어야 함, (b)는 SELECT 1회 | +| 4 | baseline parity 테스트를 지금 넣을 것인가 | 현재 일치 확인됨 → **지금이 가장 쌈** | Postgres 전용 최적화를 조용히 넣는 편의 | +| 5 | `INTERNAL_SERVER_ERROR`를 도메인 enum에 둘 것인가 | (a) `category` 축 추가 (b) enum에서 제거하고 별도 예외 타입 | (b)는 예외 타입 1개 추가 | +| 6 | "강의는 시간표 ≥1개"를 규칙으로 승격할 것인가 | (a) 승격 + 쓰기 경계에서 강제 (b) 허용하고 409 도메인 코드로 | (a)는 2단계 강의 등록 절차 | +| 7 | k8s 매니페스트를 저장소로 들여올 것인가 | readiness 타임아웃과 `connection-timeout`을 같은 리뷰 단위에 두려면 **선행 조건** | 저장소 범위 확대 | + +--- + +## 9. 실측 vs 추론 + +### 실측 (재현 가능) + +- 변조 23건 + 대조군 (샌드박스 `./gradlew test` 23회) +- 락 경계 우회 3종 전부 전체 테스트 통과 +- 앱 검증 제거 시 중복 신청이 409가 아니라 500 +- 학기 2개 / 학기 0개 프로브 +- 우회 INSERT로 잰 실제 방어 계층 수 (blank name, role='GHOST', 시간블록 겹침 통과) +- 시간표 삭제의 폭발 반경 (무관한 강의 신청까지 500, 로그 0건) +- 404·405·415·타입불일치 → 500 + ERROR 로그 (9케이스), 미매핑 경로 30회 → 정확히 30줄 +- 풀 4 / 요청 8 → 500×4(2.07s) + 503×4(3.05s), HikariMXBean `active=4 idle=0 awaiting=6` +- 데드락 end-to-end 503 @1093ms SQLState 40P01 (혼잡은 55P03 @~3000ms) +- `logging.level.org.hibernate=ERROR` → 락 타임아웃 시 WARN+ 0건 +- readiness 포화 실험 (503 DOWN 2035ms ↔ 200 UP 1467ms, liveness 6~40ms) +- 멱등 TTL 만료 시 201 → 409 전환, 공백 키가 멱등을 끄는 것 +- 최초 201과 replay 201의 바디가 바이트 동일 +- `page=99999999` → 400 (1차 500에서 고쳐짐), DELETE 3회 연속 204, 동시 150건 중복 0 +- PG16 + H2 제약 24개 일치, PG16 생성 컬럼 변경 경로, H2와 PG의 정반대 DDL 동작 +- GWT harness dangling `when()` 삼킴 +- spring-tx 6.2.11 예외 계층, Hibernate 40P01/55P03 분기 (javap) +- Boot 4.1.1 `defaults.xml`에서 `LOG_CORRELATION_PATTERN` 빈 값 확인, micrometer-tracing/prometheus 부재 +- 프로덕션 로거 선언 1 / 호출 1, `logback*.xml` 0개 +- 거부 예외 생성 비용: 스택 157프레임, 10.7µs vs 69ns (150배) — **최적화 대상 아님** + +### 추론 (가정 위의 계산) + +- 멱등 재시도의 락 경합 비율 — 부하 테스트 없음 +- R2·R3가 락 큐에 미치는 영향 — 부하 테스트 없음 +- k8s readinessProbe 기본값에서의 전 pod 퇴출·플래핑 — 매니페스트 부재로 실환경 미검증 +- 롤링 배포 중 두 버전 공존 데드락 — 현재 역순 경로가 없어 애플리케이션으로 재현 불가 +- 대용량 `user_lessons`의 `AccessExclusiveLock` 지속 시간 — 빈 테이블에서 락 등급만 확인 +- `IdempotencyRetentionJob` 벌크 DELETE와 `deleteExpiredKey`의 행 경합 +- M9·M12는 재측정하지 않았다 (1차에서 검출됐고 테스트가 순증) + +--- + +## 10. 이 리뷰가 못 본 것 + +- **부하 테스트 없음.** 500:503 비율은 풀 4 / 요청 8이라는 인위적 비율에서 나온 값이다. prod(풀 20 / pod 3)의 실제 분포는 미측정 +- **다중 Pod 실환경 검증 없음.** 롤링 중 공존, 로그 귀속 불가는 단일 JVM에서 재현 불가 +- **운영 PostgreSQL 버전이 저장소에 명시돼 있지 않다.** 생성 컬럼 변경 경로는 PG16 기준이고 PG17+에는 `ALTER COLUMN ... SET EXPRESSION`이 있다 +- **prod 강의 마스터 데이터 투입 경로가 저장소에 없다.** §4-2의 "prod 소유자 0개"는 저장소 기준이다. 별도 절차에 검증이 있다면 축소된다 +- **로그 수집 파이프라인 정보가 없다.** "JSON으로 바꾸면 검색된다"는 수집기가 있다는 전제다 +- k8s 매니페스트가 여전히 저장소에 없다 (1차 리뷰와 동일) +- 1차 P2 항목(PK `varchar(36)` → `uuid` 등)은 이번 범위가 아니다 + +### 실행 환경 메모 + +병렬 리뷰 중 공용 scratchpad가 에이전트 간에 **두 번 덮어써졌다.** 1차 리뷰 §10에 같은 경고를 적어두고 이번에도 고유 디렉터리를 지정하지 않았다. 다음 리뷰에서는 에이전트마다 `--` 형태의 고유 디렉터리를 프롬프트에 명시한다. 원본 워킹트리는 영향받지 않았고 종료 시 `git status --porcelain` 확인했다. + +--- + +## 부록: 이번에 쓴 에이전트 + +`.claude/review-workflow.md`의 Phase 1 → Phase 2 순서로 9개. + +### Phase 1 — discovery + +| 에이전트 | 맡은 것 | +|---|---| +| `invariant-miner` | 신규 코드가 도입·파괴한 불변식 | +| `change-pressure` | 정정기간 / 대기열 / 관리자 CRUD / 학기 2개 주입 | +| `cognitive-load` | 비지역적 규칙과 GWT harness의 암묵 계약 | +| `test-strategy` | M1~M13 재측정 + 신규 변조 (1차 핵심이 측정치였으므로 숫자를 다시 냄) | + +### Phase 2 — specialist + +| 에이전트 | 맡은 것 | 선정 근거 | +|---|---|---| +| `error-design` | 실패 전파 경로 | 사용자 질문 + Phase 1의 500 관련 가설 | +| `validation-layering` | 제약 provenance | 사용자 질문 + 계층별 방어 수 미확인 | +| `layering-domain` | 규칙 소유권 | 사용자 질문의 "왜 서비스/validator에 있어야 하나" | +| `http-contract` | 클라이언트 상태 머신 | 멱등 계약 + 학기 2개의 클라이언트 영향 | +| `observability-ops` | 장애 재구성 | 1차 "로거 0건" 재측정 + 503 무로그 확장 | + +`adversarial-verifier`는 돌리지 않았다. 발견 대부분이 실제 변조·실기동·DB 실험으로 확인돼 반증 대상이 아니었고, 에이전트 간 충돌 1건은 §7에서 바이트코드로 직접 판정했다. §9의 추론 항목은 부하 테스트와 실환경 검증이 필요하지 반증 리뷰로 해결되지 않는다.