@xfilecom/xframe 0.1.38 → 0.1.39

package/template/web/shared/src/store/root-store.ts

@@ -1,5 +1,47 @@
 /**
- * Root store — session, param, cache, indicator, execute/sendMessage (business-promotion 패턴 축소판)
+ * =============================================================================
+ * RootStore — 프론트 “앱 오케스트레이션” 허브 (MobX)
+ * =============================================================================
+ *
+ * 포함 관계
+ * ---------
+ * - **sessionStore** (싱글톤): JWT 등 — `api/client`가 Authorization 헤더에 반영.
+ * - **apiCacheStore** (싱글톤): `getCachedOrExecute`용 짧은 TTL 캐시.
+ * - **paramStore** (인스턴스): 화면별 URL/폼 파라미터 스키마. `getStore: () => this`로
+ *   검증 시 RootStore에 접근 가능.
+ *
+ * HTTP / UI 연동 (가장 중요)
+ * ---------------------------
+ * 생성자에서 `setApiHooks`로 axios와 연결한다:
+ *
+ * | 훅 | 호출 시점 | 템플릿 기본 동작 |
+ * |----|-----------|------------------|
+ * | onRequestStart/End | 각 apiClient 요청 (skip 아닐 때) | `_requestDepth` 증감 → `indicator.loading` |
+ * | onError | HTTP 실패 응답·네트워크 등 | `addToast(..., 'error')` |
+ * | onCommonBusinessError | HTTP 2xx + 본문 `code !== 0` | 동일 |
+ *
+ * 따라서 **대부분의 API 에러 알림은 페이지가 아니라 여기서 토스트**로 처리된다.
+ * `sendMessage` / `execute`의 catch에서는 `axios.isAxiosError`·`CommonResponseRejectedError`일 때
+ * **중복 토스트를 피하도록** 이미 인터셉터에서 처리된 경우를 건너뛴다.
+ *
+ * 토스트 UX (템플릿 기본)
+ * ----------------------
+ * - **error**: 자동 제거 없음 — 사용자가 닫기만 가능 (`StoreProvider`에서 `dismissible` true).
+ * - **info / success / warn**: `TOAST_AUTO_DISMISS_MS` 후 자동 제거, 닫기 버튼 없음.
+ *
+ * execute / sendMessage
+ * ----------------------
+ * - **sendMessage**: 단일 `EndpointDef` + 옵션. `showIndicator`에 따라 (1) 로컬 `setIndicator`와
+ *   (2) axios `skipGlobalIndicator`를 맞춘다. 전역 바만 쓰려면 엔드포인트/`showIndicator` 정책을 통일할 것.
+ * - **execute**: `ApiMethodConfig` 기반 워크플로 — 검증, `sendMessage` 또는 다중 `sendRequest`,
+ *   `post` 훅, `redirectPath`, 토스트 옵션 등.
+ * - **다중 엔드포인트 배치** (`config.endpoints`): `_multiEndpointBatch`로 axios 전역 카운터를
+ *   잠시 억제하는 패턴이 있음(배치 중 개별 요청이 바를 깜빡이지 않게).
+ *
+ * Health 데모 필드
+ * ----------------
+ * `healthData`, `healthError`, `lastHealthAt` — `useHealthStatus` + 샘플 UI용.
+ * 프로덕션 앱에서는 도메인 스토어로 옮기거나 제거해도 된다.
  */
 
 import axios from 'axios';
@@ -31,10 +73,17 @@ import type { ApiErrorItem, IndicatorState, SendMessageOptions, ToastItem } from
 import type { ToastSeverity } from '../types/ui';
 import type { HealthData } from '../types/api';
 
