@xfilecom/xframe 0.1.37 → 0.1.39

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,

package/template/web/shared/src/api/methods/health.method.ts

@@ -1,8 +1,27 @@
+/**
+ * =============================================================================
+ * healthMethod — `execute` / `executeMethod('health')` 레지스트리 항목
+ * =============================================================================
+ *
+ * `fetchHealth`와 차이
+ * ---------------------
+ * - 여기 경로는 **RootStore.execute → sendMessage**를 탄다.
+ * - `showIndicator: false`이면 `sendMessage`가 `skipGlobalIndicator: true`를 넘겨 **전역 로딩 바가 안 뜰** 수 있다.
+ *   (조용한 폴링·백그라운드 동기화에 맞춤.)
+ *
+ * `unwrapDataArray: false`
+ * ------------------------
+ * - 코어 SDK 스타일 `{ data: [...] }` 언래핑을 하지 않고 응답을 그대로 쓴다.
+ * - health 본문이 단일 객체이면 그대로 두면 된다.
+ */
+
 import type { HealthData } from '../../types/api';
 import type { ApiMethodConfig, ApiMethodStore } from '../types';
 import { healthEndpoint } from '@shared/endpoint';
 
-/** GET /health — params·body 없음, 스토어는 validate/post 에서 사용 가능 */
+/**
+ * `executeMethod('health')`용 설정. `showIndicator: false`로 전역 바 억제에 맞출 수 있음.
+ */
 export const healthMethod: ApiMethodConfig<void, HealthData, ApiMethodStore> = {
   schema: {},
   endpoint: healthEndpoint,

package/template/web/shared/src/api/methods/index.ts

@@ -1,5 +1,12 @@
 /**
- * 화면별 workflow registry — 새 method 는 *.method.ts 추가 후 여기 등록
+ * =============================================================================
+ * API Method 레지스트리 + ParamStore 초기 스키마
+ * =============================================================================
+ *
+ * - **methods**: `RootStore.executeMethod('health')` 등으로 이름 기반 호출할 워크플로 정의.
+ *   새 API 묶음은 `*.method.ts`로 추가하고 `methods` 객체에 키를 등록한다.
+ * - **screenParamSchemas**: `ParamStore`가 부팅 시 들고 있을 화면→필드 기본값.
+ *   `execute` 전 `validate`에서 `paramStore.isScreenValid(...)` 같은 식으로 연동 가능.
  */
 
 import type { ParamsSchema } from '../../params/types';

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

@@ -1,10 +1,31 @@
 /**
- * EndpointDef — path `:param` 치환, query/body, skipGlobalIndicator
+ * =============================================================================
+ * `sendRequest` — EndpointDef 기반 단발 HTTP 호출
+ * =============================================================================
+ *
+ * 이 함수는 **도메인 로직이 없다**. 오직 다음만 수행한다:
+ * - `path`의 `:param` 플레이스홀더 치환
+ * - querystring 조립
+ * - GET/DELETE vs POST/PUT/PATCH 에 따른 body 실을지 여부
+ * - `apiClient.request` 호출 → 인터셉터(토큰·봉투·로깅·전역 로딩) 전부 적용
+ * - 응답 본문에 `endpoint.post`가 있으면 한 번 더 가공 (레거시 언래핑 등)
+ *
+ * `RootStore.sendMessage`와 `fetchHealth` 같은 얇은 헬퍼는 모두 여기로 모인다.
+ *
+ * `skipGlobalIndicator`
+ * ---------------------
+ * `true`이면 해당 요청은 axios 인터셉터의 `onRequestStart`/`End`를 건너뛴다.
+ * `sendMessage`는 `showIndicator`와 연동해 `skipGlobalIndicator: !showIndicator`로 넘긴다.
  */
 
 import type { EndpointDef } from '@shared/endpoint';
 import { apiClient } from './client';
 
+/**
+ * `path` 안의 `:키` 토큰을 `params[키]` 값으로 치환한다.
+ * @param path - 예: `/users/:id`
+ * @param params - 예: `{ id: '42' }` → `/users/42` (값은 encodeURIComponent 처리)
+ */
 function buildPath(path: string, params?: Record<string, string>): string {
   if (!params) return path;
   let out = path;
@@ -14,6 +35,10 @@ function buildPath(path: string, params?: Record<string, string>): string {
   return out;
 }
 
+/**
+ * 객체를 `?a=1&b=2` 형태의 쿼리 문자열로 만든다.
+ * `undefined`·빈 문자열 키는 제외한다.
+ */
 function buildQuery(query?: Record<string, string | number | boolean | undefined>): string {
   if (!query) return '';
   const search = new URLSearchParams();
@@ -28,9 +53,16 @@ export interface RequestTransportOptions<T = unknown> {
   params?: Record<string, string>;
   query?: Record<string, string | number | boolean | undefined>;
   body?: T;
+  /** true면 전역 HTTP 인디케이터(카운터)를 이 요청에 대해 쓰지 않음 */
   skipGlobalIndicator?: boolean;
 }
 
+/**
+ * 단일 엔드포인트에 대한 HTTP 요청을 수행하고, 응답 본문(가공 후)을 반환한다.
+ * @param endpoint - 메서드·경로·선택적 `post`·`timeoutMs`·`showIndicator`(sendMessage 경로에서만 의미)
+ * @param options - path 치환·쿼리·body·전역 인디케이터 스킵
+ * @returns `endpoint.post`가 있으면 그 반환값, 없으면 인터셉터까지 거친 `response.data`
+ */
 export async function sendRequest<T = unknown, R = unknown>(
   endpoint: EndpointDef,
   options: RequestTransportOptions<T> = {},

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

@@ -1,5 +1,14 @@
 /**
- * methods.ts / RootStore.execute — RootStore 직접 참조 없이 순환 방지
+ * =============================================================================
+ * ApiMethodConfig 타입 — RootStore.execute 와 공유
+ * =============================================================================
+ *
+ * `ApiMethodStore`는 **RootStore 전체가 아니라** execute 콜백에 필요한 최소 면만 노출한다.
+ * (types → store → types 순환 import 방지)
+ *
+ * - **CoreSdkWrapped**: 백엔드가 `{ data: T | T[] }` 형태로 한 겹 더 싸는 레거시 대응.
+ * - **ApiMethodUiConfig**: 인디케이터·토스트·unwrap 동작을 UI 정책으로 묶음.
+ * - **endpoints**: 단일 `endpoint` 대신 순차 호출할 서브 호출 배열 (다중 배치 시 전역 바 억제와 연동).
  */
 
 import type { EndpointDef } from '@shared/endpoint';

package/template/web/shared/src/context/StoreProvider.tsx

@@ -1,9 +1,33 @@
 /**
- * RootStore 컨텍스트 — useStore / useParamStore / useSendMessage 등
- * (싱글톤 rootStore 이므로 Provider 없이도 rootStore 직접 import 가능)
+ * =============================================================================
+ * StoreProvider — React 트리와 `rootStore`(MobX 싱글톤) 연결
+ * =============================================================================
+ *
+ * 왜 Provider가 있는가?
+ * ----------------------
+ * - `rootStore`는 모듈 싱글톤이라 원칙적으로 어디서든 import 가능하다.
+ * - 그래도 `useStore()`는 **Provider 안에서만** 쓰게 강제해, 테스트 시 mock 주입·
+ *   “스토어 없는 트리” 실수를 막기 쉽게 했다.
+ *
+ * 최상위 UI (앱 전역, 페이지와 무관)
+ * ----------------------------------
+ * 1) **GlobalHttpIndicatorView** — `rootStore.indicator.loading`
+ *    - axios 인터셉터의 `onRequestStart`/`End`가 `_requestDepth`를 올리고,
+ *      깊이가 0→1일 때 상단 얇은 로딩 바를 표시한다.
+ *    - `skipGlobalIndicator` 또는 `execute` 다중 엔드포인트 배치 시에는 동작이 달라질 수 있음.
+ *
+ * 2) **GlobalToastStackView** — `rootStore.toasts` → `@xfilecom/front-core` `ToastList`
+ *    - 행별 `dismissible`: **error**만 닫기. **info/success/warn**은 타이머 자동 제거만.
+ *
+ * 훅들
+ * -----
+ * - `useSendMessage` — `endpoint` + 옵션으로 `rootStore.sendMessage` 래핑
+ * - `useParamStore` / `useSessionStore` / `useRootStore` — 편의 접근자
  */
 
 import React, { createContext, useCallback, useContext } from 'react';
+import { ToastList } from '@xfilecom/front-core';
+import { observer } from 'mobx-react-lite';
 import type { EndpointDef } from '@shared/endpoint';
 import type { SendMessageOptions } from '../types/ui';
 import { rootStore } from '../store/root-store';
@@ -12,16 +36,68 @@ type RootStoreApi = typeof rootStore;
 
 const StoreContext = createContext<RootStoreApi | null>(null);
 
+/**
+ * `rootStore.indicator.loading`이 true일 때만 상단 고정 로딩 바를 렌더한다.
+ * @returns 없으면 `null`
+ */
+const GlobalHttpIndicatorView = observer(function GlobalHttpIndicatorView() {
+  if (!rootStore.indicator.loading) return null;
+  return (
+    <div
+      className="xfc-global-http-indicator"
+      role="progressbar"
+      aria-busy="true"
+      aria-label="Loading"
+    />
+  );
+});
+
+/**
+ * `ToastList` + `ToastEntry.dismissible` — error만 수동 닫기, 나머지는 RootStore 타이머.
+ */
+const GlobalToastStackView = observer(function GlobalToastStackView() {
+  const entries = rootStore.toasts.map((t) => ({
+    id: t.id,
+    severity: t.severity,
+    message: t.message,
+    dismissible: t.severity === 'error',
+  }));
+  return (
+    <ToastList
+      toasts={entries}
+      dismissAriaLabel="닫기"
+      onDismiss={(id) => {
+        rootStore.removeToast(id);
+      }}
+    />
+  );
+});
+
+/**
+ * Provider에 주입된 `rootStore` 반환. Provider 밖이면 예외.
+ */
 export function useStore(): RootStoreApi {
   const ctx = useContext(StoreContext);
   if (!ctx) throw new Error('StoreProvider is required');
   return ctx;
 }
 
+/**
+ * 컨텍스트 + 전역 로딩 바 + 전역 토스트 + 자식 트리.
+ */
 export function StoreProvider({ children }: { children: React.ReactNode }) {
-  return <StoreContext.Provider value={rootStore}>{children}</StoreContext.Provider>;
+  return (
+    <StoreContext.Provider value={rootStore}>
+      <GlobalHttpIndicatorView />
+      <GlobalToastStackView />
+      {children}
+    </StoreContext.Provider>
+  );
 }
 
+/**
+ * `rootStore.sendMessage`를 안정적인 콜백으로 반환.
+ */
 export function useSendMessage() {
   const store = useStore();
   return useCallback(
@@ -32,14 +108,17 @@ export function useSendMessage() {
   );
 }
 
+/** 화면 파라미터 스토어 단축 접근 */
 export function useParamStore() {
   return useStore().paramStore;
 }
 
+/** 토큰·로그아웃 콜백 */
 export function useSessionStore() {
   return useStore().sessionStore;
 }
 
+/** `useStore()`와 동일 — 의미상 “전체 루트” 강조용 별칭 */
 export function useRootStore(): RootStoreApi {
   return useStore();
 }

package/template/web/shared/src/hooks/useAppStore.ts

@@ -1,10 +1,36 @@
+/**
+ * =============================================================================
+ * useAppStore — MobX `rootStore`를 React 18 `useSyncExternalStore`로 구독
+ * =============================================================================
+ *
+ * 사용 패턴
+ * ---------
+ * Zustand의 `useStore(selector)`와 비슷하게, **필요한 조각만** 구독해 리렌더 범위를 줄인다.
+ *
+ *   const n = useAppStore((s) => s.healthData);
+ *   const logout = useAppStore((s) => s.sessionStore.logout); // 주의: 아래 참고
+ *
+ * MobX `reaction`으로 `selector(rootStore)` 결과가 바뀔 때만 `onChange`를 호출한다.
+ *
+ * this 바인딩 주의
+ * ----------------
+ * **클래스 프로토타입 메서드**를 셀렉터로 꺼내 콜백에 넘기면 `this`가 undefined가 된다.
+ * 그 경우 스토어 쪽에서 **화살표 필드 메서드**로 정의하거나, 호출부에서 `.bind(store)` 할 것.
+ * (`setLastHealthAt` 등은 템플릿에서 화살표로 정의해 둠.)
+ *
+ * 대안
+ * ----
+ * 컴포넌트 전체를 `observer()`로 감싸고 `rootStore`를 직접 읽는 방식도 가능하다.
+ * 이 훅은 “일부 필드만” 구독할 때 유리하다.
+ */
+
 import { reaction } from 'mobx';
 import { useSyncExternalStore } from 'react';
 import { rootStore } from '../store/root-store';
 
 /**
- * Zustand 스타일 셀렉터 — RootStore(MobX) 구독
- * 예: `useAppStore((s) => s.lastHealthAt)`, `useAppStore((s) => s.setLastHealthAt)`
+ * @param selector - `rootStore`에서 구독할 조각; 참조 동등이 아니라 MobX 추적 값이 바뀔 때 리렌더
+ * @returns selector의 현재 결과
  */
 export function useAppStore<T>(selector: (store: typeof rootStore) => T): T {
   return useSyncExternalStore(

package/template/web/shared/src/hooks/useHealthStatus.ts

@@ -1,38 +1,57 @@
-import { useEffect, useState } from 'react';
+/**
+ * =============================================================================
+ * useHealthStatus — 데모용 `/health` 폴링 훅
+ * =============================================================================
+ *
+ * 하는 일
+ * --------
+ * - 마운트(및 `apiBaseUrl` 변경) 시 `fetchHealth()` 호출.
+ * - 성공/실패 결과를 `rootStore.healthData` / `rootStore.healthError`에 반영 (`runInAction`은 스토어 메서드 내부).
+ * - 컴포넌트는 `useAppStore`로 `data`·`error`를 구독해 화면에 쓸 수 있다.
+ *
+ * 로딩·에러 UI 정책 (템플릿 기본)
+ * ------------------------------
+ * - **로딩**: 별도 `isLoading` 상태를 두지 않는다. `fetchHealth`는 `sendRequest`를 타므로
+ *   axios → `indicator` → `StoreProvider` 상단 바가 진행을 표시한다.
+ * - **HTTP/비즈니스 에러 메시지**: `client` 인터셉터의 `onError` / `onCommonBusinessError`가
+ *   전역 토스트로 이미 알릴 수 있다. `healthError`는 스토어에 남아 폼·디버그 등에 재사용 가능.
+ *
+ * 언마운트
+ * --------
+ * `cancelled` 플래그로 stale 응답이 스토어를 덮어쓰지 않게 한다.
+ */
+
+import { useEffect } from 'react';
 import { configureApi } from '../api/client';
 import { fetchHealth } from '../methods/health';
-import { safeJsonStringify } from '../utils/safeJsonStringify';
+import { rootStore } from '../store/root-store';
 import { useAppStore } from './useAppStore';
 
 /**
- * @param apiBaseUrl 선택 — 넘기면 `configureApi` 로 baseURL 갱신. 앱 entry 에서 이미 `configureApi` 했다면 생략 가능.
+ * @param apiBaseUrl - 넘기면 effect 안에서 `configureApi`로 baseURL 갱신 (entry에서 이미 했으면 생략 가능)
+ * @returns `{ data, error }` — 둘 다 `rootStore` 기반 구독
  */
 export function useHealthStatus(apiBaseUrl?: string) {
-  const setLastHealthAt = useAppStore((s) => s.setLastHealthAt);
-  const [text, setText] = useState('loading…');
-  const [error, setError] = useState<string | null>(null);
+  const data = useAppStore((s) => s.healthData);
+  const error = useAppStore((s) => s.healthError);
 
   useEffect(() => {
     if (apiBaseUrl != null && apiBaseUrl !== '') {
       configureApi({ baseURL: apiBaseUrl });
     }
     let cancelled = false;
-    setError(null);
-    setText('loading…');
+    rootStore.applyHealthFetchStart();
     fetchHealth()
       .then((body) => {
-        if (!cancelled) {
-          setText(safeJsonStringify(body, 2));
-          setLastHealthAt(Date.now());
-        }
+        if (!cancelled) rootStore.applyHealthFetchSuccess(body);
       })
-      .catch((e: Error) => {
-        if (!cancelled) setError(e.message);
+      .catch((e: unknown) => {
+        if (!cancelled) rootStore.applyHealthFetchFailure(e);
       });
     return () => {
       cancelled = true;
     };
-  }, [apiBaseUrl, setLastHealthAt]);
+  }, [apiBaseUrl]);
 
-  return { text, error };
+  return { data, error };
 }

package/template/web/shared/src/import-meta.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Vite로 번들될 때 `DEV`/`PROD`가 정적으로 치환된다. `web/shared` 단독 `tsc`용 최소 선언.
+ * (소비 앱의 `vite/client`와 필드가 겹쳐도 병합된다.)
+ */
+interface ImportMetaEnv {
+  readonly DEV: boolean;
+  readonly PROD: boolean;
+  readonly MODE: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/template/web/shared/src/methods/health.ts

@@ -1,8 +1,23 @@
+/**
+ * =============================================================================
+ * fetchHealth — `/health` 직접 호출 (스토어·토스트 없음)
+ * =============================================================================
+ *
+ * `useHealthStatus`처럼 UI에서 부를 때 사용한다.
+ * - `sendRequest` → `apiClient` → 인터셉터(토큰·봉투·전역 로딩·로그) 전부 탄다.
+ * - `RootStore.sendMessage`를 쓰지 않으므로 **sendMessage 전용** `showIndicator` 기본값 해석은
+ *   `healthEndpoint.showIndicator`에만 의존하지 않고, `skipGlobalIndicator` 미전달 시 **전역 바**가 뜬다.
+ *
+ * 반환 타입 `HealthData`는 공통 봉투가 제거된 뒤의 본문 형태를 가정한다.
+ */
+
 import { sendRequest } from '../api/request';
 import { healthEndpoint } from '@shared/endpoint';
 import type { HealthData } from '../types/api';
 
-/** 직접 호출용 (토스트 없음) — UI 훅은 보통 이 함수 사용 */
+/**
+ * @returns 봉투 제거 후 `/health` JSON 본문 (`HealthData`)
+ */
 export async function fetchHealth(): Promise<HealthData> {
   return sendRequest<unknown, HealthData>(healthEndpoint, {});
 }

package/template/web/shared/src/store/api-cache-store.ts

@@ -1,3 +1,15 @@
+/**
+ * =============================================================================
+ * ApiCacheStore — 메모리 캐시 (싱글톤, TTL 선택)
+ * =============================================================================
+ *
+ * `RootStore.getCachedOrExecute`가 사용한다.
+ * - `ttlMs`를 주면 `staleAt = now + ttl` 이후 `get` 시 엔트리 삭제 후 `undefined`.
+ * - `ttlMs` 생략 시 `staleAt === 0`으로 “만료 없음”(명시적 `clear` 전까지 유지).
+ *
+ * 영속 저장소나 SWR과는 별개 — 가벼운 중복 요청 방지용.
+ */
+
 import { makeAutoObservable } from 'mobx';
 
 interface CacheEntry<T = unknown> {
@@ -12,6 +24,9 @@ export class ApiCacheStore {
     makeAutoObservable(this);
   }
 
+  /**
+   * 키에 대한 값 반환. TTL이 지났으면 엔트리 삭제 후 `undefined`.
+   */
   get<T = unknown>(key: string): T | undefined {
     const entry = this._entries.get(key);
     if (!entry) return undefined;
@@ -22,11 +37,15 @@ export class ApiCacheStore {
     return entry.value as T;
   }
 
+  /**
+   * @param ttlMs - 생략 시 만료 없음 (`staleAt === 0`)
+   */
   set<T = unknown>(key: string, value: T, ttlMs?: number): void {
     const staleAt = ttlMs != null ? Date.now() + ttlMs : 0;
     this._entries.set(key, { value, staleAt });
   }
 
+  /** 전 엔트리 삭제 (로그아웃 등) */
   clear(): void {
     this._entries.clear();
   }