문제: 설계서·계획서·납품 패키지·증거·학습 문서와 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.
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, andretryablefromApiErrorCode; - 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_DISABLEDand 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:testfor operational and transport handlers;:sample-portfolio:testfor domain advice and sample wire behavior;verifyCleanArchitectureDependenciesfor 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.