메시징 플랫폼 분리(PR #8)를 받는다. 충돌 둘: 옛 integration-main.yml은 이 브랜치가 지웠으므로 삭제를 둔다(메시징 측정 주석은 main.yml에 옮길 측정 수치가 없어 버린다). 업그레이드 안내는 메시징 절을 3.9(B-57~B-59)로 두고 CI 절을 3.10(B-60~B-66)으로 미룬다.
119 KiB
업그레이드 안내 — 2026-11 성숙도 리뷰 수정
- 범위:
01a8a2a70..refactor/maturity-review-2026-11(main → 이 브랜치) - 커밋:
34565130High·P1 19건 ·1400dc15남은 발견·매뉴얼·생성 명령 ·5786126c남은 항목과 합친 뒤 결함 ·7ef8d0b4재리뷰 기록 ·bbe944bd재리뷰 결함 ·ecc74b7d2차 재리뷰 기록·이 안내 ·1885bf8d2차 재리뷰 결함 ·339cf8fd3차 확인 리뷰 기록 ·f40c03c63차 확인 리뷰 Minor ·c2e55510마지막 확인 리뷰 기록 ·2678955c테스트 코드 정적 분석(B-40) ·70fb80bf소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록,failure-retention기동 검사, workflowcd) · B4 성능 lane 단언 상시화(2026-11-06, B-43) ·paths필터 trigger를 단계 실행으로 세지 않음(2026-11-06 소유자 결정, B-36) · r8-f1 전송 오류 처리(2026-11-07, B-45B-48) · r9-g1 GraphQL 판정 순서와 인자 변환 단계(2026-11-07 소유자 결정, B-45·B-46) · 태그 push·) —releaseworkflow는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-49docs(...)커밋은 문서만 바꾼다 - 근거 문서:
docs/reviews/2026-11-01-maturity-review/README.md1316절,13절, 각 커밋의docs/reviews/2026-11-03-rereview/README.md4·6·8BREAKING 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, ` |
· |
|
| 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'를 둔다. 실패하면 SQLState55P03이고, 열린 트랜잭션을 끝낸 뒤 다시 배포한다 (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 V11V13, 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이다.
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을 따른다. 요약:
- Step 1 — 중복 확인(읽기 전용): §8의
v21-duplicate-order-keys쿼리. 0행이면 배포한다. - Step 2: 미발행 행이 있는 키는 relay가 비울 때까지 기다린다.
DEAD행은 §4 처분을 먼저 한다. - Step 3: 모두
PUBLISHED인 키의 중복을outbox_event_v21_duplicates로 복사한 뒤 지운다(v21-remove-published-duplicates). - 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부터. - 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.mdEscalation에 따라 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 |
./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)이다. 전에는 500INTERNAL_ERROR였다(3.3절 B-45). - DB 일시 실패 넷(
DB_UNAVAILABLE등)에 레지스트리 값대로Retry-After가 붙는다(3.3절 B-47). GraphQL@Argument값이 타입에 맞지 않으면BAD_PARAMETER다(B-48). - 프론트 계약 문서(
clean-architecture-frontend-templatedocs/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), prodfixture-값 거부(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절과 같음).