diff --git a/docs/adr/VD-04-native-form-facade.md b/docs/adr/VD-04-native-form-facade.md
index 91a263e4..083dcc87 100644
--- a/docs/adr/VD-04-native-form-facade.md
+++ b/docs/adr/VD-04-native-form-facade.md
@@ -4,7 +4,7 @@
- 상태: 채택(보완)
- 작성일: 2026-07-26
- 요약: 폼은 외부 폼 라이브러리 대신 native form 이벤트를 쓰는 local `useAppForm` facade로 처리하고 검증 오류·충돌·저장 실패를 구분해 보여 준다는 결정이다.
-- 현재 정본: `src/presentation/forms/`, `src/presentation/templates/`. 결정 5(409를 입력 오류로 바꾸지 않음)는 기능이 선언하지 않은 409에 적용된다. 기능이 `refusalMessages`로 선언한 쓰기 전 거절(409 포함)은 필드 오류로 보인다(1103/03-01, `docs/manual/02-decision-tables.md` 4절의 `refusalMessages` 문단)
+- 현재 정본: `src/presentation/forms/`, `src/presentation/templates/`
# VD-04: Native form controller와 local facade
@@ -73,3 +73,7 @@ React Hook Form과 Zod resolver를 평가한다.
rollback 시 reference page는 이전 직접 form/layout으로 돌아갈 수 있다.
application input과 outbound gateway 계약은 유지되며, form facade와 template
commit은 독립적으로 되돌릴 수 있다.
+
+## 보완
+
+- 2026-11-12: 결정 5(409 conflict는 validation으로 바꾸지 않는다)는 기능이 선언하지 않은 409에 적용된다. 기능이 `useAppForm`의 `refusalMessages`로 선언한 쓰기 전 거절은 409라도 기능의 문구로 필드나 오류 요약에 보이고, 폼은 다음 저장을 받는다(1103/03-01, 매뉴얼 02 결정표 4절). 그 밖의 409는 그대로 충돌이고, `mutation` 옵션을 준 폼은 그 안내를 입력 오류 요약이 아니라 `FormSaveFeedback`에 보인다(1112/04-02).
diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md
index d298aeb7..289bb3e5 100644
--- a/docs/manual/01-add-a-feature.md
+++ b/docs/manual/01-add-a-feature.md
@@ -578,6 +578,7 @@ export function useInvoiceListFilters(): InvoiceListSearch {
- 페이지 템플릿. [02 결정표 6절](02-decision-tables.md#6-페이지-템플릿)
- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 다시 보내도 되는 요청(`KEYED`, `IDEMPOTENT`. 뮤테이션 정책의 `resendSafe`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. 폼 밖에서 `mutation.submit`을 부르는 화면도 `NEVER` 쓰기의 같은 입력을 다시 보낼 수 없다. 훅이 `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)로 거절한다. `AsyncSurface`에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의 `state`를 넘긴다).
+- 폼으로 저장하면 결과 불명 화면을 직접 잇지 않는다. `useAppForm`에 `mutation`과 저장 뒤 할 일(`onSaved`)을 주고 피드백 자리에 `FormSaveFeedback`을 둔다. 확인·재전송, 결과 불명 동안 새 저장 막기, 페이지를 떠난 뒤 끝난 저장이 아무 데도 옮기지 않는 것을 폼이 맡는다.
- 폼이면 서버 필드 오류를 받을 필드(`useAppForm`의 `allowedServerFields`). 짝 백엔드는 필드 검증 거절을 400 `VALIDATION_FAILED`와 `details[{field, code}]`로 보낸다(422가 아니다). 공유 MSW 시나리오에는 짝 백엔드가 보내지 않는 `validation-422`만 있고, Envelope operation에서 그 답은 결과 불명이다. 짝 백엔드 모양의 필드 오류 테스트는 생성된 작성 폼 테스트(`-create-page.test.tsx`)처럼 400 본문을 손으로 적는다.
② **기준**
diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md
index d8ef76a8..69c1b92a 100644
--- a/docs/manual/reference/patterns.md
+++ b/docs/manual/reference/patterns.md
@@ -96,7 +96,7 @@ const search = (q: string) =>
| 쿼리 바인딩 | `src/contracts/server-state.ts`의 `bindQuery`, `src/presentation/adapters/query/application-query.ts` | 생성 뼈대 `presentation/use--items.ts` | profile ID (실행 때). `owner`·`operationId`는 읽는 곳이 없는 `@deprecated` 칸이라 적지 않는다 |
| 무효화 topic | `src/contracts/query-invalidation.ts` | 생성 뼈대 계약 `invalidation` | 조립(중복, 고아 topic) |
| 멱등 키 쓰기 | V3 `retrySemantics: "KEYED"`, `commandRecovery`, 뮤테이션 정책(`src/contracts/server-state.ts`의 `commandMutationIdentity`로 operation ID와 키 여부를 descriptor에서 받는다) | 쓰기 slice `--keyed`(`contracts/-contract-contribution.ts`, `presentation/use--create.ts`) | 계약 조립(복구 descriptor 필수), 타입(descriptor 상수 이름, 손으로 적은 operation ID는 `MutationOperationId`가 아니다), 기능 테스트 |
-| 결과 불명 화면 | `src/presentation/components/async-surface.tsx`의 `onReconcileUnknownEffect`, `onResendUnknownEffect` | 쓰기 slice `presentation/-create-page.tsx` | 기능 테스트만(쓰기 slice는 `-create-page.test.tsx`) |
+| 결과 불명 화면 | `src/presentation/components/async-surface.tsx`의 `onReconcileUnknownEffect`, `onResendUnknownEffect`. 폼으로 저장하면 아래 「폼」 행의 `FormSaveFeedback`이 이 둘을 잇는다 | 쓰기 slice `presentation/-create-page.tsx` | 기능 테스트(쓰기 slice는 `-create-page.test.tsx`), `tests/component/form-foundation.test.tsx` |
| 수정·삭제 명령 | 같은 V3 계약 (`PUT`, `PATCH`, `DELETE`) | 없음 (쓰기 slice는 작성 명령만 만든다) | — |
| 낙관적 갱신 | `useApplicationMutation`의 `optimistic` 옵션 (`application-query.ts`) | 없음 | 런타임 테스트만 |
| 페이지 넘김 | `src/adapters/query-cache/index.ts`의 `createCursorPaginationRuntime` | 없음 (생성 뼈대 목록은 첫 페이지와 `meta.page.total`만 읽는다) | 런타임 테스트만 |
@@ -108,7 +108,7 @@ const search = (q: string) =>
|---|---|---|---|
| 페이지 템플릿 | `src/presentation/templates/page-templates.tsx` | 생성 뼈대 `CollectionPage`, 쓰기 slice `DetailPage`·`FormPage` | `page-templates-own-layout-only` |
| 비동기 상태 화면 | `src/presentation/components/async-surface.tsx`의 `AsyncSurface` | 생성 뼈대 목록 페이지 | 페이지 테스트 |
-| 폼 | `src/presentation/forms/use-app-form.ts`의 `useAppForm`. mutation으로 저장하는 폼은 `mutation` 옵션을 주고 피드백 자리에 `FormSaveFeedback`(`src/presentation/forms/form-components.tsx`)을 둔다. 결과 불명 동안 새 저장 막기, 「변경됨으로 확인」, 같은 키 재전송, 다른 저장이 도는 동안의 표시를 폼이 맡는다 | 쓰기 slice `presentation/-form.ts`와 `-create-page.tsx` | 페이지 테스트(서버 필드 오류, 이탈 확인), `tests/component/form-foundation.test.tsx` |
+| 폼 | `src/presentation/forms/use-app-form.ts`의 `useAppForm`. mutation으로 저장하는 폼은 `mutation` 옵션을 주고 피드백 자리에 `FormSaveFeedback`(`src/presentation/forms/form-components.tsx`)을 둔다. 결과 불명 동안 새 저장 막기, 「변경됨으로 확인」, 같은 키 재전송, 다른 저장이 도는 동안의 표시, 마운트된 동안만 저장 뒤 이동(`onSaved`, `FormSaveFeedback`의 `onConfirmed`)을 폼이 맡는다 | 쓰기 slice `presentation/-form.ts`와 `-create-page.tsx` | 페이지 테스트(서버 필드 오류, 이탈 확인), `tests/component/form-foundation.test.tsx` |
| 화면 문구 | `src/presentation/i18n/index.ts`, 기능 문구 catalog | 생성 뼈대 `contracts/-message-catalog.ts` | `lint`(문구 literal), `check:i18n`(ko-KR·en-US 키) |
| 권한 분기 | 라우트 `access`, 서버 403 → 실패 | 코드 조각: [01 문서 10단계](../01-add-a-feature.md#10단계-테스트)의 403 페이지 테스트 `tests/features//-forbidden.test.tsx` | 가드 테스트. 역할·권한 힌트 예제는 없음 |
diff --git a/scripts/create-feature-write-slice.ts b/scripts/create-feature-write-slice.ts
index 2ac3cb93..50d6b944 100644
--- a/scripts/create-feature-write-slice.ts
+++ b/scripts/create-feature-write-slice.ts
@@ -589,10 +589,8 @@ export default function ${pascal}DetailPage() {
export function renderCreatePage({ names, routeId, write }: SliceShape): string {
const { base, camel, pascal, upper } = names;
- return `import { useCallback, useEffect, useRef } from "react";
-import { Link, useNavigate } from "react-router-dom";
+ return `import { Link, useNavigate } from "react-router-dom";
-import type { Result } from "../../../contracts/result.ts";
import {
Button,
DirtyNavigationDialog,
@@ -606,8 +604,6 @@ import {
useDirtyNavigationGuard,
} from "../../../presentation/design-system/index.ts";
import { useLocale } from "../../../presentation/i18n/index.ts";
-import type { ${pascal}CreateCommand } from "../application/${base}-feature-api.ts";
-import type { ${pascal}ItemView } from "../contracts/${base}-mapper.ts";
import {
${upper}_FORM_DEFAULTS,
${camel}FormSchema,
@@ -633,46 +629,24 @@ export default function ${pascal}CreatePage() {
name: message("${camel}.form.name"),
} satisfies Record;
const mutation = use${pascal}Create();
- // A save outlives this page when the user leaves while it runs. Ending
- // then, it does not take them to its item or the list (1106/08-02).
- const mounted = useRef(false);
- useEffect(() => {
- mounted.current = true;
- return () => {
- mounted.current = false;
- };
- }, []);
- const openSaved = useCallback(
- (outcome: Result<${pascal}ItemView> | null) => {
- if (outcome?.ok && mounted.current) {
- void navigate(
- ${camel}RouteUrl("${write.detail.routeId}", {
- params: { ${write.idParam}: outcome.value.itemId },
- }),
- );
- }
- return outcome;
- },
- [navigate],
- );
- const submit = useCallback(
- async (command: ${pascal}CreateCommand) => {
- const outcome = await mutation.submit(command);
- openSaved(outcome);
- return outcome;
- },
- [mutation, openSaved],
- );
// The form holds the rules of a save through the mutation: no new save
// while one is unknown or another runs, confirm and resend of an unknown
- // one (useAppForm \`mutation\`, FormSaveFeedback).
+ // one, and what the page does after a save only while it is still open
+ // (useAppForm \`mutation\` and \`onSaved\`, FormSaveFeedback).
const form = useAppForm({
schema: ${camel}FormSchema,
defaultValues: ${upper}_FORM_DEFAULTS,
allowedServerFields: ["name"],
mapToCommand: to${pascal}CreateCommand,
- submit,
+ submit: mutation.submit,
mutation,
+ onSaved: (item) => {
+ void navigate(
+ ${camel}RouteUrl("${write.detail.routeId}", {
+ params: { ${write.idParam}: item.itemId },
+ }),
+ );
+ },
});
const guard = useDirtyNavigationGuard(form.dirty && !form.pending);
@@ -714,10 +688,8 @@ export default function ${pascal}CreatePage() {
// The list shows whether the item is there; the form alone
// would show nothing but an emptied input (1105/08-02).
onConfirmed={() => {
- if (mounted.current) void navigate(${camel}RouteUrl("${routeId}"));
+ void navigate(${camel}RouteUrl("${routeId}"));
}}
- // The resend is drawn only for a request with a key (a KEYED command).
- onResent={openSaved}
/>
}
guard={}
diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts
index 5837e348..65c9e950 100644
--- a/src/presentation/adapters/query/application-query.ts
+++ b/src/presentation/adapters/query/application-query.ts
@@ -280,6 +280,13 @@ type ApplicationMutationController = Readonly<{
* `state.unknownEffectResendable` carries the same answer to `AsyncSurface`.
*/
canResendUnknownEffect: boolean;
+ /**
+ * 1112/01-01. Whether the oldest request is unknown now, read at the
+ * call, not from the last render: a form asks it when a resend has ended
+ * (`useAppForm` `mutation`). `state.indicator` says the same once the
+ * hook renders again.
+ */
+ holdsUnknownEffect(): boolean;
}>;
type MutationExecution =
@@ -869,6 +876,11 @@ export function useApplicationMutation(
return submit(head.input as Input);
}, [submit, unknownEffectChannel]);
+ const holdsUnknownEffect = useCallback(
+ () => unknownEffectChannel?.admissions[0]?.state === "UNKNOWN",
+ [unknownEffectChannel],
+ );
+
const unknownEffectHead = unknownEffectChannel?.admissions[0];
const canResendUnknownEffect =
unknownEffectChannel !== null &&
@@ -891,6 +903,7 @@ export function useApplicationMutation(
reconcileUnknownEffect,
resendUnknownEffect,
canResendUnknownEffect,
+ holdsUnknownEffect,
});
}
diff --git a/src/presentation/forms/form-components.tsx b/src/presentation/forms/form-components.tsx
index b7a98b0c..3f3fb912 100644
--- a/src/presentation/forms/form-components.tsx
+++ b/src/presentation/forms/form-components.tsx
@@ -140,55 +140,56 @@ export type FormSaveFeedbackForm