56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
# 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`,
|
|
`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하지 않는다.
|
|
|
|
## 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은 독립적으로 되돌릴 수 있다.
|