diff --git a/docs/reviews/2026-11-03-rereview/round7/review.md b/docs/reviews/2026-11-03-rereview/round7/review.md new file mode 100644 index 00000000..a14c5ec9 --- /dev/null +++ b/docs/reviews/2026-11-03-rereview/round7/review.md @@ -0,0 +1,337 @@ +# round7 — r10 수정 커밋 확인 리뷰 (2026-11-06) + +> 대상: 커밋 `6e992970`(r10, round6 결함 25건 수정), Base `45d2a478`(r9). 리뷰를 시작한 HEAD는 `06477350` +> (브랜치 `claude/t1-baseline-7d623a`, `claude/improvement-manual-6ae516`에서 딴 worktree)다. `6e992970` 뒤의 커밋 넷은 +> `docs/improvement/`·`docs/manual/README.md`·리뷰 README·계획서만 바꿨고 이 리뷰의 대상 파일은 건드리지 않았다 +> (`git diff --stat 6e992970 06477350`). +> +> 방법: 리뷰어 1명이 네 영역을 직접 봤다(하위 에이전트 없음, `docs/improvement/09-working-method.md` 6절). 절차는 +> `docs/improvement/` 01장 1절, 02장 3.2·8.2절, 09장 5절을 따랐다. 결함 ID는 `RR7-<영역>-<순번>`이고 영역 번호는 +> round6과 같다(01 core·inbound, 02 멱등성·outbound, 03 persistence, 04 build-logic). 리뷰는 읽기 전용이다. 의심 결함은 +> desktop의 임시 worktree에 탐침을 얹어 확인했고, worktree는 끝나고 지웠다. + +## 범위 + +### pathspec + +커밋 전체: `git diff --stat 45d2a478..6e992970` → 97개 파일, +5143 −925. 영역별로 나눠 봤다. + +| 영역 | pathspec | `git diff --shortstat` | +| --- | --- | --- | +| 01 core·inbound | `src/app-bootstrap/src/architectureTest src/shared-contract src/adapter/inbound/{web,graphql,grpc,websocket} docs/manual/07-authorization.md` | 33개 파일, +1076 −132 | +| 02 멱등성·outbound | `src/application-core src/adapter/outbound/cache-redis src/adapter/outbound/redis-runtime …/idempotency/postgresql/PostgreSqlIdempotencyStore.java docs/manual/05-idempotency.md docs/runbooks/idempotency-unavailable.md` | 15개 파일, +412 −461 | +| 03 persistence | `src/adapter/outbound/persistence-jpa src/adapter/outbound/persistence-notification src/adapter/inbound/messaging src/sample-portfolio src/grpc docs/jpa docs/manual/04-persistence.md docs/study` | 31개 파일, +875 −135 | +| 04 build-logic | `src/build-logic AGENTS.md CLAUDE.md src/README.md` | 11개 파일, +1947 −201 | + +나머지는 `docs/upgrade/2026-11-maturity-review.md`, `docs/testing/TESTING_STRATEGY.md`, `docs/reviews/**`다. 앞의 둘은 해당 +영역과 함께 읽었다. `docs/reviews/**`(round6 문서 넷, 재리뷰 README 17절, 성숙도 리뷰 README 17절)는 리뷰 기록이라 결함 +대상이 아니고 「항목 재확인」의 근거로만 읽었다. + +`ShellScript.java`(1659줄)와 `WorkflowGradleInvocations.java`(1248줄)는 diff와 함께 `6e992970`의 새 메서드 전체를 읽었다. + +### 함께 읽은 주변 코드 + +- 01: `ApplicationBoundaryArchitectureTest`의 `ARE_USER_TRANSPORT_TYPES`(`:471-491`)와 새 `ARE_REQUEST_HANDLER_TYPES` + (`:498-548`)·`ARE_USER_TRANSPORTS`(`:565-590`), `SystemCallerHandlerFixture`, `GraphQlWireErrorMapper.sharedCodeOf`, + `GrpcExceptionHandlingInterceptor.interceptCall`·`closeWithError` 경로, `ServerFailureLog.of`, app-bootstrap lockfile의 + `architectureTestCompileClasspath`(`jakarta.ws.rs-api`, `jakarta.websocket-api`가 있다). +- 02: Redis `IdempotencyScripts.CLAIM`·`TRANSITION` 전체, `PostgreSqlIdempotencyStore.claim`·`markExecutionStarted`, + `IdempotencyExecutor`의 claim·start 분기, `newAttempt`를 부르는 운영 코드(`PublishPosterImageUseCase:106`, 요청마다 + 새 attempt), `IdempotencyStoreContract`의 새 케이스 6개, 지운 adapter 테스트 20개와 계약 케이스의 대응, + `docs/web/http-contract.md` §2 표, `docs/registries/error-codes.yaml`의 `IDEMPOTENCY_UNAVAILABLE`. +- 03: `FlywaySchemaPolicy` 전체, 운영·테스트 코드의 `Flyway.configure` 호출 전부(grep), 새 + `PostgreSqlConcurrentIndexMigrationIntegrationTest` 전체, `ConcurrentIndexMigrationInspector` 전체, 각 leaf + lockfile의 `flyway-database-postgresql`. +- 04: `.github/workflows/` 15개의 `on:`·`runs-on:`, `src/gradle/wrapper/gradle-wrapper.properties`(9.0.0), + `GradleCommandLineTest`, `build-logic.yml`(이 테스트를 도는 workflow, `src/gradle/**` 경로 포함). + +### 불러온 스킬과 적용한 기준 + +| 스킬 | 적용한 기준 | 본 것 | +| --- | --- | --- | +| `superpowers:requesting-code-review` | 리뷰어 템플릿: 계획(재리뷰 README 17절 r10 행) 대비 구현, 테스트가 진짜 동작을 보는가, 문서 완결성, 심각도별 Issues, Declined to judge, 읽기 전용, 하위 리뷰어를 띄우지 않음 | 25건마다 닫힘 여부(「항목 재확인」), 고친 규칙이 원래 잡던 것을 놓치지 않는가(RR7-01-01), 새 문서 문장이 사실인가(RR7-03-01). 템플릿은 리뷰어 subagent를 띄우라고 하지만 매뉴얼 09장 6절대로 이 세션이 직접 리뷰했다. 템플릿의 Issues·Declined는 매뉴얼 02장 8.2절 순서로 옮겼고, Strengths는 「결론」에 적었다 | +| `research-first` | 크기(중간) → 목적·선행 사례·필요 정보·격차·확인 | 선행 사례로 round4~6 확인 리뷰 문서의 범위·탐침·Declined 처리 방식을 따랐다. 보고에 사고 순서 흔적을 남겼다 | + +영역 스킬(`clean-architecture`, `ci-cd-and-automation`, `supabase-postgres-best-practices`)은 따로 부르지 않았다. 각 +영역의 판정 기준은 round6 문서가 그 스킬로 세운 기준(설정은 조립 루트이지 입구가 아니다 / 게이트는 거짓 통과가 없어야 +한다 / Flyway 잠금과 CIC의 대기 관계)을 그대로 썼다. + +### 실행한 명령과 결과 + +모두 desktop(`~/workspace/clean-architecture-backend-template`)의 임시 detached worktree `/tmp/r7/wt10`(`6e992970`)과 +`/tmp/r7/wt9`(`45d2a478`)에서, 탐침 파일만 얹어 공유 잠금(`flock /tmp/claude-gates/heavy.lock`)으로 돌렸다. 괄호 안은 +잠금을 얻은 뒤의 1분 부하다. 탐침 코드, 실행 스크립트, 로그, 테스트 보고서(XML)는 공유 노트 폴더 `r7-probes/`에 있다 +(저장소 밖). 탐침은 고칠 때 fixture·RED 테스트로 옮겨 쓸 수 있게 테스트 모양으로 썼다. + +| # | 명령 (worktree) | 결과 | 시간 | 부하 | +| --- | --- | --- | --- | --- | +| 1 | `./gradlew :app-bootstrap:architectureTest` (r10 + 탐침 fixture 3개·`Round7ProbeTest`) | rc=1. 231개 중 원래 228개 통과, 탐침 3개 중 2개 실패: 설정에 중첩된 JAX-RS resource 위반 0건, 설정에 중첩된 `@ServerEndpoint` 위반 0건. 최상위 JAX-RS resource는 1건(통과) | 51초 | 1.13 | +| 2 | 같은 명령 (r9 + 같은 탐침) | rc=0. 219개 모두 통과: 탐침 셋 모두 위반 1건 | 142초 | 4.70 | +| 3 | `./gradlew :verifyStrictLaneStages --dry-run` (r10) | rc=0, "every strict lane is in an executed stage" | 23초 | 7.83 | +| 4 | `./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run` (r10) | rc=0, 같은 출력 | 16초 | 5.77 | +| 5 | `unzip -p flyway-database-postgresql-11.14.1.jar …/PostgreSQLConfigurationExtension.class \| strings` (Gradle 캐시) | 상수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK`, `flyway.postgresql.transactional.lock`이 있다 | — | — | +| 6 | `./gradlew :adapter:inbound:grpc:test --tests '*GrpcExceptionHandlingInterceptorTest'` (r10 + 탐침 1개) | rc=1. 18개 중 원래 17개 통과, 탐침 실패: 원인이 `IllegalArgumentException`인 raw status를 던지면 `INTERNAL`·ERROR(예외 메시지 `unknown recipient alice@example.com` 첨부), 같은 status를 `close`로 넘기면 `INVALID_ARGUMENT`·WARN(메시지 없음) | 19초 | 2.78 | +| 7 | `./gradlew -p build-logic test` (r10) | rc=0, 테스트 162개, 실패·건너뜀 0 | 56초 | 5.40 | +| 8 | `./gradlew :adapter:outbound:persistence-jpa:postgresqlConcurrentIndexMigrationIntegrationTest` (r10 + 탐침 2개) | 첫 실행 rc=1: 탐침 코드가 Error Prone `StringConcatToTextBlock`(-Werror)으로 컴파일 실패(68초, 7.17). 탐침을 고쳐 다시 실행: rc=1, 6개 중 원래 4개 통과(CIC·`REINDEX … CONCURRENTLY` × Spring Boot 조립·정책), 탐침 2개 중 1개 실패 — 아래 표 | 124초 | 3.75 | +| 9 | 같은 lane (r10 + 탐침 3개) | rc=1, 7개 중 원래 4개 통과, 탐침 3개 중 2개 실패(8의 것과 복구 탐침) — 아래 표 | 22초 | 1.42 | + +명령 8·9의 PostgreSQL 탐침. V1은 `probe` 테이블과 일반 인덱스, 그리고 `note`가 겹치는 행 하나를 넣는다. 모두 +`FlywaySchemaPolicy.configure()`(세션 잠금)로 적용했다. + +| V2 | `.sql.conf` | 결과 | +| --- | --- | --- | +| `INSERT … (3001, 'partial');` + `CREATE UNIQUE INDEX CONCURRENTLY …;` | 없음 | Flyway가 실행 전에 거부("Detected both transactional and non-transactional statements … mixed is false"). 행 3001 없음, 이력 V1만 | +| 같음 | `executeInTransaction=false` | `FlywayMigrateException` SQLState 23505. **행 3001이 남았다**(부분 적용), `ix_probe_note_u valid=false`, 이력 `2 success=false` | +| `CREATE UNIQUE INDEX CONCURRENTLY …;` 하나 | `executeInTransaction=false` | 23505로 실패. 겹친 행을 지우고 가이드대로 `DROP INDEX ix_probe_note_u` 뒤 다시 배포 → `FlywayValidateException: Validate failed: … Detected failed migration to version 2 (unique note).` 이력 `2 success=false`가 남아 다음 배포가 막힌다 | + +임시 worktree 둘과 `/tmp/r7`은 끝나고 지웠다(`git worktree list`에 남은 것 0). desktop checkout의 브랜치는 건드리지 않았다. + +### 못 본 것 + +- 전체 `ci`·`mainCheck`·`integrationCheck`는 돌리지 않았다. `6e992970`과 같은 트리(`2c692554`)가 desktop에서 모두 통과한 + 기록이 재리뷰 README 17.2절에 있다(E0). 이 리뷰는 판정에 필요한 lane만 다시 돌렸다(위 표). +- 실제 GitHub runner, Windows runner의 `pwsh`. RR6-04-04 닫힘은 코드(E1)와 `-p build-logic test`(E2)로만 봤다. +- JAX-RS·JSR-356 endpoint를 실제로 띄운 실행. RR7-01-01은 ArchUnit 규칙의 판정만 확인했다(규칙이 막는다고 약속한 것이 + 판정이다). +- Flyway CLI와 실제 배포 마이그레이션 도구. 업그레이드 안내 15행의 환경 변수 이름은 플러그인 jar의 상수로만 확인했다(명령 5, E1). +- `flyway repair`를 실제로 돌린 복구. RR7-03-02의 권장안은 실행하지 않은 제안이다. +- RR6-02-02의 변이 3건, RR6-03-04의 optional `spotlessCheck`는 다시 돌리지 않았다(재리뷰 README 17절 기록, E0). + +## 항목 재확인 + +재리뷰 README 17절이 고쳤다고 한 round6 결함 25건이다. 경로의 앞부분은 줄였다(`ApplicationBoundaryArchitectureTest`는 +`src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/` 아래, 나머지는 파일 이름으로 찾는다). + +| ID | 판정 | 근거 | +| --- | --- | --- | +| RR6-01-01 (Important, 회귀) | 닫힘 — 단 고친 방식이 RR7-01-01을 만들었다 | 설정과 그 중첩 클래스는 `ARE_REQUEST_HANDLER_TYPES`에 의존하면 사용자 전송이다(`ApplicationBoundaryArchitectureTest.java:565-590`). 함수형 route·`DataFetcher`·중첩 `HandlerFunction` 위반 fixture가 잡힌다(`ArchitectureViolationFixtureTest.java:565-617`, 명령 1의 228개 통과) | +| RR6-01-02 | 닫힘 | 설정 필드를 읽는 익명 `WebMvcConfigurer`가 통과한다(`ArchitectureViolationFixtureTest.java:619`, 명령 1). 같은 변경이 중첩 클래스 판정을 좁혔다 → RR7-01-01 | +| RR6-01-03 | 닫힘 | 예외 제외(`:749`), record·enum은 언어가 주는 상위 타입만 허용(`:798-809`). `Runnable` record는 여전히 잡힌다(fixture, 명령 1) | +| RR6-01-04 | 닫힘 | 판정이 status 코드에서 `delegate.isCancelled()`로 바뀌었다(`GrpcExceptionHandlingInterceptor.java:143`). 살아 있는 호출의 `CANCELLED`는 남는다(테스트 `aCancelledStatusTheServiceClosesALiveCallWithIsLoggedAsUnhandled`) | +| RR6-01-05 | 닫힘 | 던진 raw status는 그 status 예외를 붙이지 않고 그 뒤의 원인만 붙인다(`:173-180`). 설명은 남지 않는다(테스트 2건, 명령 6). 던진 raw status의 원인이 `IllegalArgumentException`이면 그 메시지가 붙고 답도 `onError`와 다르다 → RR7-01-02(이전부터) | +| RR6-01-06 | 닫힘 | 네 전송이 `ServerFailureLog.refusedArgument`(`ServerFailureLog.java:91`)의 WARN 한 줄을 쓴다: web `GlobalExceptionHandler.java:88`, GraphQL `GraphQlWireErrorMapper.java:130-140`, gRPC `GrpcExceptionHandlingInterceptor.java:137-139`, STOMP `StompHandlerFailureLog.java:39-43`. 전송마다 메시지·예외가 없음을 단언하는 테스트가 있다 | +| RR6-01-07 | 닫힘 | runbook이 그 문구를 붙은 예외의 메시지(prod JSON의 `stack_trace`)로 적는다(`idempotency-unavailable.md:22-25`, `:103`) | +| RR6-01-08 | 닫힘 | 테스트가 4xx carrier(`IdempotencyInFlightException`)를 넣는다(`GraphQlWireErrorMapperTest.java:194-205`) | +| RR6-01-09 (이전부터) | 닫힘 | 대상이 `dev.caskeleton.shared..`이고 허용은 정확한 12개 패키지(`ForbiddenApiArchitectureTest.java:59-72`, `:114-127`). fixture는 대리 뿌리로 증명하고, 목록과 모듈의 실제 패키지가 같은지 본다(`SharedContractPackageRuleTest`). 모듈 패키지 12개와 `CLAUDE.md` 목록이 같다(`ls`로 확인). "KNOWN DEFECT" 주석은 지워졌다 | +| RR6-02-01 | 닫힘 | Redis CLAIM이 넘겨받기를 같은 owner 재생보다 먼저 본다(`IdempotencyScripts.java:86-98`). 시작의 ALREADY는 기록 revision이 핸들 + 1일 때만(`:160-162`). PG도 같은 순서(`PostgreSqlIdempotencyStore.java:141-160`)이고 시작 digest가 핸들의 attempt·revision을 담는다(`:193`). command fake·in-memory fake도 같은 순서. 계약 케이스 6개(`anAttemptWhoseStartWasRefusedTakesItsClaimOverWhenItClaimsAgain`, `aLateStartThroughTheHandleBeforeTheTakeoverIsRefusedAsAStaleOwner` 등)가 Redis·PG·두 fake에 걸린다. 운영 호출자는 요청마다 새 attempt를 만들어(`PublishPosterImageUseCase.java:106`) 바뀐 순서가 운영 요청의 재생을 바꾸지 않는다 | +| RR6-02-02 | 닫힘 | command fake가 hash TTL·`PTTL`을 모델링한다(`InMemorySemanticRedisCommands.java:684-709`). `TESTING_STRATEGY.md`가 skip 0과 변이 3건을 적는다. 이 리뷰에서 변이는 다시 돌리지 않았다(E0) | +| RR6-02-03 | 닫힘 | RR6-01-07과 같은 문장 | +| RR6-02-04 | 닫힘 | web README 매핑 표(`src/adapter/inbound/web/README.md:243`), 인계 표(`docs/upgrade/2026-11-maturity-review.md:284`)가 `docs/web/http-contract.md:111`과 같은 뜻이다 | +| RR6-02-05 | 닫힘 | 매뉴얼 05 첫 문단이 저장소별로 나뉜다(`docs/manual/05-idempotency.md:57-61`) | +| RR6-03-01 (Important, 이전부터) | 닫힘 | module-defaults `spring.flyway.postgresql.transactional-lock: false`(`persistence-jpa.yml:140-149`), 직접 만드는 Flyway는 `FlywaySchemaPolicy.configure()`(`:115-122`), 운영 코드의 `Flyway.configure` 호출은 ArchUnit이 거부(`JpaProductionArchitectureTest.java:169-190`, grep으로 남은 운영 호출 0 — messaging inbox stream의 사본만 예외이고 대조 테스트가 있다). 실 PG IT 4건이 Spring Boot 조립과 정책 양쪽으로 CIC·`REINDEX … CONCURRENTLY`를 끝낸다(명령 8·9에서 원래 4건 통과, E3). Flyway 플러그인 jar의 환경 변수 이름이 업그레이드 안내 15행과 같다(명령 5) | +| RR6-03-02 | 닫힘 | E-문자열(`LockWaitMigrationInspector.java:477-507`)과 중첩 주석(`:510-528`). 테스트 6건 | +| RR6-03-03 | 닫힘 | `PostgreSQLParser`의 static `Pattern` 8개를 값까지 고정하는 테스트가 PR `ci` lane에 있다(`LockWaitMigrationInspectorTest.java:274-298`). Javadoc·가이드가 "대조 목록의 문장만"으로 고쳐졌다 | +| RR6-03-04 | 닫힘(E1) | ledger Spotless가 Sync 출력을 뺀다(`src/grpc/grpc-operation-ledger-jpa/build.gradle:37-41`). 이 리뷰에서 다시 돌리지 않았다 | +| RR6-03-05 | 부분 | 세 곳이 "Flyway가 늘 트랜잭션으로 감싼다"를 더 말하지 않는다. 그러나 고쳐 쓴 학습 문서가 "섞인 파일은 부분 적용되지 않는다"는 새 틀린 문장을 넣었다 → RR7-03-01 | +| RR6-04-01 | 닫힘 | 작업 없이 끝나는 옵션 표(`WorkflowGradleInvocations.java:134-142`)와 판정. `GradleCommandLineTest`가 `--stop`·`--foreground` 밖의 옵션을 실제 launcher로 돌린다 | +| RR6-04-02 | 닫힘 | `GradleCommandLineTest.java:60`이 판독기 옵션 표를 이 빌드를 돌리는 Gradle(`build.gradle:110`의 `ca.gradle.home`, wrapper 9.0.0)의 `--help`와 비교한다. 이 테스트를 도는 `build-logic.yml`의 경로 필터에 `src/gradle/**`가 있어(`:12`, `:18`) wrapper를 올리는 PR에서 돈다 | +| RR6-04-03 | 닫힘 | 조건부·함수 안 `exit 0`, `exec`, `set -n`, EXIT·ERR trap(`ShellScript.java:1225-1460`). 서브셸·파이프·명령 치환 안의 `exit`은 그 셸만 끝낸다고 바르게 뺀다. `source`·`eval` 뒤는 디렉터리를 못 읽어 세지 않는다 | +| RR6-04-04 | 닫힘(E1·E2) | 셸 없는 step은 `container:`나 Linux·macOS label일 때만 센다(`WorkflowGradleInvocations.java:753-787`). 이 repo workflow 15개는 모두 `ubuntu-latest`다 | +| RR6-04-05 | 닫힘 | 세지 않는 이유 셋이 `NOT_COUNTED`(`StrictLaneStagesPlugin.java:61-75`), 두 판독기의 메시지, `AGENTS.md`·`CLAUDE.md`·`src/README.md`·build-logic README·업그레이드 B-36에서 같은 분류다(문장 대조) | +| RR6-04-06 | 닫힘 | 요청형 trigger·`types`, `workflow_call`의 호출자, `needs` 사슬(`WorkflowGradleInvocations.java:570-750`). 두 빌드의 `verifyStrictLaneStages --dry-run`이 이 repo workflow로 통과한다(명령 3·4) | + +## 결함 + +### RR7-01-01 · Minor · 설정에 중첩된 JAX-RS resource와 JSR-356 endpoint가 `@SystemCaller`를 불러도 잡히지 않는다 (회귀) + +- **위치**: + - 규칙: `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ApplicationBoundaryArchitectureTest.java:565-590` + (`ARE_USER_TRANSPORTS` — 설정이거나 설정에 중첩된 클래스는 `ARE_REQUEST_HANDLER_TYPES`로만 판정, `:574-579`), `:583-590` + (`isOrIsNestedInAConfiguration`). + - 두 목록: `:471-491`(`ARE_USER_TRANSPORT_TYPES` — `jakarta.ws.rs..`, `jakarta.websocket..`, `org.springframework.web..`, + `org.springframework.messaging.simp..` 전체), `:498-548`(`REQUEST_HANDLER_TYPE_NAMES`·`ARE_REQUEST_HANDLER_TYPES` — JAX-RS 항목이 없고, + `jakarta.websocket`은 `Endpoint` 하나뿐이다). + - 안내: `docs/manual/07-authorization.md:105`(② 설정과 그 안에 중첩된 클래스는 요청 처리기 타입으로 판정), + `:108-113`("새 전송 라이브러리를 들이면 … 요청 처리기 타입도 … 함께 더한다"). +- **무엇이 틀렸나**: + - r9는 `@Configuration`이 붙은 클래스 자신만 사용자 전송에서 뺐다. 그 안에 중첩된 클래스는 다른 클래스처럼 + `ARE_USER_TRANSPORT_TYPES`로 판정했다. + - r10은 설정에 중첩된 클래스도 좁은 목록 `ARE_REQUEST_HANDLER_TYPES`로 판정한다. 설정 필드를 읽는 익명 + `WebMvcConfigurer`를 풀어 주려는 변경(RR6-01-02)이다. + - 그런데 좁은 목록이 넓은 목록의 라이브러리를 다 덮지 않는다. `ARE_USER_TRANSPORT_TYPES`가 아는 JAX-RS + (`@Path`·`@POST`)와 JSR-356 annotated endpoint(`@ServerEndpoint`·`@OnMessage`·`Session`)의 handler 타입이 + `ARE_REQUEST_HANDLER_TYPES`에 없다. + - 그래서 설정에 중첩된 JAX-RS resource나 `@ServerEndpoint`가 시스템 호출자를 부르면 r9에서는 잡혔고 r10에서는 + 잡히지 않는다. 같은 resource를 최상위 클래스로 쓰면 r10에서도 잡힌다(명령 1·2). + - 매뉴얼 07은 두 목록을 함께 늘리라고 하지만, 이 커밋이 만든 두 목록의 첫 내용부터 그 규칙을 따르지 않는다. +- **발생 조건·영향**: + - JAX-RS(Jersey 등)나 JSR-356 endpoint를 들인 파생 서비스가 "지금 실행" endpoint를 그 handler를 등록하는 설정 + 안에 중첩 클래스로 쓰고, 그 endpoint가 `@SystemCaller`를 부른다. + - 사용자 요청이 권한 검사 없는 `@SystemInvoked` 쓰기에 닿는다. 그 길을 막겠다는 규칙(`USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`)이 + 조용히 통과한다. + - 템플릿에는 JAX-RS·JSR-356 endpoint가 없고, 중첩 클래스로 쓰는 모양도 드물어 Minor다. 같은 방식으로 WebFlux + `WebFilter`·`WebHandler`(`org.springframework.web.server..`)도 빠진다(E1, 실행하지 않음). +- **테스트가 못 본 이유**: r10의 fixture는 좁은 목록에 든 타입(`RouterFunction`, `HandlerFunction`, `DataFetcher`)만 + 설정 안에 쓴다. 넓은 목록에만 있는 라이브러리를 설정에 중첩한 fixture가 없고, 두 목록이 같은 라이브러리를 덮는지 + 보는 테스트도 없다. +- **고치는 법**: + - (권장) `ARE_REQUEST_HANDLER_TYPES`에 넓은 목록이 이미 아는 라이브러리의 handler 타입을 더한다. JAX-RS: + `jakarta.ws.rs.Path`와 HTTP 메서드 annotation(`GET`·`POST`·`PUT`·`DELETE`·`PATCH`·`HEAD`·`OPTIONS`), + `jakarta.ws.rs.container..`. JSR-356: `jakarta.websocket.server.ServerEndpoint`, `jakarta.websocket.OnMessage`·`OnOpen`, + `jakarta.websocket.Session`, `jakarta.websocket.MessageHandler`. WebFlux: `org.springframework.web.server.WebFilter`·`WebHandler`·`ServerWebExchange`. + 그리고 두 목록이 같은 라이브러리를 덮는지 보는 테스트를 둔다. 넓은 목록의 라이브러리 뿌리마다 좁은 목록에 + 항목이 하나 이상 있어야 한다. 그래야 매뉴얼 07의 "함께 더한다"가 글로만 남지 않는다(부록 A10). + - (대안) 설정 자신은 지금처럼 좁은 목록으로, 설정에 중첩된 클래스는 넓은 목록에서 설정 타입(`*Configurer`, + `*Registry`, `*Registration`)만 빼고 판정한다. 목록에 없는 새 라이브러리에서 잡히는 쪽(fail closed)이지만, 빼는 + 목록이 하나 더 생긴다. + - RED: 명령 1의 탐침 fixture 둘(설정에 중첩된 `@Path` resource, `@ServerEndpoint`)을 + `ArchitectureViolationFixtureTest`의 위반 fixture로 옮긴다. `6e992970`에서는 위반 0건으로 실패하고, `45d2a478`에서는 + 통과한다(명령 2). +- **이번 커밋/이전부터**: 이번 커밋(회귀). +- **증거**: E2 — 명령 1(r10: 중첩 JAX-RS 0건, 중첩 `@ServerEndpoint` 0건, 최상위 JAX-RS 1건), 명령 2(r9: 셋 모두 1건). + WebFlux 부분은 E1. + +### RR7-01-02 · Minor · gRPC 서비스가 `IllegalArgumentException`을 원인으로 든 raw status를 던지면 `INTERNAL_ERROR`로 답하고 그 메시지를 ERROR로 남긴다 — 같은 status를 `onError`로 넘기면 `BAD_PARAMETER`·WARN이다 + +- **위치**: + - 코드: `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java:137` + (`status.getCause() instanceof IllegalArgumentException` — 던진 경우 원인은 status 예외다), `:153` + (`closeWithError`가 던진 예외를 status의 원인으로 둔다), `:156-180`(`logUnrecognised`가 `failureBehind`로 status 예외 + 뒤의 원인을 붙인다). + - 문서: `src/adapter/inbound/grpc/README.md:157-158`("`IllegalArgumentException`은 … WARN 한 줄 … 만 남긴다(메시지 + 없음)"), `:160-161`("raw status는 `onError`로 넘겼든 던졌든 …"), `src/shared-contract/README.md:94-98`("네 전송 + 모두 … 메시지는 입력값이 들 수 있어 남기지 않고 예외도 붙이지 않는다"). +- **무엇이 틀렸나**: + - `onError(Status.INVALID_ARGUMENT.withCause(iae).asRuntimeException())`는 `close(Status.fromThrowable(t))`가 된다. + status의 원인이 `IllegalArgumentException`이라 `BAD_PARAMETER`로 답하고 WARN 한 줄만 남긴다. + - 같은 예외를 던지면 `closeWithError`가 그 status 예외를 원인으로 둔다. `:137`은 원인 자리의 status 예외를 보고 + `IllegalArgumentException`이 아니라고 판정한다. `INTERNAL_ERROR`로 답한다. + - 이어서 r10의 `failureBehind`가 status 예외를 벗기고 그 뒤의 `IllegalArgumentException`을 ERROR 줄에 붙인다. 메시지 + (명령 6: `unknown recipient alice@example.com`)가 로그에 남는다. + - README는 이 전송에서 `IllegalArgumentException`이 메시지 없는 WARN 한 줄만 남는다고 하고, raw status는 넘기든 던지든 + 같게 다룬다고 한다. 둘 다 이 경로에서 사실이 아니다. +- **발생 조건·영향**: + - 입력 검증 실패를 `Status.INVALID_ARGUMENT.withCause(e).asRuntimeException()`로 던지는 gRPC 서비스(grpc-java의 흔한 + 모양). 클라이언트는 `INVALID_ARGUMENT` 대신 재시도할 수 없는 `INTERNAL`을 받는다. 같은 실패가 넘기는 방식에 따라 다른 + 코드가 된다. + - 서버 로그에 입력값이 든 메시지가 ERROR와 스택으로 남는다. RR6-01-05·06이 막으려던 것이다. + - grpc 어댑터는 기본 조립에 없고 이 모양을 쓰는 서비스에서만 생겨 Minor다. +- **테스트가 못 본 이유**: r10이 더한 테스트는 원인이 `IllegalStateException`인 raw status(`aThrownRawStatusWithACauseIsLoggedWithTheCauseAlone`)와 + 원인 없는 raw status만 던진다. 원인이 `IllegalArgumentException`인 raw status를 던진 경우와 넘긴 경우를 비교하는 테스트가 + 없다. +- **고치는 법**: `close`가 판정에 쓰는 원인을 `failureBehind(status.getCause())`로 한 번 구하고, carrier· + `IllegalArgumentException` 판정과 로그에 같은 값을 쓴다. 그러면 던진 경우도 `BAD_PARAMETER`·WARN이 된다. RED: 명령 6의 + 탐침(`r7probeARawStatusWithAnIllegalArgumentCauseIsAnsweredTheSameThrownOrPassed`)이 지금 `INTERNAL` ≠ + `INVALID_ARGUMENT`로 실패한다. 로그 줄이 WARN이고 예외가 붙지 않는다는 단언을 더한다. +- **이번 커밋/이전부터**: 이전부터. r9도 같은 답을 했고, 붙인 status 예외의 원인 사슬로 같은 메시지를 남겼다. r10이 RR6-01-05를 + 고치며 이 경로를 직접 다시 썼는데 이 경우를 놓쳤다. +- **증거**: E2 — 명령 6. r9의 로그 내용은 E1(그때 `logUnrecognised`가 붙인 것이 status 예외 자체였다). + +### RR7-03-01 · Minor · 학습 문서가 "섞인 파일은 부분 적용되지 않는다"고 적지만, 가이드가 요구하는 `.sql.conf`를 붙이면 부분 적용된다 + +- **위치**: + - `docs/study/postgresql-jpa-walkthrough.ko.md:1346-1348`(r10이 쓴 문장: "다른 문장과 섞인 파일은 Flyway가 기본값 + (`mixed=false`)에서 아무것도 실행하기 전에 거부한다. 부분 적용은 일어나지 않는다"). + - 같은 주장의 근거가 된 Javadoc: `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/migration/ConcurrentIndexMigrationInspector.java:16-19`. +- **무엇이 틀렸나**: + - Flyway의 `mixed=false` 거부는 `.sql.conf`가 트랜잭션 여부를 정하지 않은 파일에만 걸린다. + - 같은 문서 바로 위 문단, 가이드 "Concurrent index builds", 검사기 `validate`는 동시 인덱스 문장마다 + `executeInTransaction=false`를 적으라고 한다. + - 그 설정이 붙은 섞인 파일은 Flyway가 거부하지 않고 문장마다 트랜잭션 없이 돌린다. 앞 문장은 커밋되고, 동시 인덱스가 + 실패하면 무효 인덱스와 `success=false` 이력이 남는다(명령 8: 행 3001이 남음). + - 그래서 그 문장은 문서가 안내하는 모양에서 틀렸다. r10이 고친 옛 문장("그것들은 커밋되고 인덱스만 안 된다")이 오히려 + 이 모양에서는 맞았다. +- **발생 조건·영향**: 학습 문서를 읽고 "섞어도 Flyway가 막아 준다"고 믿은 개발자가 `.sql.conf`를 붙인 채 다른 문장과 동시 + 인덱스를 한 파일에 둔다. 검사기 `requireIsolatedStatement`가 그 파일을 거부하지만, 검사기는 서비스가 마이그레이션 테스트를 + 둘 때만 돈다(가이드 `:146-147` "nothing checks it at startup"). 그 밖에서는 부분 적용된 스키마와 실패 이력이 남는다. + 문서 오류라 Minor다. +- **테스트가 못 본 이유**: 문서 문장이다. `.sql.conf`가 있는 섞인 파일을 Flyway로 끝까지 돌린 테스트가 없다. 새 IT는 한 문장짜리 + 파일만 돌린다. +- **고치는 법**: 문장을 둘로 나눈다. "`.sql.conf` 없이 섞으면 Flyway가 실행 전에 거부한다. `executeInTransaction=false`를 + 붙이고 섞으면 Flyway가 문장마다 따로 커밋해 부분 적용된다. 그래서 동시 인덱스 문장은 혼자 둔다(`requireIsolatedStatement`)." + 검사기 Javadoc `:16-19`에도 "설정 파일이 없을 때"를 붙인다. 회귀를 막으려면 명령 8의 두 탐침을 IT에 옮긴다(`.sql.conf` + 없음 → 실행 전 거부, 있음 → 부분 적용을 사실로 고정). +- **이번 커밋/이전부터**: 이번 커밋(RR6-03-05를 고치며 쓴 문장). +- **증거**: E3 — 명령 8. + +### RR7-03-02 · Important · 실패한 동시 인덱스 마이그레이션의 복구를 "`DROP INDEX` 하나"라고 안내하지만, 남은 실패 이력이 다음 배포를 막는다 + +- **위치**: + - 안내(같은 문장 세 벌): `docs/jpa/migration-guide.md:147-149`, `ConcurrentIndexMigrationInspector.java:70-73` + (`requireIsolatedStatement` Javadoc), `docs/study/postgresql-jpa-walkthrough.ko.md:1369-1371`. + - 막는 규칙: `docs/jpa/migration-guide.md:37-48`("Validation fails closed and never repairs", repair는 승인된 관리자 + 작업으로만), `docs/runbooks/migration-failed.md:42-66`(실패 분류에 이 경우가 없다), `:95`("delete or rewrite Flyway + history to make validation green" 금지), `:107`(history repair 전 DB 소유자에게 올린다). +- **무엇이 틀렸나**: + - Flyway는 트랜잭션 밖에서 돈 마이그레이션이 실패하면 이력에 `success=false` 행을 남긴다(명령 8·9). + - 다음 배포의 validate는 그 행 때문에 실패한다: "Detected failed migration to version 2". 무효 인덱스를 지우고 원인 + 데이터를 고쳐도 같다(명령 9). + - 그래서 "마이그레이션이 다른 일을 하지 않았으면 `DROP INDEX` 하나로 복구된다"는 안내를 따르면 배포는 여전히 막힌다. + 실패 이력 행도 지워야 한다(`flyway repair` 또는 그 행 삭제). + - 그런데 같은 가이드는 repair를 승인된 관리자 작업으로만 두고, runbook은 이력 수정을 금지한 채 이 실패를 분류하지 않는다. + 문서 어디에도 이 경우의 실행 가능한 복구 절차가 없다. +- **발생 조건·영향**: + - 가이드대로 동시 인덱스 마이그레이션을 쓴 파생 서비스에서 빌드가 실패한다. 유일 인덱스의 중복 값, deadlock, + `statement_timeout`, 오래 걸려 운영자가 취소한 경우다. + - 운영자는 안내대로 `DROP INDEX`하고 다시 배포하지만 validate 실패로 기동이 또 멈춘다(dev·test는 앱 기동, staging·prod는 + 배포 도구). runbook에서는 이 실패를 찾을 수 없고, 금지 목록이 유일한 해결(실패 이력 행 제거)을 막는다. + - 데이터 손실은 없고 실패가 닫힌 쪽(기동 거부)이다. 그래도 운영자에게 효과 없는 조치를 시키는 문서라 매뉴얼 02장 3.2절의 + Important 정의에 든다. r10 전에는 Flyway 기본 잠금 때문에 동시 빌드가 실패까지 가지 못하고 멈췄다(취소하면 같은 상태). + r10이 빌드를 실제로 돌게 해서 이 경로가 흔해졌다. +- **테스트가 못 본 이유**: 새 IT는 성공하는 동시 빌드와 상한에 걸려 취소되는 경우만 본다. 실패한 동시 빌드 뒤의 재배포를 돌린 + 테스트가 없다. +- **고치는 법**: + - (권장) 세 문장을 "무효 인덱스를 `DROP INDEX`하고, 실패 이력 행을 지운 뒤(아래 SQL), 원인을 고쳐 다시 배포한다"로 고친다. + 이력 행 삭제는 `DELETE FROM WHERE version = '' AND NOT success` 한 줄로, 성공한 행과 checksum은 + 건드리지 않는다. runbook 「Classify the failure」에 "트랜잭션 밖 마이그레이션 실패(`success=false` 행)" 항목과 그 SQL을 + 더하고, 「Do not」의 이력 수정 금지에 이 예외를 적는다. 이 예외는 "repair하지 않는다"는 정책을 좁히므로 소유자 확인이 + 필요하다(08장 3절). + - (대안) `flyway repair`를 이 경우에 허용한다. repair는 실패 행 삭제 말고도 적용된 마이그레이션의 checksum·설명을 다시 + 맞추므로, 가이드 `:44-48`이 막으려는 checksum 불일치까지 지운다. 권하지 않는다. + - RED: 명령 9의 복구 탐침(`r7probeAFailedConcurrentBuildIsRecoveredByDroppingTheInvalidIndex`)을 IT에 옮기고, 문서가 + 정한 절차(`DROP INDEX` + 실패 행 삭제)를 그대로 실행하게 고친다. 지금 문서 절차(`DROP INDEX`만)로는 + `FlywayValidateException`으로 실패한다. +- **이번 커밋/이전부터**: 이전부터(가이드 문장은 `6d27356e`부터). r10이 바로 옆 문단을 고쳐 쓰고 동시 빌드를 실제로 돌게 했다. +- **증거**: E3 — 명령 8·9(실 PostgreSQL 16, Flyway 11.14.1, 정책 세션 잠금). + +## Declined to judge + +이번 리뷰가 판단하지 않은 것: + +- **`paths:`·`branches:` 필터가 있는 trigger**(04). r10이 "workflow가 언제 도는가"를 이벤트와 `types`로 정했지만 필터는 + 보지 않는다. 그래서 `pull_request: paths: [...]`인 workflow(`fileserver-pr.yml`, `build-logic.yml` 등)도 "모든 변경에 + 도는" workflow로 센다. 지금 단계 명령은 필터 없는 workflow에서만 돌아 거짓 통과는 없다. round6 04가 "어떤 필터가 충분한지는 + 저장소 정책"이라며 판단하지 않은 항목이고, 아직 결정이 없다. 총괄이 결정으로 닫을 것. +- **`new FluentConfiguration()`·`new ClassicConfiguration()`으로 만든 Flyway**(03). `JpaProductionArchitectureTest`는 + `Flyway.configure(...)` 호출만 거부한다. 다른 생성 경로는 Flyway 기본(트랜잭션) 잠금을 다시 갖는다. 문서는 "`Flyway.configure()`를 + 거부한다"고 정확히 적고, 그 경로를 쓰는 코드는 이 repo에 없다. +- **`docs/registries/error-codes.yaml`의 `IDEMPOTENCY_UNAVAILABLE` `log_level: WARN`**(02, pathspec 밖). 전송은 5xx + carrier를 ERROR로 남기고(`ServerFailureLog.java:71-76`), r10의 runbook도 ERROR라고 적는다. round6 02가 판단하지 않고 넘긴 + 항목이고 아직 처리 기록이 없다. +- **같은 owner token에 다른 operation id**(02). r10이 claim 순서를 바꿔, 이 조합은 재시도 가능 실패·lease 지난 claim에서 + `OwnerOperationConflict` 대신 넘겨받기가 된다. 아무것도 실행되지 않은 기록이라 넘겨받아도 안전하고, + `OwnerOperationConflict`에는 Javadoc 약속도 계약 케이스도 없다. 운영 호출자는 요청마다 새 attempt를 만든다. +- **설정이 `RequestMethod`·`@CrossOrigin`·`HttpServletRequest`를 쓰는 경우**(01). `ARE_REQUEST_HANDLER_TYPES`가 + `org.springframework.web.bind.annotation..`·`jakarta.servlet.http..`를 통째로 담아, 그런 설정이 시스템 호출자를 bean으로 + 등록하면 거짓 실패한다. 지금 트리에는 없다(명령 1에서 원래 228개 통과). +- **`trap '…; exit $rc' EXIT` 관용구, `kill $$`와 신호 trap**(04). 앞의 것은 "0으로 끝날 수 있음"으로 읽어 세지 않는다(거짓 + 실패, 재리뷰 README 16절이 받은 방향). 뒤의 것은 판독기가 모델링하지 않는 거짓 통과지만 일부러 만든 모양이다. +- **`ConcurrentIndexMigrationInspector`가 주석을 지우지 않는다**(03). 주석 안의 `CREATE INDEX CONCURRENTLY`도 동시 문장으로 + 센다. 거부 쪽이고 이전부터다. + +round6이 판단하지 않은 항목의 처리 기록이 없다. round6 문서 넷의 「Declined to judge」는 30건이다(01: 7, 02: 6, 03: 10, +04: 7). 재리뷰 README 17절에는 그 배정이나 결정이 없다. r10이 그중 03의 "중첩 블록 주석"만 함께 고쳤다. 매뉴얼 09장 5절 +종료 조건 2와 01장 1절 완료 기준은 총괄이 이 항목을 다음 묶음에 배정하거나 결정으로 닫으라고 한다. 이 리뷰는 그 항목들을 +다시 판정하지 않았다. 그중 이 리뷰가 지나가며 보고 아직 사실이 그대로인 것은 셋이다. 위의 trigger 필터와 레지스트리 +log level, 그리고 round6 04의 httpclient 문서 항목이다. `docs/httpclient/release-checklist.md:12`와 +`docs/httpclient/support-matrix.md:61,72,86`이 없는 lane `spring62CompatibilityTest`를 적는다. 실제 lane은 +`spring62ApiSurfaceScan`이다(`src/adapter/outbound/httpclient/build.gradle:187`). + +## 결론 + +결함 4건: Critical 0, Important 1, Minor 3. 회귀 1건(RR7-01-01). + +| ID | 심각도 | 이번 커밋 / 이전부터 | 증거 | 부록 패턴 | +| --- | --- | --- | --- | --- | +| RR7-01-01 | Minor | 이번 커밋(회귀) | E2 | A1(두 목록이 같은 전송을 다르게 덮는다), A12 | +| RR7-01-02 | Minor | 이전부터(r10이 같은 경로를 고치며 놓침) | E2 | A8 | +| RR7-03-01 | Minor | 이번 커밋 | E3 | A2, A12 | +| RR7-03-02 | Important | 이전부터(r10이 그 경로를 흔하게 만듦) | E3 | A2 | + +- round6 25건: 닫힘 24, 부분 1(RR6-03-05 → RR7-03-01). 두 Important(RR6-01-01, RR6-03-01)는 닫혔다. +- 02 멱등성·04 build-logic 영역에서는 새 결함을 찾지 못했다. 두 저장소·두 fake의 claim 순서와 시작 확인 조건이 서로 같고 계약 + 케이스가 넷 모두에 걸린다. 판독기는 이 repo workflow로 두 빌드 모두 통과하고 테스트 162개가 통과한다. +- 결정이 필요한 것: RR7-03-02의 복구 절차는 "이력을 고치지 않는다" 정책의 예외다. 선택지는 (a) 실패 행만 지우는 SQL을 + runbook에 예외로 둔다(권장, checksum은 건드리지 않음), (b) 이 경우 `flyway repair`를 허용한다. 승인자는 소유자다. +- 매뉴얼 09장 5절의 종료 조건 1(발견 0)이 아직 아니다. 위 4건과 round6·이번 Declined를 총괄이 다음 수정 묶음에 배정하거나 + 결정으로 닫아야 한다.