@xfilecom/xframe 0.1.38 → 0.1.39

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,8 +1,28 @@
 /**
- * RootStore 컨텍스트 — useStore / useParamStore / useSendMessage 등
- * (싱글톤 rootStore 이므로 Provider 없이도 rootStore 직접 import 가능)
+ * =============================================================================
+ * StoreProvider — React 트리와 `rootStore`(MobX 싱글톤) 연결
+ * =============================================================================
  *
- * 최상위 레이어: HTTP 로딩 바(`indicator`) · `rootStore.toasts` → ToastList
+ * 왜 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';
@@ -16,6 +36,10 @@ 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 (
@@ -28,15 +52,20 @@ const GlobalHttpIndicatorView = observer(function GlobalHttpIndicatorView() {
   );
 });
 
+/**
+ * `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);
       }}
@@ -44,12 +73,18 @@ const GlobalToastStackView = observer(function GlobalToastStackView() {
   );
 });
 
+/**
+ * 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}>
@@ -60,6 +95,9 @@ export function StoreProvider({ children }: { children: React.ReactNode }) {
   );
 }
 
+/**
+ * `rootStore.sendMessage`를 안정적인 콜백으로 반환.
+ */
 export function useSendMessage() {
   const store = useStore();
   return useCallback(
@@ -70,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,11 +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)`
- * (프로토타입 메서드는 분리 시 this 가 깨지므로, 콜백으로 쓸 메서드는 스토어에서 화살표 필드로 두거나 `bind` 하세요.)
+ * @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,3 +1,26 @@
+/**
+ * =============================================================================
+ * 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';
@@ -5,8 +28,8 @@ import { rootStore } from '../store/root-store';
 import { useAppStore } from './useAppStore';
 
 /**
- * @param apiBaseUrl 선택 — 넘기면 `configureApi` 로 baseURL 갱신. 앱 entry 에서 이미 `configureApi` 했다면 생략 가능.
- * `data`·`error` 는 `rootStore` 에 저장·`runInAction`; 로딩 표시는 `StoreProvider` 전역 바 + `indicator`(axios).
+ * @param apiBaseUrl - 넘기면 effect 안에서 `configureApi`로 baseURL 갱신 (entry에서 이미 했으면 생략 가능)
+ * @returns `{ data, error }` — 둘 다 `rootStore` 기반 구독
  */
 export function useHealthStatus(apiBaseUrl?: string) {
   const data = useAppStore((s) => s.healthData);

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();
   }