diff --git a/src/adapter/inbound/web/CLAUDE.md b/src/adapter/inbound/web/CLAUDE.md index f4903614..b31212eb 100644 --- a/src/adapter/inbound/web/CLAUDE.md +++ b/src/adapter/inbound/web/CLAUDE.md @@ -59,7 +59,7 @@ bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adap - **B1 — 요청 경계의 Jackson 정책.** `spring.jackson.deserialization`이 `fail-on-unknown-properties`, `fail-on-null-for-primitives`, `fail-on-ignored-properties`를 `true`로, `read-unknown-enum-values-as-null`을 `false`로 고정한다. 클래스 수준 `@JsonIgnoreProperties(ignoreUnknown = true)`로 DTO마다 이것을 되돌리지 - **않는다** — ArchUnit 규칙 `request_dtos_do_not_silence_unknown_fields`가 막는다. 요청 record에는 + **않는다** — ArchUnit 규칙 `REQUEST_DTOS_DO_NOT_SILENCE_UNKNOWN_FIELDS`가 막는다. 요청 record에는 wrapper 타입(`Integer`, `Long`, `Boolean`, `Optional`)을 써서 JSON `null`이 primitive `0`이 되지 못하게 한다. - **B2 — PATCH 뜻.** RFC 7396 `application/merge-patch+json`(`null = 삭제`)을 쓰지 않는다. PATCH endpoint는 @@ -74,10 +74,10 @@ bridge, `JsonIdempotentResponseCodec`, route 목록)는 골라 쓰는 leaf `adap `@Valid` cascade 깊이는 3 이하로 둔다. - **B5 — 다형 역직렬화.** `ObjectMapper.enableDefaultTyping()` / `activateDefaultTyping()`을 부르거나 `LaissezFaireSubTypeValidator`를 참조하는 것은 CVE-2019-14379 RCE의 입구이고 ArchUnit이 막는다 - (`no_jackson_laissez_faire_subtype_validator`, `no_jackson_enable_default_typing_call`). sealed `Command` + (`NO_JACKSON_LAISSEZ_FAIRE_SUBTYPE_VALIDATOR`, `NO_JACKSON_ENABLE_DEFAULT_TYPING_CALL`). sealed `Command` 타입은 `@JsonTypeInfo(use = NAME)` + `@JsonSubTypes`나 `BasicPolymorphicTypeValidator` 허용 목록을 쓴다. - **B6 — virtual thread 문맥 전파.** `spring.threads.virtual.enabled=true`이면 `InheritableThreadLocal`을 쓰지 - 않는다(ArchUnit 규칙 `no_inheritable_thread_local`). filter와 interceptor는 SLF4J 2.0+ MDC나 + 않는다(ArchUnit 규칙 `NO_INHERITABLE_THREAD_LOCAL`). filter와 interceptor는 SLF4J 2.0+ MDC나 `RequestContextHolder`로 `requestId` / `traceId`를 전파한다. - **B7 — outbound ACL mapper 범위.** outbound HTTP·메시징 어댑터의 응답은 `application-core`나 `domain-core`에 닿기 전에 ACL mapper(정규화, 가리기, 공개 필드 고르기)를 거친다 — inbound와 같은 경계 계약이다. 외부 응답 @@ -101,7 +101,7 @@ catch-all `@ExceptionHandler(Exception.class)`가 도메인 예외를 `INTERNAL_ *요청을 받는* 정책의 짝이다. 역직렬화 스위치(B1)와 null·빈 값·없음 세 상태(`Patch` + `JsonNullable`, B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. Jackson 속성은 `app-bootstrap`의 `application.yml`(`spring.jackson.deserialization.*`, `spring.jackson.datatype.*`)에 있다. ArchUnit과 실제 -설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `no_bigdecimal_double_constructor`). +설정 시험도 `app-bootstrap`에 있다(`JacksonSerializationPolicyTest`, `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`). - **S1 — 날짜·시간·시간대.** `WRITE_DATES_AS_TIMESTAMPS=false`로 고정하므로 `java.time` 값은 `JavaTimeModule`을 거쳐 ISO-8601 문자열로 직렬화한다(`OffsetDateTime` → `"...Z"`, `LocalDate` → @@ -116,7 +116,7 @@ B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. 때 정한다. - **S3 — `new BigDecimal(double)`은 금지다.** `double`/`float` 생성자는 이진 부동소수점 오차를 담는다 (`new BigDecimal(0.1)` ≠ `0.1`). `String`(`new BigDecimal("0.1")`)이나 `BigDecimal.valueOf(double)`로 - 만든다. ArchUnit 규칙 `no_bigdecimal_double_constructor`가 강제한다. + 만든다. ArchUnit 규칙 `NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR`가 강제한다. - **S4 — enum과 null·빈 값·없음.** 요청 쪽의 모르는 enum → `VALIDATION_FAILED`(B1 `read-unknown-enum-values-as-null=false`). 옛 값은 명시한 어댑터로 대응시키고 소리 없는 대체값을 쓰지 않는다. 없음·명시한 null·값의 구별은 inbound web mapper(Controller DTO → Command)가 가지고 `Patch`(B2)로 @@ -134,7 +134,7 @@ B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. | 층 | 소유 | 검증하는 것 | `error.category` | 강제하는 곳 | |---|---|---|---|---| -| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `validation_constraints_stay_at_web_boundary` | +| 문법·모양 | `adapter:inbound:web` 요청 DTO(`@Valid` / `jakarta.validation`) | 요청 모양, 타입, 필수 필드 | `VALIDATION` | ArchUnit 규칙 `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY` | | 유스케이스 정책 | `application-core` | 인가, aggregate를 가로지르는 정책, 상태 전제 조건 | `AUTHZ` / `CONFLICT` | `BusinessRuleValidationContractTest` | | 도메인 불변식 | `domain-core` 모델·값 객체 **생성자** | 업무 불변식(예: end ≥ start) | `CONFLICT` / `VALIDATION` | 도메인 단위 시험(예: `PeriodTest`) — 생성자가 유일하고 바뀌지 않는 생성 경로다 | | 영속 무결성 | `adapter:outbound:persistence-jpa`(번역기는 `feature-persistence-failure-baseline`의 것) | unique / FK / check / serialization | `DATA_INTEGRITY` / `CONFLICT` | `BusinessRuleValidationContractTest` + 누출 시험 | @@ -142,7 +142,7 @@ B2)가 이미 inbound 쪽을 덮고, 아래 규칙이 outbound 쪽을 덮는다. - **C1 — 검증 애너테이션은 web 경계에 머문다.** `jakarta.validation`(`@NotNull`, `@Valid`, …)은 `adapter:inbound:web`에만 나와야 한다. `domain-core`와 `application-core`는 불변식과 정책을 평범한 Java로 나타낸다. Bean Validation 애너테이션이 `..domain..`이나 `..application..`으로 새면 ArchUnit 규칙 - `validation_constraints_stay_at_web_boundary`가 빌드를 실패시킨다. + `VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`가 빌드를 실패시킨다. - **C2 — 업무 불변식은 도메인에 있고 우회할 수 없다.** 불변식은 값 객체·엔티티 **생성자**(유일한 생성 경로)에서 강제하고 타입을 불변으로 둔다. 그래서 어떤 application service나 영속 경로도 불변식을 어긴 인스턴스를 내줄 수 없다. DB 제약은 뒷받침일 뿐 유일한 검사가 아니다(금지: 「불변식을 DB 제약으로만 diff --git a/src/adapter/outbound/identifier/CLAUDE.md b/src/adapter/outbound/identifier/CLAUDE.md index f3addd83..0d021b3a 100644 --- a/src/adapter/outbound/identifier/CLAUDE.md +++ b/src/adapter/outbound/identifier/CLAUDE.md @@ -38,7 +38,7 @@ ## 금지 - 영속·web 기술(JPA/Hibernate/Spring Data/Spring Web) — ArchUnit - `identifier_adapter_does_not_depend_on_other_adapters_or_bootstrap`와 registry 방향 게이트가 막는다. + `IDENTIFIER_ADAPTER_DOES_NOT_DEPEND_ON_OTHER_ADAPTERS_OR_BOOTSTRAP`와 registry 방향 게이트가 막는다. - inbound 어댑터, 영속 어댑터, 다른 outbound leaf, `app-bootstrap`. - 외부 IO(HTTP / 메시징 / cache / DB) — 그것은 IO를 하는 outbound 어댑터 leaf에 둔다. diff --git a/src/adapter/outbound/persistence-jpa/CLAUDE.md b/src/adapter/outbound/persistence-jpa/CLAUDE.md index a0ff79f3..cb4f403f 100644 --- a/src/adapter/outbound/persistence-jpa/CLAUDE.md +++ b/src/adapter/outbound/persistence-jpa/CLAUDE.md @@ -298,7 +298,7 @@ PostgreSQL `57P01`, `57P02`), SQLState 없는 전송 끊김을 가진 실패는 감사 metadata(`created_at` / `updated_at` / `created_by` / `updated_by`)는 기반 관심사이고 `domain-core`에 닿으면 안 된다. `audit/AuditableEntity` `@MappedSuperclass`에만 있다. 도메인 aggregate의 영속 엔티티가 그것을 상속해서 고른다(생성 명령이 만드는 서비스 persistence leaf의 엔티티가 그렇게 한다). 도메인 aggregate 자체는 감사 필드를 하나도 갖지 않는다. -ArchUnit `domain_is_pure`(`jakarta.persistence..` 없음)와 `domain_entities_do_not_carry_audit_fields`(`..domain..` 아래에 +ArchUnit `DOMAIN_IS_PURE`(`jakarta.persistence..` 없음)와 `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS`(`..domain..` 아래에 `createdAt`/`updatedAt`/`createdBy`/`updatedBy` 필드 없음)가 강제한다. - **잡기 = 손으로 명시해 넣기(지금 기본).** repository 어댑터가 생성자로 `Clock`과 `AuditContextPort`를 받고 `save`에서 diff --git a/src/application-core/CLAUDE.md b/src/application-core/CLAUDE.md index fb6ecce2..0a8a6bf0 100644 --- a/src/application-core/CLAUDE.md +++ b/src/application-core/CLAUDE.md @@ -39,7 +39,7 @@ - HTTP 상태, 전송 타입(`org.springframework.web..`). - `org.springframework.transaction.annotation.Transactional`(대신 `TransactionPort`를 쓴다). - `org.springframework.context.ApplicationContext` — 직접 의존 금지 - (`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `application_does_not_depend_on_application_context`가 막는다). 문자열 키로 + (`getBean(Class)` 같은 리플렉션식 우회는 ArchUnit 규칙 `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT`가 막는다). 문자열 키로 bean을 찾기, `Class.forName(String)`, `BeanFactory#getBeansOfType`은 ArchUnit 정적 분석이 보지 못하는 곳이다. 코드 리뷰 체크리스트로 막는다. - Lombok(`lombok..`) — `domain-core`에서도 금지다. `application-core`에서는 지금 Lombok이 @@ -302,7 +302,7 @@ hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 - **순수성 가드레일(core, 기계로 강제):** 단순 이름이 `QueryPort`로 끝나는 읽기 포트는 반드시 애플리케이션 계층 projection DTO만 돌려준다 — 도메인 aggregate, JPA 엔티티, web 타입은 **제네릭 타입 인자를 거쳐서도**(`List`) 안 된다. ArchUnit - `query_ports_do_not_leak_domain_jpa_or_web_types`가 강제한다. projection 사용 자체는 강요된 기본이 + `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`가 강제한다. projection 사용 자체는 강요된 기본이 아니라 **선택**이다. - **엄격한 절차:** 모든 읽기는 `QueryUseCase` bean을 거친다. web → 읽기 포트로 바로 가는 얇은 경로는 없다. 그런 경로는 필수인 `@UseCaseCapability` 적합성 검사를 건너뛴다. @@ -316,13 +316,13 @@ hikari.maximumPoolSize >= (concurrent_threads × (1 + max_inNew_depth)) + 1 ## ArchUnit 가드레일(강제됨) -- `application_does_not_depend_on_adapters_or_transport` -- `application_does_not_use_spring_transactional_annotation` -- `application_does_not_depend_on_application_context` +- `APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT` +- `APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION` +- `APPLICATION_DOES_NOT_DEPEND_ON_APPLICATION_CONTEXT` - `APPLICATION_HAS_NO_DIAGNOSTIC_FRAMEWORK` -- `inbound_port_implementations_end_with_use_case` -- `inbound_port_implementations_declare_capability` -- `query_ports_do_not_leak_domain_jpa_or_web_types`(`*QueryPort` 반환 순수성) +- `INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE` +- `INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY` +- `QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES`(`*QueryPort` 반환 순수성) ## 테스트 diff --git a/src/application-core/README.md b/src/application-core/README.md index cce525f4..026f6593 100644 --- a/src/application-core/README.md +++ b/src/application-core/README.md @@ -117,10 +117,10 @@ JSON Schema diff로 호환성을 검사하는 fixture: payload schema가 닫혀 - 외부 `*Port`(outbound adapter 에 바인딩된 포트)를 호출하려면 `externalOutboundAllowed = true` 가 필요하다. 없으면 outbound 어댑터 호출 금지. - `repositoryAccess` 가 `WRITE_REPOSITORY` 가 아닌 유스케이스는 리포지토리 포트의 쓰기 - 메서드(save/delete/update/insert)를 호출할 수 없다 — `read_only_use_cases_do_not_call_repository_write_methods` + 메서드(save/delete/update/insert)를 호출할 수 없다 — `READ_ONLY_USE_CASES_DO_NOT_CALL_REPOSITORY_WRITE_METHODS` 규칙이 막는다. 단 정적 분석은 **직접 호출만** 잡으므로, helper/mapper 를 거친 쓰기는 리뷰가 본다. - `bulkWrite = true` 는 `WRITE_REPOSITORY` 를 함께 요구한다(대량 쓰기도 결국 쓰기). - `bulk_write_capability_requires_write_repository_access` 가 강제. + `BULK_WRITE_CAPABILITY_REQUIRES_WRITE_REPOSITORY_ACCESS` 가 강제. - 이 애너테이션은 `docs/registries/capabilities.yaml` 의 7개 capability 를 코드로 구현한 것이며, **코드가 SSOT** 다. 추가 플래그의 의미: - `sensitiveRead` — PII/자격증명/비밀을 읽는 유스케이스 선언. 필드 단위 마커(엔티티 FQN + diff --git a/src/composition/service-runtime/README.md b/src/composition/service-runtime/README.md index 0fcd9479..271b74ba 100644 --- a/src/composition/service-runtime/README.md +++ b/src/composition/service-runtime/README.md @@ -287,6 +287,6 @@ runtimeOnly project(':composition:service-runtime') - **SHAPE-OWNERSHIP(하드 규칙): 이 클래스는 `HealthEndpoint` / `HealthIndicator` / `HealthComponent`를 import·구현·의존해선 안 된다** — health 엔드포인트의 형태(shape)는 runtime-health 브랜치 소유다. 보안 매칭은 오직 엔드포인트 id 문자열로만 하고 health 내부 구조에는 절대 손대지 않는다. ArchUnit - 규칙 `management_security_does_not_depend_on_health_internals`(`CleanArchitectureTest`)가 이를 정적 + 규칙 `MANAGEMENT_SECURITY_DOES_NOT_DEPEND_ON_HEALTH_INTERNALS`(`CleanArchitectureTest`)가 이를 정적 으로 강제한다. diff --git a/src/domain-core/README.md b/src/domain-core/README.md index 29f3ab82..d89d7f84 100644 --- a/src/domain-core/README.md +++ b/src/domain-core/README.md @@ -57,7 +57,7 @@ 네이밍 규칙 대신, `@ValueObject` 처럼 **명시적이고 의도가 드러나는 선언**을 기준으로 모델링 가드레일을 걸 수 있게 한다. - **왜 프레임워크 중립으로 두나.** 일부러 어떤 프레임워크에도 의존하지 않게 만들어서 - `domain-core`가 순수 라이브러리로 남게 한다(`domain_is_pure` 가드레일). + `domain-core`가 순수 라이브러리로 남게 한다(`DOMAIN_IS_PURE` 가드레일). ### `@ValueObject` — 값 객체 @@ -67,7 +67,7 @@ 단 하나의 생성 경로에서 자기 불변식을 검증한다. - **강제 규칙 — public 무인자 생성자 금지.** `@ValueObject` 타입과 `..domain.vo..` 아래 모든 타입은 public 무인자 생성자를 노출하면 안 된다. 빈 생성자는 검증을 건너뛰고 객체를 만들 수 - 있는 "불변식 우회 뒷문"이기 때문이다(`value_objects_have_no_public_no_arg_constructor`). + 있는 "불변식 우회 뒷문"이기 때문이다(`VALUE_OBJECTS_HAVE_NO_PUBLIC_NO_ARG_CONSTRUCTOR`). - **왜 `RUNTIME` 리텐션인가.** ArchUnit(바이트코드 검사)과 리플렉션 기반 테스트가 둘 다 이 애너테이션을 읽을 수 있어야 해서 런타임까지 유지한다. @@ -79,7 +79,7 @@ - **상태 변경은 의도가 드러나는 메서드로만.** 상태 변경은 불변식을 강제하는, 의도가 분명한 애그리거트 메서드를 통해서만 일어나야 한다. 날것의 `setXxx` 세터를 public 으로 열어두면 안 된다. - **강제 규칙 — public 세터 금지.** `@AggregateRoot` 타입의 모든 `set*` 메서드는 - package-private 또는 protected 여야 한다(`aggregate_root_setters_are_not_public`). 이 + package-private 또는 protected 여야 한다(`AGGREGATE_ROOT_SETTERS_ARE_NOT_PUBLIC`). 이 가시성은 Vernon Option A(ORM 외부에서 매핑하는 방식)로 객체를 재구성할 때 의존하는 지점이다. - **이 규칙의 한계.** ArchUnit 은 정적으로 `set*` 라는 이름 패턴까지만 잡을 수 있다. `applyXxx` 처럼 이름이 다른 상태 변경 메서드는 자동 검사가 닿지 않으므로 코드 리뷰가 잡아야 @@ -94,6 +94,6 @@ 포맷·HTTP 같은 전송 계층 타입을 절대 참조하지 않는다는 뜻이다. 도메인 이벤트를 통합 이벤트나 와이어 이벤트로 번역하는 일은 애플리케이션/인프라 경계의 책임이지 도메인의 책임이 아니다. - **강제 규칙 두 가지.** 모든 `@DomainEvent` 타입은 (1) `record` 여야 하고 - (`domain_events_are_records`, 불변성 보장), (2) 어떤 전송 패키지(`org.apache.kafka..`, + (`DOMAIN_EVENTS_ARE_RECORDS`, 불변성 보장), (2) 어떤 전송 패키지(`org.apache.kafka..`, `org.springframework.http..`, `jakarta.ws.rs..`)도 의존하면 안 된다 - (`domain_events_are_transport_free`). + (`DOMAIN_EVENTS_ARE_TRANSPORT_FREE`). diff --git a/src/shared-contract/README.md b/src/shared-contract/README.md index a1d66198..b22731a4 100644 --- a/src/shared-contract/README.md +++ b/src/shared-contract/README.md @@ -508,7 +508,7 @@ Spring 배선(`DomainContextConfig`)은 `composition:service-runtime` 에 있고 흐르는 값도 없다. 도메인은 필요해질 때 자기 키를 선언한다(그 전까지 seam 은 관측 가능한 동작이 없다 — route 가 없는 `RateLimitKeyResolver` 와 같다). - **`ScopedValue`/`StructuredTaskScope` strategy:** Java 21 preview API 이고 빌드에 `--enable-preview` - 가 없어(빌드 사실 C1) 운영에서 컴파일되지 않는다. `domain_context_propagation_primitives_stay_unshipped` + 가 없어(빌드 사실 C1) 운영에서 컴파일되지 않는다. `DOMAIN_CONTEXT_PROPAGATION_PRIMITIVES_STAY_UNSHIPPED` ArchUnit 규칙(app-bootstrap `ForbiddenApiArchitectureTest`)이, 해당 구현이 추가되기 전까지 이를 운영 코드에서 배제한다. @@ -534,7 +534,7 @@ Spring 배선(`DomainContextConfig`)은 `composition:service-runtime` 에 있고 살고 inbound 필터가 virtual thread 에서 전파한다(B6 + D11). 이 propagator 는 **도메인 채널** — 별개의 관심사다. - **명시적 핸드오프(S3):** 구현은 스레드 간 암묵적 상속에 의존해선 안 된다(`InheritableThreadLocal` 은 - `no_inheritable_thread_local` ArchUnit 규칙으로 금지). 스레드/`fork()` 경계를 넘는 코드는 + `NO_INHERITABLE_THREAD_LOCAL` ArchUnit 규칙으로 금지). 스레드/`fork()` 경계를 넘는 코드는 `wrap()` 또는 `capture()`+`restore()` 로 컨텍스트를 명시적으로 재확립한다. ### 전략이 하나뿐인 이유 @@ -545,13 +545,13 @@ Spring 배선(`DomainContextConfig`)은 `composition:service-runtime` 에 있고 - `io.micrometer:context-propagation` 의 `ContextSnapshot`/`ContextRegistry`. 다중 키나 Reactor bridge 가 필요할 때 고른다(C7: 활성화 전에 virtual-thread 동작을 확인할 것). - Java 21 `ScopedValue`. PREVIEW 라 `--enable-preview` 가 필요한데 현재 빌드는 켜지 않는다(C1) → - `domain_context_propagation_primitives_stay_unshipped` ArchUnit 규칙으로 guard 된다. + `DOMAIN_CONTEXT_PROPAGATION_PRIMITIVES_STAY_UNSHIPPED` ArchUnit 규칙으로 guard 된다. ### ThreadLocalDomainContextPropagator (기본 구현) - plain `ThreadLocal` 이 현재 스레드의 도메인 컨텍스트 맵을 들고, 스레드 경계는 명시적 capture/restore 로 넘긴다(D4/D6). - **왜 plain `ThreadLocal` 인가:** `InheritableThreadLocal` 이 아니라서 pooled carrier 스레드 너머로 - 조용히 새지 않고 `no_inheritable_thread_local` ArchUnit 규칙(B6)을 지킨다. virtual thread 는 각자 + 조용히 새지 않고 `NO_INHERITABLE_THREAD_LOCAL` ArchUnit 규칙(B6)을 지킨다. virtual thread 는 각자 자기 copy 를 갖는다(Oracle Java 21 docs, TL-VT-C1) → 같은 스레드 read 는 동작하지만 fork 시 상속은 없다 — 그래서 핸드오프가 `wrap()`/`capture()` 로 **명시적**이어야 하는 것이다. - multi-key 고빈도 변경이나 Reactor bridging 용이 아니다 — 그건 context-propagation 기반 구현의 일이다. 이