문제 resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만 본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의 결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고, 서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험 X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가 NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의 기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도 이 버튼을 숨기는 장치가 없다. 고른 방법 - application-query.ts canResend: head가 UNKNOWN이고 intent에 idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는 거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다. - AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고, 훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면 onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존 페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다. - KEYED는 지금처럼 같은 키로 재전송한다. 버린 대안 - 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존 배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다). - AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다. 위험·한계 - 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다. "적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정). - 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은 결과 불명 동안 제출을 막는다. - hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다. 검증 - RED: application-mutation-admission 2건(NEVER: canResend false·resend null· execute 1회, KEYED: canResend true), async-surface 2건 실패. - GREEN: tests/unit·integration·component·features·contract 250파일 3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출. - check:types, lint, check:architecture, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03 Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1
17 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: 0 |
— | retryBudget: 0 필수 |
| 뮤테이션 정책 | requiresIdempotencyKey: true |
— | — |
- 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다.
- 결과를 모를 때 새 키로 다시 보내면 안 된다. 서버는 새 키를 다른 요청으로 보고 막지 못한다.
기준: 원칙 3. 서버 계약에 적힌 보장으로 고른다. 모르면 NEVER로 두고 백엔드에 묻는다.
정본: 백엔드가 멱등 키 요청에 어떻게 답하는지는 clean-architecture-backend-template/docs/web/http-contract.md §2(멱등성 응답)다. 여기에 표를 옮기지 않는다.
어디에 적나: contracts/<base>-contract-contribution.ts의 retrySemantics, commandRecovery, frontend.retryBudget. 다른 파일에 다시 적지 않는다.
틀리면
- 쓰기(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_MISMATCHMAYBE_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 ...). - 거절 이유를 필드 옆에 보이려면
mapProblem이 그 code를VALIDATION_REJECTED와 필드 목록으로 돌려준다. 선언 없이mapProblem만 두면 필드 오류는 보이지만 저장 버튼은 꺼진 채다.
- 그 엔드포인트가 쓰기 전에만 내는 code라면
503 IDEMPOTENCY_UNAVAILABLE는 NOT_APPLIED로 분류하지 않는다.
백엔드는 이 응답을 "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로 정한다(http-contract.md §2 두 번째 표). 적용은 안 됐지만 다음 전송은 같은 키다. 위 표의 두 칸 어디에도 딱 맞지 않는다.
지금 프론트 동작:
503 IDEMPOTENCY_UNAVAILABLE
→ V3 실행기
├─ responseEnvelope: "ENVELOPE_V1" (생성한 기능) → 실행기가 MAYBE_APPLIED로 정한다
│ KEYED이고 retryBudget > 0이면 먼저 같은 키로 다시 보낸다(3절). 예산을 다 쓰면 결과 불명
└─ Envelope 없음 (참조 기능) → 기능의 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). 예제: src/features/reference-feature/contracts/reference-feature-contract-contribution.ts의 CREATE_EFFECT.
틀리면
- 쓰기 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.
기준: 백엔드가 그 API에 요구하는 인증을 따른다. 새 프로필은 템플릿 파일이 아니라 제품 소유 파일 두 곳에만 더한다.
어디에 적나: descriptor의 frontend.authProfileId, 라우트 access.
틀리면
- 없는 프로필이거나
auth와 조합이 틀리면 operation을 적재하는 모든 게이트가 실패한다.REST security profiles are incoherent for <operationId>: unknown authProfileId <id>.REST security profiles are incoherent for <operationId>: auth "external-session" cannot use the ANONYMOUS profile <id>.
- 제품 프로필 ID가 템플릿 것과 같으면
Product REST auth profile <id> reuses a template profile id.
6. 페이지 템플릿
무엇을 고르나: 페이지가 쓸 틀. 다섯 개라 표 대신 목록으로 쓴다.
CollectionPage: 목록. 도구 막대, 필터, 결과 수, 일괄 작업, 페이지 넘김 자리가 있다. 생성된 뼈대가 이것이다.DetailPage: 한 항목 보기. 요약(metadata)과 위험한 작업(destructiveAction) 자리가 있다.FormPage: 만들기·고치기. 오류 요약, 필드, 폼 버튼, 이탈 확인(guard) 자리가 있다.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로 막는다. - 템플릿을 잘못 고른 것은 검사가 잡지 못한다.