From 2017ef76ff9cee0b881bea4b2638882934c96e20 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:43:06 +0900 Subject: [PATCH] =?UTF-8?q?fix(query):=20=ED=82=A4=20=EC=97=86=EB=8A=94=20?= =?UTF-8?q?=EA=B2=B0=EA=B3=BC=20=EB=B6=88=EB=AA=85=20=EC=9A=94=EC=B2=AD?= =?UTF-8?q?=EC=97=90=EB=8A=94=20=EC=9E=AC=EC=A0=84=EC=86=A1=EC=9D=84=20?= =?UTF-8?q?=EC=A3=BC=EC=A7=80=20=EC=95=8A=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만 본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의 결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고, 서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험 X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가 NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의 기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도 이 버튼을 숨기는 장치가 없다. 고른 방법 - application-query.ts canResend: head가 UNKNOWN이고 intent에 idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는 거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다. - AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고, 훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면 onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존 페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다. - KEYED는 지금처럼 같은 키로 재전송한다. 버린 대안 - 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존 배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다). - AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다. 위험·한계 - 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다. "적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정). - 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은 결과 불명 동안 제출을 막는다. - hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다. 검증 - RED: application-mutation-admission 2건(NEVER: canResend false·resend null· execute 1회, KEYED: canResend true), async-surface 2건 실패. - GREEN: tests/unit·integration·component·features·contract 250파일 3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출. - check:types, lint, check:architecture, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03 Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1 --- docs/manual/02-decision-tables.md | 1 + .../api-contract-and-server-state-recovery.md | 4 +- src/application/view-models/async-state.ts | 15 +++++++ .../adapters/query/application-query.ts | 41 +++++++++++++++---- src/presentation/components/async-surface.tsx | 9 +++- .../application-mutation-admission.test.tsx | 36 ++++++++++++++-- tests/component/async-surface.test.tsx | 34 +++++++++++++++ 7 files changed, 124 insertions(+), 16 deletions(-) diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 139c0935..8b1a3f64 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -125,6 +125,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 └─ MAYBE_APPLIED → 결과 불명 화면 ├─ 확인 (onReconcileUnknownEffect) └─ 같은 키로 다시 보내기 (onResendUnknownEffect) + 키가 있는 요청만. 키 없는 쓰기(NEVER)는 버튼이 없다 ``` | | `NOT_APPLIED` | `MAYBE_APPLIED` | diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md index 98c3391f..c4576711 100644 --- a/docs/operations/api-contract-and-server-state-recovery.md +++ b/docs/operations/api-contract-and-server-state-recovery.md @@ -27,7 +27,7 @@ HTTP 경로는 V3 하나다. | bounded response decoder | 구현됨. 선언 길이 → 스트림 바이트 → JSON 구조 → 스키마 순 | `src/adapters/http/bounded-body-reader.ts`, `bounded-json.ts`, `http-execution-v3.ts` `admitResponse` | | typed schema/mapper | 구현됨. 계약별 input/output/problem validator와 feature mapper | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/feature-http-binding.ts` | | strict query/mutation definition과 concurrency coordinator | 구현됨 | `src/contracts/server-state.ts` `bindQuery`·`BoundMutation`, `src/presentation/adapters/query/application-query.ts` | -| 결과 불명 command의 같은 키 재전송 | 구현됨. 사용자가 누를 때만 보낸다 | `application-query.ts` `resendUnknownEffect` (6.3) | +| 결과 불명 command의 같은 키 재전송 | 구현됨. 사용자가 누를 때만 보낸다. 키 없는 command(`NEVER`)에는 재전송을 주지 않는다 | `application-query.ts` `resendUnknownEffect` (6.3) | | cursor pagination | runtime만 있다. 설치된 operation이 쓰지 않는다 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | | conditional request | validator store만 조합됐다. V3는 `If-None-Match`/`If-Match`를 보내지 않는다 | `src/adapters/query-cache/conditional-validator-store.ts` | | GraphQL reference adapter | 구현 안 됨 | 없음 | @@ -256,6 +256,8 @@ diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그 다시 보내기"는 그 intent와 같은 `Idempotency-Key`로 보낸다. 입력이 바뀌면 새 key다. 자동 재전송은 없다(`src/presentation/adapters/query/application-query.ts` `submit`·`resendUnknownEffect`, 화면 `src/presentation/components/async-surface.tsx`). + 키가 없는 command(`NEVER`)는 서버가 두 번째 요청을 가려내지 못하므로 재전송 버튼을 + 그리지 않는다(`canResendUnknownEffect`, 0929/03-03). 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 3d573d7d..ecf72aa8 100644 --- a/src/application/view-models/async-state.ts +++ b/src/application/view-models/async-state.ts @@ -69,6 +69,11 @@ export type AsyncSignals = Readonly<{ isDegraded?: boolean; isMutationPending?: boolean; hasMutationEffectUnknown?: boolean; + /** + * 0929/03-03. Whether the unknown-effect request can be sent again as the + * same request: it carries an idempotency key. + */ + isUnknownEffectResendable?: boolean; hasMutationConflict?: boolean; }>; @@ -78,6 +83,12 @@ export type AsyncState = Readonly<{ failure?: AppFailure; overlay: AsyncOverlay; indicator: (typeof ASYNC_OVERLAYS)[number] | null; + /** + * 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. + */ + unknownEffectResendable?: boolean; }>; export function deriveAsyncState(signals: AsyncSignals): AsyncState { @@ -121,6 +132,10 @@ export function deriveAsyncState(signals: AsyncSignals): AsyncState { failure: base === "terminal-error" ? signals.failure : undefined, overlay, indicator, + ...(indicator === "mutation-effect-unknown" && + signals.isUnknownEffectResendable !== undefined + ? { unknownEffectResendable: signals.isUnknownEffectResendable } + : {}), }); } diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts index 081f240b..2f6daace 100644 --- a/src/presentation/adapters/query/application-query.ts +++ b/src/presentation/adapters/query/application-query.ts @@ -255,9 +255,17 @@ type ApplicationMutationController = Readonly<{ /** * D-1. Sends the oldest unknown-effect request again with its original * intent, so a keyed command carries the same `Idempotency-Key`. Resolves - * to `null` when nothing is waiting to be resent. + * to `null` when nothing is waiting to be resent, and (0929/03-03) when + * that request has no key: the server could not tell a second one from a + * new request, so it could apply twice. */ resendUnknownEffect(): Promise | null>; + /** + * 0929/03-03. `resendUnknownEffect` would send: the oldest request is + * unknown, carries an idempotency key and is not being reconciled. + * `state.unknownEffectResendable` carries the same answer to `AsyncSurface`. + */ + canResendUnknownEffect: boolean; }>; type MutationExecution = @@ -791,18 +799,15 @@ export function useApplicationMutation( const resendUnknownEffect = useCallback(async () => { const head = unknownEffectChannel?.admissions[0]; - if ( - !head || - head.state !== "UNKNOWN" || - !head.intent || - unknownEffectChannel?.reconciliationInFlight - ) { - return null; - } + if (!head || !canResend(unknownEffectChannel, head)) return null; return submit(head.input as Input); }, [submit, unknownEffectChannel]); const unknownEffectHead = unknownEffectChannel?.admissions[0]; + const canResendUnknownEffect = + unknownEffectChannel !== null && + unknownEffectHead !== undefined && + canResend(unknownEffectChannel, unknownEffectHead); return Object.freeze({ state: deriveAsyncState({ @@ -812,15 +817,33 @@ export function useApplicationMutation( unknownEffectHead?.state === "ACTIVE" || unknownEffectHead?.state === "RECONCILING", hasMutationEffectUnknown: unknownEffectHead?.state === "UNKNOWN", + isUnknownEffectResendable: canResendUnknownEffect, hasMutationConflict: conflict !== null, }), submit, resolveConflict, reconcileUnknownEffect, resendUnknownEffect, + canResendUnknownEffect, }); } +/** + * D-1 / 0929/03-03. A resend repeats the unknown request with its original + * intent. Without an idempotency key (a `NEVER` command) nothing lets the + * server recognise the repeat, so it is not offered. + */ +function canResend( + channel: UnknownEffectChannel, + head: MutationAdmission, +): boolean { + return ( + head.state === "UNKNOWN" && + head.intent?.idempotencyKey !== undefined && + !channel.reconciliationInFlight + ); +} + function mutationFailureWithEffect(failure: AppFailure): AppFailure { switch (failure.effect) { case "NOT_STARTED": diff --git a/src/presentation/components/async-surface.tsx b/src/presentation/components/async-surface.tsx index 61d5d42a..b6028b5f 100644 --- a/src/presentation/components/async-surface.tsx +++ b/src/presentation/components/async-surface.tsx @@ -126,7 +126,11 @@ export type AsyncSurfaceProps = Readonly<{ onResolveConflict?: () => void; /** Only `APPLIED` is offered: "not applied" needs evidence the UI lacks. */ onReconcileUnknownEffect?: (resolution: "APPLIED") => void; - /** D-1. Resends the unknown request with its original intent and key. */ + /** + * 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. + */ onResendUnknownEffect?: () => void; /** 08-05. Title level of the empty and failure surfaces it renders. */ headingLevel?: HeadingLevel | undefined; @@ -219,7 +223,8 @@ export function AsyncSurface({ ) : null} {state.indicator === "mutation-effect-unknown" && - onResendUnknownEffect ? ( + onResendUnknownEffect && + state.unknownEffectResendable !== false ? ( diff --git a/tests/component/application-mutation-admission.test.tsx b/tests/component/application-mutation-admission.test.tsx index 380c6e7e..f52334af 100644 --- a/tests/component/application-mutation-admission.test.tsx +++ b/tests/component/application-mutation-admission.test.tsx @@ -406,7 +406,7 @@ describe("application mutation intent admission", () => { function renderKeyedCreate( outcomes: ApplicationResult[], - maxIdentities?: number, + options: Readonly<{ maxIdentities?: number; keyed?: boolean }> = {}, ) { const client = queryClient(); const intents: MutationIntent[] = []; @@ -421,14 +421,14 @@ describe("application mutation intent admission", () => { return outcomes.shift() ?? { ok: true, value: input }; }, ); - const scope = replayScope(maxIdentities); + const scope = replayScope(options.maxIdentities); const hook = renderHook( () => useApplicationMutation({ definitionId: "replay-intent-v1", definitionVersion: 1, operationId: "CREATE_REPLAYED", - requiresIdempotencyKey: true, + requiresIdempotencyKey: options.keyed ?? true, owner: "platform-test", duplicatePolicy: "REJECT_WHILE_ACTIVE", scope, @@ -484,7 +484,7 @@ describe("application mutation intent admission", () => { // identity registry evicts other inputs first and the same input saved // later still finds the unknown request and its key. it("keeps the unknown input's identity when the identity registry is full", async () => { - const { hook, intents } = renderKeyedCreate([unknown], 2); + const { hook, intents } = renderKeyedCreate([unknown], { maxIdentities: 2 }); await act(() => hook.result.current.submit("same-input")); // A two-entry registry: the third input evicts the oldest unleased one. await act(() => hook.result.current.submit("second-input")); @@ -536,6 +536,34 @@ describe("application mutation intent admission", () => { expect(execute).toHaveBeenCalledTimes(3); }); + // 0929/03-03. A command without a key has nothing the server can match a + // second request to: resending it after a lost answer can apply it twice. + it("offers no resend for an unknown request that carries no key", 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"); + + expect(hook.result.current.canResendUnknownEffect).toBe(false); + expect(hook.result.current.state.unknownEffectResendable).toBe(false); + let resent: ApplicationResult | null | undefined; + await act(async () => { + resent = await hook.result.current.resendUnknownEffect(); + }); + + expect(resent).toBeNull(); + expect(execute).toHaveBeenCalledOnce(); + expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown"); + }); + + it("offers the same-key resend for an unknown keyed request", async () => { + const { hook } = renderKeyedCreate([unknown]); + expect(hook.result.current.canResendUnknownEffect).toBe(false); + await act(() => hook.result.current.submit("keyed-input")); + + expect(hook.result.current.canResendUnknownEffect).toBe(true); + expect(hook.result.current.state.unknownEffectResendable).toBe(true); + }); + // 백엔드 1101/02-01. The paired backend answers a same-key request while // the first still runs with 409 IDEMPOTENT_IN_FLIGHT and Retry-After. it("holds a resend until the Retry-After of the unknown answer", async () => { diff --git a/tests/component/async-surface.test.tsx b/tests/component/async-surface.test.tsx index d13434b5..6b3ab630 100644 --- a/tests/component/async-surface.test.tsx +++ b/tests/component/async-surface.test.tsx @@ -102,6 +102,40 @@ describe("async UI state matrix", () => { expect(retry).not.toHaveBeenCalled(); }); + // 0929/03-03. The coordinator says when the unknown request has no key; + // the surface then draws no resend, whatever callback the page passes. + it("draws no resend for an unknown request that cannot 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 }), + ).not.toHaveProperty("unknownEffectResendable"); + expect( + deriveAsyncState({ + data: ["value"], + hasMutationEffectUnknown: true, + isUnknownEffectResendable: true, + }).unknownEffectResendable, + ).toBe(true); + }); + // 0929/08-04. The unknown result is the case a user most wants to report. it("shows the support reference of a save whose effect is unknown", () => { render(