From e3ebc25ef43c3fc034f0a9c4acaf8fccc7792f6c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 08:07:42 +0900 Subject: [PATCH] =?UTF-8?q?refactor(persistence-jpa):=20runbook=20SQL=20?= =?UTF-8?q?=EB=A6=AC=EB=8D=94=20=EC=9D=B4=EB=A6=84=EC=9D=84=20RunbookSql?= =?UTF-8?q?=EB=A1=9C=20=EB=B0=94=EA=BE=BC=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 (재리뷰 round8 RR8-03-03) - runbook에서 runbook-sql 블록을 읽는 IT 도우미의 이름이 OutboxRunbookSql이다. round7 수정 뒤로 마이그레이션 runbook (migration-failed.md)도 이 클래스로 읽는다. 다음 runbook의 SQL을 lane으로 돌리려는 사람이 이름을 보고 공용 리더를 찾지 못해 사본을 만들 수 있다. 고른 방법 - 리뷰 권장안대로 RunbookSql로 이름을 바꾸고 사용처 세 클래스(같은 postgresqlIntegrationTest source set)를 따라 고친다. 클래스 Javadoc에 모든 runbook lane이 이 리더 하나를 쓴다고 적는다. 동작은 바꾸지 않는다. 위험·한계 - 같은 source set 안의 package-private 클래스라 밖에서 쓰는 곳이 없다. 리뷰 기록(docs/reviews/**)의 옛 이름은 그때의 기록이라 두었다. - RED 없음 — 이름 문제다. 사용처 lane 셋이 그대로 통과하는 것으로 본다. 검증 (desktop, 이 커밋의 트리 328f6012, --no-build-cache, 로그 ~/r9-g3-logs/) - :adapter:outbound:persistence-jpa:check rc=0, test 666건 실패·skip 0 - postgresqlConcurrentIndexMigrationIntegrationTest rc=0, 7건 - postgresqlOutboxOrderKeyRunbookIntegrationTest rc=0, 10건 - postgresqlOutboxDispositionRunbookIntegrationTest rc=0, 8건 - 네 명령 모두 FROM-CACHE 0, 테스트 태스크 실행됨(UP-TO-DATE 아님) Refs: docs/reviews/2026-11-03-rereview/round8/03-migration.md RR8-03-03 Fixes: 6ec0c4f7fa0d ("fix(migration): 실패한 동시 인덱스 마이그레이션 복구와 검사기 설명을 실제 동작에 맞춘다") --- ...SqlConcurrentIndexMigrationIntegrationTest.java | 2 +- ...SqlOutboxDispositionRunbookIntegrationTest.java | 8 ++++---- ...greSqlOutboxOrderKeyRunbookIntegrationTest.java | 4 ++-- .../{OutboxRunbookSql.java => RunbookSql.java} | 14 ++++++++------ 4 files changed, 15 insertions(+), 13 deletions(-) rename src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/{OutboxRunbookSql.java => RunbookSql.java} (83%) diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlConcurrentIndexMigrationIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlConcurrentIndexMigrationIntegrationTest.java index 33b1a78f..5b7fc33d 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlConcurrentIndexMigrationIntegrationTest.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlConcurrentIndexMigrationIntegrationTest.java @@ -206,7 +206,7 @@ class PostgreSqlConcurrentIndexMigrationIntegrationTest { "실패한 동시 인덱스 마이그레이션은 runbook 절차(빌드 확인, 무효 인덱스 삭제, 원인 정리, 그 버전의 실패 이력 행 삭제) 뒤 다시 배포하면 적용된다") void aFailedConcurrentIndexMigrationIsRecoveredByTheRunbookProcedure(@TempDir Path stream) throws Exception { - OutboxRunbookSql runbook = OutboxRunbookSql.fromSystemProperty(MIGRATION_FAILED_RUNBOOK); + RunbookSql runbook = RunbookSql.fromSystemProperty(MIGRATION_FAILED_RUNBOOK); try (HikariDataSource database = postgres.createDatabase(databaseName())) { // given Files.writeString(stream.resolve("V1__probe.sql"), FIRST_RELEASE + DUPLICATE_NOTE); diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxDispositionRunbookIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxDispositionRunbookIntegrationTest.java index d5b7f9f9..bcf1ace4 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxDispositionRunbookIntegrationTest.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxDispositionRunbookIntegrationTest.java @@ -41,13 +41,13 @@ class PostgreSqlOutboxDispositionRunbookIntegrationTest { private static final Duration IN_FLIGHT_TIMEOUT = Duration.ofMinutes(5); private static PostgreSqlReadinessSupport postgres; - private static OutboxRunbookSql deadLetterRunbook; - private static OutboxRunbookSql publishFailedRunbook; + private static RunbookSql deadLetterRunbook; + private static RunbookSql publishFailedRunbook; @BeforeAll static void setup() throws IOException { - deadLetterRunbook = OutboxRunbookSql.fromSystemProperty("outbox.runbook"); - publishFailedRunbook = OutboxRunbookSql.fromSystemProperty("outbox.publish-failed.runbook"); + deadLetterRunbook = RunbookSql.fromSystemProperty("outbox.runbook"); + publishFailedRunbook = RunbookSql.fromSystemProperty("outbox.publish-failed.runbook"); postgres = PostgreSqlReadinessSupport.start(); } diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxOrderKeyRunbookIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxOrderKeyRunbookIntegrationTest.java index 09a8381c..94f7a156 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxOrderKeyRunbookIntegrationTest.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxOrderKeyRunbookIntegrationTest.java @@ -47,13 +47,13 @@ class PostgreSqlOutboxOrderKeyRunbookIntegrationTest { private static final Instant OCCURRED = Instant.parse("2026-11-01T00:00:00Z"); private static PostgreSqlReadinessSupport postgres; - private static OutboxRunbookSql runbook; + private static RunbookSql runbook; private static String duplicateCheck; private static String removePublishedDuplicates; @BeforeAll static void setup() throws IOException { - runbook = OutboxRunbookSql.fromSystemProperty("outbox.runbook"); + runbook = RunbookSql.fromSystemProperty("outbox.runbook"); duplicateCheck = runbook.block("v21-duplicate-order-keys"); removePublishedDuplicates = runbook.block("v21-remove-published-duplicates"); postgres = PostgreSqlReadinessSupport.start(); diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/OutboxRunbookSql.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/RunbookSql.java similarity index 83% rename from src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/OutboxRunbookSql.java rename to src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/RunbookSql.java index 0d2556dc..ba1855cd 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/OutboxRunbookSql.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/RunbookSql.java @@ -7,19 +7,21 @@ import java.nio.file.Path; import java.util.Map; /** - * The SQL a runbook gives an operator, read out of the runbook itself: the outbox runbooks, and the - * migration runbook's recovery of a failed concurrent index migration. + * The SQL a runbook gives an operator, read out of the runbook itself. Every lane that runs a + * runbook's SQL reads it through this one class: so far the outbox runbooks and the migration + * runbook's recovery of a failed concurrent index migration (re-review 2026-11-03 round 8, + * RR8-03-03: the class kept an outbox name after the migration runbook began to use it). * *

A runbook block is marked {@code } and followed by a {@code sql} * fence. The lanes that run these blocks against real PostgreSQL read them from the document rather * than keep a copy, so editing a block in the runbook is what the lane tests: a copy would pass * while the document an operator follows is wrong. */ -final class OutboxRunbookSql { +final class RunbookSql { private final String runbook; - private OutboxRunbookSql(String runbook) { + private RunbookSql(String runbook) { this.runbook = runbook; } @@ -30,13 +32,13 @@ final class OutboxRunbookSql { * @return the runbook's SQL blocks * @throws IOException when the file cannot be read */ - static OutboxRunbookSql fromSystemProperty(String property) throws IOException { + static RunbookSql fromSystemProperty(String property) throws IOException { String path = System.getProperty(property); if (path == null || path.isBlank()) { throw new IllegalStateException( "system property " + property + " must name the runbook this lane runs"); } - return new OutboxRunbookSql(Files.readString(Path.of(path), StandardCharsets.UTF_8)); + return new RunbookSql(Files.readString(Path.of(path), StandardCharsets.UTF_8)); } /**