리팩토링: 웹 모듈 라우팅/레지스트리 구조 분리

Author: SOIV

apps/web/src/components/AppShell.tsx

@@ -3,7 +3,7 @@ import { useTranslation } from 'react-i18next';
 import "../styles/shell.css";
 
 import { apiFetch } from "../lib/apiFetch";
-import type { ModuleSubRoute } from "../moduleConfig";
+import type { ModuleSubRoute } from "../moduleRegistry";
 
 // 코어 라우트 + 설치된 모듈 이름도 RouteKey에 포함 (가계부: "ledger" 등)
 export type CoreRouteKey = "login" | "forgot-password" | "home" | "marketplace" | "admin" | "change-password";

apps/web/src/main.tsx

@@ -1,4 +1,4 @@
-import { type FormEvent, useEffect, useMemo, useState } from "react";
+import { Suspense, type FormEvent, useEffect, useMemo, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { useTranslation } from "react-i18next";
 
@@ -23,33 +23,18 @@ import { MarketplaceView } from "./views/MarketplaceView";
 import { ChangePasswordView } from "./views/ChangePasswordView";
 import { ForgotPasswordView } from "./views/ForgotPasswordView";
 import { SetupWizardView } from "./views/SetupWizardView";
-import { LedgerView } from "../../../modules/ledger/frontend/LedgerView";
-import { SubscriptionView } from "../../../modules/subscription/frontend/SubscriptionView";
-import { MODULE_SUB_NAV } from "./moduleConfig";
-
-// ─── Helpers ──────────────────────────────────────────────────
-
-// 코어 라우트 목록 (앱 shell 없이 전체 화면으로 렌더되는 것 제외)
-const CORE_ROUTES = ["login", "forgot-password", "home", "marketplace", "admin", "change-password"] as const;
-// 모듈 라우트 — module.json name 기준 (서버 레지스트리와 일치)
-const MODULE_ROUTES: string[] = ["ledger", "subscription"];
-
-/** 해시에서 베이스 라우트만 추출 ("ledger/import" → "ledger") */
-function getRouteFromHash(rawHash: string): RouteKey {
-  const hash = rawHash.replace("#", "");
-  const base = hash.split("/")[0] ?? hash;
-  if (base === "settings") return "home";
-  if ((CORE_ROUTES as readonly string[]).includes(base)) return base as RouteKey;
-  if (MODULE_ROUTES.includes(base)) return base as RouteKey;
-  return "login";
-}
-
-/** 해시에서 서브 라우트만 추출 ("ledger/import" → "import", "ledger" → "") */
-function getSubRouteFromHash(rawHash: string): string {
-  const hash = rawHash.replace("#", "");
-  const parts = hash.split("/");
-  return parts.length > 1 ? parts.slice(1).join("/") : "";
-}
+import {
+  MODULE_SUB_NAV,
+  getModuleView,
+  preloadModuleViews,
+  registerModuleLocales,
+} from "./moduleRegistry";
+import {
+  canStoreRedirectTarget,
+  getDeepLinkTarget,
+  getRouteFromHash,
+  getSubRouteFromHash,
+} from "./routeConfig";
 
 // ─── Theme ────────────────────────────────────────────────────
 type ThemeSetting = "light" | "dark" | "system";
@@ -64,6 +49,23 @@ function applyTheme(setting: ThemeSetting) {
   try { localStorage.setItem("fs_theme", setting); } catch { /* ignore */ }
 }
 
+function runWhenBrowserIdle(task: () => void): () => void {
+  // requestIdleCallback 지원 브라우저에서는 유휴 시간에 실행하고,
+  // 미지원 브라우저에서는 짧은 setTimeout으로 동작을 에뮬레이션한다.
+  const idleWindow = window as Window & {
+    requestIdleCallback?: (callback: () => void) => number;
+    cancelIdleCallback?: (id: number) => void;
+  };
+
+  if (idleWindow.requestIdleCallback) {
+    const idleId = idleWindow.requestIdleCallback(task);
+    return () => idleWindow.cancelIdleCallback?.(idleId);
+  }
+
+  const timeoutId = window.setTimeout(task, 120);
+  return () => window.clearTimeout(timeoutId);
+}
+
 function loadTheme(): ThemeSetting {
   try {
     const saved = localStorage.getItem("fs_theme");
@@ -74,6 +76,9 @@ function loadTheme(): ThemeSetting {
 
 // 초기 테마 적용 (React 렌더 전에 FOUC 방지)
 applyTheme(loadTheme());
+// 모듈 i18n 번역 리소스를 앱 부트 시점에 선등록해
+// 모듈 첫 진입 시 영어 -> 한국어로 늦게 바뀌는 깜빡임을 줄인다.
+registerModuleLocales();
 
 // ─── Storage Keys ─────────────────────────────────────────────
 const SS = {
@@ -91,13 +96,6 @@ const LS = {
   startupRoute:    "fs_startup_route",
 } as const;
 
-// 딥 링크: 비인증 상태에서 진입한 app route 반환 (모듈 라우트 포함)
-function getDeepLinkTarget(): RouteKey | null {
-  const hash = window.location.hash.replace("#", "");
-  const appRoutes: string[] = ["home", "marketplace", "admin", ...MODULE_ROUTES];
-  return appRoutes.includes(hash) ? (hash as RouteKey) : null;
-}
-
 // 개인화: 로그인 후 첫 화면 설정
 type StartupRoute = "home" | "marketplace";
 
@@ -155,7 +153,7 @@ function App() {
   );
   // 딥 링크: 비인증 상태에서 진입한 app route (로그인 후 복귀)
   const [redirectAfterLogin, setRedirectAfterLogin] = useState<RouteKey | null>(
-    () => (sessionStorage.getItem(SS.auth) === "true" ? null : getDeepLinkTarget()),
+    () => (sessionStorage.getItem(SS.auth) === "true" ? null : getDeepLinkTarget(window.location.hash)),
   );
   // 첫 방문 온보딩 배너
   const [isFirstVisit, setIsFirstVisit] = useState(false);
@@ -184,8 +182,7 @@ function App() {
       setRoute(next);
       setSubRoute(nextSub);
       // 비인증 상태에서 app route로 hash 변경 시 redirect 대상 갱신
-      const appRoutes: RouteKey[] = ["home", "marketplace", "admin"];
-      if (sessionStorage.getItem(SS.auth) !== "true" && (appRoutes as string[]).includes(next)) {
+      if (sessionStorage.getItem(SS.auth) !== "true" && canStoreRedirectTarget(next)) {
         setRedirectAfterLogin(next);
       }
     };
@@ -203,6 +200,14 @@ function App() {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isAuthenticated]);
 
+  // 초기 로그인 이후 idle 타이밍에 모듈 청크를 미리 받아 첫 진입 체감 지연을 줄인다.
+  useEffect(() => {
+    if (!isAuthenticated) return;
+    return runWhenBrowserIdle(() => {
+      void preloadModuleViews();
+    });
+  }, [isAuthenticated]);
+
   // 관리자 PIN 세션 30분 만료
   useEffect(() => {
     if (!isPinVerified || pinVerifiedAt === null) return;
@@ -236,16 +241,37 @@ function App() {
   }, [isAuthenticated, mustChangePassword, pendingOtpEmail, route]);
 
   useEffect(() => {
-    if (window.location.hash !== `#${effectiveRoute}`) {
-      window.location.hash = effectiveRoute;
+    // 인증/비인증 가드로 effectiveRoute가 바뀔 때 해시를 일치시킨다.
+    // 모듈 라우트는 subRoute를 보존해 #ledger/import 같은 주소가 사라지지 않게 처리한다.
+    const shouldKeepSubRoute = getModuleView(effectiveRoute) !== null && subRoute.length > 0;
+    const expectedHash = shouldKeepSubRoute ? `#${effectiveRoute}/${subRoute}` : `#${effectiveRoute}`;
+    if (window.location.hash !== expectedHash) {
+      window.location.hash = expectedHash;
     }
-  }, [effectiveRoute]);
+  }, [effectiveRoute, subRoute]);
 
   const navigate = (nextRoute: RouteKey) => {
     setRoute(nextRoute);
     window.location.hash = nextRoute;
   };
 
+  const ActiveModuleView = getModuleView(effectiveRoute);
+
+  const applyServerLanguagePreference = async (): Promise<void> => {
+    // 로그인 직후 서버 저장 언어를 먼저 반영해
+    // 페이지 진입 후 번역이 뒤늦게 바뀌는 체감을 줄인다.
+    try {
+      const response = await apiFetch("/core/users/me/settings");
+      const json = await response.json() as { success: boolean; data?: { language?: string } };
+      const language = json.data?.language;
+      if (json.success && typeof language === "string" && language.length > 0) {
+        await changeLanguage(language);
+      }
+    } catch {
+      // 언어 설정 로드 실패는 무음 처리
+    }
+  };
+
   // ── 로그인 성공 시 공통 처리 ─────────────────────────────────
   const handleLoginSuccess = (email: string, isAdmin: boolean, isTempPassword: boolean) => {
     setLoginError(null);
@@ -271,19 +297,12 @@ function App() {
       if (localStorage.getItem(LS.firstVisitShown) !== "true") setIsFirstVisit(true);
     } catch { /* ignore */ }
 
-    // 서버에 저장된 언어 설정 로드 (실패해도 무음 처리)
-    apiFetch("/core/users/me/settings")
-      .then((r) => r.json())
-      .then((json: { success: boolean; data?: { language: string } }) => {
-        if (json.success && json.data?.language) {
-          void changeLanguage(json.data.language);
-        }
-      })
-      .catch(() => { /* 언어 설정 로드 실패는 무음 처리 */ });
-
-    const target = redirectAfterLogin ?? startupRoute;
-    setRedirectAfterLogin(null);
-    navigate(target);
+    // 화면 이동 전에 서버 언어 설정을 우선 반영해 en → ko 깜빡임을 줄인다.
+    void applyServerLanguagePreference().finally(() => {
+      const target = redirectAfterLogin ?? startupRoute;
+      setRedirectAfterLogin(null);
+      navigate(target);
+    });
   };
 
   // Auth handlers
@@ -520,8 +539,17 @@ function App() {
           />
         )}
         {/* ── 모듈 뷰 ────────────────────────────────────── */}
-        {effectiveRoute === "ledger" && <LedgerView subRoute={subRoute} />}
-        {effectiveRoute === "subscription" && <SubscriptionView />}
+        {ActiveModuleView && (
+          <Suspense
+            fallback={(
+              <div style={{ minHeight: 240, display: "flex", alignItems: "center", justifyContent: "center" }}>
+                <span className="setup-spinner" style={{ width: 24, height: 24, borderWidth: 3 }} />
+              </div>
+            )}
+          >
+            <ActiveModuleView subRoute={subRoute} />
+          </Suspense>
+        )}
         {isSettingsOpen && (
           <SettingsView
             theme={theme}

apps/web/src/moduleConfig.ts

@@ -0,0 +1,104 @@
+import { lazy, type ComponentType, type LazyExoticComponent } from "react";
+import { registerModuleLocale } from "./i18n/registerModuleLocale";
+import ledgerKoLocale from "../../../modules/ledger/frontend/locales/ko.json";
+import ledgerEnLocale from "../../../modules/ledger/frontend/locales/en.json";
+import subscriptionKoLocale from "../../../modules/subscription/frontend/locales/ko.json";
+import subscriptionEnLocale from "../../../modules/subscription/frontend/locales/en.json";
+
+// 모듈 서브 네비게이션 항목 정의.
+// key: "" 이면 모듈 기본 화면, "import" 같은 값이면 #module/import 형태로 이동한다.
+export interface ModuleSubRoute {
+  key: string;
+  label: string;
+  icon?: string;
+}
+
+// AppShell -> 모듈 화면으로 전달되는 공통 props.
+export interface ModuleViewProps {
+  subRoute: string;
+}
+
+type ModuleViewComponent = ComponentType<ModuleViewProps>;
+
+interface ModuleDefinition {
+  // lazy 컴포넌트와 별도로 보관하는 원본 loader.
+  // 첫 진입 전 preload 시 이 함수를 사용한다.
+  load: () => Promise<unknown>;
+  component: LazyExoticComponent<ModuleViewComponent>;
+  subNav: ModuleSubRoute[];
+  locale: {
+    ko: Record<string, unknown>;
+    en: Record<string, unknown>;
+  };
+}
+
+// 동적 import 함수는 lazy 로더와 preload 양쪽에서 재사용한다.
+const loadLedgerModule = () => import("../../../modules/ledger/frontend/LedgerView");
+const loadSubscriptionModule = () => import("../../../modules/subscription/frontend/SubscriptionView");
+
+const LedgerModuleView = lazy(async () => {
+  const module = await loadLedgerModule();
+  const LedgerRouteComponent: ModuleViewComponent = ({ subRoute }) => (
+    <module.LedgerView subRoute={subRoute} />
+  );
+  return { default: LedgerRouteComponent };
+});
+
+const SubscriptionModuleView = lazy(async () => {
+  const module = await loadSubscriptionModule();
+  const SubscriptionRouteComponent: ModuleViewComponent = () => <module.SubscriptionView />;
+  return { default: SubscriptionRouteComponent };
+});
+
+export const MODULE_REGISTRY: Record<string, ModuleDefinition> = {
+  ledger: {
+    load: loadLedgerModule,
+    component: LedgerModuleView,
+    subNav: [],
+    locale: {
+      ko: ledgerKoLocale,
+      en: ledgerEnLocale,
+    },
+  },
+  subscription: {
+    load: loadSubscriptionModule,
+    component: SubscriptionModuleView,
+    subNav: [],
+    locale: {
+      ko: subscriptionKoLocale,
+      en: subscriptionEnLocale,
+    },
+  },
+};
+
+// routeConfig에서 모듈 라우트 판단에 사용하는 단일 소스.
+export const MODULE_ROUTES = Object.keys(MODULE_REGISTRY);
+
+// AppShell이 요구하는 "모듈명 -> 서브네비 목록" 형태로 변환한다.
+const moduleSubNav: Record<string, ModuleSubRoute[]> = {};
+for (const [moduleName, definition] of Object.entries(MODULE_REGISTRY)) {
+  moduleSubNav[moduleName] = definition.subNav;
+}
+export const MODULE_SUB_NAV = moduleSubNav;
+
+export function getModuleView(route: string): LazyExoticComponent<ModuleViewComponent> | null {
+  return MODULE_REGISTRY[route]?.component ?? null;
+}
+
+// 앱 부트 시 모듈 번역 리소스를 미리 등록해
+// 첫 렌더에서 en -> ko로 바뀌는 깜빡임을 줄인다.
+export function registerModuleLocales(): void {
+  for (const [moduleName, definition] of Object.entries(MODULE_REGISTRY)) {
+    registerModuleLocale(moduleName, definition.locale.ko, definition.locale.en);
+  }
+}
+
+// 로그인 직후 idle 타이밍에 모듈 청크를 미리 받아서
+// 모듈 첫 진입 시 lazy 로딩 대기 시간을 줄인다.
+export async function preloadModuleViews(routeNames?: string[]): Promise<void> {
+  const targets = routeNames ?? MODULE_ROUTES;
+  const loaders = targets
+    .map((routeName) => MODULE_REGISTRY[routeName]?.load)
+    .filter((loader): loader is () => Promise<unknown> => loader !== undefined);
+  await Promise.all(loaders.map((loader) => loader()));
+}