Files
clean-architecture-frontend…/docs/manual/02-decision-tables.md
T
DongHyeonka 5c2f8b875c docs(manual): 매뉴얼만으로 기능을 추가한 실험의 막힘 5건을 메운다 (1101/16-01)
문제: docs/manual(7c7ef32)만 보고 notice-feature(목록·상세·작성, GET 2 +
KEYED POST 1)를 만든 실험(b58d131, 합치지 않음)에서 매뉴얼이 답하지 않아
코드를 읽어야 했던 곳이 나왔다.

| 막힘 | 절 | 매뉴얼에 없던 것 |
|---|---|---|
| 1 | 01-3단계 | 백엔드 Envelope와 뼈대 problem details 중 무엇을 따르나 |
| 2 | 01-3단계 | V2 입력 칸(requestSource, pathSchema, pathParameterNames, maxEncodedSearchBytes, boundary) |
| 3 | 01-5단계 | routeId가 무엇에 쓰이고 쓰기에는 어느 route를 적나 |
| 4 | 01-6단계 | 상세 경로를 items/ 아래 두는 이유, a11y spec 치환 고치는 법 |
| 5 | 01-10단계 | 같은 멱등 키 재전송과 요청 본문을 테스트에서 보는 법 |
| 덧 | 02-4절, 01-2단계, patterns | 503 IDEMPOTENCY_UNAVAILABLE 판정, 길이 제한 위치, 검색 폼 예 |

고친 절과 근거(코드 위치):
- 01-3단계 "응답 모양": 뼈대·MSW·V3 실행기는 DTO와 problem details를 쓴다.
  V3는 본문을 벗기지 않고 검증한다(src/adapters/http/http-execution-v3.ts:1410,
  1633-1647; src/adapters/http/index.ts:41-48; backend-api-and-server-state-
  contract.md:161-173). MSW는 {data} 감싼 응답을 실패 시나리오로 둔다
  (tests/mocks/handlers/http-scenarios.ts:80-81, 143-150). 뼈대 problem 스키마는
  최상위 code다(scripts/create-feature.ts:542-550). 짝 백엔드는 모든 JSON을
  Envelope로 보낸다(backend docs/web/http-contract.md:16-33).
- 01-3단계 "V2 행의 입력 칸": 칸 표와 공지 예 두 행. 근거
  src/contracts/api-operations.ts:9,25-27,112-125,142-190,
  src/contracts/schema-registry.ts:6-11, config/contracts/registry-governance.json:220
  (boundary는 허용값만 검사), tests/unit/http-operation-v2-v3-parity.test.ts:39-49,91,
  src/adapters/http/request-builder.ts:129-135(V2만 읽음),
  src/contracts/external-contract-runtime.ts:33,
  src/adapters/http/http-contract-bridge.ts:225-231(V3 고정 상한 8,192).
- 01-5단계 routeId: 실행기에 넘겨 관측 기록의 route_id로만 쓴다
  (src/adapters/http/feature-http-binding.ts:272-273,
  src/adapters/http/http-execution-v3.ts:248-254,653-655,
  src/bootstrap/runtime-adapters.ts:249-293). 기준은 "요청을 보내는 화면".
  참조 기능 생성은 LIST를 적었다(reference-http-gateway.ts:32-34).
- 01-6단계: items/ 이유(reference-feature-contract.ts:36-37, React Router
  정적 우선), a11y spec 치환 줄(tests/e2e/accessibility.spec.ts:26-29,36-43),
  파라미터 해석 실패 시 잘못된 경로 화면(src/presentation/routes/app-router.tsx:371).
  드릴 잔여물 검사는 기능 ID·폴더 이름만 찾는다(scripts/test-sample-removal.ts:
  114-117,383-392). URL 함수가 codec을 넘겨야 한다는 줄도 더했다
  (src/presentation/routes/route-codecs.ts:36,69-87; 생성 판
  scripts/create-feature.ts:934-938은 넘기지 않음).