+/** 토스트·에러 항목 등에 쓰는 짧은 고유 id (타임스탬프 + 랜덤) */
 function genId() {
   return `id_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
 }
 
+/**
+ * 코어 SDK 스타일 `{ data: T | T[] }` 래핑을 한 겹 벗긴다.
+ * 배열이면 첫 요소를 대표값으로 쓰는 레거시 규칙이 있음 (`unwrapDataArray`).
+ * @param res - API 응답 본문(또는 이미 펼친 T)
+ * @param unwrapDataArray - false면 `res`를 그대로 T로 취급
+ */
 function unwrapCoreSdk<T>(res: T | CoreSdkWrapped<T>, unwrapDataArray: boolean): T | null {
   if (!unwrapDataArray) return res as T;
   const r = res as CoreSdkWrapped<T>;
@@ -45,6 +94,9 @@ function unwrapCoreSdk<T>(res: T | CoreSdkWrapped<T>, unwrapDataArray: boolean):
   return res as T;
 }
 
+/**
+ * API 에러 본문 등에서 사람이 읽을 문자열 후보를 재귀적으로 추출한다.
+ */
 function extractMessageString(value: unknown): string | null {
   if (value == null) return null;
   if (typeof value === 'string') return value;
@@ -59,6 +111,10 @@ function extractMessageString(value: unknown): string | null {
   return null;
 }
 
+/**
+ * `sendMessage`/`execute` catch 등에서 토스트에 넣을 문구를 만든다.
+ * @param e - AxiosError, CommonResponseRejectedError, 일반 Error 등
+ */
 function getErrorMessage(e: unknown): string {
   if (e instanceof CommonResponseRejectedError) return e.message;
   const err = e as { response?: { data?: unknown }; message?: string };
@@ -81,10 +137,17 @@ export class RootStore {
     getStore: () => this,
   });
 
+  /** 전역 로딩 + (선택) 메시지, 현재 실행 중 method 이름 등 */
   private _indicator: IndicatorState = { loading: false, methodLoading: null };
+  /** 패널용 에러 리스트 — 토스트와 별도 */
   private _errors: ApiErrorItem[] = [];
+  /** StoreProvider 전역 토스트 스택 데이터 소스 */
   private _toasts: ToastItem[] = [];
+  /** info/success/warn 자동 제거용 — `removeToast`·타이머 콜백에서 정리 */
+  private _toastAutoDismissTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** axios onRequestStart가 중첩 호출될 때를 위한 깊이 카운터 */
   private _requestDepth = 0;
+  /** execute 다중 엔드포인트 루프 중 전역 인디케이터 억제 */
   private _multiEndpointBatch = false;
 
   /** 데모·useHealthStatus 용 타임스탬프 */
@@ -94,6 +157,9 @@ export class RootStore {
   healthData: HealthData | null = null;
   healthError: string | null = null;
 
+  /**
+   * MobX 관찰 가능 필드로 등록하고, 세션 로그아웃 시 캐시 비우기·axios 훅을 `rootStore`에 연결한다.
+   */
   constructor() {
     makeAutoObservable(this);
     this.sessionStore.registerLogoutCallback(() => {
@@ -119,30 +185,40 @@ export class RootStore {
     });
   }
 
+  /** 전역 로딩·옵션 메시지·현재 method 로딩 키 */
   get indicator(): IndicatorState {
     return this._indicator;
   }
 
+  /** 패널/리스트용 에러 히스토리 (토스트와 별도) */
   get errors(): ApiErrorItem[] {
     return this._errors;
   }
 
+  /** `GlobalToastStackView`가 구독하는 스택 */
   get toasts(): ToastItem[] {
     return this._toasts;
   }
 
-  /** useAppStore 셀렉터로 넘길 때 this 유지 */
+  /**
+   * 마지막 health 성공 시각(밀리초). 화살표 필드라 `useAppStore(s => s.setLastHealthAt)`로 꺼내 호출해도 안전.
+   * @param t - `Date.now()` 등
+   */
   setLastHealthAt = (t: number) => {
     this.lastHealthAt = t;
   };
 
-  /** 로딩 표시는 `indicator`(axios 훅) — 여기선 에러만 초기화 */
+  /** `/health` 요청 직전: `healthError`만 초기화 (진행 표시는 axios `indicator`) */
   applyHealthFetchStart = () => {
     runInAction(() => {
       this.healthError = null;
     });
   };
 
+  /**
+   * `/health` 성공 시 스토어에 페이로드 반영.
+   * @param data - 인터셉터에서 봉투 제거된 뒤의 본문
+   */
   applyHealthFetchSuccess = (data: HealthData) => {
     runInAction(() => {
       this.healthError = null;
@@ -151,12 +227,16 @@ export class RootStore {
     });
   };
 
+  /**
+   * `/health` 실패 시 `healthError`에 정규화된 메시지 저장 (토스트는 인터셉터가 담당할 수 있음).
+   */
   applyHealthFetchFailure = (err: unknown) => {
     runInAction(() => {
       this.healthError = getErrorMessage(err);
     });
   };
 
+  /** axios `onRequestStart`에서 호출: 중첩 요청 시 깊이만 증가, 첫 요청에서만 `loading: true` */
   private _startRequest() {
     this._requestDepth++;
     if (this._requestDepth === 1) {
@@ -164,6 +244,7 @@ export class RootStore {
     }
   }
 
+  /** axios `onRequestEnd`에서 호출: 깊이 0이 되면 `loading: false` */
   private _endRequest() {
     this._requestDepth = Math.max(0, this._requestDepth - 1);
     if (this._requestDepth === 0) {
@@ -171,41 +252,80 @@ export class RootStore {
     }
   }
 
+  /**
+   * `sendMessage` 등에서 쓰는 로컬 인디케이터(전역 바와 별개로 메시지 동반 가능).
+   */
   setIndicator(loading: boolean, message?: string) {
     this._indicator = { ...this._indicator, loading, message };
   }
 
+  /**
+   * `executeMethod`가 어떤 키를 실행 중인지 UI에 표시할 때 사용.
+   */
   setMethodLoading(methodName: string | null) {
     this._indicator = { ...this._indicator, methodLoading: methodName };
   }
 
+  /**
+   * 토스트가 아닌 “에러 패널”용 항목 추가 (최대 50건 유지).
+   */
   addError(message: string, code?: string | number) {
     this._errors = [{ id: genId(), message, code, createdAt: Date.now() }, ...this._errors].slice(0, 50);
   }
 
+  /** `addError`로 넣은 한 건 제거 */
   clearError(id: string) {
     this._errors = this._errors.filter((e) => e.id !== id);
   }
 
+  /** 에러 패널 전체 비우기 */
   clearAllErrors() {
     this._errors = [];
   }
 
   private static readonly TOAST_AUTO_DISMISS_MS = 2000;
 
+  /**
+   * 동일 메시지+심각도 연속 스팸 방지.
+   * - **error**: 타이머 없음 — 닫기만 제거 (`GlobalToastStackView`에서 error만 `dismissible`).
+   * - **그 외**: `TOAST_AUTO_DISMISS_MS` 후 자동 제거.
+   * @param message - 토스트 본문
+   * @param severity - `info` | `success` | `warn` | `error`
+   */
   addToast(message: string, severity: ToastSeverity = 'info') {
     if (this._toasts.some((t) => t.message === message && t.severity === severity)) return;
     const id = genId();
     this._toasts = [...this._toasts, { id, message, severity, createdAt: Date.now() }].slice(-20);
-    setTimeout(() => {
-      runInAction(() => this.removeToast(id));
-    }, RootStore.TOAST_AUTO_DISMISS_MS);
+    if (severity !== 'error') {
+      const tid = setTimeout(() => {
+        runInAction(() => {
+          this._toastAutoDismissTimers.delete(id);
+          this.removeToast(id);
+        });
+      }, RootStore.TOAST_AUTO_DISMISS_MS);
+      this._toastAutoDismissTimers.set(id, tid);
+    }
   }
 
+  /** 닫기 클릭 또는 비-error 자동 제거 타이머에서 호출 */
   removeToast(id: string) {
+    const pending = this._toastAutoDismissTimers.get(id);
+    if (pending !== undefined) {
+      clearTimeout(pending);
+      this._toastAutoDismissTimers.delete(id);
+    }
     this._toasts = this._toasts.filter((t) => t.id !== id);
   }
 
+  /**
+   * 등록된 `ApiMethodConfig` 워크플로 실행.
+   * - `endpoints` 배열이 있으면 순차 `sendRequest` (다중 배치 플래그 사용).
+   * - 아니면 단일 `sendMessage` 후 unwrap/post/redirect.
+   *
+   * @param config - 엔드포인트·UI 옵션·validate·post·redirectPath 등
+   * @param payload - 메서드 인자(바디/쿼리 빌더에서 사용)
+   * @param ctx - 라우터 `navigate` 등 실행 컨텍스트
+   */
   async execute<TPayload = unknown, TResult = unknown>(
     config: ApiMethodConfig<TPayload, TResult>,
     payload?: TPayload,
@@ -322,6 +442,10 @@ export class RootStore {
     return finalResult;
   }
 
+  /**
+   * `methods` 레지스트리에 등록된 키로 `execute` 호출. `indicator.methodLoading` 설정.
+   * @param methodName - 예: `'health'`
+   */
   async executeMethod<K extends MethodName>(
     methodName: K,
     payload?: (typeof methods)[K] extends ApiMethodConfig<infer P, unknown> ? P : never,
@@ -343,6 +467,11 @@ export class RootStore {
     }
   }
 
+  /**
+   * 캐시 히트 시 네트워크 생략, 미스 시 `executeMethod` 후 저장.
+   * @param cacheKey - 호출자 정의 문자열(화면+파라미터 해시 등)
+   * @param ttlMs - 만료(ms); 생략 시 만료 없음
+   */
   async getCachedOrExecute<K extends MethodName>(
     cacheKey: string,
     methodName: K,
@@ -360,8 +489,13 @@ export class RootStore {
   }
 
   /**
-   * `EndpointDef.post`·`timeoutMs` 는 `sendRequest` 에서 적용.
-   * `showIndicator` 는 options → `endpoint.showIndicator` → `true` 순으로 결정.
+   * 단일 엔드포인트 호출 래퍼.
+   * - `showIndicator`: 옵션 → `endpoint.showIndicator` → 기본 true.
+   * - `skipGlobalIndicator: !showIndicator` 로 axios 전역 바와 로컬 setIndicator를 정렬.
+   * - 에러 시: Axios/봉투 비즈니스 에러는 인터셉터가 이미 토스트 → catch에서는 중복 방지.
+   *
+   * @param endpoint - shared `EndpointDef`
+   * @param options - 쿼리·바디·토스트·인디케이터 옵션
    */
   async sendMessage<T = unknown, R = unknown>(endpoint: EndpointDef, options: SendMessageOptions<T> = {}): Promise<R> {
     const {

package/template/web/shared/src/store/session-store.ts

@@ -1,25 +1,44 @@
+/**
+ * =============================================================================
+ * SessionStore — 인증 세션 (싱글톤)
+ * =============================================================================
+ *
+ * - `token`이 설정되면 `api/client` 요청 인터셉터가 `Authorization: Bearer …`를 붙인다.
+ * - `logout()` / `setToken(null)` 시 `registerLogoutCallback`으로 등록된 루틴 실행
+ *   (템플릿에서는 RootStore가 `apiCacheStore.clear()` 연동).
+ *
+ * 앱별로 refresh 토큰·저장소(localStorage) 동기화는 소비자 앱에서 확장한다.
+ */
+
 import { makeAutoObservable } from 'mobx';
 
-/** Bearer 토큰 등 — api/client 가 Authorization 헤더에 반영 */
 export class SessionStore {
   token: string | null = null;
   private _onLogout?: () => void;
 
+  /** MobX 관찰 필드로 등록 */
   constructor() {
     makeAutoObservable(this);
   }
 
-  /** RootStore 등에서 한 번 등록 — 토큰 제거 시 캐시 비우기 등 */
+  /**
+   * 로그아웃 시 한 번 호출할 콜백 등록 (중복 등록 시 마지막 것이 유효).
+   * @param cb - 예: API 캐시 클리어
+   */
   registerLogoutCallback(cb: () => void) {
     this._onLogout = cb;
   }
 
+  /**
+   * 액세스 토큰 설정. `null`로 두면 Bearer 제거; 이전에 토큰이 있었는데 `null`이면 `_onLogout` 실행.
+   */
   setToken(token: string | null) {
     const had = this.token != null;
     this.token = token;
     if (had && token == null) this._onLogout?.();
   }
 
+  /** `setToken(null)`과 동일 */
   logout() {
     this.setToken(null);
   }

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

@@ -1,5 +1,11 @@
 /**
- * indicator / toast / sendMessage 옵션 — RootStore·api/client 와 공유
+ * =============================================================================
+ * UI 상태 타입 — RootStore·StoreProvider·sendMessage 옵션과 공유
+ * =============================================================================
+ *
+ * - **ToastItem**: MobX 배열 → `GlobalToastStackView`에서 front-core `Toast`로 매핑 (error만 닫기 버튼).
+ * - **IndicatorState**: 전역 로딩 바(`loading`) + (선택) 문구, 현재 method 이름 표시용 슬롯.
+ * - **SendMessageOptions**: `sendRequest`에 그대로 안 넘어가고 RootStore가 해석 후 일부만 전달.
  */
 
 export type ToastSeverity = 'info' | 'success' | 'warn' | 'error';