feat: centralize routes and navigation guards

package.json

@@ -28,6 +28,7 @@
     "@tanstack/react-query": "5.101.4",
     "react": "19.2.8",
     "react-dom": "19.2.8",
+    "react-router-dom": "7.18.1",
     "zod": "4.4.3"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -17,6 +17,9 @@ importers:
       react-dom:
         specifier: 19.2.8
         version: 19.2.8(react@19.2.8)
+      react-router-dom:
+        specifier: 7.18.1
+        version: 7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       zod:
         specifier: 4.4.3
         version: 4.4.3
@@ -1260,6 +1263,23 @@ packages:
   react-is@17.0.2:
     resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==}
 
+  react-router-dom@7.18.1:
+    resolution: {integrity: sha512-KaZh+X/6UtEp28x51AUYZDMg9NGoz2ja3dNHa+ta/tk40vCzKhQ/RypCWBMLbmDr6//E24Vv5uPsrqXFozdkAg==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
+  react-router@7.18.1:
+    resolution: {integrity: sha512-GDLgg3i3uM0aeJO3Fm+TCS+sDQ7gu12T6x0qdTEzcwqEfleci7JwugVNIF3U//0FWKnJT7ptG+20B2jfDqnZAg==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+
   react@19.2.8:
     resolution: {integrity: sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==}
     engines: {node: '>=0.10.0'}
@@ -1312,6 +1332,9 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  set-cookie-parser@2.7.2:
+    resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==}
+
   set-cookie-parser@3.1.2:
     resolution: {integrity: sha512-5/r/lTwbJ3zQ+qwdUFZYeRNqda7P5HD8zQKqlSjdGt1/S0cjLAphHusj4Y58ahDtWn/g32xrIS58/ikOvwl0Lw==}
 
@@ -2604,6 +2627,20 @@ snapshots:
 
   react-is@17.0.2: {}
 
+  react-router-dom@7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+    dependencies:
+      react: 19.2.8
+      react-dom: 19.2.8(react@19.2.8)
+      react-router: 7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+
+  react-router@7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+    dependencies:
+      cookie: 1.1.1
+      react: 19.2.8
+      set-cookie-parser: 2.7.2
+    optionalDependencies:
+      react-dom: 19.2.8(react@19.2.8)
+
   react@19.2.8: {}
 
   rechoir@0.8.0:
@@ -2663,6 +2700,8 @@ snapshots:
 
   semver@7.8.5: {}
 
+  set-cookie-parser@2.7.2: {}
+
   set-cookie-parser@3.1.2: {}
 
   shebang-command@2.0.0:

src/adapters/http/client.js

@@ -3,7 +3,9 @@ import { getApiOperation } from "../../contracts/api-operations.js";
 import {
   createFailure as failure,
   kindForStatus as statusKind,
+  normalizeUnknownFailure,
 } from "../../contracts/errors.js";
+import { mapOperationPayload } from "./resource-mapper.js";
 import { retryDelay, shouldRetry } from "./retry-policy.js";
 import {
   validateEnvelope,
@@ -49,6 +51,7 @@ const noAuthSession =
  *   random?: () => number,
  *   validatePayload?: (schemaId: string, value: unknown) =>
  *     { success: true, data: unknown } | { success: false },
+ *   mapPayload?: (operationId: string, payload: unknown) => unknown,
  *   idempotencyKeyFactory?: () => string
  * }} dependencies
  */
