From e54fbf2014b5b87bf107eca19d893c9bc57af08c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 23:17:54 +0900 Subject: [PATCH] =?UTF-8?q?feat(presentation):=20=ED=8F=BC=20=EC=A0=80?= =?UTF-8?q?=EC=9E=A5=20=EC=8B=A4=ED=8C=A8=EC=99=80=20=EA=B2=B0=EA=B3=BC=20?= =?UTF-8?q?=EB=B6=88=EB=AA=85=20=ED=99=94=EB=A9=B4=EC=97=90=20=EC=A7=80?= =?UTF-8?q?=EC=9B=90=20=EC=B0=B8=EC=A1=B0=EB=A5=BC=20=EB=B3=B4=EC=9D=B8?= =?UTF-8?q?=EB=8B=A4=20(0929/08-04)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의 FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의 indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다. 사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의 contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는 고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다. 고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다. - FormFailureStatus가 supportReference={failure.requestId}를 넘긴다. - useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재 보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는 여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번 그리지 않는다. - AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만 보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다. - 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에 넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다. 공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop). 버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에 두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03 (raw 경로 정리)과 겹친다. 위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서 남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가 x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03). 결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준 202,520 → 202,631 B(예산 204,800 B). 검증: - RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1, reference-page 3. 예: "Unable to find an element with the text: 지원 참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조: corr-save-500') not found). - GREEN: 관련 3파일 70/70, tests/component·features·architecture 59 files 336 tests 통과. e2e reference-save·reference-form· reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint, check-i18n, check-design-system 통과. Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04 --- .../reference-resource-form-page.tsx | 1 + .../reference-resource-status-page.tsx | 17 +++++- .../use-reference-failure-action.ts | 10 +++- src/presentation/components/async-surface.tsx | 14 +++++ src/presentation/forms/form-components.tsx | 2 + src/presentation/forms/use-app-form.ts | 12 ++++ tests/component/async-surface.test.tsx | 12 ++++ tests/component/form-foundation.test.tsx | 50 +++++++++++++++++ tests/e2e/reference-save.spec.ts | 32 +++++++++++ .../reference-feature/reference-page.test.tsx | 56 +++++++++++++++++++ 10 files changed, 203 insertions(+), 3 deletions(-) diff --git a/src/features/reference-feature/presentation/reference-resource-form-page.tsx b/src/features/reference-feature/presentation/reference-resource-form-page.tsx index d884853c..342dc106 100644 --- a/src/features/reference-feature/presentation/reference-resource-form-page.tsx +++ b/src/features/reference-feature/presentation/reference-resource-form-page.tsx @@ -147,6 +147,7 @@ export default function ReferenceResourceFormPage() { <> { void mutation .reconcileUnknownEffect(resolution) diff --git a/src/features/reference-feature/presentation/reference-resource-status-page.tsx b/src/features/reference-feature/presentation/reference-resource-status-page.tsx index 28ad01a5..e0a68adf 100644 --- a/src/features/reference-feature/presentation/reference-resource-status-page.tsx +++ b/src/features/reference-feature/presentation/reference-resource-status-page.tsx @@ -1,11 +1,24 @@ -import { useNavigate } from "react-router-dom"; +import { useLocation, useNavigate } from "react-router-dom"; import { StatusPage } from "../../../presentation/design-system/index.ts"; import { useLocale } from "../../../presentation/i18n/index.ts"; +import type { ReferenceSupportState } from "./use-reference-failure-action.ts"; + +/** History state is untrusted input: only a string reference is shown. */ +function receivedSupportReference(state: unknown): string | undefined { + const reference = + state && typeof state === "object" + ? (state as ReferenceSupportState).supportReference + : undefined; + return typeof reference === "string" && reference !== "" ? reference : undefined; +} export default function ReferenceResourceStatusPage() { const navigate = useNavigate(); + const location = useLocation(); const { message } = useLocale(); + // 0929/08-04. Only the id the failed request carried; none when opened directly. + const supportReference = receivedSupportReference(location.state); return ( navigate("/examples/reference-resources"), }} - supportReference="REFERENCE-STATUS-DEMO" + supportReference={supportReference} /> ); } diff --git a/src/features/reference-feature/presentation/use-reference-failure-action.ts b/src/features/reference-feature/presentation/use-reference-failure-action.ts index 3ef131e5..a16bb7b3 100644 --- a/src/features/reference-feature/presentation/use-reference-failure-action.ts +++ b/src/features/reference-feature/presentation/use-reference-failure-action.ts @@ -6,6 +6,9 @@ import { useSession } from "../../../presentation/providers/session-provider.tsx const REFERENCE_SUPPORT_ROUTE = "/examples/reference-resources/status"; +/** 0929/08-04. What the support status page receives as navigation state. */ +export type ReferenceSupportState = Readonly<{ supportReference?: string }>; + /** * Reference queries own concrete destinations for generic application failure * actions. Retry remains query-owned; guarded release reloads remain in the @@ -18,6 +21,7 @@ export function useReferenceFailureAction( const navigate = useNavigate(); const { beginSignIn } = useSession(); const action = failure?.action; + const requestId = failure?.requestId; const handleAction = useCallback(() => { if (action === "reauth") { const returnTo = `${location.pathname}${location.search}${location.hash}`; @@ -31,10 +35,14 @@ export function useReferenceFailureAction( return; } if (action === "contact-support") { - void navigate(REFERENCE_SUPPORT_ROUTE); + // The id stays in history state, never in the URL. + const state: ReferenceSupportState = + requestId === undefined ? {} : { supportReference: requestId }; + void navigate(REFERENCE_SUPPORT_ROUTE, { state }); } }, [ action, + requestId, beginSignIn, location.hash, location.pathname, diff --git a/src/presentation/components/async-surface.tsx b/src/presentation/components/async-surface.tsx index ca2cde83..61d5d42a 100644 --- a/src/presentation/components/async-surface.tsx +++ b/src/presentation/components/async-surface.tsx @@ -130,6 +130,12 @@ export type AsyncSurfaceProps = Readonly<{ onResendUnknownEffect?: () => void; /** 08-05. Title level of the empty and failure surfaces it renders. */ headingLevel?: HeadingLevel | undefined; + /** + * 0929/08-04. Shown with an unknown mutation result: the request id of the + * save whose effect is unknown (`useAppForm().supportReference`). A + * terminal error shows its own `failure.requestId`. + */ + supportReference?: string | undefined; }>; export function AsyncSurface({ @@ -142,6 +148,7 @@ export function AsyncSurface({ onReconcileUnknownEffect, onResendUnknownEffect, headingLevel, + supportReference, }: AsyncSurfaceProps) { const { message } = useLocale(); if (state.base === "idle") return idle ?? null; @@ -217,6 +224,13 @@ export function AsyncSurface({ {message("action.resendMutation")} ) : null} + {state.indicator === "mutation-effect-unknown" && supportReference ? ( +

+ {message("template.supportReference", { + reference: supportReference, + })} +

+ ) : null} ) : null} {children} diff --git a/src/presentation/forms/form-components.tsx b/src/presentation/forms/form-components.tsx index 2da44361..a5d400a7 100644 --- a/src/presentation/forms/form-components.tsx +++ b/src/presentation/forms/form-components.tsx @@ -108,6 +108,8 @@ export function FormFailureStatus(props: Readonly<{ ? message("form.reauthLosesInput") : undefined } + // 0929/08-04. The same support reference a failed query shows. + supportReference={failure.requestId} /> ); } diff --git a/src/presentation/forms/use-app-form.ts b/src/presentation/forms/use-app-form.ts index e39d3877..1682abc3 100644 --- a/src/presentation/forms/use-app-form.ts +++ b/src/presentation/forms/use-app-form.ts @@ -221,6 +221,8 @@ export function useAppForm< } else if (outcome.error.effect === "MAYBE_APPLIED") { unknownSubmissionRef.current = submittedValues; setFormErrors([]); + // 0929/08-04. Kept for its request id, not shown as a status. + setStatusFailure(outcome.error); setResult("effect-unknown"); } else if (outcome.error.effect === "APPLIED_CONFIRMED") { settleSuccessfulValues(submittedValues); @@ -357,6 +359,16 @@ export function useAppForm< * or `unavailable`. */ failure: STATUS_RESULTS.has(result) ? statusFailure : null, + /** + * 0929/08-04. The request id a user quotes to support for the save the + * form shows now: a status failure or an unknown result. Pass it to the + * unknown-result `AsyncSurface`; `FormFailureStatus` reads `failure`. + * Gone after a remount, like the submitted values. + */ + supportReference: + STATUS_RESULTS.has(result) || result === "effect-unknown" + ? statusFailure?.requestId + : undefined, field, fieldId, focusField, diff --git a/tests/component/async-surface.test.tsx b/tests/component/async-surface.test.tsx index 3be76c70..56d3ceff 100644 --- a/tests/component/async-surface.test.tsx +++ b/tests/component/async-surface.test.tsx @@ -103,6 +103,18 @@ describe("async UI state matrix", () => { expect(retry).not.toHaveBeenCalled(); }); + // 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( + , + ); + + expect(screen.getByRole("status")).toHaveTextContent("지원 참조: corr-save-500"); + }); + it("keeps content visible while a non-blocking refresh runs", () => { const state = deriveAsyncState({ data: ["value"], isFetching: true }); render(existing content); diff --git a/tests/component/form-foundation.test.tsx b/tests/component/form-foundation.test.tsx index 91000a81..be1d1bb3 100644 --- a/tests/component/form-foundation.test.tsx +++ b/tests/component/form-foundation.test.tsx @@ -81,6 +81,7 @@ function FormHarness(props: Readonly<{ {String(form.dirty)} {form.result} + {form.supportReference ?? ""} ); } @@ -236,6 +237,54 @@ describe("local form facade", () => { }, ); + // 0929/08-04. A failed or unknown save carries the id a user quotes to + // support, the same as a failed query. + it("shows the save failure's request id as its support reference", async () => { + const user = userEvent.setup(); + render( + ({ + ok: false, + error: createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_ENTITY", 0, { + effect: "NOT_APPLIED", + requestId: "corr-save-400", + }), + })} + />, + ); + await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid"); + await user.click(screen.getByRole("button", { name: "Submit" })); + + expect(await screen.findByRole("alert")).toHaveTextContent( + "지원 참조: corr-save-400", + ); + expect(screen.getByTestId("support")).toHaveTextContent("corr-save-400"); + }); + + it("keeps the request id of a save whose effect is unknown", async () => { + const user = userEvent.setup(); + render( + ({ + ok: false, + error: createFailure("SERVER_FAILURE", "CREATE_ENTITY", 0, { + effect: "MAYBE_APPLIED", + requestId: "corr-save-500", + }), + })} + resetOnSuccess={false} + />, + ); + await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid"); + await user.click(screen.getByRole("button", { name: "Submit" })); + + expect(await screen.findByTestId("result")).toHaveTextContent("effect-unknown"); + expect(screen.getByTestId("support")).toHaveTextContent("corr-save-500"); + + await user.click(screen.getByRole("button", { name: "Confirm applied" })); + expect(screen.getByTestId("support")).toHaveTextContent(""); + }); + it("keeps conflict input out of URL and storage", async () => { const user = userEvent.setup(); localStorage.clear(); @@ -404,6 +453,7 @@ describe("submission timing", () => { {form.result} + {form.supportReference ?? ""} ); } diff --git a/tests/e2e/reference-save.spec.ts b/tests/e2e/reference-save.spec.ts index 5396e159..caa0f157 100644 --- a/tests/e2e/reference-save.spec.ts +++ b/tests/e2e/reference-save.spec.ts @@ -98,3 +98,35 @@ test.describe("after a rate-limited save", () => { ]); }); }); + +test.describe("after a save whose result is unknown", () => { + // The browsers log the 500 response to the console. + test.use({ + allowedBrowserFailure: /^console:error:.*status of 500/u, + }); + + // 0929/08-04. The case a user most wants to report shows the id support + // can find in the server logs. + test("shows the request id the server echoed", async ({ page }) => { + await openForm(page); + await routeCreate(page, [ + (route) => + route.fulfill({ + status: 500, + headers: { + "x-correlation-id": "corr-save-500", + "access-control-expose-headers": "x-correlation-id", + }, + json: { title: "Internal error" }, + }), + ]); + + await page + .getByRole("textbox", { name: /새 항목 이름/ }) + .fill("Saved in the browser"); + await page.getByRole("button", { name: "저장" }).click(); + + await expect(page.getByText("변경 결과를 확인할 수 없습니다.")).toBeVisible(); + await expect(page.getByText("지원 참조: corr-save-500")).toBeVisible(); + }); +}); diff --git a/tests/features/reference-feature/reference-page.test.tsx b/tests/features/reference-feature/reference-page.test.tsx index a9e69d67..c833f7c3 100644 --- a/tests/features/reference-feature/reference-page.test.tsx +++ b/tests/features/reference-feature/reference-page.test.tsx @@ -517,6 +517,62 @@ describe("reference feature page states", () => { }, ); + // 0929/08-04. The ids a user quotes to support reach the screens that + // need them, and the sample status page shows no made-up reference. + it("shows the request id of an unknown create next to its result", async () => { + const user = userEvent.setup(); + renderReference( + inputWith({ + createResource: async () => ({ + ok: false, + error: createFailure("SERVER_FAILURE", "CREATE_REFERENCE_RESOURCE", 0, { + effect: "MAYBE_APPLIED", + requestId: "corr-save-500", + }), + }), + }), + "/examples/reference-resources/new", + ); + await user.type( + await screen.findByRole("textbox", { name: /새 항목 이름/ }), + "Unknown result", + ); + await user.click(screen.getByRole("button", { name: "저장" })); + + expect(await screen.findByText("변경 결과를 확인할 수 없습니다.")).toBeVisible(); + expect(screen.getByText("지원 참조: corr-save-500")).toBeVisible(); + }); + + it("carries a failure's request id to the support status page", async () => { + const user = userEvent.setup(); + renderReference( + inputWith({ + listResources: async () => ({ + ok: false, + error: createFailure("UNKNOWN_CLIENT_FAILURE", "LIST_REFERENCE_RESOURCES", 0, { + requestId: "corr-list-400", + }), + }), + }), + ); + await user.click(await screen.findByRole("button", { name: "지원 정보 확인" })); + + expect( + await screen.findByRole("heading", { level: 1, name: "잠시 사용할 수 없습니다." }), + ).toBeVisible(); + expect(screen.getByText("지원 참조: corr-list-400")).toBeVisible(); + expect(document.body).not.toHaveTextContent("REFERENCE-STATUS-DEMO"); + }); + + it("shows no support reference on a status page opened directly", async () => { + renderReference(inputWith(), "/examples/reference-resources/status"); + + expect( + await screen.findByRole("heading", { level: 1, name: "잠시 사용할 수 없습니다." }), + ).toBeVisible(); + expect(document.body).not.toHaveTextContent("지원 참조"); + }); + it("settles the form after confirming an unknown create was applied", async () => { const user = userEvent.setup(); const createResource = vi.fn(async () => ({