- 03 "기능을 지울 때"·C절, 01-11단계: a11y spec 치환 줄을 손으로 지운다.
- 01-10단계, patterns "테스트": msw request:start로 요청을 모으는 예
  (실험 tests/features/notice-feature/notice-pages.test.tsx, msw 2.15
  node_modules/msw/lib/core/experimental/frames/http-frame.d.ts:58,
  생성 판 setupServer scripts/create-feature.ts:1147-1149).
- 02-4절 503: V3는 problem 스키마 실패면 쓰기를 MAYBE_APPLIED로 두고
  (http-execution-v3.ts:1633-1647), 통과하면 기능 classifyProblem이 정한다
  (src/adapters/http/http-effect-certainty.ts:99-131; 참조 기능
  reference-feature-contract-contribution.ts:49-70은 503을 MAYBE_APPLIED).
  V2 IDEMPOTENCY_REFUSALS에 503이 없어 effect가 비고
  (src/adapters/http/client.ts:1035-1038,1109-1135) 조정자가 MAYBE_APPLIED로
  본다(src/presentation/adapters/query/application-query.ts:824-834). 재전송은
  같은 키, 새 저장은 새 키(같은 파일 583-589, 636-669). 판정: 백엔드 행동
  (http-contract.md:94 "같은 키로 나중에 다시")과 맞는다. 화면 문구만 다르다.
- 01-2단계: 길이 제한은 경계 검증. 참조 기능도 스키마·폼에만 둔다
  (reference-schemas.ts:66, reference-resource-form.ts:9).
- patterns "URL 검색값을 바꾸는 폼": 짧은 예(SearchField, CollectionPage
  toolbar, buildRouteUrl search).
- errors.md: V2 입력 칸 실패 메시지 3개와 Unregistered route codec.

남긴 것:
- 응답 모양 제한: 지금 생성한 기능은 짝 백엔드의 Envelope 응답을 읽지
  못한다. 매뉴얼에는 제한과 선택지 둘(백엔드가 DTO를 보냄 / 프론트 V3가
  Envelope를 벗김)만 적었다. 결정은 없다. CHANGELOG·리뷰 기록은 이 커밋
  범위 밖이다.
- 경로 파라미터와 본문을 함께 받는 operation(PUT 등)의 V2/V3 일치 규칙이
  없다는 사실만 적었다.
- 예시 코드는 실험 브랜치의 notice 기능에서 옮겼다. 이 저장소에서 다시
  돌려 보지 않았다(실험 커밋 기록상 기능 테스트 21개 통과).

검증:
- node scripts/generate-product-feature-index.ts &&
  node scripts/verify-documentation-readiness.ts: PASS_SCOPED,
  documentReferences의 docs/manual 8개 파일 missing 0
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
  tests/unit/documentation-readiness.test.ts: 2 파일 16개 통과
- 새로 적은 실패 메시지·식별자: src·scripts·tests에서 모두 찾음.
  request:start는 msw 타입에서 확인
2026-11-03 08:01:49 +09:00

14 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.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절)으로 넘긴다 된다 하지 않는다
V3 commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField } 필수. 참조 기능은 retryBudget: 0 — retryBudget: 0 필수
V2 replayPolicy KEYED_COMMAND IDEMPOTENT NON_REPLAYABLE
뮤테이션 정책 requiresIdempotencyKey: true — —
  • 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다.
  • 결과를 모를 때 새 키로 다시 보내면 안 된다. 서버는 새 키를 다른 요청으로 보고 막지 못한다.

기준: 원칙 3. 서버 계약에 적힌 보장으로 고른다. 모르면 NEVER로 두고 백엔드에 묻는다.

정본: 백엔드가 멱등 키 요청에 어떻게 답하는지는 clean-architecture-backend-template/docs/web/http-contract.md §2(멱등성 응답)다. 여기에 표를 옮기지 않는다.

