Files
clean-architecture-frontend…/docs/manual/02-decision-tables.md
T
DongHyeonka 1dda18da30 fix(docs): 참조 기능 경로를 다시 백틱으로 적어 문서 검사가 본다
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.

고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
  README, starter-experience, static-delivery, compatibility,
  backend-api-and-server-state-contract, manual-checklist,
  adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
  참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
  적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
  1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
  지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
  measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
  안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
  위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
  and scripts only where verify:documentation checks them"을 더했다. 검사기가
  읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
  기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
  같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
  커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
  검사기와 같은 규칙을 두 곳에 두게 된다.

위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
  백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
  아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/template-feature-removal-documents.test.ts
  tests/unit/documentation-readiness.test.ts, corepack pnpm
  verify:documentation, corepack pnpm test:sample-removal

Refs: 1105/14-03
2026-11-06 02:59:02 +09:00

35 KiB
Raw Blame History

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.0
  • PLACEHOLDER_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(아래 표), 참조 기능은 0 — retryBudget: 0 필수
뮤테이션 정책 ...commandMutationIdentity(<OPERATION>_CONTRACT)가 requiresIdempotencyKey: true를 준다 같은 함수가 false를 준다 같은 함수가 false를 준다
  • 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다.
  • 결과를 모를 때 새 키로 다시 보내면 안 된다. 서버는 새 키를 다른 요청으로 보고 막지 못한다.

기준: 원칙 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(쓰기 전 거절): 400 VALIDATION_FAILED(details 모양과 상관없음), 400 IDEMPOTENCY_KEY_INVALID, 422 IDEMPOTENT_REQUEST_MISMATCH, 503 RATE_LIMIT_UNAVAILABLE·RATE_LIMIT_INCOMPATIBLE(rate-limit 저장소 장애·제공자 불일치. 컨트롤러 전에 거절한다)
    • MAYBE_APPLIED: 그 밖의 400·409·422. 409 IDEMPOTENT_IN_FLIGHT, BAD_PARAMETER, 도메인 code, fileserver의 422가 여기 든다. 그리고 status와 code가 함께 맞는 5xx 넷: 503 IDEMPOTENCY_UNAVAILABLE, 503 IDEMPOTENCY_COMPLETION_UNKNOWN(실행 뒤 결과 기록 실패, 새 키 금지), 500 IDEMPOTENCY_RECOVERY_REQUIRED(이전 시도 효과를 증명 못 함), 503 REQUEST_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)도 적을 수 없다. 폼을 막는 400 BAD_PARAMETER나 409 DB_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와 상관없이 결과 불명으로 남는다.

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.
  • 서버가 401을 주면 그 요청의 자격 증명을 낸 쪽만 안다. ANONYMOUS 요청의 401은 세션을 바꾸지 않는다. 템플릿 세션이 낸 자격 증명이면 세션이 로그아웃된다. 제품 credentialProviders가 낸 자격 증명이면 세션은 그대로이고 composeProduct가 돌려준 onCredentialRejected가 불린다(선택).
    • provider가 템플릿 세션 자신의 자격 증명(BFF 쿠키 세션)을 보낸다면 onCredentialRejected에서 context.notifySessionUnauthenticated()를 부른다. 그래야 그 401이 세션을 로그아웃시킨다. 쿠키 recipe는 이 handler를 createSessionCookieRejectionHandler로 준다(04 문서 4.3).
  • 짝 백엔드에 붙일 때 세션 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, code FILE_REJECTED, NOT_APPLIED다. 사용자가 다른 파일을 골라야 한다.
  • 빈 파일은 보내지 않는다. 짝 백엔드 기본 검증기가 빈 파일을 거절하기 때문이다. VALIDATION_REJECTED, code FILE_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다. 504 TRANSFER_TIMEOUT도 여기 든다. 백엔드는 대기 시간이 지나면 작업이 어느 단계에 있든 이 code를 내고, 작업은 그 뒤에 끝나 READY가 될 수 있다. 다시 보낼 때는 같은 idempotencyKey를 쓴다.
    • 멱등성 응답(IDEMPOTENT_*, IDEMPOTENCY_*)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(backend-envelope.ts, 4절)로 판정한다. 400 IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE·503 IDEMPOTENCY_COMPLETION_UNKNOWN·500 IDEMPOTENCY_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 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다.
  • client는 스스로 다시 보내지 않는다. retryable: true이고 retryAfterMs가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(maxRetryAfterMs, 기본 30초)보다 길게 기다리라고 하면 retryable: false다.
  • MAYBE_APPLIED는 언제나 retryable: false다. 백엔드가 Envelope에 retryable: true와 Retry-After를 붙여도(504 TRANSFER_TIMEOUT) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다.

주의 — 멱등 키: 짝 백엔드(45d2a478)의 POST /v1/files는 멱등 키를 읽지 않는다(업로드 use case가 NOT_IDEMPOTENT).

  • 그래서 MAYBE_APPLIED 뒤 다시 보내면 같은 파일이 두 개 생길 수 있다.
  • 같은 키 재전송이 중복을 막는 것은 배포가 업로드를 백엔드 멱등성 executor 뒤에 둘 때뿐이다.
  • 그 전에는 다시 보내기 전에 업무 데이터(파일 목록 등)로 먼저 확인한다.

어디에 적나: 두 곳이다.

  1. src/bootstrap/product-composition.ts: client를 만들 재료(주소, 인증 프로필, 자격 증명, 크기 상한)를 capability로 넘긴다. client 코드는 넘기지 않는다. 기능 adapter는 기능 runtime과 함께 늦게 적재되므로, 업로드 코드가 boot 번들이 아니라 기능 chunk에 든다.
  2. 기능 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. 백엔드 문서는 202 VERIFYING만 적는다).