Files
clean-architecture-backend-…/docs/upgrade/2026-11-maturity-review.md
T
DongHyeonka 4d778c2293
pr / gradle (pull_request) Successful in 12m38s
pr / vulnerabilities (pull_request) Successful in 36s
pr / done (pull_request) Successful in 0s
Merge remote-tracking branch 'origin/main' into claude/t2a-backend-ci-451e3b
메시징 플랫폼 분리(PR #8)를 받는다. 충돌 둘: 옛 integration-main.yml은
이 브랜치가 지웠으므로 삭제를 둔다(메시징 측정 주석은 main.yml에 옮길
측정 수치가 없어 버린다). 업그레이드 안내는 메시징 절을 3.9(B-57~B-59)로
두고 CI 절을 3.10(B-60~B-66)으로 미룬다.
2026-11-08 22:20:58 +09:00

395 lines
119 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 업그레이드 안내 — 2026-11 성숙도 리뷰 수정
- 범위: `01a8a2a70..refactor/maturity-review-2026-11` (main → 이 브랜치)
- 커밋: `34565130` High·P1 19건 · `1400dc15` 남은 발견·매뉴얼·생성 명령 · `5786126c` 남은 항목과 합친 뒤 결함 ·
`7ef8d0b4` 재리뷰 기록 · `bbe944bd` 재리뷰 결함 · `ecc74b7d` 2차 재리뷰 기록·이 안내 · `1885bf8d` 2차 재리뷰 결함 ·
`339cf8fd` 3차 확인 리뷰 기록 · `f40c03c6` 3차 확인 리뷰 Minor · `c2e55510` 마지막 확인 리뷰 기록 ·
`2678955c` 테스트 코드 정적 분석(B-40) · `70fb80bf` 소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록, `failure-retention` 기동 검사, workflow `cd`) · B4 성능 lane 단언 상시화(2026-11-06, B-43) · `paths` 필터 trigger를 단계 실행으로 세지 않음(2026-11-06 소유자 결정, B-36) · r8-f1 전송 오류 처리(2026-11-07, B-45~B-48) · r9-g1 GraphQL 판정 순서와 인자 변환 단계(2026-11-07 소유자 결정, B-45·B-46) · 태그 push·`release` workflow는 `releaseCheck`에만 셈(2026-11-07 소유자 결정, B-36) · 실패한 동시 인덱스 drop의 복구 절차(2026-11-07, 재리뷰 RR8-03-01, 5절) · STOMP channel interceptor를 사용자 전송으로 셈(2026-11-07, B-16) · 멱등 저장소의 markFailed 재전송 인자와 renew 뒤 start(2026-11-07 소유자 결정, 5절) · 저장소 구조 정리(2026-11-07 소유자 결정, 3.6절 B-49~) — `docs(...)` 커밋은 문서만 바꾼다
- 근거 문서: `docs/reviews/2026-11-01-maturity-review/README.md` 13~16절, `docs/reviews/2026-11-03-rereview/README.md`
4·6·8~13절, 각 커밋의 `BREAKING CHANGE:` 꼬리말
- 아래 표의 각 줄은 위 범위의 diff와 코드로 확인했다. 확인하지 못한 것은 그 자리에 "확인 못 함"으로 적었고 9절에
모았다.
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 변경을 merge해 받는 파생 서비스(예: `tech-log-backend` — `origin`=서비스,
`upstream`=이 템플릿)의 개발자가 읽는다. 이 브랜치가 main에 합쳐진 뒤 `git merge upstream/main`을 하기 전에 본다.
## 2. 한눈에
### 반드시 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
|---|---|---|---|
| 1 | JWT 모드면 `APP_SECURITY_JWT_AUDIENCE`에 이 서비스의 client id를 쉼표로 넣는다 | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required` | JWT 모드(기본값) 전부 |
| 2 | dev·prod 환경 변수의 `APP_FLYWAY_ENABLED` 값을 확인한다 | `false`가 남아 있으면 이제 정말로 마이그레이션이 안 돈다 | persistence-jpa 선택 |
| 3 | prod 비밀값(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>`이 가리키는 변수)이 `fixture-`로 시작하지 않게 한다 | prod 기동 실패(exit 78) | prod 배포 전부 |
| 4 | 직접 만든 `StartupRule`·`RequiredProductionSecrets` bean을 `static @Bean`, 의존성 없이 바꾸고, 그 클래스에서 `@Value`·`@Autowired` 멤버와 `@ConfigurationProperties`를 뺀다 | 기동 실패 `startup rule or secret list '<이름>' created [...]` 또는 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one`(exit 78) | 자기 rule이 있는 서비스 |
| 5 | 직접 구현한 outbox·발행·알림·파일 서버 포트를 새 시그니처로, 직접 구현한 멱등성 store를 새 결과 값(B-41)으로 고친다(3.1절) | 컴파일 오류, 멱등성 공유 계약 실패 | 해당 포트를 구현·호출하는 서비스 |
| 6 | `dev.caskeleton.application.outbound.*` import를 `application.secret.*`·`application.objectstorage.content.CallBudget`으로 바꾼다 | 컴파일 오류 | 해당 타입을 쓰는 서비스 |
| 7 | 이벤트 id를 소문자 UUIDv7로 만들고 `IntegrationEventDraft`는 `IntegrationEventDrafts.draft(...)`로만 만든다 | 쓰기 요청이 `IllegalArgumentException`으로 실패, architectureTest 실패 | 통합 이벤트를 내는 서비스 |
| 8 | V21 배포 전에 `docs/runbooks/outbox-dead-letter.md` §8 Step 1 쿼리를 운영 DB에 돌린다 | 중복 순서 키가 있으면 기동 실패(exit 70, V20에 남음) | persistence-jpa + outbox |
| 9 | 이 브랜치의 이전 V21(또는 3차 수정 전 V20·V22·V11~V13·V8_1·V002·V003)을 적용한 개발 DB를 다시 만든다(4.2절) | Flyway checksum 불일치로 기동 실패(exit 70) | 이 브랜치를 미리 받아 돌린 개발 DB |
| 10 | 자기 SecurityFilterChain이 있으면 `DispatcherType.ERROR`를 허용한다 | 핸들러 밖 오류가 401로 바뀌어 나간다 | 자기 보안 체인을 둔 서비스 |
| 11 | 짝 프론트(또는 다른 클라이언트)에 7절 계약을 맞추게 한다 | 409를 재시도 불가로 읽거나, `null` 키를 기대하다 깨진다 | HTTP 클라이언트가 있는 서비스 |
| 12 | 자기 Flyway 마이그레이션 번호가 템플릿의 새 번호와 겹치지 않는지 본다(4절) | 같은 버전 두 개로 Flyway 실패 | 같은 stream에 자기 마이그레이션을 둔 서비스 |
| 13 | `.env`에 옛 `.env.example` 값을 복사해 두었다면 5.6절 키를 다시 맞춘다 | 새 기본값이 안 먹거나(JDBC batch), 기동 실패(알림 콜백 상한) | `.env`를 복사해 쓰는 서비스 |
| 14 | 자기 테스트 코드에 `./gradlew testQualityCheck`를 돌려 보고, 발견을 고치거나 이유를 단 Match로 뺀다(B-40) | `mainCheck`가 실패 | 테스트 코드가 있는 모든 서비스 |
| 15 | staging·prod 배포 마이그레이션 도구에 `flyway.postgresql.transactional.lock=false`(환경 변수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`)를 넣는다. 자기 Flyway stream은 `Flyway.configure()` 대신 `FlywaySchemaPolicy.configure()`로 만든다(5절 「Flyway 잠금」) | `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY` 마이그레이션에서 배포가 오류 없이 멈춘다. 자기 stream이 `Flyway.configure()`를 부르거나 설정 객체를 직접 만들면(`new FluentConfiguration()`·`new ClassicConfiguration()`, 재리뷰 round7 RR7-03-06부터) `:app-bootstrap:architectureTest` 실패 | persistence-jpa 선택 + 배포 도구로 마이그레이션하거나 자기 stream을 둔 서비스 |
| 16 | 자기 성능 lane(`performance()`)에서 `performance.assertions.enabled`를 `false`로 두는 `systemProperty` 줄을 지우고, 그 속성을 읽어 상한 단언을 건너뛰던 테스트는 항상 단언하게 고친다. 성능 lane의 `@Disabled`·assumption skip을 없앤다(B-43) | `performanceCheck`가 테스트 전에 실패(`its test JVM would get performance.assertions.enabled=false`)하거나 skip 때문에 실패(`forbids skipped tests`) | 자기 성능 lane이 있는 서비스 |
| 17 | 자기 `docs/registries/error-codes.yaml` 행에서 `log_level:` 줄을 지운다(B-44) | `mainCheck`의 `:app-bootstrap:documentContractTest`가 실패(`docs/registries/error-codes.yaml rows with a log_level; the code decides the level, not the registry`) | `error-codes.yaml`에 자기 행을 더한 서비스 |
### 되돌릴 수 없는 것
- 이 repo에는 down 마이그레이션이 없다(`U*__*.sql` 파일 0개). 되돌리려면 배포 전 백업을 복원한다(4.4절).
- notification V12는 중복 수신 거부(suppression) 행을 **지운다**. 알림을 쓰는 서비스는 배포 전 백업이 필수다.
## 3. 호환성을 깨는 변경
증상 칸의 exit 코드는 `StartupErrorCode`(`src/adapter/outbound/support/.../startup/StartupErrorCode.java`)를 따른다:
70 `MIGRATION_FAILED`, 71 `PROFILE_MISMATCH`, 72 `REQUIRED_ADAPTER_DISABLED`, 78 `STARTUP_VALIDATION_FAILED`.
### 3.1 Java API — 컴파일이 깨진다
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-01 | `OutboxStorePort`: `markFailed(OutboxLease, Instant)` → `markFailed(OutboxLease, Instant, String failureCode)`, `markDead(OutboxLease)` → `markDead(OutboxLease, String failureCode)`. 추상 메서드 추가: `markDeferred(OutboxLease, Instant, String)`, `releaseLease(OutboxLease, Instant)`, `longRetries(int, Instant)`(반환 `OutboxLongRetries`) | 직접 만든 store·fake가 `does not override abstract method` 컴파일 오류, 호출부 인자 수 오류 | 템플릿 `JpaOutboxStore`만 쓰면 할 일 없음. 직접 구현했다면 다섯 메서드를 구현한다. `failureCode`는 메시지가 아닌 코드다(`OutboxPublishAttempt.isFailureCode`) | `1400dc15`(markDeferred·releaseLease), `bbe944bd`(failureCode·longRetries) · `src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxStorePort.java` |
| B-02 | 발행 포트 반환형: `IntegrationEventPublishPort.publish(ValidatedIntegrationEvent)`가 `CompletionStage<OutboxPublishOutcome>` → `CompletionStage<OutboxPublishAttempt>`. `OutboxMessagePublishPort.publishForOutcome(ClaimedOutboxEvent)`가 `OutboxPublishOutcome` → `OutboxPublishAttempt`. 둘 다 default `longestAttempt()` 추가 | 구현체 반환형 불일치 컴파일 오류 | 결과를 `OutboxPublishAttempt.confirmed()`, `OutboxPublishAttempt.of(outcome)`, `OutboxPublishAttempt.failed(outcome, code)`로 감싼다 | `bbe944bd` · `.../messaging/event/IntegrationEventPublishPort.java`, `.../outbox/OutboxMessagePublishPort.java` |
| B-03 | enum 값 추가: `OutboxPublishOutcome.REJECTED_RETRYABLE`(`retryable()`=true), `OutboxRelayResult.Outcome.RELEASED`, `OutboxEventStatus.PARKED` | `default` 없는 switch 식이 "does not cover all possible input values" 컴파일 오류 | 새 값 분기를 더한다 | `34565130`(REJECTED_RETRYABLE), `1400dc15`(RELEASED), `bbe944bd`(PARKED) |
| B-04 | `OutboxRelayFailureReport`에 `failureCode` 필드 추가, `retryableFailure(...)`·`deadLetter(...)`에 `String failureCode` 인자 추가. `PublishPendingOutboxEventsCommand()` → `PublishPendingOutboxEventsCommand(BooleanSupplier stopRequested)` | 직접 생성하는 코드 컴파일 오류 | 보고서는 code를 넘긴다. command는 `PublishPendingOutboxEventsCommand.INSTANCE`를 쓰거나 supplier를 넘긴다 | `bbe944bd`(report), `1400dc15`(command) |
| B-05 | 알림: `ReconciliationJobStorePort.claimDue(int, Instant)` → `claimDue(int limit, Instant now, Duration lease)`. `ReconciliationJob`에 `long claimFence` 필드 추가. `reschedule`·`complete`는 fence가 다르면 아무것도 안 바꾼다 | 직접 구현한 store·job 생성 코드 컴파일 오류 | lease 인자를 받고, claim마다 fence를 올리고, 쓰기에 fence 조건을 건다. 계약은 `application-notification` testFixtures의 공유 계약 테스트로 확인 | `34565130`, `bbe944bd` · `src/application-notification/.../dispatch/ReconciliationJobStorePort.java` |
| B-06 | 파일 서버: `CleanupQueuePort.claimDue(Instant, int)` → `claimDue(Instant, int, Duration lease)`, `markAbandoned(CleanupItem, String reasonCode)` 추가. `CleanupItem`에 `UUID claimToken` 필드 추가. `FileQuotaPort.usedBytes(QuotaScope)` 추가. `UploadContentPort.releaseLease(UploadSession, RequestContext)` 삭제 | 직접 구현한 포트·`CleanupItem` 생성 코드 컴파일 오류 | 새 메서드 구현, `releaseLease` 호출 제거 | `1400dc15`(cleanup), `5786126c`(quota·upload) · `src/application-fileserver/.../cleanup/CleanupQueuePort.java`, `.../api/metadata/FileQuotaPort.java`, `.../upload/UploadContentPort.java` |
| B-07 | 패키지 이동: `dev.caskeleton.application.outbound.SecretSourcePort`·`SecretReference` → `dev.caskeleton.application.secret.*`. `dev.caskeleton.application.outbound.CallBudget` → `dev.caskeleton.application.objectstorage.content.CallBudget`(leaf `application-objectstorage`). `application.outbound` 패키지 삭제 | `package dev.caskeleton.application.outbound does not exist` | import를 바꾼다. `CallBudget`을 쓰는 leaf가 `application-objectstorage`에 의존해도 되는지 `modules.json` 간선을 확인 | `5786126c` · `src/application-core/.../secret/`, `src/application-objectstorage/.../content/CallBudget.java` |
| B-08 | `shared-contract`에서 `dev.caskeleton.shared.operation.Operation`·`OperationStatus` 삭제. 샘플 모듈로 옮겼다가 샘플과 함께 지웠다(B-49) | import 실패 | 쓰고 있었다면 자기 inbound adapter로 복사한다 | `1400dc15` · `src/shared-contract/src/main/java/dev/caskeleton/shared/operation/`(삭제) |
| B-09 | `SecuritySettings`(adapter:inbound:web): `audience`가 `String` → `List<String>`. `@ConfigurationProperties` 제거, `SecuritySettings.bind(Environment)`로 strict 바인딩. 생성자 `(String, String, List)` → `(String, List<String>, List<String>)`. `bootstrap.security.AuthenticationModeSettings` 삭제 | `audience()`를 문자열로 쓰는 코드, 직접 생성하는 테스트 컴파일 오류 | `List<String>`으로 바꾼다. 인증 모드는 `SecuritySettings.authMode()`에서 읽는다 | `34565130`(List), `5786126c`(strict·삭제) · `src/adapter/inbound/web/.../settings/SecuritySettings.java` |
| B-10 | adapter 공개 타입 삭제·이동: graphql `execution.GraphQlTimeoutPolicy`·`dataloader.GraphQlDataLoaderRequestRegistry` 삭제(`runtime.GraphQlDeadlineInstrumentation`·`GraphQlPerParentFetchInstrumentation` 추가). jpa `experimental.tenant.TenantId` 삭제 → `dev.caskeleton.application.tenant.TenantId`. persistence-notification의 엔티티는 `...platform.entity`, 저장소는 `...platform.repository`로 이동, `inbox` 하위 클래스는 `platform`으로 올라옴, `PreferenceJpaRepository`·`SuppressionJpaRepository` 삭제, `JpaNotificationSideEffect` → application-notification `dispatch.SuppressionSideEffect`. graphql `GraphQlClientPolicy.effectivePageSize(Integer, Integer)` 삭제 → `pagination.GraphQlConnectionPolicy.effectivePageSize`(상한 검사 포함, 재리뷰 RR-01-14). grpc(optional-platforms) `GrpcOperationLedger.release(identity)` → `boolean release(identity, GrpcClaimToken)`: 진행 중이고 그 token이 가진 claim만 지운다(RR-01-15) | import 실패, 호출부·직접 구현한 ledger 컴파일 오류. leaf `check`의 API surface 비교가 스냅샷과 달라 실패(자기 공개 타입을 더했다면 merge 충돌) | import를 바꾼다. 스냅샷 파일은 upstream 것을 받고 자기 추가분을 다시 승인한다 | `1400dc15`·`5786126c` · `docs/architecture/graphql-api-surface.txt`, `docs/architecture/jpa-api-surface.txt`(166→165), `docs/notification/api-surface-snapshot.txt`(362→364) |
| B-11 | 조립·지원 타입: `bootstrap.autoconfigure.operation.DurableOperationConfig` → `composition:durable-operation`의 `composition.operation.DurableOperationAutoConfiguration`. `bootstrap.settings.LoggingSettings` 삭제. `composition.outbox.OutboxLeaderElectionToken` 삭제. `TracingSamplingEnvironmentPostProcessor` → `TracingEnvironmentPostProcessor`, `StartupOrder.TRACING_SAMPLING` → `TRACING_PROPERTIES`. `StartupRuleRunner(Environment, List<StartupRule>)` → `StartupRuleRunner(Environment)`. `SecretSourceValidator(ConfigurableEnvironment, SecretSourcePort, List)` → `SecretSourceValidator(Supplier<List<RequiredProductionSecrets>>)` | 이 타입을 참조하는 코드·테스트 컴파일 오류 | 새 이름으로 바꾼다 | `1400dc15`, `34565130`, `bbe944bd` · `src/composition/durable-operation/`, `src/adapter/outbound/support/.../startup/` |
| B-39 | vendored messaging SPI `KafkaQuarantinePublisher`(`messaging-kafka`): `quarantine(ConsumerRecord, Throwable)` → `quarantine(ConsumerRecord, FailureCategory category, Throwable reason)`. 호출자가 격리 이유(읽을 수 없는 레코드 `DESERIALIZATION`, 시도 예산 소진은 실패의 category 또는 `POISON_MESSAGE`)를 넘기고, 구현은 그것을 `msg.failure-category` header로 쓴다 | 이 SPI를 직접 구현한 서비스는 `does not override abstract method` 컴파일 오류. 람다로 만든 것도 인자 수 오류 | 세 인자 메서드로 고친다. category를 header나 저장소에 그대로 남겨야 redrive가 두 경우를 가른다(템플릿 `KafkaDeadLetterQuarantine`, 테스트 `KafkaDeadLetterQuarantineTest`) | `bbe944bd`(리뷰 06-14), 3차 수정에서 목록에 추가(재리뷰 2차 RR-02-16) · `src/platforms/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java` |
| B-41 | enum 값 추가: `IdempotencyStartOutcome.LEASE_EXPIRED`, `IdempotencyRenewOutcome.LEASE_EXPIRED`(둘 다 `carriesOwner()`=false). 주인이 아직 기록을 가졌지만 processing lease가 끝나 시작·renew를 거절한다는 뜻이다. 전에는 PostgreSQL이 둘 다 `NOT_OWNER`, Redis가 renew는 `NOT_OWNER`·시작은 `STARTED`였다 | `default` 없는 switch 식이 "does not cover all possible input values" 컴파일 오류. 직접 구현한 store는 `IdempotencyStoreContract`의 새 시간 케이스(lease 지난 시작·renew)에서 실패 | 새 값 분기를 더한다. `LEASE_EXPIRED`를 `NOT_OWNER`처럼 "기록을 잃었다"로 읽지 않는다 — 실행 중이면 주인은 여전히 `complete`·`markFailed` 한다. store는 lease가 끝난 시작·renew에 이 값을 돌려준다 | r9(재리뷰 README 15 남음, RR5-01-02) · `src/application-core/.../idempotency/IdempotencyStartOutcome.java`, `IdempotencyRenewOutcome.java`, `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java` |
### 3.2 설정·기동 — 기동이 실패하거나 런타임 예외가 난다
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-12 | JWT 모드에서 `APP_SECURITY_JWT_AUDIENCE` 필수(빈 값 거부, `${...}`가 안 풀린 값도 없는 값으로 봄). 토큰 `aud`가 목록 중 하나를 담아야 통과. `resource_access` role은 audience에 적은 client 것만 읽는다(realm role은 그대로) | 기동 실패 `APP_SECURITY_JWT_AUDIENCE (app.security.audience) is required`(exit 코드 확인 못 함). `.env.example`이 `APP_SECURITY_JWT_AUDIENCE=`(빈 값)를 싣고 있다. 다른 client의 role에 기대던 권한이 사라짐 | client id를 쉼표로 넣는다. 다른 client role로 권한을 받던 사용자가 있는지 IdP에서 확인 | `34565130`(필수·role), `1400dc15`(안 풀린 `${...}`) · `src/adapter/inbound/web/.../auth/JwtDecoderConfig.java`, `.../JwtToAuthenticatedPrincipalConverter.java`, `.../settings/SecuritySettings.java` |
| B-13 | `app.security.*` strict 바인딩: 접두어 아래 오타 키, 또는 설정·placeholder 어디에도 쓰이지 않는 `APP_SECURITY_*` 환경 변수가 기동을 막는다 | 기동 실패(메시지는 `StrictSettingsBinder`가 키 이름을 담아 냄, 정확한 문구 확인 못 함) | 쓰지 않는 `APP_SECURITY_*` 변수를 지운다 | `5786126c` · `SecuritySettings.bind`, `src/adapter/outbound/support/.../StrictSettingsBinder.java` |
| B-14 | prod 프로필에서 `fixture-`로 시작하는 비밀값을 거부(레지스트리 `secret` 행, 모듈이 기여한 비밀, `secret://…/<VAR>` 참조 대상. `HOSTNAME`·앱 이름 같은 비밀 아닌 값은 보지 않는다 — RR2-04-01). Redis ACL fixture 파일 이름 변경: `infra/redis-sdk/acl/all-accounts.acl` → `lane-fixture-accounts.acl`(폴더는 지금 `compose/redis/acl/`, B-51) | prod 기동 실패, 요약 `prod secret/config-source contract is invalid`(exit 78). 옛 ACL 경로를 mount하던 compose는 파일 없음 | prod 값을 진짜 비밀로 바꾼다. compose의 ACL 경로를 새 이름으로. Redis SDK admin 계정(`RedisAccountContribution`)을 조립했다면 그 변수를 `static` `RequiredProductionSecrets` bean으로도 낸다(코드에 든 참조는 검사가 보지 않는다, RR3-04-03, `src/adapter/outbound/redis-sdk/README.md`) | `bbe944bd` · `src/app-bootstrap/.../runtime/SecretSourceValidator.java`, `docs/registries/secrets-classification.yaml` |
| B-15 | 기동 rule이 모든 singleton보다 먼저 돈다(`StartupRuleRunner`가 `BeanFactoryPostProcessor`). `StartupRule`과 `RequiredProductionSecrets` bean은 `static @Bean`이고 `Environment`, bean factory, static 무인자 `RequiredProductionSecrets`의 `ObjectProvider`만 받아야 한다. 두 타입의 클래스는 `@Value`·`@Autowired`·`@Inject`·`@Resource` 멤버, `@PostConstruct`·`@PreDestroy`, `@ConfigurationProperties`를 가질 수 없다(post-processor보다 먼저 만들어져 비어 있게 된다, RR2-04-03) | non-static `@Bean`이거나 다른 bean을 받으면 기동 실패 `startup rule or secret list '<이름>' created [<bean>] while creating it ... Declare the rule with a static @Bean method ...`, 위 멤버가 있으면 `'<이름>' (...) is a StartupRule or RequiredProductionSecrets ... but it needs one: [...]`(둘 다 exit 78, 둘 다 모든 프로필. runner가 rule과 비밀 목록을 프로필과 무관하게 먼저 만들어, 인터페이스 타입 `@Bean`이 돌려준 실제 클래스까지 본다, RR3-04-01) | rule 선언을 `static`으로, 인자를 위 셋으로 줄인다. 값은 `violations(Environment)`가 받는 `Environment`에서 읽는다. 다른 bean이 필요한 검사는 rule이 아니라 일반 bean으로 둔다 | `34565130`, `bbe944bd` · `src/adapter/outbound/support/.../startup/StartupRule.java`, `StartupRuleRunner.java` |
| B-16 | 권한 가드(새 `PermissionEnforcementGuard`): `@SystemInvoked` 유스케이스가 bean이면 기동 실패. `@RequiresPermission`을 단 bean에 적용되는 advisor가 없어도 기동 실패. ArchUnit `SYSTEM_INVOKED_USE_CASES_DECLARE_NO_PERMISSION`, `ONLY_SYSTEM_CALLERS_REACH_SYSTEM_INVOKED_USE_CASES`, `SYSTEM_CALLERS_ARE_SYSTEM_DRIVEN_INBOUND_ADAPTERS`, `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS`, `SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES` 추가, 새 표시 `@SystemCaller` | 기동 실패 `@SystemInvoked use cases are registered as beans ...` 또는 `beans declare @RequiresPermission but no advisor enforces it ...`(exit 72). `@SystemCaller`가 아닌 inbound adapter가 그 유스케이스를 부르거나, 사용자 전송(controller 등)이 `@SystemCaller` bean을 직접·중간 클래스를 거쳐·그 작업이 구현하는 프로젝트 인터페이스로 부르면 architectureTest 실패. `@SystemCaller` 클래스가 `Runnable`·`ApplicationRunner` 같은 프로젝트 밖 타입을 구현·상속해도 실패. 설정(`@Configuration`)은 웹 bean(`WebMvcConfigurer`·CORS 설정·controller bean)과 handler bean을 함께 등록해도 사용자 전송으로 세지 않지만, 요청 처리기 타입(함수형 route·data fetcher·interceptor)에 의존하면 사용자 전송으로 센다. 처리 코드를 설정에 직접 쓰든, 다른 클래스의 메서드를 참조해 등록만 하든 같다. 설정 안에 중첩된 클래스는 설정용 타입(configurer·registry·CORS 설정·`RequestMethod`)에만 의존할 때를 빼고 다른 클래스처럼 사용자 전송 타입으로 판정한다(중첩된 JAX-RS 자원·`@ServerEndpoint`도 잡힌다). STOMP inbound channel interceptor(`ChannelInterceptor`·`ExecutorChannelInterceptor`)도 사용자 전송 타입이자 요청 처리기 타입이다. 사용자 전송 패키지 밖에 둔 interceptor, 설정에 중첩한 interceptor(익명 클래스 포함), interceptor를 구현한 설정이 `@SystemCaller`에 닿거나, interceptor를 `@Bean`으로 내놓는 설정이 `@SystemCaller` bean도 만들면 실패한다(2026-11-07 전에는 STOMP 헤더 타입을 읽는 interceptor만 잡혔다). record·enum이 언어로 받는 상위 타입(`Record`·`Enum` 등)과 예외 클래스는 프로젝트 밖 상위 타입으로 세지 않는다 | 시스템만 부르는 쓰기 유스케이스는 composition에서 `new`로 만들어 스케줄러에 넘기거나, 메시지 handler·예약 작업이면 그 클래스에 `@SystemCaller`를 달고 생성자에서 `new`로 만든다. 예약 작업은 서비스 leaf의 `..adapter.inbound.scheduler..` 패키지에 둔다. 세 경로와 두는 곳은 매뉴얼 07장 「시스템이 부르는 쓰기」(handler 작업 순서는 09장 「소비」 4단계). "지금 실행" endpoint가 필요하면 `@RequiresPermission` 유스케이스를 따로 만든다. 작업을 task scheduler에 직접 등록하던 코드는 작업이 `Runnable`을 구현하는 대신 등록하는 곳에서 `job::run`을 넘긴다. route·data fetcher·interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. STOMP channel interceptor 등록도 같다. `@RequiresPermission`을 쓰면 web adapter(`MethodSecurityConfig`)가 조립돼 있어야 한다 | `1400dc15`, `bbe944bd`, r9 · `src/composition/service-runtime/.../authorization/PermissionEnforcementGuard.java`, `src/application-core/.../security/SystemInvoked.java`, `SystemCaller.java` |
| B-17 | `IntegrationEventDraft`: `eventId`·`causationId`는 소문자 UUIDv7만. ArchUnit `INTEGRATION_EVENT_DRAFTS_ARE_BUILT_BY_THE_SHARED_HELPER`: `new IntegrationEventDraft<>(...)` 금지, `IntegrationEventDrafts.draft(...)`만 | 이벤트를 만드는 쓰기 요청이 `IllegalArgumentException: eventId must be a canonical lower-case UUIDv7...`로 실패. architectureTest 실패 | event id를 UUIDv7로 만든다(예: sample `UuidOutboxEventIdFactory`가 `UuidCreator.getTimeOrderedEpochPlus1()`). draft는 헬퍼로 만든다. tenant가 없는 이벤트는 `IntegrationEventDrafts.SINGLE_TENANT_SCOPE`(`global`) | `1400dc15`, `bbe944bd` · `src/application-core/.../messaging/event/IntegrationEventDraft.java`, `IntegrationEventDrafts.java` |
| B-18 | `MessageHandler.schemaVersions()`(vendored `messaging-core-api`, default `{v1}`): 소비자 decode 목록을 handler 선언으로 만든다. 같은 (메시지 타입, 버전)에 다른 payload class를 선언하면 실패 | 컴파일은 된다. v1이 아닌 메시지는 `SCHEMA_VERSION_NOT_REGISTERED`로 거부. 발행 등록(`MessageContracts`)과 class가 다르면 기동 실패 `MESSAGING_CONTRACT_CONFLICT` | v2 이상을 읽는 handler는 `schemaVersions()`를 override한다. 소비 타입을 `MessageContracts`에 따로 등록하던 코드는 지운다 | `5786126c` · `src/platforms/messaging/messaging-core-api/.../delivery/MessageHandler.java`, `messaging-spring-boot-starter/.../MessageContracts.java` |
| B-19 | `APP_FLYWAY_ENABLED`가 모든 프로필에서 읽힌다. dev·prod 프로필 파일의 `spring.flyway.enabled: true`·`app.persistence.vendor` 고정값을 지우고 persistence-jpa `config/module-defaults`가 `${APP_FLYWAY_ENABLED:true}`를 싣는다 | dev·prod 환경에 `APP_FLYWAY_ENABLED=false`가 있으면 전에는 무시됐지만 이제 기동 때 마이그레이션이 안 돈다 | dev·prod 환경 값을 확인한다. 자기 `application-dev.yml`·`application-prod.yml`에 같은 고정값을 다시 넣지 않는다 | `5786126c` · `src/app-bootstrap/src/main/resources/application-{dev,prod}.yml`, `src/adapter/outbound/persistence-jpa/.../module-defaults/persistence-jpa.yml` |
| B-20 | JDBC batch 기본 켜짐: `APP_JPA_HIBERNATE_BATCH_SIZE` 0→50, `APP_JPA_HIBERNATE_ORDER_INSERTS`·`ORDER_UPDATES` false→true(registry `compatibility_impact: behavior-change`) | 컴파일·기동은 그대로. SQL이 묶여 나가고 insert·update 순서가 바뀐다. IDENTITY 키 엔티티는 batch가 조용히 꺼진다. `.env`에 옛 값(0·false)이 있으면 새 기본값이 안 먹는다 | 문장 순서에 기대는 코드가 있는지 본다. 끄려면 0·false를 명시 | `1400dc15` · `persistence-jpa.yml`, `docs/registries/env-keys.yaml` |
| B-21 | 트랜잭션 제한: `TransactionPort` 쓰기·읽기 트랜잭션 30초(`app.persistence-jpa.transaction.write-timeout`·`read-timeout`, env 키 아님) | 30초를 넘는 트랜잭션은 문장이 취소되고 `DB_QUERY_CANCELED`로 실패 | 긴 일괄 작업은 쪼갠다. 꼭 필요하면 프로필 yml에서 값을 올린다 | `1400dc15` · `persistence-jpa.yml` |
| B-22 | 격리 수준을 Hikari에서 고정: `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED`. 다른 값이면 거부. `TransactionPort`는 트랜잭션마다 격리 수준을 정하지 않는다 | 다른 격리 수준을 설정했다면 기동 실패(`HikariPoolConstraintValidator`) | 값을 지운다. 더 높은 격리가 필요한 곳은 따로 설계한다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/.../startup/HikariPoolConstraintValidator.java` |
| B-23 | H2 드라이버가 운영 jar에서 빠짐(persistence-jpa `runtimeOnly` → `testRuntimeOnly`). `bootRunH2` 작업만 따로 넣는다 | `APP_PERSISTENCE_VENDOR=h2`로 `bootRunH2` 밖에서 띄우면 드라이버가 없다(정확한 오류 확인 못 함) | 로컬은 Compose PostgreSQL 또는 `bootRunH2`를 쓴다 | `1400dc15` · `src/adapter/outbound/persistence-jpa/build.gradle` |
| B-24 | `APP_IDEMPOTENCY_PROCESSING_LEASE`는 2초(`IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER`)보다 길어야 한다. `APP_IDEMPOTENCY_TTL`(replay TTL)은 그 lease보다 짧으면 안 된다(재리뷰 RR-03-11). `APP_IDEMPOTENCY_FAILURE_RETENTION`은 replay TTL보다 짧으면 안 된다(RR3-03-02) | 2초 이하면, replay TTL < lease면, 또는 failure retention < replay TTL이면 기동 실패(exit 78). 마지막은 메시지에 `failure-retention`·`replay-ttl` 두 키와 값이 나온다 | lease를 2초보다 길게(기본 30s), replay TTL을 lease 이상으로(기본 24h), failure retention을 replay TTL 이상으로(기본 24h — 기본값끼리는 그대로 뜬다) | `5786126c`, `bbe944bd`, 3차 수정, `70fb80bf`(2026-11-04 소유자 결정) · `src/composition/idempotency/.../IdempotencySettings.java` |
| B-25 | 알림 콜백 본문 상한 65508 → 65251(바인딩에서 상한 검사) | `.env`에 옛 예제 값 `APP_NOTIFICATION_PLATFORM_CALLBACK_MAX_BODY_BYTES=65508`이 있으면 기동 실패 `max-body-bytes must be 1..65251` | 값을 지우거나 65251 이하로 | `5786126c` · `src/adapter/outbound/notification/.../autoconfigure/NotificationPlatformSettings.java` |
| B-26 | `config/module-defaults/`에 같은 이름 파일이 둘이거나, 두 파일이 같은 키를 실으면 기동 실패 | 기동 실패 `two capability modules ship config/module-defaults/<file>` 또는 `... both ship <key>`(exit 78) | 자기 leaf의 module-defaults 파일 이름·키가 템플릿 모듈과 겹치지 않게 한다 | `1400dc15` · `src/adapter/outbound/support/.../startup/ModuleDefaultsEnvironmentPostProcessor.java` |
| B-27 | **샘플 삭제(B-49)로 템플릿에서 사라졌다. 받을 변경이 없다.** (sample-portfolio를 남겨 둔 경우) 데모 계정은 활성 프로필이 모두 `local`·`test`·`demo` 중 하나일 때만. 프로필이 없어도 거부 | 기동 실패 `the sample's demo accounts authenticate only under the local, test or demo profile` | `SPRING_PROFILES_ACTIVE=demo`(이미지·jar), `local`(bootRun)로 띄우거나 sample 보안 설정을 지운다. 세 프로필 모두 sample `application.yml`이 object storage를 끈다(RR2-04-02) | `5786126c`, `bbe944bd` · `src/sample-portfolio/.../security/SampleDemoAccountsProductionGuard.java` |
### 3.3 HTTP wire — 응답이 달라진다
정본은 `docs/web/http-contract.md`다. 클라이언트는 `success`와 `error.code`로 가른다.
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-28 | 처리 중 409 `IDEMPOTENT_IN_FLIGHT`: `retryable` false→true, `Retry-After: 2` 추가. gRPC trailer `error-retryable`과 GraphQL extension `retryable`도 true | 409를 "재시도 금지"로 처리하던 클라이언트가 틀린다 | **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송하게 한다. 새 키 금지 | `34565130` · `src/shared-contract/.../error/OperationalError.java`, `docs/registries/error-codes.yaml` |
| B-29 | Envelope의 `null` 필드를 키째 생략: 성공은 `error` 키 없음, 실패는 `data` 키 없음, `meta.page`·`meta.correlationId`·`error.details`도 값이 없으면 키 없음. 빈 목록은 그대로 | `"error": null`·`"data": null`을 기대하던 클라이언트·계약 테스트가 깨진다 | `success`로 가르고 키 존재로 판단하지 않는다 | `34565130` · `src/adapter/inbound/web/.../envelope/EnvelopeWireFormatConfig.java` |
| B-30 | 새 코드 `IDEMPOTENCY_COMPLETION_UNKNOWN`(503, `TRANSIENT_DEPENDENCY`, retryable=true): 작업 실행 **뒤** complete 단계에서 멱등성 저장소가 응답하지 않음. 전에는 `IDEMPOTENCY_UNAVAILABLE` | 503을 "적용 안 됨"으로 읽던 클라이언트가 새 키로 다시 보내 중복이 생길 수 있다 | `error.code`로 가른다. 결과 불명이므로 같은 키로만 재전송. 실행 중 lease가 지난 기록은 두 저장소 모두 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다 — Redis 저장소는 전에 넘겨받아 작업을 다시 돌렸다(재리뷰 RR-01-11). 그 기록은 바꾸지 않아, 첫 시도가 늦게 끝나면 결과가 기록되고 그 뒤 재전송은 재생을 받는다(5절) | `bbe944bd`, 3차 수정, `70fb80bf`(2026-11-04 소유자 결정) · `src/application-core/.../idempotency/IdempotencyCompletionUnknownException.java`, `IdempotencyExecutor.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` |
| B-31 | 핸들러 밖 오류(`/error` 디스패치)를 `EnvelopeErrorController`가 실패 Envelope로 답한다. 전에는 Boot `/error` 맵이 `success:true`로 감싸져 요청 경로까지 실려 나갔다. 기본 JWT 체인에서 익명 400이 401로 바뀌지 않는다. 4xx·5xx 본문은 `success:true`로 감싸지 않는다. 보안 체인이 `DispatcherType.ERROR`를 허용한다 | 오류 본문 모양이 바뀐다. 자기 SecurityFilterChain이 ERROR 디스패치를 막으면 400이 401로 나간다 | 자기 체인에 `auth.dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 넣는다(템플릿 `SecurityConfig`와 같게) | `bbe944bd` · `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`, `.../auth/SecurityConfig.java` |
| B-32 | 새·바뀐 오류 코드: 비동기 요청 timeout 500 `INTERNAL_ERROR` → 503 `REQUEST_TIMEOUT`(retryable). `IDEMPOTENCY_KEY_INVALID` 400(`details.reason`=`MISSING`·`MALFORMED`, `IdempotencyKeyHeader.parse`를 쓰는 엔드포인트, sample은 `BAD_PARAMETER`에서 바뀜). web-advanced 예외 10종이 모두 500 `INTERNAL_ERROR`였다가 각자 코드(`ADMISSION_REFUSED` 503 등) | 코드로 분기하던 클라이언트가 새 코드를 모른다 | 클라이언트 분기표에 더한다. web-advanced 표는 `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | `1400dc15` · `src/adapter/inbound/web/.../error/WebTransportError.java`, `HttpStatusErrorCodes.java`, `src/adapter/inbound/web-advanced/.../error/WebAdvancedError.java` |
| B-33 | DB 실패 분류: 낙관적 잠금 충돌 500 → 409 `DB_OPTIMISTIC_CONFLICT`. 커밋 단계 연결 끊김(08xxx, 40003 등)을 재시도 가능으로 답하던 것 → 500 `DB_COMPLETION_UNKNOWN`(retryable=false) | 응답 status·code가 바뀐다 | 409는 다시 읽고 재시도, `DB_COMPLETION_UNKNOWN`은 업무 데이터로 결과를 확인 | `34565130`, `1400dc15` · `src/adapter/outbound/persistence-jpa/.../failure/PersistenceExceptionTranslator.java` |
| B-45 | 분산 락 timeout(`LockAcquisitionTimeoutException`): 500 `INTERNAL_ERROR`(retryable=false) → 409 `LOCK_ACQUISITION_TIMEOUT`(retryable=true, `Retry-After: 1`). GraphQL extension `code`·`retryable`, gRPC `ABORTED` + trailer `error-code`도 같은 코드. 예외가 `ApiErrorCarrier`가 되어 레지스트리가 약속한 값으로 답한다. 4xx라 "unhandled exception" ERROR 줄이 사라진다 | 500을 "재시도 금지"로 읽던 클라이언트가 이제 409를 받는다. 이 예외에 자기 `@ExceptionHandler`를 둔 서비스는 web에서 그쪽 응답이 그대로 나간다. GraphQL에서 이 예외를 `GraphQlExceptionResolver`에 등록한 매핑은 쓰이지 않는다: 실패 자신이 carrier라 그 코드가 등록 매핑보다 먼저다 | `Retry-After` 뒤 같은 요청을 다시 보내게 한다. 자기 처리기와 GraphQL 등록 매핑을 두었다면 지워도 된다 | r8-f1(2026-11-07, 재리뷰 RR7-01-04), r9-g1(2026-11-07, 재리뷰 RR8-01-01) · `src/application-core/.../lock/LockAcquisitionTimeoutException.java`, `src/adapter/inbound/web/.../observability/RetryAfterAdvisor.java` |
| B-46 | 다른 예외로 감싼 carrier: web·GraphQL도 gRPC처럼 원인 사슬의 첫 carrier 코드로 답한다(전에는 500 `INTERNAL_ERROR`). `IllegalArgumentException`이 carrier를 감쌌으면 `BAD_PARAMETER` 대신 그 carrier 코드다. STOMP ERROR 프레임의 `error-code`도 `IllegalArgumentException` 뒤의 carrier를 그 코드로 낸다. gRPC는 `Status.INVALID_ARGUMENT.withCause(iae)`처럼 `IllegalArgumentException`을 원인으로 든 raw status를 던져도 `onError`로 넘긴 것과 같이 `INVALID_ARGUMENT`·`BAD_PARAMETER`다(전에는 던지면 `INTERNAL`). 바뀌지 않는 것 둘(소유자 결정 2026-11-07): GraphQL에서 앱이 `GraphQlExceptionResolver`에 등록한 실패는 carrier를 원인으로 들어도 등록한 코드로 답한다(등록 매핑이 원인 사슬의 carrier보다 먼저, 실패 자신이 carrier면 그 코드가 먼저). 인자 변환 단계 — web `MethodArgumentTypeMismatchException`·`HttpMessageNotReadableException`, GraphQL `@Argument` binder — 는 원인에 carrier가 있어도 `BAD_PARAMETER`·`VALIDATION_FAILED`다. STOMP는 `@DestinationVariable`·`@Header`의 `ConversionFailedException`과 받은 메시지가 실린 `MessageConversionException`을 원인의 carrier와 상관없이 거부 WARN 한 줄로 남긴다 | 감싼 실패에 500·`INTERNAL`을 받던 클라이언트가 이제 그 carrier 코드(예: 503 `DB_UNAVAILABLE`)를 받는다. GraphQL 등록 매핑과 인자 변환 실패의 답은 그대로다 | 클라이언트 분기는 `error.code`로 한다(바꿀 것 없음). 감싼 실패를 일부러 500으로 보내려면 감싸지 말고 `IllegalStateException`을 던진다 | r8-f1(2026-11-07, 소유자 결정 2026-11-06, 재리뷰 RR7-01-05·RR7-01-03), r9-g1(2026-11-07, 재리뷰 RR8-01-01, README 19.4절 ①·④) · `src/shared-contract/.../error/ApiErrorCarrier.java` `firstIn`, 네 전송의 오류 처리기 |
| B-47 | `Retry-After`를 레지스트리 `retry_after_seconds`대로 붙인다. 새로 붙는 응답: 503 `DB_UNAVAILABLE` 5초, 409 `DB_SERIALIZATION_FAILURE`·`DB_DEADLOCK` 1초, 503 `DB_IDLE_IN_TX_TIMEOUT` 2초(나머지 `OUTBOX_PUBLISH_FAILED`·`JOB_*`는 HTTP로 나가지 않는 코드다). 전에는 web 표에서 빠져 헤더가 없었다. 표와 레지스트리를 `OperationalErrorRegistryContractTest`(document-contract, `mainCheck`)가 대조한다 | 이 응답에 `Retry-After`가 생긴다. 템플릿 `OperationalError` 행의 `retry_after_seconds`를 바꾼 서비스는 `RetryAfterAdvisor` 표도 같이 바꾸지 않으면 `mainCheck`가 실패한다(대조 대상은 `OperationalError` 코드뿐이다) | 헤더를 따르는 클라이언트는 그만큼 기다렸다 재시도한다. 자기 코드의 값은 그 코드가 `RetryAfterHint`로 말한다 | r8-f1(2026-11-07, 소유자 결정) · `src/adapter/inbound/web/.../observability/RetryAfterAdvisor.java`, `src/app-bootstrap/src/test/.../contract/OperationalErrorRegistryContractTest.java` |
| B-48 | GraphQL `@Argument` 값이 컨트롤러 파라미터 타입으로 바뀌지 않으면(Spring 인자 binder의 `BindException`) `INTERNAL_ERROR`(`INTERNAL`) 대신 `BAD_PARAMETER`(`REQUEST`, `BAD_REQUEST`)로 답한다. 로그는 ERROR + 예외(`rejected value [...]`가 실림) 대신 WARN 한 줄 `request refused as BAD_PARAMETER by org.springframework.validation.BindException (executionId=…)`이다 | 그 실패에 `INTERNAL_ERROR`를 받던 클라이언트가 `BAD_PARAMETER`를 받는다. ERROR 경보가 잘못된 인자에 울리지 않는다 | 클라이언트는 `extensions.code`로 가른다. `BindException`에 자기 `GraphQlExceptionResolver` 매핑을 둔 서비스는 그 매핑이 그대로 먼저다 | r8-f1(2026-11-07, 소유자 결정) · `src/adapter/inbound/graphql/.../error/GraphQlWireErrorMapper.java` |
### 3.4 빌드 게이트·아키텍처 규칙 — `ci`가 빨개진다
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-34 | 템플릿 패키지 규칙(ArchUnit): `FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES`, `TEMPLATE_PACKAGES_DO_NOT_DEPEND_ON_FEATURE_PACKAGES`. 템플릿 이름: application `usecase command query capability transaction security tenant observability secret messaging outbox idempotency operation lease lock cache realtime notification fileserver objectstorage`, domain `identifier stereotype` | 기능 패키지 이름이 이 목록과 겹치거나(예: `domain.lock`), 업무 코드를 템플릿 패키지(예: `application.usecase.*`)에 두고 기능 패키지를 import하면 `:app-bootstrap:architectureTest` 실패 | 기능 패키지 이름을 바꾸고, 업무 코드를 `dev.caskeleton.application.<feature>`로 옮긴다. 규칙 정본은 `src/application-core/CLAUDE.md` "Package ownership" | `5786126c`, r9 · `src/app-bootstrap/src/test/.../TemplatePackageOwnership.java`(표와 대조: `TemplatePackageOwnershipDocumentTest`) |
| B-35 | JPA 규칙: 양방향 연관은 한쪽에서만 매핑(`mappedBy`), notification·fileserver 저장소 엔티티는 그 leaf 안에서만, `@Version` 엔티티의 bulk update는 version을 올려야 함 | 위반 엔티티·쿼리가 있으면 architectureTest 실패 | 매핑·쿼리를 고친다 | `34565130`, `1400dc15`, `bbe944bd` · `src/app-bootstrap/src/architectureTest/.../JpaProductionArchitectureTest.java` |
| B-36 | 빌드 검사 강화: `modules.json`에 없는 `build.gradle`이 있으면 `verifyCleanArchitectureDependencies` 실패. `verifyStrictLaneStages --dry-run`은 모든 strict lane이 workflow가 실행하는 단계(`:ci` `:mainCheck` `:integrationCheck` `:performanceCheck` `:releaseCheck`)에 속해야 하고 `.github/workflows`를 읽는다. 명령의 빌드는 `working-directory`(단계·job·workflow `defaults`)에서 시작해 같은 `run:` 셸이 그 앞에서 실행한 `cd <상대 경로>`(`cd src && ./gradlew …`, `cd src; ./gradlew …`, 앞 줄의 `cd src`)를 따라간 뒤 `-p`를 붙인 디렉터리로 정하고(`70fb80bf`(2026-11-04 소유자 결정)), `workflow_dispatch`로만 시작하는 workflow의 명령은 세지 않으며, 축약한 `-x`도 Gradle처럼 맞춰 본다(RR2-04-04). 붙여 쓴 `-x<task>`·`-p<dir>`도 Gradle처럼 읽는다(RR3-04-02). `run:` 스크립트를 bash 문법으로 읽고(heredoc·여러 줄 문자열·함수 본문 안의 `cd`는 따라가지 않음), 세지 않는 명령은 이유를 셋으로 나눠 적는다(r10). (1) 실패해도 단계가 실패하지 않을 수 있음: `\|\| exit <0 아닌 값>` 밖의 `\|\|`(`\|\| true` 등), pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, `exit 0` 하는 `EXIT`·`ERR` trap 뒤. (2) 돌지 않을 수 있음: `\|\|` 뒤, 마지막이 아닌 `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec <명령>`·`set -n` 뒤, 조건부이거나 부른 함수 안의 `exit 0`·인자 없는 `exit`·값을 모르는 `exit`·`exec`·`set -n` 뒤, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment`·`types: [labeled]`인 `pull_request`·`workflow_run` 등; `push`·`pull_request`·`pull_request_target`·`merge_group`·`schedule`·`release`는 센다), change trigger가 모두 `paths`·`paths-ignore` 필터를 단 workflow(그 경로 밖 변경에는 돌지 않는다, 2026-11-06 소유자 결정), `releaseCheck` 밖의 단계에서는 태그 push(`branches` 없는 `tags`·`tags-ignore`)나 `release`로만 시작하는 workflow(2026-11-07 소유자 결정), 세는 job이 `uses: ./.github/workflows/<파일>`로 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job(자기 `if:`가 `always()`·`!cancelled()`면 센다). (3) 실패하면 단계도 실패하지만 검사가 읽지 않음: `\|\| exit 1`·`\|\| { …; exit 1; }`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 명령의 인자인 `gradlew`(`timeout 60 ./gradlew`), `bash`·`sh`가 아닌 `shell:`, `shell:` 없이 Windows일 수 있는 runner(Windows 라벨, `${{ matrix.os }}` 같은 식, `linux`·`macos` 라벨 없는 self-hosted)에서 도는 단계 — 기본 셸이 `pwsh`다(Linux·macOS runner의 기본은 `bash -e`, `container:` job은 `sh -e`이고 둘은 같게 읽는다). Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--version`·`-h`·`-?`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`)·값을 받지 않는 옵션에 붙인 값(`-m=yes`)도 세지 않는다. 판독기의 Gradle 옵션 표는 `GradleCommandLineTest`가 build-logic을 돌리는 Gradle의 `--help`와 대조하므로, Gradle을 올려 옵션이 늘면(9.2의 `--task-graph`) 그 테스트가 실패한다. 단계를 부르지만 세지 않은 명령은 다른 빌드로 읽힌 것까지 실패 메시지에 이유와 함께 적는다(r9). `verifyEnvKeys`: lane 계약 json의 `APP_` 밖 키는 `SPRING_`·`MANAGEMENT_`·`SERVER_`이거나 `secret://…/<VAR>`가 가리키는 변수여야 하고, 레지스트리 `property:` 행은 그 property가 설정 metadata에 있어야 읽히는 것으로 친다(`@ConditionalOnProperty`로만 읽는 스위치는 `META-INF/additional-spring-configuration-metadata.json`에 선언, RR2-04-05). SpotBugs 신뢰도 HIGH → MEDIUM | 등록 안 한 leaf, 단계에 안 걸린 자기 lane, 자기 코드의 MEDIUM 발견이 `ci`·`qualityCheck`를 막는다. `working-directory: src`도 `cd src`도 없이 `./gradlew`를 부르는 자기 workflow 단계는 실행으로 세지 않는다. 확실히 따라갈 수 없는 디렉터리 이동(`cd "$VAR"`, `cd -`, `cd ~`, 절대 경로, `pushd`, `if`/`for`/`case`·`{ }`·서브셸 안의 `cd`, `||`·`|`로 이은 `cd`, 다른 명령과 `&&`로 묶인 `cd` 다음 줄) 뒤의 명령도 세지 않고, 실패 메시지에 그 명령과 이유를 적는다. 단계를 `./gradlew ci \| tee log`(기본 셸), `./gradlew ci \|\| true`, `./gradlew ci \|\| exit 1`, `if ./gradlew ci; then` 같은 모양으로만 부르거나, 조건부 `exit 0` 뒤, `-v`·`--help`를 붙여, 요청형 trigger·`paths` 필터 trigger로만 시작하는 workflow·`releaseCheck`가 아닌 단계를 태그 push·`release`로만 시작하는 workflow·호출되지 않는 `workflow_call` workflow·조건부 job을 `needs`로 기다리는 job·`shell:` 없는 Windows runner에서만 부르는 자기 workflow도 실패한다 | leaf를 등록하거나 지운다. 자기 lane은 단계에 건다. 단계를 부르는 workflow 명령에 `working-directory`를 두거나 같은 셸에서 `cd <상대 경로>`로 옮긴 뒤 부른다. 단계 명령은 혼자 한 줄로 두고, 로그를 파이프로 남기려면 `shell: bash`나 앞 줄 `set -o pipefail`을 둔다. Windows runner에서는 `shell: bash`를 둔다. 단계는 매 push·pull request·schedule에 도는(`paths`·`paths-ignore` 필터 없는) workflow와 job에서(`releaseCheck`만 태그 push·`release` workflow에서), 재사용 workflow라면 그런 job이 조건 없이 부르게 한다. Gradle을 올려 `GradleCommandLineTest`가 실패하면 새 옵션을 값 옵션·플래그·작업 없이 끝나는 옵션 중 하나로 판독기 표에 넣는다. SpotBugs 발견은 고치거나 이유를 단 제외로 | `1400dc15`, `34565130`, `bbe944bd`, `5786126c`, `70fb80bf`(2026-11-04 소유자 결정), r9, r10(RR6-04-01~06), RR7-05-01(2026-11-06 소유자 결정), 태그·릴리스 workflow(2026-11-07 소유자 결정) · `src/build-logic/.../ModuleRegistry.java`, `.../strictlane/StrictLaneStagesPlugin.java`, `.../strictlane/WorkflowGradleInvocations.java`, `.../strictlane/ShellScript.java`, `.../strictlane/GradleCommandLineTest.java`(test), `.../quality/QualityConventionsPlugin.java`, `src/build.gradle` |
| B-37 | app-bootstrap 테스트 lane 분리: 저장소 파일을 읽는 테스트는 태그 `document-contract`(main 단계) 또는 `repository-contract`(`check`)여야 하고, 일반 `test` lane에는 `ca.repository.root`가 없다 | app-bootstrap에 둔 자기 테스트가 저장소 파일을 읽으면 `test`에서 실패 | 태그를 단다 | `1400dc15` · `src/app-bootstrap/build.gradle` |
| B-40 | 테스트 코드 정적 분석 `testQualityCheck`: SpotBugs·FindSecBugs를 main 밖 모든 source set(test, testFixtures, integrationTest, systemTest 등)에 돌린다. 테스트용 제외 목록은 `config/spotbugs/exclude-test.xml`(보안 범주·내부 상태 노출·생성자 예외·반환값 null 역참조·아키텍처 위반 fixture). 분석 classpath가 그 source set의 runtime classpath로 넓어졌고, 분석이 불완전하면(빠진 클래스) 실패한다. main 빌드는 `mainCheck`(`qualificationCheck`), optional 빌드는 `ci` | 자기 테스트 코드의 SpotBugs 발견(예: `CountDownLatch.await` 반환값 무시, 공유 변수 비원자 쓰기, 닫지 않은 `Statement`)이 main 단계를 막는다. 테스트 classpath에 없는 타입을 참조하면 `SpotBugs analysis incomplete` | 고치거나, 클래스·메서드로 좁힌 Match를 이유와 함께 `exclude-test.xml`에 더한다. 빠진 타입은 그 테스트 suite 의존성에 넣는다 | `2678955c` · `src/build-logic/.../quality/QualityConventionsPlugin.java`, `src/config/spotbugs/exclude-test.xml`, `src/build.gradle` |
| B-42 | shared-contract 패키지 규칙 `SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`가 실제로 검사한다. 대상은 `dev.caskeleton.shared..`뿐이고, 허용은 목록의 패키지(`concurrency digest error metrics observability ratelimit request response retry runtime security tracing`)와 그 아래, 뿌리 패키지에는 `package-info`만이다. 전에는 뿌리를 허용 목록에 넣고 접두어로 비교해서 모듈 안은 아무것도 잡지 못했고, 다른 leaf의 `..shared..` 패키지를 잡았다 | `dev.caskeleton.shared`에 목록에 없는 패키지나 뿌리 클래스를 둔 파생 서비스는 architectureTest 실패. 다른 leaf의 `shared` 패키지는 더는 걸리지 않는다 | 업무 개념이면 그것을 소유하는 모듈로 옮긴다. 운영 계약이면 `ForbiddenApiArchitectureTest.SHARED_CONTRACT_PACKAGES`와 shared-contract CLAUDE.md 「Responsibility」에 함께 더한다 | r10 · `src/app-bootstrap/src/architectureTest/.../ForbiddenApiArchitectureTest.java`, `SharedContractPackageRuleTest.java` |
| B-43 | 성능 lane 단언 상시화: `performance()` lane은 convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣는다. 빌드가 `-P`·`GRADLE_OPTS`(`-Dorg.gradle.project.…`)로 `true` 아닌 값을 주거나, lane `systemProperty`·`jvmArgs`(`-D…`)·task 설정이 테스트 JVM 값을 `true` 아닌 값으로 덮으면 테스트 전에 실패한다. 성능 lane은 `rejectSkipped` 없이도 skip된 테스트가 있으면 실패한다. httpclient·Mongo leaf의 속성 선언과 `integration-main.yml` `performance-check`·`release.yml` `httpclient-release-gate`의 `GRADLE_OPTS` 줄을 지웠다. 측정만 하는 모드는 만들지 않았다(JMH가 그 용도) | `performanceCheck`·`:<leaf>:performanceTestLaneCheck`가 `is a performance lane, and this build sets performance.assertions.enabled=false`, `its test JVM would get performance.assertions.enabled=false`, `forbids skipped tests … a skipped test is a bound nobody measured` 중 하나로 실패 | `-Pperformance.assertions.enabled=false`를 지운다. 자기 lane의 그 `systemProperty`·`jvmArgs` 줄을 지우고, 그 속성을 읽던 테스트는 항상 단언하게 고친다. 성능 lane의 skip은 없애거나 그 테스트를 다른 lane으로 옮긴다. `GRADLE_OPTS=-Dorg.gradle.project.performance.assertions.enabled=true`·`-P…=true`는 받아 주므로 그대로 둬도 된다 | B4(2026-11-06) · `src/build-logic/.../strictlane/StrictTestLanePlugin.java`, `.../strictlane/StrictTestLaneConventionTest.java`(test), `docs/testing/TESTING_STRATEGY.md` 6절 |
| B-44 | `docs/registries/error-codes.yaml`에서 `log_level` 칸을 지웠다. 행에 `log_level`이 있으면 `OperationalErrorRegistryContractTest.noRegistryRowCarriesALogLevel`(태그 `document-contract`, `mainCheck`)이 실패한다. 칸을 읽는 코드는 없었고 값 대부분이 실제 로그 레벨과 달랐다. 레벨은 실패 종류·경로가 정한다(`ServerFailureLog`, 보안 필터 `AuthErrorResponseWriter`) | 자기 행에 `log_level`이 남은 서비스는 `mainCheck` 실패(`… rows with a log_level; the code decides the level, not the registry`와 그 행의 code 목록) | 자기 행에서 `log_level:` 줄을 지운다. 레벨을 바꾸려면 그 실패를 로그로 남기는 코드를 고친다. 자기 설계서가 "행마다 `log_level`을 채운다"고 적었으면 그 문장도 지운다 | 설계 메모 2026-11-06 7절 결정 1·1-b · `docs/registries/error-codes.yaml` 머리말, `src/app-bootstrap/src/test/.../contract/OperationalErrorRegistryContractTest.java` |
### 3.5 모듈 registry·새 leaf
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-38 | 새 leaf: `adapter-inbound-messaging`(`:adapter:inbound:messaging`, 이벤트 소비+inbox, 기본 조립에 없음), `composition-durable-operation`(`:composition:durable-operation`, `/operations`). 새 간선: `application-objectstorage`·`adapter-outbound-persistence-mongo`·`adapter-outbound-identifier`·`adapter-outbound-redis-sdk` → `shared-contract`, `adapter-inbound-web` → `adapter-outbound-support`, `sample-portfolio` → `adapter-outbound-support`, `app-bootstrap` → 두 새 leaf. 지운 간선: `composition-fileserver-platform` → `adapter-outbound-identifier`. `app-bootstrap/build.gradle`에 `runtimeOnly project(':composition:durable-operation')` 추가 | 자기 leaf를 더한 서비스는 `modules.json`·`app-bootstrap/build.gradle`에서 merge 충돌. 충돌을 풀다 durable-operation 줄을 빠뜨리면 `/operations` 조립이 없다(`DurableOperationConfig`가 app-bootstrap에서 빠졌기 때문) | 두 파일을 손으로 합친다. 합친 뒤 `architectureCheck`로 간선을 확인 | `1400dc15`, `5786126c` · `src/config/architecture/modules.json`, `src/app-bootstrap/build.gradle` |
### 3.6 저장소 배치 — 폴더·파일이 지워지거나 옮겨졌다
소유자 결정(2026-11-07, design-docs `repo-structure/README.md` 3.1절)으로 저장소 배치를 정리했다. 파생 서비스가
고치지 않은 파일이면 병합이 그대로 지우거나 옮긴다. 고친 파일이면 "수정 대 삭제"나 이름 바뀜 충돌이 난다.
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-49 | 샘플 모듈 삭제: `src/sample-portfolio`, `src/Dockerfile.sample`, registry `sample-portfolio` 행, 루트 `build.gradle`의 샘플 태스크·단계(`sampleWebContractCheck`, `:sample-portfolio:*` 의존, strict lane 단계 `:sample-portfolio:check`), `ci-quality-gates.yml`의 `sample-portfolio` job, `SampleRuntimeDefaultsContractTest`, spotbugs 제외의 샘플 클래스. 샘플에만 있던 검사(OpenAPI 스냅숏 `openapiCheckSnapshot`, Date 헤더, 가상 스레드 MDC 전파)도 함께 없어졌다 | 샘플을 고쳐 쓰던 서비스: 병합 때 "수정 대 삭제" 충돌. 샘플을 이미 지운 서비스: 충돌 없음 | 샘플을 이미 지웠으면 할 일 없음. 고쳐 쓰고 있으면 자기 leaf로 옮기고 registry 행·빌드 줄을 자기 것으로 둔다. 위 검사가 필요하면 자기 기능 leaf에 둔다 | `ab5982e9` |
| B-50 | `infra/`에서 15개 삭제. 쓰는 곳이 없던 12개(`infra/httpclient/**`, `infra/jpa/postgres/README.md`, `infra/jpa/toxiproxy/`, `infra/messaging/{kafka,postgres,toxiproxy,tls}/`, `infra/notification/toxiproxy/`)와 운영 인프라 셋(`infra/fileserver/nginx/nginx.conf`, `infra/fileserver/kubernetes/pvc-certification-job.yaml`, `infra/jpa/roles/runtime-roles.sql`). `release.yml`의 `fileserver-pvc-certification` job도 지웠고, fileserver 지원 표에서 "Kubernetes ReadWriteOnce PVC — Limited" 주장을 「주장하지 않음」으로 옮겼다 | 그 파일을 배포에 쓰던 서비스: 병합이 파일을 지운다. 고쳐 쓰던 서비스: "수정 대 삭제" 충돌 | 그 파일은 자기 인프라 repo로 옮긴다. 지켜야 할 조건은 `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」, `docs/fileserver/storage-certification.md`, `docs/jpa/security.md` 「역할과 권한」·「서버 설정」에 있다 | `a025f244` |
| B-51 | compose 정리. 루트 `docker-compose.yml`·`docker-compose.local.yml`·`docker-compose.infra.yml`을 개발 환경 `compose.yaml` 하나로 합쳤다(app은 `local` 런타임, 뒷단 서비스는 capability profile `jpa`·`redis`·`kafka`·`mongo`·`objectstorage`·`auth`·`mail`). 보조 파일은 `compose/`(keycloak realm·entrypoint, minio init, Redis ACL, mailpit 인증서 폴더). 테스트 lane fixture는 그 lane을 가진 leaf로 옮겼다: `docker-compose.dev.yml`·`docker-compose.prod-smoke.yml`·`docker-compose.tls.yml`·fileserver overlay·smoke 스크립트·스키마 적용 스크립트·lane 계약 JSON(`src/config/runtime/compose-profile-contracts.json`) → `src/app-bootstrap/compose-lanes/`, Redis topology compose → `src/adapter/outbound/redis-sdk/compose/`, NFS compose → `src/adapter/outbound/fileserver/compose/nfs/`. `infra/`는 없어졌다. lane 계약의 `composeProfile`(문자열)은 `composeProfiles`(목록)로 바뀌었고 `appMemoryLimit`이 생겼다. smoke는 lane 중 컨테이너가 재시작하거나 메모리로 죽으면 실패한다. `scripts/bootstrap-local.sh`는 인자를 받지 않는다 | `docker compose -f docker-compose.yml -f docker-compose.local.yml …`을 쓰던 스크립트·문서가 "no such file"로 실패. 옛 compose 파일에 서비스를 더했으면 수정 대 삭제 충돌. lane 계약을 고쳐 쓰던 서비스는 `composeProfile` 키를 smoke 스크립트가 읽지 않는다 | 명령을 `docker compose …`(루트 `compose.yaml`)와 profile로 바꾼다. 더한 서비스는 `compose.yaml`에 capability profile을 달아 옮기고, lane 전용이면 `src/app-bootstrap/compose-lanes/lane-services.yaml`에 둔다. 경로를 적은 workflow·문서를 위 새 경로로 고친다 | `50cd7154` |
| B-52 | `src/` 배치 정리. 들여온 플랫폼 넷을 `src/platforms/` 아래로 옮겼다: `src/messaging` → `src/platforms/messaging`, `src/grpc` → `src/platforms/grpc`, `src/grpc-advanced` → `src/platforms/grpc-advanced`, `src/optional-platforms` → `src/platforms/optional-build`(빌드 이름 `optional-platforms`는 그대로). registry `source_path`만 바뀌고 Gradle 경로(`:messaging:*`, `:grpc:*`)는 그대로다. optional 빌드는 `./gradlew -p platforms/optional-build …`로 부른다. `src/config/`에서 기능 하나가 주인인 데이터를 그 leaf의 `release/`로 옮겼다: `config/jpa/*` → `adapter/outbound/persistence-jpa/release/`, `config/messaging/**` → `adapter/outbound/messaging/release/`, `config/mongodb/release-contracts.json` → `adapter/outbound/persistence-mongo/release/` | `-p optional-platforms`를 부르는 workflow·스크립트가 "Project directory … does not exist"로 실패. 옮긴 폴더를 고쳐 쓰던 서비스는 이름 바뀜 충돌(Git이 이동으로 알아보면 자동 병합). `rootProject.file('config/jpa/…')`처럼 옛 경로를 읽던 자기 빌드 줄은 파일 없음 | workflow·스크립트의 `-p`와 경로를 새 위치로 고친다. 자기 leaf를 `src/messaging` 아래에 더했다면 `src/platforms/messaging` 아래로 옮기고 registry `source_path`를 고친다 | `8d69e599` |
| B-53 | 새 PR 검사 `python3 scripts/check-repo-layout.py`(`ci-quality-gates.yml`): 저장소 루트와 `src/` 최상위의 추적 항목이 허용 목록 안에 있어야 하고, registry `source_path`가 허용된 `src/` 폴더 아래여야 한다 | 자기 최상위 폴더(예: `infra/`, `src/<서비스 전용 폴더>`)를 둔 서비스는 PR 게이트가 실패한다 | 그 폴더가 정말 필요하면 스크립트의 `ROOT_ALLOWED`·`SRC_ALLOWED`와 자기 `CLAUDE.md` 지도에 같은 변경으로 더한다. 아니면 그 내용을 주인 leaf나 `docs/`로 옮긴다 | 커밋 「최상위 폴더 허용 목록 검사를 더한다」 |
### 3.7 의존성 버전 — 취약점 때문에 올렸다
이 절은 위 머리의 범위보다 뒤에 main에 들어간다. 범위: `5ab1b418..claude/v1-vuln-fix-e089b9`(2026-11-07, 총괄이 맡긴
의존성 취약점 수정). 이 안내가 이미 main에 합쳐졌으므로 위 머리는 고치지 않고 이 절에만 적는다.
PR 단계 trivy 검사(`dependency-vulnerability.yml`의 HIGH·CRITICAL 단계)가 막던 37건을 버전을 올려 고쳤다.
파생 서비스는 merge 때 lockfile 충돌을 보고, 자기 leaf도 같은 버전을 받는다.
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-54 | 버전 변경. ① `springBoot` 4.0.8 → 4.0.9(Tomcat 11.0.24 → 11.0.27, Jackson 2.21.5 → 2.21.7, Jackson 3 3.1.5 → 3.1.7, Spring Framework 7.0.10 등 Boot가 고른 패치). ② `grpc` 1.68.1 → 1.75.0, `protobufGrpc` 3.25.5 → 3.25.8(grpc-contract의 protoc 포함). ③ `jackson3`(build-logic만 씀) 3.0.2 → 3.1.7. ④ BOM 속성 override 둘(build-logic `JavaConventionsPlugin`): httpcore5 5.3.6 → 5.4.3, httpclient5 5.5.2 → 5.6.3. ⑤ 새 카탈로그 묶음 `pinned-*`: 어떤 leaf도 선언하지 않는데 upstream이 낡은 버전을 가져오는 라이브러리를 모든 leaf의 모든 구성(Checkstyle·Error Prone 구성 포함)에서 고정한다 — guava 33.7.2-jre, plexus-utils 3.6.1, lz4-java 1.11.4, snappy-java 1.1.10.9. ⑥ lockfile 5개에서 지금 빌드에 없는 구성(`redisPolicyContractTest`, `edgeRateLimitContractTest`, objectstorage의 MinIO lane 두 개, persistence-jpa·persistence-mongo의 `testkit`)의 옛 줄을 지웠다. ⑦ persistence-jpa는 Querydsl을 querydsl-core로만 컴파일한다(전에는 `com.querydsl:querydsl-jpa:5.1.0:jakarta`). 그 좌표는 HIGH CVE-2024-49203에 고친 버전이 없다 | merge 때 `gradle.lockfile` 충돌. 자기 leaf lockfile을 다시 쓰지 않으면 `verifyDependencyLocks` 실패. httpcore5 5.4.3은 들어오는 HTTP/1 메시지(HTTP client가 받는 응답)에 줄 길이 8192, 헤더 100개 상한을 기본으로 건다. 넘는 응답은 거절된다. 자기 의존성이 33.7.2보다 새 guava를 요구해도 `pinned-guava`가 33.7.2로 내린다 | merge 뒤 `./gradlew resolveAndLockAll --write-locks`와 `./gradlew -p platforms/optional-build resolveAndLockAll --write-locks`. 자기 lockfile에 지운 source set의 줄이 남았으면 그 lockfile을 지우고 같은 명령으로 새로 만든다(`--write-locks`는 해석한 구성만 다시 쓴다). 더 새 guava가 필요하면 그 leaf에서 guava를 버전과 함께 직접 선언한다(직접 선언이 고정을 이긴다). 응답 헤더가 큰 외부 API를 부르면 그 호출을 시험한다. Querydsl을 켜서 querydsl-jpa를 직접 더한 서비스는 그 좌표에 고친 버전이 없으니 OpenFeign 포크(`io.github.openfeign.querydsl:querydsl-jpa` 6.10.1 이상)로 옮기거나 자기 무시 항목에 이유와 만료일을 적는다 | 커밋 「lockfile에서 지금 빌드에 없는 구성의 옛 줄을 지운다」~「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」, `src/gradle/libs.versions.toml` 「Pinned」 |
### 3.8 gRPC 플랫폼 — 별도 repo `grpc-library`로 옮겼다
이 절도 위 머리의 범위보다 뒤에 main에 들어간다. 범위: `22df3525..claude/x2-grpc-library-43dd09`(2026-11-08, 소유자
결정 2026-11-07 「프로젝트 계층이 아닌 라이브러리는 별도 repo로」, design-docs `repo-structure/05-library-repos.md`).
템플릿 안에는 gRPC 플랫폼을 쓰는 곳이 없었다(`adapter:inbound:grpc`는 `io.grpc`를 직접 쓴다). 그래서 템플릿은 이
라이브러리를 받지 않고 지우기만 한다. 코드와 이력은 https://git.learn.hyeonworks.com/donghyeon.kang/grpc-library 에
있다.
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-55 | 삭제: `src/platforms/grpc`, `src/platforms/grpc-advanced`, `src/platforms/optional-build`(두 번째 빌드 `optional-platforms` 전체), registry의 `"build": "optional-grpc"` 9행, workflow job `ci-quality-gates.yml` `optional-platforms`·`grpc-proto-buf`(그리고 `release-gate`의 두 `needs`), `integration-main.yml`의 optional 성능 단계와 job `grpc-optional-platform-integration`, `release.yml` job `grpc-stable-release-gate`(그리고 이미지 job의 `needs` 한 줄), 살아 있는 문서 `docs/compatibility/`(폴더째), `docs/runbooks/grpc-platform-operations.md`·`grpc-advanced-capabilities.md`. 새 자리는 grpc-library repo이고 같은 이름의 파일이 이력째 있다. 기록(`docs/adr/ADR-GRPC-*` 7개, `docs/design/2026-08-30-grpc-platform-adaptation-design.md`)은 본문을 두고 머리 블록 「현재 정본」만 그 repo를 가리키게 했다. 사본이 그 repo에도 있다. 그 repo에서 Maven group과 Java 패키지는 `dev.cakit.grpc`, proto 패키지는 `cakit.grpc.common.v1`이다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기와 겹치지 않게 다른 이름) | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌이 난다. `project(':grpc:…')`·`project(':grpc-advanced:…')`나 `-p platforms/optional-build`를 쓴 서비스는 빌드가 실패한다 | 쓰지 않았으면 삭제를 그대로 받는다. 썼으면 grpc-library 첫 버전(`1.0.0`, 소유자가 태그를 단 뒤)을 좌표 `dev.cakit.grpc:<모듈>:1.0.0`으로 받고(저장소 선언은 그 repo README 「받는 법」), import를 `dev.caskeleton.grpc` → `dev.cakit.grpc`로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절, `docs/work/reference/related-repos.md` |
| B-56 | 빌드 규칙·카탈로그: build-logic의 `ca.grpc-platform-module`·`ca.optional-architecture-registry` 플러그인과 `MainBuild`(두 번째 빌드에서 주 빌드를 찾던 것)를 지웠다. 도구 설정·테스트 이미지 목록·registry는 Gradle 루트(`src/`)에서만 찾는다. 카탈로그에서 `protobufPlugin`·`protobuf-java-grpc`·`protoc`·plugin `protobuf`를, SpotBugs 제외에서 gRPC 플랫폼 클래스 줄을 지웠다 | 서비스 leaf가 `ca.grpc-platform-module`이나 `libs.protoc`·`libs.protobuf.java.grpc`·`libs.plugins.protobuf`를 쓰면 빌드가 실패한다. `src/` 밖 두 번째 빌드에서 이 build-logic을 쓰던 서비스는 도구 설정을 못 찾는다 | 그 leaf `build.gradle`에서 `io.grpc:grpc-bom` import와 protobuf 플러그인 버전을 직접 적거나, 지운 카탈로그 항목을 서비스 카탈로그에 다시 더한다 | 같은 설계 13.1절 2단계 |
### 3.9 메시징 플랫폼 — 별도 repo `messaging-library`로 옮기고 버전 1.0.0으로 받는다
이 절도 위 머리의 범위보다 뒤에 main에 들어간다. 범위: `2959eff0..claude/x3-messaging-library-1aa3fa`(2026-11-08, 같은
소유자 결정, design-docs `repo-structure/05-library-repos.md` 13.1절 3~5단계). 메시징은 템플릿 adapter 넷이 쓰므로, 라이브러리를
먼저 `dev.cakit.messaging` 1.0.0으로 Gitea Packages에 배포하고 템플릿이 그 버전을 받게 바꿨다. 코드와 이력은
https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library 에 있다. 동작은 같다(같은 소스, 패키지 이름만 바뀜).
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-57 | 삭제: `src/platforms/messaging`(19개 모듈)과 빈 `src/platforms/`, registry의 메시징 19행, workflow `messaging-certification.yml`, 저장소 계약 테스트 `MessagingPublicSurfaceContractTest`(라이브러리 repo로), 살아 있는 문서 `docs/messaging/`(폴더째, 같은 이름으로 라이브러리 repo에), SpotBugs 제외의 메시징 클래스 줄, 카탈로그의 메시징 전용 항목(`avro`, `cloudevents`, `protobuf` 4.33.2와 `protobuf-java`). `check-repo-layout.py` 허용 목록에서 `platforms`를 뺐다. 메시징 기록(`docs/design/2026-08-10-messaging-platform-design.md` 등)은 본문을 두고 머리 블록 「현재 정본」만 고쳤다 | 이 경로를 고친 서비스는 「수정 대 삭제」 충돌. `project(':messaging:…')`를 쓴 자기 leaf는 빌드가 실패한다. `src/platforms/` 아래 자기 폴더를 둔 서비스는 `check-repo-layout.py`가 실패한다 | 메시징 코드를 고쳤으면 그 수정을 messaging-library repo로 보낸다(`docs/work/reference/related-repos.md` 2절). 자기 leaf의 `project(':messaging:<모듈>')`은 B-58처럼 좌표로 바꾼다 | design-docs `repo-structure/05-library-repos.md` 4·13절 |
| B-58 | 받는 법: `src/settings.gradle`에 Gitea Packages 저장소를 `exclusiveContent`(group `dev.cakit`와 그 아래만)로 더했다. 카탈로그에 `messagingLibrary = "1.0.0"`과 모듈 여섯(`libs.messaging.core.api` 등). 쓰는 leaf(`adapter:outbound:messaging`, `adapter:outbound:messaging-kafka`, `adapter:inbound:messaging`, 시험만 `composition:outbox-relay`·`adapter:outbound:persistence-jpa`)가 좌표로 받는다. Java 패키지 `dev.caskeleton.messaging` → `dev.cakit.messaging`, auto-configuration 이름 `dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration`. 그대로인 것: 설정 키 `app.messaging.*`, env 키, Flyway 위치 `db/migration/messaging`과 파일, 표 이름 | 메시징 타입을 import한 자기 코드가 컴파일되지 않는다. `afterName`·`beforeName`으로 플랫폼 root 이름을 적은 자기 auto-configuration은 순서 제약이 조용히 사라진다. 캐시가 빈 빌드(새 기계, 이미지 builder)는 `git.learn.hyeonworks.com`에 닿아야 한다 | import와 이름 문자열의 `dev.caskeleton.messaging`을 `dev.cakit.messaging`으로 바꾼다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기에 넣지 않는다). merge 뒤 `./gradlew resolveAndLockAll --write-locks`. 빌드 기계가 Gitea에 닿는지 본다(공개 owner라 토큰은 필요 없다) | messaging-library `CHANGELOG.md` 1.0.0 |
| B-59 | registry 칸 둘: 맨 위 `library_groups`(`["dev.cakit"]`)와 행마다 `allowed_libraries`(`group:artifact`). 방향 검사(`verifyModuleDependencyDirection`)가 소유 group 라이브러리의 운영 선언(`runtimeOnly` 포함)과 컴파일에서 보이는 모듈을 그 칸과 대조한다. build-logic `ModuleRegistry`·`VerifyModuleDependencyDirectionTask`가 바뀌었다 | 자기 leaf가 `dev.cakit.*` 모듈을 칸에 적지 않고 쓰면 `verifyCleanArchitectureDependencies`가 「forbidden library dependencies」로 실패한다. registry를 읽는 자기 도구가 모르는 키를 거절하면 실패한다 | 그 leaf 행에 `allowed_libraries`를 적는다(`src/config/architecture/README.md` 「별도 repo 라이브러리」). build-logic을 고쳐 쓴 서비스는 두 파일 병합 충돌을 푼다 | 같은 설계 10.2절 T2(Q11) |
### 3.10 CI — workflow를 단계 파일 셋으로 접었다
2026-11-08. 소유자가 design-docs `repo-structure/03-ci.md` 7절 B안과 11절 ①~⑧을 권하는 안대로 정했다(2026-11-07). workflow 15개를 `.gitea/workflows`의 `pr.yml`·`main.yml`·`release.yml` 셋으로 접고, 무엇을 돌릴지는 Gradle 단계 태스크가 정한다. Gitea Actions(desktop runner)에서 실제로 돈다.
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-60 | 삭제: `.github/workflows`의 `build-logic.yml`, `ci-quality-gates.yml`, `dependency-vulnerability.yml`, `docs-check.yml`, `fileserver-nightly.yml`, `fileserver-pr.yml`, `integration-main.yml`, `jpa-next.yml`, `jpa-nightly.yml`, `link-check.yml`, `notification-platform.yml`, `object-storage-qualification.yml`, `pr-adapters.yml`, `redis-sdk-topology.yml`, `release.yml`, 그리고 `.github/actions/setup-gradle-java`, `.github/scripts/install-jq.sh`, `.github/dependency-review-config.yml`. 다른 단계가 이미 돌리던 job(`fileserver-pr` 다섯, `fileserver-nightly` 재실행 셋, `jpa-nightly` lane 셋, `notification-platform` `pr`, object storage MinIO 둘)은 옮기지 않고 지웠다. 나머지는 세 파일의 job이 됐다: PR은 `pr.yml`(`gradle`·`vulnerabilities`·`done`), main과 nightly는 `main.yml`(`main`·`integration`·`build-logic`·`configuration-cache`·`links`·`vulnerabilities`·`http3-experimental`, nightly 행렬과 `compose-smoke`, 마지막에 `performance`), 태그는 `release.yml` | 이 파일을 고친 서비스는 「수정 대 삭제」 충돌이 난다. Gitea는 `.gitea/workflows`가 있으면 `.github/workflows`를 읽지 않으므로 남긴 `.github/workflows` 파일은 돌지 않는다 | 자기 workflow 변경을 세 파일의 같은 단계 job으로 옮긴다. 새 workflow 파일을 만들지 않는다(`docs/work/reference/gates.md` 7절). GitHub에서 돌리는 서비스는 `https://github.com/` 접두어를 뺀다 | design-docs `repo-structure/03-ci.md` 3.1·7.2절 |
| B-61 | 단계 이동: 어댑터 컨테이너 lane(web·websocket·httpclient·jpa)과 Redis standalone topology lane이 PR에서 빠졌다. 매개 변수가 없는 것은 원래부터 `mainCheck`·`integrationCheck` 안이고, 행렬(PostgreSQL major, HTTP transport, Redis topology)은 nightly job이다. `performanceCheck`는 매 main push가 아니라 nightly에서 다른 무거운 job 뒤에 돈다. build-logic 시험은 main 단계다. main push는 `ci`를 다시 돌리지 않는다(PR 단계가 돌렸다) | PR이 어댑터 회귀를 막지 않고 main에서 빨갛게 된다 | 어댑터를 바꾼 PR은 그 leaf의 strict lane을 desktop에서 돌린다(`docs/work/reference/gates.md` 2절). main을 오래된 PR 머리로 병합하지 않게 branch protection의 「오래된 브랜치 막기」를 켠다 | 같은 설계 11절 ②③⑦ |
| B-62 | 새 Gradle 태스크: `prCheck`(= `ci` + `verifyDependencyLocks` + `verifyComposeProfiles` + `verifyRepositoryLayout` + `documentCheck`←`testDocumentChecks`). `verifyStrictLaneStages`가 workflow YAML·bash를 해석하지 않고 그래프 검사와 형식 검사만 한다. `strictLaneStages` 문법이 `stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'` 모양으로 바뀌었고(단계마다 workflow·이벤트·필터·job·옵션·조건), `workflowDirectory`는 `.gitea/workflows`다. build-logic의 `ShellScript`·`WorkflowGradleInvocations`·`TaskSelectors`를 지웠다 | 서비스 `src/build.gradle`의 옛 `stage ':ci', ':mainCheck', …` 줄은 설정 단계에서 실패한다. 단계 job이 정해진 한 줄이 아니면 `verifyStrictLaneStages --dry-run`이 실패한다 | `src/build.gradle`의 `strictLaneStages` 블록을 템플릿 것으로 바꾸고 자기 workflow job 이름에 맞춘다. 단계 job은 `run: ./gradlew <단계> <옵션>` 한 줄로 쓴다(`src/build-logic/AGENTS.md` 「단계 job의 모양」) | 같은 설계 7.4절 |
| B-63 | 릴리스: 이미지를 ghcr가 아니라 이 Gitea의 컨테이너 레지스트리(`<서버>/<소유자>/caskeleton`)에 올리고, cosign keyless 대신 키 쌍으로 서명한다. repo secret `PACKAGE_TOKEN`·`COSIGN_PRIVATE_KEY`·`COSIGN_PASSWORD`가 필요하다. JPA 승격은 artifact 대조 대신 `needs: jpa-release-gate`(같은 실행의 행렬 전부)다. 손으로 실행하면 push·서명 앞까지 돈다. `actions/upload-artifact`·`download-artifact`를 쓰지 않는다(증거는 job 로그) | 태그를 달아도 secret이 없으면 push에서 실패한다. keyless 신원(`--certificate-identity`)으로 확인하던 admission 정책은 새 서명을 거절한다 | secret을 만들고, admission 정책을 서명 job이 로그에 남긴 공개 키로 바꾼다. 다른 레지스트리를 쓰면 `release.yml`의 `REGISTRY` 계산을 바꾼다 | 같은 설계 9절, 11절 ④ |
| B-64 | 검증 진입점 `scripts/verify.sh <단계>`(`docs`·`leaf`·`pr`·`main`·`nightly`·`release`·`app`·`round`). 단계 이름이 workflow와 같고, 무거운 단계는 지금 작업 트리를 패치로 desktop에 보내 잠금 아래에서 돌린다. workflow가 부르는 스크립트는 `scripts/ci/`(`trivy-scan.sh`, `redis-topology.sh`, `forward-ports.py`, `verify-configuration-cache.sh`)다 | 없음(새 파일). desktop·잠금 경로는 소유자 환경 값이다 | 자기 환경에 맞게 `VERIFY_HOST`·`VERIFY_REMOTE_REPO`·`VERIFY_LOCK`을 주거나 `--on here`로 쓴다 | design-docs `harness/01-harness-design.md` 6절 |
| B-65 | dev lane overlay(`src/app-bootstrap/compose-lanes/dev.yaml`)의 heap dump가 bind mount `./tmp/heap-dumps`가 아니라 named volume `heap-dumps`다. Docker가 root 소유로 만든 폴더 때문에 worktree를 지우지 못했다 | 호스트 `tmp/heap-dumps`에 dump가 생기지 않는다 | `docker compose cp app:/var/tmp/heap/<file> .`로 꺼낸다 | `docs/work/operate.md` 4.1절 |
| B-66 | fileserver 지원 매트릭스(`docs/fileserver/support-matrix.md`)의 증거 칸이 job id 대신 테스트 클래스·모듈 `test`·남은 job(`fileserver-nfs-ambiguity`, release의 셋)이고, `FileserverDocumentationCoverageTest`가 행마다 그 이름이 있는지 본다 | 서비스가 그 표에 지운 job id를 적었으면 시험이 실패한다 | 그 행의 증거를 실제 테스트 클래스나 모듈 `test`로 바꾼다 | B-60 |
## 4. DB 마이그레이션
### 4.1 새 버전과 영향
| stream (history 표) | 버전 | 하는 일 | 기존 데이터 영향 | 실패 조건 | 근거 |
|---|---|---|---|---|---|
| postgresql (`flyway_schema_history`, persistence-jpa 선택 시) | V20 | `outbox_event.deferred_attempt_count INTEGER NOT NULL DEFAULT 0` + CHECK ≥ 0 | 기존 행 0. 지난 claim은 전부 시도 예산에 센다 | `outbox_event`를 건드린 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V19에 남음(exit 70) | `1400dc15`, 3차 수정(RR-02-09) |
| 〃 | V21 | `outbox_aggregate_sequence`(aggregate별 counter), `outbox_aggregate_sequence_floor`(V21 적용 시각 마이크로초 한 행), 남은 행 최대 번호로 counter 미리 생성, 유일 인덱스 `ux_outbox_event_aggregate_order (tenant_scope, aggregate_type, aggregate_id, aggregate_sequence, event_index)` | 새로 생기는 aggregate의 첫 번호가 floor+1(약 1.7×10¹⁵)부터. 순서 열이 NULL인 옛 행은 비교 안 함 | ① 같은 순서 키 행이 이미 둘 이상 → 실패, V21 전체 롤백, V20에 남음(exit 70). ② `SET LOCAL lock_timeout = '5s'` 안에 `outbox_event` 잠금을 못 잡으면 실패·롤백. ③ 같은 이름 인덱스가 유효한 유일 인덱스가 아니면(실패한 CONCURRENTLY) `RAISE EXCEPTION` | `1400dc15`, `bbe944bd` · `docs/runbooks/outbox-dead-letter.md` §8 |
| 〃 | V22 | `outbox_event.last_failure_code VARCHAR(120)` NULL, 기본값 없음. 새 상태 `PARKED`는 DDL 없음 | 행 재작성 없음. 기존 행은 다음 실패 때까지 NULL | `outbox_event`를 건드린(읽기만 한 것도) 트랜잭션이 열려 있어 5초(`SET LOCAL lock_timeout`) 안에 잠금을 못 잡으면 실패·롤백, V21에 남음(exit 70) | `bbe944bd`, 3차 수정(RR-02-09) |
| notification (`flyway_jpa_notification_history`, notification-platform 선택 시) | V11 | `notification_reconciliation_job.claimed_until timestamptz`, `claim_fence bigint NOT NULL DEFAULT 0` + CHECK | 기존 job은 fence 0, lease 없음 | 그 표를 건드린 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V10에 남음(exit 70) | `34565130`, 3차 수정(RR-02-09) |
| 〃 | V12 | `notification_suppression`의 `(tenant_id, normalized_target_hmac, reason)` 중복 행을 **삭제**(만료 없는 것 > 늦은 만료 > 이른 `effective_at` > 이른 `created_at` > 작은 id 순으로 하나 남김) 후 UNIQUE `uk_notification_suppression_target` | 지운 행의 `SuppressionId`는 더 이상 조회되지 않는다. 되돌리려면 백업 필요 | 그 표를 건드린 트랜잭션이 열려 있어 5초 안에 잠금(행 잠금 포함)을 못 잡으면 실패·롤백(삭제도 롤백), V11에 남음(exit 70) | `1400dc15`, 3차 수정(RR-02-09) |
| 〃 | V13 | `notification_request.acceptance varchar(40) NOT NULL DEFAULT 'ACCEPTED'` + CHECK(`ACCEPTED`, `DROPPED_AS_DUPLICATE`) | 기존 요청은 모두 `ACCEPTED` | 그 표를 건드린 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V12에 남음(exit 70) | `5786126c`, 3차 수정(RR-02-09) |
| sample (`flyway_sample_schema_history`, sample-portfolio를 남긴 경우. **샘플 삭제(B-49)로 템플릿에서 사라졌다**) | V8_1 | 유일 인덱스 `uq_poster_title_ci ON poster (upper(title))` | 없음 | 대소문자만 다른 제목이 있으면 `poster has titles that differ only by case or repeat: ...`로 실패. `poster`에 쓴 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V8에 남음 | `34565130`, 3차 수정(RR-02-09) |
| grpc-ledger (optional-platforms, history 표 확인 못 함) | V002 | 부분 인덱스 `ix_grpc_operation_ledger_finished_completed_at` (일반 `CREATE INDEX`) | 없음 | 큰 ledger면 만드는 동안 쓰기가 멈춘다. 파일 주석은 손으로 `CONCURRENTLY`를 먼저 돌리라고 한다. ledger에 쓴 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V001에 남음 | `1400dc15`, 3차 수정(RR-02-09) |
| 〃 | V003 | `grpc_operation_ledger.claim_attempt BIGINT NOT NULL DEFAULT 1` + CHECK > 0 | 기존 행은 첫 시도(1) | ledger를 건드린 트랜잭션이 열려 있어 5초 안에 잠금을 못 잡으면 실패·롤백, V002에 남음 | `bbe944bd`, 3차 수정(RR-02-09) |
- **새로 연결된 stream**: `adapter:inbound:messaging`을 `runtimeOnly`로 넣으면 platform의 `V1101__messaging_inbox.sql`을
`MessagingInboxSchemaStream`이 `flyway_messaging_inbox_history`에 적용한다(baseline 1100). 넣지 않으면 영향 없음
(`src/adapter/inbound/messaging/README.md`).
- **잠금 대기 상한(3차 수정, RR-02-09)**: 위 표에서 이미 쓰이는 테이블을 잠그는 마이그레이션은 모두 그 잠금 앞에
`SET LOCAL lock_timeout = '5s'`를 둔다. 실패하면 SQLState `55P03`이고, 열린 트랜잭션을 끝낸 뒤 다시 배포한다
(`docs/runbooks/migration-failed.md` "Classify the failure"). 자기 스트림에도 같은 규칙과 검사
(`LockWaitMigrationInspector`, 예: `SampleMigrationLockWaitTest`)를 둔다(`docs/jpa/migration-guide.md` "Bound the lock wait").
검사기는 3차 확인 리뷰(RR3-02-01) 뒤로 기존 테이블을 가리키는 `REFERENCES`, trigger 만들기·지우기, `REINDEX` 등을 더 잡고,
`CREATE TABLE IF NOT EXISTS`를 "이 마이그레이션이 만든 테이블"로 세지 않으며, 0인 `lock_timeout`과 `executeInTransaction=false`
파일의 `SET LOCAL`을 상한으로 세지 않는다. 자기 스트림의 이미 배포된 파일이 새로 걸리면 그 파일은 고치지 않고 규칙 이전
목록에 더한다(템플릿은 idempotency V1, notification V3, messaging V1003, postgresql V11·V12를 더했다). 파일 경로를 넘기는
`unboundedLockingStatements(Path)`가 옆의 `.sql.conf`까지 읽으니, 복사한 검사는 문자열 대신 경로를 넘긴다.
r9부터 검사기는 Flyway가 `.sql.conf` 없이 스스로 트랜잭션 밖에서 돌리는 문장(`VACUUM`, `CREATE`·`DROP INDEX CONCURRENTLY`,
`REINDEX SCHEMA` 등)이 있는 파일도 트랜잭션 밖으로 보고 그 파일의 `SET LOCAL`을 상한으로 세지 않으며(그런 파일은 다른 문장과
섞이면 Flyway가 기본 `mixed=false`로 거부한다), `VACUUM FULL`은 "마이그레이션에 두지 말고 운영 절차로" 거부한다.
`.sql.conf`는 Flyway처럼 properties로 읽어 `executeInTransaction=FALSE`·`executeInTransaction: false`도 트랜잭션 밖으로 본다.
`GRANT … REFERENCES ON`과 `REINDEX (CONCURRENTLY) …`는 더 이상 거부하지 않는다. 자기 스트림 검사가 새로 실패하면 그 파일은
Flyway가 거부하거나(`mixed=false`) 상한 없이 도는(`mixed=true`) 파일이다. 아직 배포 전이면 문장을 나누고, 이미 배포했으면
규칙 이전 목록에 더한다(r9, 재리뷰 RR4-02-01).
재리뷰 round7(RR7-03-05) 수정부터는 `.sql.conf`가 `executeInTransaction=true`를 정한 파일의 `VACUUM FULL`·비동시
`REINDEX SCHEMA|DATABASE|SYSTEM`도 앞의 `SET LOCAL`과 상관없이 같은 이유로 거부한다. 그런 파일은 PostgreSQL이 배포 때
`25001`로 거부하므로 배포된 적이 없다. 새로 걸리면 그 문장을 마이그레이션에서 빼 운영 절차로 옮긴다.
- **번호 충돌**: 템플릿이 이제 postgresql V20~V22, notification V11~V13, grpc V002·V003을 쓴다(sample V8_1은 샘플과 함께 사라졌다, B-49). 파생 서비스가 같은
위치에 같은 번호를 두었다면 Flyway가 같은 버전 두 개로 실패한다. 자기 마이그레이션은 템플릿과 떨어진 번호대로 옮긴다
(이미 적용된 파일 이름을 바꾸면 checksum·history가 어긋나므로 운영 DB에 적용된 것이면 DB 담당과 정한다).
- **migration-on-startup=false로 운영하는 서비스**: `infra/postgres/apply-capability-streams.sh`(지금 `src/app-bootstrap/compose-lanes/postgres/apply-capability-streams.sh`, B-51)가 바뀌었다(stream을
`/flyway/streams/<name>`에서 먼저 찾음). 운영자가 직접 적용한다.
### 4.2 이 브랜치의 이전 V21(과 3차 수정 전 V20·V22·V11~V13·V8_1·V002·V003)을 적용한 DB
3차 수정(RR-02-09)은 이 브랜치가 더한 마이그레이션 중 이미 쓰이는 테이블을 잠그는 여덟 개(postgresql V20·V22,
notification V11·V12·V13, sample V8_1, grpc-ledger V002·V003)에 `SET LOCAL lock_timeout`을 넣으려고 파일을 직접
고쳤다. V21과 같은 전제(어느 배포에도 적용되지 않음)다. 그 이전 내용을 적용한 개발 DB도 아래 V21과 같이 checksum
불일치로 기동이 실패하므로 다시 만든다. 새 checksum은 `applied-migrations.sha256`에 있다(sample·grpc-ledger는 고정 목록
없음).
V21은 `bbe944bd`에서 V22를 따로 두지 않고 직접 고쳤다(floor 표와 counter 미리 만들기를 넣음). `1400dc15`·`5786126c` 시점의
V21(sha256 `f830cda5…`)을 적용한 DB는 새 V21(sha256 `21744ea1…`, `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`)과
checksum이 달라 Flyway 검증에서 기동이 실패한다(exit 70 `MIGRATION_FAILED`).
- 해당 여부 확인: V21이 history에 있는데 floor 표가 없으면 이전 V21이다.
```sql
SELECT version, success FROM flyway_schema_history WHERE version = '21';
SELECT to_regclass('outbox_aggregate_sequence_floor'); -- NULL이면 이전 V21
```
- 할 일: 그 개발 DB를 다시 만든다(예: Compose PostgreSQL 볼륨 삭제 후 재기동). `flyway repair`로 checksum만 맞추지 않는다.
이전 V21에는 floor 표와 counter 미리 만들기가 없어서 스키마가 새 코드와 맞지 않는다.
- 운영 DB: 이 브랜치는 main에 합쳐지기 전이라 어느 배포에도 V21이 없다는 것이 커밋 메시지의 전제다(`bbe944bd`). 파생 서비스가
이 브랜치를 운영에 미리 배포했다면 이 전제가 깨진다. 그 경우는 DB 담당과 정한다.
### 4.3 V21 배포 전 절차
`docs/runbooks/outbox-dead-letter.md` §8을 따른다. 요약:
1. **Step 1 — 중복 확인(읽기 전용)**: §8의 `v21-duplicate-order-keys` 쿼리. 0행이면 배포한다.
2. **Step 2**: 미발행 행이 있는 키는 relay가 비울 때까지 기다린다. `DEAD` 행은 §4 처분을 먼저 한다.
3. **Step 3**: 모두 `PUBLISHED`인 키의 중복을 `outbox_event_v21_duplicates`로 복사한 뒤 지운다(`v21-remove-published-duplicates`).
4. **Step 0 — outbox가 커서 V21이 거는 SHARE 잠금을 견딜 수 없으면**: 중복을 없앤 뒤 같은 이름 인덱스를 transaction 밖에서
`CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS ux_outbox_event_aggregate_order ...`로 먼저 만든다. V21의 `IF NOT EXISTS`가 그것을 쓴다.
CONCURRENTLY가 실패해 INVALID 인덱스가 남으면 `DROP INDEX CONCURRENTLY` 후 Step 1부터.
5. tenant scope를 바꾼 서비스는 옛 scope의 미발행 행이 없는지 §8의 `GROUP BY tenant_scope` 쿼리로 본다.
이 절의 SQL 블록은 `:adapter:outbound:persistence-jpa:postgresqlOutboxOrderKeyRunbookIntegrationTest` lane이 실제 PostgreSQL에서 돌린다.
V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failure"에 추가됐다.
### 4.4 되돌리기
- **down 마이그레이션 없음.** 이 repo에 `U*__*.sql`(Flyway undo) 파일이 없다. `migration-failed.md`는 앞으로 고치는 마이그레이션을
먼저 쓰고, 적용된 파일 수정·history 고쳐 쓰기·`clean`을 금지한다.
- **배포 전 백업**: 마이그레이션을 돌리기 전에 DB 백업(또는 PITR 지점)을 남긴다. 특히 notification V12는 행을 지운다.
스키마를 되돌려야 하면 백업 복원이 유일한 길이고, `migration-failed.md` Escalation에 따라 DB 담당이 결정한다.
- **V21 실패 시**: V21은 transaction 하나라 실패하면 V20에 그대로 남는다. 원인(중복·잠금)을 없애고 다시 배포한다.
- **앱만 옛 버전으로 되돌릴 때**: 이번 범위의 마이그레이션은 열·표·인덱스·제약을 더하기만 하고(V12의 중복 행 삭제 제외) 열을 지우거나
이름을 바꾸지 않는다. 새 열은 기본값이 있거나 NULL을 허용해서 옛 코드의 insert가 막히지 않는다. 다만 V21 유일 인덱스와 V12·V8_1
유일 제약은 옛 코드가 같은 키를 두 번 쓰면 이제 DB가 거부한다. 옛 앱의 Flyway가 자기가 모르는 최신 버전(V20~V22 등)이 적용된
DB에서 기동하는지는 **확인 못 함**(이 repo는 해당 Flyway 옵션을 설정하지 않음). 스테이징에서 먼저 확인한다.
## 5. 동작 변경 — 코드는 안 깨지지만 결과가 달라진다
| 영역 | 바뀐 것 | 영향 | 근거 |
|---|---|---|---|
| outbox relay | 일시 거부(`REJECTED_RETRYABLE`)·무응답(`AMBIGUOUS`)은 시도 예산을 쓰지 않고 최대 5분 간격(`OutboxBackoffPolicy.MAX_DELAY`)으로 끝없이 재시도. 실패 원인 코드를 `last_failure_code`에 남김. 수동 보류 상태 `PARKED`. 지표 `outbox.retry.long.size`·`outbox.retry.long.age`. claim이 DEAD로 옮긴 행(`ATTEMPT_COUNTERS_INCONSISTENT`·`UNREADABLE_ROW`)도 그 이유를 `last_failure_code`에 쓰고, 경보에 `outbox.pending.size{status=DEAD}` > 0을 더함(RR-02-12). 이 버전이 모르는 상태 값은 `outbox.pending.size`에서 빼고 WARN 한 번(RR-02-11) | 진짜 인증 오류도 DEAD가 아니라 계속 재시도한다. 경보는 새 지표로 잡는다. 처분 SQL은 `docs/runbooks/outbox-dead-letter.md`·`outbox-publish-failed.md` | `34565130`, `1400dc15`, `bbe944bd` |
| outbox append | 읽기 전용 트랜잭션 안의 `append`도 거부(`CallerTransaction.requireReadWrite`). 전에는 트랜잭션 밖만 거부했고 읽기 전용에서는 이벤트가 조용히 사라졌다 | `inRead` 안에서 이벤트를 쓰던 코드가 이제 예외로 드러난다 | `5786126c` · `JpaOutboxStore.java` |
| 순서 번호 | aggregate 순서 번호를 DB counter가 매긴다(`OutboxAggregateSequencePort.nextSequence`). 한 aggregate에 이벤트가 하나면 `AggregateOrder.first()`. 같은 순서 키 두 번째 append는 유일 인덱스가 거부(정확한 오류 코드 확인 못 함) | 소비자가 보는 번호가 새 aggregate에서 floor+1부터 시작해 크게 뛴다. 벽시계로 번호를 만들던 코드는 바꾼다 | `1400dc15`, `bbe944bd` |
| durable operation | operation id가 UUIDv7(`UuidV7DurableOperationIdFactory`). 제출 이벤트의 event id·aggregate id가 UUIDv7이고 tenant scope는 `global` | 전에는 이 이벤트가 messaging bridge에서 전부 DEAD가 됐다(커밋 `1400dc15` 본문). 소비자가 보는 id 모양이 바뀐다 | `1400dc15`, `bbe944bd` · `SubmitDurableOperationUseCase.java` |
| tracing | 자체 tracer를 지우고 Boot tracing·OTLP로. `OTEL_EXPORTER_OTLP_ENDPOINT`는 base 주소로 보고 `<값>/v1/traces`(OTLP/HTTP)로 보낸다. 빈 값이면 exporter 없음. `meta.traceId`가 tracer의 trace id와 같다 | span이 실제로 나가기 시작한다. gRPC 포트(4317)를 넣었다면 HTTP 수신 주소로 바꾼다 | `34565130`, `1400dc15` · `docs/registries/env-keys.yaml` |
| correlation id | `X-Correlation-Id`가 `[A-Za-z0-9._-]{1,128}`(앞뒤 공백 제거 후) 밖이면 서버가 새 값으로 바꾼다 | 규칙 밖 값을 쓰던 호출자는 로그에서 자기 값을 못 찾는다 | `1400dc15` · `docs/web/http-contract.md` §3 |
| String 응답 | `String`을 반환하는 컨트롤러에 JSON을 요청하면 Envelope(`"data": "<문자열>"`)로 나간다. 전에는 500이었다. `byte[]`는 감싸지 않는다(`/v3/api-docs`) | JSON 클라이언트가 이제 200을 받는다 | `1400dc15` · `EnvelopeBodyAdvice.java` |
| GraphQL | 크기를 선언하지 않은 list를 원소 20개로 계산, `first`·`last` 둘 다면 큰 쪽. per-parent 경고 임계 10(`APP_GRAPHQL_PER_PARENT_FETCH_WARNING_THRESHOLD`). deadline instrumentation이 `REQUEST_TIMEOUT` | 전에 통과하던 깊은 목록 쿼리가 복잡도로 거부될 수 있다. 필요한 필드에 `estimatedListSize`를 선언 | `34565130`, `1400dc15`, `bbe944bd` |
| WebSocket | 노드당 STOMP 세션 1000개(`APP_WEBSOCKET_MAX_CONNECTIONS`), 초과 시 연결 후 1013으로 닫음. 메시지 64KB, 송신 버퍼 512KB, 송신 시간 10s, 첫 메시지 60s를 명시 | 동시 연결이 많은 서비스는 상한을 올린다 | `1400dc15` · `env-keys.yaml` |
| gRPC 서버(inbound adapter) | 수신 메시지 1 MiB(io.grpc 기본 4 MiB에서 줄어듦), 메타데이터 8 KiB, 연결당 동시 호출 100, 실행 스레드 32·대기열 256, 기본 deadline 10s, keepalive 30s/10s, 최대 연결 수명 30분, drain 2s | 1 MiB를 넘는 메시지는 거부된다 | `1400dc15` · `src/adapter/inbound/grpc/.../GrpcServerSettings.java` |
| 파일 서버 | 정리 worker 기본 켜짐(`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED` false→true, 끄면 기동 경고). copy·move 대상은 기본 namespace만(`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, 그 밖은 `ACCESS_DENIED`). namespace 쿼터 상한(`APP_FILESERVER_PLATFORM_QUOTA_NAMESPACE_LIMIT`, 비우면 무제한, 넘으면 413 `QUOTA_EXCEEDED`). move가 쿼터를 옮긴다 | 다른 namespace로 copy·move하던 서비스는 허용 목록을 설정해야 한다. 정리 worker가 물리 객체를 지운다. 이 수정 전에 다른 namespace로 move된 파일의 바이트는 여전히 출발 namespace 사용량에 잡혀 있고 도착 namespace에는 없다 — 그 파일을 지우면 도착 namespace에서 회수되어(0에서 멈춘다) 출발 쪽은 그대로 남는다. 상한을 켜기 전에 `docs/fileserver/operations.md` 「Namespace quota drift」의 쿼리로 namespace별 차이를 보고, 있으면 같은 절의 재계산 SQL로 고친다(쓰기를 멈춘 뒤, 재리뷰 RR-01-17) | `5786126c`, `bbe944bd` · `CopyFileApplicationUseCase.java`, `env-keys.yaml` |
| 알림 | SES 콜백 replay 허용 차이 5m→1h. 중복 제거 창에서 버린 제출을 `CANCELED`·`DROPPED_AS_DUPLICATE`로 저장해 같은 멱등성 키에 같은 영수증. reconciliation job은 DB lease로 소유. INGEST_ONLY도 accept 때 route 이름 기록 | 콜백·영수증 결과가 바뀐다 | `34565130`, `5786126c` |
| Redis | 캐시 조건부 쓰기가 자기 SCRIPT lane(`APP_CACHE_REDIS_MAXIMUM_SCRIPT_CONNECTIONS`, 기본 4)을 쓴다. registry에서 `redis.capability.*` 지표 6개를 빼고 `redis.lane.*` 6개를 더했다 | Redis 연결이 캐시 lane만큼 늘어난다. 옛 지표 이름으로 만든 대시보드·경보는 바꾼다 | `bbe944bd` · `docs/registries/metrics.yaml` |
| 설정 바인딩 | strict 설정에서 선택 숫자·크기·기간 키의 빈 값은 "미설정". 목록 원소 아래 오타 키도 거부(`StrictSettingsBinder`) | `.env.example`의 빈 값으로 기동 가능. 목록 원소 아래 오타는 이제 기동 실패 | `5786126c` · `StrictSettingsBinder.java` |
| 권한 매핑 | `app.authz.role-permissions` 기본 항목이 app-bootstrap `config/security.yml`에서 각 capability의 module-defaults(notification·fileserver·durable-operation)로 옮겨짐. 여러 출처의 항목이 합쳐진다 | 모듈을 빼면 그 권한 매핑도 빠진다 | `1400dc15` · `src/app-bootstrap/src/main/resources/config/security.yml` |
| 로그 설정 | logback이 `APP_LOG_*` 대신 `app.logging.*`을 읽는다(환경 변수 이름은 그대로 매핑) | 프로필 yml의 `app.logging.*`이 이제 먹힌다 | `1400dc15` · `logback-spring.xml` |
| local 프로필 | `server.port`가 `${APP_SERVER_PORT:8080}`을 읽는다. Flyway·`ddl-auto validate`·PostgreSQL vendor를 module-defaults에서 받는다 | local에서 `APP_SERVER_PORT`가 다른 값이면 포트가 바뀐다 | `1400dc15`, `5786126c` · `application-local.yml` |
| deprecated | `APP_CACHE_REDIS_TTL_JITTER`는 아무것도 바인딩하지 않음(`removal_deadline: 2027-02-28`) | 값이 아무 효과 없다 | `1400dc15` · `env-keys.yaml` |
| HTTP client(JDK transport) | 스트리밍 응답의 read-idle 감시가 전용 데몬 스레드 하나(`httpclient-jdk-read-idle`)에서 돈다. 스트림마다 감시 작업 하나, 스트림을 닫으면 작업을 바로 취소 | 스레드 덤프에 그 스레드가 하나 보인다. 공용 `ForkJoinPool`이 바빠도 timeout이 설정값에 난다(전에는 늦게 났다). Apache transport(기본)는 영향 없음 | 3차 확인 리뷰 RR3-03-01 · `src/adapter/outbound/httpclient/.../jdk/ReadIdleInputStream.java` |
| 멱등성 | `IDEMPOTENCY_RECOVERY_REQUIRED`를 내는 예외 메시지 끝에 scope digest가 붙는다. Redis 기록 조회(INSPECT 스크립트)가 `leaseUntil`을 돌려줘 `processingLeaseUntil`이 실제 lease 끝이다(전에는 key TTL 끝, 즉 lease + replay TTL) | 예외 메시지 전체에 맞추던 로그 매처는 고친다. 회복 절차는 `docs/runbooks/idempotency-unavailable.md`(digest로 기록을 찾는다) | 3차 확인 리뷰 RR3-03-03·05 · `src/application-core/.../idempotency/IdempotencyRecoveryRequiredException.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java` |
| 멱등성(lease가 지난 실행) | lease가 지난 `EXECUTING` 기록을 claim이 만나면 기록을 바꾸지 않고 500 `IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 그 실행의 주인이 늦게 부른 `complete`·`markFailed`는 기록된다. 전에는 두 저장소 모두 기록을 `ABANDONED`로 바꿔(PostgreSQL은 `last_transition_kind` `EXPIRED_EXECUTION`) 늦은 결과를 거절했고 첫 요청도 500이었다. 이미 끝난 lease의 `renew`는 두 저장소 모두 거절한다(Redis는 전에 받아들였다). 남의 lease 지난 실행을 `inspect`하면 `ABANDONED`(전에는 `IN_PROGRESS_OTHER`) | 30s를 넘는 정상 요청이 이제 결과를 남기고 정상 응답을 받는다. 같은 키 재전송은 500을 받은 뒤 재생을 받을 수 있다. 직접 구현한 store는 `IdempotencyStoreContract`의 바뀐 시간 케이스로 확인한다. 운영자는 `EXECUTING` 기록을 지우지 않는다 — 살아 있는 실행의 늦은 결과가 기록을 못 찾아(`ABSENT`) 사라진다(`docs/runbooks/idempotency-unavailable.md`) | `70fb80bf`(2026-11-04 소유자 결정) · `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java` |
| 멱등성(lease가 끝난 시작, r9) | lease가 지난 `CLAIMED`는 주인도 시작할 수 없다(`LEASE_EXPIRED`). executor는 작업을 돌리지 않고 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거부, 메시지 `the claim's processing lease ran out before the action started`)로 답하고, 다음 같은 키 요청이 그 claim을 넘겨받아 실행한다. 전에는 Redis가 시작해 작업을 돌렸고 그동안 다른 요청은 lease가 지난 실행으로 500을 받았다. PostgreSQL은 `NOT_OWNER`로 거절해 500 `IDEMPOTENCY_RECOVERY_REQUIRED`였다. | claim과 시작 사이가 lease(기본 30s)보다 길었던 드문 요청이 500 대신 503(같은 키 재전송)을 받는다. 클라이언트는 `error.code`로 이미 가르므로 바꿀 것이 없다. 운영자는 이 503에서 저장소 장애를 찾지 않는다(runbook) | r9(재리뷰 README 15 남음, RR5-01-02·03) · `IdempotencyExecutor.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java` |
| 멱등성(같은 attempt의 재시도, r10) | lease가 지나 시작을 거절당한 claim과 재시도 가능 실패 기록은 같은 attempt로 다시 claim해도 넘겨받는다(`TakenOverClaimed`, attempt+1). 전에는 두 저장소가 그 claim을 재생해(`ReplayedAcquire`) 시작이 다시 거절되거나(503, 기록이 사라질 때까지) 시작할 수 없는 기록이라 500 `IDEMPOTENCY_RECOVERY_REQUIRED`였다. 효과 불명으로 포기한 기록은 같은 attempt에도 `RecoveryRequired`(PostgreSQL은 전에 `ReplayedAcquire`). Redis는 이미 실행 중인 기록에 같은 attempt의 다른 핸들(넘겨받기 전 핸들, 재생받은 현재 핸들)로 온 시작을 `ALREADY_STARTED_SAME_OPERATION`으로 확인하지 않는다 — 전에는 executor가 작업을 한 번 더 돌렸다(PostgreSQL은 전부터 거절). in-memory fake는 재시도 가능 실패 기록에 다른 요청 본문이 오면 넘겨주지 않고 `FingerprintMismatch` | attempt를 재시도 사이에 들고 있다가 503 뒤 같은 attempt로 다시 부르는 호출자(재시도 래퍼, 메시지 소비자)가 이제 실행된다. 요청마다 새 attempt를 만드는 호출자(템플릿의 HTTP 경로)는 바뀌는 것이 없다. 같은 attempt를 두 호출이 동시에 쓰는 것은 여전히 가려내지 못한다 — 재시도는 앞 호출이 돌아온 뒤에. 직접 구현한 store는 `IdempotencyStoreContract`의 새 케이스로 확인한다 | r10(라운드6 RR6-02-01) · `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java`, `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `InMemoryIdempotencyStore.java` |
| 멱등성(전이의 operation id·release·inspect, 2026-11-06) | owner token이 같아도 호출이 claim과 다른 operation id를 대면 PostgreSQL·in-memory fake도 다섯 전이(start·renew·complete·fail·release)를 `OPERATION_CONFLICT`로 거절하고 기록을 바꾸지 않는다(전에는 적용했다. Redis는 전부터 거절). in-memory fake의 claim은 같은 token·다른 operation에 `OwnerOperationConflict`(전에는 `InProgress`), inspect는 `OPERATION_CONFLICT`(전에는 `IN_PROGRESS_OTHER`). PostgreSQL·fake의 inspect는 완료된 기록에도 `OPERATION_CONFLICT`(전에는 응답을 재생). PostgreSQL complete는 같은 operation id를 쓴 다른 attempt에 `NOT_OWNER`(전에는 `ALREADY_COMPLETED_SAME_RESULT`). Redis release는 기록이 없으면 `ABSENT`(전에는 `ALREADY_RELEASED_SAME_OPERATION`)이고 핸들 revision을 본다: 같은 attempt가 넘겨받기 전 핸들로 release하면 `NOT_OWNER`(전에는 지금의 claim을 지웠다) | 템플릿의 호출자(`IdempotencyExecutor`)는 늘 claim의 operation id를 넘기고 release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접 부르며 전이마다 다른 operation id를 넘기던 코드는 이제 `OPERATION_CONFLICT`를 받는다 — `IdempotencyOwner.claimOperationId()`를 넘긴다. Redis release의 `ALREADY_RELEASED_SAME_OPERATION`을 기다리던 코드는 `ABSENT`도 "해제됨"으로 읽는다. 직접 구현한 store는 `IdempotencyStoreContract`의 새 케이스로 확인한다 | 2026-11-06(소유자 결정 "(a)로 진행", 라운드6 02 Declined) · `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java`, `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `RedisIdempotencyStoreAdapter.java`, `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `InMemoryIdempotencyStore.java` |
| 멱등성(이미 적용된 전이의 재전송, 2026-11-06·11-07) | 이미 적용된 전이를 "이미 처리됨"으로 확인받는 것은 그 전이를 적용한 핸들(기록보다 revision이 하나 낮고 기록의 마지막 전이가 그 전이인 핸들)뿐이다. 같은 attempt가 넘겨받기 전 핸들로, 넘겨받은 뒤 적용된 complete·markFailed를 다시 보내면 `NOT_OWNER`(전에는 Redis가 `ALREADY_COMPLETED_SAME_RESULT`·`ALREADY_MARKED_SAME_OPERATION`, PostgreSQL이 `ALREADY_COMPLETED_SAME_RESULT`·`OPERATION_CONFLICT`). PostgreSQL은 renew가 돌려준 핸들로 다시 renew하면 한 번 더 renew한다(전에는 `OPERATION_CONFLICT`). 넘겨받기 전 핸들의 renew는 `NOT_OWNER`, release는 `NOT_OWNER`(전에는 둘 다 `OPERATION_CONFLICT`). in-memory fake는 적용한 핸들이 start·renew·markFailed를 다시 보내면 `ALREADY_STARTED_SAME_OPERATION`·`ALREADY_RENEWED_SAME_OPERATION`(다른 lease면 `OPERATION_CONFLICT`)·`ALREADY_MARKED_SAME_OPERATION`(전에는 `NOT_OWNER`). release한 핸들로 start하면 PostgreSQL은 `NOT_OWNER`, Redis·fake는 `ABSENT`이고 계약은 둘 다 받는다(동작 변경 없음, Javadoc만). Redis는 renew를 적용한 핸들로 start하면 `NOT_OWNER`(전에는 `ALREADY_STARTED_SAME_OPERATION`). 적용한 핸들이 markFailed를 다른 disposition으로 다시 보내면 셋 다 `OPERATION_CONFLICT`이고 기록된 실패는 그대로다(전에는 셋 다 `NOT_OWNER`). retention만 다르면 셋 다 `ALREADY_MARKED_SAME_OPERATION`이고 처음 retention이 남는다(전에는 PostgreSQL만 `OPERATION_CONFLICT`) | 템플릿의 호출자(`IdempotencyExecutor`)는 넘겨받기 전 핸들로 다시 보내지 않고 renew·release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접 부르며 heartbeat로 renew를 이어 부르는 코드는 PostgreSQL에서 두 번째 renew부터 거절당하던 것이 이제 된다. 직접 구현한 store는 `IdempotencyStoreContract`의 새 케이스로 확인한다. fake로 lost reply를 흉내 내던 테스트는 이제 "이미 처리됨"을 받는다. Redis 기록 hash에 `lastKind` 필드가 생긴다(claim·renew·전이 프로그램이 쓴다) | 2026-11-06(소유자 결정 「넘겨받기 전 핸들의 재전송」「해제된 핸들로 start」) · 2026-11-07(소유자 결정 「적용한 핸들의 markFailed 재전송 인자」, 재리뷰 round8 RR8-04-01·02) · `src/adapter/outbound/cache-redis/.../idempotency/IdempotencyScripts.java`, `src/adapter/outbound/persistence-jpa/.../postgresql/PostgreSqlIdempotencyStore.java`, `src/application-core/src/testFixtures/.../IdempotencyStoreContract.java`, `InMemoryIdempotencyStore.java`, `IdempotencyStartOutcome.java`, `IdempotencyFailOutcome.java` |
| 빌드 단계(HTTP client) | `httpClientFailureInjectionTest`(Toxiproxy 장애 주입)가 `mainCheck`에서 빠졌다. `integrationCheck`에만 있고, main push·nightly의 `integration-main.yml` `integration-check` job이 돌린다 | main push마다 같은 lane이 `main-check`·`integration-check` 두 job에서 두 번 돌던 것이 한 번이 된다. 로컬에서 `mainCheck`만 돌리면 이 lane은 돌지 않는다(`integrationCheck`로 돌린다) | r9 · `src/adapter/outbound/httpclient/build.gradle` |
| 서버 로그(GraphQL·gRPC·STOMP) | carrier로 답한 실패를 web과 같은 줄(shared-contract `ServerFailureLog`)로 ERROR에 남긴다: persistence 실패는 분류만, 5xx carrier는 예외와 함께, 4xx carrier는 남기지 않는다. gRPC는 ` (method=…)`, GraphQL은 ` (executionId=…)`를 붙인다. gRPC는 인식 못 한 실패(`INTERNAL_ERROR`)도 `unhandled failure on <method> …`로 남긴다. 클라이언트가 취소한 호출은 남기지 않고, 서비스가 `CANCELLED` status로 끝낸 살아 있는 호출은 남긴다. raw status는 넘겼든 던졌든 설명을 남기지 않는다(원인 예외가 있으면 그것만 붙인다). `IllegalArgumentException`(`BAD_PARAMETER`)은 web과 같은 WARN 한 줄 `request refused as BAD_PARAMETER by <예외 타입>`(메시지 없음)으로 남긴다. STOMP `@MessageMapping` 실패는 Spring의 `Unhandled exception from message handler method`(예외 전체) 대신 같은 줄로 남는다 | ERROR 로그가 늘어난다(전에는 gRPC가 아무것도 남기지 않았다). GraphQL·gRPC·STOMP는 잘못된 입력마다 WARN 한 줄이 생긴다. STOMP에서 Spring 문구로 경보를 걸었다면 고친다. `IDEMPOTENCY_RECOVERY_REQUIRED`의 scope digest를 모든 전송에서 찾을 수 있다(`docs/runbooks/idempotency-unavailable.md`) | r9 · `src/shared-contract/.../error/ServerFailureLog.java`, `GrpcExceptionHandlingInterceptor.java`, `GraphQlWireErrorMapper.java`, `StompHandlerFailureLog.java` |
| 서버 로그(STOMP 거부·감싼 carrier, 2026-11-07) | `@MessageMapping` 앞에서 Spring이 거부한 메시지를 WARN 한 줄 `request refused as <code> by <예외 타입>`으로 남긴다: 읽지 못한 payload(`MessageConversionException`)·비었거나 검증에 걸린 payload(`MethodArgumentNotValidException`)는 `VALIDATION_FAILED`, 변환되지 않는 `@DestinationVariable`·`@Header`(`ConversionFailedException`)는 `BAD_PARAMETER`. 전에는 ERROR에 예외 메시지(받은 JSON 조각·값)까지 남겼다. 응답을 쓰지 못한 변환 실패는 그대로 ERROR. 네 전송 모두 감싼 carrier를 그 carrier 줄로 남긴다(감싼 persistence 실패는 분류만, SQL 원인 없음) | ERROR 경보가 클라이언트의 잘못된 메시지에 울리지 않는다. 그 실패를 찾던 로그 검색은 WARN으로 바꾼다 | r8-f1(재리뷰 RR7-01-06·RR7-01-05) · `src/adapter/inbound/websocket/.../stomp/StompHandlerFailureLog.java`, `src/shared-contract/.../error/ServerFailureLog.java` `refused` |
| sample-portfolio | **샘플 삭제(B-49)로 템플릿에서 사라졌다.** 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` |
| Flyway 잠금 | Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션 대신 세션에 둔다. Spring Boot의 Flyway는 module-defaults `spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway(멱등성·알림·sample stream, schema-per-tenant, testkit `MigrationContractRunner`)는 `FlywaySchemaPolicy.configure()`, messaging inbox stream은 같은 값을 직접 넣는다. 운영 코드의 `Flyway.configure()` 직접 호출과 설정 객체 직접 생성(`new FluentConfiguration()`·`new ClassicConfiguration()`·그 하위 클래스, round7 RR7-03-06)은 `JpaProductionArchitectureTest`가 거부한다 | Flyway 기본값에서는 동시 인덱스 마이그레이션이 Flyway 자신의 열린 트랜잭션을 기다려 끝나지 않았다. 이제 끝난다. 마이그레이션은 잠금을 잡은 연결 하나로 돈다. transaction 모드 PgBouncer 뒤에서는 잠금 해제가 다른 서버 연결로 가 다음 배포가 기다릴 수 있으니 마이그레이션은 직접 연결이나 session 모드 pool로 돌린다. 배포 도구는 이 repo 밖이라 2절 15번으로 맞춘다 | 재리뷰 round6 RR6-03-01 · `persistence-jpa.yml`, `.../migration/FlywaySchemaPolicy.java`, `docs/jpa/migration-guide.md` "Who may change the schema"·"Concurrent index builds" |
| 실패한 동시 인덱스 마이그레이션 복구 | `docs/runbooks/migration-failed.md`에 「Recover a failed concurrent index migration」을 더했다: 진행 중인 빌드가 없는지 보고, 원인(중복 행, 문장을 붙잡던 열린 트랜잭션)을 정리하고, 실패한 빌드·재빌드가 남긴 무효 인덱스를 `DROP INDEX CONCURRENTLY`로 지우고, 그 버전의 실패 이력 행(`success = false`)만 지운 뒤 다시 배포한다. 실패한 문장이 `DROP INDEX CONCURRENTLY`면 남은 무효 인덱스는 지우지 않는다. 그 마이그레이션이 지우려던 인덱스라 다시 배포한 같은 문장이 지운다. 「Do not」의 이력 수정 금지에 이 한 가지 예외를 적었다. `flyway repair`는 계속 쓰지 않는다 | 전에는 안내가 "`DROP INDEX` 하나"였고, 그대로 하면 남은 실패 이력 때문에 다음 배포가 validate에서 다시 멈췄다. 실패한 drop의 인덱스를 손으로 지우면 다시 배포한 문장이 `42704`(없는 인덱스)로 또 실패한다. 동시 인덱스 마이그레이션을 쓰는 서비스의 운영자는 이 절차로 복구한다 | 재리뷰 round7 RR7-03-03, round8 RR8-03-01, 소유자 결정 2026-11-06 · `docs/jpa/migration-guide.md` "Concurrent index builds", `PostgreSqlConcurrentIndexMigrationIntegrationTest` |
| 성능 lane(HTTP client·Mongo) | httpclient `LargeBodyResourceTest`의 힙 상한(32 MiB 스트리밍 중 힙 증가 16 MiB 미만)을 매번 단언한다. 전에는 `-Pperformance.assertions.enabled=true`일 때만 단언하고 아니면 건너뛴다는 줄만 찍었다. Mongo `MongoResourceBudgetLaneTest`는 표준 gate 전체(p99 500ms, pool 대기 250ms, 힙 512 MiB, examined/returned 10, spill 금지)를 Gradle 밖 실행에서도 단언한다(B-43) | 손으로 돌린 `performanceCheck`가 상한을 실제로 재므로, 전에는 통과하던 느린 기계에서 실패할 수 있다 | B4(2026-11-06) · `LargeBodyResourceTest`, `MongoResourceBudgetLaneTest` |
| 보안 필터 로그 레벨 | 보안 필터(`AuthErrorResponseWriter`)의 `security failure` 줄을 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)면 ERROR, 4xx면 WARN으로 남긴다. 전에는 모두 WARN이었다. 다른 경로가 5xx를 ERROR로 남기는 규칙(`ServerFailureLog`)과 같아졌다 | ERROR로 거르는 로그 경보·대시보드에 JWKS 장애와 인증 설정 오류가 새로 잡힌다. 401·403은 그대로 WARN | 설계 메모 2026-11-06 7절 결정 2 · `src/adapter/inbound/web/.../auth/AuthErrorResponseWriter.java`, `docs/design/2026-11-06-error-code-log-level-design.md` |
## 6. 따라오는 순서
모든 명령은 `src/`에서 `--console=plain`으로 돌린다. 한 단계가 빨개지면 다음으로 가지 않는다.
| 단계 | 할 일 | 게이트 |
|---|---|---|
| 0. 준비 | 운영·스테이징 DB 백업. 작업 브랜치를 따로 만든다. 자기 마이그레이션 번호가 4.1절 번호와 겹치는지 본다. 운영 DB 사본에 4.3절 Step 1 쿼리를 돌려 둔다 | — |
| 1. merge·의존성 | `git fetch upstream` 후 merge. 충돌 예상 파일: `config/architecture/modules.json`, `app-bootstrap/build.gradle`, `docs/registries/env-keys.yaml`, `.env.example`, `application*.yml`, API surface 스냅샷, `gradle.lockfile`. 자기 의존성을 바꿨으면 `./gradlew :<leaf>:resolveAndLockAll --write-locks` | `./gradlew verifyDependencyLocks` |
| 2. 컴파일·아키텍처 | 3.1절(B-01~B-11) 고치기. 3.4절 규칙 위반 고치기 | `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, 고친 leaf마다 `./gradlew <gradle-path>:check` |
| 3. PR 게이트 전체 | 자기 strict lane을 단계에 건다. SpotBugs MEDIUM 발견 처리 | `./gradlew ci`, `./gradlew verifyStrictLaneStages --dry-run` |
| 4. 설정 | 2절 체크리스트 1~4·10·13. 3.2절(B-12~B-27) 확인 | `./gradlew :app-bootstrap:verifyEnvKeys`, `./gradlew configContractCheck` |
| 5. DB | 이전 V21을 적용한 개발 DB 재생성(4.2절). 스테이징에 4.3절 절차 후 마이그레이션 | `./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck`(Docker 필요), 알림을 쓰면 `./gradlew integrationCheck` |
| 6. 기동 | prod와 같은 프로필·환경으로 스테이징 기동. exit 코드 70·71·72·78이면 3.2절·4절 해당 줄로 | `./gradlew :app-bootstrap:systemTest`, `./gradlew mainCheck` |
| 7. 계약 | HTTP 응답 모양·코드(3.3절)를 클라이언트와 맞춘다. 공개 경로가 바뀌었는지 확인 | `./gradlew verifyPublicPathSnapshot`, `./gradlew mainCheck`(문서 계약 lane 포함), 짝 프론트 계약 테스트 |
## 7. 짝 프론트
프론트가 맞출 계약의 정본은 `docs/web/http-contract.md`다. 요약:
**Envelope**
| 응답 | 있는 키 | 없는 키 |
|---|---|---|
| 성공 | `success`(true), `data`, `meta` | `error` |
| 실패 | `success`(false), `error`, `meta` | `data` |
| bulk 전체 성공 | `success`(true), `results`, `meta` | `error` |
| bulk 부분 실패 | `success`(false), `error`(`BATCH_PARTIAL_FAILURE`, `details`), `meta` | `results` |
- `success`로 가른다. 키 존재로 판단하지 않는다. `null`이면 키가 없고, 빈 목록은 `[]`로 온다.
- `error`는 `code`·`category`·`message`·`retryable`이 항상 있고 `details`는 있을 때만.
- `meta`의 모르는 키는 무시한다. 요청 id 필터 전에 끊긴 응답은 id 키가 빠질 수 있다.
**멱등성** (같은 `Idempotency-Key` 재전송에 대한 서버 판정)
| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |
|---|---|---|---|---|---|
| 재생 | 첫 요청의 성공 status | — | — | — | 첫 결과로 받는다 |
| 처리 중 | 409 | `IDEMPOTENT_IN_FLIGHT` | true | 2 | 같은 키로 `Retry-After` 뒤 재전송. 새 키 금지 |
| 본문 불일치 | 422 | `IDEMPOTENT_REQUEST_MISMATCH` | false | — | 다시 보내지 않는다 |
| 키 누락·형식 오류 | 400 | `IDEMPOTENCY_KEY_INVALID`(`details.reason`) | false | — | 보이는 ASCII 1~256자 키로 다시 |
| 실행 전 거부: 저장소 응답 없음, 또는 claim의 processing lease가 시작 전에 끝나 저장소가 시작을 거절함 | 503 | `IDEMPOTENCY_UNAVAILABLE` | true | — | 실행 안 됨. 같은 키로 나중에(다음 요청이 그 claim을 넘겨받아 실행한다) |
| 실행 뒤 기록 실패(결과 불명) | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | true | — | 같은 키로 나중에. 새 키 금지 |
| 이전 효과 증명 불가 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | false | — | 업무 데이터로 확인 |
- CORS가 켜져 있으면 `Retry-After`·`X-Request-Id`·`X-Correlation-Id`·`traceparent` 등이 `Access-Control-Expose-Headers`에 있다(§3).
- 새 코드: `REQUEST_TIMEOUT`(503, retryable), web-advanced를 쓰는 서비스는 10종(3.3절 B-32).
- 분산 락 timeout은 409 `LOCK_ACQUISITION_TIMEOUT`(retryable, `Retry-After: 1`)이다. 전에는 500 `INTERNAL_ERROR`였다(3.3절 B-45).
- DB 일시 실패 넷(`DB_UNAVAILABLE` 등)에 레지스트리 값대로 `Retry-After`가 붙는다(3.3절 B-47). GraphQL `@Argument` 값이 타입에 맞지 않으면 `BAD_PARAMETER`다(B-48).
- 프론트 계약 문서(`clean-architecture-frontend-template` `docs/architecture/backend-api-and-server-state-contract.md` §4.1·§6)는
`docs/web/http-contract.md`를 가리켜야 한다.
- 프론트 세션에 넘긴 인계 문서(세션 scratchpad라 지워질 수 있음):
`/tmp/claude-1000/-home-donghyeon-workspace-desktop-server-git-clean-architecture-frontend-template/4cfb2000-88f4-4501-87c2-64e07e1575a5/scratchpad/backend-contract-handoff.md`
## 8. 소유자 확인이 남은 결정
재리뷰 README 8절은 아래를 "소유자 확인이 필요한 결정"으로 남겼다. main에 합쳐지기 전에 바뀔 수 있다.
- 서블릿 오류 디스패치 허용(B-31), 데모 계정 허용 목록(B-27), V21을 V22 없이 직접 수정(4.2절), 발행·저장소 포트 시그니처 변경
(B-01·B-02), `IDEMPOTENCY_COMPLETION_UNKNOWN` 신설(B-30), prod `fixture-` 값 거부(B-14).
## 9. 확인 못 한 것
- 실제 파생 서비스(예: `tech-log-backend`) 코드에 이 안내를 적용해 보지 않았다. 각 줄이 그 서비스에 해당하는지는 서비스 쪽에서 확인한다.
- `APP_SECURITY_JWT_AUDIENCE` 누락·`app.security` 오타의 정확한 exit 코드와 메시지 전문(바인딩 예외로 감싸지는 경로).
- H2를 `bootRunH2` 밖에서 쓸 때의 정확한 오류(B-23).
- 같은 순서 키를 두 번 append할 때 나가는 오류 코드(5절 "순서 번호").
- 옛 버전 앱이 V20~V22가 적용된 DB에서 기동하는지(4.4절).
- gRPC ledger stream의 history 표 이름과 누가 적용하는지.
- 실제 CI runner에서의 workflow 실행(재리뷰 README 8절과 같음).