From 6142cc8e0876ac92362acade9268be22ec98149c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 08:25:56 +0900 Subject: [PATCH] =?UTF-8?q?docs(contracts):=20=EC=9E=AC=EC=A0=84=EC=86=A1?= =?UTF-8?q?=EC=9D=84=20=ED=91=B8=EB=8A=94=20VALIDATION=5FFAILED=EB=8A=94?= =?UTF-8?q?=20=EC=9A=94=EC=B2=AD=20=EB=82=B4=EC=9A=A9=20=EA=B2=80=EC=82=AC?= =?UTF-8?q?=EC=97=AC=EC=95=BC=20=ED=95=9C=EB=8B=A4=EA=B3=A0=20=EC=A0=81?= =?UTF-8?q?=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: b41990c 뒤 같은 키 재전송이 400 VALIDATION_FAILED로 거절되면 훅과 폼이 첫 요청도 거절된 것으로 보고 결과 불명을 푼다. 백엔드가 시각이나 데이터베이스를 읽는 규칙을 VALIDATION_FAILED로 내면, 첫 요청이 적용된 뒤의 재전송도 이 답을 받을 수 있다. 계약 문서 6.1절은 이 전제를 적지 않는다(최종 리뷰 FR-02). 고른 방법: 6.1절의 재전송 규칙 옆에 한 문장을 더한다. VALIDATION_FAILED는 요청 내용만 보는 검사여야 하고, 시각이나 데이터베이스를 읽는 규칙은 기능이 선언한 code로 내며 그 code는 결과 불명을 풀지 않는다. 버린 대안: 프론트에서 VALIDATION_FAILED도 결과 불명으로 남기기(메인 세션 결정 "D10 보완 2"가 이 code를 푸는 쪽으로 정했다). 위험·한계: 문서 규칙이다. 백엔드에서 이것을 막는 검사는 없다(6.1절 끝의 남은 위험과 같다). 검증: desktop batch에서 확인. corepack pnpm verify:documentation, node scripts/run-vitest.ts run tests/unit/backend-contract-pin-document.test.ts Refs: 1106/03-01 (final review FR-02) --- docs/architecture/backend-api-and-server-state-contract.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 57bc3da1..f6131c85 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -338,6 +338,10 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 `IDEMPOTENCY_RECOVERY_REQUIRED`, §4의 503 `REQUEST_TIMEOUT`이다. 실행기가 자동으로 다시 보내는 것은 KEYED 명령의 503 `IDEMPOTENCY_UNAVAILABLE`뿐이다. 나머지는 결과 불명 화면에서 사용자가 같은 키로 다시 보낸다. +- 같은 키 재전송이 400 `VALIDATION_FAILED`로 거절되면 첫 요청도 거절된 것으로 보고 결과 + 불명을 풀므로(1106/03-01, `src/contracts/errors.ts` `isRefusedOnEveryAttempt`), + `VALIDATION_FAILED`는 요청 내용만 보는 검사여야 하고, 시각이나 데이터베이스를 읽는 + 규칙은 기능이 선언한 code로 내며 그 code는 결과 불명을 풀지 않는다. - §4의 503 `RATE_LIMIT_UNAVAILABLE`(rate-limit 저장소 응답 없음, `Retry-After` 있음)과 503 `RATE_LIMIT_INCOMPATIBLE`(rate-limit 제공자가 계약과 맞지 않음)은 status와 code가 함께 맞으면 기능 분류기와 상관없이 `NOT_APPLIED`다(1105/03-02, `backend-envelope.ts`