Files
clean-architecture-backend-…/docs/manual
DongHyeonka 931178760a
pr / done (pull_request) Canceled after 0s
fix(outbound)!: S3 조건부 쓰기·MongoDB 예산과 lease·HTTP 압축을 맞춘다
S3 control 저장소는 SDK가 응답을 잃고 다시 보낸 조건부 PUT의 412를
충돌로 본다. MongoDB 집계는 결과 바이트 예산을 보지 않고 전부 메모리에
올린다. tenant client registry는 쓰는 중인 client를 내보내고, 내보내다
닫기에 실패하면 다른 tenant의 acquire가 실패한다. migration lease를 잃은
runner가 그 뒤에도 checkpoint를 쓴다. HTTP client는 SOCKS proxy를 HTTP로
붙이고, 압축을 켜면 Apache는 스스로 풀어 max-wire-bytes가 푼 크기를
세며, JDK transport는 그 설정을 읽지 않는다.

고른 방법: S3는 412에서 다시 읽어 이 호출이 쓴 record 그대로면 성공으로
본다. 집계는 $limit(maxResults + 1)과 maxResultBytes를 집행한다. registry
acquire는 Lease를 돌려주고 쓰는 중에는 내보내지 않으며 idle은 마지막
close부터 잰다. 상한·lease 수·내보내기는 registry 밖에서 잡을 수 없는 전용
lock 하나로 묶는다. 닫기 실패는 evictionCloseFailures가 센다. migration
ledger는 lock 문서의 현재 fence로 쓴다. ProxyType은 HTTP만 남긴다.
압축은 RestClient 기본 헤더로 보내고 ContentDecoding이 버퍼·스트리밍
본문을 모두 푼다(겹친 coding과 그 밖의 coding은 거부, 빈 본문은 빈
본문). Jetty HTTP/3는 기동 뒤 decoder를 비운다. 버린 대안: SOCKS 지원
(transport 셋 중 하나만 된다), transport마다 자동 풀기(크기 상한이
transport마다 달라진다), 집계를 RawBsonDocument로 재기(converter를 거치지
않으면 반환 타입 mapping이 갈라진다).

위험·한계: MongoTenantClientRegistry.acquire 반환형과 ProxyType이 바뀐다.
S3에서 두 writer가 같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다
(Javadoc과 안내 3절). 집계 결과는 converter로만 바뀌어 entity callback이
돌지 않는다. evictionCloseFailures 지표는 지표 묶음에 넘긴다.

검증: desktop RED(pr2-red2). GREEN은 PR 본문의 verify.sh pr 결과.

Refs: RR9-01-08, RR9-01-11, RR9-01-19, RR9-01-20, RR9-01-27, RR9-01-28, RR9-01-30, RR9-01-31
BREAKING CHANGE: MongoTenantClientRegistry.acquire가 Lease를 돌려주고, migration lease를 잃은 refresh가 MongoOperationRejectedException을 던진다. HTTP client ProxyType.SOCKS가 없어져 그 설정은 바인딩이 실패한다. request.compression이 모든 transport에서 같은 coding만 받는다. docs/upgrade/2026-11-round9-outbound.md
2026-11-13 16:21:16 +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와 가장 가까운 src/**/AGENTS.md
테스트 작성 규칙 .claude/rules/java-tests.md
leaf 목록·허용 의존 gradle/modules.json
이름 규칙(유스케이스·포트·command·query) src/application/core/AGENTS.md 「Naming convention」. 기계 검사는 src/bootstrap/app/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java와 ApplicationBoundaryArchitectureTest.java
유스케이스 모양·트랜잭션 모양 src/application/core/README.md 「정해진 유스케이스 모양 (Canonical use case shape)」, src/application/core/AGENTS.md 「허용하는 트랜잭션 모양 (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개 10-capabilities.md

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

따라 할 예시는 하나

예시가 셋(한 leaf에 모든 계층을 둔 샘플 모듈, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라 배치가 달라졌다(2026-11-01 성숙도 리뷰). 이제 새 업무 기능의 예시는 생성 명령의 출력 하나다. 샘플 모듈은 2026-11-07에 지웠다.

코드 역할 따라 하나
scripts/new-feature.sh 출력 계층 leaf에 나눈 업무 기능 이것을 따른다
src/bootstrap/app/src/test/java/dev/caskeleton/onboarding/** ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture 따르지 않는다
src/application/core/.../operation + DurableOperationAutoConfiguration(composition:durable-operation) 템플릿 플랫폼 기능 조립 모양(@ConditionalOnBean + 유스케이스 @Bean)만 본다

리뷰 뒤 첫 수정으로 생긴 패턴

2026-11-01 성숙도 리뷰 뒤 같은 날 한 첫 수정에서 굳은 모양이다. 각 장에 반영했다.

패턴 근거 코드 장
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로 변환 04장 「중복·경쟁은 DB가 막는다」(템플릿 코드에 예 없음) 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(build.gradle strictLaneStages) 08
서비스 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 NotificationSchemaStream(persistence-notification) 04
재시도 가능한 broker 거부는 DEAD가 아니라 재시도 docs/runbooks/outbox-dead-letter.md 09