diff --git a/config/ci/ungated-scripts.json b/config/ci/ungated-scripts.json index 5abf98f9..42d1fd1b 100644 --- a/config/ci/ungated-scripts.json +++ b/config/ci/ungated-scripts.json @@ -1,6 +1,10 @@ { "schemaVersion": 1, "entries": [ + { + "script": "check:backend-contract-drift", + "reason": "1103/12-06. Compares the paired backend checkout next to this repository with the commit config/contracts/backend-contract-pin.json pins. CI checks out this repository alone, so a gate has no backend to read; with no checkout the script reports skipped. The gated half of the pin is tests/unit/backend-contract-pin.test.ts (test:unit), which holds the Envelope table to the copied backend answer table. Run this before moving the pin." + }, { "script": "check:feature-index", "reason": "Local check that the generated indexes (src/.generated/, not committed) are current, and the first step of verify:extreme-scale (scripts/verify-extreme-scale.ts), itself a local run. A gate gains nothing from it: every gate script regenerates the indexes first (generate-product-feature-index.ts)." diff --git a/config/contracts/backend-contract-pin.json b/config/contracts/backend-contract-pin.json new file mode 100644 index 00000000..c76b6120 --- /dev/null +++ b/config/contracts/backend-contract-pin.json @@ -0,0 +1,19 @@ +{ + "schemaVersion": 1, + "backend": { + "repository": "clean-architecture-backend-template", + "commit": "bbe944bd3c332c04be8d7af5eeef8f48bee1f2f8", + "document": "docs/web/http-contract.md", + "sectionsCompared": ["1", "2", "4"] + }, + "frontend": { + "contractDocument": "docs/architecture/backend-api-and-server-state-contract.md", + "contractSections": ["4.1", "6", "6.1"], + "readers": ["src/adapters/http/backend-envelope.ts"] + }, + "tables": { + "idempotencyAnswers": "config/contracts/backend-idempotency-answers.json" + }, + "owner": "frontend-platform", + "comparedOn": "2026-11-04" +} diff --git a/config/contracts/backend-idempotency-answers.json b/config/contracts/backend-idempotency-answers.json new file mode 100644 index 00000000..af9a0aab --- /dev/null +++ b/config/contracts/backend-idempotency-answers.json @@ -0,0 +1,59 @@ +{ + "schemaVersion": 1, + "source": { + "repository": "clean-architecture-backend-template", + "commit": "bbe944bd3c332c04be8d7af5eeef8f48bee1f2f8", + "document": "docs/web/http-contract.md" + }, + "answers": [ + { + "section": "2", + "code": "IDEMPOTENT_IN_FLIGHT", + "status": 409, + "refusedBeforeWrite": false, + "sameKeyResend": true + }, + { + "section": "2", + "code": "IDEMPOTENT_REQUEST_MISMATCH", + "status": 422, + "refusedBeforeWrite": true, + "sameKeyResend": false + }, + { + "section": "2", + "code": "IDEMPOTENCY_KEY_INVALID", + "status": 400, + "refusedBeforeWrite": true, + "sameKeyResend": false + }, + { + "section": "2", + "code": "IDEMPOTENCY_UNAVAILABLE", + "status": 503, + "refusedBeforeWrite": true, + "sameKeyResend": true + }, + { + "section": "2", + "code": "IDEMPOTENCY_COMPLETION_UNKNOWN", + "status": 503, + "refusedBeforeWrite": false, + "sameKeyResend": true + }, + { + "section": "2", + "code": "IDEMPOTENCY_RECOVERY_REQUIRED", + "status": 500, + "refusedBeforeWrite": false, + "sameKeyResend": false + }, + { + "section": "4", + "code": "REQUEST_TIMEOUT", + "status": 503, + "refusedBeforeWrite": false, + "sameKeyResend": false + } + ] +} diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 00ba8467..38d2df52 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -165,9 +165,16 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 - 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md) 1절 "Envelope 키 존재 규칙" -- 기준 커밋: 백엔드 `5786126c`. `http-contract.md`는 `34565130`에서 들어왔고 - `1400dc15`에서 마지막으로 바뀌었다. 값이 null인 필드는 키째 생략한다. 백엔드 - 기준 커밋을 올리면 6.1절 표를 같은 변경에서 다시 확인한다. +- 기준 커밋: 백엔드 `bbe944bd`. 기계가 읽는 정본은 + `config/contracts/backend-contract-pin.json`(repo, 전체 SHA, 대조한 절 §1·§2·§4, + 담당)이다. 백엔드 §2 표와 §4 `REQUEST_TIMEOUT`은 + `config/contracts/backend-idempotency-answers.json`에 code·status·쓰기 전 거절·같은 키 + 재전송 열로 옮겨 두었다. `tests/unit/backend-contract-pin.test.ts`가 그 표와 + `backend-envelope.ts`의 판정을 양방향으로 대조한다. 값이 null인 필드는 키째 + 생략한다. 백엔드 기준 커밋을 올리면 pin, 답 표 JSON, 6.1절 표를 같은 변경에서 + 다시 확인한다. 형제 디렉터리에 백엔드 checkout이 있으면 + `corepack pnpm check:backend-contract-drift`가 pin 뒤 `http-contract.md`가 + 바뀌었는지 알려 준다(게이트 밖). - 프론트에서 Envelope를 읽는 곳: `src/adapters/http/backend-envelope.ts`(스키마와 해석). V3 실행기는 descriptor가 `responseEnvelope: "ENVELOPE_V1"`일 때 쓴다. `create:feature`가 만든 기능은 이 값을 선언한다. 참조 기능은 선언하지 않고 @@ -252,7 +259,7 @@ backend idempotency를 대체하지 않는다. - 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md) 2절 "멱등성 응답", 4절 "web 전용 오류 코드" -- 기준 커밋: 4.1절과 같다(백엔드 `5786126c`). +- 기준 커밋: 4.1절과 같다(백엔드 `bbe944bd`, `config/contracts/backend-contract-pin.json`). - 프론트가 그 응답을 읽는 곳: - 키 생성·검사: `src/contracts/mutation-intent.ts` `isValidIdempotencyKey` - 결과 불명 재전송이 같은 키를 쓰고 `Retry-After`까지 기다리는 곳: @@ -272,7 +279,10 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 결과 불명으로 보인다. effect가 없는 실패도 이 값이다. 백엔드 `http-contract.md`는 code가 어느 단계에서 나오는지 적지 않는다. 아래 표는 -프론트가 백엔드 `5786126c`의 코드를 읽고 정한 판정이다. 같은 code가 쓰기 전과 +프론트가 백엔드 코드를 읽고 정한 판정이다. `5786126c`에서 읽었고, `bbe944bd`에서 +바뀐 파일(`GlobalExceptionHandler`, `IdempotencyExecutor`, `PersistenceExceptionTranslator`, +`FailureCategory`, `DomainExceptionHandler`)을 다시 읽었다. 판정은 바뀌지 않았고 줄 +번호만 옮겼다. 같은 code가 쓰기 전과 뒤에서 모두 나오면 "쓰기 뒤 가능"으로 둔다. 프론트는 code만 보고 둘을 가를 수 없다. @@ -283,11 +293,11 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 | `VALIDATION_FAILED` (400), details = `{cause}` 또는 없음 | 본문을 읽지 못함(`HttpMessageNotReadableException`) | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:233-251` | | `VALIDATION_FAILED` (400), details = `{field, code}` | 페이지·정렬 파라미터. 목록 GET 컨트롤러가 use case 전에 검사한다 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:149-153`, `PageParams.java:27-33`, `SortParam.java:16-43` | | `IDEMPOTENCY_KEY_INVALID` (400) | KEYED 컨트롤러 첫 줄의 키 파싱 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyKeyHeader.java:32-38`, `PosterImagePublicationController.java:64` | -| `IDEMPOTENT_REQUEST_MISMATCH` (422) | 멱등성 executor가 action 전에 판정 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyExecutor.java:102-103`, `:134-135` | -| `IDEMPOTENT_IN_FLIGHT` (409) | 멱등성 executor가 action 전에 판정. 같은 키의 앞선 요청이 실행 중이다 | 이번 요청은 쓰기 전. 앞선 요청은 적용될 수 있다 | `MAYBE_APPLIED` | `IdempotencyExecutor.java:104-105`, `:136-137` | -| `BAD_PARAMETER` (400) | 타입 변환 실패, 필수 파라미터·헤더 없음(쓰기 전). **어느 층이든 `IllegalArgumentException`**(use case·domain 포함) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `GlobalExceptionHandler.java:92-99`, `:108-116`, `:397-438` | -| `MAPPING_FAILED` (400) | web 매퍼(쓰기 전), outbound ACL 매퍼(use case 안), 멱등성 응답 직렬화(action이 끝난 뒤) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `WorkLogWebMapper.java:36`, `RepoStatsAclMapper.java:14`, `JsonIdempotentResponseCodec.java:32`, `IdempotencyExecutor.java:229` | -| `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_LOCK_TIMEOUT`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT` (409) | persistence 어댑터가 SQL·JPA 실패를 바꾼 것. 트랜잭션 안이나 commit에서 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FailureCategory.java:79-95`, `StandardSqlStateErrorMapping.java:46-52`, `PersistenceExceptionTranslator.java:131` | +| `IDEMPOTENT_REQUEST_MISMATCH` (422) | 멱등성 executor가 action 전에 판정 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyExecutor.java:119-120`, `:151-152` | +| `IDEMPOTENT_IN_FLIGHT` (409) | 멱등성 executor가 action 전에 판정. 같은 키의 앞선 요청이 실행 중이다 | 이번 요청은 쓰기 전. 앞선 요청은 적용될 수 있다 | `MAYBE_APPLIED` | `IdempotencyExecutor.java:121-122`, `:153-154` | +| `BAD_PARAMETER` (400) | 타입 변환 실패, 필수 파라미터·헤더 없음(쓰기 전). **어느 층이든 `IllegalArgumentException`**(use case·domain 포함) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `GlobalExceptionHandler.java:92-99`, `:108-116`, `:397-417`, `HttpStatusErrorCodes.java:33-34` | +| `MAPPING_FAILED` (400) | web 매퍼(쓰기 전), outbound ACL 매퍼(use case 안), 멱등성 응답 직렬화(action이 끝난 뒤) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `WorkLogWebMapper.java:36`, `RepoStatsAclMapper.java:14`, `JsonIdempotentResponseCodec.java:32`, `IdempotencyExecutor.java:246` | +| `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_LOCK_TIMEOUT`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT` (409) | persistence 어댑터가 SQL·JPA 실패를 바꾼 것. 트랜잭션 안이나 commit에서 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FailureCategory.java:86-102`, `StandardSqlStateErrorMapping.java:46-52`, `PersistenceExceptionTranslator.java:133` | | `LOCK_ACQUISITION_TIMEOUT` (409) | 분산 락 대기 초과. use case 안 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `LockRegistryDistributedLock.java:50`, `:53` | | 참조 도메인 `WORKLOG_INVALID`, `POSTER_INVALID_STATE`, `POSTER_IMAGE_REQUIRED` (400), `WORKLOG_CONFLICT`, `POSTER_ALREADY_EXISTS`, `POSTER_IMAGE_ALREADY_PUBLISHED` (409) | application·domain 예외 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `DomainExceptionHandler.java:52-90` | | 선택 모듈 web-advanced `PATCH_REJECTED` (400), `PATCH_TEST_FAILED` (409) | patch 라이브러리. 부르는 코드가 단계를 정한다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | @@ -304,7 +314,7 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 자동으로 다시 보내는 것은 KEYED 명령의 503 `IDEMPOTENCY_UNAVAILABLE`뿐이다. 나머지는 결과 불명 화면에서 사용자가 같은 키로 다시 보낸다. - 파일 위치(백엔드 repo 기준): - - `GlobalExceptionHandler.java`: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/` + - `GlobalExceptionHandler.java`, `HttpStatusErrorCodes.java`: `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/` - `PageParams.java`, `SortParam.java`: 같은 모듈 `.../web/pagination/` - `IdempotencyKeyHeader.java`: 같은 모듈 `.../web/http/` - `IdempotencyExecutor.java`: `src/application-core/src/main/java/dev/caskeleton/application/idempotency/` diff --git a/package.json b/package.json index f0cf9a37..147ef6c4 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,7 @@ "check:i18n": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts", "check:i18n:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts --fixture", "check:adapter-inventory": "node scripts/check-adapter-inventory.ts", + "check:backend-contract-drift": "node scripts/check-backend-contract-drift.ts", "check:remediation-ledger": "node scripts/check-remediation-ledger.ts", "check:release-admission": "node scripts/generate-product-feature-index.ts && node scripts/check-release-admission.ts", "check:diagnostics": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts", diff --git a/scripts/check-backend-contract-drift.ts b/scripts/check-backend-contract-drift.ts new file mode 100644 index 00000000..d7dfe35e --- /dev/null +++ b/scripts/check-backend-contract-drift.ts @@ -0,0 +1,83 @@ +import { spawnSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import path from "node:path"; + +/** + * 1103/12-06. Local only, outside every gate: CI checks this repository out + * alone. Tells whether the paired backend checkout next to this one has moved + * past the commit `config/contracts/backend-contract-pin.json` pins, and + * whether the contract document changed since. + * + * corepack pnpm check:backend-contract-drift [--backend