From 1d17e7d2d174c5a291976c621940b41e5bd5ccf4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 21:04:28 +0900 Subject: [PATCH] =?UTF-8?q?docs(manual):=20=EC=97=85=EB=AC=B4=20=EA=B1=B0?= =?UTF-8?q?=EC=A0=88=20code=EB=A5=BC=20refusedBeforeWrite=EC=97=90=20?= =?UTF-8?q?=EC=A0=81=EC=9C=BC=EB=9D=BC=EA=B3=A0=20=EA=B8=B0=EB=8A=A5=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80=20=EC=95=88=EB=82=B4=EC=97=90=20=EC=93=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 매뉴얼 01은 "필요하면 mapProblem을 둔다(예: 409, 422를 업무 실패로)"라고만 적는다. Envelope operation에서 mapProblem은 kind·code·필드 오류만 바꾸고 적용 여부는 바꾸지 못한다. 이 안내만 따르면 필드 오류는 보이지만 저장 버튼은 꺼진 채로 남는다(리뷰 08-01 P1의 mapProblem 행). 1e8b3d0이 더한 refusedBeforeWrite는 매뉴얼 02 4절에만 있다. 고른 방법 Envelope 실패 흐름 목록과 "정할 것"의 mapProblem 줄에 한 문장씩 더해 refusedBeforeWrite와 02 결정표 4절을 가리킨다. 5xx 판정 문장도 지금 표에 맞췄다. 위험·한계 문서만 바꿨다. 검증 verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01 Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01 --- docs/manual/01-add-a-feature.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 8382286d..d668434f 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -202,7 +202,8 @@ FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-ope - 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다. - problem 스키마(`-schemas.ts`의 `ProblemSchema`)는 Envelope의 `error` 객체다. 분기는 `code`로 한다. `message`는 버린다. -- 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`가 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. +- 400·409·422와 백엔드가 정한 5xx 넷이 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. +- 업무 규칙 거절(`_INVALID`, `*_ALREADY_EXISTS` 등)은 표에 없어 결과 불명이 된다. 그 엔드포인트가 쓰기 전에만 내는 code면 `commandEffect.refusedBeforeWrite`에 적는다. 적어야 사용자가 값을 고쳐 다시 저장할 수 있다(02 결정표 4절). - `mapProblem`이 없거나 `undefined`를 돌려주면 백엔드 code·필드 오류·status별 kind로 읽는다(`src/adapters/http/backend-envelope.ts`). - 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다. - MSW: `createHttpScenarioHandler`는 descriptor의 `responseEnvelope`를 보고 Envelope로 답한다(`tests/mocks/handlers/http-scenarios.ts`). 생성된 `tests/features//-http-gateway.test.ts`는 백엔드 본문을 그대로 적어 검사한다. @@ -326,7 +327,7 @@ projectRequest: (input) => Object.freeze({ ① **정할 것** - `needs`: 기능이 받을 capability. 템플릿이 만드는 것은 `http`, `telemetry`다. -- 문제 응답 → 실패 매핑. 필요하면 `mapProblem`을 둔다(예: 409, 422를 업무 실패로). +- 문제 응답 → 실패 매핑. 필요하면 `mapProblem`을 둔다(예: 409, 422를 업무 실패로). Envelope operation에서 `mapProblem`은 kind·code·필드 오류만 바꾸고 적용 여부는 못 바꾼다. 쓰기 전 거절이면 그 code를 `refusedBeforeWrite`에도 적는다. - operation마다 `routeId`. `defineFeatureHttpOperationForRoutes`로 정의할 때 적는다. ② **기준**