문제
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
411 lines
35 KiB
Markdown
411 lines
35 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: 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를 그대로 두었는지로 정해진다.
|
|
|
|
```text
|
|
백엔드 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. 결과 불명
|
|
|
|
**무엇을 고르나**: 쓰기가 실패 응답을 받았을 때 "적용 안 됨"으로 볼지, "적용됐을 수도 있음"으로 볼지.
|
|
|
|
- 결과 불명: 서버가 요청을 적용했는지 모르는 상태다. 응답을 잃었거나, 서버가 "처리 중"이라고 답한 경우다.
|
|
|
|
```text
|
|
쓰기 요청
|
|
→ 실패 응답 (또는 응답 없음)
|
|
→ 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`). 표의 근거는 [계약 문서](../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`, 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 두 번째 표). 적용은 안 됐지만 다음 전송은 같은 키다. 위 표의 두 칸 어디에도 딱 맞지 않는다.
|
|
|
|
지금 프론트 동작:
|
|
|
|
```text
|
|
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 문서](04-paired-backend-session.md) 4.3).
|
|
- 짝 백엔드에 붙일 때 세션 owner와 프로필은 [04 문서](04-paired-backend-session.md)가 모드별로 정한다. 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`다.
|
|
|
|
```text
|
|
사용자가 파일을 고른다 (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`를 부른다.
|
|
|
|
```ts
|
|
// 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;
|
|
}
|
|
```
|
|
|
|
```ts
|
|
// 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`로 보는 이유는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절에 있다.
|
|
- 테스트 예: `tests/integration/fileserver-upload.test.ts`(백엔드 코드가 답하는 대로 답하는 MSW. 백엔드 문서는 202 `VERIFYING`만 적는다).
|