Files
clean-architecture-backend-…/docs
DongHyeonka 6764246ac9 fix(architecture): Flyway 규칙이 설정 객체를 직접 만드는 길도 막는다
문제 (재리뷰 round7 RR7-03-06)
- 규칙 문장은 "코드로 만드는 Flyway는 모두 FlywaySchemaPolicy.configure()
  에서 시작한다"(persistence-jpa CLAUDE.md, FlywaySchemaPolicy Javadoc,
  migration-guide)인데 JpaProductionArchitectureTest는 Flyway.configure()
  호출만 막는다. new FluentConfiguration(), new ClassicConfiguration(),
  FluentConfiguration::new로 만든 Flyway는 검사를 지나 Flyway의
  PostgreSQL 잠금 기본값(트랜잭션 안의 잠금)을 되찾는다. 그 잠금 아래
  동시 인덱스 마이그레이션은 끝나지 않는다(RR6-03-01).

고른 방법
- 규칙을 상수 EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY로 빼고, Flyway
  Configuration에 대입 가능한 타입의 생성자 접근(호출과 생성자 참조)을
  더 막는다. 하위 클래스와 직접 구현도 같은 접근이라 함께 걸린다.
  new Flyway(...)는 허용한다 — 정책의 설정 위에서는 정책의 Flyway다.
- 위반 fixture 4개(configure 호출, FluentConfiguration·ClassicConfiguration
  생성, 생성자 참조)와 허용 fixture 1개(정책 빌더, 정책 설정 위의
  new Flyway)를 ArchitectureViolationFixtureTest로 평가한다.
- 버린 안: callConstructor를 생성자 시그니처마다 나열 — Flyway 버전마다
  생성자 목록이 바뀌고 생성자 참조를 못 본다. new Flyway(...)까지 금지 —
  정책 설정 위의 정당한 사용까지 막는다.

위험·한계
- 하위 클래스 fixture는 두지 않았다. SpotBugs가 Flyway 설정을 상속한
  클래스를 분석하다 lombok.Generated를 못 찾아 testQualityCheck가 실패한다
  (빌드는 불완전 분석을 실패로 본다). 이 경우는 GREEN 1차 실행에서 규칙이
  잡는 것을 확인했고(g0306-archtest.log), 규칙 Javadoc에 이유를 적었다.
- 리플렉션이나 Configuration 맵으로 잠금 값을 덮어쓰는 것은 막지 않는다.
- 이 규칙을 이미 지키는 파생 서비스(업그레이드 안내 2절 15번)는 바꿀 것이
  없다. 설정 객체를 직접 만들던 서비스는 architectureTest가 새로 실패한다
  (안내 15번과 5절 「Flyway 잠금」 행에 적었다).

검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/)
RED — 6ec0c4f7 + 규칙 상수 추출(규칙 그대로)과 fixture·테스트:
- :app-bootstrap:architectureTest 1차 233건 중 3건 실패
  (FluentConfiguration·ClassicConfiguration·하위 클래스 fixture 통과),
  2차(생성자 참조 fixture 추가) 234건 중 4건 실패. Flyway.configure()
  fixture는 잡히고 허용 fixture는 통과 (red0306-arch*.log)
GREEN — 이 커밋의 트리 e7e19298:
- :app-bootstrap:architectureTest rc=0 (233건 실패 0; 위반 fixture 4개
  모두 걸리고 허용 fixture와 운영 코드는 통과)
- architectureCheck rc=0
- :adapter:outbound:persistence-jpa:check rc=0, :app-bootstrap:check rc=0
- :app-bootstrap:documentContractTest rc=0 (66건 실패 0)
- :app-bootstrap:testQualityCheck rc=0. 하위 클래스 fixture를 둔 1차
  트리(f8fecd1e)에서는 spotbugsArchitectureTest가 "missing analysis class
  lombok.Generated"로 실패했고, 그 fixture만 빼자 통과했다
  (g0306-testquality.log, g0306b-testquality.log)
- 같은 우회가 다른 곳에 있는지: 운영 코드 전체(src 아래 main·testFixtures)
  에서 Flyway를 만드는 곳은 FlywaySchemaPolicy와 규칙이 예외로 둔
  MessagingInboxSchemaStream의 Flyway.configure()뿐이다. optional 빌드와
  src/messaging에는 운영 Flyway 생성이 없다

Refs: docs/reviews/2026-11-03-rereview/README.md 18.5절 round7 1차 Declined 판정 (cb340001)
2026-11-07 01:28:33 +09:00
..

docs

저장소의 모든 문서는 이 디렉터리 아래에 있다. 어떤 문서를 어디에 두는지가 유일한 규칙이고, 파일 목록은 디렉터리를 직접 읽는다. 개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.

어댑터별 운영 문서

각 어댑터의 지원 범위, 설정, 보안, 운영, 마이그레이션 문서다. 코드와 함께 갱신되어야 하는 문서이고, docs/httpclient/ 는 scripts/verify-httpclient-docs.py 가 코드에서 뽑은 이름과 대조한다.

디렉터리 대상
fileserver/ 파일 서버 어댑터
httpclient/ HTTP 클라이언트 플랫폼
jpa/ JPA·PostgreSQL 영속성
messaging/ 메시징 어댑터
mongodb/ MongoDB 문서 영속성 (advanced/, runbooks/ 포함)
notification/ 알림 전달 플랫폼 (adr/ 포함)
redis/ Redis 캐시·세션

횡단 문서

디렉터리 대상
adr/ 아키텍처 결정 기록
architecture/ 공개 API 표면 스냅숏
work/ 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 CLAUDE.md 다음에 읽는다
manual/ 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(scripts/new-feature.sh). 입구는 work/new-feature.md
evidence/ 작업 단계별 증거·체크포인트
registries/ env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT
reviews/ 모듈 코드 리뷰 결과
runbooks/ 장애 코드별 대응 런북 (template.md 기준)
security/ 공개 경로 스냅숏

설계와 계획

디렉터리 대상
superpowers/specs/ 설계서. YYYY-MM-DD-<주제>-design.md
superpowers/plans/ 구현·확장 계획서. YYYY-MM-DD-<주제>-plan.md
superpowers/packages/ 외부에서 납품된 설계 패키지의 README와 정적 검증 결과

superpowers/packages/<어댑터>/ 는 설계서가 처음 전달됐을 때의 안내와 VALIDATION.md 검증 이력을 남긴 기록 보관소다. 설계서·계획서 본문은 전부 specs/ 와 plans/ 에 있으므로 이 디렉터리에서 문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.

계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로 조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 repository-adaptation.md 또는 module-mapping.md 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.

여기에 없는 것

  • 실행되는 검증 스크립트는 문서가 아니다. scripts/ 와 .github/scripts/ 에 있다.
  • 모듈 레지스트리·Gradle 정책은 src/config/architecture/modules.json 과 src/build.gradle 이 소유한다.
  • 각 모듈의 지역 규칙은 해당 모듈의 src/**/CLAUDE.md 가 소유한다.