From d549ceb330b1c1281f57e041367b93e9dca40e17 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:31:30 +0900 Subject: [PATCH] =?UTF-8?q?perf(examples):=20=ED=94=8C=EB=9E=AB=ED=8F=BC?= =?UTF-8?q?=20=EA=B5=AC=EC=84=B1=20=ED=99=94=EB=A9=B4=EC=9D=B4=20=EC=A0=9C?= =?UTF-8?q?=EB=AA=A9=EC=9D=84=20=EB=A8=BC=EC=A0=80=20=EA=B7=B8=EB=A6=AC?= =?UTF-8?q?=EA=B3=A0=20=EC=8B=A4=ED=96=89=EB=B6=80=20=ED=91=9C=EB=A7=8C=20?= =?UTF-8?q?=EA=B8=B0=EB=8B=A4=EB=A6=B0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 lab 게이트 FE-GATE-026은 내비게이션 클릭부터 플랫폼 구성 화면 제목이 보일 때까지를 잰다. 298201f 뒤로 이 route module은 그리기 전에 loadInstalledFeatureRuntimeRegistries()를 기다린다. 그 함수는 설치된 모든 기능의 실행부를 dynamic import한다. 그래서 클릭 뒤 요청 묶음이 두 번이 되고 상호작용 중앙값이 117 -> 227 ms가 됐다(예산 200 ms). 고른 방법 (영역 문서 최소 개선 방향 (c)) - route module은 페이지 컴포넌트를 바로 돌려준다(default export). 제목·릴리스·라우트 표·서버 상태·능력·기능 상태처럼 선언과 런타임 snapshot으로 아는 것은 바로 그린다. - 실행부가 있어야 아는 것(HTTP 오퍼레이션 수, 픽스처 수, 오퍼레이션 표, 검증 생략 표)만 Suspense 경계 두 곳 뒤에서 use()로 채운다. - 실행부 조립 모듈도 dynamic import로 바꿔 제목이 기다리는 페이지 청크에서 뺐다(첫 요청 묶음 8,095 -> 6,919 B). - 기능 사이 중복은 여전히 이 화면에서 throw하고 route 경계로 간다. 실패한 load는 캐시에서 지워 다음 방문 때 다시 시도한다. - 버린 대안: 예산 300 ms(회귀를 숨김), lab 대상 라우트 변경(같은 이유), hover 프리페치(키보드·직접 진입에 효과 작음). 위험·한계 - 화면 안에 "기능 실행부를 불러오고 있습니다." 로딩 상태가 생긴다. - PlatformOverviewPage의 contracts prop이 Promise가 됐다. 이 컴포넌트를 직접 쓰는 다운스트림 테스트는 Promise를 넘기고 act로 기다려야 한다. - 첫 요청 묶음은 d99301b보다 여전히 크다(6,919 vs 5,019 B). 그 사이 페이지가 커졌고 badge·card가 공유 청크로 갈라졌다. 그래서 d99301b보다 약 30 ms 느리다. - 실제 CI 러너에서는 재지 않았다. 검증 - 새 component 테스트(실행부 load가 끝나지 않아도 제목·라우트 표가 보이고 오퍼레이션 표만 로딩): 수정 전 실패, 수정 뒤 통과. - test:component 통과. check:types, check:architecture, 바뀐 파일 eslint 통과. - lab A/B(heavy lock, 같은 호스트, d99301b worktree와 번갈아, test:performance --runs=5, CHOKIDAR_USEPOLLING=1, 이 브랜치 끝 기준): 부하 19 -> 11에서 d99301b 107·106 ms PASS, 이 변경 136·134 ms PASS. LCP 1,968·1,984 ms, CLS 0. (같은 날 다른 묶음 한 번은 두 쪽 모두 홈 링크를 30초 안에 찾지 못해 측정 전에 끝났다. 포트를 바꿔 다시 잰 것이 위 결과다.) - 요청 추적: 클릭 뒤 제목은 첫 묶음(페이지 청크 4개) 뒤에 나오고, feature-runtime·reference-schemas는 제목 뒤에 받는다. Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-01 --- .../frontend-application-foundation.md | 3 +- .../installed-feature-runtime-registries.ts | 6 +- .../examples/platform-overview-page.tsx | 152 ++++++++++++------ src/presentation/routes/route-runtime.tsx | 7 +- .../starter-platform-overview-page.test.tsx | 128 +++++++-------- .../starter-platform-overview-route.test.tsx | 54 +++++++ 6 files changed, 233 insertions(+), 117 deletions(-) create mode 100644 tests/component/starter-platform-overview-route.test.tsx diff --git a/docs/architecture/frontend-application-foundation.md b/docs/architecture/frontend-application-foundation.md index d9fe275e..d722cb20 100644 --- a/docs/architecture/frontend-application-foundation.md +++ b/docs/architecture/frontend-application-foundation.md @@ -119,7 +119,8 @@ Central installed catalogs are aggregation points only: registry the HTTP executor resolves against, filled as features load - `installed-feature-runtime-registries.ts`: loads every runtime half and composes the V2 API registries and contract contributions; the platform - overview route calls it before it renders, the boot never does + overview page calls it after it draws its title (1103/15-01), the boot + never does - `loaded-feature-runtimes.ts`: the same registries as module constants (top- level await) for Node scripts, tests and registry governance; nothing under `src` may import it (`boot-does-not-load-every-feature-runtime`) diff --git a/src/features/installed-feature-runtime-registries.ts b/src/features/installed-feature-runtime-registries.ts index 1404c147..7c02ea78 100644 --- a/src/features/installed-feature-runtime-registries.ts +++ b/src/features/installed-feature-runtime-registries.ts @@ -22,8 +22,10 @@ import { INSTALLED_PRODUCT_FEATURE_MODULES } from "./installed-product-manifest. * * The app boot never calls this: at runtime the composition root loads one * feature at a time when its routes are entered (`installed-feature-adapters.ts`). - * The platform overview route calls it before it renders, and Node scripts and - * tests read the same result through `loaded-feature-runtimes.ts`. + * The platform overview page calls it after it draws its title (1103/15-01: + * awaiting it in the route module added a request round to entering the + * route), and Node scripts and tests read the same result through + * `loaded-feature-runtimes.ts`. */ export async function loadInstalledFeatureRuntimeRegistries() { const runtimes = Object.freeze( diff --git a/src/presentation/examples/platform-overview-page.tsx b/src/presentation/examples/platform-overview-page.tsx index 86d5250b..1cf80f90 100644 --- a/src/presentation/examples/platform-overview-page.tsx +++ b/src/presentation/examples/platform-overview-page.tsx @@ -1,4 +1,4 @@ -import { type ComponentType, useEffect, useState } from "react"; +import { Suspense, use, useEffect, useState } from "react"; import { HTTP_EXECUTION_CEILINGS, @@ -11,7 +11,6 @@ import { import { SERVER_STATE_PROFILES } from "../../contracts/server-state.ts"; import { EXPECTED_CONTRACT_SET_PACKAGES } from "../../features/installed-contract-contributions.ts"; import { ROUTE_REGISTRY } from "../../features/installed-feature-contracts.ts"; -import { loadInstalledFeatureRuntimeRegistries } from "../../features/installed-feature-runtime-registries.ts"; import type { RuntimeCapabilityId, RuntimeCapabilityStatus, @@ -21,6 +20,7 @@ import { Card, DataTable, EmptySurface, + LoadingSurface, PageHeader, type DataTableColumn, } from "../design-system/index.ts"; @@ -309,14 +309,71 @@ function buildOperationRows( ); } +const CONTRACTS_LOADING = "기능 실행부를 불러오고 있습니다."; + +/** The summary counts that only the features' runtime halves know. */ +function ContractMetrics({ + contracts, +}: Readonly<{ contracts: Promise }>) { + const composed = use(contracts); + const fixtureContributions = composed.contributions.filter( + (contribution) => contribution.source.kind === "TEMPLATE_FIXTURE", + ).length; + return ( + <> + + + + ); +} + +function ContractTables({ + contracts, +}: Readonly<{ contracts: Promise }>) { + const composed = use(contracts); + return ( + <> + row.operationId} + empty={ + + } + /> + {/* 1101/07-03. Drawn only when a contract skips validation by name. */} + `${row.contractId}.${row.validator}`} + empty={null} + /> + + ); +} + /** * 15-01. The page lists every installed HTTP operation, which lives in the - * features' runtime halves. Its route loads them all before it renders - * (`loadPlatformOverviewPage`); the boot never does. + * features' runtime halves; the boot never loads them. 1103/15-01: only the + * parts that read them wait (`contracts`). The title and everything the + * declarations know draw at once, so entering the route costs the page chunk + * alone, not a second request round for every feature's runtime. */ export function PlatformOverviewPage({ contracts, -}: Readonly<{ contracts: ComposedContractContributions }>) { +}: Readonly<{ contracts: Promise }>) { const runtime = useApplicationRuntime(); const [release, setRelease] = useState< Awaited> | "failed" | null @@ -338,16 +395,11 @@ export function PlatformOverviewPage({ }, [runtime]); const routes = Object.values(ROUTE_REGISTRY); - const operations = buildOperationRows(contracts); const capabilities = runtime.getCapabilitySnapshot(); const features = runtime.getFeatureSnapshot(); const activeCapabilityCount = capabilities.filter( (status) => status.active > 0, ).length; - const fixtureContributions = - contracts.contributions.filter( - (contribution) => contribution.source.kind === "TEMPLATE_FIXTURE", - ).length; return ( // 08-07. Example copy is Korean in every locale (outside the catalog). @@ -413,12 +465,19 @@ export function PlatformOverviewPage({
- - + + + + + } + > + + - row.operationId} - empty={ - - } - /> - {/* 1101/07-03. Drawn only when a contract skips validation by name. */} - `${row.contractId}.${row.validator}`} - empty={null} - /> + }> + +
-> { - const registries = await loadInstalledFeatureRuntimeRegistries(); - const contracts = registries.composedContractContributions; - return Object.freeze({ - default: function InstalledPlatformOverviewPage() { - return ; - }, - }); +let installedContracts: Promise | undefined; + +/** + * One load shared by both waiting parts and by later visits. The composer is + * imported here too, so its code is not in the page chunk the title waits + * for. A duplicate across features rejects here and reaches the route + * boundary, as it did when the route awaited it; a failed load is dropped so + * the next visit retries. + */ +function loadInstalledContracts(): Promise { + if (installedContracts === undefined) { + const loading = import( + "../../features/installed-feature-runtime-registries.ts" + ) + .then((module) => module.loadInstalledFeatureRuntimeRegistries()) + .then((registries) => registries.composedContractContributions); + loading.catch(() => { + if (installedContracts === loading) installedContracts = undefined; + }); + installedContracts = loading; + } + return installedContracts; +} + +/** The route module: the page bound to the installed registries. */ +export default function InstalledPlatformOverviewPage() { + return ; } diff --git a/src/presentation/routes/route-runtime.tsx b/src/presentation/routes/route-runtime.tsx index 69dfb550..8ae93a40 100644 --- a/src/presentation/routes/route-runtime.tsx +++ b/src/presentation/routes/route-runtime.tsx @@ -24,10 +24,9 @@ function runtime( export const PLATFORM_ROUTE_RUNTIME = { APP_HOME: runtime("APP_HOME", () => import("../pages/home-page.tsx")), - EXAMPLES_PLATFORM: runtime("EXAMPLES_PLATFORM", () => - import("../examples/platform-overview-page.tsx").then((module) => - module.loadPlatformOverviewPage(), - ), + EXAMPLES_PLATFORM: runtime( + "EXAMPLES_PLATFORM", + () => import("../examples/platform-overview-page.tsx"), ), EXAMPLES_UI: runtime( "EXAMPLES_UI", diff --git a/tests/component/starter-platform-overview-page.test.tsx b/tests/component/starter-platform-overview-page.test.tsx index 1c043b16..3484238c 100644 --- a/tests/component/starter-platform-overview-page.test.tsx +++ b/tests/component/starter-platform-overview-page.test.tsx @@ -1,9 +1,12 @@ // @vitest-environment jsdom -import { render, screen, waitFor, within } from "@testing-library/react"; +import { act, render, screen, waitFor, within } from "@testing-library/react"; import { describe, expect, it } from "vitest"; -import { composeContractContributions } from "../../src/contracts/external-contract-runtime.ts"; +import { + composeContractContributions, + type ComposedContractContributions, +} from "../../src/contracts/external-contract-runtime.ts"; import { unvalidatedPayload } from "../../src/contracts/unvalidated-payload.ts"; import { SERVER_STATE_PROFILES } from "../../src/contracts/server-state.ts"; import { COMPOSED_CONTRACT_CONTRIBUTIONS } from "../../src/features/loaded-feature-runtimes.ts"; @@ -24,14 +27,31 @@ import { createRuntimeCapabilitiesStub } from "../helpers/runtime-capabilities-s * template that removes its sample feature still satisfies this suite. */ -function renderPage() { - return render( - - - - - , - ); +/** + * 1103/15-01. The contract tables wait for the features' runtime halves + * behind their own Suspense boundary; `act` lets the given promise settle. + */ +async function renderPage( + options: Readonly<{ + application?: ReturnType; + contracts?: ComposedContractContributions; + }> = {}, +) { + await act(async () => { + render( + + + + + , + ); + }); } function tableByCaption(caption: string): HTMLElement { @@ -48,8 +68,8 @@ function metricByLabel(scope: HTMLElement, label: string): HTMLElement { } describe("platform overview page", () => { - it("renders one route row per installed route registry entry", () => { - renderPage(); + it("renders one route row per installed route registry entry", async () => { + await renderPage(); const table = tableByCaption("설치된 라우트 목록"); const dataRows = within(table).getAllByRole("row").slice(1); @@ -62,11 +82,11 @@ describe("platform overview page", () => { } }); - it("renders one operation row per installed HTTP contract", () => { + it("renders one operation row per installed HTTP contract", async () => { const operationIds = [ ...COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.keys(), ]; - renderPage(); + await renderPage(); if (operationIds.length === 0) { expect( @@ -87,7 +107,7 @@ describe("platform overview page", () => { }); // 1101/07-03. A skipped validation is shown, not just composed. - it("lists the operations that skip runtime validation, with the reason", () => { + it("lists the operations that skip runtime validation, with the reason", async () => { const [listRow, ...rest] = TEST_CONTRACT_CONTRIBUTION.http; const contracts = composeContractContributions([ Object.freeze({ @@ -107,13 +127,7 @@ describe("platform overview page", () => { ]), }), ]); - render( - - - - - , - ); + await renderPage({ contracts }); const table = tableByCaption("런타임 검증을 생략한 계약"); const [row, ...others] = within(table).getAllByRole("row").slice(1); @@ -122,16 +136,16 @@ describe("platform overview page", () => { expect(within(row!).getByText("typed by the package")).toBeVisible(); }); - it("shows no skipped-validation list when every operation validates", () => { - renderPage(); + it("shows no skipped-validation list when every operation validates", async () => { + await renderPage(); expect( screen.queryByRole("table", { name: "런타임 검증을 생략한 계약" }), ).toBeNull(); }); - it("renders every fixed server-state profile with its own budget", () => { - renderPage(); + it("renders every fixed server-state profile with its own budget", async () => { + await renderPage(); const table = tableByCaption("서버 상태 프로파일"); for (const profile of Object.values(SERVER_STATE_PROFILES)) { @@ -142,8 +156,8 @@ describe("platform overview page", () => { ); }); - it("labels a capability that was never selected as unselected", () => { - renderPage(); + it("labels a capability that was never selected as unselected", async () => { + await renderPage(); const region = screen.getByRole("region", { name: "선택적 런타임 능력" }); @@ -151,21 +165,15 @@ describe("platform overview page", () => { expect(within(region).queryByText("운영자가 비활성화함")).toBeNull(); }); - it("separates an operator disable from a capability that was never selected", () => { - render( - - - - - , - ); + it("separates an operator disable from a capability that was never selected", async () => { + await renderPage({ + application: createTestApplication({ + runtimeCapabilities: createRuntimeCapabilitiesStub({ + SERVICE_WORKER: { selected: 1, active: 0, override: "DISABLED" }, + OFFLINE_COMMANDS: { selected: 1, active: 1 }, + }), + }), + }); const region = screen.getByRole("region", { name: "선택적 런타임 능력" }); @@ -174,11 +182,11 @@ describe("platform overview page", () => { expect(within(region).getAllByText("미선택")).toHaveLength(2); }); - it("counts installed contract packages separately from template fixtures", () => { + it("counts installed contract packages separately from template fixtures", async () => { const fixtures = COMPOSED_CONTRACT_CONTRIBUTIONS.contributions.filter( (contribution) => contribution.source.kind === "TEMPLATE_FIXTURE", ).length; - renderPage(); + await renderPage(); const summary = screen.getByRole("region", { name: "설치 요약" }); const packages = metricByLabel(summary, "외부 계약 패키지"); @@ -199,7 +207,7 @@ describe("platform overview page", () => { }); it("renders the verified release identity once the runtime resolves it", async () => { - renderPage(); + await renderPage(); const region = screen.getByRole("region", { name: "릴리스 신원" }); await waitFor(() => @@ -213,24 +221,18 @@ describe("platform overview page", () => { }); it("stops the release metrics from loading forever", async () => { - render( - { - throw new Error("manifest unavailable"); - }, - refresh: async () => { - throw new Error("manifest unavailable"); - }, + await renderPage({ + application: createTestApplication({ + releaseInfo: { + getCurrent: async () => { + throw new Error("manifest unavailable"); }, - })} - > - - - - , - ); + refresh: async () => { + throw new Error("manifest unavailable"); + }, + }, + }), + }); await waitFor(() => expect( screen.getByText("런타임 정보를 확인하지 못했습니다."), diff --git a/tests/component/starter-platform-overview-route.test.tsx b/tests/component/starter-platform-overview-route.test.tsx new file mode 100644 index 00000000..a6fad087 --- /dev/null +++ b/tests/component/starter-platform-overview-route.test.tsx @@ -0,0 +1,54 @@ +// @vitest-environment jsdom + +import { render, screen, within } from "@testing-library/react"; +import { Suspense } from "react"; +import { describe, expect, it, vi } from "vitest"; + +import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts"; +import { LocaleProvider } from "../../src/presentation/i18n/index.ts"; +import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx"; +import { PLATFORM_ROUTE_RUNTIME } from "../../src/presentation/routes/route-runtime.tsx"; +import { createTestApplication } from "../helpers/create-test-application.ts"; + +// The feature runtimes never arrive: the route must not wait for them. +vi.mock("../../src/features/installed-feature-runtime-registries.ts", () => ({ + loadInstalledFeatureRuntimeRegistries: () => new Promise(() => {}), +})); + +/** + * 1103/15-01. The lab gate (FE-GATE-026) times this route from the click to + * its heading. Its route module used to await every installed feature's + * runtime half first, which added a second request round to the click. + */ +describe("platform overview route module", () => { + it("draws the title and the declared routes before the feature runtimes load", async () => { + const Page = PLATFORM_ROUTE_RUNTIME.EXAMPLES_PLATFORM.Component; + render( + + + route chunk

}> + +
+
+
, + ); + + expect( + await screen.findByRole("heading", { level: 1, name: "플랫폼 구성" }), + ).toBeVisible(); + const routes = screen.getByRole("table", { name: "설치된 라우트 목록" }); + expect(within(routes).getAllByRole("row").slice(1)).toHaveLength( + Object.keys(ROUTE_REGISTRY).length, + ); + // Only the part read from the runtime halves waits. + const contracts = screen.getByRole("region", { + name: "계약과 HTTP 오퍼레이션", + }); + expect( + within(contracts).getByLabelText("기능 실행부를 불러오고 있습니다."), + ).toBeVisible(); + expect( + screen.queryByRole("table", { name: "설치된 HTTP 오퍼레이션" }), + ).toBeNull(); + }); +});