Files
clean-architecture-backend-…/docs
DongHyeonka 06b9433855 fix(app-bootstrap)!: STOMP channel interceptor를 사용자 전송으로 센다
문제
- 사용자 전송 타입 목록(USER_TRANSPORT_TYPE_NAMES)은 STOMP 쪽에서 simp
  패키지와 @MessageMapping만 담는다. 클라이언트 프레임마다 도는 inbound
  channel interceptor(ChannelInterceptor·ExecutorChannelInterceptor)는
  STOMP 헤더 타입을 읽지 않으면 사용자 전송으로 보이지 않는다.
- 그래서 설정이 configureClientInboundChannel에서 익명 interceptor를
  등록해 @SystemCaller를 부르거나, 사용자 전송 패키지 밖의 interceptor가
  부르거나, interceptor를 구현한 설정이 부르면
  USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가 통과한다. 인증만 된
  WebSocket 클라이언트가 권한 검사 없는 쓰기를 부른다.
- 매뉴얼 07 「규칙이 못 보는 길」은 설정에 중첩한 클래스가 이 사각지대에
  들지 않는다고 적어 동작과 다르다(RR8-02-01).

고른 방법
- 두 interceptor 타입을 사용자 전송 타입 목록과 요청 처리기 타입 목록
  (REQUEST_HANDLER_TYPE_NAMES)에 이름으로 더한다. 앞쪽은 중첩·최상위
  interceptor를, 뒤쪽은 interceptor를 구현하거나 @Bean으로 내놓는 설정
  자신을 잡는다. HandlerInterceptor·ServerInterceptor도 두 목록에 있다.
- inbound channel의 thread만 정하는 설정(ChannelRegistration)은 설정용
  타입이라 그대로 통과한다. interceptor bean을 handler bean과 다른 설정에
  두면 통과한다. 둘 다 허용 fixture로 고정했다.
- 위반 fixture 다섯(설정 안 익명 ChannelInterceptor, 설정 안
  ExecutorChannelInterceptor, 최상위 interceptor, interceptor를 구현한
  설정, @Bean ChannelInterceptor를 내놓으며 handler bean도 만드는 설정)이
  목록 항목을 하나씩 증명한다. fixture가 spring-messaging 타입을 써서
  architectureTestCompileOnly 한 줄과 lockfile 한 줄을 더했다. runtime에는
  WebSocket adapter가 이미 싣는다.
- 매뉴얼 07, 업그레이드 안내 B-16, app-bootstrap README, 규칙 Javadoc과
  실패 메시지를 동작에 맞췄다.
- 버린 대안:
  - 요청 처리기 목록에는 넣지 않기(리뷰 A 권장안). interceptor는 람다로
    설정에 쓸 수 없지만, 설정이 interceptor를 구현하거나 @Bean으로 내놓는
    길이 남는다. 매뉴얼은 이미 "interceptor 등록은 handler bean을 만드는
    설정과 다른 설정에 둔다"고 적는다. 리뷰 B 권장안을 따랐다.
  - org.springframework.messaging.support 패키지째 넣기. 같은 패키지의
    MessageBuilder를 시스템 쪽 Spring Integration 흐름도 써서 판정이
    넓어진다.
  - 규칙은 두고 매뉴얼에 사각지대로 적기(리뷰 대안). 템플릿 자신이 쓰는
    진입 타입이라 규칙으로 막을 수 있다.
  - ChannelInterceptor로 대입 가능한 타입 전부(assignableTo). 프로젝트
    interceptor 클래스까지 사용자 전송 타입이 되어, 그것에 의존하는 모든
    클래스가 사용자 전송이 된다. 다른 목록과 모양도 달라진다.

위험·한계
- 판정이 넓어진 곳: STOMP outbound·broker channel interceptor도 같은
  타입이라 사용자 전송으로 센다. 시스템 쪽 Spring Integration 흐름의
  channel interceptor를 @SystemCaller 안에 두면 실패한다. 템플릿에는 둘 다
  없다(Spring Integration은 JDBC lock registry만 쓴다).
- 이름 목록이라 ImmutableMessageChannelInterceptor 같은 구현 클래스를
  상속한 interceptor는 보지 못한다.
- 설정이 registration.interceptors(x)로 넘기기만 할 때 설정 자신이
  잡히는지는 확인하지 않았다. interceptor 자신은 사용자 전송으로 검사된다.
- STOMP 런타임 기동은 보지 않았다. 규칙 판정만 봤다.

검증 (desktop, flock /tmp/claude-gates/heavy.lock,
로그 ~/r9-g2-stomp-interceptor-logs/)
- RED: 3eb3b067에 테스트·fixture·의존성 줄만 얹은 트리 39b02529에서
  ArchitectureViolationFixtureTest 실행. 99건 중 5건 실패, 다섯 모두 위반
  0건(Expecting any element of: []). 허용 2건은 통과. rc=1.
- GREEN: :app-bootstrap:architectureTest --rerun 249건, 실패·skip 0, rc=0.
- 변이: ExecutorChannelInterceptor를 두 목록에서 빼면 [2]만, 요청 처리기
  목록의 ChannelInterceptor를 빼면 [4][5]만, 사용자 전송 목록의
  ChannelInterceptor를 빼면 [1][3]과 UserTransportTypeListsTest가 실패.
- 트리 742428a9에서 모두 rc=0, FROM-CACHE 0:
  :app-bootstrap:check(305건, skip 5, 실패 0), architectureCheck,
  :app-bootstrap:testQualityCheck,
  :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache
  (842 태스크 실행, 6906건 실패 0), :verifyStrictLaneStages --dry-run,
  scripts/verify-compose-profile-contracts.sh,
  :sample-portfolio:check :sample-portfolio:qualityCheck(340건 실패 0),
  -p optional-platforms ci(593건 실패 0),
  -p optional-platforms :verifyStrictLaneStages --dry-run.

Refs: docs/reviews/2026-11-03-rereview/README.md 19절 RR8-02-01

BREAKING CHANGE: STOMP inbound channel interceptor(ChannelInterceptor,
ExecutorChannelInterceptor)가 사용자 전송 타입이자 요청 처리기 타입이
됐다. 사용자 전송 패키지 밖이나 설정 안에 둔 interceptor, interceptor를
구현한 설정이 @SystemCaller에 닿거나, interceptor를 @Bean으로 내놓는 설정이
@SystemCaller bean도 만들면 :app-bootstrap:architectureTest가 실패한다.
interceptor에서 시스템 작업을 부르지 않는다. 사용자도 시켜야 하면
@RequiresPermission 유스케이스를 따로 만들고, interceptor 등록은 handler
bean을 만드는 설정과 다른 설정에 둔다(업그레이드 안내 B-16).
2026-11-07 07:55:55 +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 가 소유한다.