Files
clean-architecture-backend-…/docs/manual
DongHyeonka a8166598d5 fix(app-bootstrap)!: 설정에 중첩된 endpoint를 다시 잡고 route 등록 판정을 문서에 맞춘다
문제
- 설정에 중첩된 클래스를 요청 처리기 목록(ARE_REQUEST_HANDLER_TYPES)으로만
  본다. 이 목록에는 JAX-RS와 주석형 JSR-356 타입이 없어서, 설정 안에 둔
  JAX-RS 자원이나 @ServerEndpoint가 @SystemCaller를 불러도 잡히지 않는다.
  r9는 잡았다(RR7-01-01, 회귀).
- 메서드 참조로 route만 등록한 설정도 사용자 전송으로 센다. 그런데 Javadoc,
  매뉴얼 07, 업그레이드 안내 B-16은 "요청 처리 코드가 있을 때만"이라고 적어,
  안내대로 처리 코드를 옮겨도 빌드가 실패한다(RR7-01-02). 같은 원인으로
  CORS 설정에 쓰는 RequestMethod도 설정을 사용자 전송으로 만든다.

고른 방법
- 설정 클래스 자신만 요청 처리기 목록으로 본다. 중첩 클래스는 r9처럼 사용자
  전송 타입 전체로 본다. 설정용 타입(ARE_TRANSPORT_SETUP_TYPES: MVC·WebFlux·
  WebSocket·STOMP broker 설정 패키지, CORS 설정, RequestMethod)에만 의존하는
  중첩 클래스는 설정의 일부로 둔다. 설정 필드를 읽는 익명 WebMvcConfigurer
  (RR6-01-02)가 이 경우다. 목록에 없는 타입은 잡히는 쪽(거짓 실패)으로 간다.
- RR7-01-02는 판정을 좁히지 않고 문서를 동작에 맞췄다. route·data fetcher·
  interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다. 실패
  메시지에도 이 안내를 넣었다. RequestMethod만 설정용 타입으로 뺐다.
- 두 목록이 다시 갈라지지 않게 UserTransportTypeListsTest를 더했다. 요청
  처리기·설정용 항목은 모두 사용자 전송 타입이어야 하고, 설정용 항목은 요청
  처리기 타입을 덮지 않아야 한다.
- 버린 대안:
  - 중첩 클래스에서 바깥 설정으로 가는 의존을 따라가지 않기(리뷰 권장안).
    중첩 endpoint가 설정의 메서드를 거쳐 작업을 부르는 길을 놓친다. r9는
    잡던 길이다. 위반 fixture RunNowThroughTheConfigurationFixture로 고정했다.
  - 요청 처리기 목록에 JAX-RS·JSR-356 타입을 더하기. 목록에 없는 다음
    라이브러리에서 같은 구멍이 난다.
  - 설정 판정을 "요청을 받는 메서드"(파라미터·annotation·상속)로 좁히기.
    route builder 람다(b -> b.GET(...))도 builder를 받아 목록이 또 필요하고
    규칙이 복잡해진다.
  - @CrossOrigin·HttpServletRequest는 설정용 타입으로 빼지 않았다.
    @CrossOrigin은 handler에만 붙고, HttpServletRequest를 받는 람다(matcher,
    CORS source)는 요청마다 돈다.

위험·한계
- 판정이 넓어진 곳: 설정에 중첩된 클래스가 설정용이 아닌 웹 타입(예:
  HandlerMethodArgumentResolver, RestClient)을 쓰고 설정 필드를 읽으며, 그
  설정이 @SystemCaller bean을 만들면 이제 실패한다. r9와 같고 r10보다 엄격하다.
  그 타입이 기동 때만 도는 설정용 타입이면 목록에 더한다.
- JAX-RS·JSR-356 런타임 기동은 보지 않았다. 규칙 판정만 봤다.

