설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
565 lines
49 KiB
Markdown
565 lines
49 KiB
Markdown
# 부가 기능(capability) 모듈 포장 — 실행 계획
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 부가 기능을 "의존성을 붙이면 켜지고 떼면 사라지는 capability 모듈"로 바꾸고, 템플릿 기본 조립을 web만으로 줄인다. 그 전에 1차 리뷰 Critical을 고치고 리팩터링 잔재를 걷어낸다.
|
||
|
||
**Architecture:** 서비스 코드는 application-core 포트만 호출한다. 각 capability 모듈은 자기 `AutoConfiguration.imports`로 켜지고, `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 선택된다. bootstrap의 끄는 장치(MasterSwitch, import filter, scan 제외 정규식, 흩어진 validator)는 capability가 모듈 안으로 들어가는 만큼 삭제한다.
|
||
|
||
**Tech Stack:** Java 21, Spring Boot 4.0.8, Gradle 멀티모듈(registry `src/config/architecture/modules.json`), JUnit 5 + AssertJ + ArchUnit, Testcontainers(PostgreSQL 등), Flyway.
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md` (확정). 입력 리뷰: `docs/reviews/2026-09-24-src-module-code-review.md`(1차), `docs/reviews/2026-09-24-src-maintainability-review.md`(2차).
|
||
|
||
## Global Constraints
|
||
|
||
- 기본 조립 방식: **B — 서비스가 고른 capability만 `runtimeOnly` 한 줄** (spec 10절 1).
|
||
- 템플릿 기본 포함: web 인바운드 + 운영 관측 + 코어 + support/identifier. 나머지는 전부 기본 제외 (spec 10절 2).
|
||
- HARD-STOP 7개(`AGENTS.md`)는 모든 Wave에서 유지한다. 특히 5번: 모든 project 의존성은 `modules.json`의 `allowed_dependencies` 안에 있어야 한다.
|
||
- 커밋은 `human-only`. 에이전트는 stage/commit/amend/push 하지 않는다. Wave마다 `git diff` 스냅샷을 scratchpad에 남겨 추적한다.
|
||
- 이미 적용됐을 수 있는 Flyway versioned migration은 바이트를 바꾸지 않는다. 수정은 새 버전으로만 한다.
|
||
- 설정 키: 동작하지 않는 옵션은 설정 키 자체를 두지 않는다 (spec 6절 3).
|
||
- 문서에 leaf 개수를 적지 않는다 (registry가 SSOT).
|
||
- Gradle은 한 작업 트리에서 동시에 하나만 돌린다. 병렬 작업은 별도 복사본에서만 한다.
|
||
|
||
## Review Focus
|
||
|
||
사용자가 가장 먼저 부딪힐 입력·조건과 기대 동작. 각 줄의 테스트는 해당 Task에 넣는다.
|
||
|
||
1. **이미 V9/V13이 적용된 DB로 기동** → checksum mismatch 없이 기동해야 한다. (Task 0-5: 적용 파일 해시 고정 테스트 + 원복)
|
||
2. **Docker 빌드 컨텍스트(`src`만 있음)에서 Gradle 실행** → compose 파일이 없어도 설정 단계가 통과해야 한다. (Task 0-3: compose 파일 없는 루트에서 `help` 성공 테스트)
|
||
3. **`APP_MESSAGING_PRODUCER_ID`를 비워 둔 채 messaging 활성화** → bridge bean만 생기지 않고 기동은 성공해야 한다. (Task 0-7: 빈 값·공백 값 테스트)
|
||
4. **prod에서 `APP_SERVER_ERROR_INCLUDE_STACKTRACE=always` 같은 env override** → 기동이 exit 71로 실패해야 한다. 대소문자(`Prod`, `ALWAYS`)도 같다. (Task 0-8)
|
||
5. **capability 한 줄을 지운 빌드** → 그 기능의 bean·설정 바인딩·validator가 전부 사라지고 나머지는 그대로 기동해야 한다. (Wave 4 완료 기준 — 기본 조립 system test)
|
||
|
||
---
|
||
|
||
## 실행 방식
|
||
|
||
- Wave 0: 현재 세션에서 직접 실행(작고 서로 독립).
|
||
- Wave 1 이후: Wave마다 시작 시점에 이 문서 아래 "Wave N 상세 Task"를 추가한 뒤 실행한다(rolling-wave). 작업 단위 하나를 구현 subagent 하나에 맡기고, 끝나면 리뷰 subagent가 확인한다. Gradle 충돌을 피하려고 같은 작업 트리에서는 순차로 돌리고, 병렬이 필요하면 `rsync`로 만든 복사본에서 돌린 뒤 diff를 되가져온다.
|
||
- 매 Wave 종료 시: focused test + `./gradlew architectureCheck --console=plain` + (영향 범위에 따라) 통합 lane. Wave 종료 기록은 맨 아래 "진행 기록"에 남긴다.
|
||
|
||
## Wave 개요
|
||
|
||
| Wave | spec 9절 단계 | 내용 | 완료 기준 |
|
||
|---|---|---|---|
|
||
| 0 | 1, 2(Wave 0) | 규칙 고정(AGENTS.md) + 결정 불필요 차단 결함 7건 | 7건 각각 회귀 테스트 통과, architectureCheck 통과 |
|
||
| 1 | 2(Wave 1) | 데이터·보안 Critical 10건 | 10건 각각 회귀 테스트(가능하면 포트 계약 테스트) 통과 |
|
||
| 2 | 3 | 분류 3(잔재) 삭제, 분류 4(실험용 자리) 삭제 | 삭제 후 전체 leaf `check` + architectureCheck 통과 |
|
||
| 3 | D1(분류 2) | 분류 2(라이브러리형 API) — 완성해서 포장(동작하지 않는 약속 제거, web 라이브러리는 opt-in leaf로 분리) | 기준 3 위반 0, web 기본 leaf에 라이브러리 없음 |
|
||
| 4 | 4 | 분류 1 capability 포장 + 기본 조립 web-only + 끄는 장치 삭제 | spec 6절 완료 기준 7개를 capability마다 충족, 기본 조립 system test 통과 |
|
||
| 5 | 5 | 빌드 O3(바로 할 것 1–12 포함) + 테스트 컨벤션(sample부터) | `ci` 통과, build-logic/build-tools 축소 |
|
||
|
||
---
|
||
|
||
## Wave 0 — 규칙 고정 + 결정 불필요 차단 결함
|
||
|
||
### Task 0-1: 결정 기록
|
||
|
||
**Files:**
|
||
- Modify: `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md` (상태, 10절)
|
||
|
||
- [x] **Step 1:** 10절을 "결정"으로 바꾸고 B안 확정, 기본 포함 목록(web만)과 해석 근거를 적는다.
|
||
|
||
### Task 0-2: capability 완료 기준과 테스트 컨벤션을 AGENTS.md에 고정
|
||
|
||
**Files:**
|
||
- Modify: `AGENTS.md` (새 절 "부가 기능(capability) 모듈 규칙", "테스트 전략"에 컨벤션)
|
||
- Modify: `CLAUDE.md` (Testing 절에 포인터, capability 규칙 한 줄 요약)
|
||
|
||
- [x] **Step 1: AGENTS.md에 capability 규칙 절 추가** — spec 6절 완료 기준 7개를 그대로 옮기고, 기본 조립 목록(spec 10절 2)과 "기능 추가 = `runtimeOnly` 한 줄 + env" 절차를 적는다. settings 규칙(prefix 하나, `StrictSettingsBinder`, compact constructor 검증)도 여기 둔다.
|
||
- [x] **Step 2: AGENTS.md "테스트 전략"에 컨벤션 6개 추가** — 2차 리뷰 TEST 절 "제안 컨벤션" 1–6(이름=행동 문장이고 이름이 약속한 성질을 단언, `@DisplayName` 선택·영어, GWT 주석은 본문 3문장 이상일 때 필수·`// when` 하나, `@Nested` 조건, 단언 규칙, 포트 fake는 포트 소유 모듈 testFixtures에 하나 + fake와 adapter가 같은 `XxxContract` 통과, Mockito는 프레임워크 경계만). 적용 범위: 새로 쓰거나 고치는 테스트. 주석 게이트는 만들지 않는다(이유 한 줄).
|
||
- [x] **Step 3: CLAUDE.md 동기화** — Testing 절 끝에 "테스트 작성 규칙과 capability 모듈 규칙은 `AGENTS.md`가 정본" 한 줄, capability 규칙 3줄 요약.
|
||
- [x] **Step 4: 확인** — `grep -n "capability" AGENTS.md CLAUDE.md`로 두 문서가 같은 7개 기준을 가리키는지 본다(요약과 정본이 어긋나지 않게).
|
||
|
||
### Task 0-3: O-1 — compose overlay 확인을 task 실행 시점으로
|
||
|
||
1차 Critical #1. `DeveloperBootstrapPlugin.apply()`가 compose overlay가 없으면 설정 단계에서 실패해, Docker 빌드 컨텍스트(`src`만 있음)에서 어떤 task도 못 돈다.
|
||
|
||
**Files:**
|
||
- Modify: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/bootstrap/DeveloperBootstrapPlugin.java:40-50`
|
||
- Test: `src/build-logic/src/test/java/dev/caskeleton/buildlogic/bootstrap/DeveloperBootstrapPluginFunctionalTest.java`
|
||
|
||
- [x] **Step 1: 실패하는 테스트 작성** — compose 파일이 하나도 없는 루트에서 `help`가 성공해야 한다. 기존 "없는 profile 거부" 테스트는 `tasks` 대신 `bootstrapDockerPreflight` 실행으로 바꾼다(거부는 task 실행 시점으로 옮겨진다).
|
||
|
||
```java
|
||
@Test
|
||
void configurationDoesNotRequireComposeFiles(@TempDir Path temporaryDirectory)
|
||
throws IOException {
|
||
// The Docker image build copies only src/ into the build context, so the repository root and
|
||
// its compose files do not exist there. Configuring the root project must still succeed.
|
||
Path projectDirectory = fixtureWithoutComposeFiles(temporaryDirectory);
|
||
|
||
BuildResult result = run(projectDirectory, "help");
|
||
|
||
assertThat(result.getOutput()).contains("BUILD SUCCESSFUL");
|
||
}
|
||
|
||
@Test
|
||
void aProfileWithNoOverlayIsRefusedAndTheMessageListsTheRealOnes(
|
||
@TempDir Path temporaryDirectory) throws IOException {
|
||
Path projectDirectory = fixture(temporaryDirectory);
|
||
|
||
BuildResult failure =
|
||
runAndFail(projectDirectory, "bootstrapDockerPreflight", "-PbootstrapProfile=staging");
|
||
|
||
assertThat(failure.getOutput())
|
||
.contains("names no overlay")
|
||
.contains("docker-compose.staging.yml")
|
||
.contains("[dev, local]");
|
||
}
|
||
```
|
||
|
||
`fixtureWithoutComposeFiles`는 `fixture`와 같되 `docker-compose*.yml`을 만들지 않는다(`fixture`가 이것을 호출한 뒤 compose 파일을 추가하도록 나눈다).
|
||
|
||
- [x] **Step 2: 실패 확인** — `cd src && ./gradlew :build-logic:test --tests '*DeveloperBootstrapPluginFunctionalTest' --console=plain` → `configurationDoesNotRequireComposeFiles` FAIL("names no overlay").
|
||
- [x] **Step 3: 구현** — `apply()`의 overlay 확인 블록을 지우고 `bootstrapDockerPreflight`에 `doFirst`로 옮긴다. 캡처하는 값은 `File`/`String`만(configuration cache 호환).
|
||
|
||
```java
|
||
task.doFirst(
|
||
ignored -> requireOverlay(overlay, bootstrapProfile, repositoryDirectory));
|
||
```
|
||
|
||
```java
|
||
private static void requireOverlay(File overlay, String profile, File repositoryDirectory) {
|
||
if (!overlay.isFile()) {
|
||
throw new GradleException(
|
||
"bootstrap: -P" + PROFILE_PROPERTY + "=" + profile + " names no overlay; expected "
|
||
+ overlay.getName() + " beside docker-compose.yml. Available: "
|
||
+ availableProfiles(repositoryDirectory));
|
||
}
|
||
}
|
||
```
|
||
|
||
- [x] **Step 4: 통과 확인** — Step 2 명령 → 5개 테스트 PASS.
|
||
|
||
### Task 0-4: O-2 — 항상 실패하는 `redis-sdk` CI job 삭제
|
||
|
||
1차 Critical #2. `--tests '*…'`의 따옴표가 word-split 뒤에도 남아 매칭 0 → 항상 실패, `release-gate`가 success 요구. 같은 테스트는 이미 `:shared-contract:test`로 `ci`에서 돈다.
|
||
|
||
**Files:**
|
||
- Modify: `.github/workflows/ci-quality-gates.yml` (`redis-sdk:` job 블록, `release-gate`의 `needs`·`REDIS_RESULT` 두 줄)
|
||
|
||
- [x] **Step 1:** `redis-sdk:` job 블록 전체와 `release-gate`의 `- redis-sdk`, `REDIS_RESULT: ...`, `"${REDIS_RESULT}" \` 줄을 지운다.
|
||
- [x] **Step 2: 확인** — `grep -n "redis-sdk\|REDIS_RESULT" .github/workflows/ci-quality-gates.yml` → 0건. `python3 -c "import yaml,sys; yaml.safe_load(open('.github/workflows/ci-quality-gates.yml'))"` → 오류 없음.
|
||
|
||
### Task 0-5: E-1 — 적용된 migration 원복 + 새 버전 + 해시 고정
|
||
|
||
1차 Critical #3. `postgresql/V9`, `postgresql/V13`이 적용 후 제자리 수정됐다(9da00eb7). 기본 Flyway location이라 이전 파일이 적용된 모든 DB가 checksum mismatch로 기동 실패한다.
|
||
|
||
범위 결정: 세 번째 파일 `jpa/outbox-storage/V1`은 어떤 composition도 location을 설정하지 않은 미조립 V2 outbox 세대다. Wave 2(D2)에서 그 세대를 migration 트리째 삭제하므로 여기서는 손대지 않는다.
|
||
|
||
**Files:**
|
||
- Restore: `src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V9__widen_capability_schema_stream.sql` (`9da00eb7^` 바이트)
|
||
- Restore: `.../postgresql/V13__outbox_canonical_transport_compatibility.sql` (`9da00eb7^` 바이트)
|
||
- Create: `.../postgresql/V16__outbox_canonical_hash_columns_varchar.sql`
|
||
- Create: `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`
|
||
- Create: `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/AppliedMigrationImmutabilityTest.java`
|
||
- Modify: `.../migration/PostgreSqlConstraintMigrationSafetyTest.java` (V13 NOT VALID 단언 → V16 varchar 단언)
|
||
|
||
- [x] **Step 1: 해시 고정 테스트 작성** — 매니페스트(`<sha256> <db/migration 기준 상대경로>`)에 있는 파일은 바이트가 같아야 하고, 디스크의 모든 `V*.sql`은 매니페스트에 있어야 한다. 줄 끝은 `\n`으로 정규화(CRLF checkout 오탐 방지).
|
||
|
||
```java
|
||
class AppliedMigrationImmutabilityTest {
|
||
|
||
private static final Path MIGRATIONS = Path.of("src/main/resources/db/migration");
|
||
private static final Path MANIFEST = Path.of("src/test/resources/db/applied-migrations.sha256");
|
||
|
||
@Test
|
||
void appliedMigrationsKeepTheBytesTheyWereAppliedWith() throws IOException {
|
||
// given
|
||
Map<String, String> pinned = pinnedChecksums();
|
||
|
||
// when
|
||
Map<String, String> actual = currentChecksums();
|
||
|
||
// then
|
||
assertThat(actual)
|
||
.as("an applied migration changed; add a new version instead of editing it")
|
||
.containsAllEntriesOf(pinned);
|
||
}
|
||
|
||
@Test
|
||
void everyVersionedMigrationIsPinned() throws IOException {
|
||
// given
|
||
Map<String, String> pinned = pinnedChecksums();
|
||
|
||
// when
|
||
Map<String, String> actual = currentChecksums();
|
||
|
||
// then
|
||
assertThat(pinned.keySet())
|
||
.as("pin a new migration in %s when it is added", MANIFEST)
|
||
.containsAll(actual.keySet());
|
||
}
|
||
// pinnedChecksums(): 매니페스트 파싱, currentChecksums(): Files.walk로 V*.sql 수집 후 정규화 SHA-256
|
||
}
|
||
```
|
||
|
||
- [x] **Step 2: 원복** — `git show 9da00eb7^:<path> > <path>`로 V9·V13을 되돌린다.
|
||
- [x] **Step 3: 매니페스트 생성** — 원복된 트리에서 모든 `V*.sql`의 정규화 SHA-256을 기록한다(원복 파일이 기준). V16은 Step 4 뒤에 추가.
|
||
- [x] **Step 4: V16 작성** — 9da00eb7이 V13에서 바꾼 `char(64)→varchar(64)`를 새 버전으로 옮긴다. 이미 varchar인 DB에서는 no-op.
|
||
|
||
```sql
|
||
-- V13 created the canonical hash columns as char(64). The JPA mapping is String(length = 64),
|
||
-- which Hibernate validates as varchar, so ddl-auto=validate rejected a database migrated through
|
||
-- V13. Every stored value is exactly 64 hex characters, so widening keeps the data unchanged; on a
|
||
-- database whose columns are already varchar(64) this is a no-op.
|
||
ALTER TABLE outbox_event
|
||
ALTER COLUMN partition_key TYPE varchar(64),
|
||
ALTER COLUMN schema_set_hash TYPE varchar(64),
|
||
ALTER COLUMN envelope_sha256 TYPE varchar(64),
|
||
ALTER COLUMN envelope_schema_hash TYPE varchar(64),
|
||
ALTER COLUMN payload_schema_hash TYPE varchar(64);
|
||
```
|
||
|
||
- [x] **Step 5: `PostgreSqlConstraintMigrationSafetyTest` 갱신** — V13 내용 단언(varchar, NOT VALID) 2개를 "V16이 다섯 컬럼을 varchar(64)로 바꾼다" 단언 하나로 교체. V14 단언은 유지.
|
||
- [x] **Step 6: 확인** — `./gradlew :adapter:outbound:persistence-jpa:test --console=plain` PASS. Docker lane: `./gradlew :adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests '*Migration*' --console=plain` PASS(실제 PostgreSQL에서 V1→V16 적용 + `ddl-auto=validate`).
|
||
- [x] **Step 7: 문서** — `docs/` migration 안내(기존 persistence-jpa README의 migration 절)에 "09-23~09-25 사이 새로 만든 개발 DB는 `flyway repair` 필요" 한 줄.
|
||
|
||
### Task 0-6: L-1 — outbox relay가 `@EnableScheduling` 없이 멈춤
|
||
|
||
1차 Critical #5. 앱 전체의 `@EnableScheduling`이 `idempotency.provider=jdbc` 조건부 `IdempotencyConfig`에만 있어, outbox relay가 다른 provider 조합에서 조용히 멈춘다.
|
||
|
||
**Files:**
|
||
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java`
|
||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfigTest.java`
|
||
|
||
- [x] **Step 1: 실패하는 테스트**
|
||
|
||
```java
|
||
@Test
|
||
void outboxCapabilityEnablesSchedulingWithoutTheJdbcIdempotencyProvider() {
|
||
// given
|
||
ApplicationContextRunner runner =
|
||
new ApplicationContextRunner()
|
||
.withConfiguration(AutoConfigurations.of(OutboxConfig.class))
|
||
.withPropertyValues(
|
||
"ca-skeleton.outbox.enabled=true", "ca-skeleton.outbox.relay-enabled=false");
|
||
|
||
// when & then
|
||
runner.run(
|
||
context ->
|
||
assertThat(context)
|
||
.hasBean(TaskManagementConfigUtils.SCHEDULED_ANNOTATION_PROCESSOR_BEAN_NAME));
|
||
}
|
||
```
|
||
|
||
- [x] **Step 2: 실패 확인** — `./gradlew :app-bootstrap:test --tests '*OutboxConfigTest' --console=plain` → FAIL.
|
||
- [x] **Step 3: 구현** — `OutboxConfig`에 `@EnableScheduling` 추가(이미 `ca-skeleton.outbox.enabled`로 gate됨).
|
||
- [x] **Step 4: 통과 확인** — Step 2 명령 PASS.
|
||
|
||
### Task 0-7: H-1 — messaging bridge 조립 순서 + 빈 producer-id
|
||
|
||
1차 Critical #6. (a) bridge auto-config에 `after` 지정이 없어 알파벳 순서상 platform보다 먼저 평가되고 `@ConditionalOnBean(EncodedMessagePublisher)`가 항상 false. (b) `producer-id: ${APP_MESSAGING_PRODUCER_ID:}`가 빈 문자열로 존재해 `@ConditionalOnProperty`를 통과 → `new ProducerId("")` 예외.
|
||
|
||
**Files:**
|
||
- Modify: `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java`
|
||
- Test: `src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingPlatformBridgeAutoConfigurationTest.java`
|
||
- Create (test): `src/adapter/outbound/messaging/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingPlatformRootAutoConfiguration.java` — 실제 starter 클래스와 같은 FQN의 테스트 대역. 이 leaf의 test classpath에는 starter가 없으므로 충돌하지 않는다. `EncodedMessagePublisher` bean 하나만 등록한다. 목적: Boot의 auto-config 정렬(`afterName`)을 실제로 거치게 해서 (a)를 재현.
|
||
|
||
- [x] **Step 1: 실패하는 테스트 2개**
|
||
|
||
```java
|
||
@Test
|
||
void bridgeIsAssembledAfterThePlatformRootThatProvidesThePublisher() {
|
||
// given
|
||
ApplicationContextRunner assembled =
|
||
new ApplicationContextRunner()
|
||
.withConfiguration(
|
||
AutoConfigurations.of(
|
||
MessagingBridgeRootAutoConfiguration.class,
|
||
dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration
|
||
.class))
|
||
.withBean(FailOpenDependencyLogger.class, FailOpenDependencyLogger::new)
|
||
.withPropertyValues(
|
||
"app.messaging.enabled=true", "app.messaging.producer-id=portfolio-service");
|
||
|
||
// when & then
|
||
assembled.run(
|
||
context -> assertThat(context).hasSingleBean(IntegrationEventPublishPort.class));
|
||
}
|
||
|
||
@ParameterizedTest
|
||
@ValueSource(strings = {"", " "})
|
||
void blankProducerIdLeavesTheBridgeOutWithoutFailingStartup(String producerId) {
|
||
runner
|
||
.withPropertyValues("app.messaging.producer-id=" + producerId)
|
||
.run(
|
||
context -> {
|
||
assertThat(context).hasNotFailed();
|
||
assertThat(context).doesNotHaveBean(IntegrationEventPublishPort.class);
|
||
});
|
||
}
|
||
```
|
||
|
||
- [x] **Step 2: 실패 확인** — `./gradlew :adapter:outbound:messaging:test --tests '*MessagingPlatformBridgeAutoConfigurationTest' --console=plain` → 두 테스트 FAIL.
|
||
- [x] **Step 3: 구현**
|
||
|
||
```java
|
||
@AutoConfiguration(
|
||
afterName = "dev.caskeleton.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration")
|
||
...
|
||
@Bean
|
||
@ConditionalOnBean(EncodedMessagePublisher.class)
|
||
@ConditionalOnMissingBean(IntegrationEventPublishPort.class)
|
||
@Conditional(ProducerIdConfigured.class)
|
||
public IntegrationEventPublishPort integrationEventPublishPort(...)
|
||
|
||
/** {@code producer-id} is always present as a key (the yml default is empty), so presence alone is not configuration. */
|
||
static final class ProducerIdConfigured extends SpringBootCondition {
|
||
@Override
|
||
public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeMetadata metadata) {
|
||
String producerId = context.getEnvironment().getProperty("app.messaging.producer-id");
|
||
return StringUtils.hasText(producerId)
|
||
? ConditionOutcome.match("app.messaging.producer-id is set")
|
||
: ConditionOutcome.noMatch("app.messaging.producer-id is blank");
|
||
}
|
||
}
|
||
```
|
||
|
||
- [x] **Step 4: 통과 확인** — Step 2 명령 PASS.
|
||
|
||
### Task 0-8: L-2 — prod 에러 상세 노출 차단을 실제 코드로
|
||
|
||
1차 L-2. `application-prod.yml`은 "`StartupSafetyValidator`가 error-detail 노출을 막는다"고 적지만 그 검사는 9da00eb7에서 지워졌다. `spring.web.error.include-*`는 env로 prod에서도 켜진다.
|
||
|
||
**Files:**
|
||
- Create: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/ErrorDetailExposureSafetyValidator.java`
|
||
- Modify: `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/RuntimeSafetyConfig.java` (bean 등록)
|
||
- Test: `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/ErrorDetailExposureSafetyValidatorTest.java`
|
||
- Modify(문서): `src/app-bootstrap/src/main/resources/application-prod.yml:13`, `src/app-bootstrap/README.md`(StartupSafetyValidator 절, RuntimeSafetySettings 절), `src/README.md`(Runtime safety 절)
|
||
|
||
- [x] **Step 1: 실패하는 테스트** — `JpaSchemaSafetyValidatorTest`와 같은 `ApplicationContextRunner` 모양.
|
||
|
||
```java
|
||
@ParameterizedTest
|
||
@CsvSource({
|
||
"spring.web.error.include-stacktrace, always, APP_SERVER_ERROR_INCLUDE_STACKTRACE",
|
||
"spring.web.error.include-stacktrace, ON_PARAM, APP_SERVER_ERROR_INCLUDE_STACKTRACE",
|
||
"spring.web.error.include-message, always, APP_SERVER_ERROR_INCLUDE_MESSAGE",
|
||
"spring.web.error.include-binding-errors, always, spring.web.error.include-binding-errors",
|
||
"spring.web.error.include-exception, true, spring.web.error.include-exception"
|
||
})
|
||
void prodRefusesToStartWhenErrorDetailsWouldReachClients(String key, String value, String named) {
|
||
runner
|
||
.withInitializer(context -> context.getEnvironment().setActiveProfiles("Prod"))
|
||
.withPropertyValues(key + "=" + value)
|
||
.run(
|
||
context -> {
|
||
assertThat(context).hasFailed();
|
||
assertThat(context.getStartupFailure())
|
||
.isInstanceOf(ProfileMismatchException.class)
|
||
.hasStackTraceContaining(named);
|
||
});
|
||
}
|
||
|
||
@Test
|
||
void prodStartsWhenEveryErrorDetailStaysHidden() { /* never/never/never/false → hasNotFailed */ }
|
||
|
||
@Test
|
||
void nonProdMayExposeErrorDetailsForDebugging() { /* local + always → hasNotFailed */ }
|
||
```
|
||
|
||
- [x] **Step 2: 실패 확인** — `./gradlew :app-bootstrap:test --tests '*ErrorDetailExposureSafetyValidatorTest' --console=plain` → 컴파일 실패(클래스 없음).
|
||
- [x] **Step 3: 구현** — `SmartInitializingSingleton`. prod 판정은 `RuntimeProfileSnapshot.from(environment).isProduction()`(기존 validator와 같음). 위반을 모아 `StartupFailures.profileMismatch(...)` 한 번(exit 71). 키→사용자에게 보여줄 env 이름 표: stacktrace→`APP_SERVER_ERROR_INCLUDE_STACKTRACE`, message→`APP_SERVER_ERROR_INCLUDE_MESSAGE`, binding-errors·exception→property 이름 그대로.
|
||
- [x] **Step 4: 등록** — `RuntimeSafetyConfig`에 `@Bean ErrorDetailExposureSafetyValidator`.
|
||
- [x] **Step 5: 통과 확인** — Step 2 명령 PASS.
|
||
- [x] **Step 6: 문서 4곳 정정** — 거짓 주장("StartupSafetyValidator가 막는다", "shipped 구현이 없다", "5종")을 새 validator 이름과 실제 검사 키로 바꾼다.
|
||
|
||
### Task 0-9: L-3 — sample actuator `loggers`를 읽기 전용으로
|
||
|
||
1차 L-3. sample은 `loggers`를 노출하고 모든 경로가 `permitAll`이라 인증 없이 로그 레벨을 바꿀 수 있다.
|
||
|
||
**Files:**
|
||
- Modify: `src/sample-portfolio/src/main/resources/application.yml` (`management.endpoint.loggers.access: read-only`)
|
||
- Test: sample의 기존 actuator/설정 테스트에 단언 추가, 없으면 `SampleActuatorLoggersAccessTest`(yml을 `YamlPropertySourceLoader`로 읽어 값 단언).
|
||
|
||
- [x] **Step 1: 실패하는 테스트** — `management.endpoint.loggers.access`가 `read-only`인지 단언.
|
||
- [x] **Step 2: 실패 확인** — `./gradlew :sample-portfolio:test --tests '*Loggers*' --console=plain` → FAIL.
|
||
- [x] **Step 3: 구현** — yml에 한 줄.
|
||
- [x] **Step 4: 통과 확인** — Step 2 명령 PASS.
|
||
|
||
### Wave 0 종료 검증
|
||
|
||
- [x] `cd src && ./gradlew :build-logic:test :adapter:outbound:persistence-jpa:test :adapter:outbound:messaging:test :app-bootstrap:test :sample-portfolio:test --console=plain`
|
||
- [x] `./gradlew architectureCheck --console=plain`
|
||
- [x] `./gradlew :adapter:outbound:persistence-jpa:postgresqlIntegrationTest --tests '*Migration*' --console=plain` (Docker)
|
||
- [x] `git diff > <scratchpad>/wave-0.patch`, 진행 기록 갱신
|
||
|
||
---
|
||
|
||
## Wave 1 — 데이터·보안 Critical 10건
|
||
|
||
각 항목은 "재현 테스트 먼저 → 수정 → 통과". fake가 결함을 숨긴 포트는 포트 소유 모듈 testFixtures에 추상 계약 테스트(`XxxContract`)를 만들고 fake와 실제 adapter가 둘 다 상속한다(spec 6절 5, 2차 리뷰 권고 순서 1). 상세 Task는 Wave 1 시작 때 이 절 아래에 추가한다.
|
||
|
||
| # | 결함 (1차 리뷰) | 위치 | 수정 방향 | 회귀 테스트 |
|
||
|---|---|---|---|---|
|
||
| 1-1 | #4 durable operation 재제출이 PG 25P02 | `persistence-jpa/.../operation/DurableOperationStoreAdapter.java:47-78` | native `INSERT … ON CONFLICT DO NOTHING` 후 0건이면 기존 row 조회(`JpaNotificationRequestStore` 방식) | `DurableOperationStoreContract`(application-core testFixtures) — in-memory fake + PG adapter(Testcontainers)가 같은 이중 submit 시나리오 통과 |
|
||
| 1-2 | #12 web이 operation 조회·취소 유스케이스를 대신 수행(HARD-STOP 4) | `web/.../operationasync/OperationQueryService.java` | application-core에 `GetDurableOperationUseCase`(Query), `CancelDurableOperationUseCase`(Command + `@UseCaseCapability`), owner·tenant 판정은 `ObjectAccessPolicy` 뒤로; web은 요청 컨텍스트 변환만 | use case 단위 테스트(fake store), web slice 테스트 |
|
||
| 1-3 | #7 outbox relay·DLQ·retry-topic이 인코딩된 메시지를 재인코딩 | `messaging-outbox-jdbc-postgresql/.../OutboxRelay.java:223-229`, `DefaultMessagePublisher.java:177` | 이미 인코딩된 `EncodedMessage`는 raw publish 경로로(재인코딩 없이 transport로) | relay → publisher 경로 테스트: 저장된 row가 PUBLISHED |
|
||
| 1-4 | #8 Kafka TLS/SASL 설정이 producer에 적용 안 됨 | `messaging-spring-boot-starter-kafka/.../KafkaMessagingAutoConfiguration.java:109-154` | `KafkaSecurityConfigurer`를 producer properties 생성에 실제로 적용 | producer config에 `security.protocol`/`sasl.*`/`ssl.*`가 들어가는지 단언 |
|
||
| 1-5 | #9 알림 recovery/replay가 트랜잭션 없이 `@Modifying` 실행 | `adapter/outbound/notification/.../LeaseRecoveryService.java:106` 외 3곳 | 행 단위 작업을 `TransactionPort.inWrite`로 감쌈 | PG lane에서 `recoverOnce`/`replayOnce` 실제 실행 |
|
||
| 1-6 | #10 SNS 서명 검증 우회(호스트, TopicArn, Timestamp) | `.../ses/SnsSignatureVerifier.java:99-109`, `SesProviderCallbackAssembler.java:19` | 호스트 `^sns\.[a-z0-9-]+\.amazonaws\.com(\.cn)?$`, SES callback 켜면 `allowed-topic-arns` 필수, 오래된 Timestamp 거부, 인증서 캐시 상한 | S3 버킷 URL·타 토픽·오래된 메시지 거부 테스트 |
|
||
| 1-7 | #11 tus `Upload-Checksum`을 누적 digest와, 커밋 후 비교 | `web-fileserver/.../tus/TusController.java:167-174` | append에 기대 checksum 전달, chunk digest를 커밋 전에 검증, 불일치 시 롤백·460 | 정상 checksum 2번째 chunk 성공 + 불일치 chunk가 offset을 올리지 않음(tus 계약 테스트, fake digest도 chunk 단위로) |
|
||
| 1-8 | #13 GraphQL 인가 단계 fragment 재귀 전개 무제한 | `graphql/.../runtime/GraphQlDocumentAuthorizationHandler.java:109-137` | 방문 budget(노드 수 상한) + fragment 전개 memo, 초과 시 거부 | 1.6KB 중첩 fragment 문서가 제한 시간 안에 거부 |
|
||
| 1-9 | #14 Redis SCRIPT lane 한도가 동시 lease 수 → 정상 Redis에서도 9번째부터 거부 | `redis-runtime/.../RedisRuntimeOwner.java:134-140`, `RedisSdkSettings.java:687` | lane 한도를 연결(connection) 수에 맞게, lease는 대기 후 획득(짧은 timeout) | 동시 호출 N > 한도에서 정상 Redis면 전부 성공(fake gateway 동시성 테스트) |
|
||
| 1-10 | #15 gRPC 멱등성: FAILED_TERMINAL 행에서 claim 없이 PROCEED | `grpc/grpc-policy/.../GrpcIdempotencyInterceptor.java:109-114` | FAILED_TERMINAL은 재claim(새 attempt) 또는 거부로 명시, fake ledger도 같은 전이 규칙 | `GrpcOperationLedgerContract`(grpc-testkit) — fake와 JPA ledger 공통 |
|
||
|
||
완료 기준: 10건 각각 회귀 테스트가 수정 전 FAIL·수정 후 PASS. 영향 leaf `check` + `architectureCheck` 통과. Docker 필요한 lane(1-1, 1-5, 1-10 JPA ledger)은 실제 실행.
|
||
|
||
### Wave 1 상세 Task (작업 묶음)
|
||
|
||
서로 다른 leaf를 건드리는 7개 묶음으로 나눠 복사본에서 병렬 실행한다. 묶음마다 구현 subagent 하나.
|
||
|
||
| 묶음 | 항목 | 건드리는 leaf | 검증 명령 (`src/`에서) |
|
||
|---|---|---|---|
|
||
| W1-OP | 1-1, 1-2 | application-core(+testFixtures), persistence-jpa, adapter:inbound:web | `:application-core:check :adapter:outbound:persistence-jpa:check :adapter:inbound:web:check`, PG lane(durable operation) |
|
||
| W1-MSG | 1-3, 1-4 | messaging-outbox-jdbc-postgresql, messaging-runtime-core, messaging-spring-boot-starter-kafka | 해당 leaf `check` |
|
||
| W1-NOTIF | 1-5, 1-6 | adapter:outbound:notification(+ application-notification 필요 시) | leaf `check` + PG lane(recovery/replay) |
|
||
| W1-TUS | 1-7 | adapter:inbound:web-fileserver, application-fileserver, adapter:outbound:fileserver | leaf `check` |
|
||
| W1-GQL | 1-8 | adapter:inbound:graphql | leaf `check` |
|
||
| W1-REDIS | 1-9 | redis-runtime(+ cache-redis 영향 시) | leaf `check` |
|
||
| W1-GRPC | 1-10 | optional build `grpc:grpc-policy`, `grpc:grpc-testkit`, `grpc:grpc-operation-ledger-jpa` | `./gradlew -p optional-platforms <leaf>:check`, ledger PG lane |
|
||
|
||
공통 절차(각 묶음):
|
||
- [x] 재현 테스트 작성 → 실행해서 FAIL 확인(출력 기록)
|
||
- [x] 최소 수정 → 같은 테스트 PASS
|
||
- [x] fake가 결함을 숨긴 포트는 추상 계약 테스트로 fake·adapter 양쪽 실행
|
||
- [x] `spotlessApply`, 영향 leaf `check`, `architectureCheck`
|
||
- [x] 복사본 diff를 main 작업 트리에 반영 후 main에서 영향 leaf `check` 재실행
|
||
|
||
---
|
||
|
||
## Wave 2 — 분류 3(리팩터링 잔재)·분류 4(실험용 자리) 삭제
|
||
|
||
원칙(spec 5절, 8절 D2–D4): 한 기능에 한 세대만 남긴다. 삭제한 것은 `docs/capability-status.md`의 "제거된 코드" 표에 마지막으로 존재한 커밋과 함께 한 줄씩 적는다(복구 경로). 분류 4는 SDK가 없거나 기동 시 거부되므로 optional build로 옮기지 않고 삭제한다(2차 리뷰 S7 #1 권고: experimental 4개·Debezium 삭제; rabbit은 기동 거부·운영 채널 구현 없음).
|
||
|
||
| # | 대상 | 남길 것 | 삭제 | 근거 |
|
||
|---|---|---|---|---|
|
||
| 2-A | web 2세대·WebFlux | servlet 1세대(`RequestLoggingFilter`, `RateLimitInterceptor`, `ETags`, `PageParams`, Envelope 에러) | `webflux/*`, `advanced/webflux`, `callback/reactive`, web-fileserver reactive; 2세대 conditional/pagination/throttle/admission/access-log, `WebMvcPlatformAutoConfiguration`의 미사용 bean 9개·evidence filter·startup check·`admin/platform`, `cursor/CursorCodec`, main의 `moduleboundary`; WebProblem 어휘는 fixture 전용이면 삭제 | D4, S5 #2–#4, #8 |
|
||
| 2-B | outbox 3세대 | v1 `outbox_event` + fencing(owner+token CAS) | app-core `outbox/v2`, persistence-jpa `postgresql/outbox`, `jpa/outbox-storage`·`jpa/outbox-polling` 트리(미조립), `OutboxV2RetryPolicy` | D2, X1 #1. 새 migration `V17` (lease_owner, lease_token) |
|
||
| 2-C | 멱등성 2세대 | V2(이름에서 `V2` 제거), 조립 1곳 | v1 executor·port·adapter·H2/PG claim repo·`IdempotencyConfig`, websocket `CommittedResultLedger`, graphql `idempotencyKey` 미연결 allowlist | D3, X1 #2. sample을 V2로 이전 |
|
||
| 2-D | notification R1 | R2 platform | application-notification 루트 R1 타입, Reactor facade·의존성, `spring-web` 의존, 미사용 platform 코드(throw 0 예외, security 3종, sms/push/email/webpush), `NotificationOrchestrator`, contract-v1 템플릿 | 1차 B-8, S1 #10 #14 |
|
||
| 2-E | messaging adapter R1 | canonical bridge + R0 seam | `envelope`·`contract`·`destination`·`config` R1 체인, `realtime/MessagingDurableFanoutAdapter`, NetworkNT 런타임 의존 | S4 #2 |
|
||
| 2-F | fileserver R1/R2 publication | `platform/**` HTTP 파일 서버 | 루트 패키지 publication(31파일), app-core `filepublication`, `FileExportPort`, `app.fileserver.*`·`app.file-export.*` 설정 | S4 #1, X1 #8 |
|
||
| 2-G | STOMP 2벌, main의 governance gate | `stomp/` 스택 | `advanced/stomp/**`, `StompBrokerExclusivity`, websocket `moduleboundary`·`evidence`·`release`, graphql `architecture/`(런타임 경계 검사 — ArchUnit이 이미 검사)·`compat/`·`moduleboundary`, grpc 상수 gate·`GrpcStableModuleCatalog` | S5 #7 #11, S6 #1, S7 #4 |
|
||
| 2-H | 두 번째 트랜잭션·재시도 엔진, Mongo reactive 쌍둥이 | port 기반 엔진, imperative Mongo | persistence-jpa `SpringJpaTransactionExecutor` 계열, Mongo `reactive/**`·change stream | S2 #3 #5 |
|
||
| 2-I | messaging 분류 4 | Kafka | `messaging-pulsar-experimental`, `-nats-experimental`, `-kafka-share-experimental`, `-spring-cloud-stream-bridge`, `-rabbit`, `-starter-rabbit`, Debezium 클래스; starter의 미사용 edge(cloudevents, claim-check) | spec 5절 분류 4, S7 #1 #5 |
|
||
| 2-J | 호출자 0 잔재 | — | httpclient `BoundedErrorBody`·`spring7/`·`migration/`, objectstorage legacy adoption(켜면 기동 실패), `UuidCodec`, `CompiledPackageScanner`, app-core `@Deprecated` 캐시 executor 계열(소비자 확인 후), `PolicyTransactionPort` 계열 | 1차 A-9, S1 #3 #8, S3 #8, S4 #10 |
|
||
|
||
완료 기준: 삭제한 타입의 main 참조 0(`grep -rw`), registry·settings·문서의 참조 정리, 영향 leaf `check` + `architectureCheck` + `:app-bootstrap:architectureTest` 통과, `docs/capability-status.md` 제거 표 갱신.
|
||
|
||
### Wave 2 상세 Task (작업 묶음)
|
||
|
||
사전 조사(읽기 전용) 결과로 범위를 확정했다. 조사에서 "아직 쓰인다"로 확인된 것은 삭제 대상에서 뺐다:
|
||
`PolicyTransactionPort` 계열(fileserver 보상 트랜잭션이 사용 — 삭제가 아니라 `TransactionPort.inNew`로 교체 후 삭제),
|
||
cache 타입 9개(cache-redis 사용), `IdempotencyReaper`와 멱등성 엔티티(V2 행 정리에 필요), v1 패키지의 공용 타입 8개(V2가 사용),
|
||
`NotificationSubmissionService`의 진입 메서드, `NotificationPort` bean.
|
||
|
||
| 묶음 | 대상 | 결정 |
|
||
|---|---|---|
|
||
| W2-1 | T-F 파일 서버 publication 평면, T-G websocket 중복 STOMP·governance, T-J httpclient/identifier/objectstorage legacy 잔재 | 전부 삭제. MasterSwitch `FILESERVER`(R1 스위치)와 문서·env key 동반 삭제 |
|
||
| W2-2 | T-G graphql governance(`architecture/`, `compat/`, `moduleboundary`, `release`), T-E messaging adapter R1 체인, T-I messaging 분류 4 leaf | graphql 부팅 시 경계 검사에서 잃는 규칙 2개(resolver는 transport 타입만 반환, raw `DataFetcher`는 infra에만)는 ArchUnit으로 옮긴다. `IntegrationEventEncoderPort`는 adopter 확장 지점으로 남기고 검증 메시지만 고친다. rabbit·pulsar·nats·kafka-share·stream-bridge·Debezium 삭제 |
|
||
| W2-3 | T-A web 2세대·WebFlux·WebProblem | 전부 삭제. WebProblem을 인증하던 fixture lane은 transport 동작을 보는 것(Jetty 호환)은 Envelope 기준으로 고치고, WebProblem 표면만 인증하던 것은 삭제 |
|
||
| W2-4 | T-D notification R1, T-H 두 번째 트랜잭션 엔진·Mongo reactive, T-J application-core 잔재(cache 20개, `LeaseWatchdog`, inbox, `EphemeralFanoutPort`, 미사용 lock/write 실행기), `PolicyTransactionPort` 교체 | 삭제 + fileserver 보상 트랜잭션을 `TransactionPort.inNew`로 |
|
||
| W2-5 | T-B outbox V2 삭제 + v1 fencing(D2) | V2 코드·`jpa/outbox-storage`·`jpa/outbox-polling` 트리 삭제(어떤 조립도 적용한 적 없음), `V17` lease_owner/lease_token + CAS 완료 처리 |
|
||
| W2-6 | T-C 멱등성 v1 삭제(D3) | V2 정본. PostgreSQL provider는 켜지면 자기 migration stream(`jpa/idempotency`)을 적용해야 "켜면 동작"(기준 3)을 충족. 실행기 조립은 한 곳. sample을 V2로 이전. `IdempotencyReaper`는 `postgresql` provider로 재조건 |
|
||
|
||
조사 원문: scratchpad `w2-inventory-A.md`, `w2-inventory-B.md`(세션 산출물). 순서: W2-1·W2-2·W2-4 병렬 → W2-3 → W2-5 → W2-6(동작 변경).
|
||
|
||
---
|
||
|
||
## Wave 3 — 분류 2(라이브러리형 API)
|
||
|
||
spec 5절: "완성해서 1번처럼 포장하거나 `optional-platforms`로 이동". 대상: redis-sdk, Mongo `advanced` 등, JPA 플랫폼 라이브러리, graphql `advanced`, websocket 플랫폼 라이브러리, web의 기본 경로 밖 라이브러리 패키지.
|
||
|
||
**확인한 사실 (2026-09-25 실험):** optional build(`src/optional-platforms`)에 `includeBuild('..')`를 넣으면 main build를 composite로 불러와 `dev.caskeleton:<leaf>` 좌표로 받을 수는 있다. 그러나 (1) redis-sdk의 테스트 전체가 cache-redis 테스트 소스에 들어 있어 이동하려면 테스트 이전이 먼저이고, (2) B안에서는 서비스가 고르지 않은 leaf가 jar에 들어가지 않으므로 optional build로 옮겨도 서비스가 내는 비용(jar·CVE·기동)은 줄지 않는다. 줄어드는 것은 main `ci` 시간뿐이다.
|
||
|
||
**결정:** 분류 2는 "옮기기" 대신 "완성해서 포장"으로 처리한다. 라이브러리는 유지하되:
|
||
1. 동작하지 않는 약속은 없앤다(기준 3): 어떤 코드도 바인딩하지 않는 설정 키, 켜면 기동이 실패하는 `Unsupported` 플래그, 구현체 없는 인터페이스, main에 있는 promotion/release/evidence gate, 테스트에서만 쓰는 main 클래스.
|
||
2. 남는 라이브러리 API는 leaf README에 "라이브러리 API — 서비스의 어댑터 leaf에서 `implementation`으로 받아 직접 호출"로 적는다(AGENTS.md capability 규칙의 라이브러리형 예외).
|
||
3. 기본 조립에 들어가는 leaf(`adapter:inbound:web`)에 있는 라이브러리 패키지는 opt-in leaf `adapter:inbound:web-advanced`로 분리한다. 기본 서비스가 쓰지 않는 코드를 싣지 않게 하기 위해서다.
|
||
4. redis-sdk는 이미 독립 leaf다. 테스트를 cache-redis에서 redis-sdk leaf로 옮겨 cache-redis가 테스트에서도 redis-sdk에 의존하지 않게 한다.
|
||
|
||
| 묶음 | leaf | 내용 |
|
||
|---|---|---|
|
||
| W3-1 | redis-sdk, cache-redis | SDK 테스트 이전, cache-redis의 redis-sdk test edge 제거, README |
|
||
| W3-2 | adapter:inbound:web → web-advanced | 기본 경로 밖 패키지(advanced, admin/route, budget, cache, contract, operation, proxy 등) 분리, registry 등록 |
|
||
| W3-2b | web-advanced | W3-2 결과 후속: `advanced/functional`(WebFlux `RouterFunction` — D4상 servlet 전용 템플릿에서 동작 불가)과 운영이 이미 다른 방식으로 하는 기능의 중복 패키지(`proxy`↔`forward-headers-strategy`, `security` 프로필↔`SecurityConfig`, `cache`↔`CacheControlFilter`, `json` factory↔Boot Jackson, `openapi` customizer↔`OpenApiContractConfig`) 삭제 — "한 기능에 한 세대" |
|
||
| W3-3 | graphql | 동작하지 않는 약속 제거, 라이브러리 API 문서화 |
|
||
| W3-4 | websocket | 같음 |
|
||
| W3-5 | persistence-mongo | 같음(구현체 없는 인터페이스 10개, 바인딩 안 되는 `advanced.*.enabled` 등) |
|
||
| W3-6 | persistence-jpa | 같음(지원 표면 밖 단일 구현 인터페이스, 호출자 없는 실행기 등) |
|
||
|
||
완료 기준: 각 leaf에서 기준 3 위반(동작하지 않는 설정·인터페이스·gate) 0건, README에 라이브러리 API 목록, web 기본 leaf에 라이브러리 패키지 없음, 영향 leaf `check` + `architectureCheck` 통과.
|
||
|
||
---
|
||
|
||
## Wave 4 — 분류 1 capability 포장 + 기본 조립 web-only
|
||
|
||
대상 capability와 "한 줄":
|
||
|
||
| capability | `app-bootstrap/build.gradle` 한 줄 | 모듈로 옮길 bootstrap 코드 |
|
||
|---|---|---|
|
||
| JPA/PostgreSQL (Flyway, TransactionPort, outbox store, JDBC 멱등성, 분산 락) | `runtimeOnly project(':adapter:outbound:persistence-jpa')` | `autoconfigure/jpa/*`, `autoconfigure/lock/*`, JPA 계열 `runtime/*Validator`, `MigrationStartup*`, `DataSourceRequirement` |
|
||
| outbox relay | (JPA + Kafka를 둘 다 고르면 켜짐) | `autoconfigure/outbox/*` → 발행 쪽 capability(messaging)로, `@ConditionalOnBean(OutboxStorePort)` + `afterName` |
|
||
| Redis (cache/lock/idempotency/rate-limit) | `runtimeOnly project(':adapter:outbound:cache-redis')` | `autoconfigure/redis/*`, Redis 계열 validator |
|
||
| Kafka 발행 | `runtimeOnly project(':adapter:outbound:messaging-kafka')` (bridge + platform starter-kafka를 끌어옴) | `autoconfigure/messaging/*`, `DisabledMessagingSentinelAutoConfiguration` 삭제 |
|
||
| 알림 (SES/SMTP) | `runtimeOnly project(':adapter:outbound:notification')` | `autoconfigure/notification/*`; notification persistence를 `persistence-notification` leaf로 추출(S2 #1), web notification HTTP를 `adapter:inbound:web-notification`으로 추출(S5 #9). 미조립 provider 5종 삭제(spec 6절 3) |
|
||
| Mongo | `runtimeOnly project(':adapter:outbound:persistence-mongo')` | `MongoOptInAutoConfigurationImportFilter` 삭제, "있으면 켜짐" |
|
||
| object storage (S3) | `runtimeOnly project(':adapter:outbound:objectstorage')` | 모듈 자체 auto-config 정리 |
|
||
| HTTP client | `runtimeOnly project(':adapter:outbound:httpclient')` | master switch 제거 |
|
||
| GraphQL | `runtimeOnly project(':adapter:inbound:graphql')` | `GraphQlOffAutoConfigurationImportFilter` 삭제 |
|
||
| WebSocket / gRPC 어댑터 | `runtimeOnly project(':adapter:inbound:websocket')` / `grpc` | conditional-transport qualification을 기본 조립 테스트로 대체 |
|
||
| 파일 서버 | `runtimeOnly project(':composition:fileserver-platform')` | bootstrap의 fileserver 스위치·설정·`dependencyPolicy` 항목 삭제 |
|
||
|
||
capability마다 spec 6절 완료 기준 7개를 체크한다: 포트만 호출 / 자기 `AutoConfiguration.imports` + `enabled`(기본 true) + `afterName` / 켜면 완전히 동작 / prefix 하나 + `StrictSettingsBinder` + compact constructor / 포트 계약 테스트(fake + adapter, Testcontainers 1개 이상) / README(제공·한 줄·env) / bootstrap이 모듈을 모름.
|
||
|
||
bootstrap에서 삭제: `MasterSwitch`(+ shared-contract `activation`), `MasterSwitchEnvironmentPostProcessor`, `CapabilityDependency*`, `AdapterActivation*`, `CaSkeletonApplication` scan 제외 정규식(scan은 `dev.caskeleton.bootstrap`으로 좁히고 web은 자기 auto-config 공개), 흩어진 startup validator(각 capability로 이동하거나 `StartupRule` 목록 하나로).
|
||
|
||
아키텍처 검사 분리(spec 7절): `architectureTest` classpath에는 모든 모듈을 테스트 의존으로, 운영 `runtimeClasspath`에는 고른 모듈만.
|
||
|
||
기본 조립: web + 관측 + 코어 + support/identifier. 나머지 한 줄은 주석으로 목록에 남긴다.
|
||
|
||
완료 기준:
|
||
- 기본 조립으로 `bootRun`/system test 기동 성공, DB·Redis·Kafka 없이.
|
||
- capability 한 줄을 추가/삭제하는 system test(대표 3개: JPA, Redis, Kafka)가 bean 생성/부재를 확인.
|
||
- 끄는 장치 5종(MasterSwitch, import filter 2, sentinel, scan 정규식)의 main 참조 0.
|
||
- sample-portfolio가 자기 조립(JPA, objectstorage, web, identifier 한 줄씩)으로 기동·테스트 통과.
|
||
|
||
---
|
||
|
||
### Wave 4 상세 Task (작업 묶음)
|
||
|
||
조사 결과(세션 산출물 `w4-inventory.md`)로 순서를 정했다. 모두 app-bootstrap을 건드리므로 JPA 계열은 순차, 나머지는 파일이 겹치지 않는 범위에서 병렬.
|
||
|
||
| 묶음 | 내용 |
|
||
|---|---|
|
||
| W4-1 | 준비: 옮겨 갈 클래스가 쓰는 bootstrap 전용 helper(`StartupFailures`, `ReadinessGroup` 등)를 `adapter:outbound:support`로, persistence-jpa에 support edge 추가, 연결 안 된 `JpaPlatformAutoConfiguration` 삭제. lock·outbox·Redis 조립 코드를 각 leaf로(outbox relay는 발행 포트 bean이 있을 때만), `DisabledMessagingSentinelAutoConfiguration` 삭제 |
|
||
| W4-2 | JPA root(`autoconfigure/jpa/*`, JPA validator, Flyway startup, `application.yml`의 datasource/flyway/jpa 블록, `persistence.yml`)를 persistence-jpa로. `JpaOffAutoConfigurationImportFilter`·`DataSourceRequirement` 삭제. sample이 broad scan 대신 leaf auto-config로 JPA를 받게 |
|
||
| W4-3 | 알림: `composition/notification-platform` 신설(조립 클래스 2개 + `notification.yml`), web의 `notification/` callback ingress를 web 밖으로 옮겨 기본 web이 `application-notification`을 싣지 않게 |
|
||
| W4-4 | messaging·Mongo·GraphQL·httpclient·objectstorage·websocket·gRPC·파일 서버: import filter 삭제, "있으면 켜짐"(`enabled` 기본 true), 설정 yml을 leaf로, Rabbit 설정 키 제거 |
|
||
| W4-5 | 끄는 장치 철거(`MasterSwitch`·activation 패키지·scan 정규식·`CapabilityDependency*`·`AdapterActivation*`), 기본 조립을 web-only로 바꾸고 나머지는 주석 한 줄 목록, architectureTest classpath에 모든 leaf, registry 정리, 관련 테스트 삭제·재작성, 기본 조립 기동 테스트 + capability 한 줄 추가/삭제 테스트(JPA·Redis·Kafka), capability README(제공·한 줄·env) |
|
||
|
||
## Wave 5 — 빌드 O3 + 테스트 컨벤션
|
||
|
||
1. 2차 리뷰 BUILD 절 "바로 할 것" 1–12를 순서대로 적용한다(Wave 2–4에서 이미 사라진 대상은 건너뛰고 진행 기록에 적는다).
|
||
2. O3: build-logic에는 registry, 방향·순수성 task, 컨벤션, 레인 하나만. 기능별 검사(evidence, readiness, API-surface, family plugin)는 소유 leaf 테스트로 옮기고, 읽는 파일은 `inputs`로 선언한다. build-tools는 비운다.
|
||
3. 테스트 컨벤션: `sample-portfolio` 전체 테스트를 AGENTS.md 컨벤션으로 재작성(`WorkLogRepositoryContract`로 fake와 adapter 공통 계약, `TransactionPort` fake는 application-core testFixtures 하나).
|
||
|
||
완료 기준: `./gradlew ci --console=plain` 통과, build-logic+build-tools 줄 수 감소 기록, sample 테스트 GWT 컨벤션 적용.
|
||
|
||
---
|
||
|
||
## 진행 기록
|
||
|
||
| Wave | 상태 | 검증 | 스냅샷 | 비고 |
|
||
|---|---|---|---|---|
|
||
| 0 | 완료 (2026-09-25) | build-logic test, persistence-jpa·messaging·app-bootstrap·sample `check`, `architectureCheck`, PG lane `postgresqlMigrationIntegrationTest`·`postgresqlLegacyOutboxRowLifecycleIntegrationTest` 전부 통과 | scratchpad `wave-0.patch` | outbox-storage V1은 Wave 2(D2 삭제)로 넘김. V16 적용 확인(실제 PostgreSQL) |
|
||
| 1 | 완료 (2026-09-25) | 10건 모두 재현 테스트 FAIL→PASS. main에서 영향 leaf 20개 `check` + `app-bootstrap:check` + `sample-portfolio:check` + `architectureCheck` + `verifyDependencyLocks` + `verifyEnvKeys` 통과, optional gRPC `check`·ledger PG lane 통과. PG lane(durable operation 계약 24, notification background 7), gRPC ledger 계약 16 실제 DB 통과 | scratchpad `wave-1-cumulative.patch` | 새 env key `APP_NOTIFICATION_PLATFORM_SES_ALLOWED_TOPIC_ARNS`(SES 콜백 사용 시 필수). 남은 것: Redis 실제 lane 기존 실패 4건(테스트 ACL에 TIME 권한 없음, 시계 +1h), durable operation 같은 id 재시도 시 outbox 중복, Redis idempotency/lease의 lane 거부 분류가 Indeterminate, Kafka truststore/keystore 설정 키 없음 |
|
||
| 2 | 완료 (2026-09-25) | W2-1~W2-6 반영 후 main 전체 `check` + `architectureCheck` + locks + env keys + public path + config contract 통과. W2-5 fencing은 실제 PG에서 중복 전달 재현 후 해결, W2-6 PostgreSQL 멱등성은 빈 DB에서 실패 재현 후 해결 | scratchpad `wt-w2*.patch` | 제거 목록은 `docs/capability-status.md` "제거된 코드" 표 |
|
||
| 3 | 완료 (2026-09-25) | W3-1~W3-6, W3-2b 반영 후 main 전체 `check` 통과(Redis/Mongo/websocket/web/JPA/graphql 실제 lane은 각 묶음에서 실행) | scratchpad `wt-w3*.patch` | web 기본 leaf 13.9k→5.3k줄(라이브러리는 opt-in `web-advanced`), graphql 22k→12.8k, websocket 10.2k→1.9k. 추가 수정: notification admin 결과 codec jsonb 공백 결함(기존) |
|
||
| 4 | 완료 (2026-09-25) | main 전체 `check` + `architectureCheck` + locks + env keys + public path + config contract + `qualificationBootJar` 통과. 기본 runtimeClasspath = web·identifier·support·domain-core·application-core·shared-contract. `DefaultCompositionBootTest`(local/dev/prod, DB·Redis·Kafka 없이) + capability별 활성화 테스트 | scratchpad `wt-w4*.patch` | 끄는 장치(MasterSwitch·activation·scan 정규식·import filter·sentinel) 제거. CI compose 18 lane 실제 실행 안 함(정적 검증만). `S3AsyncResponseBodyBridgeTest` 부하 시 간헐 실패 |
|
||
| 5 | 완료 (2026-09-25) | `check`(481 task), `ci verifyDependencyLocks --warning-mode=fail`, `mainCheck`(14 lane 152 tests), build-logic 80·build-tools 35 tests, bootstrap/sample integration·system, configuration cache 통과 | scratchpad `wt-w51/w52/wfin.patch` | 빌드 코드 17.2k→10.8k줄(바로 할 것 1–12 적용, notification·mongo·messaging·graphql·jpa 검사를 leaf 테스트로). sample 테스트 컨벤션 적용(test 198→283, integration 13→49). 남은 설계 결정: `verifyEnvKeys`·JPA evidence·redis topology lane 이동 여부 |
|