fix(arch): 아키텍처 규칙이 놓친 HARD-STOP 2 사각지대 다섯을 닫는다 #19

Closed
donghyeon.kang wants to merge 0 commits from claude/r9-arch-rules into main
Owner

무엇을, 왜

round9 리뷰의 High 둘(RR9-05-01·02)과 같은 원인의 Medium 셋(RR9-05-03~05)을 고친다. 저장소 전체 ArchUnit suite가 HARD-STOP 2와 매뉴얼 07 「시스템이 부르는 쓰기」의 약속을 막지 못하는 길이 다섯이었다.

발견 길 고친 것
RR9-05-01 High controller·gRPC 서비스가 domain *Repository(생성 명령이 dev.caskeleton.domain.<feature>에 둠)·application *StorePort·*QueryPort를 들어도 통과 새 규칙 ENDPOINTS_DO_NOT_HOLD_PERSISTENCE_PORTS
RR9-05-02 High ..adapter.inbound.. 밖 사용자 전송이나 표시 없는 중간 클래스를 거쳐 @SystemInvoked 유스케이스에 닿아도 통과, bootstrap controller 금지가 문서뿐 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS 전이 대상에 @SystemInvoked 유스케이스, 새 규칙 CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS
RR9-05-03 web 밖 Spring Security 확장점(JWT converter, AuthorizationManager, AuthenticationProvider, chain DSL)이 사용자 전송이 아님 보안 패키지·타입을 사용자 전송·요청 처리기 목록에
RR9-05-04 설정이 interceptor를 자기 클래스 필드로 쥐고 registration.interceptors(x)로 넘기면 설정이 안 걸림 요청 처리기 타입을 상속·구현한 프로젝트 클래스에 의존하는 설정도 사용자 전송
RR9-05-05 capabilityProjects에 inbound messaging이 없어 suite가 그 모듈을 못 읽음 목록과 주석 처리된 runtimeOnly 줄에 더함

매뉴얼 07 규칙 표와 app AGENTS.md를 같이 고쳤다.

고른 방법과 버린 대안

  • inbound가 application *Port 전부를 못 쓰게 하는 안은 버렸다. web이 AuthorizationPort·CorrelationIdPort를 구현·사용해 맞는 코드가 걸린다. 그래서 영속 포트(*Repository·*StorePort·*QueryPort)와 endpoint(controller·gRPC 서비스)로 좁혔다.
  • *IdFactory는 지금 DurableOperationController가 쓰고 있어 규칙에서 뺐다. 그 controller의 id 생성은 RR9-05-13으로 따로 고친다.

위험과 영향

  • 지금 운영 코드에서 걸리는 곳은 없다(전체 suite 259건 통과). 파생 서비스가 controller에 repository 포트를 주입했거나 조립 모듈에 controller를 두었다면 architectureCheck가 새로 실패한다 — 문서에 이미 적힌 금지(HARD-STOP 2, app AGENTS)를 검사가 지키게 된 것이다.
  • 규칙 3·4는 목록·클래스 의존 방식이라 타입 이름이 남지 않는 길(bean 이름 조회, 함수로 감싸 넘기기)은 여전히 못 본다(매뉴얼 07 「규칙이 못 보는 길」).
  • gRPC 서비스 fixture는 io.grpc가 architectureTest 컴파일 classpath에 없어 두지 않았다(판정은 io.grpc.BindableService 이름).

검증

