문제: 앞 커밋이 기록·설계서·결정 기록을 옮겨서, 그 문서를 가리키는 상대 링크 182개와 살아 있는 문서·코드 주석의 경로 23곳이 없는 곳을 가리킨다. 고른 방법: 기계적으로 바꾼다. - 상대 링크: 모든 .md(기록 포함)에서 옮기기 전 트리로 대상을 풀고, 대상이나 문서 자신이 옮겨졌으면 새 위치 기준 상대 경로로 다시 쓴다. 옮기기 전에도 없던 대상은 건드리지 않는다. 기록 본문에서 고친 것은 링크 대상뿐이다(백엔드 1단계와 같은 예외). - 경로 글자: 살아 있는 문서와 코드·설정 주석의 `docs/architecture/…`, `docs/superpowers/…`, `decisions/VD-…`를 새 경로로 바꾼다. 기록 본문과 CHANGELOG.md는 쓴 때의 경로를 그대로 둔다. review-evidence.md와 review-ledger.json의 `docs/superpowers/specs/…`는 이 트리가 아닌 검토 작업 공간의 출처 표시라 그대로 둔다. 위험: 경로 글자를 바꾼 곳은 주석과 문서뿐이고 실행 코드의 경로 상수는 없다. 문서 지도(docs/README.md)의 옛 폴더 행은 뒤 커밋이 다시 쓴다. 검증: `git grep -n -E "docs/superpowers|architecture/decisions"`가 기록, CHANGELOG.md, 출처 표시 두 곳, docs/README.md·README.md(뒤에서 다시 쓴다) 밖에서 0건.
528 lines
40 KiB
Markdown
528 lines
40 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`(아래 표). 503 같은 키 재전송 규칙이 없는 백엔드는 `0` | — | `retryBudget: 0` 필수 |
|
|
| 뮤테이션 정책 | `...commandMutationIdentity(<OPERATION>_CONTRACT)`가 `requiresIdempotencyKey: true`, `resendSafe: true`를 준다 | 같은 함수가 `requiresIdempotencyKey: false`, `resendSafe: true`를 준다 | 같은 함수가 둘 다 `false`로 준다 |
|
|
| 결과 불명 뒤 | "같은 요청으로 다시 보내기"와 같은 입력 저장이 같은 키로 간다 | 다시 보내기와 같은 입력 저장이 키 없이 간다(1106/03-03) | 확인만 남는다. 같은 입력 저장은 보내지 않는다 |
|
|
|
|
- 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다.
|
|
- 결과를 모를 때 새 키로 다시 보내면 안 된다. 서버는 새 키를 다른 요청으로 보고 막지 못한다.
|
|
|
|
**기준**: 원칙 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 없음 (problem details 백엔드) → 기능의 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`). 짝 백엔드 예제는 `create:feature <id> --with-create`가 만든 그 파일이다. Envelope가 없는 백엔드의 예는 아래에 있다.
|
|
|
|
**problem details 백엔드의 예**
|
|
|
|
짝 백엔드가 아닌 백엔드는 DTO와 problem details(RFC 9457의 `type`·`title`·`status`)를 감싸지 않고 보낸다. 그 백엔드의 작성 operation이 쓰는 두 조각이다. 기능 이름은 `invoice-feature`(`create:feature invoice-feature --with-create`로 만든 기능)로 두었다. 자기 기능의 이름으로 바꿔 쓴다.
|
|
|
|
- 조각 1은 `contracts/<base>-problem-details.ts`다. problem 스키마와 검증기, 작성의 `commandEffect`를 둔다.
|
|
- descriptor마다 `responseEnvelope: "NONE" as const`, `problemValidator: <BASE>_PROBLEM_VALIDATOR`를 적는다. 작성 descriptor의 `commandEffect`는 `<BASE>_CREATE_EFFECT`다. Envelope operation 전용인 `refusedBeforeWrite`는 적지 않는다.
|
|
- 스키마 ID(`InvoiceProblem`)도 다른 스키마처럼 스키마 메타데이터(`contracts/<base>-schema-metadata.ts`)에 적는다. 없으면 `check:registries`가 실패한다.
|
|
- 조각 2는 `adapters/<base>-problem-mapping.ts`다. HTTP 바인딩의 `mapProblem`이 되는 함수다.
|
|
- `adapters/<base>-http-gateway.ts`의 작성 operation 정의에 `mapProblem: map<Base>CreateProblem`으로 넘긴다.
|
|
- 정하지 않은 status는 `undefined`를 돌려준다. 그러면 실행기가 status로 실패 종류를 정한다.
|
|
|
|
<!-- manual-code-block: src/features/invoice-feature/contracts/invoice-problem-details.ts -->
|
|
```ts
|
|
import { z } from "../../../contracts/zod.ts";
|
|
|
|
import type { CommandEffectDescriptor } from "../../../contracts/external-contract-runtime.ts";
|
|
import { zodValidator } from "../../../contracts/zod-validator.ts";
|
|
|
|
export const invoiceProblemSchema = z
|
|
.object({
|
|
type: z.string().min(1).max(512),
|
|
title: z.string().min(1).max(240),
|
|
status: z.int().min(100).max(599),
|
|
code: z.string().min(1).max(120).optional(),
|
|
// 422 field issues. The backend's messages are not kept.
|
|
issues: z
|
|
.array(
|
|
z
|
|
.object({
|
|
path: z.string().min(1).max(120),
|
|
code: z.string().min(1).max(80),
|
|
})
|
|
.strip(),
|
|
)
|
|
.max(50)
|
|
.optional(),
|
|
})
|
|
.strip();
|
|
|
|
export type InvoiceProblem = z.output<typeof invoiceProblemSchema>;
|
|
|
|
export const INVOICE_PROBLEM_VALIDATOR = zodValidator(
|
|
"InvoiceProblem",
|
|
invoiceProblemSchema,
|
|
);
|
|
|
|
/**
|
|
* A 409 is not by itself "refused": a resend with the same key can meet the
|
|
* first attempt still running. Only the conflict codes the backend sends
|
|
* before it writes are NOT_APPLIED; any other 409 stays MAYBE_APPLIED, so the
|
|
* next send reuses the key.
|
|
*/
|
|
const NOT_APPLIED_CONFLICT_CODES: ReadonlySet<string> = new Set(["CONFLICT"]);
|
|
|
|
export const INVOICE_CREATE_EFFECT: CommandEffectDescriptor<InvoiceProblem> =
|
|
Object.freeze({
|
|
successEffect: "APPLIED_CONFIRMED" as const,
|
|
classifyProblem({
|
|
status,
|
|
problem,
|
|
}: Readonly<{ status: number; problem: InvoiceProblem }>) {
|
|
if (status === 400 || status === 422) return "NOT_APPLIED";
|
|
if (
|
|
status === 409 &&
|
|
problem.code !== undefined &&
|
|
NOT_APPLIED_CONFLICT_CODES.has(problem.code)
|
|
) {
|
|
return "NOT_APPLIED";
|
|
}
|
|
return "MAYBE_APPLIED";
|
|
},
|
|
// The backend refuses an unauthenticated, forbidden or rate-limited
|
|
// create before it touches state. Delete this line if it does not.
|
|
classifyStatus: () => "NOT_APPLIED" as const,
|
|
});
|
|
```
|
|
|
|
<!-- manual-code-block: src/features/invoice-feature/adapters/invoice-problem-mapping.ts -->
|
|
```ts
|
|
import type {
|
|
FeatureHttpProblemMapping,
|
|
SafeResponseMetadata,
|
|
} from "../../../adapters/http/index.ts";
|
|
import type { InvoiceProblem } from "../contracts/invoice-problem-details.ts";
|
|
|
|
export function mapInvoiceCreateProblem(
|
|
problem: InvoiceProblem,
|
|
metadata: SafeResponseMetadata,
|
|
): FeatureHttpProblemMapping | undefined {
|
|
if (metadata.status === 409) {
|
|
return Object.freeze({
|
|
kind: "CONFLICT" as const,
|
|
code: problem.code ?? "INVOICE_CONFLICT",
|
|
});
|
|
}
|
|
// The executor checked the key before it sent, so this names a key rule
|
|
// the two sides disagree on: keep the code for diagnostics.
|
|
if (metadata.status === 400 && problem.code === "IDEMPOTENCY_KEY_INVALID") {
|
|
return Object.freeze({
|
|
kind: "UNKNOWN_CLIENT_FAILURE" as const,
|
|
code: problem.code,
|
|
});
|
|
}
|
|
if (metadata.status === 422) {
|
|
return Object.freeze({
|
|
kind: "VALIDATION_REJECTED" as const,
|
|
code: problem.code ?? "INVOICE_REJECTED",
|
|
validationIssues: problem.issues ?? [],
|
|
});
|
|
}
|
|
return undefined;
|
|
}
|
|
```
|
|
|
|
- 이 두 조각은 `tests/unit/manual-code-blocks.test.ts`가 시험한다. 저장소 사본에 `create:feature invoice-feature --with-create`로 기능을 만들고, 조각을 위 경로에 그대로 넣어 타입 검사를 하고, 분류와 매핑이 위 설명대로인지 돌려 본다(`tests/fixtures/manual-code-blocks/`).
|
|
|
|
**틀리면**
|
|
|
|
- 쓰기 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/design/2026-07-28-server-file-capability-infrastructure-design.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 실행기와 같다. 지원 담당이 서버 로그에서 그 요청을 찾을 때 쓴다. 202 `REJECTED`의 `FILE_REJECTED`도 성공 Envelope의 `meta.traceId`를 싣는다. 이 응답에는 거절 이유가 없다. 짝 백엔드는 검증기 code를 파일 레코드에만 적는다. 그래서 화면은 이유별 문구를 고를 수 없다.
|
|
- 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`만 적는다).
|