검증 (desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f2-arch-rules-logs/)
- RED: 73d39212에 테스트·fixture만 얹고 ArchitectureViolationFixtureTest
  실행. 87건 중 5건 실패: 중첩 JAX-RS·설정 경유·@ServerEndpoint 셋은 위반
  0건, CORS 두 모양은 거짓 위반. rc=1.
- GREEN: :app-bootstrap:architectureTest --rerun 237건 실패 0, rc=0.
- 변이: 설정용 목록에 servlet.function, 요청 처리기 목록에 io.vertx.ext.web을
  넣으면 UserTransportTypeListsTest 2건과 fixture 테스트 3건이 실패했다.
- :app-bootstrap:check, architectureCheck, :app-bootstrap:testQualityCheck,
  :ci :verifyDependencyLocks --warning-mode=fail, :verifyStrictLaneStages
  --dry-run, :sample-portfolio:check :sample-portfolio:qualityCheck,
  -p optional-platforms ci, -p optional-platforms :verifyStrictLaneStages
  --dry-run, scripts/verify-compose-profile-contracts.sh 모두 rc=0.
- 매뉴얼 07과 업그레이드 안내를 읽는 테스트는 없다(src grep 0건).
  check-work-docs.py --links docs: 깨진 링크 0.

BREAKING CHANGE: 설정(@Configuration)에 중첩된 클래스를 사용자 전송 타입 전체로
판정한다. 그 안의 JAX-RS 자원·@ServerEndpoint 같은 endpoint가 @SystemCaller에
닿으면(설정의 메서드를 거쳐도) architectureTest가 실패한다. route·data fetcher·
interceptor 등록은 handler bean을 만드는 설정과 다른 설정에 둔다
(docs/upgrade/2026-11-maturity-review.md B-16).
Refs: docs/reviews/2026-11-03-rereview/round7/01-core-inbound.md RR7-01-01, RR7-01-02
2026-11-07 01:09:54 +09:00
..

개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점

이 매뉴얼은 새 업무 기능을 추가하는 사람이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 가리키고 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).

입구는 작업 매뉴얼의 새 기능 playbook이다. 일의 크기, 완료 기준, 하지 말 것은 거기에 있다. 새 기능이 아닌 일(개선, 조사·설계, 문서, 운영)은 docs/work/가 맡는다.

판단 지점은 모두 같은 틀로 적는다.

  • 고르는 기준 — 무엇을 보고 고르는가
  • 기본값 — 기준이 애매하면 이것
  • 예외 — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것

근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.

읽는 순서

처음이면 1 → 2 → 3을 읽고 생성 명령을 한 번 돌려 본다. 그다음은 기능에 필요한 장만 읽는다.

장 언제 읽나
01. 생성 명령 새 기능 뼈대를 만들 때. 무엇을 만들고 무엇을 안 만드는지
02. 새 도메인·유스케이스 추가 기능 하나를 domain → application → outbound → inbound → bootstrap 순서로 만들 때
03. 새 기능을 둘 곳 고르기 계층 leaf 안 패키지 / application-* capability / 별도 수직 중 고를 때
04. 영속성 저장 adapter, 엔티티 매핑, DB 제약과 충돌 변환, 마이그레이션 번호
05. 멱등성·결과 불명 재시도될 수 있는 쓰기, 409/422, DB_COMPLETION_UNKNOWN
06. 오류 모델 실패를 클라이언트 탓/서버 탓으로 나누고 코드로 내보낼 때
07. 권한 @RequiresPermission, 역할 매핑, 객체 단위 인가
08. 테스트 작성 규칙 포트당 fake, 공유 계약, 이름·주석, lane 단계 지정
09. outbox·이벤트 저장과 함께 이벤트를 내보낼 때
10. capability 추가·제거 JPA·Redis·Kafka 같은 부가 기능을 켜고 끌 때
11. 체크리스트 PR 올리기 전
부록. 공통 원칙 후보 프론트·백엔드 공통 실무 원칙으로 옮길 후보

