Commit Graph
11 Commits
Author SHA1 Message Date
DongHyeonka 048f490ada refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.

고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
  resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
  스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
  parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
  parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
  지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
  legacy-http-credential-authority, bounded-json-compatibility,
  request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
  지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
  boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
  계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
  422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
  비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
  보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
  1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
  risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
  경로를 V3 파일로 바꿨다.

버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
  곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.

위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
  CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
  자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
  재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
  커밋에서 지우지 않았다. 다음 커밋이 지운다.

검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
  check:adapter-inventory(140 files), check:diagnostics, check:registries,
  check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
  test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).

BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
2026-11-03 21:12:34 +09:00
DongHyeonka 326120867c fix(http): 거절의 적용 여부를 백엔드 기준 표 하나로 V2·V3가 판정한다
문제
계약 문서 6.1절(ed0e4b1, 백엔드 5786126c 코드 기준)은 400·409·422 code마다
쓰기 전 거절인지를 정했다. 쓰기 전이라 적용 안 됨인 것은 400
VALIDATION_FAILED(details 모양과 상관없음), 400 IDEMPOTENCY_KEY_INVALID,
422 IDEMPOTENT_REQUEST_MISMATCH뿐이고, 표에 없는 400·409·422는 쓰기 뒤에도
나올 수 있어 결과 불명이다. 지금 판정은 이 표와 세 곳이 다르다.
- V2: 필드 목록 없는 400 VALIDATION_FAILED({cause}, details 없음,
  {field, code})에 effect가 없다. 결과 불명으로 붙들려 다시 저장할 수 없다.
- V2: 422는 code와 상관없이 적용 안 됨이다. fileserver의 422
  INTEGRITY_MISMATCH·MALWARE_DETECTED는 레코드를 쓴 뒤 던진다.
- V3 Envelope operation(7db32e1): 위 V2 규칙을 같이 쓰고, 표 밖 400·409·422는
  classifyProblem에 맡긴다. 400·422를 모두 적용 안 됨으로 보는 분류기면
  BAD_PARAMETER·도메인 400이 틀린다.

고른 방법
- backend-envelope.ts에 표 REFUSED_BEFORE_WRITE(code → status, 진단
  reason)를 하나 두고 V2 client.ts, V3 실행기가 envelopeFailureEffect로
  같이 읽는다. 표에 있으면 NOT_APPLIED, 그 밖의 400·409·422와 503
  IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED, 나머지 status는 undefined
  (V2는 effect 없음, V3는 classifyProblem)다. 진단 reason도 같은 표에서
  읽는다.
- kind와 validationIssues 판정(isFieldValidationFailure)은 그대로 둔다.
  필드 목록 없는 400 VALIDATION_FAILED는 UNKNOWN_CLIENT_FAILURE, 422는
  VALIDATION_REJECTED다. 적용 여부만 바뀐다.
- V3 Envelope operation에서는 400·409·422를 표가 정하고 classifyProblem이
  바꾸지 못한다.

버린 대안
- V2와 V3에 표를 따로 두기: 7db32e1 전처럼 두 벌이 갈라진다.
- 표 밖 400·409·422를 classifyProblem에 맡기기: 6.1절이 표 밖은
  MAYBE_APPLIED로 정했고, 적용 안 됨을 잘못 내면 다음 저장이 새 키를 써
  같은 작업이 두 번 적용된다. 잘못된 MAYBE_APPLIED는 결과 불명 화면만 남긴다.
- 422 전부를 필드 검증(적용 안 됨)으로 남기기: 짝 백엔드는 필드 검증을
  400으로 보내고, fileserver 422는 쓴 뒤 던진다.
- V3 참조 기능 분류기 고치기: 참조 기능은 Envelope operation이 아니고
  fixture가 problem details라 이 표의 대상이 아니다. 고치지 않았다.

위험·한계
- 필드 검증을 422로 보내는 다른 백엔드를 V2로 쓰는 프로젝트는 422 뒤에
  폼에서 다시 저장할 수 없다(결과 불명). 프론트 계약 문서 4.2절의 "422
  field validation" 행과 어긋난다. 그 문서는 이 커밋에서 고치지 않았다.
- 표는 백엔드 5786126c 기준이다. 백엔드가 쓰기 전 거절 code를 새로 만들면
  6.1절과 이 표를 함께 고쳐야 한다. 두 repo를 비교하는 검사는 없다.
