diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index f9285207..2d258ddc 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -504,7 +504,7 @@ projectRequest: (input) => Object.freeze({ ① **정할 것** - 페이지 템플릿. [02 결정표 6절](02-decision-tables.md#6-페이지-템플릿) -- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 키가 있는 요청(`KEYED`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. +- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 키가 있는 요청(`KEYED`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. 폼 밖에서 `mutation.submit`을 부르는 화면도 `NEVER` 쓰기의 같은 입력을 다시 보낼 수 없다. 훅이 `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)로 거절한다. `AsyncSurface`에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의 `state`를 넘긴다). - 폼이면 서버 필드 오류를 받을 필드(`useAppForm`의 `allowedServerFields`). 짝 백엔드는 필드 검증 거절을 400 `VALIDATION_FAILED`와 `details[{field, code}]`로 보낸다(422가 아니다). 공유 MSW 시나리오에는 짝 백엔드가 보내지 않는 `validation-422`만 있고, Envelope operation에서 그 답은 결과 불명이다. 짝 백엔드 모양의 필드 오류 테스트는 생성된 작성 폼 테스트(`-create-page.test.tsx`)처럼 400 본문을 손으로 적는다. ② **기준** diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md index c4576711..ba60984a 100644 --- a/docs/operations/api-contract-and-server-state-recovery.md +++ b/docs/operations/api-contract-and-server-state-recovery.md @@ -257,7 +257,11 @@ diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그 key다. 자동 재전송은 없다(`src/presentation/adapters/query/application-query.ts` `submit`·`resendUnknownEffect`, 화면 `src/presentation/components/async-surface.tsx`). 키가 없는 command(`NEVER`)는 서버가 두 번째 요청을 가려내지 못하므로 재전송 버튼을 - 그리지 않는다(`canResendUnknownEffect`, 0929/03-03). + 그리지 않는다(`canResendUnknownEffect`, 0929/03-03). 같은 canonical input의 재저장도 + 보내지 않는다. 훅의 `submit`이 `NOT_STARTED` `DUPLICATE_IN_FLIGHT`(code + `UNKNOWN_EFFECT_PENDING`)를 돌려주고, 결과 불명 요청이 확인될 때까지 그대로다. 폼 + 밖에서 `submit`을 부르는 화면도 같다. 화면은 상태에 `unknownEffectResendable: true`가 + 있을 때만 재전송 버튼을 그린다. 5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다. 화면의 "변경됨으로 확인"이 이 경로다. 6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는 diff --git a/src/application/view-models/async-state.ts b/src/application/view-models/async-state.ts index ecf72aa8..02f2a4f5 100644 --- a/src/application/view-models/async-state.ts +++ b/src/application/view-models/async-state.ts @@ -86,7 +86,9 @@ export type AsyncState = Readonly<{ /** * 0929/03-03. Only with `indicator: "mutation-effect-unknown"`, when the * coordinator said: `false` means the request has no idempotency key, so - * sending it again is a second, unprotected request and no resend is drawn. + * sending it again is a second, unprotected request. A resend is drawn + * only for `true`; absent (a state built without the coordinator) draws + * none. */ unknownEffectResendable?: boolean; }>; diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts index 2f6daace..49750c6c 100644 --- a/src/presentation/adapters/query/application-query.ts +++ b/src/presentation/adapters/query/application-query.ts @@ -243,6 +243,13 @@ export type LegacyMutationOptions = LegacyMutationBase = Readonly<{ state: AsyncState; + /** + * D-1. The same canonical input as an unknown-effect request is the same + * logical request: a keyed command sends it again with that request's + * key. 0929/03-03. Without a key it is not sent: the result is a + * `NOT_STARTED` `DUPLICATE_IN_FLIGHT` failure with code + * `UNKNOWN_EFFECT_PENDING` until the unknown request is reconciled. + */ submit(input: Input): Promise>; resolveConflict(): Promise; /** @@ -559,6 +566,21 @@ export function useApplicationMutation( candidate.state === "UNKNOWN" && candidate.intent?.canonicalInputIdentity === identity, ); + // 0929/03-03. Without an idempotency key the server cannot tell that + // request from this one, so saving the same input again could apply it + // twice. The unknown request is settled first (reconcileUnknownEffect), + // never repeated; a page that calls submit outside the form meets this + // too. + if (replayed && replayed.intent?.idempotencyKey === undefined) { + identityLease?.release(); + return Promise.resolve({ + ok: false, + error: createFailure("DUPLICATE_IN_FLIGHT", definitionId, 0, { + code: "UNKNOWN_EFFECT_PENDING", + effect: "NOT_STARTED", + }), + }); + } const admission: MutationAdmission = { sequence: unknownEffectChannel.nextSequence++, state: "ACTIVE", diff --git a/src/presentation/components/async-surface.tsx b/src/presentation/components/async-surface.tsx index b6028b5f..041d3072 100644 --- a/src/presentation/components/async-surface.tsx +++ b/src/presentation/components/async-surface.tsx @@ -128,8 +128,10 @@ export type AsyncSurfaceProps = Readonly<{ onReconcileUnknownEffect?: (resolution: "APPLIED") => void; /** * D-1. Resends the unknown request with its original intent and key. - * 0929/03-03. Not drawn when `state.unknownEffectResendable` is `false`: - * a request without a key would go out as a second, unprotected one. + * 0929/03-03. Drawn only when `state.unknownEffectResendable` is `true` + * (the coordinator's `canResendUnknownEffect`): a request without a key + * would go out as a second, unprotected one, and a state built by hand + * without that answer draws no resend either. */ onResendUnknownEffect?: () => void; /** 08-05. Title level of the empty and failure surfaces it renders. */ @@ -224,7 +226,7 @@ export function AsyncSurface({ ) : null} {state.indicator === "mutation-effect-unknown" && onResendUnknownEffect && - state.unknownEffectResendable !== false ? ( + state.unknownEffectResendable === true ? ( diff --git a/tests/component/application-mutation-admission.test.tsx b/tests/component/application-mutation-admission.test.tsx index f52334af..b62cff0c 100644 --- a/tests/component/application-mutation-admission.test.tsx +++ b/tests/component/application-mutation-admission.test.tsx @@ -555,6 +555,43 @@ describe("application mutation intent admission", () => { expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown"); }); + // 0929/03-03. Saving the same input again reuses the unknown request's + // intent. Without a key that is a second request the server cannot tell + // from the first, so the hook refuses it before sending, whatever page + // calls it (review experiment X1: keys [null, null]). + it("refuses to send a keyless unknown request again for the same input", async () => { + const { hook, execute } = renderKeyedCreate([unknown], { keyed: false }); + await act(() => hook.result.current.submit("keyless-input")); + expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown"); + + let again: ApplicationResult | undefined; + await act(async () => { + again = await hook.result.current.submit("keyless-input"); + }); + + expect(again).toMatchObject({ + ok: false, + error: { + kind: "DUPLICATE_IN_FLIGHT", + code: "UNKNOWN_EFFECT_PENDING", + effect: "NOT_STARTED", + }, + }); + expect(execute).toHaveBeenCalledOnce(); + expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown"); + }); + + it("still sends another input while a keyless request is unknown", async () => { + const { hook, execute } = renderKeyedCreate([unknown], { keyed: false }); + await act(() => hook.result.current.submit("first-input")); + await act(() => hook.result.current.submit("changed-input")); + + expect(execute.mock.calls.map(([input]) => input)).toEqual([ + "first-input", + "changed-input", + ]); + }); + it("offers the same-key resend for an unknown keyed request", async () => { const { hook } = renderKeyedCreate([unknown]); expect(hook.result.current.canResendUnknownEffect).toBe(false); diff --git a/tests/component/async-surface.test.tsx b/tests/component/async-surface.test.tsx index 6b3ab630..3eceb061 100644 --- a/tests/component/async-surface.test.tsx +++ b/tests/component/async-surface.test.tsx @@ -65,9 +65,11 @@ describe("async UI state matrix", () => { const retry = vi.fn(); const reconcile = vi.fn(); const resend = vi.fn(); + // 0929/03-03. The coordinator says the request carries a key. const state = deriveAsyncState({ data: ["value"], hasMutationEffectUnknown: true, + isUnknownEffectResendable: true, }); render( @@ -123,6 +125,23 @@ describe("async UI state matrix", () => { expect(screen.getByRole("button", { name: "변경됨으로 확인" })).toBeInTheDocument(); }); + // 0929/03-03. A state built by hand without the coordinator's answer does + // not know the request has a key, so it draws no resend (review X3). + it("draws no resend for an unknown state that does not say it can be resent", () => { + render( + , + ); + + expect( + screen.queryByRole("button", { name: "같은 요청으로 다시 보내기" }), + ).not.toBeInTheDocument(); + expect(screen.getByRole("button", { name: "변경됨으로 확인" })).toBeInTheDocument(); + }); + it("keeps the resend state to an unknown mutation only", () => { expect( deriveAsyncState({ data: ["value"], isUnknownEffectResendable: false }),