---
kind: CASE
slug: narrowing-the-scan-orphaned-eight-components
title: 넓은 스캔을 좁히자 여덟 컴포넌트에 아무것도 도달하지 않았다
topic: assembly-ownership
project: clean-architecture-backend-template
status: 게시 전
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
rootTreeNode: case:narrowing-the-scan-orphaned-eight-components
evidenceCapturedOn: 2026-09-01
assets:
  - key: narrowing-the-scan-orphaned-eight-components
    file: ../../../final/evidence/rendered/narrowing-the-scan-orphaned-eight-components.svg
evidence:
  - ../../../final/evidence/raw/narrowing-the-scan-orphaned-eight-components.txt
source:
  - 원본 분석 절은 final/document.md#a05 §14.2 이다.
---

# 넓은 스캔을 좁히자 여덟 컴포넌트에 아무것도 도달하지 않았다

컴포지션 루트가 퍼시스턴스 패키지를 스캔에서 뺐다. 그 제외는 옳았지만 나머지 절반이 빠져 있었다. 스캔 컴포넌트로 작성된 여덟 클래스에 아무도 도달하지 않았고, 그중 하나는 트랜잭션 포트의 유일한 구현이었다.

## 관계

- **스캔에서 뺀 다섯 패키지의 컴포넌트 여섯을 두 자동설정 어느 쪽도 소유하지 않았다**
  같은 형태가 웹 리프에서 반복된 사례다.
- **꺼짐은 조건의 반복이 아니라 구조여야 한다**
  스캔 제외가 그 규칙을 따른 조치라는 점이 이 사례의 전제다.
- **@Bean이 있다는 것은 조립 증거가 아니다**
  스테레오타입이 붙어 있다는 것도 조립 증거가 아니다.

## 문제

컴포지션 루트의 컴포넌트 스캔은 퍼시스턴스 어댑터 패키지 전체를 정규식으로 제외한다. javadoc 은 그 제외가 옳다고 명시한다. 선택적 능력을 선택적으로 만드는 것이 그 제외이며, JPA 가 꺼진 배포는 퍼시스턴스 빈을 조립하지 않는다.

빠진 것은 나머지 절반이다. 이 리프의 여덟 클래스가 스캔 컴포넌트로 작성되어 있었다.

SpringTransactionPort
PersistenceExceptionTranslator
StandardSqlStateErrorMapping
DomainContextAuditContextPort
멱등성 저장소와 그 리퍼
outbox 저장소와 그 리퍼

넓은 스캔이 이들에게 닿지 않게 되자 다른 어떤 것도 닿지 않았다. @Component 와 @Repository 가 붙어 있었지만 실행 중인 어떤 애플리케이션에서도 빈이 아니었다.

특히 TransactionPort 는 구현이 아예 없는 상태가 됐다. 트랜잭션을 여는 모든 유스케이스가 그것을 열 포트를 갖지 못했다.

## 결론

단위 테스트로는 보이지 않았다. 이 클래스들은 각자의 테스트에서 직접 생성되기 때문이다.

드러난 것은 트랜잭션이 필요한 능력이 실제로 조립됐을 때다. 알림 오케스트레이터가 local-notification-ingest 레인에서 미충족 의존성으로 실패했다.

수정은 스캔을 복원하되 원래 덮었어야 할 패키지로 좁히고, PersistenceJpaRootAutoConfiguration 을 통해서만 도달하게 만드는 것이었다. 그 루트가 JPA 마스터 스위치를 갖는다. 꺼짐은 여전히 구조적이다.

두 패키지는 의도적으로 빠져 있다. fileserver 는 자기 능력 스위치로 게이트되고 자기 설정 클래스가 스캔한다. notification 은 전용 파사드가 빈 단위로 명시적으로 조립한다.

이 패키지들 아래 컴포넌트는 각자의 ConditionalOnProperty 가드를 유지한다. 스캔 대상이 된다는 것은 후보가 된다는 뜻이지 무조건 빈이 된다는 뜻이 아니다.

## 검증 환경

OpenJDK : 21.0.12
Gradle : 9.0.0
Spring Boot : 4.0.8
근거 : 저장소의 javadoc 이 사후 기록으로 남긴 회귀
소스 수정 : x

## 재현 조건

수정된 형태를 확인하는 절차다.

1. JpaAdapterComponentsConfig 의 클래스 javadoc 을 읽는다. 여덟 클래스가 이름으로 열거되어 있다.
2. CaSkeletonApplication 의 제외 정규식에 퍼시스턴스 패키지가 있는지 확인한다.
3. 이 설정 클래스가 PersistenceJpaRootAutoConfiguration 을 통해서만 도달하는지 확인한다.
4. 의도적으로 빠진 두 패키지의 대체 조립 경로를 확인한다.

## 본문

<!-- body:start -->

합성 루트의 스캔이 persistence 트리를 정규식으로 제외했고 **그 제외는 옳다** — 그것이 optional capability를 optional하게 만든다. 빠진 것은 나머지 절반이다.

## SpringTransactionPort 참조 위치

:::evidence key="narrowing-the-scan-orphaned-eight-components" alt="코드베이스에서 SpringTransactionPort 를 검색한 출력 11줄. 이 기록이 세는 참조가 그 출력에 그대로 보인다." caption="SpringTransactionPort 코드베이스 검색 — 11줄 · exit 0" zoom="true"
:::

## 여덟 클래스에 아무것도 도달하지 않았다

`SpringTransactionPort`·`PersistenceExceptionTranslator`·`StandardSqlStateErrorMapping`·`DomainContextAuditContextPort`·idempotency store와 reaper·outbox store와 reaper가 scanned component로 쓰여 있는데, 넓은 스캔이 멈추자 아무것도 도달하지 않았다.

## 특히 TransactionPort 는 구현이 전혀 없었다

트랜잭션을 여는 모든 유스케이스가 열 포트를 갖지 못했고, 단위 테스트는 각 클래스를 직접 생성하므로 볼 수 있는 것이 없었다.

## 확인하지 못한 것

당시 실패했던 local-notification-ingest 레인을 이 리비전에서 재실행하지 않았다.

없음 — 수정된 @ComponentScan 대상 6개를 코드로 확인했다

<!-- body:end -->