- 6.1절의 남은 위험: 백엔드가 use case 안에서 VALIDATION_FAILED를 내게 되면
  적용 안 됨 판정이 틀린다.

검증
- RED: 바뀐 행 8건 실패. tests/integration/http-client.test.ts 필드 목록
  없는 400 VALIDATION_FAILED 3모양의 effect, http-diagnostics.test.ts의
  "unrelated 422"(effect NOT_APPLIED), http-execution-v3-envelope.test.ts의
  고정 판정 2건(VALIDATION_FAILED 3모양 NOT_APPLIED, BAD_PARAMETER·도메인
  409·fileserver 422 MAYBE_APPLIED), form-foundation.test.tsx 2건({cause}
  실패 뒤 다시 저장, 422 뒤 저장 버튼 꺼짐).
- GREEN: 위 4개 파일 128건 통과. V2와 V3에 같은 응답 11가지를 보내 판정을
  비교하는 행이 모두 같다.
- check:types, lint, check:architecture, check:diagnostics, check:ci,
  check:registries, check:adapter-inventory 통과. test:unit 2,604,
  test:integration 209, test:component 245, tests/features·tests/contract
  124건 통과. check:bundle 203,354 / 204,800 B.

Refs: docs/architecture/backend-api-and-server-state-contract.md 6.1 (ed0e4b1),
docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
2026-11-03 20:26:28 +09:00
DongHyeonka 64e98ee2fa fix(http): V2 검증 거절을 적용 안 됨으로 보고 고친 값을 다시 저장하게 한다 (백엔드 1101/02-01)
문제
V2 클라이언트(client.ts)는 필드 검증 거절(422, 짝 백엔드의 400
VALIDATION_FAILED + 필드 목록)에 effect를 붙이지 않는다. mutation
코디네이터(application-query.ts mutationFailureWithEffect)는 effect가 없으면
MAYBE_APPLIED로 보고 admission을 UNKNOWN으로 붙든다. 폼은 VALIDATION_
REJECTED를 필드 오류로 보여 주지만, 참조 폼 페이지는 코디네이터가 결과 불명을
들고 있으면 저장 버튼을 끈다(reference-resource-form-page.tsx
mutationBlocked). 사용자가 필드를 고쳐도 다시 저장할 수 없다. use-app-form
자체는 VALIDATION_REJECTED에서 unknownSubmissionRef를 비우므로 막지 않는다.
막는 것은 코디네이터 상태다.
V3 참조 기능은 재현되지 않는다. 생성 분류기가 400·422를 NOT_APPLIED로
본다(reference-feature-contract-contribution.ts classifyProblem).

고른 방법
V2에서 필드 검증 거절(fieldValidation: 422, 또는 400 VALIDATION_FAILED +
배열 details)에 effect NOT_APPLIED를 붙인다. 멱등성 거절(IDEMPOTENCY_
REFUSALS)과 같은 자리에서 붙이고, 진단 reason은 멱등성 거절에만 남긴다.

근거(백엔드 계약)
- docs/web/http-contract.md 4절과 web adapter README 예외 표가 VALIDATION_
  FAILED의 출처를 적는다: 요청 본문 바인딩(MethodArgumentNotValid
  Exception), 컨트롤러 파라미터 제약(HandlerMethodValidationException),
  Bean Validation(ConstraintViolationException), 페이지 파라미터, 읽을 수
  없는 본문. 모두 요청을 묶는 단계에서 컨트롤러·use case보다 먼저 거절한다.
- 4절에 "상태를 바꾸지 않는다"는 문장은 없다. 이 판정은 위 출처에서
  끌어낸 것이다.

버린 대안
- 코디네이터가 effect 없는 VALIDATION_REJECTED를 모두 NOT_APPLIED로 보기:
  거절을 판정하는 곳은 응답을 읽는 클라이언트다. 코디네이터의 "모르면
  MAYBE_APPLIED" 규칙은 그대로 둔다.
- 폼 페이지가 VALIDATION_REJECTED 뒤 결과 불명을 무시하기: 키가 붙은 채
  남아 같은 입력을 다시 저장하면 같은 키가 나간다.

위험·한계
- application 층에서 쓰기 뒤에 VALIDATION_FAILED를 던지는 백엔드 코드가
  있다면 이 판정은 틀린다. 짝 백엔드 IdempotencyExecutor는 실행 중 예외를
  EFFECT_UNKNOWN_ABANDONED로 기록한다. 이 경우 같은 키 재전송은 500
  IDEMPOTENCY_RECOVERY_REQUIRED를 받는다. NOT_APPLIED면 다음 저장이 새 키를
  쓰므로 그 경로를 타지 않는다.
