문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).
방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.
위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).
검증: 묶음별 RED·GREEN은 로컬(노트북 빌드 금지 지시 전)에서, 지시 뒤에
바뀐 01 A5 fixture의 RED와 02 늦은 시작 revision 검사의 RED, 03 동시 인덱스
검사기 GREEN은 desktop에서 확인했다. 합친 트리를 desktop에서 돌려 모두 첫
실행 통과: :ci :verifyDependencyLocks --warning-mode=fail, sample check,
두 빌드 verifyStrictLaneStages --dry-run, :mainCheck, :integrationCheck,
-p optional-platforms ci integrationCheck performanceCheck, :performanceCheck,
:releaseCheck, compose 18 lane, -p build-logic check javadoc(README 17.2절).
Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
sample-portfolio — WorkLog 포트폴리오 게시판 (예시 도메인)
이 모듈은 ca-skeleton 템플릿이 유지하는 fixture/reference 예시 도메인입니다. production 모듈
(domain-core/application-core/adapter-*/shared-contract/app-bootstrap)의
경계와 운영 계약을 "어떻게 쓰는지" 보여줍니다. 새 프로젝트는 이 모듈을 import하지 않고 자신의
도메인을 production 모듈에 추가합니다. 템플릿에서는 이 모듈을 유지하며, 다운스트림 fork는
./gradlew :app-bootstrap:sampleOffTest 통과 후에만 선택적으로 정리할 수 있습니다.
도메인: WorkLog (엔지니어링 작업 기록 게시판)
메인 화면 = GET /api/worklogs 목록. 각 항목은 직접 수행한 작업입니다.
| 필드 | 설명 |
|---|---|
| title | 작업 제목 |
| category | INFRASTRUCTURE / DATABASE / BACKEND / PLATFORM |
| summary / content | 요약 / 본문 |
| techStack[] | 사용 기술 |
| links[] | 관련 링크 (repo/blog) |
| period | 기간 (end=null → 진행 중) |
엔드포인트
| Method | Path | 설명 | 필요 권한 | 시연 계약 |
|---|---|---|---|---|
| GET | /api/worklogs | 목록 (메인) | 없음(공개) | Envelope wrap |
| GET | /api/worklogs/{id} | 상세 | 없음(공개) | 도메인 예외→404 envelope |
| POST | /api/worklogs | 생성 | worklog:write |
Bean Validation @GroupSequence (B4), unknown-field 거부 (B1), mapper 실패→MAPPING_FAILED (B3) |
| PATCH | /api/worklogs/{id} | 부분수정 | worklog:write + 소유자 본인 |
JsonNullable 3-state (B2), 남의 기록이면 403 WORKLOG_NOT_OWNER |
| DELETE | /api/worklogs/{id} | 삭제 | worklog:close |
204 |
| POST | /api/worklogs:batchCreate | 일괄 등록 | worklog:write |
동기 = 원자적(한 항목 실패 → 전체 롤백, 단일 4xx) |
데모 계정과 권한
읽기(GET)는 인증 없이 열려 있고, 나머지 메서드는 아래 데모 계정 중 하나로 HTTP Basic 인증을 해야
합니다. 인증 없이 쓰면 401 envelope입니다. 계정이 그 작업을 해도 되는지는 이 체인이 아니라 유스케이스의
@RequiresPermission이 정하고, 역할→권한 표는 application.yml의 app.authz.role-permissions입니다.
운영 경로(JWT)와 같은 advisor·같은 표를 씁니다.
| 계정 | 비밀번호 | 역할 | 할 수 있는 것 |
|---|---|---|---|
demo-user |
demo-user |
user |
읽기, 생성, 자기 기록 수정. 삭제는 403 |
demo-admin |
demo-admin |
admin |
읽기, 생성, 자기 기록 수정, 삭제 |
수정은 권한(worklog:write)과 소유자를 둘 다 봅니다. demo-admin 도 demo-user 가 만든 기록은
고칠 수 없습니다(403 WORKLOG_NOT_OWNER). 삭제는 관리 작업이라 소유자를 보지 않습니다.
비밀번호가 문서에 적혀 있는 공개 데모 계정입니다. 비밀이 아니며, 실제 서비스는 이 방식을 쓰지 않고
adapter:inbound:web의 JWT 체인으로 인증합니다.
그래서 데모 프로필(local·test·demo)이 명시적으로 켜져 있고 그 밖의 프로필이 하나도 없을 때만
기동합니다. 프로필 없음, prod, production, staging 등은 기동을 거부합니다
(SampleDemoAccountsProductionGuard, 종료 코드 71). 샘플을 복제해 운영에 올릴 때 이 계정이 남아 있으면
누구나 관리자로 들어올 수 있기 때문입니다. 거부 목록(prod)이 아니라 허용 목록인 이유는 프로필 이름이
하나만 달라도 계정이 열리지 않게 하려는 것입니다. ./gradlew :sample-portfolio:bootRun은
SPRING_PROFILES_ACTIVE가 비어 있으면 local을 넘기고, jar·이미지로 띄울 때는
SPRING_PROFILES_ACTIVE=demo를 직접 줍니다(src/Dockerfile.sample 머리말의 docker run 예시). 세 프로필
모두 같은 데모 기본값(object storage 끔 등)을 application.yml에서 받고, 각 프로필로 실제로 뜨는지는
SampleDemoProfilesStartupSystemTest가 확인합니다. 운영으로
가져가려면 SampleDemoSecurityConfig·SampleDemoAccounts를 지우고 SamplePortfolioApplication에서
WebSecurityAutoConfiguration 제외를 풉니다. 이 규칙은 데모 설정 옆에 선언되어 있어 함께 지워집니다.
샘플 데이터 (curl 예시)
# 1) 인프라 인증·인가 위임 (Keycloak + k3s + Vault)
curl -X POST localhost:8080/api/worklogs -u demo-user:demo-user -H 'Content-Type: application/json' -d '{
"title": "Keycloak + k3s + Vault 기반 인증·인가 위임",
"category": "INFRASTRUCTURE",
"summary": "인증/인가를 Keycloak으로 위임, k3s + Vault로 시크릿·구성 관리",
"content": "...",
"techStack": ["keycloak", "k3s", "vault"],
"links": ["https://example.com/infra"],
"periodStart": "2025-01-01"
}'
# 2) DB 쿼리 튜닝
curl -X POST localhost:8080/api/worklogs -u demo-user:demo-user -H 'Content-Type: application/json' -d '{
"title": "DB 쿼리 튜닝",
"category": "DATABASE",
"summary": "slow query 분석 및 인덱스/실행계획 개선",
"content": "...",
"techStack": ["postgresql"],
"links": [],
"periodStart": "2025-02-01"
}'
복제해도 되는 모양 — 새 기능이 따라 할 것
이 샘플은 새 기능이 베껴 가는 예시입니다. 아래 다섯은 리뷰(2026-11-01 성숙도 리뷰 09·01·04 영역)에서 실측으로 문제를 확인하고 고친 모양이라, 그대로 복제해도 안전합니다. 각 항목의 근거는 아래 「설계 결정 참조」에 있습니다.
| 할 일 | 이 샘플의 모양 | 피한 함정 |
|---|---|---|
| 목록 조회 | 요약 projection(WorkLogSummaryQueryPort.findPage) 한 쿼리 + count |
애그리거트를 통째로 읽으면 항목마다 컬렉션 쿼리 2개(20건에 SQL 42개, 100건에 202개) |
| 수정 저장 | 읽어 둔 관리 엔티티에 바뀐 값만 덮어쓰기(WorkLogRepositoryAdapter.update) |
새 엔티티를 merge 하면 제목 하나 고쳐도 자식 테이블 전부 삭제·재삽입 |
| 남의 리소스 수정 | 권한 검사 + 유스케이스 안 소유자 검사(UpdateWorkLogUseCase) |
권한만 보면 worklog:write 가진 누구나 남의 기록을 고침 |
| 유일해야 하는 값 | DB 유일 인덱스가 규칙을 지키고 위반을 도메인 409 로 변환(생성·수정 둘 다) | 사전 조회만으로는 동시 요청에서 중복 행 |
| 동기 일괄 쓰기 | 건수 상한 + JDBC batch(application.yml), 상한·왕복 수를 테스트로 고정 |
행마다 왕복하는 동안 커넥션 하나를 오래 잡음(자식 컬렉션 행은 아직 항목당 왕복 — 아래 BatchCreate 절) |
이 다섯은 테스트로 고정돼 있습니다: WorkLogStatementCostSystemTest(목록 SQL 수가 페이지 크기와
무관, 제목만 고친 PATCH 의 자식 테이블 쓰기 0), SampleWorkLogAuthorizationSystemTest(남의 기록 PATCH
403), PosterRepositoryAdapterIntegrationTest(다른 포스터 제목으로 바꾸면 409),
WorkLogStatementCostSystemTest.batchCreate…(일괄 생성 JDBC 왕복 수).
계층 (adapter-mirrored)
domain/worklog— WorkLog/WorkCategory/Period/RepoStats/WorkLogRepository (POJO)application/<기능>— 기능별 패키지(review S6-#10a):worklog(대표 예제),poster,posterimage(object storage 검증용). 각 패키지가 자기 *UseCase(CommandUseCase/QueryUseCase + @UseCaseCapability)·command·query·예외·포트·이벤트 payload를 함께 가진다.application/event에는 기능 사이에 공유하는 계약(PortfolioEventContract(s)·PortfolioEventOutbox)만 남는다adapter/web— controller/dto/mapper/erroradapter/persistence— entity/repository/mapperadapter/outbound/repostats— B7 ACL 예시
설계 결정 참조 (코드 주석에서 이전)
여기 아래는 예전에 각 클래스의 주석/JavaDoc 에 흩어져 있던 "왜 이렇게 짰는가" 설명을 한곳에 모은 것입니다. 코드에는 "무엇을 하는지"만 짧게 남기고, 그 배경·결정·트레이드오프는 이 문서로 옮겼습니다. 코드를 읽다 "왜 이렇게 했지?"가 궁금할 때 보세요.
읽는 법:
- 모듈 규칙(허용/금지 의존, 테스트 명령)의 기준은 CLAUDE.md 입니다. 이 문서는 규칙이 아니라 결정의 근거를 모은 참조 기록입니다.
- 본문은 코드가 어떤 약속을 지키려고 존재하는지 설명합니다. 추적용 꼬리표는 코드 주석에 남기지 않고, 필요한 배경은 여기서 문장으로 풀어 설명합니다.
domain — 도메인 (순수 POJO, 프레임워크 의존 없음)
WorkLog (애그리거트 루트)
- WorkLog 애그리거트의 루트입니다. 상태를 바꾸는 길은 의도가 드러나는 메서드뿐입니다
(
rename,recategorize,startProgress,close…). 공개setXxx세터를 두지 않은 이유는, 세터를 열어두면 불변식(invariant)을 건너뛴 채로 객체를 망가뜨릴 수 있기 때문입니다. 모든 변경 경로가 불변식 검사를 거치도록 강제합니다. - 불변식을 어기면
WorkLogInvariantException을 던집니다. 이 예외는 안전한 사유(reason)만 담고, 로그 문자열이나 운영 에러 코드/HTTP 상태는 전혀 모릅니다 — 그 변환은 상위 (application/web)의 몫입니다. - id 는 도메인이 직접 만들지 않습니다.
WorkLog.create(...)는 이미 만들어진WorkLogId를 받기만 합니다. UUIDv7 생성은 유스케이스가WorkLogIdFactory포트를 통해 하고, 도메인 안에는UUID.randomUUID()나 id 생성 라이브러리가 들어오지 않습니다(서버가 id 를 정해주는 계약). version필드(낙관적 락 버전)의 역할: 새로 만든(아직 저장 안 된) 객체는null이고, 저장소가 값을 채우고 증가시킵니다. 영속 계층은 이null여부로 "INSERT 인지 UPDATE 인지"를 구분하고, 웹 경계에서는 이 값이 HTTPETag/If-Match의 출처가 됩니다. 즉 DB 가 낙관적 락 충돌로 잡아내는 그 충돌을, 웹에서는 HTTP 412 로 표현합니다.title규칙: null 이면 안 되고(NullPointerException), 공백만 있어도 안 됩니다 (TITLE_BLANK). 공백 금지는 도메인 불변식이라, 웹 경계의@NotBlank(형식 검사)와는 별개로 한 번 더 지킵니다 — 웹을 거치지 않는 호출자가 있어도 규칙이 새지 않도록.
값 객체 — WorkLogId / Period / WorkLogOwner
- WorkLogId: 36자 canonical UUID(RFC 9562 UUIDv7). 순수 값 객체라 형식(정규형)만 검증하고,
id 생성 라이브러리에는 의존하지 않습니다. 대소문자 정규화는 이 타입을 만들기 전에 웹 경계에서
끝냅니다(canonical 형태는 소문자 hex). 형식은
8-4-4-4-12hex 그룹입니다. - Period: 작업 기간.
end == null이면 "진행 중"이라는 뜻입니다. 생성자에서end < start를 막습니다(기간 역전 불가). - WorkLogOwner: 소유자 식별자. 공백/빈 값을 막고 trim 합니다.
열거형 — WorkLogStatus / WorkCategory / WorkLogSortField
- WorkLogStatus: OPEN → IN_PROGRESS → CLOSED. 전이 규칙은 WorkLog 가 강제합니다.
- WorkCategory: 포트폴리오 보드에 노출하는 작업 분류(INFRASTRUCTURE/DATABASE/BACKEND/PLATFORM).
- WorkLogSortField: 목록 정렬에 허용된 필드만 담은 닫힌 열거형입니다. 정렬 키를 ORM 에
넘기는 열린 문자열이 아니라 열거형으로 막아둔 이유는, 알 수 없는 필드를 쿼리까지 보내지 않고
웹 경계에서 400 으로 거절하기 위해서입니다(
?sort=field,direction계약을 안전하게 만드는 핵심).
WorkLogInvariantException
- WorkLog 불변식 위반을 알리는 예외입니다.
Reason(명사형 안전 enum)만 담고, 운영 에러 코드·HTTP 상태·로깅은 모릅니다. 도메인은 로거를 갖지 않고 운영 코드로 매핑하지도 않는다는 규칙 때문입니다.reason()을 로그 라인과error.category로 번역하는 일은 application/web 의 책임입니다. 사유가 거친 명사라서 민감 정보가 클라이언트로 새지 않습니다.
WorkLogReserved (도메인 이벤트)
- "WorkLog 기간이 예약됨"이라는 도메인 사실을 표현하는 이벤트입니다. 전송(transport)과
무관합니다 — 도메인 데이터(
WorkLogId/WorkCategory/LocalDate)만 담고 broker/wire/HTTP 타입을 일절 참조하지 않습니다. 이것을 발행 가능한 integration 이벤트로 바꾸는 일은 application 경계의 몫입니다(application.worklog.WorkLogReservedPayload와application.event.PortfolioEventOutbox참고).
포트 — WorkLogRepository / WorkLogIdFactory (도메인), OutboxEventIdFactory (application)
- WorkLogRepository: WorkLog 영속 아웃바운드 포트(구현은 adapter-persistence).
findPage는 한 페이지 + 전체 개수를 함께 돌려주며,sortField/category가null이면 정렬/필터 없음을 뜻합니다. 전체 개수는 같은 필터 기준으로 세어meta.page.total이 필터된 결과를 반영하게 합니다. - WorkLogIdFactory / OutboxEventIdFactory: id 를 만들어 주는 포트.
WorkLogIdFactory는 도메인 포트이고,OutboxEventIdFactory는application.event에 있다 — outbox는 도메인 개념이 아니고 쓰는 곳이PortfolioEventOutbox뿐이기 때문이다. 둘을 굳이 따로 둔 이유는, 애그리거트 식별자 타입(WorkLogId)이 이벤트 id 모양을 묶어버리지 않게 하기 위해서입니다. 실제로는 둘 다 UUIDv7 기반이지만(identifier 어댑터가 구현), 도메인은 생성 방식을 모릅니다. outbox 이벤트 id 는 envelope 의eventId이고, consumer 는 이 값으로 중복을 거릅니다(이벤트 단위 중복 제거).
RepoStats
- 외부 저장소 통계를 정규화한 결과 값입니다. 아웃바운드 ACL(B7)을 통과한 뒤에만 만들어집니다.
application — 응용 (유스케이스)
Command / Query — 스스로 검증하는 입력 모델
CreateWorkLogCommand,UpdateWorkLogCommand,DeleteWorkLogCommand,GetWorkLogQuery,GetRepoStatsQuery,ListWorkLogsQuery,BatchCreateWorkLogsCommand는 생성자에서 스스로 필수값을 검증합니다("self-validating input model"). 이렇게 하면 어떤 인바운드 어댑터가 부르든(오늘은 웹, 내일은 메시징 컨슈머) 웹 경계의 jakarta validation 에 기대지 않고도 같은 계약을 보장받습니다. id 나 patch 가 null 인 것은 프로그래밍 오류이므로 생성 시점에 즉시 실패시킵니다("없음"은Patch.absent()로 표현하고 null 을 쓰지 않습니다).UpdateWorkLogCommand의 필드는Patch<T>입니다. PATCH 의 3가지 상태 — 값 없음(변경 안 함) / 명시적 null(필드 비움) / 값(교체) — 을 구분하기 위해서입니다.
CreateWorkLogUseCase — 생성 + outbox 동시 기록 (dual-write 금지)
- WorkLog 를 저장하면서
WorkLogReservedoutbox 이벤트를 같은 쓰기 트랜잭션 안에서 함께 적재하는 예시입니다. 핵심은repository.save(...)와 outbox append 가 같은tx.inWrite { ... }블록 안에 있다는 점입니다. 저장이나 적재 중 하나라도 실패하면 트랜잭션 전체가 롤백됩니다 — "DB 한 번, 브로커 한 번" 식의 분리된 이중 쓰기(dual-write)를 막는 보장입니다. - 순서: ① 저장된 애그리거트로 도메인 이벤트 생성 → ② payload record(
WorkLogReservedPayload)로 변환(경계는 application) → ③PortfolioEventOutbox가 draft 를 만들어IntegrationEventEncoderPort로 encode → ④ 같은 트랜잭션에서OutboxAppendPort에 append. outbox append 모델은 canonical 하나입니다(소유자 결정 7). 포스터 이벤트(PosterEventPublisher,PosterImagePublicationEventPublisher)도 같은 길로 갑니다. eventId는OutboxEventIdFactory(UUIDv7) 로 만듭니다(이벤트 단위 중복 제거 키).correlationId는 application-core의CorrelationIdPort로 읽습니다. inbound web adapter가 sanitized MDC 값을 포트 뒤에서 제공하므로 sample application 코드는 SLF4J/MDC를 알지 않습니다. 요청 밖에서 실행되거나 값이 blank이거나 canonical identity 문법에 맞지 않으면eventId를 그대로correlationId로 사용해 이벤트가 최소한 자신을 가리키게(self-correlation) 폴백합니다.- aggregate 순서는 발생 시각(마이크로초)입니다. sample 애그리거트에는 event 카운터가 없고, 시간 순서는 옛 outbox 가 풀어 주던 순서와 같습니다. version 컬럼이 있는 서비스는 그것을 씁니다.
- 쓰기 작업이라
@RequiresPermission("worklog:write")로 권한을 요구합니다(이 권한은user/admin역할 묶음에 부여).
BatchCreateWorkLogsUseCase — 원자적 일괄 생성
- 동기 일괄 생성은 전부 성공 아니면 전부 롤백입니다. 모든 항목을 하나의
tx.inWrite단위로 처리하므로 한 항목이라도(매핑/검증/영속) 실패하면 배치 전체가 되돌려지고, 엔드포인트는 부분 성공 대신 단일 4xx 를 냅니다. (BATCH_PARTIAL_FAILURE같은 부분 실패 형태는 비동기 폴링 응답용으로 예약돼 있고, 동기 배치에는 쓰지 않습니다.) - 크기와 트랜잭션. 상한은
MAX_BATCH_SIZE(1000)이고, 1000건도 한 트랜잭션입니다. 트랜잭션을 나누면 "전부 아니면 전무" 계약이 깨지므로 나누지 않았습니다. 대신 행 단위 왕복을 줄였습니다: 샘플application.yml이hibernate.jdbc.batch_size=50·order_inserts=true를 켭니다(2라운드 04 수정 뒤로는 persistence-jpa 모듈 기본값도 같다). JDBC 왕복으로 세면(InsertRoundTripCounter) 100건 = insert 400행이 400번 → 8번입니다: 표마다 50행씩(work_log 2 + tech_stack 4 + link 2). 새 엔티티를 merge 가 아니라 persist 하게 바꾼 뒤(Persistable, 리뷰 04-17)@ElementCollection행도 소유 엔티티를 넘어 묶입니다. 그 전에는 컬렉션 행이 항목마다 따로 가서 202번이었습니다 (WorkLogStatementCostSystemTest.batchCreatingAHundredWorkLogsSendsTheWorkLogRowsInJdbcBatches). - 실측(2026-11-02, 리뷰 09 문서와 같은 방법: 호스트
java -jar -Xmx1g, PostgreSQL 16 컨테이너--cpus 4 --memory 1g,work_log10,000행): 1000건 요청 시간 batch 끔 0.320.61 s → 켬 0.220.47 s. PG 문장 로그는 둘 다 4,004줄입니다 — 서버는 묶음 안의 행도 하나씩 execute 로 기록하기 때문입니다(줄어드는 것은 네트워크 왕복: 1000건 4,000번 → 약 2,000번). 로컬 DB 라 왕복 비용이 작아 차이가 작고, 원격 DB(왕복 1 ms)라면 1000건 요청이 커넥션을 약 2 s 잡습니다. - 상한을 바꿀 조건: 1000건 요청이 커넥션을 잡는 시간이
connection-timeout(기본 5 s)의 일부를 넘기 시작하면 (원격 DB, 큰 본문) 상한을 낮추고 그 이상은 비동기 operation(OperationsController)으로 보냅니다.
UpdateWorkLogUseCase — 소유자 검사 + Patch 3-state 적용
- 소유자만 고칠 수 있습니다.
@RequiresPermission("worklog:write")는 "이 사람이 기록을 고칠 수 있는 역할인가"만 답합니다. "이 기록을 고칠 수 있는가"는 저장된 소유자가 있어야 답할 수 있어서, 유스케이스가 기록을 읽은 직후 같은 쓰기 트랜잭션 안에서WorkLog.isOwnedBy(editor)로 확인합니다. 검사와 변경 사이에 다른 쓰기가 끼어들 틈이 없습니다. 소유자가 아니면WorkLogNotOwnedException→ 403WORKLOG_NOT_OWNER. 읽기가 공개라 존재 자체는 비밀이 아니므로 404 로 숨기지 않습니다. - 호출자는
UpdateWorkLogCommand.editor로 들어옵니다(웹 어댑터가 인증 principal 의 subject 를 넣음). command 가 생성 시점에 null 을 거부하므로, 인증 없이 이 유스케이스에 닿는 경로는 만들 수 없습니다. - 버린 대안: application-core
ObjectAccessPolicy로 묻기 — tenant 가 필수이고 정책 구현이 소유자를 다시 읽어야 해서 왕복이 하나 늘고, 검사와 변경이 다른 읽기를 보게 됩니다. 이미 읽은 애그리거트에 묻는 쪽이 싸고 원자적입니다. 관리자 예외(관리자는 남의 기록도 수정)는 두지 않았습니다. 필요하면 별도 권한 (worklog:moderate등)으로 명시해 이 검사 옆에 둡니다. - 각 필드의
Patch상태에 따라 다르게 동작합니다:hasValue()면 교체,isExplicitNull()이면 비움, 둘 다 아니면(없음) 변경하지 않습니다. 상태 전이는 도메인 메서드(startProgress/close)에 위임하고, OPEN 으로 되돌리는 시도는 잘못된 전이로 막습니다.
DeleteWorkLogUseCase — 권한 3-tier 가시화
- 삭제는 파괴적인 admin 등급 작업이라
@RequiresPermission("worklog:close")로 막습니다.worklog:close는admin역할 묶음에만 부여되고user에는 주지 않습니다(샘플 모델에는 별도 "close" 유스케이스가 없어 delete 가 그 민감 작업 역할을 합니다). 이 한 군데가 3-tier 권한 모델을 눈에 보이게 만듭니다 — 인증된user는 여기서 거절되고admin만 통과합니다. (참고로 생성·수정· 일괄 생성은worklog:write로 막고, 이 권한은user/admin양쪽에 부여됩니다.)
읽기 모델(projection) — ListWorkLogsUseCase / ListRecentWorkLogSummariesUseCase / WorkLogSummaryQueryPort / WorkLogSummary
- 목록은 모두 이 길로 읽습니다.
GET /api/worklogs(ListWorkLogsUseCase)가WorkLogSummaryQueryPort.findPage를 씁니다. 예전에는WorkLogRepository.findPage로 애그리거트를 통째로 읽었고, 항목마다 lazy@ElementCollection두 개를 따로 읽어 SQL 이 페이지 크기에 비례했습니다(실측 20건 42개, 100건 202개 — 리뷰 09-01). 응답에 쓰지 않는content·techStack·links를 읽던 것이라, 그 메서드는 지웠습니다. 실측(2026-11-02, 리뷰 09 문서와 같은 방법, PG 문장 로그·동시 16·15 s×3 중앙값): 20건 46 → 6문장, 765 → 2,528 rps / 100건 206 → 6문장, 147 → 703 rps. 6문장은 SHOW·BEGIN·본문·count·COMMIT·검증 1개입니다.WorkLogRepository는 이제 한 건씩만 다룹니다. 목록 응답에 컬렉션이 필요해지면 projection 에 넣지 말고 IN 쿼리 하나(또는default_batch_fetch_size)로 따로 읽어 문장 수를 상수로 유지합니다. - 이 타입들은 CQRS-lite "쿼리 우회(query bypass)" 예시입니다. 보드/목록 화면처럼 가벼운 읽기는
WorkLog 애그리거트를 통째로 복원하지 않고, 필요한 컬럼만 뽑은 projection 으로 읽습니다
(
content/summary/techStack/links같은 무거운 상태를 빼서, lazy 컬렉션 조인 없는 컬럼-부분 SELECT 가 됩니다). - 단건 읽기(
GET /worklogs/{id})는 애그리거트(WorkLogRepository.findById)로 읽습니다. 한 건이라 컬렉션 쿼리가 2개로 고정이고, 응답이 컬렉션을 씁니다. - projection DTO 의 순수성: projection 은 application 타입이어야 합니다 — 도메인 애그리거트도,
JPA 엔티티도, 웹 DTO 도 아니어야 합니다. 도메인 값 타입(예:
WorkCategoryenum)을 참조하는 것은 허용됩니다(application 은 domain 에 의존 가능). 다만 쿼리 포트의 반환 시그니처에 도메인 애그리거트/ JPA 엔티티/웹 타입이 새면 안 됩니다(List<WorkLogSummary>같은 제네릭 인자까지 포함, ArchUnit 규칙query_ports_do_not_leak_domain_jpa_or_web_types가 강제). - 명명 규칙: projection 을 반환하는 읽기 포트 이름은
…QueryPort로 끝냅니다. - id 표현: projection 의
id는 애플리케이션의 표준 id 어휘인 36자 UUID 문자열입니다. 저장소 고유의UUID는 어댑터 안에서 변환되어, 읽기 모델은 저장 형식이 아니라 애플리케이션과 같은 식별자 형식을 말합니다. - 격식(ceremony)은 그대로 지킵니다: projection 읽기여도
QueryUseCase빈을 거치고 (@UseCaseCapability계약을 모든 읽기에 기계적으로 적용), 기본은tx.inRead안에서 읽습니다. projection 도 저장소 기반이면 여전히READ_REPOSITORY입니다 — "projection 이냐 애그리거트냐"는 반환 모양의 축이고, 저장소 접근 수준과는 별개라서 새 capability enum 이 필요 없습니다.
WorkLogReservedPayload / …ContractContribution — canonical contract fixture
WorkLogReservedPayload는 새 closed contract SPI에 제공하는 exact final record다. v1은workLogId하나만 소유하며, schema와 같은 canonical bounded identifier 규칙을 생성자에서 지킨다.contracts/messaging/portfolio.worklog.reserved/v1.schema.json과 golden vector는 sample fixture contract다. 공통 envelope는 WorkLog 필드를 알지 못하며 이 모듈을 삭제해도 production module build/runtime은 깨지지 않아야 한다.- contribution은 contract ID, exact payload type/component order, classpath resource ID, checked-in digest와 provider-neutral descriptor만 제공한다. JSON mapper, physical topic, Kafka 설정을 소유하지 않으며 매 호출 filesystem I/O도 하지 않는다.
CreateWorkLogUseCase가 이 contract로 발행한다. 예전의 3-fieldWorkLogReservedIntegrationEvent와 손으로 짠 JSON 매퍼는 outbox 를 canonical 로 통일하면서 삭제했다(2026-09-28).- 포스터 이벤트의 contract 는 기능별
PosterEventContracts·PosterImageEventContracts(schema 는contracts/messaging/poster.*)에 있다. 조립(SampleApplicationUseCaseConfig)이 contract 마다 bean 을 등록하고, 템플릿 encoder 가 그 bean 들로 닫힌 catalog 를 만든다. classpath scanning 은 없다. encoder 는 선언한 schema hash 를 schema 파일과 대조하지만 Draft 2020-12 validator 로 payload 를 검증하지는 않는다.
RepoStatsPort
- 외부 저장소 통계를 가져오는 아웃바운드 포트(구현은 adapter-outbound).
adapter/web — 인바운드 HTTP / 보안 / DTO
WorkLogController
- 포트폴리오 보드 엔드포인트. 리소스 이름은 AIP-122 를 따릅니다:
/worklogs(복수·소문자),/worklogs/repoStats(lowerCamelCase 하위 세그먼트), 콜론-동사 커스텀 메서드/worklogs:batchCreate./v1버전 접두사는PresentationWebConfig가 중앙에서 붙입니다. - GET /worklogs: 페이지네이션 + (선택) 정렬 + (선택) 평면 동등 필터. 정렬 문자열은
SortParam.parse가 파싱해 native 가 아닌 구문은 400 으로 거절하고, 허용 목록에 없는 필드도 거절합니다. offset 이 너무 깊으면 커서 사용을 권하는Deprecation헤더를 답니다. - GET /worklogs/{id}:
ETag를 내보내고,If-None-Match가 맞으면 본문 없이 304 를 답니다. - PATCH /worklogs/{id}:
If-Match가 오면 현재 ETag 와 같아야 하고, 다르면 412(낙관적 동시성).If-Match가 없으면 검사를 건너뜁니다 — 스켈레톤은 권장 패턴을 보여주되 강제하지는 않습니다. 헤더 해석(W/"<version>"→ 숫자)은 웹 어댑터가 하고, 비교는UpdateWorkLogCommand.expectedVersion으로 받은 update 유스케이스가 쓰기 트랜잭션 안에서 합니다. 컨트롤러가 트랜잭션 밖에서 읽고 비교하면 그 사이에 다른 수정이 끼어들 수 있기 때문입니다. application 은 ETag 문자열을 보지 않습니다. 이 리소스는 validator 하나만 내보내므로 목록·비숫자If-Match는 읽지 않고 412 입니다. - POST /worklogs: 이 예제는 멱등성을 약속하지 않습니다. 지원하지 않는
Idempotency-Key를 시그니처에 받아 놓고 무시하지 않으며, 멱등성 예시는 poster image publication 유스케이스에서 applicationIdempotencyExecutor로 제공합니다. - POST /worklogs:batchCreate: AIP-136 콜론-동사 일괄 생성. 동기 = 원자적이라 한 항목이라도
실패하면 배치 전체가 롤백되고 단일 4xx 가 납니다. 한 번에 보낼 수 있는 항목 수는
MAX_BATCH_SIZE(1000)로 제한하고, 넘으면 400 입니다. 요청 봉투는{ "requests": [ ... ] }형태입니다. - 소유자(owner) 스탬프: 생성되는 WorkLog 에는 인증된 호출자의 IdP subject 를 소유자로 찍습니다.
보안 컨텍스트에서 null 안전하게 읽으며, 이 값은 가공 전 원시 principal id 입니다 —
가명화(pseudonymization)는 별도 프라이버시 계약의 몫이라 여기서 적용하지 않습니다. 같은 값이 PATCH 의
editor로 들어가 소유자 검사에 쓰입니다(UpdateWorkLogUseCase). 유스케이스에 건worklog:write권한이 생성이 실제 실행될 시점엔 인증된 principal 이 있음을 보장합니다. - id 정규화(
toId): 대소문자 무관 canonical UUID 경로 입력을 받아, 도메인 id 를 만들기 전에 표준 36자 소문자 UUID 로 정규화합니다. 여기서 쓰는UUID.fromString(...)은 (생성기가 아니라) 파서라, 잘못된 id 면IllegalArgumentException을 던지고 전역 핸들러가 이를 HTTP 400 으로 매핑합니다.
OperationsController / SampleOperationStore / WorkLogExportResult — 장기 실행 작업(LRO) 예시
POST /worklogs:export는202 Accepted+ 폴링 경로를 가리키는Location헤더 +operationId/statusUrl을 담은 봉투를 돌려주고,GET /operations/{id}로 상태를 폴링합니다. 상태는 5값OperationStatusenum 에서 옵니다. 모르는 id 는 404OPERATION_NOT_FOUND입니다.Operation·OperationStatus는 이 샘플 전용 타입입니다(adapter.inbound.web.operation). 예전엔 shared-contract 에 있었지만 소비자가 샘플뿐이었습니다. 실제 서비스의 LRO 정본은 application-coreDurableOperation+ webOperationHttpResponse(GET /operations/{operationId})이고, 두 컨트롤러는 같은 경로를 잡으므로 한 앱에 함께 켜지 않습니다.- operation id 를 컨트롤러가 아니라
SampleOperationStore에서 만드는 이유: 컨트롤러/유스케이스는 id 를 직접 생성하면 안 된다는 규칙(no_uuid_random_in_controller) 때문입니다.SampleOperationStore는 컨트롤러도 application 서비스도 아닌 웹 인프라 컴포넌트라 여기서 id 를 발급해도 됩니다. - 단순화: 이 "export" 는 동기로 끝나므로, 클라이언트가 폴링할 때 저장된 operation 은 이미
SUCCEEDED입니다. 진짜 비동기 잡이라면 PENDING → RUNNING → 종료 로 전이하겠지만, wire 모양 (202 + Location + 폴링 enum)은 동일합니다.
SamplePolymorphicRequest — 안전한 다형 역직렬화(B5)
- 다형 JSON 을 안전하게 받는 표준 예시입니다.
@JsonTypeInfo(use = NAME, property = "kind")+ 명시적@JsonSubTypes허용 목록은, RCE 취약점(CVE-2019-14379)의 입구인ObjectMapper.enableDefaultTyping()대신 Jackson 이 권장하는 방식입니다. 목록에 없는 하위 타입은InvalidTypeIdException으로 거절되고, 계약 핸들러가 이를MAPPING_FAILED로 보냅니다. sealed키워드를 쓴 이유: 허용 목록과 타입 계층을 기계적으로 일치시키기 위해서입니다.permits만 추가하고@JsonSubTypes.Type을 안 넣거나(혹은 반대로) 하면 조용히 통과되는 게 아니라 컴파일/테스트에서 잡힙니다.
WorkLogWebMapper
- 요청 DTO ↔ application command 변환을 웹 어댑터가 전부 책임지게 모은 매퍼입니다. PATCH 도
컨트롤러에서 인라인으로 만들지 않고 매퍼를 거치게 해서 일관성을 지킵니다.
WorkLogId는 웹 edge 에서 파싱(UUID 경로 정규화)해 넘겨받아, id 구문 관심사를 컨트롤러에 둡니다. - 응답에는 소유자(owner)를 일부러 넣지 않습니다 — 원시 principal id 노출은 프라이버시 문제라, 가명화는 별도 프라이버시 계약의 몫입니다.
- 링크 URI 가 잘못되면
MappingException을 던져 전역 핸들러가MAPPING_FAILED(400)로 보냅니다.
WorkLogIdSerializer
WorkLogId를 record 기본 모양({"value":"..."})이 아니라 맨 36자 소문자 UUID 문자열로 직렬화합니다.@JsonComponent로 Spring Boot 가 자동 등록합니다.
DomainExceptionHandler / PortfolioErrorCode
- DomainExceptionHandler: 이 샘플의 도메인 예외를
Envelope로 매핑합니다. 운영/전송/보안 예외는 스켈레톤의 기본GlobalExceptionHandler가 처리하고, Spring 이 두 advice 를 함께 적용합니다. 이 핸들러를@Order(HIGHEST_PRECEDENCE)로 기본 핸들러보다 앞에 두는 이유는, 그렇지 않으면 기본 advice 의 포괄 핸들러(@ExceptionHandler(Exception.class))가 도메인 예외를 먼저 잡아 INTERNAL_ERROR 로 만들어 버리기 때문입니다. - PortfolioErrorCode: 이 샘플 전용 도메인 에러 코드. 운영/전송/보안 코드는 공용
OperationalError에 있습니다.
WorkLogValidationGroups
@GroupSequence용 검증 그룹 순서(형식 → 불변식)를 정의합니다 — 형식 검사가 실패하면 불변식 평가를 건너뛰게 합니다.
adapter/persistence — RDBMS / JPA 영속
WorkLogEntity
- WorkLog 애그리거트의 JPA 엔티티.
AuditableEntity를 상속해created_at/updated_at/created_by/ updated_by감사 컬럼을 물려받습니다. 감사 필드는 엔티티(영속 계층)에만 있고 도메인 WorkLog 에는 없습니다 — 값은WorkLogRepositoryAdapter가 Clock + 감사 컨텍스트로 찍어줍니다. - id 저장 형식: UUIDv7 을 varchar(36)가 아니라 PostgreSQL 16 의 native
uuid타입(16바이트 바이너리)으로 저장합니다. UUID 문자열↔native uuid 변환은WorkLogPersistenceMapper가 합니다. (tenant 범위 컬럼/복합 인덱스는 tenant 정책 계약으로 미뤄둠.) @Version version: 낙관적 락 버전이자 웹 경계 ETag/If-Match 의 출처. Hibernate 가 증가를 관리하고,null이면 새 행이라save()가 INSERT 합니다.
WorkLogPersistenceMapper — UUID 문자열 ↔ native uuid 변환
- 36자 canonical UUID 와 PostgreSQL native
uuid(128비트)를 JDKjava.util.UUID로 직접 변환합니다. - 엔티티로 변환할 때 도메인
version을 그대로 실어, JPA 가 새 행(null→ INSERT)과 추적 중인 행 (non-null → 낙관적 merge)을 구분할 수 있게 합니다.
WorkLogRepositoryAdapter — 저장 + 감사 스탬프
WorkLogRepository포트 구현체. 감사 메타데이터(생성/수정 시각·주체)를 여기 영속 어댑터에서 찍습니다(생성자 주입 Clock + 감사 컨텍스트). 도메인 WorkLog 는 감사 필드를 들고 있지 않습니다.- INSERT(버전 null): 새 애그리거트라 created/updated 둘 다 지금 시각·주체로 초기화합니다.
- UPDATE(버전 non-null): 새 엔티티를 merge 하지 않고, 유스케이스가 같은 트랜잭션에서 읽어 둔 관리
엔티티에 값을 덮어씁니다(
WorkLogPersistenceMapper.copyState→WorkLogEntity.replaceState, 1차 캐시라 추가 왕복 없음). 새 엔티티는 새List를 들고 오고, Hibernate 는 바뀐 컬렉션을 "전부 지우고 전부 다시 넣기"로 처리합니다 — 제목만 고친 PATCH 가work_log_tech_stack·work_log_link를 매번 삭제·재삽입했습니다 (리뷰 09-06, 실측 13문장). 이제 컬렉션은 내용이 다를 때만 교체하고, 같으면 SQL 이 없습니다. 비교는 복사본으로 합니다: HibernatePersistentBag.equals는 인스턴스 동일성이라 같은 내용이어도 false 입니다. - created 값은 저장된 그대로 두고 updated 만 갱신합니다. 도메인 객체의 version 이 관리 엔티티와 다르면(다른
시점에 읽은 객체)
ObjectOptimisticLockingFailureException으로 거절합니다 — merge 가 하던 것과 같은 답입니다. 그 사이 다른 트랜잭션의 수정은@Version조건 UPDATE 가 잡습니다. saveAndFlush로 UPDATE 를 그 자리에서 실행해, Hibernate 가 올린 version 이 반환 객체(→ 응답 ETag)에 들어갑니다.
PosterRepositoryAdapter — 중복 규칙은 DB 제약 + 충돌 변환
- 포스터 제목은 대소문자를 무시하고 유일합니다. 이 규칙은 DB 유일 인덱스가 지킵니다
(
uq_poster_title_ci ON poster (upper(title)), 샘플 마이그레이션 V8.1). CreatePosterUseCase의existsByTitle사전 조회는 흔한 경우에 일찍 409 를 주는 용도일 뿐입니다. READ COMMITTED 에서 동시 요청 둘은 모두 "없음"을 보고 둘 다 insert 하므로, 조회만으로는 규칙이 깨집니다(리뷰 09-02: 동시 16요청에 10행).save()는saveAndFlush로 insert 를 그 자리에서 실행하고,uq_poster_title_ci위반을 사전 조회와 같은PosterTitleAlreadyExistsException(409POSTER_ALREADY_EXISTS)으로 바꿉니다. flush 를 미루면 위반이 커밋 시점에 일반DB_UNIQUE_VIOLATION으로 나와 도메인 오류 코드를 잃습니다.- 버린 대안: 비관적 락·
SERIALIZABLE격리(더 비싸고 재시도가 필요함), 사전 조회만 유지(동시성에서 깨짐). - 수정(PATCH)도 같은 규칙입니다. 다른 포스터가 가진 제목(대소문자 무시)으로 바꾸면 같은
PosterTitleAlreadyExistsException→ 409POSTER_ALREADY_EXISTS입니다.UpdatePosterUseCase는 사전 조회를 하지 않습니다:existsByTitle은 자기 자신의 제목도 찾아서, 같은 포스터의 대소문자만 바꾸는 수정을 잘못 거절하기 때문입니다. 인덱스만으로 규칙이 지켜지고 동시 수정에서도 같습니다. 고정 테스트:PosterRepositoryAdapterIntegrationTest.renamingAPosterToAnotherPostersTitleIs…,…ToItsOwnTitleInAnotherCaseIsAccepted,PosterControllerWireTest.patchToATitleAnotherPosterHolds…. - 인덱스 키가
upper(title)인 이유: 사전 조회(existsByTitleIgnoreCase)를 Hibernate 가upper(title) = upper(?)로 만들기 때문입니다. 같은 식이라 그 조회도 순차 스캔 대신 이 인덱스를 씁니다. 제목 정렬용ix_poster_title은 그대로 둡니다. - 버전이 9 가 아니라 8.1 인 이유: 일부 샘플 테스트는 프로덕션 위치와 샘플 위치를 한 Flyway 로 합쳐 돌리고, 프로덕션이 9 이상 정수 버전을 이미 씁니다. 소수 버전은 겹치지 않습니다. 마이그레이션은 이미 중복 제목이 있으면 그 제목을 이름으로 대며 멈춥니다.
WorkLogJpaRepository
findSummaryRows/findSummaryRowsByCategory: 목록 projection. 같은SUMMARY_SELECT에 정렬·페이지는Pageable로, 카테고리는 계약이 허용하는 유일한 필터 구문인 평면 동등 필터로 붙입니다. count 쿼리를 명시해 Spring Data 가 생성자 표현식에서 count 를 추론하지 않게 합니다.findRecentSummaryRows: 같은 projection, count 없음. CQRS-lite projection 읽기. JPQLSELECT new생성자 표현식으로 요약 컬럼만 골라(content/summary/techStack/links제외)WorkLogSummaryRow로 담는 컬럼-부분 읽기라, 애그리거트 복원과 lazy@ElementCollection조인을 건너뜁니다. 닫힌 인터페이스 projection 대신SELECT new/JdbcTemplate을 택한 이유: 닫힌-projection 의 컬럼 가지치기는 구현체 의존적이고 Hibernate 6 에서 검증되지 않았기 때문입니다.
WorkLogSummaryQueryAdapter / WorkLogSummaryRow
- WorkLogSummaryQueryAdapter: application
WorkLogSummaryQueryPort구현체. JPQL projection 쿼리에 위임하고, 저장소 nativeWorkLogSummaryRow(UUID id)를 applicationWorkLogSummary(UUID 문자열 id)로 매핑합니다. 저장소 nativeUUID는 이 어댑터를 벗어나지 않습니다 — application 에 노출되는 읽기 모델은 canonical UUID 문자열 형식으로 말합니다. - WorkLogSummaryRow: projection 의 영속-쪽 읽기 행. JPQL
SELECT new의 대상이며 저장 모양 (id 가 nativeUUID)을 그대로 반영합니다. 이 행을 persistence 패키지 안에 두는 것 자체가 nativeUUID가 어댑터를 벗어나지 못하게 막는 장치입니다.
JpaConfig
- Spring Boot 메인 클래스가
dev.caskeleton.bootstrap에 있어, 패키지 기준 기본 스캔이…sample.portfolio.adapter.persistence.*를 놓칩니다. 그래서 엔티티/리포지토리 스캔 위치를 여기서 명시해, 그 배선을 실제로 소유하는 모듈 안에 둡니다.
adapter/outbound — 아웃바운드 통합 (저장소 통계 ACL)
RepoStatsPortClient / RepoStatsAclMapper / RawRepoStatsResponse
- ACL(Anti-Corruption Layer) 패턴(B7) 예시입니다. 외부 응답이 도메인으로 들어오기 전에 반드시 ACL 매퍼를 거치게 해서, 원시 외부 타입이 도메인을 오염시키지 못하게 합니다.
- RepoStatsPortClient: 실제 HTTP 호출(
fetchRaw)을 추상화해 템플릿을 가볍게 유지합니다 — 실제 프로젝트라면 여기에 WebClient/RestClient 를 끼웁니다. 원시 응답은 ACL 을 통과한 뒤에야 도메인 타입이 됩니다. - RepoStatsAclMapper: ACL 의 세 가지 일 — 정규화(full name 소문자화), 마스킹(echoedToken 은 버려서
도메인에 닿지 않음), 공개 필드 선택(
fullName/stargazers/pushedAt만RepoStats로). 필수 필드가 없으면MappingException. - RawRepoStatsResponse: 외부 제공자 원시 모양. 도메인으로 넘어가지 않으며 package-private 입니다.
adapter/identifier — ID 생성 (UUIDv7)
UuidWorkLogIdFactory / UuidOutboxEventIdFactory
- id 포트(
WorkLogIdFactory(도메인),OutboxEventIdFactory(application))의 인프라 구현체입니다. - 둘 다
UuidCreator.getTimeOrderedEpochPlus1()을 씁니다 — RFC 9562 UUIDv7(time-ordered)이며 같은 밀리초 안에서도 단조 증가(monotonic)하고 secure random 으로 뒷받침됩니다. - 여기가 샘플에서
UuidCreator호출이 허용되는 유일한 곳입니다.no_uuid_random_in_controllerArchUnit 규칙이 웹/application 계층의 직접 id 생성을 금지하기 때문에, id 생성은 이 인프라 어댑터에만 둡니다.
bootstrap — 샘플 전용 구성 루트
이 패키지가 왜 존재하는가 (공통 배경): 프로덕션 조립은
app-bootstrap모듈이 합니다.sample-portfolio는 일부러app-bootstrap에 의존하지 않습니다(샘플이 부트스트랩을 끌어오면 안 됨). 두 구성 루트가 함께 필요한 조립은 공용composition:*모듈이 하고, 샘플은 app-bootstrap과 같은runtimeOnly한 줄로 받습니다 — tracing·metrics 계약 filter·domain context·user principal 가명화·actuator 보안 chain은composition:service-runtime, 멱등성 executor는composition:idempotency. 예전에는 이것들을 여기bootstrap.*패키지에 복사해 두었고, 복사본은 이미 원본과 갈라져 있었습니다(런타임 어휘에 없는staging샘플 레이트, typed startup 실패 대신IllegalStateException). 여기 남은 것은 샘플만의 결정입니다.
SamplePortfolioApplication — 독립 실행 구성 루트
- 관계형 저장소는 다른 서비스와 똑같이 고른다:
build.gradle의implementation project(':adapter:outbound:persistence-jpa')한 줄과 그 모듈의 auto-configuration. (implementation인 이유는 샘플 어댑터가 모듈의AuditableEntity·AuditContextPort를 직접 쓰기 때문이다.) 컴포넌트 스캔과@ConfigurationPropertiesScan은 샘플 패키지(dev.caskeleton.sample) 하나만 본다. web·objectstorage는 자기AutoConfiguration.imports로, identifier는 샘플 config가 직접 만드는 타입으로 들어온다. 그래서 JPA가 두 번 들어오거나 모듈의 기동 가드 없이 들어오는 일이 없고, web leaf에 새 컨트롤러가 생겨도 샘플에 끌려오지 않는다(Wave 2 때 web 스캔이 durable operation 엔드포인트를 샘플에 등록한 적이 있다). @SpringBootApplication대신@Configuration+@EnableAutoConfiguration+@ComponentScan을 쓴 이유:@SpringBootApplication은@SpringBootConfiguration을 포함하는데, 그러면 이 클래스가 Spring Boot 의AnnotatedClassFinder에 보입니다. 그 finder 가 이 클래스와 (같은 패키지·테스트 classpath 의)SamplePortfolioTestApplication둘 다 찾으면 "multiple @SpringBootConfiguration" 오류를 냅니다.@Configuration(=@SpringBootConfiguration아님)을 쓰면 finder 에 숨으면서도,@SpringBootTest(classes = SamplePortfolioApplication.class)로 부팅하는 데는 문제가 없습니다.@EnableAutoConfiguration(exclude = WebSecurityAutoConfiguration.class): web leaf의 인증 체인 (JWT 필터 체인)만 뺀다 — IdP 없이 띄우는 데모라 그 자리는SampleDemoSecurityConfig(읽기 공개, 나머지는 데모 계정 HTTP Basic)가 채운다. 메서드 보안은 빼지 않는다:@RequiresPermissionadvisor와 권한 port는WebMethodSecurityAutoConfiguration으로 프로덕션과 같게 들어와서, 데모 계정의 역할도app.authz표로 검사된다. 에러 envelope·필터·health·rate limit은WebAdapterAutoConfiguration으로 프로덕션과 같게 들어온다.- 예전에는 체인과 메서드 보안이 한 root에 있어서, 체인을 빼면 권한 검사도 같이 꺼졌다. 실행 중인
샘플에서 누구나 삭제할 수 있었고, 인증 주체가 없어 owner가 null이라 생성은 항상 500이었다(리뷰
07-03·09-03).
SampleWorkLogAuthorizationSystemTest가 실제 서버로 이 동작을 지킨다. - 버린 대안: 공개 체인을 두고 README에 경고만 적기(위험이 코드에 드러나지 않는다), 샘플에서
@RequiresPermission을 지우기(인가 위치를 보여 주는 예시가 사라진다),X-Demo-Role같은 헤더를 그대로 믿는 필터(호출자가 역할을 스스로 주장하는 패턴이 복제될 위험).
- 예전에는 체인과 메서드 보안이 한 root에 있어서, 체인을 빼면 권한 검사도 같이 꺼졌다. 실행 중인
샘플에서 누구나 삭제할 수 있었고, 인증 주체가 없어 owner가 null이라 생성은 항상 500이었다(리뷰
07-03·09-03).
- 데이터 계층을 빼고 뜨는 테스트 슬라이스(
DataSourceAutoConfiguration제외)는app.persistence-jpa.enabled=false도 함께 준다. 모듈은 classpath에 있으면 켜지기 때문이다.
SamplePostgreSqlPersistenceConfig — 샘플 전용 두 번째 마이그레이션 스트림
- 샘플 스키마(
db/sample-migration)를 별도 history 테이블(flyway_sample_schema_history)로 적용하는FlywayMigrationStrategy하나만 둔다. 프로덕션 스트림을 먼저 migrate 한 뒤 샘플 스트림을 baseline 0 으로 적용하므로, 샘플 V2/V7/V8이 프로덕션 버전 번호를 차지하지 않는다. - vendor bean(
OutboxClaimRepository,SqlStateErrorMapping), 엔티티·리포지토리 스캔, 프로덕션 Flyway 위치는 persistence-jpa 모듈이 준다. 모듈의migrationStartupRunner는@ConditionalOnMissingBean(FlywayMigrationStrategy)라 이 전략이 있으면 물러난다.
공용 runtime 배선 — composition:service-runtime
- tracing(
TracingConfig, 샘플 레이트 resolver, sampling bridgeEnvironmentPostProcessor,MicrometerSpanErrorRecorder), metrics 계약 filter(MetricsContractConfig), domain context propagator(DomainContextConfig), user principal 가명화(PseudonymizationConfig/PrivacySettings), actuator 보안 chain(ManagementSecurityConfig)을 app-bootstrap과 같은 모듈에서 받습니다. 설정 키(app.tracing.*,app.privacy.*)는 그대로입니다. - 샘플 레이트 기본값은 공용 런타임 어휘(
RuntimeEnvironment)를 따릅니다:prod=0.01, 그 밖은 1.0. 샘플 복사본에만 있던staging=0.10분기는 삭제했습니다 —staging프로파일은 이 템플릿에 없습니다. - SampleManagementSecurityConfig: 샘플의 actuator chain은 복사본이 아니라 샘플만의 결정입니다
(IdP 없이 둘러볼 수 있는 공개 데모라 모든 요청 허용). 공용 모듈의 chain과 같은 bean 이름
actuatorSecurityFilterChain으로 선언해, 공용 chain이 물러나게 합니다. 그래서loggers는 읽기 전용으로 둡니다(SampleActuatorLoggersAccessTest).
그 밖의 부트스트랩 구성
- 멱등성 executor: 샘플은
app.capabilities.idempotency.provider=postgresql로persistence-jpa의 PostgreSQL store 를 고르고, executor 는 app-bootstrap 과 같은composition:idempotency모듈이 만듭니다(runtimeOnly한 줄). 예전의 샘플 복사본SampleIdempotencyConfig(상한 검증 없이Binder로 읽고 store 를 하나로 가정)는 삭제됐고,Clock과@EnableScheduling만bootstrap/runtime/SampleSchedulingConfig로 남았습니다.