매뉴얼 예제 칸 14곳(S4 3.3절)과 산문 30여 곳이 참조 기능을 가리킨다. problem details(Envelope가 아닌 백엔드) 응답 매핑의 예는 참조 기능에만 있다. 생성기 출력이 그 모양을 만들면 그 경로로 바꿨다. 없으면 매뉴얼 안 코드 조각으로 썼다: problem details의 분류와 매핑(02 결정표 4절, 소유자 결정 D1), 도메인 모델, 검색값 스키마와 hook, 실패 행동 hook, 403 페이지 시험. 조각마다 manual-code-block 표식에 둘 경로를 적는다. tests/unit/manual-code-blocks.test.ts가 저장소 사본에 create:feature invoice-feature --with-create를 만들고 조각을 그 경로에 그대로 넣어 tsc(app, test), eslint, check:architecture, 그 기능 폴더의 vitest를 돈다. 조각의 동작은 tests/fixtures/manual-code-blocks/가 본다. 위험: 403 조각은 본문 없는 403으로 답한다. 공유 시나리오 forbidden-403(JSON 본문)은 jsdom + MSW에서 실행기의 본문 cancel이 끝나지 않아 화면이 로딩에 머물렀다. 실행기는 고치지 않았다. 사본에 이미 invoice-feature가 있는 프로젝트에서는 이 시험이 생성 단계에서 실패한다. 검증(desktop): test:unit 213 files 3096 passed(이 커밋까지), verify:documentation PASS_SCOPED, lint 통과.
40 KiB
02. 결정표
기능을 만들며 고르는 일곱 가지다. 각 절은 같은 순서로 쓴다.
무엇을 고르나 → 선택지 비교 → 고르는 기준 → 어디에 적나 → 틀리면 무엇이 잡나
판단 원칙은 design-docs repo의 conventions/feature-design-principles.md에 있다. 여기서는 번호로만 가리킨다.
1. context 경계
무엇을 고르나: 새 기능을 기존 context에 넣을지, 새 context를 만들지.
context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기능들은 함께 지연 로드된다.
사용자가 /invoice 로 들어온다
→ 라우터가 루트 invoice/* 를 가진 context를 찾는다
→ 그 context의 기능들(context-routes.ts)을 한 번에 지연 로드한다
→ 기능 라우트 중 경로가 맞는 페이지를 그린다
| 기존 context에 넣는다 | 새 context를 만든다 | |
|---|---|---|
| 언제 | URL 앞부분, 함께 로드·배포되어도 되는지, 소유자 셋이 모두 같다 | 셋 중 하나라도 다르다 |
| 명령 | corepack pnpm create:feature <id> --context <context id> |
corepack pnpm create:feature <id> |
| 라우트 경로 | /<루트>/<base> |
/<base> (루트는 <base>/*) |
| 기능 폴더 밖 | 없음 | src/contexts/<base>-context/context-module.ts (명령이 만든다) |
| 주의 | context의 기능 수 예산(CONTEXT_MAX_FEATURES)을 넘으면 생성기가 거부한다 |
앱이 하나일 때만 명령이 만든다. 앱이 여럿이면 --context로 기존 context를 고른다 |
기준: 원칙 1. context 하나는 루트 경로 하나만 가진다. 그래서 URL 앞부분이 다르면 다른 context다.
어디에 적나: src/contexts/<context>/context-module.ts의 CONTEXT_ROUTE_PATH, 기능의 feature-module.ts의 FEATURE_CONTEXT_ID.
틀리면
- 기능 라우트가 루트 밖이면 앱 모듈이 적재 때 거부한다(
... is not under the route root of its context ...). - 경계를 업무상 잘못 고른 것은 검사가 잡지 못한다.
근거: scale-architecture.md §5(모듈 소유), §7(개수 예산), §9(라우터 구조).
2. 계약 출처
무엇을 고르나: 기능의 API 계약(V3 descriptor와 패키지 신원)을 어디서 받나.
| 배포된 계약 패키지 | 자리표시자 신원 | TEMPLATE_FIXTURE |
|
|---|---|---|---|
| 언제 | 백엔드가 @org-contracts/<service> 패키지를 배포했다 |
패키지가 아직 없다 | 쓰지 않는다. 템플릿이 예전 참조 샘플에 쓰던 출처다 |
| 만드는 법 | create:feature에 --package, --digest, --revision을 준다 |
create:feature에 패키지 인자를 주지 않는다 |
— |
| 로컬·개발 빌드 | 된다 | 된다 | 제품 기능에 쓰면 계약 조립이 거부한다 |
| staging·production 승인 | 된다 | check:release-admission(FE-GATE-027)이 거절한다 |
— |
자리표시자 값은 src/contracts/deployment-admission.ts의 세 상수다.
PLACEHOLDER_CONTRACT_PACKAGE_DIGEST:sha256:뒤에 0이 64개PLACEHOLDER_CONTRACT_PACKAGE_VERSION:0.0.0PLACEHOLDER_CONTRACT_PACKAGE_REVISION:0000000
기준: 원칙 2. 제품 기능은 버전과 digest를 고정한 패키지만 쓴다. 패키지를 기다리느라 화면 작업을 멈추지 않도록 자리표시자로 시작할 수 있다. 다만 공개 환경에는 나가지 못한다.
어디에 적나
- 신원 네 필드:
contracts/<base>-feature-contract.ts의<BASE>_CONTRACT_PACKAGE. - 패키지 descriptor import:
contracts/<base>-contract-contribution.ts에서만. - 자리표시자를 실제 신원으로 바꾸는 절차: 03 문서 "자리표시자 교체".
틀리면
- 신원 형식이 틀리면(정확한 SemVer 아님, digest가 소문자 hex 64자리 아님 등) 생성 명령과 계약 조립이 거부한다.
- 자리표시자로 공개 대상을 승인받으려 하면
contractPackages.<packageId>: pins the placeholder identity create:feature writes; ...로 거절된다.
3. 재시도 의미
무엇을 고르나: operation을 다시 보내도 되는지. V3 retrySemantics에 적는다.
읽기(GET)는 늘 SAFE다. 자동 재시도가 된다(retryBudget 0~2). 생성된 뼈대가 이 경우다.
쓰기는 서버가 무엇을 보장하는지로 고른다.
KEYED |
IDEMPOTENT |
NEVER |
|
|---|---|---|---|
| 서버 보장 | 멱등 키(Idempotency-Key 헤더)로 같은 요청의 중복 적용을 막는다 |
같은 요청을 여러 번 적용해도 결과가 같다 (키 없이) | 중복을 막지 못한다 |
| 자동 재시도 | 실제로 보내기 전까지만. 보낸 뒤 결과를 모르면 결과 불명(4절)으로 넘긴다. 예외: 짝 백엔드가 503 IDEMPOTENCY_UNAVAILABLE(실행 전 거절)로 답하면 retryBudget 안에서 같은 키로 다시 보낸다 |
된다 | 하지 않는다 |
| descriptor | commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField } 필수. 짝 백엔드는 retryBudget: 1(아래 표). 503 같은 키 재전송 규칙이 없는 백엔드는 0 |
— | retryBudget: 0 필수 |
| 뮤테이션 정책 | ...commandMutationIdentity(<OPERATION>_CONTRACT)가 requiresIdempotencyKey: true, resendSafe: true를 준다 |
같은 함수가 requiresIdempotencyKey: false, resendSafe: true를 준다 |
같은 함수가 둘 다 false로 준다 |
| 결과 불명 뒤 | "같은 요청으로 다시 보내기"와 같은 입력 저장이 같은 키로 간다 | 다시 보내기와 같은 입력 저장이 키 없이 간다(1106/03-03) | 확인만 남는다. 같은 입력 저장은 보내지 않는다 |
- 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다.
- 결과를 모를 때 새 키로 다시 보내면 안 된다. 서버는 새 키를 다른 요청으로 보고 막지 못한다.
기준: 원칙 3. 서버 계약에 적힌 보장으로 고른다. 모르면 NEVER로 두고 백엔드에 묻는다.
짝 백엔드의 생성 기능에 붙일 때 (1103/16-07, 03-07)
짝 백엔드 new-feature.sh가 만드는 create는 NOT_IDEMPOTENT다(Create__Feature__UseCase.java.tmpl). Idempotency-Key를 읽지 않는다. 그래서 프론트 쪽 값은 백엔드 create를 그대로 두었는지로 정해진다.
백엔드 create
├─ 생성한 그대로 (NOT_IDEMPOTENT, 키를 읽지 않음)
│ → 프론트 NEVER ← create:feature <id> --with-create
└─ IdempotencyExecutor 뒤로 옮김 (KEYED, 백엔드 docs/manual/05-idempotency.md "KEYED로 만드는 순서")
→ 프론트 KEYED ← create:feature <id> --with-create --keyed
백엔드가 키를 읽지 않는데 프론트를 KEYED로 두면 안 된다. 결과 불명 화면의 "같은 요청으로 다시 보내기"가 새 항목을 하나 더 만든다. 같은 키가 중복을 막는다는 보장이 백엔드에 없다.
두 경우의 값이다. 생성 명령이 이 값을 쓴다. 손으로 만들 때도 같은 값을 쓴다.
| 값 | NEVER (백엔드 그대로) |
KEYED (백엔드 KEYED) |
이유 |
|---|---|---|---|
retrySemantics |
"NEVER" |
"KEYED" |
백엔드가 키를 읽는지 |
frontend.retryBudget |
0 (조립이 강제) |
1 |
백엔드는 503 IDEMPOTENCY_UNAVAILABLE(작업 실행 전 거절)에 "같은 키로 다시"를 요구한다. 실행기는 이 답에만 같은 키로 스스로 다시 보낸다. 실제 상한은 min(retryBudget, 앱 MAX_RETRY_ATTEMPTS(기본 2), 하드 상한 2)이다. 응답을 잃은 뒤에는 스스로 다시 보내지 않는다 |
commandRecovery |
null |
{ mode: "IDEMPOTENCY_REPLAY", operationIdentityField: "idempotencyKey" } |
조립이 KEYED에 요구한다. operationIdentityField는 같은 요청을 알아보는 값의 이름이다. 실행기는 intent의 idempotencyKey를 Idempotency-Key 헤더로 보낸다. 이 칸은 FE-REG-API에 기록되고 실행기는 읽지 않는다 |
호출 문맥의 intent |
넘긴다(키 없음) | 넘긴다(키 있음) | 뮤테이션 조정자가 만든 intent를 input → gateway → 바인딩까지 그대로 넘긴다(생성된 <Base>CommandContext가 intent를 필수로 받는다). 빠뜨리면 KEYED는 보내기 전에 거부된다 |
commandEffect.classifyStatus |
() => "NOT_APPLIED" |
같다 | 생성된 create의 401은 보안 필터 체인, 403은 use case의 @RequiresPermission 프록시, 429는 rate-limit interceptor(preHandle)가 use case 전에 낸다. use case 안에서 AuthorizationPort를 쓰기 뒤에 부르게 바꾸면 403이 쓰기 뒤에도 나올 수 있다. 그때는 이 칸을 지운다(= MAYBE_APPLIED) |
commandEffect.refusedBeforeWrite |
["<FEATURE>_INVALID"] |
같다 | 이름 규칙을 트랜잭션 전에 검사한다(4절) |
acceptedStatuses |
[201] |
[201] |
ResponseEntity.created. 같은 키 재생도 첫 요청과 같은 201이다 |
| 결과 불명 화면 | 확인만. 다시 보내기 버튼 없음 | "같은 요청으로 다시 보내기"가 같은 키로 보낸다 | 키 없는 재전송은 서버가 새 요청으로 본다 |
| 생성 테스트 | 응답 유실 → 결과 불명, 다시 보내기 없음, 키 헤더 없음. "변경됨으로 확인" → 목록 화면 | 응답 유실 → 같은 키로 다시 보내기. 503 IDEMPOTENCY_UNAVAILABLE → 같은 키로 1회 자동 재전송. "변경됨으로 확인" → 목록 화면 |
tests/features/<id>/<base>-create-page.test.tsx, <base>-http-gateway.test.ts |
- 테스트 하네스의 재시도 상한: 생성된 gateway 테스트는 앱 기본값(
maxRetryAttempts: 2)으로 돈다. 그래야retryBudget: 1의 재전송이 보인다. 페이지 테스트(<base>-test-app.tsx)는 실패를 바로 보이려고MAX_RETRY_ATTEMPTS: 0이다.
정본: 백엔드가 멱등 키 요청에 어떻게 답하는지는 clean-architecture-backend-template/docs/web/http-contract.md §2(멱등성 응답)다. 여기에 표를 옮기지 않는다.
어디에 적나: contracts/<base>-contract-contribution.ts의 retrySemantics, commandRecovery, frontend.retryBudget. 다른 파일에 다시 적지 않는다.
틀리면
- 읽기(GET·HEAD)에
KEYED나NEVER를 적으면 계약 조립이<method> is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값>으로 거부한다. - 쓰기(POST·PUT·PATCH·DELETE)에
SAFE를 주면 계약 조립이SAFE retry semantics is for GET and HEAD only; ...로 거부한다.SAFE는 보낸 뒤 응답을 잃어도 다시 보내는 의미라, 쓰기에서는 같은 생성이 두 번 나간다. 생성된 뼈대의 GET descriptor를 복사해 쓰기를 만들 때retrySemantics를 위 표에서 다시 고른다. NEVER에retryBudget을 0보다 크게 주면 계약 조립이retry budget contradicts NEVER retry semantics로 거부한다.KEYED에commandRecovery가 없으면KEYED commands require a recovery descriptor로 거부한다.- 서버 보장과 다른 의미를 고른 것은 검사가 잡지 못한다.
근거: scale-architecture.md §13(재시도 모델).
4. 결과 불명
무엇을 고르나: 쓰기가 실패 응답을 받았을 때 "적용 안 됨"으로 볼지, "적용됐을 수도 있음"으로 볼지.
- 결과 불명: 서버가 요청을 적용했는지 모르는 상태다. 응답을 잃었거나, 서버가 "처리 중"이라고 답한 경우다.
쓰기 요청
→ 실패 응답 (또는 응답 없음)
→ commandEffect.classifyProblem({ status, problem })
├─ NOT_APPLIED → 폼 오류·실패로 보여 준다. 다음 저장은 새 키를 쓴다
└─ MAYBE_APPLIED → 결과 불명 화면
├─ 확인 (onReconcileUnknownEffect)
└─ 같은 키로 다시 보내기 (onResendUnknownEffect)
키가 있는 요청만. 키 없는 쓰기(NEVER)는 버튼이 없다
NOT_APPLIED |
MAYBE_APPLIED |
|
|---|---|---|
| 뜻 | 서버가 상태를 바꾸지 않았다 | 바꿨을 수도 있다 |
| 언제 | 서버 계약이 "상태를 바꾸지 않음"을 보장하는 status·code | 그 밖의 모든 경우. 모르는 code 포함 |
| 화면 | 실패·폼 오류 | 결과 불명 화면 |
| 다음 전송 | 새 멱등 키 | 같은 멱등 키 |
기준: 원칙 3.
- 서버가 보장하는 것만
NOT_APPLIED로 적는다. 나머지는MAYBE_APPLIED다. - 같은 status라도 code로 나뉠 수 있다. 예: 409 중 "처리 중"은
MAYBE_APPLIED여야 한다.NOT_APPLIED로 보면 다음 저장이 새 키를 만들어 같은 작업이 두 번 적용된다. - 401·403·429는 문제 응답 본문을 읽기 전에 status로 나뉜다. 서버가 상태를 안 바꾼다고 보장하면
classifyStatus로NOT_APPLIED를 돌려준다. 없으면MAYBE_APPLIED다. - 문제 응답 본문이 기능의 problem 스키마를 통과하지 못하면
classifyProblem을 부르지 않는다. 쓰기는MAYBE_APPLIED가 된다(src/adapters/http/http-execution-v3.ts). responseEnvelope: "ENVELOPE_V1"인 operation은 400·409·422와 백엔드가 직접 정한 5xx 여섯 가지의 판정을 실행기가 백엔드 기준 표로 정한다(src/adapters/http/backend-envelope.ts의REFUSED_BEFORE_WRITE,MAYBE_APPLIED_ANSWERS). 표의 근거는 계약 문서 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과).classifyProblem은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다.NOT_APPLIED(쓰기 전 거절): 400VALIDATION_FAILED(details 모양과 상관없음), 400IDEMPOTENCY_KEY_INVALID, 422IDEMPOTENT_REQUEST_MISMATCH, 503RATE_LIMIT_UNAVAILABLE·RATE_LIMIT_INCOMPATIBLE(rate-limit 저장소 장애·제공자 불일치. 컨트롤러 전에 거절한다)MAYBE_APPLIED: 그 밖의 400·409·422. 409IDEMPOTENT_IN_FLIGHT,BAD_PARAMETER, 도메인 code, fileserver의 422가 여기 든다. 그리고 status와 code가 함께 맞는 5xx 넷: 503IDEMPOTENCY_UNAVAILABLE, 503IDEMPOTENCY_COMPLETION_UNKNOWN(실행 뒤 결과 기록 실패, 새 키 금지), 500IDEMPOTENCY_RECOVERY_REQUIRED(이전 시도 효과를 증명 못 함), 503REQUEST_TIMEOUT(비동기 요청 시간 초과, 처리가 계속될 수 있음)- 이 넷은 실행기가 자동으로 다시 보내지 않는다. 결과 불명 화면에서 같은 키로 다시 보낸다. 예외는 KEYED 명령의 503
IDEMPOTENCY_UNAVAILABLE하나다(아래) - 짝 백엔드가 모든 엔드포인트에서 쓰기 전에 거절하는 code를 새로 만들면 계약 문서 6.1절과 이 표를 함께 고친다. 표에 없으면
MAYBE_APPLIED다
- 업무 규칙 거절은 operation이 선언한다. 도메인 code(
<FEATURE>_INVALID,*_ALREADY_EXISTS등)는 엔드포인트마다 쓰기 전에 나오는지가 다르다. 그래서 표에 없고, 그대로 두면 결과 불명이 된다. 폼은 "변경 결과를 확인할 수 없습니다"를 보이고 저장 버튼을 끈다. 사용자가 값을 고쳐 다시 저장할 수 없다.- 그 엔드포인트가 쓰기 전에만 내는 code라면
commandEffect.refusedBeforeWrite에 적는다. 그 code로 온 400·409·422는NOT_APPLIED가 되고, 다음 저장은 새 키를 쓴다. - 짝 백엔드
new-feature.sh가 만든 create는 이름을 트랜잭션 전에 검사하고 400<FEATURE>_INVALID를 준다(백엔드Create__Feature__UseCase.java.tmpl). 이 code는 적는다. 예: 기능worklog이면refusedBeforeWrite: ["WORKLOG_INVALID"]. - 고르는 기준: 백엔드 코드에서 그 code를 던지는 곳이 모두 쓰기(트랜잭션, 외부 호출) 전인지 확인했을 때만 적는다. 확인하지 못했으면 적지 않는다. 쓰기 뒤에도 나오는 code를 적으면 결과 불명 요청을 새 키로 다시 보내 중복이 생길 수 있다.
- 적을 수 없는 code:
IDEMPOTENT_*,IDEMPOTENCY_*. 멱등성 응답은 백엔드 표가 정한다. 적으면 계약 조립이refusedBeforeWrite cannot declare ...로 거부한다.responseEnvelope: "ENVELOPE_V1"가 아닌 operation에 적어도 거부한다(refusedBeforeWrite needs responseEnvelope ENVELOPE_V1 ...). - 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 플랫폼 code(
BAD_PARAMETER,MAPPING_FAILED,DB_UNIQUE_VIOLATION등DB_*,LOCK_ACQUISITION_TIMEOUT, fileserver code)도 적을 수 없다. 폼을 막는 400BAD_PARAMETER나 409DB_UNIQUE_VIOLATION은 어느 층에서든, 트랜잭션 안에서도 나온다. 적으면 계약 조립이refusedBeforeWrite cannot declare ...; contract 6.1 reads this platform code as possibly raised after the write로 거부한다. - 거절 이유를 필드 옆에 보이려면
mapProblem이 그 code를VALIDATION_REJECTED와 필드 목록으로 돌려준다. 선언 없이mapProblem만 두면 필드 오류는 보이지만 저장 버튼은 꺼진 채다. - 거절 이유를 기능의 말로 보이려면
useAppForm의refusalMessages에 code별로 기능 catalog의 메시지 키와 필드를 적는다(예:{ POSTER_ALREADY_EXISTS: { field: "name", message: "poster.form.nameTaken" } }). 적용 안 됨(NOT_APPLIED)으로 끝난 실패만 읽는다. 그 code는 필드 오류(필드가 없으면 오류 요약)가 되고, 결과는validation-error다. 적지 않으면 선언한 400은 "요청을 처리할 수 없습니다" + 지원 안내, 409는 충돌 문구가 보인다. 결과 불명은 code와 상관없이 결과 불명으로 남는다.
- 그 엔드포인트가 쓰기 전에만 내는 code라면
503 IDEMPOTENCY_UNAVAILABLE는 NOT_APPLIED로 분류하지 않는다.
백엔드는 이 응답을 "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로 정한다(http-contract.md §2 두 번째 표). 적용은 안 됐지만 다음 전송은 같은 키다. 위 표의 두 칸 어디에도 딱 맞지 않는다.
지금 프론트 동작:
503 IDEMPOTENCY_UNAVAILABLE
→ V3 실행기
├─ responseEnvelope: "ENVELOPE_V1" (생성한 기능) → 실행기가 MAYBE_APPLIED로 정한다
│ KEYED이고 retryBudget > 0이면 먼저 같은 키로 다시 보낸다(3절). 예산을 다 쓰면 결과 불명
└─ Envelope 없음 (problem details 백엔드) → 기능의 classifyProblem이 정한다
아래 예: 400·422와 정해 둔 409 code만 NOT_APPLIED → 503은 MAYBE_APPLIED
→ 결과 불명 화면 → "같은 요청으로 다시 보내기"가 같은 키로 보낸다
- 뮤테이션 조정자는 effect가 없는 실패도
MAYBE_APPLIED로 본다(src/presentation/adapters/query/application-query.ts의mutationFailureWithEffect). - 판정: 맞는다. 지금 동작은
MAYBE_APPLIED이고 재전송은 같은 키다. 백엔드가 요구하는 행동과 같다. - 다른 점은 화면뿐이다. 서버는 "실행 안 함"이라고 답했지만 화면은 "결과를 모른다"로 보여 준다.
NOT_APPLIED로 바꾸면 다음 저장이 새 키를 만든다. 키를 다시 쓰는 것은 결과 불명으로 남은 요청뿐이다(같은 파일). 백엔드가 말한 "같은 키"와 어긋난다.
정본: 어떤 status·code가 "적용 안 됨"인지는 clean-architecture-backend-template/docs/web/http-contract.md §2다.
어디에 적나: contracts/<base>-contract-contribution.ts의 commandEffect(classifyProblem, classifyStatus, Envelope operation이면 refusedBeforeWrite). 짝 백엔드 예제는 create:feature <id> --with-create가 만든 그 파일이다. Envelope가 없는 백엔드의 예는 아래에 있다.
problem details 백엔드의 예
짝 백엔드가 아닌 백엔드는 DTO와 problem details(RFC 9457의 type·title·status)를 감싸지 않고 보낸다. 그 백엔드의 작성 operation이 쓰는 두 조각이다. 기능 이름은 invoice-feature(create:feature invoice-feature --with-create로 만든 기능)로 두었다. 자기 기능의 이름으로 바꿔 쓴다.
- 조각 1은
contracts/<base>-problem-details.ts다. problem 스키마와 검증기, 작성의commandEffect를 둔다.- descriptor마다
responseEnvelope: "NONE" as const,problemValidator: <BASE>_PROBLEM_VALIDATOR를 적는다. 작성 descriptor의commandEffect는<BASE>_CREATE_EFFECT다. Envelope operation 전용인refusedBeforeWrite는 적지 않는다. - 스키마 ID(
InvoiceProblem)도 다른 스키마처럼 스키마 메타데이터(contracts/<base>-schema-metadata.ts)에 적는다. 없으면check:registries가 실패한다.
- descriptor마다
- 조각 2는
adapters/<base>-problem-mapping.ts다. HTTP 바인딩의mapProblem이 되는 함수다.adapters/<base>-http-gateway.ts의 작성 operation 정의에mapProblem: map<Base>CreateProblem으로 넘긴다.- 정하지 않은 status는
undefined를 돌려준다. 그러면 실행기가 status로 실패 종류를 정한다.
import { z } from "../../../contracts/zod.ts";
import type { CommandEffectDescriptor } from "../../../contracts/external-contract-runtime.ts";
import { zodValidator } from "../../../contracts/zod-validator.ts";
export const invoiceProblemSchema = z
.object({
type: z.string().min(1).max(512),
title: z.string().min(1).max(240),
status: z.int().min(100).max(599),
code: z.string().min(1).max(120).optional(),
// 422 field issues. The backend's messages are not kept.
issues: z
.array(
z
.object({
path: z.string().min(1).max(120),
code: z.string().min(1).max(80),
})
.strip(),
)
.max(50)
.optional(),
})
.strip();
export type InvoiceProblem = z.output<typeof invoiceProblemSchema>;
export const INVOICE_PROBLEM_VALIDATOR = zodValidator(
"InvoiceProblem",
invoiceProblemSchema,
);
/**
* A 409 is not by itself "refused": a resend with the same key can meet the
* first attempt still running. Only the conflict codes the backend sends
* before it writes are NOT_APPLIED; any other 409 stays MAYBE_APPLIED, so the
* next send reuses the key.
*/
const NOT_APPLIED_CONFLICT_CODES: ReadonlySet<string> = new Set(["CONFLICT"]);
export const INVOICE_CREATE_EFFECT: CommandEffectDescriptor<InvoiceProblem> =
Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem({
status,
problem,
}: Readonly<{ status: number; problem: InvoiceProblem }>) {
if (status === 400 || status === 422) return "NOT_APPLIED";
if (
status === 409 &&
problem.code !== undefined &&
NOT_APPLIED_CONFLICT_CODES.has(problem.code)
) {
return "NOT_APPLIED";
}
return "MAYBE_APPLIED";
},
// The backend refuses an unauthenticated, forbidden or rate-limited
// create before it touches state. Delete this line if it does not.
classifyStatus: () => "NOT_APPLIED" as const,
});
import type {
FeatureHttpProblemMapping,
SafeResponseMetadata,
} from "../../../adapters/http/index.ts";
import type { InvoiceProblem } from "../contracts/invoice-problem-details.ts";
export function mapInvoiceCreateProblem(
problem: InvoiceProblem,
metadata: SafeResponseMetadata,
): FeatureHttpProblemMapping | undefined {
if (metadata.status === 409) {
return Object.freeze({
kind: "CONFLICT" as const,
code: problem.code ?? "INVOICE_CONFLICT",
});
}
// The executor checked the key before it sent, so this names a key rule
// the two sides disagree on: keep the code for diagnostics.
if (metadata.status === 400 && problem.code === "IDEMPOTENCY_KEY_INVALID") {
return Object.freeze({
kind: "UNKNOWN_CLIENT_FAILURE" as const,
code: problem.code,
});
}
if (metadata.status === 422) {
return Object.freeze({
kind: "VALIDATION_REJECTED" as const,
code: problem.code ?? "INVOICE_REJECTED",
validationIssues: problem.issues ?? [],
});
}
return undefined;
}
- 이 두 조각은
tests/unit/manual-code-blocks.test.ts가 시험한다. 저장소 사본에create:feature invoice-feature --with-create로 기능을 만들고, 조각을 위 경로에 그대로 넣어 타입 검사를 하고, 분류와 매핑이 위 설명대로인지 돌려 본다(tests/fixtures/manual-code-blocks/).
틀리면
- 쓰기 operation에
commandEffect가 없으면 계약 조립이command operations require a command effect descriptor로 거부한다. - 분류가 서버 계약과 다른 것은 검사가 잡지 못한다. 기능 테스트(같은 키 재전송, 409 처리 중)로 확인한다.
5. 인증
무엇을 고르나: operation이 어떤 인증 프로필로 나가는지.
- 인증 프로필: 요청에 어떤 자격 증명 헤더를 붙이고 쿠키를 보낼지 정한 이름이다.
ANONYMOUS |
EXTERNAL_BEARER |
제품 프로필 | |
|---|---|---|---|
| 언제 | 로그인 없이 부르는 API | 세션 토큰을 authorization 헤더로 보내는 API. 생성된 뼈대가 이것이다 |
위 둘로 안 되는 경우(쿠키 세션, 별도 토큰 등) |
| 정의 | src/contracts/rest-profiles.ts (템플릿 소유) |
같은 파일 | src/contracts/product-contracts.ts의 PRODUCT_REST_AUTH_PROFILES (제품 소유) |
| 자격 증명 | 없음 | 템플릿 세션 | src/bootstrap/product-composition.ts의 credentialProviders |
라우트 access |
보통 public |
보통 session-required |
프로필에 맞게 |
REFERENCE_EXTERNAL_BEARER는EXTERNAL_BEARER의 옛 이름이다.@deprecated이고 한 릴리스 뒤 지운다. 새 코드는 쓰지 않는다.- 제품 프로필 ID는 템플릿 프로필 ID와 겹치면 안 된다.
- 쿠키 인증과 CSRF 헤더는 인증 프로필의 헤더 집합으로 표현한다. 예제:
tests/unit/product-composition-fixture.test.ts. - 서버가 401을 주면 그 요청의 자격 증명을 낸 쪽만 안다.
ANONYMOUS요청의 401은 세션을 바꾸지 않는다. 템플릿 세션이 낸 자격 증명이면 세션이 로그아웃된다. 제품credentialProviders가 낸 자격 증명이면 세션은 그대로이고composeProduct가 돌려준onCredentialRejected가 불린다(선택).- provider가 템플릿 세션 자신의 자격 증명(BFF 쿠키 세션)을 보낸다면
onCredentialRejected에서context.notifySessionUnauthenticated()를 부른다. 그래야 그 401이 세션을 로그아웃시킨다. 쿠키 recipe는 이 handler를createSessionCookieRejectionHandler로 준다(04 문서 4.3).
- provider가 템플릿 세션 자신의 자격 증명(BFF 쿠키 세션)을 보낸다면
- 짝 백엔드에 붙일 때 세션 owner와 프로필은 04 문서가 모드별로 정한다. JWT 모드는
EXTERNAL_BEARER, Redis session 모드는SESSION_COOKIE_READ·SESSION_COOKIE_WRITE다.
기준: 백엔드가 그 API에 요구하는 인증을 따른다. 새 프로필은 템플릿 파일이 아니라 제품 소유 파일 두 곳에만 더한다.
어디에 적나: descriptor의 frontend.authProfileId, 라우트 access.
틀리면
- 없는 프로필이면 계약 조립이 거부해
check:registries와 그 기능의 실행부를 적재하는 테스트가 실패한다.check:types는 통과한다.Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>
- 제품 프로필 ID가 템플릿 것과 같으면
Product REST auth profile <id> reuses a template profile id.
6. 페이지 템플릿
무엇을 고르나: 페이지가 쓸 틀. 다섯 개라 표 대신 목록으로 쓴다.
CollectionPage: 목록. 도구 막대, 필터, 결과 수, 일괄 작업, 페이지 넘김 자리가 있다. 생성된 뼈대가 이것이다.DetailPage: 한 항목 보기. 요약(metadata)과 위험한 작업(destructiveAction) 자리가 있다.FormPage: 만들기·고치기. 오류 요약, 필드, 폼 버튼, 이탈 확인(guard) 자리가 있다.feedbackId={form.feedbackId}를 넘기면 저장이 필드 오류가 아닌 실패(결과 불명, 429 등)로 끝날 때 포커스가 실패 상태로 간다. 저장 버튼은 저장 중에disabled대신pending을 쓴다. 꺼진 버튼은 키보드 포커스를 잃는다.
StatusPage: 안내 화면. 로그인 필요, 권한 없음, 없음, 쓸 수 없음, 오프라인, 점검, 예상 못 한 오류(variant).StandardPage: 위 넷에 맞지 않는 페이지. 넷 모두 이것을 바탕으로 한다.
기준: 화면의 주된 일 하나로 고른다. 목록과 상세를 한 페이지에 섞지 않는다. 라우트를 나눈다.
정본: src/presentation/templates/page-templates.tsx. 기능은 src/presentation/design-system/index.ts를 거쳐 import한다.
틀리면
- 템플릿은 데이터를 가져오지 않는다. 데이터와 동작은 props로 받는다. 템플릿 파일이 application·어댑터를 import하면
check:architecture가page-templates-own-layout-only로 막는다. - 디자인 시스템 하위 경로를 import하면
design-system-is-reached-through-its-index로 막는다. - 템플릿을 잘못 고른 것은 검사가 잡지 못한다.
7. 파일 업로드
무엇을 고르나: 기능이 파일을 서버에 올리는 경로.
두 템플릿을 짝으로 쓰면 presigned 레시피는 맞지 않는다.
- 프론트
src/adapters/browser-transfer/의 resumable upload는PRESIGNED_MULTIPART_V1서버를 가정한다. 브라우저가 object store에 바로 PUT하는 방식이다. - 짝 백엔드는 2026-09-25에 그 서버 코드(presigned·direct multipart)를 지웠다. 파일은 자기 Fileserver가 직접 받는다(
clean-architecture-backend-template/docs/fileserver/http-contract.md). - 이 레시피를 짝 백엔드에 그대로 붙이면 첫 응답부터 읽지 못한다. 백엔드는 응답을 Envelope로 감싸고, 레시피의 control plane은 감싸지 않은 DTO를 기대한다.
- 짝으로 쓰는 경로는 Fileserver의 multipart 한 번 업로드(
POST /v1/files)다. 프론트 client는src/adapters/http/fileserver-upload.ts의createFileserverUploadClient다.
사용자가 파일을 고른다 (FilePickerPort → LocalFileRef)
→ FileContentPort.openSource(ref) → FileByteSource
→ 기능 어댑터: upload({ source, filename, mediaType, idempotencyKey, signal })
→ POST /v1/files (multipart, 파트 이름 file)
→ 201 READY 또는 202 VERIFYING·QUARANTINED + 저장된 파일 정보(fileId, sha256 …)
202 REJECTED는 저장된 파일이 아니다 → 실패 FILE_REJECTED
FileByteSource: 고른 파일의 바이트를 조각으로 읽는 값이다.File·Blob은 파일 어댑터 밖으로 나오지 않는다.- 파일 선택·읽기(
createBrowserFileRuntime,src/adapters/browser-files/index.ts)도file-transfer레시피라 제품이 조립한다(productionComposition: false).
| Fileserver 한 번 업로드 | presigned resumable 레시피 | |
|---|---|---|
| 짝 백엔드 | 맞는다 | 서버가 없다 |
| 코드 | src/adapters/http/fileserver-upload.ts |
src/adapters/browser-transfer/index.ts |
| 끊긴 뒤 | 처음부터 다시 보낸다 | part 단위로 이어 간다 |
| 메모리 | 파일 전체를 한 번 읽는다. maxFileBytes까지 |
part 크기 × 동시 수 |
| 바이트 경로 | 앱 서버를 지난다 | 브라우저 → object store |
기준
- 짝 백엔드를 그대로 쓰면 Fileserver 한 번 업로드를 쓴다.
- 큰 파일을 끊긴 데서 이어 올려야 하면 지금 템플릿에는 짝 경로가 없다. 짝 백엔드의 tus(
/v1/uploads)를 부르는 프론트 client는 아직 없다. - presigned 레시피는 제품 backend가 그 BFF 계약(
docs/architecture/server-file-capability-infrastructure.md)을 직접 만들 때만 쓴다.
결과 읽기: upload()는 Result<FileserverUploadedFile, AppFailure>를 돌려준다.
- 성공
state가READY(201)면 바로 내려받을 수 있다. 202는 아직 내려받을 수 없다. 짝 백엔드는 업로드 요청 안에서 검증을 끝내고,READY가 아닌 state는 모두 202로 답한다.VERIFYING: 검증기가 나중에 다시 보자고 했다. 서버가 다시 검사하면READY가 될 수 있다.QUARANTINED: 격리됐다. 이름·타입 불일치, 스크립트 같은 이유다. 관리자가 정하기 전까지 내려받을 수 없다. "검사 중"으로 보이면 화면이 끝나지 않는 대기가 된다.REJECTED: 검증기가 거절했다(악성 코드 말고 다른 이유). 저장된 파일이 아니므로 성공으로 돌려주지 않는다. 실패VALIDATION_REJECTED, codeFILE_REJECTED,NOT_APPLIED다. 사용자가 다른 파일을 골라야 한다.
- 빈 파일은 보내지 않는다. 짝 백엔드 기본 검증기가 빈 파일을 거절하기 때문이다.
VALIDATION_REJECTED, codeFILE_EMPTY,NOT_STARTED다. - 실패
effect:NOT_STARTED: 보내지 않았다. 입력, 크기, 자격 증명에서 거절했다.NOT_APPLIED: 서버가 거절했고 파일은 없다. Fileserver는 모호하지 않은 실패에서 업로드를 취소한다. 아래MAYBE_APPLIED경우를 뺀 4xx와, 5xx 중 작업 스레드가 게시 전에 내는 code 넷(PARTIAL_WRITE,ATOMIC_PUBLISH_UNSUPPORTED,STORAGE_UNAVAILABLE,STORAGE_FULL)이다.MAYBE_APPLIED: 올라갔을 수도 있다. 응답을 잃음, 시간 초과,details.ambiguous: true, 그 밖의 5xx다. 504TRANSFER_TIMEOUT도 여기 든다. 백엔드는 대기 시간이 지나면 작업이 어느 단계에 있든 이 code를 내고, 작업은 그 뒤에 끝나READY가 될 수 있다. 다시 보낼 때는 같은idempotencyKey를 쓴다.- 멱등성 응답(
IDEMPOTENT_*,IDEMPOTENCY_*)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(backend-envelope.ts, 4절)로 판정한다. 400IDEMPOTENCY_KEY_INVALID·422IDEMPOTENT_REQUEST_MISMATCH는NOT_APPLIED, 409IDEMPOTENT_IN_FLIGHT·503IDEMPOTENCY_UNAVAILABLE·503IDEMPOTENCY_COMPLETION_UNKNOWN·500IDEMPOTENCY_RECOVERY_REQUIRED는MAYBE_APPLIED다. APPLIED_CONFIRMED: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다.
code는 백엔드 code 그대로다(FILE_TOO_LARGE,UNSUPPORTED_MEDIA_TYPE,MALWARE_DETECTED…). 백엔드가 code를 주지 않는 거절은 client가 이름을 붙인다(FILE_REJECTED,FILE_EMPTY,FILE_NOT_READABLE). 화면 문구는 기능이 code로 고른다.- 실패 Envelope의
meta.traceId는 실패의traceId로 온다. V3 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. 202REJECTED의FILE_REJECTED도 성공 Envelope의meta.traceId를 싣는다. 이 응답에는 거절 이유가 없다. 짝 백엔드는 검증기 code를 파일 레코드에만 적는다. 그래서 화면은 이유별 문구를 고를 수 없다. - client는 스스로 다시 보내지 않는다.
retryable: true이고retryAfterMs가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(maxRetryAfterMs, 기본 30초)보다 길게 기다리라고 하면retryable: false다. MAYBE_APPLIED는 언제나retryable: false다. 백엔드가 Envelope에retryable: true와Retry-After를 붙여도(504TRANSFER_TIMEOUT) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다.
주의 — 멱등 키: 짝 백엔드(45d2a478)의 POST /v1/files는 멱등 키를 읽지 않는다(업로드 use case가 NOT_IDEMPOTENT).
- 그래서
MAYBE_APPLIED뒤 다시 보내면 같은 파일이 두 개 생길 수 있다. - 같은 키 재전송이 중복을 막는 것은 배포가 업로드를 백엔드 멱등성 executor 뒤에 둘 때뿐이다.
- 그 전에는 다시 보내기 전에 업무 데이터(파일 목록 등)로 먼저 확인한다.
어디에 적나: 두 곳이다.
src/bootstrap/product-composition.ts: client를 만들 재료(주소, 인증 프로필, 자격 증명, 크기 상한)를 capability로 넘긴다. client 코드는 넘기지 않는다. 기능 adapter는 기능 runtime과 함께 늦게 적재되므로, 업로드 코드가 boot 번들이 아니라 기능 chunk에 든다.- 기능
adapters/create-<base>-feature-input.ts:needs에 그 capability를 적고, 거기서createFileserverUploadClient를 부른다.
// src/bootstrap/product-composition.ts (제품 소유). BACKEND_SESSION은
// src/contracts/product-contracts.ts에 더한 쿠키 세션 프로필이다.
import type { FileserverUploadClientDependencies } from "../adapters/http/index.ts";
import { PRODUCT_REST_AUTH_PROFILES } from "../contracts/product-contracts.ts";
// 파일에 이미 있는 import에 ProductCredentialProvider를 더한다.
import type { ProductCredentialProvider } from "./product-composition-contract.ts";
declare module "../features/feature-adapter-contribution.ts" {
interface FeaturePlatformCapabilities {
readonly fileserverUpload: FileserverUploadClientDependencies;
}
}
export function composeProduct(context: ProductCompositionContext) {
const sessionCredentials: ProductCredentialProvider = () => {
if (!context.isScopeReady()) return { kind: "SCOPE_FENCED" };
const csrf = context.readCookie("XSRF-TOKEN");
return csrf === undefined
? { kind: "UNAUTHENTICATED" }
: { kind: "READY", headers: { "x-xsrf-token": csrf } };
};
return {
capabilities: {
fileserverUpload: {
baseUrl: context.config.API_BASE_URL,
authProfile: PRODUCT_REST_AUTH_PROFILES.BACKEND_SESSION,
attachCredentials: sessionCredentials,
maxFileBytes: 20 * 1024 * 1024,
...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }),
},
},
credentialProviders: { BACKEND_SESSION: sessionCredentials },
// BACKEND_SESSION은 세션 쿠키 그 자체다. 그 401은 세션을 로그아웃시킨다(5절).
onCredentialRejected: () => context.notifySessionUnauthenticated(),
} satisfies ProductComposition;
}
// src/features/<id>/adapters/create-<base>-feature-input.ts
import { createFileserverUploadClient } from "../../../adapters/http/index.ts";
import { defineFeatureAdapterContribution } from "../../feature-adapter-contribution.ts";
export const createAttachmentFeatureInput = defineFeatureAdapterContribution({
featureId: "attachment",
needs: ["http", "fileserverUpload"],
createInput: ({ http, fileserverUpload }) => {
const uploads = createFileserverUploadClient(fileserverUpload);
return {
featureId: "attachment",
// 기능 port 구현이 uploads.upload({ source, filename, mediaType, idempotencyKey, signal })를 부른다.
input: { /* … */ },
};
},
});
baseUrl은 끝이/여야 한다.v1/files를 그 아래에 붙인다. 경로가 base 밖으로 나가면 조립할 때TypeError다.- 자격 증명 함수는 V3 실행기의
attachCredentials와 계약이 같다. 같은 프로필의credentialProviders를 그대로 쓴다. 프로필이 허락하지 않은 헤더를 주면 보내지 않고AUTH_INTEGRATION_FAILURE다.
틀리면
- 프로필의 필수 헤더가 없으면
fetch를 부르지 않고MISSING_REQUIRED_CREDENTIAL_HEADER로 끝난다. - 파일이
maxFileBytes보다 크면 읽기 전에FILE_TOO_LARGE(NOT_STARTED)다. 비어 있으면FILE_EMPTY(NOT_STARTED)다. - 202 응답을 모두 "검사 중"으로 보이면
QUARANTINED파일의 화면이 끝나지 않는다. state마다 따로 보인다. - 멱등성·web 공통 응답의 판정은 V3 표를 그대로 쓴다.
tests/integration/fileserver-upload.test.ts가 pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의 행마다 client와 V3 표가 같은지 본다. pin을 옮기면 같이 다시 돈다. - 백엔드가 Fileserver 응답 모양이나 Fileserver 자신의 code를 바꾸면 검사가 잡지 못한다. 그 표(
fileserver-upload.ts의NOT_APPLIED_5XX_CODES)는 백엔드45d2a478(pin) 코드를 읽은 것이다. 백엔드 SHA가 바뀌면FileserverErrorCode,BlockingTransferExecutor, 게시 경로를 같이 다시 본다. 4xx를NOT_APPLIED로 보는 이유는 계약 문서 6.1절에 있다. - 테스트 예:
tests/integration/fileserver-upload.test.ts(백엔드 코드가 답하는 대로 답하는 MSW. 백엔드 문서는 202VERIFYING만 적는다).