desktop, --no-build-cache, 로그 ~/r9-be-logs/b14-{red,green2}.log.

  • RED: 기준 a7e38c10 + 새 fixture·시험(새 규칙 대신 기존 규칙을 부르는 변형)만으로 ArchitectureViolationFixtureTest 204건 중 5건 실패 — 다섯 위반 모두 기존 규칙에 안 걸림. 허용 시험은 통과.
  • GREEN: :app-bootstrap:resolveAndLockAll --write-locks(잠금 변화 없음), spotlessApply 뒤 :app-bootstrap:architectureTest 259건 실패 0, :app-bootstrap:testQualityCheck, :app-bootstrap:spotlessCheck, :verifyDependencyLocks, :architectureCheck rc=0.
  • 노트북: check-docs.py rc=0. check-work-docs.py는 main의 operate.md 151줄 때문에만 rc=1(PR #15가 고침).

리뷰어가 볼 곳

  • ApplicationBoundaryArchitectureTest의 ARE_PROJECT_REQUEST_HANDLERS: 설정이 쥔 프로젝트 클래스의 상위 타입 판정. 설정용 타입(WebMvcConfigurer 등)을 구현한 익명 클래스는 빼서 기존 허용 fixture가 그대로 통과한다.
  • AdapterBoundaryArchitectureTest의 ARE_PERSISTENCE_PORTS 이름 규칙.

관련

  • 리뷰 기록: PR #17 docs/reviews/2026-11-12-round9-review/ RR9-05-01~05.
## 무엇을, 왜 round9 리뷰의 High 둘(RR9-05-01·02)과 같은 원인의 Medium 셋(RR9-05-03~05)을 고친다. 저장소 전체 ArchUnit suite가 HARD-STOP 2와 매뉴얼 07 「시스템이 부르는 쓰기」의 약속을 막지 못하는 길이 다섯이었다. | 발견 | 길 | 고친 것 | |---|---|---| | RR9-05-01 High | controller·gRPC 서비스가 domain `*Repository`(생성 명령이 `dev.caskeleton.domain.<feature>`에 둠)·application `*StorePort`·`*QueryPort`를 들어도 통과 | 새 규칙 `ENDPOINTS_DO_NOT_HOLD_PERSISTENCE_PORTS` | | RR9-05-02 High | `..adapter.inbound..` 밖 사용자 전송이나 표시 없는 중간 클래스를 거쳐 `@SystemInvoked` 유스케이스에 닿아도 통과, bootstrap controller 금지가 문서뿐 | `USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS` 전이 대상에 `@SystemInvoked` 유스케이스, 새 규칙 `CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS` | | RR9-05-03 | web 밖 Spring Security 확장점(JWT converter, `AuthorizationManager`, `AuthenticationProvider`, chain DSL)이 사용자 전송이 아님 | 보안 패키지·타입을 사용자 전송·요청 처리기 목록에 | | RR9-05-04 | 설정이 interceptor를 자기 클래스 필드로 쥐고 `registration.interceptors(x)`로 넘기면 설정이 안 걸림 | 요청 처리기 타입을 상속·구현한 프로젝트 클래스에 의존하는 설정도 사용자 전송 | | RR9-05-05 | `capabilityProjects`에 inbound messaging이 없어 suite가 그 모듈을 못 읽음 | 목록과 주석 처리된 `runtimeOnly` 줄에 더함 | 매뉴얼 07 규칙 표와 app `AGENTS.md`를 같이 고쳤다. ## 고른 방법과 버린 대안 - inbound가 application `*Port` 전부를 못 쓰게 하는 안은 버렸다. web이 `AuthorizationPort`·`CorrelationIdPort`를 구현·사용해 맞는 코드가 걸린다. 그래서 영속 포트(`*Repository`·`*StorePort`·`*QueryPort`)와 endpoint(controller·gRPC 서비스)로 좁혔다. - `*IdFactory`는 지금 `DurableOperationController`가 쓰고 있어 규칙에서 뺐다. 그 controller의 id 생성은 RR9-05-13으로 따로 고친다. ## 위험과 영향 - 지금 운영 코드에서 걸리는 곳은 없다(전체 suite 259건 통과). 파생 서비스가 controller에 repository 포트를 주입했거나 조립 모듈에 controller를 두었다면 `architectureCheck`가 새로 실패한다 — 문서에 이미 적힌 금지(HARD-STOP 2, app AGENTS)를 검사가 지키게 된 것이다. - 규칙 3·4는 목록·클래스 의존 방식이라 타입 이름이 남지 않는 길(bean 이름 조회, 함수로 감싸 넘기기)은 여전히 못 본다(매뉴얼 07 「규칙이 못 보는 길」). - gRPC 서비스 fixture는 `io.grpc`가 architectureTest 컴파일 classpath에 없어 두지 않았다(판정은 `io.grpc.BindableService` 이름). ## 검증 desktop, `--no-build-cache`, 로그 `~/r9-be-logs/b14-{red,green2}.log`. - RED: 기준 `a7e38c10` + 새 fixture·시험(새 규칙 대신 기존 규칙을 부르는 변형)만으로 `ArchitectureViolationFixtureTest` 204건 중 5건 실패 — 다섯 위반 모두 기존 규칙에 안 걸림. 허용 시험은 통과. - GREEN: `:app-bootstrap:resolveAndLockAll --write-locks`(잠금 변화 없음), `spotlessApply` 뒤 `:app-bootstrap:architectureTest` 259건 실패 0, `:app-bootstrap:testQualityCheck`, `:app-bootstrap:spotlessCheck`, `:verifyDependencyLocks`, `:architectureCheck` rc=0. - 노트북: `check-docs.py` rc=0. `check-work-docs.py`는 main의 `operate.md` 151줄 때문에만 rc=1(PR #15가 고침). ## 리뷰어가 볼 곳 - `ApplicationBoundaryArchitectureTest`의 `ARE_PROJECT_REQUEST_HANDLERS`: 설정이 쥔 프로젝트 클래스의 상위 타입 판정. 설정용 타입(`WebMvcConfigurer` 등)을 구현한 익명 클래스는 빼서 기존 허용 fixture가 그대로 통과한다. - `AdapterBoundaryArchitectureTest`의 `ARE_PERSISTENCE_PORTS` 이름 규칙. ## 관련 - 리뷰 기록: PR #17 `docs/reviews/2026-11-12-round9-review/` RR9-05-01~05.
donghyeon.kang added 1 commit 2026-11-12 15:28:25 +00:00
문제: 저장소 전체 ArchUnit suite가 약속한 것을 막지 못하는 길이 다섯이다.
1. controller가 domain repository 포트(생성 명령이 aggregate 옆
   dev.caskeleton.domain.<feature>에 두는 <Aggregate>Repository)를 주입해도
   걸리지 않는다. 규칙은 ..repository.. 패키지와 Spring Data·JPA 타입만 본다.
   gRPC 서비스는 controller 판정에 들지 않는다(HARD-STOP 2).
2. ..adapter.inbound.. 밖의 사용자 전송(조립 모듈의 controller 등)이
   @SystemInvoked 유스케이스를 new로 만들어 부르거나, 표시 없는 중간 클래스를
   거쳐 부르면 통과한다. 매뉴얼 07은 이것을 "빌드 실패"라고 약속한다. app
   AGENTS의 "bootstrap에 controller 금지"도 검사가 없다.
3. web 패키지 밖에 둔 Spring Security 요청 경로 확장점(JWT converter,
   AuthorizationManager, AuthenticationProvider, 필터 chain DSL)은 servlet 타입을
   쓰지 않아 사용자 전송으로 보이지 않는다.
4. 설정이 interceptor를 자기 클래스 타입 필드로 쥐고
   registration.interceptors(x)로 넘기면, ArchUnit 1.3은 ChannelRegistration
   (설정용 타입)만 기록해 설정이 사용자 전송이 되지 않는다.
5. capabilityProjects에 :adapter:inbound:messaging이 없어 저장소 전체 suite가
   MessagingInboxAutoConfiguration을 읽지 않는다("suite가 모든 모듈을 본다"는
   주석과 다름).

고른 방법:
1. ENDPOINTS_DO_NOT_HOLD_PERSISTENCE_PORTS: controller와 gRPC 서비스는
   ..domain..·..application..의 *Repository·*StorePort·*QueryPort에 의존하지
   않는다.
2. CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS, 그리고
   USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS의 전이 대상에 @SystemInvoked
   유스케이스 자신을 더한다.
3. org.springframework.security.web·config.annotation.web·
   oauth2.server.resource·oauth2.jwt 패키지와 AuthenticationProvider·
   AuthorizationManager를 사용자 전송·요청 처리기 목록에 더한다.
4. 설정이 의존하는 프로젝트 클래스가 요청 처리기 타입을 상속·구현하면 그
   설정도 사용자 전송으로 본다.
5. capabilityProjects와 주석 처리된 runtimeOnly 줄에 inbound messaging을 더한다.
매뉴얼 07 표와 app AGENTS를 같이 고쳤다. 지금 운영 코드에 걸리는 곳은
없다(inbound가 그런 포트를 import한 곳 0, 조립 모듈 controller 0).
버린 대안: inbound가 application *Port 전부를 못 쓰게 하기 — web이
AuthorizationPort·CorrelationIdPort를 구현하고 쓰므로 맞는 코드가 걸린다.
IdFactory는 지금 DurableOperationController가 쓰고 있어 이번 규칙에서 뺐다
(그 controller의 id 생성은 리뷰 RR9-05-13로 따로 고친다).

위험·한계: 규칙 3·4는 목록·클래스 의존 방식이라, 목록에 없는 보안 타입이나
타입 이름이 남지 않는 길(bean 이름 조회, 함수로 감싸 넘기기)은 여전히
못 본다(매뉴얼 07 「규칙이 못 보는 길」). gRPC 서비스 fixture는 io.grpc가
architectureTest 컴파일 classpath에 없어 두지 않았다 — 판정은
BindableService 이름으로 한다.

검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 새 fixture와 시험(새 규칙 대신 기존 규칙을 부르는
  변형)만으로 ArchitectureViolationFixtureTest 204건 중 5건 실패 — 다섯 위반
  모두 기존 규칙에 안 걸림. 허용 시험은 통과.
- GREEN: :app-bootstrap:resolveAndLockAll --write-locks(잠금 변화 없음),
  spotlessApply 뒤 :app-bootstrap:architectureTest 259건 실패 0,
  :app-bootstrap:testQualityCheck, :app-bootstrap:spotlessCheck,
  :verifyDependencyLocks, :architectureCheck rc=0. 로그 desktop
  ~/r9-be-logs/b14-{red,green2}.log.

Refs: docs/reviews/2026-11-12-round9-review RR9-05-01~05
donghyeon.kang added 1 commit 2026-11-12 16:55:03 +00:00
Merge branch 'main' into claude/r9-arch-rules
pr / done (pull_request) Canceled after 0s
692f8fba71
donghyeon.kang added 1 commit 2026-11-12 17:00:30 +00:00
Merge branch 'main' into claude/r9-arch-rules
pr / done (pull_request) Canceled after 2m37s
b86ef0e8dd
donghyeon.kang added 1 commit 2026-11-12 18:58:58 +00:00
Merge branch 'main' into claude/r9-arch-rules
pr / done (pull_request) Canceled after 0s
3df1685104
Author
Owner

#28로 병합됐다(main 3d31896a). 이 PR의 head 3df16851가 #28 브랜치에 merge 커밋으로 들어 있고, #28의 runner pr / done이 그 합친 트리로 초록이었다. runner 대기를 줄이려고 이번만 쓴 방식이다(소유자 승인, 2026-11-13).

#28로 병합됐다(main `3d31896a`). 이 PR의 head `3df16851`가 #28 브랜치에 merge 커밋으로 들어 있고, #28의 runner `pr / done`이 그 합친 트리로 초록이었다. runner 대기를 줄이려고 이번만 쓴 방식이다(소유자 승인, 2026-11-13).
donghyeon.kang closed this pull request 2026-11-12 23:28:30 +00:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#19