문제 GET에 `retrySemantics: "KEYED"`(commandRecovery 없음)나 `"NEVER"`를 적어도 계약 조립이 통과하고 FE-REG-API 행에 그 값이 남는다. KEYED 복구 descriptor 검사가 쓰기 분기 안에만 있기 때문이다. 실행기는 이 GET을 쓰기로 보지 않아 재시도 없는 읽기로 돌린다. 매뉴얼은 "읽기(GET)는 늘 SAFE"라 적는다. V2 `defineRestOperation`은 조회에 SAFE·IDEMPOTENT만 허용했는데 V2 삭제 때 이 규칙이 V3로 옮겨지지 않았다(실험 R1). 고른 방법 assertHttpContract의 읽기 분기에서 GET·HEAD의 retrySemantics가 SAFE나 IDEMPOTENT가 아니면 method와 값을 담아 거절한다. realtime snapshot 바인딩이 요구하는 짝(GET + SAFE·IDEMPOTENT)과 같은 어휘다. 매뉴얼 02 3절 "틀리면"에 거절 문구를 더했다. 버린 대안 - 레지스트리 governance의 allowedValues로 막기: method별 허용값을 표현할 칸이 없고, 조립(부팅 경로)이 아니라 check:registries에서만 걸린다. 위험·한계 - GET·HEAD를 KEYED나 NEVER로 적은 다운스트림 descriptor는 부팅에서 계약 조립 실패가 된다. 템플릿 안에는 그런 descriptor가 없다(grep). - 쓰기의 SAFE 금지(03-03)는 이 커밋 범위가 아니다. 검증 - RED: tests/unit/external-contract-runtime.test.ts의 GET·HEAD × KEYED·NEVER 4건이 실패(조립 통과)했다. - GREEN: `run-vitest related src/contracts/external-contract-runtime.ts` 105파일 950건 통과. check:types, eslint, check:registries, verify:documentation 통과. BREAKING CHANGE: GET·HEAD operation의 retrySemantics가 KEYED나 NEVER이면 계약 조립이 CONTRACT_CONTRIBUTION_INVALID로 실패한다. SAFE(재시도 허용)나 IDEMPOTENT로 바꾼다. 재시도를 막으려면 frontend.retryBudget을 0으로 둔다. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
228 lines
14 KiB
Markdown
228 lines
14 KiB
Markdown
# 02. 결정표
|
|
|
|
기능을 만들며 고르는 여섯 가지다. 각 절은 같은 순서로 쓴다.
|
|
|
|
```text
|
|
무엇을 고르나 → 선택지 비교 → 고르는 기준 → 어디에 적나 → 틀리면 무엇이 잡나
|
|
```
|
|
|
|
판단 원칙은 design-docs repo의 `conventions/feature-design-principles.md`에 있다. 여기서는 번호로만 가리킨다.
|
|
|
|
---
|
|
|
|
## 1. context 경계
|
|
|
|
**무엇을 고르나**: 새 기능을 기존 context에 넣을지, 새 context를 만들지.
|
|
|
|
context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기능들은 함께 지연 로드된다.
|
|
|
|
```text
|
|
사용자가 /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 문서 "자리표시자 교체"](03-outside-feature-folder.md#자리표시자-계약-신원-교체).
|
|
|
|
**틀리면**
|
|
|
|
- 신원 형식이 틀리면(정확한 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`. 다른 파일에 다시 적지 않는다.
|
|
|
|
**틀리면**
|
|
|
|
- 읽기(GET·HEAD)에 `KEYED`나 `NEVER`를 적으면 계약 조립이 `<method> is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값>`으로 거부한다.
|
|
- `NEVER`에 `retryBudget`을 0보다 크게 주면 계약 조립이 `retry budget contradicts NEVER retry semantics`로 거부한다.
|
|
- `KEYED`에 `commandRecovery`가 없으면 `KEYED commands require a recovery descriptor`로 거부한다.
|
|
- 서버 보장과 다른 의미를 고른 것은 검사가 잡지 못한다.
|
|
|
|
근거: `scale-architecture.md` §13(재시도 모델).
|
|
|
|
---
|
|
|
|
## 4. 결과 불명
|
|
|
|
**무엇을 고르나**: 쓰기가 실패 응답을 받았을 때 "적용 안 됨"으로 볼지, "적용됐을 수도 있음"으로 볼지.
|
|
|
|
- 결과 불명: 서버가 요청을 적용했는지 모르는 상태다. 응답을 잃었거나, 서버가 "처리 중"이라고 답한 경우다.
|
|
|
|
```text
|
|
쓰기 요청
|
|
→ 실패 응답 (또는 응답 없음)
|
|
→ 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`).
|
|
- `responseEnvelope: "ENVELOPE_V1"`인 operation은 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 판정을 실행기가 백엔드 기준 표로 정한다(`src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`). 표의 근거는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과). `classifyProblem`은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다.
|
|
- `NOT_APPLIED`(쓰기 전 거절): 400 `VALIDATION_FAILED`(details 모양과 상관없음), 400 `IDEMPOTENCY_KEY_INVALID`, 422 `IDEMPOTENT_REQUEST_MISMATCH`
|
|
- `MAYBE_APPLIED`: 그 밖의 400·409·422. 409 `IDEMPOTENT_IN_FLIGHT`, `BAD_PARAMETER`, 도메인 code, fileserver의 422가 여기 든다. 그리고 503 `IDEMPOTENCY_UNAVAILABLE`
|
|
- 짝 백엔드가 쓰기 전에 거절하는 code를 새로 만들면 계약 문서 6.1절과 이 표를 함께 고친다. 표에 없으면 `MAYBE_APPLIED`다
|
|
|
|
**503 `IDEMPOTENCY_UNAVAILABLE`는 `NOT_APPLIED`로 분류하지 않는다.**
|
|
|
|
백엔드는 이 응답을 "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로 정한다(`http-contract.md` §2 두 번째 표). 적용은 안 됐지만 다음 전송은 같은 키다. 위 표의 두 칸 어디에도 딱 맞지 않는다.
|
|
|
|
지금 프론트 동작:
|
|
|
|
```text
|
|
503 IDEMPOTENCY_UNAVAILABLE
|
|
→ V3 실행기
|
|
├─ responseEnvelope: "ENVELOPE_V1" (생성한 기능) → 실행기가 MAYBE_APPLIED로 정한다
|
|
└─ 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`). 예제: `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`로 막는다.
|
|
- 템플릿을 잘못 고른 것은 검사가 잡지 못한다.
|