docs(manual): 업무 거절 code를 refusedBeforeWrite에 적으라고 기능 추가 안내에 쓴다

문제
매뉴얼 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
This commit is contained in:
DongHyeonka
2026-11-04 21:04:28 +09:00
parent ba2b4f4c6d
commit 1d17e7d2d1
+3 -2
View File
@@ -202,7 +202,8 @@ FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-ope
- 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다.
- problem 스키마(`<base>-schemas.ts`의 `<base>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-결과-불명)이다.
- 업무 규칙 거절(`<FEATURE>_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/<id>/<base>-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`로 정의할 때 적는다.
② **기준**