- 필드 목록 없는 400 VALIDATION_FAILED({cause}, 본문 파싱 실패)와 그 밖의
  400·409는 effect 없이 둔다(결과 불명으로 붙듦). 이번 범위 밖이다.
- 422 IDEMPOTENT_REQUEST_MISMATCH는 원래 NOT_APPLIED였고 그대로다.

검증
- RED: tests/component/form-foundation.test.tsx "saves the corrected value
  after a $status field error" 2행(422, 400 VALIDATION_FAILED) 실패. 필드
  오류 뒤 저장 버튼이 disabled다.
- V3: tests/features/reference-feature/reference-production-vertical.test.tsx
  "saves the corrected value after a server 422 field error"는 수정 전에도
  통과한다(재현 안 됨, 동작 고정).
- GREEN: 위 행 통과. tests/integration/http-diagnostics.test.ts의 "unrelated
  422" 행은 effect가 없다고 기대하던 것을 NOT_APPLIED로 바꾸고, 409 행을
  더해 다른 거절은 effect가 없음을 고정했다. tests/integration/http-client.
  test.ts에 400 VALIDATION_FAILED effect 단언을 더했다.
  tests/unit·contract·runtime-schema·integration·component·features·platform
  3398 tests 통과, 1개 실패(tests/unit/second-api-feature-registries.test.ts,
  기준 3b7d73a에서도 같은 메시지로 실패). tsc app·test, 바꾼 파일 eslint
  통과.

Refs: clean-architecture-backend-template docs/web/http-contract.md 4절, src/adapter/inbound/web/README.md 예외 표
2026-11-03 02:16:49 +09:00
DongHyeonka 02e35d2b38 fix(http): 짝 백엔드의 400 VALIDATION_FAILED를 폼 필드 오류로 읽는다 (백엔드 1101/02-01)
문제
짝 백엔드는 필드 검증 실패를 400 VALIDATION_FAILED로 보낸다. details는
위반 하나마다 {field, code, message}인 배열이다(백엔드 docs/web/http-
contract.md 4절, ClientSafeValidationDetails). field는 점으로 이은 속성
이름이고 인덱스는 뺀다. 클래스 수준 오류는 "request"다.
프론트 V2 클라이언트(client.ts)는 422만 필드 검증으로 읽는다. 400은
UNKNOWN_CLIENT_FAILURE이고 validationIssues가 없어서, 폼(use-app-form.ts)이
필드 오류 대신 "unavailable" 상태를 보인다. safeValidationIssues도
{issues}·{fieldErrors} 객체만 읽어서 배열 details를 버린다.

고른 방법
- V2: 400 + code VALIDATION_FAILED + details가 배열이면 422와 같은 것으로
  본다. kind VALIDATION_REJECTED와 validationIssues를 422 경로와 같은 식으로
  만든다. 폼은 기존 mapValidationFailureToFields와 allowedServerFields를
  그대로 쓴다. 새 폼 경로는 없다.
- safeValidationIssues: details가 배열이면 각 항목의 field를 path로 읽는다.
  message는 버린다. 후보 수는 기존 상한(MAX_VALIDATION_ISSUE_CANDIDATES)으로
  자른 뒤 projectValidationIssues에 넘긴다.
- 그 밖의 400은 그대로 둔다: details가 {cause}인 VALIDATION_FAILED(본문
  파싱 실패), details 없는 VALIDATION_FAILED, BAD_PARAMETER,
  IDEMPOTENCY_KEY_INVALID(NOT_APPLIED 판정 유지).

버린 대안
- 400 VALIDATION_FAILED 전체를 VALIDATION_REJECTED로: 파싱 실패 같은
  클라이언트 버그가 "입력값을 다시 확인해 주세요."로 보인다. 필드 목록이
  있을 때만 바꾼다.
- 공용 projectValidationIssues가 field를 path 별칭으로 받게: zod 이슈와
  V3 경로까지 같은 규칙을 갖게 된다. 백엔드 wire 모양은 V2 전용
  safeValidationIssues에서만 읽는다.
- V3 참조 기능 mapProblem도 바꾸기: 참조 fixture는 problem+json
  (type·title·status·issues)이라 짝 백엔드 Envelope가 problem 검증을 통과하지
  않는다. 짝 백엔드 wire를 읽는 곳은 V2다.