@@ -59,6 +62,7 @@ export function createHttpClient(dependencies) {
   const random = dependencies.random ?? Math.random;
   const validatePayload =
     dependencies.validatePayload ?? validateOperationPayload;
+  const mapPayload = dependencies.mapPayload ?? mapOperationPayload;
   const idempotencyKeyFactory =
     dependencies.idempotencyKeyFactory ?? (() => crypto.randomUUID());
 
@@ -195,7 +199,13 @@ export function createHttpClient(dependencies) {
       }
 
       const response = await fetcher(request);
-      return await parseResponse(response, operation, attempt, validatePayload);
+      return await parseResponse(
+        response,
+        operation,
+        attempt,
+        validatePayload,
+        mapPayload,
+      );
     } catch {
       if (timedOut) {
         return {
@@ -254,9 +264,16 @@ export function createHttpClient(dependencies) {
  * @param {number} attempt
  * @param {(schemaId: string, value: unknown) =>
  *   { success: true, data: unknown } | { success: false }} validatePayload
+ * @param {(operationId: string, payload: unknown) => unknown} mapPayload
  * @returns {Promise<HttpResult>}
  */
-async function parseResponse(response, operation, attempt, validatePayload) {
+async function parseResponse(
+  response,
+  operation,
+  attempt,
+  validatePayload,
+  mapPayload,
+) {
   const contentType = response.headers.get("content-type") ?? "";
   if (!contentType.toLowerCase().includes("application/json")) {
     return {
@@ -311,11 +328,21 @@ async function parseResponse(response, operation, attempt, validatePayload) {
       };
     }
 
-    return {
-      ok: true,
-      value: structuredClone(payload.data),
-      meta: safeMeta(envelopeRecord.meta),
-    };
+    try {
+      return {
+        ok: true,
+        value: mapPayload(operation.operationId, payload.data),
+        meta: safeMeta(envelopeRecord.meta),
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: normalizeUnknownFailure(error, {
+          operationId: operation.operationId,
+          attempt,
+        }),
+      };
+    }
   }
 
   const kind = statusKind(response.status);

src/adapters/http/resource-mapper.js

@@ -0,0 +1,30 @@
+import { createResource } from "../../domain/models/resource.js";
+
+/** @param {unknown} value */
+export function mapResourceDto(value) {
+  if (!value || typeof value !== "object") {
+    throw new TypeError("Validated resource DTO is required");
+  }
+  const dto = /** @type {Record<string, unknown>} */ (value);
+  if (typeof dto.id !== "string" || typeof dto.name !== "string") {
+    throw new TypeError("Validated resource DTO invariants were breached");
+  }
+
+  return createResource({
+    id: dto.id,
+    displayName: dto.name,
+    createdAt: typeof dto.createdAt === "string" ? dto.createdAt : null,
+  });
+}
+
+/** @param {string} operationId @param {unknown} payload */
+export function mapOperationPayload(operationId, payload) {
+  if (operationId === "LIST_SAMPLE_RESOURCES") {
+    if (!Array.isArray(payload)) throw new TypeError("Expected a resource list");
+    return payload.map(mapResourceDto);
+  }
+  if (operationId === "CREATE_SAMPLE_RESOURCE") {
+    return mapResourceDto(payload);
+  }
+  throw new TypeError(`No boundary mapper registered for ${operationId}`);
+}

src/application/view-models/async-state.js

@@ -0,0 +1,81 @@
+export const ASYNC_BASE_STATES = Object.freeze([
+  "initial-loading",
+  "success",
+  "empty",
+  "terminal-error",
+]);
+
+export const ASYNC_OVERLAYS = Object.freeze([
+  "refreshing",
+  "stale-degraded",
+  "mutation-pending",
+  "mutation-conflict",
+]);
+
+/**
+ * @typedef {{
+ *   data?: unknown,
+ *   isInitialLoading?: boolean,
+ *   failure?: import("../../contracts/errors.js").ApiFailure,
+ *   isFetching?: boolean,
+ *   isStale?: boolean,
+ *   isDegraded?: boolean,
+ *   isMutationPending?: boolean,
+ *   hasMutationConflict?: boolean
+ * }} AsyncSignals
+ */
+
+/** @param {AsyncSignals} signals */
+export function deriveAsyncState(signals) {
+  const hasData = signals.data !== undefined && signals.data !== null;
+  const empty =
+    hasData &&
+    ((Array.isArray(signals.data) && signals.data.length === 0) ||
+      signals.data === "");
+
+  let base;
+  if (signals.isInitialLoading && !hasData) {
+    base = "initial-loading";
+  } else if (signals.failure && !hasData) {
+    base = "terminal-error";
+  } else if (empty) {
+    base = "empty";
+  } else if (hasData) {
+    base = "success";
+  } else {
+    base = "initial-loading";
+  }
+
+  const overlay = Object.freeze({
+    refreshing: Boolean(signals.isFetching && hasData),
+    staleDegraded: Boolean(signals.isStale && signals.isDegraded && hasData),
+    mutationPending: Boolean(signals.isMutationPending && hasData),
+    mutationConflict: Boolean(signals.hasMutationConflict && hasData),
+  });
+
+  const state = {
+    base,
+    data: base === "success" || base === "empty" ? signals.data : undefined,
+    failure: base === "terminal-error" ? signals.failure : undefined,
+    overlay,
+    indicator: selectOverlayIndicator(overlay),
+  };
+
+  return Object.freeze(state);
+}
+
+/**
+ * @param {{
+ *   refreshing: boolean,
+ *   staleDegraded: boolean,
+ *   mutationPending: boolean,
+ *   mutationConflict: boolean
+ * }} overlay
+ */
+export function selectOverlayIndicator(overlay) {
+  if (overlay.mutationConflict) return "mutation-conflict";
+  if (overlay.mutationPending) return "mutation-pending";
+  if (overlay.staleDegraded) return "stale-degraded";
+  if (overlay.refreshing) return "refreshing";
+  return null;
+}

src/application/view-models/resource-view-model.js

@@ -0,0 +1,16 @@
+/**
+ * @param {import("../../domain/models/resource.js").Resource} resource
+ * @param {(value: Date) => string} [formatDate]
+ */
+export function toResourceViewModel(
+  resource,
+  formatDate = (value) => new Intl.DateTimeFormat("ko-KR").format(value),
+) {
+  return Object.freeze({
+    resourceId: resource.id,
+    title: resource.displayName,
+    createdAtLabel: resource.createdAt
+      ? formatDate(new Date(resource.createdAt))
+      : null,
+  });
+}

src/bootstrap/main.jsx

@@ -1,18 +1,10 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 
+import { createAnonymousSessionAdapter } from "../adapters/auth/external-session-adapter.js";
+import { AppRouter } from "../presentation/routes/app-router.jsx";
 import { BootConfigError, loadRuntimeConfig } from "./load-runtime-config.js";
 
-/** @param {{ environment: string }} props */
-function BootstrapShell({ environment }) {
-  return (
-    <main>
-      <h1>Clean Architecture Frontend</h1>
-      <p>{environment} 런타임 계약이 검증되었습니다.</p>
-    </main>
-  );
-}
-
 /** @param {{ supportReference: string }} props */
 function BootErrorShell({ supportReference }) {
   return (
@@ -36,7 +28,10 @@ async function boot() {
     const runtime = await loadRuntimeConfig();
     root.render(
       <StrictMode>
-        <BootstrapShell environment={runtime.config.APP_ENV} />
+        <AppRouter
+          authSession={createAnonymousSessionAdapter()}
+          basename={runtime.build.routerBasePath}
+        />
       </StrictMode>,
     );
   } catch (error) {

src/contracts/errors.js

@@ -9,13 +9,18 @@ const DROP_SENSITIVE = Object.freeze([
   "storageValue",
 ]);
 
+/**
+ * @typedef {"retry" | "reauth" | "navigate" | "reload-once" |
+ *   "contact-support" | "none"} ErrorAction
+ */
+
 /**
  * @typedef {{
  *   kind: string,
  *   defaultRetryable: boolean,
  *   severity: string,
  *   userMessageKey: string,
- *   action: string,
+ *   action: ErrorAction,
  *   telemetryEvent: string,
  *   redaction: readonly string[]
  * }} ErrorDefinition
@@ -25,7 +30,7 @@ const DROP_SENSITIVE = Object.freeze([
  * @param {string} kind
  * @param {boolean} defaultRetryable
  * @param {string} severity
- * @param {string} action
+ * @param {ErrorAction} action
  * @param {string} [telemetryEvent]
  * @returns {Readonly<ErrorDefinition>}
  */
@@ -156,7 +161,7 @@ export const ERROR_REGISTRY = Object.freeze({
  *   traceId?: string,
  *   retryAfterMs?: number,
  *   userMessageKey: string,
- *   action: string,
+ *   action: ErrorAction,
  *   causeClass?: string
  * }} ApiFailure
  */

src/contracts/routes.js

@@ -0,0 +1,63 @@
+/**
+ * @typedef {{
+ *   routeId: string,
+ *   path: string,
+ *   paramsSchema: string | null,
+ *   searchSchema: string | null,
+ *   access: "public" | "session-required" | "integration-defined",
+ *   loadingSurface: string,
+ *   errorSurface: string,
+ *   chunkId: string
+ * }} RouteDefinition
+ */
+
+/** @param {RouteDefinition} definition */
+const route = (definition) => Object.freeze(definition);
+
+export const ROUTE_REGISTRY = Object.freeze({
+  APP_HOME: route({
+    routeId: "APP_HOME",
+    path: "/",
+    paramsSchema: null,
+    searchSchema: null,
+    access: "public",
+    loadingSurface: "app-shell",
+    errorSurface: "route-boundary",
+    chunkId: "route-home",
+  }),
+  SAMPLE_RESOURCE_LIST: route({
+    routeId: "SAMPLE_RESOURCE_LIST",
+    path: "/sample/resources",
+    paramsSchema: null,
+    searchSchema: "SampleResourceListQuery",
+    access: "integration-defined",
+    loadingSurface: "sample-resource-list",
+    errorSurface: "feature-boundary",
+    chunkId: "route-sample-resources",
+  }),
+  NOT_FOUND: route({
+    routeId: "NOT_FOUND",
+    path: "*",
+    paramsSchema: null,
+    searchSchema: null,
+    access: "public",
+    loadingSurface: "none",
+    errorSurface: "not-found",
+    chunkId: "route-not-found",
+  }),
+});
+
+/** @param {string} routeId */
+export function getRoute(routeId) {
+  const registry = /** @type {Record<string, Readonly<RouteDefinition>>} */ (
+    ROUTE_REGISTRY
+  );
+  const selected = registry[routeId];
+  if (!selected) throw new Error(`Unregistered route: ${routeId}`);
+  return selected;
+}
+
+/** @param {string} routeId */
+export function routePath(routeId) {
+  return getRoute(routeId).path;
+}

src/domain/models/resource.js

@@ -0,0 +1,19 @@
+/**
+ * @typedef {{
+ *   id: string,
+ *   displayName: string,
+ *   createdAt: string | null
+ * }} Resource
+ */
+
+/** @param {Resource} values @returns {Readonly<Resource>} */
+export function createResource(values) {
+  if (!values.id || !values.displayName) {
+    throw new TypeError("Resource invariants require id and displayName");
+  }
+  return Object.freeze({
+    id: values.id,
+    displayName: values.displayName,
+    createdAt: values.createdAt,
+  });
+}

src/presentation/components/async-surface.jsx

@@ -0,0 +1,72 @@
+/** @param {{ label?: string }} props */
+export function LoadingSurface({ label = "불러오는 중" }) {
+  return (
+    <section aria-busy="true" aria-label={label}>
+      <div className="ui-skeleton" aria-hidden="true" />
+      <span className="sr-only">{label}</span>
+    </section>
+  );
+}
+
+/** @param {{ title?: string, action?: React.ReactNode }} props */
+export function EmptySurface({ title = "표시할 항목이 없습니다.", action }) {
+  return (
+    <section>
+      <p>{title}</p>
+      {action}
+    </section>
+  );
+}
+
+/**
+ * @param {{
+ *   userMessageKey: string,
+ *   action: "retry" | "reauth" | "navigate" | "reload-once" |
+ *     "contact-support" | "none",
+ *   onAction?: () => void
+ * }} props
+ */
+export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
+  return (
+    <section role="alert" aria-labelledby="terminal-error-message">
+      <p id="terminal-error-message">{userMessageKey}</p>
+      {action !== "none" && (
+        <button type="button" onClick={onAction}>
+          {action}
+        </button>
+      )}
+    </section>
+  );
+}
+
+/**
+ * @param {{
+ *   state: ReturnType<typeof import("../../application/view-models/async-state.js").deriveAsyncState>,
+ *   children?: React.ReactNode,
+ *   onAction?: () => void
+ * }} props
+ */
+export function AsyncSurface({ state, children, onAction }) {
+  if (state.base === "initial-loading") return <LoadingSurface />;
+  if (state.base === "empty") return <EmptySurface />;
+  if (state.base === "terminal-error" && state.failure) {
+    return (
+      <TerminalErrorSurface
+        userMessageKey={state.failure.userMessageKey}
+        action={state.failure.action}
+        onAction={onAction}
+      />
+    );
+  }
+
+  return (
+    <section aria-busy={state.overlay.refreshing || state.overlay.mutationPending}>
+      {state.indicator && (
+        <p role="status" aria-live="polite">
+          {state.indicator}
+        </p>
+      )}
+      {children}
+    </section>
+  );
+}

src/presentation/routes/app-router.jsx

@@ -0,0 +1,79 @@
+import {
+  BrowserRouter,
+  Link,
+  Route,
+  Routes,
+} from "react-router-dom";
+
+import { routePath } from "../../contracts/routes.js";
+import { decideRouteAccess } from "./navigation-policy.js";
+
+function HomePage() {
+  return (
+    <main>
+      <h1>Clean Architecture Frontend</h1>
+      <p>런타임 계약이 검증되었습니다.</p>
+      <Link to={routePath("SAMPLE_RESOURCE_LIST")}>샘플 리소스</Link>
+    </main>
+  );
+}
+
+function SamplePlaceholder() {
+  return (
+    <main>
+      <h1>샘플 리소스</h1>
+      <p>계약 fixture를 준비하고 있습니다.</p>
+    </main>
+  );
+}
+
+function NotFoundPage() {
+  return (
+    <main>
+      <h1>페이지를 찾을 수 없습니다.</h1>
+      <Link to={routePath("APP_HOME")}>홈으로 이동</Link>
+    </main>
+  );
+}
+
+/**
+ * @param {{
+ *   authSession: import("../../application/ports/auth-session-port.js").AuthSessionPort
+ * }} props
+ */
+function GuardedSampleRoute({ authSession }) {
+  const decision = decideRouteAccess(
+    "SAMPLE_RESOURCE_LIST",
+    authSession.getState(),
+  );
+  if (!decision.allowed) {
+    return (
+      <main>
+        <h1>세션이 필요합니다.</h1>
+        <button type="button">로그인</button>
+      </main>
+    );
+  }
+  return <SamplePlaceholder />;
+}
+
+/**
+ * @param {{
+ *   authSession: import("../../application/ports/auth-session-port.js").AuthSessionPort,
+ *   basename?: string
+ * }} props
+ */
+export function AppRouter({ authSession, basename = "/" }) {
+  return (
+    <BrowserRouter basename={basename}>
+      <Routes>
+        <Route path={routePath("APP_HOME")} element={<HomePage />} />
+        <Route
+          path={routePath("SAMPLE_RESOURCE_LIST")}
+          element={<GuardedSampleRoute authSession={authSession} />}
+        />
+        <Route path={routePath("NOT_FOUND")} element={<NotFoundPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}

src/presentation/routes/navigation-policy.js

@@ -0,0 +1,37 @@
+import { getRoute } from "../../contracts/routes.js";
+
+/**
+ * @param {string} routeId
+ * @param {import("../../application/ports/auth-session-port.js").SessionState} sessionState
+ */
+export function decideRouteAccess(routeId, sessionState) {
+  const route = getRoute(routeId);
+  if (route.access === "public") return { allowed: true, action: "none" };
+  if (sessionState === "authenticated") {
+    return { allowed: true, action: "none" };
+  }
+  if (sessionState === "recovery-pending") {
+    return { allowed: false, action: "wait-for-session" };
+  }
+  return { allowed: false, action: "show-sign-in" };
+}
+
+export function createRedirectLoopGuard() {
+  const visitedPairs = new Set();
+
+  return Object.freeze({
+    /**
+     * @param {string} source
+     * @param {string} target
+     */
+    allow(source, target) {
+      const pair = `${source}->${target}`;
+      if (source === target || visitedPairs.has(pair)) return false;
+      visitedPairs.add(pair);
+      return true;
+    },
+    reset() {
+      visitedPairs.clear();
+    },
+  });
+}

tests/component/async-surface.test.jsx

@@ -0,0 +1,76 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { deriveAsyncState } from "../../src/application/view-models/async-state.js";
+import { AsyncSurface } from "../../src/presentation/components/async-surface.jsx";
+import { createFailure } from "../../src/contracts/errors.js";
+
+describe("async UI state matrix", () => {
+  it.each([
+    [{ isInitialLoading: true }, "initial-loading"],
+    [{ data: [{ id: "1" }] }, "success"],
+    [{ data: [] }, "empty"],
+    [
+      { failure: createFailure("SERVER_FAILURE", "LIST", 0) },
+      "terminal-error",
+    ],
+  ])("derives base state %#", (signals, expected) => {
+    expect(deriveAsyncState(signals).base).toBe(expected);
+  });
+
+  it.each([
+    [{ data: ["value"], isFetching: true }, "refreshing"],
+    [{ data: ["value"], isStale: true, isDegraded: true }, "stale-degraded"],
+    [{ data: ["value"], isMutationPending: true }, "mutation-pending"],
+    [{ data: ["value"], hasMutationConflict: true }, "mutation-conflict"],
+  ])("derives overlay state %#", (signals, indicator) => {
+    expect(deriveAsyncState(signals).indicator).toBe(indicator);
+  });
+
+  it("uses deterministic overlay priority for crossed states", () => {
+    const state = deriveAsyncState({
+      data: ["value"],
+      isFetching: true,
+      isMutationPending: true,
+      hasMutationConflict: true,
+    });
+    expect(state.indicator).toBe("mutation-conflict");
+    expect(state.overlay).toMatchObject({
+      refreshing: true,
+      mutationPending: true,
+      mutationConflict: true,
+    });
+  });
+
+  it("keeps content visible while a non-blocking refresh runs", () => {
+    const state = deriveAsyncState({ data: ["value"], isFetching: true });
+    render(<AsyncSurface state={state}>existing content</AsyncSurface>);
+
+    expect(screen.getByText("existing content")).toBeVisible();
+    expect(screen.getByRole("status")).toHaveTextContent("refreshing");
+  });
+
+  it("renders only safe error vocabulary", () => {
+    const failure = createFailure("SERVER_FAILURE", "LIST", 0, {
+      code: "SERVER_FAILURE",
+    });
+    const state = deriveAsyncState({ failure });
+    render(<AsyncSurface state={state} />);
+
+    expect(screen.getByRole("alert")).toHaveTextContent(failure.userMessageKey);
+    expect(screen.getByRole("button")).toHaveTextContent("retry");
+    expect(screen.getByRole("alert")).not.toHaveTextContent("stack");
+  });
+
+  it("does not retain a terminal error after usable data is restored", () => {
+    const failed = deriveAsyncState({
+      failure: createFailure("SERVER_FAILURE", "LIST", 0),
+    });
+    const recovered = deriveAsyncState({ data: ["value"] });
+    expect(failed.base).toBe("terminal-error");
+    expect(recovered.base).toBe("success");
+    expect(recovered.failure).toBeUndefined();
+  });
+});

tests/component/router.test.jsx

@@ -0,0 +1,24 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
+import { AppRouter } from "../../src/presentation/routes/app-router.jsx";
+
+describe("application router", () => {
+  it("renders not-found without making an API request", () => {
+    window.history.pushState({}, "", "/missing");
+    render(<AppRouter authSession={createAnonymousSessionAdapter()} />);
+    expect(
+      screen.getByRole("heading", { name: "페이지를 찾을 수 없습니다." }),
+    ).toBeVisible();
+  });
+
+  it("shows session-required UX without claiming authorization", () => {
+    window.history.pushState({}, "", "/sample/resources");
+    render(<AppRouter authSession={createAnonymousSessionAdapter()} />);
+    expect(screen.getByRole("heading", { name: "세션이 필요합니다." })).toBeVisible();
+    expect(screen.getByRole("button", { name: "로그인" })).toBeVisible();
+  });
+});

tests/integration/http-client.test.js

@@ -46,7 +46,7 @@ describe("shared HTTP client", () => {
       client.execute("LIST_SAMPLE_RESOURCES", { routeId: "SAMPLE_RESOURCE_LIST" }),
     ).resolves.toMatchObject({
       ok: true,
-      value: [{ id: "resource-1" }],
+      value: [{ id: "resource-1", displayName: "Example" }],
       meta: { requestId: "request-1" },
     });
     expect(attempts).toBe(3);
@@ -99,4 +99,30 @@ describe("shared HTTP client", () => {
       error: { kind: "SCHEMA_MISMATCH" },
     });
   });
+
+  it("guards mapper exceptions as UNKNOWN_FAILURE", async () => {
+    server.use(
+      http.get("https://api.test/api/sample/resources", () =>
+        HttpResponse.json({
+          success: true,
+          data: [{ id: "resource-1", name: "Example" }],
+          meta: { requestId: "request-1", traceId: "trace-1" },
+        }),
+      ),
+    );
+    const client = createHttpClient({
+      baseUrl: "https://api.test",
+      clock,
+      mapPayload: () => {
+        throw new Error("raw mapper detail");
+      },
+    });
+
+    const result = await client.execute("LIST_SAMPLE_RESOURCES");
+    expect(result).toMatchObject({
+      ok: false,
+      error: { kind: "UNKNOWN_FAILURE" },
+    });
+    expect(JSON.stringify(result)).not.toContain("raw mapper detail");
+  });
 });

tests/unit/boundary-mapper.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  mapOperationPayload,
+  mapResourceDto,
+} from "../../src/adapters/http/resource-mapper.js";
+import { toResourceViewModel } from "../../src/application/view-models/resource-view-model.js";
+
+describe("DTO to model to view-model mapping", () => {
+  it("contains raw DTO names at the HTTP boundary", () => {
+    const model = mapResourceDto({
+      id: "resource-1",
+      name: "Example",
+      createdAt: "2026-07-25T00:00:00.000Z",
+      backendOnly: "not propagated",
+    });
+
+    expect(model).toEqual({
+      id: "resource-1",
+      displayName: "Example",
+      createdAt: "2026-07-25T00:00:00.000Z",
+    });
+    expect(model).not.toHaveProperty("name");
+    expect(model).not.toHaveProperty("backendOnly");
+  });
+
+  it("maps operation payloads and rejects missing mappers", () => {
+    expect(
+      mapOperationPayload("LIST_SAMPLE_RESOURCES", [
+        { id: "resource-1", name: "Example" },
+      ]),
+    ).toEqual([
+      { id: "resource-1", displayName: "Example", createdAt: null },
+    ]);
+    expect(() => mapOperationPayload("UNKNOWN", {})).toThrow(
+      "No boundary mapper registered",
+    );
+  });
+
+  it("projects an application-owned render-ready shape", () => {
+    const model = mapResourceDto({
+      id: "resource-1",
+      name: "Example",
+      createdAt: null,
+    });
+    expect(toResourceViewModel(model)).toEqual({
+      resourceId: "resource-1",
+      title: "Example",
+      createdAtLabel: null,
+    });
+  });
+});

tests/unit/navigation-policy.test.js

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createRedirectLoopGuard,
+  decideRouteAccess,
+} from "../../src/presentation/routes/navigation-policy.js";
+import { ROUTE_REGISTRY } from "../../src/contracts/routes.js";
+
+describe("route registry", () => {
+  it("matches the stable registry snapshot", () => {
+    expect(ROUTE_REGISTRY).toMatchInlineSnapshot(`
+      {
+        "APP_HOME": {
+          "access": "public",
+          "chunkId": "route-home",
+          "errorSurface": "route-boundary",
+          "loadingSurface": "app-shell",
+          "paramsSchema": null,
+          "path": "/",
+          "routeId": "APP_HOME",
+          "searchSchema": null,
+        },
+        "NOT_FOUND": {
+          "access": "public",
+          "chunkId": "route-not-found",
+          "errorSurface": "not-found",
+          "loadingSurface": "none",
+          "paramsSchema": null,
+          "path": "*",
+          "routeId": "NOT_FOUND",
+          "searchSchema": null,
+        },
+        "SAMPLE_RESOURCE_LIST": {
+          "access": "integration-defined",
+          "chunkId": "route-sample-resources",
+          "errorSurface": "feature-boundary",
+          "loadingSurface": "sample-resource-list",
+          "paramsSchema": null,
+          "path": "/sample/resources",
+          "routeId": "SAMPLE_RESOURCE_LIST",
+          "searchSchema": "SampleResourceListQuery",
+        },
+      }
+    `);
+  });
+
+  it("treats client access as a UX hint, not authorization", () => {
+    expect(decideRouteAccess("APP_HOME", "unauthenticated")).toEqual({
+      allowed: true,
+      action: "none",
+    });
+    expect(decideRouteAccess("SAMPLE_RESOURCE_LIST", "unauthenticated")).toEqual({
+      allowed: false,
+      action: "show-sign-in",
+    });
+    expect(decideRouteAccess("SAMPLE_RESOURCE_LIST", "authenticated")).toEqual({
+      allowed: true,
+      action: "none",
+    });
+  });
+
+  it("allows at most one automatic redirect per source-target pair", () => {
+    const guard = createRedirectLoopGuard();
+    expect(guard.allow("/private", "/signin")).toBe(true);
+    expect(guard.allow("/private", "/signin")).toBe(false);
+    expect(guard.allow("/signin", "/signin")).toBe(false);
+  });
+});