Files
clean-architecture-backend-…/docs/design/2026-08-02-client-safe-error-boundary-design.md
T
DongHyeonka 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +09:00

4.3 KiB

기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-08-02
  • 요약: 공개 HTTP 오류 응답에 허용한 문구와 안전한 값만 담게 하는 경계 설계다.
  • 현재 정본: docs/web/http-contract.md

Client-Safe Error Boundary Design

Date: 2026-08-02 Status: approved by the user's instruction to apply the detailed P1/P2 review sequentially Scope: HTTP error envelopes in adapter:inbound:web and the sample-portfolio domain advice

Context

Several handlers pass Exception#getMessage(), rejected request values, or a raw request URL into the public error envelope. Those values are not a stable API contract and can contain identifiers, tokens, uploaded values, configuration details, or internal diagnostics. Persistence and outbound dependency failures already use fixed client-safe messages; the rest of the HTTP boundary must follow the same rule.

Decision

The inbound adapter owns a message allowlist keyed by stable error code. Handlers may expose only:

  • stable code, category, HTTP status, and retryable from ApiErrorCode;
  • fixed, code-specific client messages;
  • bounded structural details such as field name, validation reason code, expected Java type, supported HTTP methods, or supported media types.

They must not expose exception messages, rejected values, raw request URLs, adapter/configuration diagnostics, opaque cursors, authentication diagnostics, resource identifiers, or duplicate domain values. Bean Validation interpolated/default messages are also discarded because custom templates can include the validated value. Validation details contain only normalized server-owned property names plus allowlisted reason codes and fixed messages; collection/map keys and indices are removed.

ClientSafeErrorMessages is extended for skeleton-wide operational codes. The sample keeps its domain wording in a separate package-private PortfolioClientSafeErrorMessages, preserving the rule that production modules do not know sample business concepts.

Public Messages

Representative mappings are fixed as follows:

  • MAPPING_FAILED → Request data could not be mapped;
  • BAD_PARAMETER → Request parameter is invalid;
  • INVALID_TOKEN → Authentication token is invalid;
  • UNAUTHENTICATED → Authentication is required;
  • authorization denials → Access is denied;
  • PRECONDITION_FAILED → Resource state changed; refresh and retry;
  • page/cursor failures → generic corrective text, with safe field/reason details retained;
  • ADAPTER_DISABLED and internal classifications → Internal server error;
  • domain not-found/conflict/invariant codes → fixed noun-level text with no ID/title value.

Transport overrides use fixed wording and retain only safe protocol metadata. For example, 405 still emits Allow, while both controller-route (NoHandlerFoundException) and static-resource (NoResourceFoundException) 404s use the same envelope without echoing the request URL.

Testing

Tests inject conspicuous secret sentinels into exception messages, rejected values, URLs, tokens, IDs, and duplicate titles. Every resulting response must preserve its status/code/category while excluding the sentinel from both error.message and error.details.

Validation tests additionally place sentinels in interpolated/default messages and iterable keys/indices. A real MockMvc resource-resolution request verifies the Spring 7 NoResourceFoundException path rather than calling the advice method directly.

The focused module suites remain the primary verification:

  • :adapter:inbound:web:test for operational and transport handlers;
  • :sample-portfolio:test for domain advice and sample wire behavior;
  • verifyCleanArchitectureDependencies for dependency direction.

Non-Goals

  • no change to error codes, categories, statuses, or retryability;
  • no suppression of server-side logs or tracing in this batch;
  • no application/domain dependency on HTTP response types;
  • no generic exception-message sanitizer based on regexes or truncation;
  • no staging, commit, amend, or push by an agent.