feat(presentation): 폼 저장 실패와 결과 불명 화면에 지원 참조를 보인다 (0929/08-04)
문제: 조회 실패는 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
This commit is contained in:
@@ -147,6 +147,7 @@ export default function ReferenceResourceFormPage() {
|
||||
<>
|
||||
<AsyncSurface
|
||||
state={mutation.state}
|
||||
supportReference={form.supportReference}
|
||||
onReconcileUnknownEffect={(resolution) => {
|
||||
void mutation
|
||||
.reconcileUnknownEffect(resolution)
|
||||
|
||||
@@ -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 (
|
||||
<StatusPage
|
||||
@@ -20,7 +33,7 @@ export default function ReferenceResourceStatusPage() {
|
||||
label: message("reference.status.back"),
|
||||
onAction: () => navigate("/examples/reference-resources"),
|
||||
}}
|
||||
supportReference="REFERENCE-STATUS-DEMO"
|
||||
supportReference={supportReference}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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")}
|
||||
</Button>
|
||||
) : null}
|
||||
{state.indicator === "mutation-effect-unknown" && supportReference ? (
|
||||
<p>
|
||||
{message("template.supportReference", {
|
||||
reference: supportReference,
|
||||
})}
|
||||
</p>
|
||||
) : null}
|
||||
</div>
|
||||
) : null}
|
||||
{children}
|
||||
|
||||
@@ -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}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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(
|
||||
<AsyncSurface
|
||||
state={deriveAsyncState({ data: ["value"], hasMutationEffectUnknown: true })}
|
||||
supportReference="corr-save-500"
|
||||
/>,
|
||||
);
|
||||
|
||||
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(<AsyncSurface state={state}>existing content</AsyncSurface>);
|
||||
|
||||
@@ -81,6 +81,7 @@ function FormHarness(props: Readonly<{
|
||||
</Button>
|
||||
<output data-testid="dirty">{String(form.dirty)}</output>
|
||||
<output data-testid="result">{form.result}</output>
|
||||
<output data-testid="support">{form.supportReference ?? ""}</output>
|
||||
</Form>
|
||||
);
|
||||
}
|
||||
@@ -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(
|
||||
<FormHarness
|
||||
submit={async () => ({
|
||||
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(
|
||||
<FormHarness
|
||||
submit={async () => ({
|
||||
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", () => {
|
||||
<FormField {...form.field("name")} label="Name" required />
|
||||
<Button type="submit">Submit</Button>
|
||||
<output data-testid="result">{form.result}</output>
|
||||
<output data-testid="support">{form.supportReference ?? ""}</output>
|
||||
</Form>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -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();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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 () => ({
|
||||
|
||||
Reference in New Issue
Block a user