정본 위치

매뉴얼과 정본이 다르면 정본이 맞다. 매뉴얼을 고친다.

무엇 정본
계층 경계·금지 규칙·테스트 작성 규칙 AGENTS.md(작업 지도는 CLAUDE.md)
leaf 목록·허용 의존 src/config/architecture/modules.json
이름 규칙(유스케이스·포트·command·query) src/application-core/CLAUDE.md 「Naming convention」. 기계 검사는 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java와 ApplicationBoundaryArchitectureTest.java
유스케이스 모양·트랜잭션 모양 src/application-core/CLAUDE.md 「Canonical use case shape」「Allowed transactional shapes」
HTTP wire 계약(Envelope·멱등성 응답) docs/web/http-contract.md
운영 오류 코드 docs/registries/error-codes.yaml, src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java
엔티티 매핑·마이그레이션 docs/jpa/entity-mapping-guide.md, docs/jpa/migration-guide.md, docs/jpa/transaction-guide.md
capability 완료 기준 7개 AGENTS.md 「부가 기능(capability) 모듈 규칙」

이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 따른 결과를 보여 줄 뿐이고, 규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(scripts/feature-scaffold/templates/)이 규칙과 어긋나면 scripts/verify-feature-scaffold.sh가 ArchUnit으로 잡는다.

따라 할 예시는 하나

예시가 셋(sample-portfolio 수직, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라 배치가 달라졌다(리뷰 2026-11-01 01-01·07-09). 이제 새 업무 기능의 예시는 생성 명령의 출력 하나다.

코드 역할 따라 하나
scripts/new-feature.sh 출력 계층 leaf에 나눈 업무 기능 이것을 따른다
src/sample-portfolio 한 leaf에 모든 계층을 둔 지울 수 있는 샘플. 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일성 제약)의 참고 기법만 본다. 배치는 따르지 않는다
src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/** ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture 따르지 않는다
application-core/.../operation + DurableOperationAutoConfiguration(composition:durable-operation) 템플릿 플랫폼 기능 조립 모양(@ConditionalOnBean + 유스케이스 @Bean)만 본다

1라운드 수정으로 생긴 패턴 (리뷰 README 13절)

리뷰 뒤 1라운드에서 굳은 모양이다. 각 장에 반영했다.

패턴 근거 코드 장
Envelope는 null 필드를 내보내지 않는다 docs/web/http-contract.md 1절 06
처리 중 409 IDEMPOTENT_IN_FLIGHT는 retryable=true + Retry-After: 2, 같은 키로 재전송 docs/web/http-contract.md 2절 05
커밋 중 연결이 끊기면 재시도 가능이 아니라 결과 불명(DB_COMPLETION_UNKNOWN, 500) src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java, docs/adr/ADR-JPA-003-completion-unknown.md 05
중복 규칙은 조회 후 insert가 아니라 DB 유일성 제약, 위반은 같은 409로 변환 src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql, PosterRepositoryAdapter 04
여러 인스턴스가 집는 작업은 lease 있는 claim ReconciliationJobStorePort.claimDue(application-notification) 04
양방향 연관관계 금지를 ArchUnit으로 JpaArchitectureRules.associationsAreMappedFromOneSideOnly() 04
store는 호출자 트랜잭션을 요구한다 src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java 04
@RequiresPermission 검사는 인증 체인과 분리된 자동 설정 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java 07
JWT audience 필수, 자기 client role만 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/JwtDecoderConfig.java, docs/runbooks/auth-audience-mismatch.md 07
strict lane은 반드시 어떤 단계에 속한다 verifyStrictLaneStages(src/build.gradle strictLaneStages) 08
샘플 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 SamplePostgreSqlPersistenceConfig, V8_1__… 04
재시도 가능한 broker 거부는 DEAD가 아니라 재시도 docs/runbooks/outbox-dead-letter.md 09