어디에 적나: contracts/<base>-contract-contribution.ts의 retrySemantics, commandRecovery, frontend.retryBudget. 같은 의미를 contracts/<base>-api-contract.ts의 replayPolicy, idempotency, idempotencyKeyPolicy에도 적는다.

틀리면

  • NEVER에 retryBudget을 0보다 크게 주면 계약 조립이 retry budget contradicts NEVER retry semantics로 거부한다.
  • KEYED에 commandRecovery가 없으면 KEYED commands require a recovery descriptor로 거부한다.
  • V2와 V3의 재시도 의미가 다르면 tests/unit/http-operation-v2-v3-parity.test.ts가 실패한다.
  • 서버 보장과 다른 의미를 고른 것은 검사가 잡지 못한다.

근거: scale-architecture.md §13(재시도 모델).


4. 결과 불명

무엇을 고르나: 쓰기가 실패 응답을 받았을 때 "적용 안 됨"으로 볼지, "적용됐을 수도 있음"으로 볼지.

  • 결과 불명: 서버가 요청을 적용했는지 모르는 상태다. 응답을 잃었거나, 서버가 "처리 중"이라고 답한 경우다.
쓰기 요청
  → 실패 응답 (또는 응답 없음)
  → commandEffect.classifyProblem({ status, problem })
      ├─ NOT_APPLIED   → 폼 오류·실패로 보여 준다. 다음 저장은 새 키를 쓴다
      └─ MAYBE_APPLIED → 결과 불명 화면
                          ├─ 확인 (onReconcileUnknownEffect)
                          └─ 같은 키로 다시 보내기 (onResendUnknownEffect)
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).

503 IDEMPOTENCY_UNAVAILABLE는 NOT_APPLIED로 분류하지 않는다.

백엔드는 이 응답을 "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로 정한다(http-contract.md §2 두 번째 표). 적용은 안 됐지만 다음 전송은 같은 키다. 위 표의 두 칸 어디에도 딱 맞지 않는다.

지금 프론트 동작:

503 IDEMPOTENCY_UNAVAILABLE
  → V3 실행기: 본문을 기능의 problem 스키마로 검증
      ├─ 통과 (problem details 모양) → 기능의 classifyProblem이 정한다
      │     참조 기능: 400·422와 정해 둔 409 code만 NOT_APPLIED → 503은 MAYBE_APPLIED
      └─ 실패 (짝 백엔드의 Envelope 모양) → 쓰기는 MAYBE_APPLIED
  → 결과 불명 화면 → "같은 요청으로 다시 보내기"가 같은 키로 보낸다
  • V2 클라이언트(레거시)도 같다. src/adapters/http/client.ts의 IDEMPOTENCY_REFUSALS에는 422 IDEMPOTENT_REQUEST_MISMATCH와 400 IDEMPOTENCY_KEY_INVALID만 있다. 503은 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). 예제: 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
V2 auth none external-session 프로필에 맞게
라우트 access 보통 public 보통 session-required 프로필에 맞게
  • REFERENCE_EXTERNAL_BEARER는 EXTERNAL_BEARER의 옛 이름이다. @deprecated이고 한 릴리스 뒤 지운다. 새 코드는 쓰지 않는다.
  • 제품 프로필 ID는 템플릿 프로필 ID와 겹치면 안 된다.
  • CSRF 프로필은 템플릿 상수(REST_CSRF_PROFILES)뿐이다. 제품이 더할 자리는 없다. 쿠키 인증은 인증 프로필의 헤더 집합으로 표현한다. 예제: tests/unit/product-composition-fixture.test.ts.

기준: 백엔드가 그 API에 요구하는 인증을 따른다. 새 프로필은 템플릿 파일이 아니라 제품 소유 파일 두 곳에만 더한다.

어디에 적나: V3 frontend.authProfileId와 V2 authProfileId(같은 값), V2 auth, 라우트 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로 막는다.
  • 템플릿을 잘못 고른 것은 검사가 잡지 못한다.