위험·한계
- 백엔드 code(NOT_BLANK, SIZE 등)는 폼 문구 표(VALIDATION_COPY)에 없어서
  필드 문구가 "입력값을 확인해 주세요."(form.validation.unknown)다. 필드
  위치는 맞게 표시된다. 코드별 문구는 이 변경 밖이다.
- 페이지·정렬 파라미터 검증(PageValidationException)은 details가 배열이
  아닌 단일 {field, code}라 지금처럼 UNKNOWN_CLIENT_FAILURE로 남는다. 폼
  입력이 아니라 목록 조회 파라미터다.
- V2 필드 검증 실패에는 effect가 없다(422와 같다). mutation 코디네이터는
  이것을 MAYBE_APPLIED로 보고 admission을 붙든다. 422에도 있던 기존 동작이다.

검증
- RED: tests/component/form-foundation.test.tsx 새 행이 실패. V2
  클라이언트가 400 VALIDATION_FAILED를 받으면 폼 결과가 "unavailable"이고
  Name 필드에 aria-invalid가 없다. tests/integration/http-client.test.ts
  "reads the field details as validation issues" 실패(kind
  UNKNOWN_CLIENT_FAILURE, issues 없음). 다른 400 3행은 처음부터 통과(유지
  동작 고정).
- GREEN: 위 행 모두 통과. tests/unit·contract·runtime-schema·integration·
  component·features·platform 283 files 중 282 통과, 3394 tests 통과.
  실패 1개(tests/unit/second-api-feature-registries.test.ts "passes
  check-registries…")는 기준 3b7d73a에서도 같은 메시지로 실패한다.
  tsc app·test·node 통과, 바꾼 파일 eslint 통과, check:registries PASS.

Refs: clean-architecture-backend-template docs/web/http-contract.md 4절
2026-11-03 02:15:48 +09:00
DongHyeonka e54fbf2014 feat(presentation): 폼 저장 실패와 결과 불명 화면에 지원 참조를 보인다 (0929/08-04)
문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의
FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의
indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다.
사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의
contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는
고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다.

고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다.
- FormFailureStatus가 supportReference={failure.requestId}를 넘긴다.
- useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재
  보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는
  여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번
  그리지 않는다.
- AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만
  보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다.
- 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에
  넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다.
공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop).
버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에
두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03
(raw 경로 정리)과 겹친다.

위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서
남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가
x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03).
결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준
202,520 → 202,631 B(예산 204,800 B).

검증:
- RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1,
  reference-page 3. 예: "Unable to find an element with the text: 지원
  참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조:
  corr-save-500') not found).
- GREEN: 관련 3파일 70/70, tests/component·features·architecture
  59 files 336 tests 통과. e2e reference-save·reference-form·
  reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint,
  check-i18n, check-design-system 통과.

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04
2026-11-01 23:20:32 +09:00
donghyeon-kaandClaude Opus 5.5 67117cc5a5 fix(forms): show unavailable save failures as a status, not an input error (F-10)
Save failures outside sign-in, permission and retry still went into
ErrorSummary under "review the entered information". They now reach
FormFailureStatus with their own copy and action; the unused copy is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:11:25 +09:00
DongHyeonkaandClaude Opus 5.5 9894a70f04 fix(forms): give sign-in, forbidden and retry-later save failures their own state (08-01)
Every non-input save failure became "unavailable" under the "review the entered
information" summary, with no sign-in button. useAppForm now reports
reauth-required, forbidden and retry-later with the failure, and
FormFailureStatus shows each one's copy and action outside ErrorSummary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:22:58 +09:00
DongHyeonkaandClaude Opus 5.5 cc1c7d879c fix(presentation): single-flight form submit and clean state before navigation (Q-6.8-13b)
useAppForm holds one submission from validation to outcome, so a second
submit during an async refine returns the running submission instead of
submitting again (the pending ref used to be set only after
safeParseAsync). A successful save commits its settled values with
flushSync before submitForm resolves, so a navigate() right after the
save meets a clean form and the dirty guard does not ask to discard.

Verified with two new form-foundation cases (RED: submit ran twice; the
discard dialog blocked navigation) and the lane gates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:44:38 +09:00
DongHyeonka 184bd98d92 fix: preserve reconciliation authorities 2026-08-02 03:15:22 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00
donghyeon-ka b327d7370b feat: add form and page platform 2026-07-26 15:22:52 +09:00