Files
clean-architecture-frontend…/tests/component
DongHyeonka 12d97d7469 feat(forms): 기능이 백엔드 거절 code에 자기 문구를 붙인다
문제
refusedBeforeWrite로 선언한 업무 거절은 이제 결과 불명이 아니고 다시
저장된다. 그런데 거절 이유가 사용자 말로 보이지 않는다. 선언한 400은 kind
UNKNOWN_CLIENT_FAILURE라 "요청을 처리할 수 없습니다." + "지원 정보 확인"이고,
409는 kind CONFLICT라 "다른 변경과 충돌했습니다."다. 고칠 수 있는 입력인데
지원 문의로 보낸다. mapProblem으로 필드 오류를 만들어도 문구는 플랫폼 표에서
issue code로만 고르므로(표에 없는 DUPLICATE는 "입력값을 확인해 주세요.")
기능이 *_ALREADY_EXISTS 같은 거절에 자기 문구를 붙일 자리가 없다(리뷰 08-R1
A1~A3). conflict 결과에서는 form.failure가 null이라 페이지가 code를 읽어 따로
그릴 수도 없다.

고른 방법
useAppForm에 refusalMessages 옵션을 더한다. 실패 code별로 기능 catalog의
메시지 키와(선택) 필드를 적는다. 적용 안 됨(effect NOT_APPLIED)으로 끝난 실패의
code가 있으면 그 문구를 필드 오류로(필드가 없거나 allowedServerFields 밖이면 오류
요약으로) 보이고 결과를 validation-error로 둔다. 필드면 그 필드로 포커스를
옮긴다. 키는 렌더 때 번역한다(다른 폼 오류와 같다). Object.hasOwn으로 자기 키만
읽는다(1103/08-03). 재로그인(action reauth)이 먼저다. 결과 불명은 code와 상관없이
결과 불명이다. 매뉴얼 02 4절에 적었다.

버린 대안
- 플랫폼 문구 표(form-contracts.ts)에 code를 더한다: 기능 code를 템플릿 파일에
  적게 된다.
- mapProblem이 문구까지 돌려주게 한다: 어댑터가 presentation 메시지 키를 알게
  된다.
- 지난 리뷰 5.3절 (B)(useAppForm이 코디네이터 상태를 받아 결과를 하나로 낸다):
  더 넓은 구조 변경이라 이 커밋에서 하지 않았다.

위험·한계
- 1103/03-01 남은 부분 중 이 커밋은 "이유 문구와 기능 문구 자리"만 고친다.
  KEYED 결과 불명의 같은 키 재전송이 500 IDEMPOTENCY_RECOVERY_REQUIRED를 받아도
  재전송 버튼이 남는 것(08-R1 A5)은 결정 대기로 남긴다. 백엔드 §2는 이 답에
  "같은 키 재전송은 안전하다, 첫 시도가 늦게 끝났으면 그 결과를 재생한다"고 적고
  답 표 사본도 sameKeyResend: true다. 버튼을 거두면 그 회복 길도 닫힌다. 고르는
  사람: 프론트 템플릿 담당(frontend-platform). 선택지: (a) RECOVERY_REQUIRED 뒤
  재전송을 거두고 "목록에서 확인" 안내를 둔다(AppFailure에 답의 원인을 싣는 계약
  추가 필요), (b) 백엔드가 KEYED 작업 안의 업무 예외(트랜잭션 롤백)를 "효과 없음"
  으로 기록해 같은 키 재전송이 다시 실행되게 한다(백엔드 변경), (c) 지금대로 둔다
  (재전송은 안전하고, 참조 폼은 목록 새로 보기 링크가 있다).
- 선언하지 않은 code는 지금처럼 결과 불명이고 "변경됨으로 확인"이 남는다(완료
  기준의 설계). 참조 기능과 생성기는 이 옵션을 쓰지 않는다. 생성기는 이미
  <FEATURE>_INVALID를 필드 오류로 보인다.

검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/form-foundation.test.tsx

Refs: 1103/03-01
2026-11-06 02:33:16 +09:00
..