sh-ui-cli 0.57.0 → 0.58.0

package/src/create/plugins/authJwt.js

@@ -1,3 +1,9 @@
+/**
+ * auth-jwt 플러그인 — Layer 2 부터 arch-aware.
+ *
+ * fs 경로 / import alias 가 arch.paths.api / arch.aliases.api 에서 파생.
+ * FSD 기준 v0.57 까지의 하드코딩과 1:1 일치 (회귀 가드는 smoke).
+ */
 export const authJwtPlugin = {
   name: 'auth-jwt',
   label: '쿠키 기반 JWT 인증 (refresh 자리표시자 포함)',
@@ -26,7 +32,7 @@ export const authJwtPlugin = {
   // refreshSession.ts 는 v1 placeholder — 백엔드 명세 확정 후 본문만 채우면
   // BFF 와 withAuthRetry 가 자동 활용한다.
 
-  files: {
+  files: (arch) => ({
     'proxy.ts': `import { NextRequest, NextResponse } from 'next/server';
 
 const AUTH_ROUTES = ['/sign-in', '/sign-up'];
@@ -57,7 +63,7 @@ export const config = {
 };
 `,
 
-    'src/shared/api/refreshSession.ts': `type RefreshResult =
+    [`${arch.paths.api}/refreshSession.ts`]: `type RefreshResult =
   | { ok: true; accessToken: string; refreshToken: string }
   | { ok: false };
 
@@ -109,7 +115,7 @@ export async function refreshSession(
 }
 `,
 
-    'src/shared/api/withAuthRetry.ts': `import { cookies } from 'next/headers';
+    [`${arch.paths.api}/withAuthRetry.ts`]: `import { cookies } from 'next/headers';
 
 import { ApiError } from './error';
 import { refreshSession } from './refreshSession';
@@ -135,8 +141,8 @@ const COOKIE = {
  * 사용 예 (Server Action):
  *
  *   'use server';
- *   import { serverFetch } from '@/src/shared/api/serverFetch';
- *   import { withAuthRetry } from '@/src/shared/api/withAuthRetry';
+ *   import { serverFetch } from '${arch.aliases.api}/serverFetch';
+ *   import { withAuthRetry } from '${arch.aliases.api}/withAuthRetry';
  *
  *   export async function toggleFavoriteAction(id: number) {
  *     return withAuthRetry(() =>
@@ -171,8 +177,8 @@ import { NextResponse, type NextRequest } from 'next/server';
 import {
   captureApiError,
   logApiError,
-} from '@/src/shared/api/observability';
-import { refreshSession } from '@/src/shared/api/refreshSession';
+} from '${arch.aliases.api}/observability';
+import { refreshSession } from '${arch.aliases.api}/refreshSession';
 
 const API_URL = process.env.API_URL ?? 'http://localhost:8080/api';
 const ACCESS_TOKEN_COOKIE = 'accessToken';
@@ -338,5 +344,5 @@ export const DELETE = (
   ctx: { params: Promise<{ path: string[] }> },
 ) => proxyRequest(req, ctx, 'DELETE');
 `,
-  },
+  }),
 };

package/src/create/plugins/nextIntl.js

@@ -1,3 +1,13 @@
+/**
+ * next-intl 플러그인 — Layer 2 부터 arch-aware.
+ *
+ * 모든 fs 경로 / import alias 가 arch 디스크립터의 논리 키에서 파생된다:
+ *   - i18n 설정 (request/routing/navigation/messages) → arch.paths.config + '/i18n'
+ *   - 내부 import (RootLayout, GlobalProvider) → arch.aliases.layouts / providers
+ *
+ * FSD 에서는 v0.57 까지의 하드코딩과 1:1 일치 (회귀 가드는 smoke 시나리오 3).
+ * flat 에서는 자동으로 lib/config/i18n + components/layouts/RootLayout 로 emit.
+ */
 export const nextIntlPlugin = {
   name: 'next-intl',
   label: 'next-intl (다국어 지원)',
@@ -15,8 +25,8 @@ export const nextIntlPlugin = {
     `import createNextIntlPlugin from 'next-intl/plugin';`,
   ],
 
-  preExport: [
-    `const withNextIntl = createNextIntlPlugin('./src/shared/config/i18n/request.ts');`,
+  preExport: (arch) => [
+    `const withNextIntl = createNextIntlPlugin('./${arch.paths.config}/i18n/request.ts');`,
   ],
 
   wrapExport(expr) {
@@ -36,7 +46,7 @@ export const nextIntlPlugin = {
 
   // ─── 라우트 구조 변환 ───
 
-  transforms: [
+  transforms: (arch) => [
     { type: 'move', from: 'app/page.tsx', to: 'app/[locale]/page.tsx' },
     { type: 'move', from: 'app/error.tsx', to: 'app/[locale]/error.tsx' },
     {
@@ -62,7 +72,7 @@ export const nextIntlPlugin = {
           .filter((line) => /^\s*import\s+['"][^'"]+['"];?\s*$/.test(line))
           .join('\n');
         const body = `import type { Metadata } from 'next';
-import { RootLayout } from '@/src/app/layouts/RootLayout';
+import { RootLayout } from '${arch.aliases.layouts}/RootLayout';
 
 export const metadata: Metadata = {
   title: 'My App',
@@ -84,11 +94,11 @@ export default function Layout({
     },
     {
       type: 'replace',
-      path: 'src/app/layouts/RootLayout.tsx',
+      path: `${arch.paths.layouts}/RootLayout.tsx`,
       content: `import { hasLocale } from 'next-intl';
 import { notFound } from 'next/navigation';
-import { GlobalProvider } from '@/src/app/providers';
-import { routing } from '@/src/shared/config/i18n/routing';
+import { GlobalProvider } from '${arch.aliases.providers}';
+import { routing } from '${arch.aliases.config}/i18n/routing';
 
 export async function RootLayout({
   children,
@@ -117,8 +127,8 @@ export async function RootLayout({
 
   // ─── 독립 파일 ───
 
-  files: {
-    'src/shared/config/i18n/routing.ts': `import { defineRouting } from 'next-intl/routing';
+  files: (arch) => ({
+    [`${arch.paths.config}/i18n/routing.ts`]: `import { defineRouting } from 'next-intl/routing';
 
 export const routing = defineRouting({
   locales: ['ko', 'en'],
@@ -126,7 +136,7 @@ export const routing = defineRouting({
 });
 `,
 
-    'src/shared/config/i18n/request.ts': `import { getRequestConfig } from 'next-intl/server';
+    [`${arch.paths.config}/i18n/request.ts`]: `import { getRequestConfig } from 'next-intl/server';
 import { hasLocale } from 'next-intl';
 import { routing } from './routing';
 
@@ -143,14 +153,14 @@ export default getRequestConfig(async ({ requestLocale }) => {
 });
 `,
 
-    'src/shared/config/i18n/navigation.ts': `import { createNavigation } from 'next-intl/navigation';
+    [`${arch.paths.config}/i18n/navigation.ts`]: `import { createNavigation } from 'next-intl/navigation';
 import { routing } from './routing';
 
 export const { Link, redirect, usePathname, useRouter, getPathname } =
   createNavigation(routing);
 `,
 
-    'src/shared/config/i18n/messages/ko.json': `{
+    [`${arch.paths.config}/i18n/messages/ko.json`]: `{
   "common": {
     "loading": "로딩 중...",
     "error": "오류가 발생했습니다",
@@ -181,7 +191,7 @@ export const { Link, redirect, usePathname, useRouter, getPathname } =
 }
 `,
 
-    'src/shared/config/i18n/messages/en.json': `{
+    [`${arch.paths.config}/i18n/messages/en.json`]: `{
   "common": {
     "loading": "Loading...",
     "error": "An error occurred",
@@ -212,10 +222,8 @@ export const { Link, redirect, usePathname, useRouter, getPathname } =
 }
 `,
 
-    // app/[locale]/layout.tsx 는 transforms 에서 생성된다 (위 move + replace 참고)
-
     'proxy.ts': `import createIntlMiddleware from 'next-intl/middleware';
-import { routing } from '@/src/shared/config/i18n/routing';
+import { routing } from '${arch.aliases.config}/i18n/routing';
 
 const intl = createIntlMiddleware(routing);
 
@@ -225,5 +233,5 @@ export const config = {
   matcher: '/((?!api|trpc|_next|_vercel|monitoring|.*\\\\..*).*)',
 };
 `,
-  },
+  }),
 };

package/src/create/plugins/pluginSchema.js

@@ -31,6 +31,13 @@ const wrapperFn = z
   })
   .optional();
 
+// arch-aware 필드. 정적 값 OR `(arch) => 정적 값` 함수 모두 허용.
+// 플러그인이 arch 디스크립터의 paths/aliases 를 조회해 자기 산출물의 fs 경로/import
+// alias 를 결정할 때 사용. Layer 2 이전엔 모든 플러그인이 정적, Layer 2 이후엔 함수형.
+const archAwareFn = z.custom((val) => typeof val === "function");
+const archAwareRecord = z.union([z.record(filePath, z.string()), archAwareFn]);
+const archAwareArray = z.union([z.array(z.any()), archAwareFn]);
+
 export const PluginSchema = z.object({
   name: z.string().regex(/^[a-z][a-z0-9-]*$/, {
     message: 'Plugin name must be lowercase kebab-case (e.g., "auth-jwt")',
@@ -43,26 +50,35 @@ export const PluginSchema = z.object({
   devDependencies: z.record(z.string(), z.string()).optional(),
 
   imports: z.array(z.string()).optional(),
+  // preExport 은 arch-aware (next.config.ts 의 export 직전 emit 되는 라인들 —
+  // 예: next-intl 의 `createNextIntlPlugin('./src/shared/config/i18n/request.ts')` 같이
+  // arch.paths.config 가 박혀야 하는 경로 포함).
+  preExport: z.union([z.array(z.string()), archAwareFn]).optional(),
   wrapExport: wrapperFn,
 
   envVars: z.array(z.string()).optional(),
   turboEnvVars: z.array(z.string()).optional(),
 
-  providerImports: z.array(z.string()).optional(),
+  // providerImports/providerWrappers/files/transforms 는 arch-aware —
+  // 정적 값 또는 (arch) => 정적 값 함수 형태 둘 다 허용.
+  providerImports: z.union([z.array(z.string()), archAwareFn]).optional(),
   providerWrappers: z
-    .array(
-      z.union([
-        z.object({ open: z.string(), close: z.string() }),
-        z.string(),
-      ]),
-    )
+    .union([
+      z.array(
+        z.union([
+          z.object({ open: z.string(), close: z.string() }),
+          z.string(),
+        ]),
+      ),
+      archAwareFn,
+    ])
     .optional(),
 
-  files: z.record(filePath, z.string()).optional(),
+  files: archAwareRecord.optional(),
 
   // 향후 확장 — moves, transforms, etc 는 nextIntl.js 에서 사용하므로 허용
-  moves: z.array(z.any()).optional(),
-  transforms: z.array(z.any()).optional(),
+  moves: archAwareArray.optional(),
+  transforms: archAwareArray.optional(),
 });
 
 /**

package/src/create/plugins/sentry.js

@@ -57,8 +57,12 @@ export const sentryPlugin = {
   // HTTP/proxy 인프라(http.ts, apiTypes.ts, error.ts, app/api/proxy 등)는
   // 베이스 템플릿이 소유한다. Sentry 는 베이스의 observability.ts 를
   // Sentry-aware 버전으로 덮어써서 캡처/로그를 활성화한다.
+  //
+  // arch 의존: FallbackBoundary 는 arch.paths.ui 에, observability 는 arch.paths.api 에
+  // 떨어진다. FallbackBoundary 안의 ApiError import 는 arch.aliases.api 로 fully-qualified —
+  // 상대 경로 (`../../api/error`) 는 FSD 에서만 동작하므로 alias 로 통일.
 
-  files: {
+  files: (arch) => ({
     'sentry.server.config.ts': `import * as Sentry from '@sentry/nextjs';
 
 Sentry.init({
@@ -280,7 +284,7 @@ export default function Error({
 }
 `,
 
-    'src/shared/ui/FallbackBoundary/index.tsx': `import React, {
+    [`${arch.paths.ui}/FallbackBoundary/index.tsx`]: `import React, {
   Component,
   ComponentType,
   ErrorInfo,
@@ -290,7 +294,7 @@ export default function Error({
 import * as Sentry from '@sentry/nextjs';
 import { QueryErrorResetBoundary } from '@tanstack/react-query';
 
-import { ApiError } from '../../api/error';
+import { ApiError } from '${arch.aliases.api}/error';
 
 interface ErrorFallbackProps {
   error: Error | null;
@@ -386,7 +390,7 @@ export function FallbackBoundary({
     // http.ts / serverFetch.ts / proxy/route.ts 가 이 모듈을 import 하므로,
     // Sentry 플러그인이 켜지면 자동으로 캡처가 활성화된다.
 
-    'src/shared/api/observability.ts': `import * as Sentry from '@sentry/nextjs';
+    [`${arch.paths.api}/observability.ts`]: `import * as Sentry from '@sentry/nextjs';
 
 type ApiCaptureParams = {
   url: string;
@@ -439,5 +443,5 @@ export const logApiError = (prefix: string, params: ApiLogParams): void => {
   if (responseBody) console.error('- Response Body:', responseBody);
 };
 `,
-  },
+  }),
 };

package/src/mcp.mjs

@@ -45,6 +45,7 @@ import {
   CSS_FRAMEWORKS_SUPPORTED,
 } from "./constants.js";
 import { allPlugins } from "./create/plugins/index.js";
+import { allArchitectures } from "./create/architectures/index.js";
 import { THEME_PRESET_NAMES } from "./create/theme/presets.js";
 import { decodeTheme } from "./create/theme/decode.js";
 import { encodeTheme } from "./create/theme/encode.js";
@@ -55,6 +56,7 @@ const RADII = THEME_RADII;
 const MODES = THEME_MODES;
 const CSS_FRAMEWORKS = CSS_FRAMEWORKS_SUPPORTED;
 const PLUGIN_NAMES = allPlugins.map((p) => p.name);
+const ARCH_NAMES = allArchitectures.map((a) => a.name);
 const THEME_PRESETS_LIST = THEME_PRESET_NAMES.join(", ");
 
 const INIT_DESCRIPTIONS = {
@@ -227,6 +229,13 @@ export async function startMcpServer() {
           .describe("Next.js 구조 — platform=next 일 때 필수. standalone(단독) | monorepo(Turborepo)"),
         plugins: z.array(z.enum(PLUGIN_NAMES)).optional()
           .describe(`Next.js 플러그인 (${PLUGIN_NAMES.join(', ')}). 미지정시 빈 배열`),
+        arch: z.enum(ARCH_NAMES).optional()
+          .describe(
+            `프로젝트 아키텍처 — 플랫폼별로 사용 가능한 값이 다름. ` +
+            `현재 next 에서 사용 가능: ${allArchitectures.filter((a) => a.platforms.includes('next')).map((a) => a.name).join(', ')} (기본 fsd). ` +
+            `flutter 는 현재 arch 디스크립터 없음 (미지정 또는 host 자체 default). ` +
+            `arch 와 플러그인은 별개 — arch 는 폴더 구조/import alias 컨벤션, 플러그인은 기능.`,
+          ),
         theme: z.string().optional()
           .describe(`프리셋 이름 (${THEME_PRESETS_LIST}) 또는 base64 테마 코드. 사용자가 톤을 직접 손본 결과를 영구 보관하려면 sh_ui_encode_theme 으로 base64 를 만들어 여기에 넘긴다.`),
         cssFramework: z.enum(CSS_FRAMEWORKS).optional()
@@ -271,6 +280,7 @@ export async function startMcpServer() {
             platform: input.platform,
             structure: input.structure,
             plugins: input.plugins,
+            arch: input.arch,
             theme: input.theme,
             css: input.cssFramework,
             yes: true, // 사전 검사를 마쳤으니 generator 의 confirm 프롬프트 우회

package/templates/nextjs-app/_arch/flat/app/api/proxy/[...path]/route.ts

@@ -0,0 +1,112 @@
+import { cookies } from 'next/headers';
+import { NextResponse, type NextRequest } from 'next/server';
+
+import {
+  captureApiError,
+  logApiError,
+} from '@/lib/api/observability';
+
+const API_URL = process.env.API_URL ?? 'http://localhost:8080/api';
+const ACCESS_TOKEN_COOKIE = 'accessToken';
+const LOCALE_COOKIE = 'NEXT_LOCALE';
+
+const proxyRequest = async (
+  request: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+  method: string,
+) => {
+  const { path } = await ctx.params;
+  const apiPath = path.join('/');
+  const url = new URL(`${API_URL}/${apiPath}`);
+
+  request.nextUrl.searchParams.forEach((value, key) => {
+    url.searchParams.set(key, value);
+  });
+
+  const cookieStore = await cookies();
+  const accessToken = cookieStore.get(ACCESS_TOKEN_COOKIE)?.value;
+  const locale =
+    cookieStore.get(LOCALE_COOKIE)?.value ??
+    request.headers.get('Accept-Language') ??
+    undefined;
+
+  const headers: Record<string, string> = {};
+  if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  if (locale) headers['Accept-Language'] = locale;
+
+  let body: BodyInit | undefined;
+  if (method !== 'GET' && method !== 'HEAD') {
+    const contentType = request.headers.get('Content-Type');
+    if (contentType?.includes('multipart/form-data')) {
+      body = await request.formData();
+    } else {
+      headers['Content-Type'] = 'application/json';
+      body = await request.text();
+    }
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(url.toString(), { method, headers, body });
+  } catch (error) {
+    console.error(`[PROXY] ${method} ${url.toString()} —`, error);
+    return NextResponse.json(
+      {
+        result: 'ERROR',
+        data: null,
+        error: {
+          code: 'NETWORK_ERROR',
+          message: '서버에 연결할 수 없습니다.',
+        },
+      },
+      { status: 502 },
+    );
+  }
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    logApiError('PROXY', {
+      url: url.toString(),
+      method,
+      status: response.status,
+      requestBody: typeof body === 'string' ? body : undefined,
+      responseBody: data,
+    });
+
+    captureApiError({
+      url: url.toString(),
+      apiPath,
+      method,
+      status: response.status,
+      responseBody: data,
+    });
+  }
+
+  return NextResponse.json(data, { status: response.status });
+};
+
+export const GET = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'GET');
+
+export const POST = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'POST');
+
+export const PUT = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PUT');
+
+export const PATCH = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PATCH');
+
+export const DELETE = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'DELETE');

package/templates/nextjs-app/_arch/flat/app/layout.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from 'next';
+import '@workspace/ui-app-name/globals.css';
+import { RootLayout } from '@/components/layouts/RootLayout';
+
+export const metadata: Metadata = {
+  title: 'App Name',
+  description: 'App Description',
+};
+
+export default function Layout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return <RootLayout>{children}</RootLayout>;
+}

package/templates/nextjs-app/_arch/flat/components/common/PrefetchBoundary/index.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import {
+  dehydrate,
+  type FetchQueryOptions,
+  HydrationBoundary,
+} from '@tanstack/react-query';
+
+import getQueryClient from '@/lib/utils/getQueryClient';
+
+export type FetchOptions = Pick<FetchQueryOptions, 'queryKey' | 'queryFn'>;
+
+type Props = {
+  fetchOptions?: FetchOptions[] | FetchOptions | null;
+  children: ReactNode;
+};
+
+/**
+ * RSC 에서 prefetch 를 끝낸 뒤 dehydrated state 로 클라이언트에 hydrate.
+ * 단일/배열 둘 다 받는다.
+ */
+export async function PrefetchBoundary({ fetchOptions, children }: Props) {
+  const queryClient = getQueryClient();
+
+  if (fetchOptions) {
+    const list = Array.isArray(fetchOptions) ? fetchOptions : [fetchOptions];
+    await Promise.all(list.map((opt) => queryClient.prefetchQuery(opt)));
+  }
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      {children}
+    </HydrationBoundary>
+  );
+}

package/templates/nextjs-app/_arch/flat/components/layouts/RootLayout.tsx

@@ -0,0 +1,11 @@
+import { GlobalProvider } from '@/components/providers';
+
+export function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang='ko' suppressHydrationWarning>
+      <body>
+        <GlobalProvider>{children}</GlobalProvider>
+      </body>
+    </html>
+  );
+}

package/templates/nextjs-app/_arch/flat/components/providers/tanstack/QueryClientProvider.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { QueryClientProvider as TanstackQueryClientProvider } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+
+import { getBrowserQueryClient } from '@/lib/api/queryClient';
+
+export function QueryClientProvider({ children }: { children: ReactNode }) {
+  return (
+    <TanstackQueryClientProvider client={getBrowserQueryClient()}>
+      {children}
+    </TanstackQueryClientProvider>
+  );
+}

package/templates/nextjs-app/_arch/flat/lib/utils/getQueryClient.ts

@@ -0,0 +1,14 @@
+import { isServer } from '@tanstack/react-query';
+
+import {
+  getBrowserQueryClient,
+  getServerQueryClient,
+} from '@/lib/api/queryClient';
+
+/**
+ * RSC 와 클라이언트 양쪽에서 안전하게 호출 가능한 QueryClient 핸들.
+ * 서버에서는 React `cache()` 로 요청 단위 싱글턴, 브라우저에서는 모듈 싱글턴.
+ */
+export default function getQueryClient() {
+  return isServer ? getServerQueryClient() : getBrowserQueryClient();
+}

package/templates/nextjs-app/_arch/flat/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "extends": "@workspace/typescript-config/nextjs.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/lib/*": ["./lib/*"],
+      "@/components/*": ["./components/*"],
+      "@/app/*": ["./app/*"],
+      "@workspace/ui-app-name/*": ["../../packages/ui/ui-apps/ui-app-name/src/*"]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "next.config.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}

package/templates/nextjs-standalone/_arch/flat/app/api/proxy/[...path]/route.ts

@@ -0,0 +1,112 @@
+import { cookies } from 'next/headers';
+import { NextResponse, type NextRequest } from 'next/server';
+
+import {
+  captureApiError,
+  logApiError,
+} from '@/lib/api/observability';
+
+const API_URL = process.env.API_URL ?? 'http://localhost:8080/api';
+const ACCESS_TOKEN_COOKIE = 'accessToken';
+const LOCALE_COOKIE = 'NEXT_LOCALE';
+
+const proxyRequest = async (
+  request: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+  method: string,
+) => {
+  const { path } = await ctx.params;
+  const apiPath = path.join('/');
+  const url = new URL(`${API_URL}/${apiPath}`);
+
+  request.nextUrl.searchParams.forEach((value, key) => {
+    url.searchParams.set(key, value);
+  });
+
+  const cookieStore = await cookies();
+  const accessToken = cookieStore.get(ACCESS_TOKEN_COOKIE)?.value;
+  const locale =
+    cookieStore.get(LOCALE_COOKIE)?.value ??
+    request.headers.get('Accept-Language') ??
+    undefined;
+
+  const headers: Record<string, string> = {};
+  if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  if (locale) headers['Accept-Language'] = locale;
+
+  let body: BodyInit | undefined;
+  if (method !== 'GET' && method !== 'HEAD') {
+    const contentType = request.headers.get('Content-Type');
+    if (contentType?.includes('multipart/form-data')) {
+      body = await request.formData();
+    } else {
+      headers['Content-Type'] = 'application/json';
+      body = await request.text();
+    }
+  }
+
+  let response: Response;
+  try {
+    response = await fetch(url.toString(), { method, headers, body });
+  } catch (error) {
+    console.error(`[PROXY] ${method} ${url.toString()} —`, error);
+    return NextResponse.json(
+      {
+        result: 'ERROR',
+        data: null,
+        error: {
+          code: 'NETWORK_ERROR',
+          message: '서버에 연결할 수 없습니다.',
+        },
+      },
+      { status: 502 },
+    );
+  }
+
+  const data = await response.json();
+
+  if (!response.ok) {
+    logApiError('PROXY', {
+      url: url.toString(),
+      method,
+      status: response.status,
+      requestBody: typeof body === 'string' ? body : undefined,
+      responseBody: data,
+    });
+
+    captureApiError({
+      url: url.toString(),
+      apiPath,
+      method,
+      status: response.status,
+      responseBody: data,
+    });
+  }
+
+  return NextResponse.json(data, { status: response.status });
+};
+
+export const GET = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'GET');
+
+export const POST = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'POST');
+
+export const PUT = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PUT');
+
+export const PATCH = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'PATCH');
+
+export const DELETE = (
+  req: NextRequest,
+  ctx: { params: Promise<{ path: string[] }> },
+) => proxyRequest(req, ctx, 'DELETE');