@xfilecom/xframe 0.1.38 → 0.1.40

package/bin/xframe.js

@@ -645,7 +645,13 @@ Next:
   yarn dev   # 또는 npm run dev
   → API :3000/health  ·  Client :3001  ·  Admin :3002
   (설치 생략: npx @xfilecom/xframe <dir> --no-install)
-  최신 스캐폴드: npx --yes @xfilecom/xframe@latest <dir>`);
+  최신 스캐폴드: npx --yes @xfilecom/xframe@latest <dir>
+
+엔드포인트 추가 시 (상세: docs/SCAFFOLD_CHECKLIST.md):
+  • shared/endpoint  → 계약(EndpointDef)
+  • apps/api/src     → Controller·Module 라우트
+  • web/shared/src/api/methods → ApiMethodConfig + index 등록
+  • web/shared/src/methods → (선택) sendRequest 헬퍼`);
 }
 
 main().catch((err) => {

package/defaults.json

@@ -1,4 +1,4 @@
 {
-  "backendCore": "^1.0.18",
-  "frontCore": "^0.2.24"
+  "backendCore": "^1.0.20",
+  "frontCore": "^0.2.26"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/xframe",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "Scaffold full-stack app: Nest + @xfilecom/backend-core, Vite/React + @xfilecom/front-core",
   "license": "UNLICENSED",
   "bin": {

package/template/apps/api/src/main.ts

@@ -1,3 +1,21 @@
+/**
+ * =============================================================================
+ * Nest API 부트스트랩 (xframe 템플릿)
+ * =============================================================================
+ *
+ * 실행 순서
+ * ---------
+ * 1. `config.loader` — YAML/ENV 병합 후 `appConfig` 싱글톤 (DB URL, CORS, globalPrefix 등).
+ * 2. `AppModule` — `@xfilecom/backend-core` `CoreModule` 및 앱 라우트 등록.
+ * 3. `applyNestAppFromConfig` — CORS, `setGlobalPrefix` 등 Nest 인스턴스 레벨 설정만 적용.
+ *    (인터셉터·필터·DB는 모듈 쪽 책임)
+ *
+ * 프론트와의 계약
+ * ---------------
+ * - 공통 응답 봉투 `{ code, data, error }`는 보통 CoreModule/인터셉터에서 맞춘다.
+ * - 프론트 `shared/endpoint`의 `path`와 여기 `globalPrefix` 조합이 실제 URL이 된다.
+ */
+
 import './config.loader';
 import 'reflect-metadata';
 import { NestFactory } from '@nestjs/core';
@@ -5,12 +23,17 @@ import type { INestApplication } from '@nestjs/common';
 import { AppModule } from './app.module';
 import { appConfig } from './config.loader';
 
+/**
+ * 양의 유한 숫자면 그 값, 아니면 `undefined`.
+ */
 function parsePositivePort(v: string | number | undefined): number | undefined {
   const n = typeof v === 'number' ? v : Number(v);
   return Number.isFinite(n) && n > 0 ? n : undefined;
 }
 
-/** `PORT`(syncEnvKeys) → `server.port`(YAML) → 기본값 */
+/**
+ * `PORT`(syncEnvKeys) → `server.port`(YAML) → 기본값 `3000`.
+ */
 function resolveListenPort(): number {
   return (
     parsePositivePort(process.env.PORT) ??
@@ -19,6 +42,9 @@ function resolveListenPort(): number {
   );
 }
 
+/**
+ * `appConfig.cors`에 따라 `enableCors` 호출. `enabled: false`면 아무 것도 안 함.
+ */
 function applyCorsFromConfig(app: INestApplication): void {
   const cors = appConfig.cors;
   if (cors?.enabled === false) {
@@ -33,6 +59,9 @@ function applyCorsFromConfig(app: INestApplication): void {
   app.enableCors({ origin: origin === true, credentials });
 }
 
+/**
+ * `globalPrefix`가 있으면 앞뒤 슬래시 정리 후 `setGlobalPrefix`.
+ */
 function applyHttpFromConfig(app: INestApplication): void {
   const prefix = appConfig.http?.globalPrefix;
   if (prefix != null && String(prefix).trim() !== '') {
@@ -49,6 +78,9 @@ function applyNestAppFromConfig(app: INestApplication): void {
   applyHttpFromConfig(app);
 }
 
+/**
+ * 한 줄 요약 로그 (포트·환경·CORS·DB·JWT·sql 엔드포인트 플래그).
+ */
 function logStartupFromConfig(port: number): void {
   const base = appConfig.http?.publicBaseUrl?.replace(/\/$/, '');
   const pfx = appConfig.http?.globalPrefix
@@ -74,6 +106,9 @@ function logStartupFromConfig(port: number): void {
   );
 }
 
+/**
+ * Nest 앱 생성 → 설정 적용 → 리슨 → 스타트업 로그.
+ */
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
   applyNestAppFromConfig(app);

package/template/docs/SCAFFOLD_CHECKLIST.md

@@ -0,0 +1,13 @@
+# 스캐폴드 직후 — API·프론트 연결 체크리스트
+
+새 앱을 `npx @xfilecom/xframe <dir>` 로 만든 뒤, 엔드포인트를 추가할 때 아래 순서를 참고하면 된다.
+
+1. **`shared/endpoint/`** — 경로·메서드·타입·`EndpointDef`(및 OpenAPI가 있으면 동기화).
+2. **`apps/api/src/`** — Nest `Controller` / `Service` / `Module`에 라우트 등록·의존성 연결.
+3. **`web/shared/src/api/methods/`** — `ApiMethodConfig` 정의 후 `index.ts`의 `methods` 맵에 등록.
+4. **`web/shared/src/methods/`** — `sendRequest`만 쓰는 얇은 헬퍼가 필요하면 추가(예: `health.ts`).
+5. **`shared/config/api`** — 공개 URL·글로벌 prefix 등 API 쪽 YAML이 바뀌면 반영.
+6. **`shared/config/web/client` · `admin`** — 프록시·API 베이스가 달라지면 각 `application*.yml` 수정.
+7. **`shared/schema/` · `sql/`** — DB 스키마·마이그레이션이 도메인에 필요하면 여기서 정리 후 `apps/api`와 맞춘다.
+
+자세한 DB·설정 흐름은 **[DATABASE.md](./DATABASE.md)**, 웹 콘솔·번들은 **[WEB_DEV_CONSOLE.md](./WEB_DEV_CONSOLE.md)** 를 본다.

package/template/shared/README.md

@@ -5,7 +5,7 @@
 | 경로 | 용도 |
 |------|------|
 | **`config/api`** | Nest API YAML (`application.yml`, `application-<env>.yml`) |
-| **`config/web/client`**, **`config/web/admin`** | 각 Vite 앱별 YAML (`VITE_API_BASE_URL`, `VITE_APP_TITLE` 등 주입) |
+| **`config/web/client`**, **`config/web/admin`** | 각 Vite 앱별 YAML — `vite.config` `define`으로 `import.meta.env.XFC_*`에 주입 (`.env` 미사용) |
 | **`schema/`** | Drizzle 등 DB 스키마(TS). `apps/api`의 `tsconfig.build.json`에 경로를 포함하거나, 스키마만 `apps/api/src/database`에 두고 여기서 re-export 하는 식으로 맞추면 됩니다. Nest 에서의 주입·쿼리 패턴은 루트 **[docs/DATABASE.md](../docs/DATABASE.md)** 참고. |
 | **`sql/`** | 마이그레이션·시드·원시 SQL; **`sql/sql.ts`** (`databaseSqlManifest`) 로 경로·절차 메타 정리 |
 | **`endpoint/`** | HTTP 계약(OpenAPI yaml, 공유 DTO 타입, 라우트 메타) — 제품에 맞게 확장 |

package/template/shared/endpoint/endpoint.ts

@@ -1,15 +1,31 @@
 /**
- * HTTP API 엔드포인트 정의 — Nest(`@shared/*`)와 Vite(`@shared/*` alias) 공통.
- * `web/` 옆 루트 `shared/endpoint/` 에 두어 백엔드 라우트·프론트 axios 경로를 한곳에서 맞춥니다.
+ * =============================================================================
+ * shared/endpoint — Nest·Vite 공통 API 경로 정의 (`EndpointDef`)
+ * =============================================================================
  *
- * Nest 는 주로 `method`·`path` 만 쓰고, `post`·`showIndicator`·`timeoutMs` 등은 프론트 `sendRequest` / RootStore `sendMessage` 가 참고합니다.
+ * 왜 shared에 두는가?
+ * --------------------
+ * - 백엔드(Nest) 컨트롤러의 `@Get('health')` 와 프론트 axios URL을 **문자열 하나로** 맞추기 위함.
+ * - `packages/.../template` 기준으로 `web/`과 `apps/api`가 같은 파일(또는 복사본)을 바라보게 스캐폴딩한다.
+ *
+ * 필드 의미
+ * ---------
+ * - **method / path**: HTTP 메서드와 상대 경로 (`apiClient.defaults.baseURL`에 붙음).
+ * - **post**: 이름이 HTTP POST와 무관하다. `sendRequest`가 axios 응답 본문(`response.data`)을 받은 **뒤**
+ *   한 번 더 변환할 때 쓰는 함수. (예: 레거시 `{ data: T }` 한 겹 제거)
+ *   ※ 공통 봉투 `{ code, data, error }`는 **먼저** `api/client` 인터셉터에서 안쪽 `data`로 치환되므로,
+ *   여기서의 `post`는 그 **이후**의 값을 받는다. 이중 언래핑에 주의.
+ * - **showIndicator**: `RootStore.sendMessage`가 `options.showIndicator`를 생략했을 때 쓰는 기본값.
+ *   `sendRequest`만 직접 호출할 때는 이 필드가 자동 적용되지 않는다 (전역 바만 axios config로 제어).
+ * - **timeoutMs**: 해당 요청만 axios timeout 덮어쓰기.
  */
 
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 
 /**
- * 백엔드 `CommonResponseDto` 류 `{ data: T, code?, error? }` 에서 `data` 만 꺼냄.
- * 해당 필드가 없으면 본문 그대로 반환.
+ * 객체에 `data` 키가 있으면 그 값만 반환, 없으면 인자 그대로 반환.
+ * `EndpointDef.post`에서 레거시 한 겹 래핑 제거용. (공통 봉투는 axios 쪽에서 먼저 처리)
+ * @param body - `sendRequest`가 넘기는 응답 본문
  */
 export function unwrapResponseData(body: unknown): unknown {
   if (body !== null && typeof body === 'object' && 'data' in body) {
@@ -44,6 +60,7 @@ export const healthEndpoint: EndpointDef = {
   path: '/health',
   /** health 는 인디케이터 없이 조용히 호출하는 경우가 많음 */
   showIndicator: false,
+  /** 공통 봉투를 쓰지 않는 레거시 응답이면 안쪽 data 추출에 유용. 봉투만 쓰는 API면 생략 가능. */
   post: unwrapResponseData,
 };
 

package/template/web/admin/src/App.tsx

@@ -1,7 +1,7 @@
 import { Badge, Text } from '@xfilecom/front-core';
 import { safeJsonStringify, Shell, useHealthStatus } from '__WEB_SHARED_WORKSPACE__';
 
-const title = import.meta.env.VITE_APP_TITLE || '__PACKAGE_NAME__ (admin)';
+const title = import.meta.env.XFC_APP_TITLE || '__PACKAGE_NAME__ (admin)';
 
 export function App() {
   const { data } = useHealthStatus();

package/template/web/admin/src/main.tsx

@@ -1,3 +1,12 @@
+/**
+ * =============================================================================
+ * Vite + React 엔트리 (admin)
+ * =============================================================================
+ *
+ * client와 동일한 shared 패키지·`configureApi`·`StoreProvider` 구성을 공유한다.
+ * API base·앱 제목은 `.env`가 아니라 `shared/config/web/admin` YAML → `vite.config` `define` 주입.
+ */
+
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import '@xfilecom/front-core/tokens.css';
@@ -12,7 +21,7 @@ import {
 import { App } from './App';
 
 configureApi({
-  baseURL: import.meta.env.VITE_API_BASE_URL || FALLBACK_API_BASE_URL,
+  baseURL: import.meta.env.XFC_API_BASE_URL || FALLBACK_API_BASE_URL,
 });
 
 ReactDOM.createRoot(document.getElementById('root')!).render(

package/template/web/admin/src/vite-env.d.ts

@@ -1,8 +1,9 @@
 /// <reference types="vite/client" />
 
 interface ImportMetaEnv {
-  readonly VITE_API_BASE_URL: string;
-  readonly VITE_APP_TITLE: string;
+  /** `vite.config` `define` — 원본은 `shared/config/web/admin/application*.yml` (`.env` 미사용) */
+  readonly XFC_API_BASE_URL: string;
+  readonly XFC_APP_TITLE: string;
 }
 
 interface ImportMeta {

package/template/web/admin/vite.config.ts

@@ -69,8 +69,8 @@ export default defineConfig(({ mode }) => {
       },
     },
     define: {
-      'import.meta.env.VITE_API_BASE_URL': JSON.stringify(apiBase),
-      'import.meta.env.VITE_APP_TITLE': JSON.stringify(title),
+      'import.meta.env.XFC_API_BASE_URL': JSON.stringify(apiBase),
+      'import.meta.env.XFC_APP_TITLE': JSON.stringify(title),
     },
     server: {
       port: 3002,

package/template/web/client/src/App.tsx

@@ -3,7 +3,7 @@ import { Badge, Button, Stack, Text } from '@xfilecom/front-core';
 import { safeJsonStringify, Shell, useHealthStatus } from '__WEB_SHARED_WORKSPACE__';
 import { FrontCoreShowcase } from './FrontCoreShowcase';
 
-const title = import.meta.env.VITE_APP_TITLE || '__PACKAGE_NAME__';
+const title = import.meta.env.XFC_APP_TITLE || '__PACKAGE_NAME__';
 
 type Tab = 'api' | 'atoms';
 

package/template/web/client/src/FrontCoreShowcase.tsx

@@ -5,13 +5,17 @@ import {
   Box,
   Button,
   Card,
+  Checkbox,
   ConfirmDialog,
   Dialog,
+  Field,
   Input,
   InlineErrorList,
   LoadingOverlay,
+  Select,
   Stack,
   Text,
+  Textarea,
   Toast,
   ToastList,
   ToastSeverityIcon,
@@ -71,6 +75,9 @@ export function FrontCoreShowcase() {
   const [confirmCustomOpen, setConfirmCustomOpen] = useState(false);
   const [sheetOpen, setSheetOpen] = useState(false);
   const [sheetRichOpen, setSheetRichOpen] = useState(false);
+  const [fieldBio, setFieldBio] = useState('');
+  const [fieldPlan, setFieldPlan] = useState('a');
+  const [fieldAgree, setFieldAgree] = useState(false);
 
   const pushToast = useCallback(
     (severity: ToastSeverity) => {
@@ -173,7 +180,7 @@ export function FrontCoreShowcase() {
         open={confirmOpen}
         onOpenChange={setConfirmOpen}
         title="ConfirmDialog"
-        message="일반 확인창입니다. 취소 시 onCancel 후 닫힙니다."
+        message="Default labels: OK / Cancel. Cancel runs onCancel then closes."
         onConfirm={() => setConfirmOpen(false)}
       />
 
@@ -354,6 +361,42 @@ export function FrontCoreShowcase() {
           </Stack>
         </Card>
 
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>Field · Textarea · Select · Checkbox</SectionTitle>
+            <Field
+              htmlFor={`${uid}-field-bio`}
+              label="Bio"
+              hint="Short description"
+              error={fieldBio.length > 12 ? 'Keep it under 12 characters' : undefined}
+              invalid={fieldBio.length > 12}
+            >
+              <Textarea
+                id={`${uid}-field-bio`}
+                rows={3}
+                placeholder="Type here…"
+                value={fieldBio}
+                onChange={(e) => setFieldBio(e.target.value)}
+              />
+            </Field>
+            <Field htmlFor={`${uid}-field-plan`} label="Plan">
+              <Select
+                id={`${uid}-field-plan`}
+                value={fieldPlan}
+                onChange={(e) => setFieldPlan(e.target.value)}
+              >
+                <option value="a">Plan A</option>
+                <option value="b">Plan B</option>
+              </Select>
+            </Field>
+            <Checkbox
+              label="I agree to the terms"
+              checked={fieldAgree}
+              onChange={(e) => setFieldAgree(e.target.checked)}
+            />
+          </Stack>
+        </Card>
+
         <Card>
           <Stack direction="column" gap="md" align="stretch">
             <SectionTitle>Box · Stack · 레이아웃 props</SectionTitle>

package/template/web/client/src/main.tsx

@@ -1,3 +1,13 @@
+/**
+ * =============================================================================
+ * Vite + React 엔트리 (client)
+ * =============================================================================
+ *
+ * - 스타일: design tokens → base → xframe 테마 → 앱 레이아웃(`app.css`) 순서 유지.
+ * - `configureApi`: axios `baseURL` — `vite.config` `define`으로 주입(`shared/config/web/client` YAML). 없으면 `FALLBACK_API_BASE_URL`.
+ * - `StoreProvider`: 전역 로딩 바·토스트 스택·MobX `rootStore` 컨텍스트.
+ */
+
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import '@xfilecom/front-core/tokens.css';
@@ -12,7 +22,7 @@ import {
 import { App } from './App';
 
 configureApi({
-  baseURL: import.meta.env.VITE_API_BASE_URL || FALLBACK_API_BASE_URL,
+  baseURL: import.meta.env.XFC_API_BASE_URL || FALLBACK_API_BASE_URL,
 });
 
 ReactDOM.createRoot(document.getElementById('root')!).render(

package/template/web/client/src/vite-env.d.ts

@@ -1,8 +1,9 @@
 /// <reference types="vite/client" />
 
 interface ImportMetaEnv {
-  readonly VITE_API_BASE_URL: string;
-  readonly VITE_APP_TITLE: string;
+  /** `vite.config` `define` — 원본은 `shared/config/web/client/application*.yml` (`.env` 미사용) */
+  readonly XFC_API_BASE_URL: string;
+  readonly XFC_APP_TITLE: string;
 }
 
 interface ImportMeta {

package/template/web/client/vite.config.ts

@@ -71,9 +71,10 @@ export default defineConfig(({ mode }) => {
         '__WEB_SHARED_WORKSPACE__': webSharedSrc,
       },
     },
+    // `.env` 없음 — 값은 위 `loadWebConfig`(YAML)에서만 온다. `define`으로 번들에 고정 주입.
     define: {
-      'import.meta.env.VITE_API_BASE_URL': JSON.stringify(apiBase),
-      'import.meta.env.VITE_APP_TITLE': JSON.stringify(title),
+      'import.meta.env.XFC_API_BASE_URL': JSON.stringify(apiBase),
+      'import.meta.env.XFC_APP_TITLE': JSON.stringify(title),
     },
     server: {
       port: 3001,

package/template/web/shared/README.md

@@ -37,3 +37,8 @@ import { Shell } from '__WEB_SHARED_WORKSPACE__';
 ### `web/shared` CSS·TS가 수정해도 반영되지 않을 때
 
 `file:../shared` 가 `node_modules`에 **복사본**으로 설치되면 Vite는 낡은 파일을 씁니다. `web/client`·`web/admin`의 Vite 설정에 **`__WEB_SHARED_WORKSPACE__` → `../shared/src`** alias가 있어 워크스페이스 소스를 직접 가리킵니다.
+
+## HTTP 클라이언트·토스트
+
+- **`api/client`**: 요청·성공·에러 응답 **콘솔 로그**는 `import.meta.env.DEV`일 때만 (`devHttpLog`). 프로덕션 번들에서는 해당 분기가 제거된다.
+- **전역 토스트**: `error`는 **수동 닫기만**(자동 제거 없음). `info` / `success` / `warn`은 일정 시간 후 자동 제거이며 닫기 버튼은 없다. front-core 기본 닫기 레이블은 영어(`Dismiss`); 필요 시 `ToastList` `dismissAriaLabel`로 변경.

package/template/web/shared/src/api/client.ts

@@ -1,6 +1,24 @@
 /**
- * Axios — baseURL, 로깅 인터셉터, 전역 훅(onRequestStart/End), Bearer
- * HTTP 200/201 본문이 `{ code, data, error }` 이면 code 검사 후 data 로 치환 또는 토스트+reject
+ * =============================================================================
+ * xframe — 공용 Axios 인스턴스 (`apiClient`) 및 인터셉터
+ * =============================================================================
+ *
+ * 역할 요약
+ * ---------
+ * 1) **요청**: Bearer 토큰(`sessionStore`) 부착, 선택적 전역 로딩 훅(`onRequestStart`).
+ * 2) **응답(HTTP 2xx)**: 공통 본문 `{ code, data, error }` 이면 비즈니스 코드 검사 후
+ *    `response.data`를 안쪽 `data`로 치환하거나, 실패 시 토스트 콜백 + Promise reject.
+ * 3) **응답(HTTP 비 2xx / 네트워크)**: 메시지 추출 후 `onError` (보통 RootStore에서 토스트).
+ *
+ * 데이터가 흘러가는 순서 (성공 시)
+ * ---------------------------------
+ * 서버 JSON → axios가 파싱 → `response.data` (아직 봉투일 수 있음)
+ *   → `logResponseSuccess` (콘솔에는 공통 봉투면 **내부 `data`만** 요약 출력)
+ *   → `applyCommonResponseEnvelope` (봉투면 `response.data = body.data` 로 치환)
+ *   → `sendRequest` / 호출부는 **항상 “실제 페이로드”**만 받는 것을 목표로 함.
+ *
+ * `setApiHooks`는 앱 기동 시 한 번(RootStore 생성자 등)에서 `rootStore`와 연결합니다.
+ * `skipGlobalIndicator`는 개별 요청 config에 붙이며, 전역 로딩 바/카운터를 건너뜁니다.
  */
 
 import axios, {
@@ -11,16 +29,23 @@ import axios, {
 import { sessionStore } from '../store/session-store';
 import {
   applyCommonResponseEnvelope,
-  CommonResponseRejectedError,
   formatCommonErrorField,
   isCommonResponsePayload,
 } from './commonResponse';
 
 const LOG_PREFIX = '[xframe/http]';
 
+/** 요청/성공 응답 콘솔 로그 — Vite `import.meta.env.DEV`일 때만 (프로덕션 번들에서는 제거됨) */
+function devHttpLog(fn: () => void) {
+  if (import.meta.env.DEV) fn();
+}
+
+/** 전역 로딩(예: 상단 바) — `skipGlobalIndicator`가 아닐 때만 호출됨 */
 export type OnRequestStart = () => void;
 export type OnRequestEnd = () => void;
+/** HTTP 레벨 실패(4xx/5xx, 네트워크 등) — 표시는 보통 RootStore `addToast` */
 export type OnError = (message: string, code?: string | number) => void;
+/** HTTP 2xx인데 본문 `code !== 0` — 비즈니스 실패 */
 export type OnCommonBusinessError = (message: string, appCode: number) => void;
 
 let onRequestStart: OnRequestStart = () => {};
@@ -35,6 +60,11 @@ export {
   isCommonResponsePayload,
 } from './commonResponse';
 
+/**
+ * 런타임에 전역 훅을 주입한다. **전달한 키만** 덮어쓰고, 나머지는 기존 구현을 유지한다.
+ * - 테스트 시 mock으로 바꾸거나, 스토어 없이 쓰는 스크립트에서 noop 유지 가능.
+ * @param hooks - 요청 시작/종료, HTTP 에러, 비즈니스 코드 실패 시 콜백
+ */
 export function setApiHooks(hooks: {
   onRequestStart?: OnRequestStart;
   onRequestEnd?: OnRequestEnd;
@@ -53,16 +83,27 @@ export const apiClient = axios.create({
   headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
 });
 
+/**
+ * axios 기본 `baseURL` 설정. 끝의 `/`는 제거해 경로 결합 시 이중 슬래시를 피한다.
+ * @param options.baseURL - 예: `https://api.example.com` 또는 `http://localhost:3000`
+ */
 export function configureApi(options: { baseURL: string }) {
   apiClient.defaults.baseURL = options.baseURL.replace(/\/$/, '');
 }
 
+/**
+ * 현재 설정된 axios `baseURL` (미설정이면 빈 문자열).
+ */
 export function getApiBaseUrl(): string {
   return apiClient.defaults.baseURL ?? '';
 }
 
+/** axios InternalAxiosRequestConfig 확장 — sendRequest가 문자열 키로 전달 */
 type ExtConfig = InternalAxiosRequestConfig & { skipGlobalIndicator?: boolean };
 
+/**
+ * 나가는 요청을 콘솔에 남긴다. 호출부는 `devHttpLog`로 감싸 **개발 모드에서만** 실행한다.
+ */
 function logRequest(config: InternalAxiosRequestConfig) {
   console.log(`${LOG_PREFIX} request`, {
     method: config.method?.toUpperCase(),
@@ -74,6 +115,12 @@ function logRequest(config: InternalAxiosRequestConfig) {
   });
 }
 
+/**
+ * 성공 응답 로그: 공통 봉투면 `data` 키에 **내부 페이로드**만 넣어 가독성 확보.
+ * (인터셉터에서 아직 치환 전이므로, 여기서는 `response.data`를 직접 읽어 분기)
+ * 호출부는 `devHttpLog`로 감싸 프로덕션에서는 출력하지 않는다.
+ * @param response - axios 2xx 응답
+ */
 function logResponseSuccess(response: AxiosResponse) {
   const body = response.data;
   const data = isCommonResponsePayload(body) ? body.data : body;
@@ -85,6 +132,10 @@ function logResponseSuccess(response: AxiosResponse) {
   });
 }
 
+/**
+ * AxiosError면 status·url·응답 body 등을 묶어 로그, 그 외는 그대로 출력.
+ * `devHttpLog` 안에서만 호출한다.
+ */
 function logResponseError(error: unknown) {
   if (axios.isAxiosError(error)) {
     console.log(`${LOG_PREFIX} response error`, {
@@ -100,43 +151,51 @@ function logResponseError(error: unknown) {
   }
 }
 
+/** 요청: 로깅 → Bearer → FormData 시 Content-Type 제거 → 전역 로딩 시작(옵션) */
 apiClient.interceptors.request.use(
   (config: InternalAxiosRequestConfig) => {
-    logRequest(config);
+    devHttpLog(() => logRequest(config));
     const c = config as ExtConfig;
     const token = sessionStore.token;
     if (token && c.headers) {
       c.headers.Authorization = `Bearer ${token}`;
     }
+    // 브라우저가 multipart boundary를 넣도록 Content-Type 제거
     if (c.data instanceof FormData && c.headers) {
       delete c.headers['Content-Type'];
     }
     if (!c.skipGlobalIndicator) onRequestStart();
     return c;
   },
+  /** 요청 단계에서의 예외 (네트워크 전 단계 등) */
   (err) => {
-    console.log(`${LOG_PREFIX} request error`, err);
+    devHttpLog(() => console.log(`${LOG_PREFIX} request error`, err));
     return Promise.reject(err);
   },
 );
 
+/** 응답(2xx): 전역 로딩 종료 → 성공 로그 → 공통 봉투 처리 */
 apiClient.interceptors.response.use(
   (response: AxiosResponse) => {
     const c = response.config as ExtConfig;
+    // 성공이므로 이 요청에 대응하는 “진행 중” 카운터를 내림
     if (!c.skipGlobalIndicator) onRequestEnd();
-    logResponseSuccess(response);
+    devHttpLog(() => logResponseSuccess(response));
     try {
+      // 봉투 처리 실패 시 CommonResponseRejectedError throw → 아래 체인에서 catch
       applyCommonResponseEnvelope(response, onCommonBusinessError);
     } catch (e) {
       return Promise.reject(e);
     }
     return response;
   },
+  /** 응답(비 2xx)·네트워크 오류: 로딩 종료 → 로그 → 메시지 추출 → `onError` → reject */
   (err: AxiosError) => {
     const c = err.config as ExtConfig | undefined;
     if (!c?.skipGlobalIndicator) onRequestEnd();
-    logResponseError(err);
+    devHttpLog(() => logResponseError(err));
     const resData = err.response?.data;
+    // 공통 봉투가 실패 응답에 실려 온 경우 error 필드 우선
     let raw: unknown =
       isCommonResponsePayload(resData) ? resData.error : undefined;
     if (raw === undefined) {

package/template/web/shared/src/api/commonResponse.ts

@@ -1,17 +1,45 @@
 /**
- * 서버 공통 본문: HTTP 200/201 + body `{ code, data, error }`
- * — 비즈니스 실패는 code !== 0 (HTTP는 정상).
+ * =============================================================================
+ * 공통 API 응답 봉투 — `{ code, data, error }`
+ * =============================================================================
+ *
+ * 전제 (백엔드와의 계약)
+ * ----------------------
+ * - **전송 성공**은 HTTP 상태로 표현: 클라이언트는 200/201 등 2xx를 “통신 OK”로 본다.
+ * - **비즈니스 성공/실패**는 본문의 숫자 `code`로 표현한다. (예: `0` = 성공)
+ * - 실패 시 사용자에게 보여 줄 메시지는 `error` 필드에 둔다 (문자열·객체·배열 등 가변).
+ *
+ * 이 모듈의 책임
+ * --------------
+ * - 봉투 형태인지 판별 (`isCommonResponsePayload`)
+ * - `error`를 사람이 읽을 문자열로 정규화 (`formatCommonErrorField`)
+ * - axios **성공** 인터셉터에서: 성공이면 `response.data`를 안쪽 `data`만 남기고,
+ *   실패면 콜백(토스트) 후 `CommonResponseRejectedError`로 끊기 (`applyCommonResponseEnvelope`)
+ *
+ * 주의
+ * ----
+ * - `code`가 **문자열** `"0"`인 JSON은 봉투로 인식하지 않는다 (`typeof b.code === 'number'`).
+ *   백엔드와 타입을 맞출 것.
  */
 
 import type { AxiosResponse } from 'axios';
 
-/** 백엔드와 동일한 “성공” 코드 */
+/** 백엔드와 동일한 “성공” 코드 (비 0 이면 비즈니스 실패로 처리) */
 export const COMMON_RESPONSE_SUCCESS_CODE = 0 as const;
 
+/**
+ * 봉투 검사를 통과했으나 `code !== 0` 인 경우, 성공 인터셉터에서 throw.
+ * AxiosError가 아니므로 `axios.isAxiosError`로는 구분되지 않음 → catch 분기에서 `instanceof` 사용.
+ */
 export class CommonResponseRejectedError extends Error {
   readonly appCode: number;
   readonly payload: unknown;
 
+  /**
+   * @param message - 사용자/토스트용 문구 (`formatCommonErrorField(error)` 등)
+   * @param appCode - 서버가 돌려준 비즈니스 코드 (0이 아님)
+   * @param payload - 원본 봉투 객체 (디버그·로깅용)
+   */
   constructor(message: string, appCode: number, payload: unknown) {
     super(message);
     this.name = 'CommonResponseRejectedError';
@@ -20,6 +48,11 @@ export class CommonResponseRejectedError extends Error {
   }
 }
 
+/**
+ * 최소한의 봉투 판별: `code`가 number이고 `data` 키가 존재하면 공통 응답으로 본다.
+ * (레거시 API는 이 조건을 만족하지 않으면 그대로 통과)
+ * @param body - axios `response.data` 등
+ */
 export function isCommonResponsePayload(
   body: unknown,
 ): body is { code: number; data: unknown; error?: unknown } {
@@ -28,6 +61,10 @@ export function isCommonResponsePayload(
   return typeof b.code === 'number' && 'data' in b;
 }
 
+/**
+ * 중첩된 `message` 프로퍼티·문자열 배열 등에서 읽을 만한 첫 문자열을 꺼낸다.
+ * @returns 없으면 `null`
+ */
 function extractMessageString(value: unknown): string | null {
   if (value == null) return null;
   if (typeof value === 'string') return value;
@@ -42,7 +79,11 @@ function extractMessageString(value: unknown): string | null {
   return null;
 }
 
-/** `error` 필드를 사용자용 문구로 */
+/**
+ * 서버 `error` 필드를 토스트/로그용 한 줄 문자열로 만든다.
+ * 구조가 복잡하면 JSON.stringify, 실패 시 fallback.
+ * @param error - 봉투의 `error` 필드 (타입 불명)
+ */
 export function formatCommonErrorField(error: unknown): string {
   const extracted = extractMessageString(error);
   if (extracted) return extracted;
@@ -60,7 +101,14 @@ export function formatCommonErrorField(error: unknown): string {
 export type OnCommonBusinessError = (message: string, appCode: number) => void;
 
 /**
- * 성공 인터셉터에서 호출: 공통 래핑이면 code 검사 후 data 로 치환하거나 reject.
+ * axios 성공 콜백 안에서 호출한다.
+ *
+ * - 봉투가 아니면: 아무 것도 하지 않고 반환 (레거시 API).
+ * - 봉투 + `code !== 0`: `onBusinessError` 호출 후 `CommonResponseRejectedError` throw.
+ * - 봉투 + `code === 0`: `response.data`를 `body.data`로 **치환** (이후 파이프라인은 페이로드만 봄).
+ *
+ * @param response - axios 응답 (본문은 아직 봉투일 수 있음)
+ * @param onBusinessError - `code !== 0` 일 때 UI 알림 (예: 토스트)
  */
 export function applyCommonResponseEnvelope(
   response: AxiosResponse,