@uniai-fe/uds-templates 0.5.29 → 0.6.1

package/src/weather/types/api.ts

@@ -1,221 +1,549 @@
 import type {
-  KMA_Res_WeatherNow,
-  KMA_Res_WeatherForecast,
-  KMA_Res_Base,
-  KMA_Req_BaseGridCoordinate,
-  KMA_Req_BaseMoments,
-  KMA_Res_AlertType,
-  KMA_Res_AlertLevel,
-  KMA_Res_AlertCommand,
-  KMA_Res_WeatherItem,
-} from "./korea";
+  WeatherApiLocaleOptions,
+  WeatherCoordinate,
+  WeatherGeoCoordinate,
+  WeatherGridCoordinate,
+} from "./base";
 
-export type API_Req_WeatherKoreaGrid = KMA_Req_BaseGridCoordinate;
-export type API_Req_WeatherKoreaMoments = KMA_Req_BaseMoments;
+/**
+ * Weather backend; 농장/좌표/locale 공통 요청 옵션.
+ * @property {number|string|null} [farm_idx] 농장 식별자
+ * @property {number|null} [lat] 위도
+ * @property {number|null} [lng] 경도
+ * @property {number|null} [nx] backend 격자 X
+ * @property {number|null} [ny] backend 격자 Y
+ * @property {string} [base_date] 현재/예보 단일 route 재현용 날짜
+ * @property {string} [base_time] 현재/예보 단일 route 재현용 시각
+ * @property {string} [now_base_date] summary 현재 날씨 재현용 날짜
+ * @property {string} [now_base_time] summary 현재 날씨 재현용 시각
+ * @property {string} [forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @property {string} [forecast_base_time] summary 예보 날씨 재현용 시각
+ * @property {string} [locale] 요청 언어 코드
+ * @property {boolean} [include_raw] 원본 응답 포함 여부
+ */
+export interface API_Req_Weather
+  extends
+    WeatherApiLocaleOptions,
+    Partial<WeatherGeoCoordinate>,
+    Partial<WeatherGridCoordinate> {
+  /**
+   * 농장 식별자
+   */
+  farm_idx?: number | string | null;
+  /**
+   * 위도
+   */
+  lat?: number | null;
+  /**
+   * 경도
+   */
+  lng?: number | null;
+  /**
+   * backend 격자 X
+   */
+  nx?: number | null;
+  /**
+   * backend 격자 Y
+   */
+  ny?: number | null;
+  /**
+   * 현재/예보 단일 route 재현용 날짜
+   */
+  base_date?: string;
+  /**
+   * 현재/예보 단일 route 재현용 시각
+   */
+  base_time?: string;
+  /**
+   * summary 현재 날씨 재현용 날짜
+   */
+  now_base_date?: string;
+  /**
+   * summary 현재 날씨 재현용 시각
+   */
+  now_base_time?: string;
+  /**
+   * summary 예보 날씨 재현용 날짜
+   */
+  forecast_base_date?: string;
+  /**
+   * summary 예보 날씨 재현용 시각
+   */
+  forecast_base_time?: string;
+  /**
+   * 요청 언어 코드
+   */
+  locale?: string;
+  /**
+   * 원본 응답 포함 여부
+   */
+  include_raw?: boolean;
+}
+
+/**
+ * Weather backend; 현재 날씨 요청.
+ */
+export type API_Req_WeatherNow = API_Req_Weather;
+
+/**
+ * Weather backend; 예보 날씨 요청.
+ */
+export type API_Req_WeatherForecast = API_Req_Weather;
+
+/**
+ * Weather backend; summary 요청.
+ */
+export type API_Req_WeatherSummary = API_Req_Weather;
+
+/**
+ * Weather backend; 특보 요청 파라미터.
+ * @property {number|string|null} farm_idx 농장 식별자
+ */
+export interface API_Req_WeatherAlert {
+  /**
+   * 농장 식별자
+   */
+  farm_idx: number | string | null;
+}
+
+/**
+ * Weather Client; local route 경로 옵션.
+ * @property {string} [routePath] service app의 local weather route 경로
+ */
+export interface WeatherClientRouteOptions {
+  /**
+   * service app의 local weather route 경로
+   */
+  routePath?: string;
+}
+
+/**
+ * Weather Client; React Query 실행 옵션.
+ * @property {boolean} [enabled] query 실행 여부
+ */
+export interface WeatherQueryOptions {
+  /**
+   * query 실행 여부
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Weather Client; local route 경로와 query 실행 옵션.
+ * @property {string} [routePath] service app의 local weather route 경로
+ * @property {boolean} [enabled] query 실행 여부
+ */
+export interface WeatherClientQueryOptions
+  extends WeatherClientRouteOptions, WeatherQueryOptions {
+  /**
+   * service app의 local weather route 경로
+   */
+  routePath?: string;
+  /**
+   * query 실행 여부
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Weather Server; backend proxy route 입력.
+ * @property {string} domain backend API domain
+ * @property {string} routeUrl service app local route URL
+ * @property {URLSearchParams} searchParams service app local route query
+ */
+export interface WeatherServerRouteParams {
+  /**
+   * backend API domain
+   */
+  domain: string;
+  /**
+   * service app local route URL
+   */
+  routeUrl: string;
+  /**
+   * service app local route query
+   */
+  searchParams: URLSearchParams;
+}
 
 /**
- * 기상청 API; 날씨 요청.
+ * Weather Server; backend fetch helper 입력.
+ * @property {string} domain backend API domain
+ * @property {string} routeUrl service app local route URL
+ * @property {URLSearchParams} searchParams service app local route query
+ * @property {string} queryUrl backend weather route URL
+ * @property {"now"|"forecast"|"summary"|"alert"} routeKind backend weather route 종류
+ * @property {Data} fallback 실패 시 반환할 fallback 응답
  */
-export type API_Req_WeatherKorea = API_Req_WeatherKoreaGrid &
-  Partial<API_Req_WeatherKoreaMoments>;
+export type WeatherBackendFetchParams<Data> = WeatherServerRouteParams & {
+  /**
+   * backend weather route URL
+   */
+  queryUrl: string;
+  /**
+   * backend weather route 종류
+   */
+  routeKind: "now" | "forecast" | "summary" | "alert";
+  /**
+   * 실패 시 반환할 fallback 응답
+   */
+  fallback: Data;
+};
 
 /**
- * 기상청 API; 특보 요청 파라미터
- * @property {number | null} farm_idx 농장 식별자
+ * Weather Hook; 통합 weather 조회 옵션.
+ * @property {string} [locale] 요청 언어 코드
+ * @property {boolean} [enabled] query 실행 여부
  */
-export type API_Req_WeatherKoreaAlert = { farm_idx: number | null };
+export interface UseWeatherOptions extends WeatherApiLocaleOptions {
+  /**
+   * 요청 언어 코드
+   */
+  locale?: string;
+  /**
+   * query 실행 여부
+   */
+  enabled?: boolean;
+}
 
 /**
- * 기상청 API; 특보 응답 타입 - 지역별 특보정보
+ * Weather Hook; 통합 weather query 결과.
+ * @property {API_Req_Weather} params weather summary 요청 파라미터
+ * @property {WeatherCoordinate} coordinate 현재 지역 좌표
+ * @property {number|null} farm_idx 특보 조회에 사용할 농장 식별자
+ * @property {API_Res_WeatherSummary} [summary] summary 응답
+ * @property {API_Res_WeatherNow} [now] 현재 날씨 응답
+ * @property {API_Res_WeatherForecast} [forecast] 예보 날씨 응답
+ * @property {API_Res_WeatherAlertItem[]} alert 특보 목록
+ * @property {boolean} isFetching 현재/예보/특보 조회 상태
+ * @property {boolean} isFetchingNow 현재 날씨 조회 상태
+ * @property {boolean} isFetchingForecast 예보 날씨 조회 상태
+ * @property {boolean} isFetchingAlert 특보 조회 상태
  */
-export type API_Res_WeatherKoreaAlertEach = {
+export interface UseWeatherReturn {
+  /**
+   * weather summary 요청 파라미터
+   */
+  params: API_Req_Weather;
+  /**
+   * 현재 지역 좌표
+   */
+  coordinate: WeatherCoordinate;
+  /**
+   * 특보 조회에 사용할 농장 식별자
+   */
+  farm_idx: number | null;
+  /**
+   * summary 응답
+   */
+  summary?: API_Res_WeatherSummary;
+  /**
+   * 현재 날씨 응답
+   */
+  now?: API_Res_WeatherNow;
+  /**
+   * 예보 날씨 응답
+   */
+  forecast?: API_Res_WeatherForecast;
+  /**
+   * 특보 목록
+   */
+  alert: API_Res_WeatherAlertItem[];
+  /**
+   * 현재/예보/특보 조회 상태
+   */
+  isFetching: boolean;
+  /**
+   * 현재 날씨 조회 상태
+   */
+  isFetchingNow: boolean;
+  /**
+   * 예보 날씨 조회 상태
+   */
+  isFetchingForecast: boolean;
+  /**
+   * 특보 조회 상태
+   */
+  isFetchingAlert: boolean;
+}
+
+/**
+ * Weather Hook; 통합 weather alert 조회 옵션.
+ * @property {boolean} [enabled] query 실행 여부
+ */
+export interface UseWeatherAlertOptions {
+  /**
+   * query 실행 여부
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Weather Hook; 통합 weather alert query 결과.
+ * @property {number|null} farm_idx 특보 조회에 사용할 농장 식별자
+ * @property {API_Res_WeatherAlertItem[]} alert 특보 목록
+ * @property {boolean} isFetching 특보 조회 상태
+ */
+export interface UseWeatherAlertReturn {
+  /**
+   * 특보 조회에 사용할 농장 식별자
+   */
+  farm_idx: number | null;
+  /**
+   * 특보 목록
+   */
+  alert: API_Res_WeatherAlertItem[];
+  /**
+   * 특보 조회 상태
+   */
+  isFetching: boolean;
+}
+
+/**
+ * Weather backend; 특보 종류.
+ */
+export type API_Res_WeatherAlertType = string;
+
+/**
+ * Weather backend; 특보 수준.
+ */
+export type API_Res_WeatherAlertLevel = string;
+
+/**
+ * Weather backend; 특보 명령.
+ */
+export type API_Res_WeatherAlertCommand = string;
+
+/**
+ * Weather backend; 지역별 특보정보.
+ * @property {string} upper_region_code 상위 지역 코드
+ * @property {string} upper_region_name 상위 지역 이름
+ * @property {string} alert_region_code 특보 지역 코드
+ * @property {string} alert_region_name 특보 지역 이름
+ * @property {string} announcement_time 특보 발표시간
+ * @property {string} effective_time 특보 발효시간
+ * @property {API_Res_WeatherAlertType} alert_type 특보 종류
+ * @property {API_Res_WeatherAlertLevel} alert_level 특보 수준
+ * @property {API_Res_WeatherAlertCommand} alert_command 특보 명령
+ * @property {string} cancel_notice_time 특보 해제 예고시점
+ */
+export type API_Res_WeatherAlertItem = {
   /**
    * 상위 지역 코드
-   * @see https://apihub.kma.go.kr/api/typ01/url/wrn_reg.php?tmfc=0&authKey=njld-D40Rb25Xfg-NAW9hA
    */
   upper_region_code: string;
   /**
    * 상위 지역 이름
-   * @see https://apihub.kma.go.kr/api/typ01/url/wrn_reg.php?tmfc=0&authKey=njld-D40Rb25Xfg-NAW9hA
    */
   upper_region_name: string;
   /**
    * 특보 지역 코드
-   * @see https://apihub.kma.go.kr/api/typ01/url/wrn_reg.php?tmfc=0&authKey=njld-D40Rb25Xfg-NAW9hA
    */
   alert_region_code: string;
   /**
    * 특보 지역 이름
-   * @see https://apihub.kma.go.kr/api/typ01/url/wrn_reg.php?tmfc=0&authKey=njld-D40Rb25Xfg-NAW9hA
    */
   alert_region_name: string;
   /**
    * 특보 발표시간
-   * - yyyymmddhhmm
    */
   announcement_time: string;
   /**
    * 특보 발효시간
-   * - yyyymmddhhmm
    */
   effective_time: string;
-  /** * 특보 종류 (한글) */
-  alert_type: KMA_Res_AlertType;
   /**
-   * 특보 수준 (한글)
-   * - 경보, 주의, 예비
+   * 특보 종류
    */
-  alert_level: KMA_Res_AlertLevel;
+  alert_type: API_Res_WeatherAlertType;
   /**
-   * 특보 명령 (한글)
-   * - 발표, 변경, 해제
+   * 특보 수준
    */
-  alert_command: KMA_Res_AlertCommand;
+  alert_level: API_Res_WeatherAlertLevel;
   /**
-   * 특보 해제 예고시점 (한글)
-   * - dd일 오전/오후/밤(HH시 ~ HH시)
+   * 특보 명령
+   */
+  alert_command: API_Res_WeatherAlertCommand;
+  /**
+   * 특보 해제 예고시점
    */
   cancel_notice_time: string;
 };
+
 /**
- * 기상청 API; 특보 응답 타입
+ * Weather backend; 특보 응답 타입.
+ * @property {string|null} api_announcement_time 특보 발표 시간
+ * @property {number} total_count 총 특보 개수
+ * @property {API_Res_WeatherAlertItem[]} alerts 지역별 특보
  */
-export type API_Res_WeatherKoreaAlert = {
-  /** * 특보 발표 시간 */
+export type API_Res_WeatherAlert = {
+  /**
+   * 특보 발표 시간
+   */
   api_announcement_time: string | null;
-  /** * 총 특보 개수 */
+  /**
+   * 총 특보 개수
+   */
   total_count: number;
-  /** * 지역별 특보 */
-  alerts: API_Res_WeatherKoreaAlertEach[];
+  /**
+   * 지역별 특보
+   */
+  alerts: API_Res_WeatherAlertItem[];
 };
 
 /**
- * 기상청 API; 기초 정보
- * @property {string} condition - 개황 정보
+ * Weather backend; 기초 정보.
+ * @property {string|null} sky 하늘상태 코드
+ * @property {string|null} drop 강수형태 코드
+ * @property {string|null} rainAmount 강수량 코드
+ * @property {string|null} snowAmount 강설량 코드
+ * @property {string|null} windSpeed 풍속 코드
+ * @property {string|null} condition 날씨 상태 코드
+ * @property {string|null} conditionName 날씨 상태 텍스트
  */
-export type API_Res_WeatherKoreaBase = {
+export type API_Res_WeatherBase = {
   /**
    * 하늘상태 코드
-   * - 1(맑음)
-   * - 2(구름조금)
-   * - 3(구름많음)
-   * - 4(흐림)
    */
   sky: string | null;
   /**
    * 강수형태 코드
-   * - 0(없음)
-   * - 1(비)
-   * - 2(비/눈)
-   * - 3(눈)
-   * - 4(소나기)
    */
   drop: string | null;
   /**
    * 강수량 코드
-   * - 1(약한 비); 3mm/h 미만
-   * - 2(보통 비); 3mm/h 이상 15mm/h 미만
-   * - 3(강한 비); 15mm/h 이상
    */
   rainAmount: string | null;
   /**
    * 강설량 코드
-   * - 1(보통 눈); 1cm/h 미만
-   * - 2(많은 눈); 1cm/h 이상
    */
   snowAmount: string | null;
   /**
    * 풍속 코드
-   * - 1(약한 바람); 4m/s 미만
-   * - 2(약간 강한 바람); 4m/s 이상 9m/s 미만
-   * - 3(강한 바람); 9m/s 이상
    */
   windSpeed: string | null;
   /**
    * 날씨 상태 코드
-   * - sky-1(맑음)
-   * - sky-2(구름조금)
-   * - sky-3(구름많음)
-   * - sky-4(흐림)
-   * - drop-rain-shower(소나기)
-   * - drop-rain(비)
-   * - drop-rain-1(약한 비)
-   * - drop-rain-2(보통 비)
-   * - drop-rain-3(강한 비)
-   * - drop-rain-snow(비/눈)
-   * - drop-rain-snow-1(약한 비/눈)
-   * - drop-rain-snow-2(보통 비/눈)
-   * - drop-rain-snow-3(강한 비/눈)
-   * - drop-snow(눈)
-   * - drop-snow-1(보통 눈)
-   * - drop-snow-2(많은 눈)
    */
   condition: string | null;
-  /** 날씨 상태 텍스트 */
+  /**
+   * 날씨 상태 텍스트
+   */
   conditionName: string | null;
 };
 
 /**
- * 기상청 API; 오늘 날씨
+ * Weather backend; 오늘 날씨.
  * @property {number|string|null} temperature 기온(℃)
  * @property {number|string|null} max_temperature 최고기온(℃)
  * @property {number|string|null} min_temperature 최저기온(℃)
  * @property {number|string|null} humidity 습도(%)
  */
-export type API_Res_WeatherKoreaToday = API_Res_WeatherKoreaBase & {
-  /** 기온(℃) */
+export type API_Res_WeatherToday = API_Res_WeatherBase & {
+  /**
+   * 기온(℃)
+   */
   temperature: number | string | null;
-  /** 최고 기온(℃) */
+  /**
+   * 최고 기온(℃)
+   */
   max_temperature: number | string | null;
-  /** 최저 기온(℃) */
+  /**
+   * 최저 기온(℃)
+   */
   min_temperature: number | string | null;
-  /** 습도(%) */
+  /**
+   * 습도(%)
+   */
   humidity: number | string | null;
 };
 
 /**
- * 기상청 API; 내일/모레 날씨
+ * Weather backend; 내일/모레 날씨.
  * @property {number|string|null} max_temperature 최고기온(℃)
  * @property {number|string|null} min_temperature 최저기온(℃)
  */
-export type API_Res_WeatherKoreaNextDays = API_Res_WeatherKoreaBase & {
-  /** 최고 기온(℃) */
+export type API_Res_WeatherNextDays = API_Res_WeatherBase & {
+  /**
+   * 최고 기온(℃)
+   */
   max_temperature: number | string | null;
-  /** 최저 기온(℃) */
+  /**
+   * 최저 기온(℃)
+   */
   min_temperature: number | string | null;
 };
 
 /**
- * 기상청 API; 원본 응답
- * @property {RAW} raw API 원본 데이터
+ * Weather backend; 공통 응답 메타.
+ * @property {string|null} [source] backend weather source
+ * @property {boolean} [fallback_used] fallback 사용 여부
+ * @property {unknown} [raw] include_raw 요청 시 원본 응답
  */
-export type API_Res_WeatherKoreaRaw<RAW = KMA_Res_Base<KMA_Res_WeatherItem>> = {
-  /** API 원본 */
-  raw: RAW;
+export interface API_Res_WeatherBackendMeta {
+  /**
+   * backend weather source
+   */
+  source?: string | null;
+  /**
+   * fallback 사용 여부
+   */
+  fallback_used?: boolean;
+  /**
+   * include_raw 요청 시 원본 응답
+   */
+  raw?: unknown;
+}
+
+/**
+ * Weather backend; 현재 날씨 구조.
+ * @property {API_Res_WeatherToday} today 오늘 데이터
+ */
+export type API_Res_WeatherNow = API_Res_WeatherBackendMeta & {
+  /**
+   * 오늘 날씨
+   */
+  today: API_Res_WeatherToday;
 };
 
 /**
- * 기상청 API; 초단기 실황 구조
- * @property {API_Res_WeatherKoreaToday} today 오늘 데이터
+ * Weather backend; 예보 날씨 구조.
+ * @property {API_Res_WeatherToday} today 오늘 데이터
+ * @property {API_Res_WeatherNextDays} day_1 내일 데이터
+ * @property {API_Res_WeatherNextDays} day_2 모레 데이터
  */
-export type API_Res_WeatherKoreaNow =
-  API_Res_WeatherKoreaRaw<KMA_Res_WeatherNow> & {
-    /** 오늘 날씨 */
-    today: API_Res_WeatherKoreaToday;
-  };
+export type API_Res_WeatherForecast = API_Res_WeatherBackendMeta & {
+  /**
+   * 오늘 날씨
+   */
+  today: API_Res_WeatherToday;
+  /**
+   * 내일 날씨
+   */
+  day_1: API_Res_WeatherNextDays;
+  /**
+   * 모레 날씨
+   */
+  day_2: API_Res_WeatherNextDays;
+};
 
 /**
- * 기상청 API; 단기 예보 구조
- * @property {API_Res_WeatherKoreaToday} today 오늘 데이터
- * @property {API_Res_WeatherKoreaNextDays} day_1 내일 데이터
- * @property {API_Res_WeatherKoreaNextDays} day_2 모레 데이터
+ * Weather backend; summary 구조.
+ * @property {API_Res_WeatherNow} now 현재 날씨
+ * @property {API_Res_WeatherForecast} forecast 예보 날씨
+ * @property {API_Res_WeatherAlert} alert 특보
  */
-export type API_Res_WeatherKoreaForecast =
-  API_Res_WeatherKoreaRaw<KMA_Res_WeatherForecast> & {
-    /** 오늘 날씨 */
-    today: API_Res_WeatherKoreaToday;
-    /** 내일 날씨 */
-    day_1: API_Res_WeatherKoreaNextDays;
-    /** 모레 날씨 */
-    day_2: API_Res_WeatherKoreaNextDays;
-  };
+export type API_Res_WeatherSummary = {
+  /**
+   * 현재 날씨
+   */
+  now: API_Res_WeatherNow;
+  /**
+   * 예보 날씨
+   */
+  forecast: API_Res_WeatherForecast;
+  /**
+   * 특보
+   */
+  alert: API_Res_WeatherAlert;
+};