문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금 정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture 목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어 값을 쓴다. 고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은 한 글자도 고치지 않는다. 상태는 기계 변환이다. - 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면 확인 안 함 (채택 4, 확인 안 함 21) - 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는 같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5, 확인 안 함 14. 이미 블록이 있던 5개는 그대로) - 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에 있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터 한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다. - 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일. 위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서 고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다. 보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는 문서나 코드 경로만 쓴다. 검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가 같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
76 lines
4.2 KiB
Markdown
76 lines
4.2 KiB
Markdown
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
|
|
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
|
|
|
|
- 상태: 채택(보완)
|
|
- 작성일: 2026-07-26
|
|
- 요약: 폼은 외부 폼 라이브러리 대신 native form 이벤트를 쓰는 local `useAppForm` facade로 처리하고 검증 오류·충돌·저장 실패를 구분해 보여 준다는 결정이다.
|
|
- 현재 정본: `src/presentation/forms/`, `src/presentation/templates/`
|
|
<!-- 머리 블록 끝 -->
|
|
|
|
# VD-04: Native form controller와 local facade
|
|
|
|
- 상태: Accepted
|
|
- 결정일: 2026-07-26
|
|
- 적용 브랜치: `feature-frontend-form-page-platform`
|
|
|
|
## 배경
|
|
|
|
플랫폼에는 Zod가 이미 설치돼 있지만 form state, field error, dirty navigation과
|
|
page template 계약은 없었다. React Hook Form과 resolver를 바로 추가하면
|
|
dependency와 lockfile이 바뀌고, 현재 reference form에 필요하지 않은 복합 비동기
|
|
field orchestration까지 플랫폼 기본값으로 고정하게 된다.
|
|
|
|
## 결정
|
|
|
|
1. RP-06은 React native form event와 controlled value를 사용하는 local
|
|
`useAppForm` facade를 기본 엔진으로 채택한다.
|
|
2. Zod presentation schema, application command mapper와 domain invariant는 서로
|
|
다른 소유물로 유지한다.
|
|
3. page와 feature는 `useAppForm`, `Form`, `FormField`, `ErrorSummary`,
|
|
`FormFailureStatus`, `mapValidationFailureToFields`, `useDirtyNavigationGuard`만
|
|
사용한다.
|
|
4. 422 details는 승인된 `path`와 `code`만 HTTP 경계에서 투영한다. backend
|
|
message와 알 수 없는 field는 field에 전달하지 않고 안전한 form-level
|
|
error로 이동한다.
|
|
5. 409 conflict는 validation으로 바꾸지 않으며 입력과 dirty 상태를 보존한다.
|
|
6. pending submit은 동일 controller에서 한 번만 실행하고 success/reset 이후
|
|
dirty 상태를 해제한다.
|
|
7. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`는
|
|
layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다.
|
|
8. (2026-09-25, 08-01) 입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다.
|
|
`useAppForm`은 `action: "reauth"`를 `reauth-required`, `FORBIDDEN`을 `forbidden`,
|
|
`action: "retry"`를 `retry-later`로, 나머지 입력 외 실패를 `unavailable`로 구분하고
|
|
그 실패를 `failure`로 낸다(F-10). 화면은
|
|
`FormFailureStatus`로 문구와 행동(로그인·이동·다시 시도)을 보여 준다. 재로그인은
|
|
입력을 지운다는 안내를 버튼 앞에 둔다(`src/presentation/forms/use-app-form.ts`,
|
|
`form-components.tsx`).
|
|
9. (2026-09-25, 03-01) 결과 불명 저장은 사용자가 "변경되지 않음"을 판정하지 않는다.
|
|
`resendUnknown(mutation.resendUnknownEffect)`로 같은 intent·같은
|
|
`Idempotency-Key`를 다시 보낸다(`src/presentation/adapters/query/application-query.ts`).
|
|
|
|
## React Hook Form 도입 조건
|
|
|
|
다음 중 하나가 실제 제품 요구로 확인되면 local facade 내부 adapter로
|
|
React Hook Form과 Zod resolver를 평가한다.
|
|
|
|
- 동적 field array와 중첩 object를 함께 다루는 복합 form
|
|
- field 단위 비동기 validation 취소와 의존 validation
|
|
- 수백 개 field의 render isolation이 측정 가능한 병목인 경우
|
|
- uncontrolled input 또는 vendor extension이 필요한 경우
|
|
|
|
도입하더라도 이 문서의 public API와 component/application tests를 유지해야
|
|
한다. vendor package를 feature/page에서 직접 import하는 것은 허용하지 않는다.
|
|
|
|
## 검증과 rollback
|
|
|
|
- client validation, transform/default, 422 allowlist, conflict, duplicate submit,
|
|
reset, dirty guard와 focus를 component test로 검증한다.
|
|
- template 최소/전체 slot과 async/status variation을 component test로 검증한다.
|
|
- architecture gate가 template의 application/HTTP/query vendor import를
|
|
거절한다.
|
|
- secret-like input이 URL, storage, diagnostics에 복제되지 않는지 검증한다.
|
|
|
|
rollback 시 reference page는 이전 직접 form/layout으로 돌아갈 수 있다.
|
|
application input과 outbound gateway 계약은 유지되며, form facade와 template
|
|
commit은 독립적으로 되돌릴 수 있다.
|