Files
clean-architecture-frontend…/tests/integration
DongHyeonka 969979d904 fix(http): 짝 백엔드가 생략한 Envelope 키를 null과 같이 읽는다 (백엔드 1101/02-02)
문제
짝 백엔드는 이제 값이 null인 필드를 키째 뺀다(백엔드
docs/web/http-contract.md §1). V2 Envelope 스키마
(src/adapters/http/schema-registry.ts)는 두 곳에서 "키 없음"을 null과
다르게 읽는다.
- 성공 응답의 data: z.unknown()은 키가 없으면 거절한다(zod 4). 백엔드가
  data:null을 빼고 보낸 성공이 ENVELOPE_MISMATCH 실패가 된다. data:null은
  그대로 통과한다.
- meta.requestId·traceId가 필수다. 백엔드는 요청 id 필터 앞에서 끊긴
  응답(보안 entry point 등)에서 이 키를 뺄 수 있다고 적는다. 그러면 실패
  Envelope 전체가 거절되어 백엔드 error.code가 HTTP_FAILURE로 바뀐다.
error.details(키 없음 허용), meta.correlationId(선택), meta.page(strip)는
이미 키가 없어도 받는다.

고른 방법
- data를 z.unknown().default(null)로 둔다. 키가 없으면 스키마가 null을
  채우므로 client.ts의 "data" in 검사와 payload 검증이 data:null과 같은
  길을 탄다. 정규화가 wire 스키마 한 곳에 있다.
- meta.requestId·traceId를 optional로 둔다. safeMeta()는 이미 키가 없는
  경우를 처리한다.

버린 대안
- client.ts에서 "data" in 검사를 빼고 data ?? null로 읽기: 스키마와
  클라이언트 두 곳이 같은 규칙을 나눠 갖는다.
- 성공의 error:null, 실패의 data:null도 다시 받기: 백엔드가 더는 보내지
  않는 모양이다. 최상위 strict는 그대로 둔다.

위험·한계
- meta id가 없는 Envelope도 이제 유효하다. 그런 응답의 HttpResult.meta와
  AppFailure에는 requestId·traceId가 없다(이전에는 응답 전체가 거절됐다).
- V3 실행기는 Envelope를 읽지 않는다(DTO 자체를 검증). 이 변경은 V2
  경로만 바꾼다. bulk Envelope(results)는 프론트에 쓰는 곳이 없어 다루지
  않았다.

검증
- RED: tests/integration/http-client.test.ts "envelope keys the paired
  backend omits" 5행 중 2행 실패. data 키 없는 성공이 ok:false, id 키 없는
  403이 code HTTP_FAILURE.
- GREEN: 같은 5행 통과. tests/integration/http-client·http-diagnostics·
  http-execution-contract·auth-recovery·legacy-http-credential-authority,
  tests/runtime-schema 8 files 150 tests 통과. tsc app·test 통과, 바꾼
  파일 eslint 통과.

Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15
2026-11-03 02:00:45 +09:00
..