@uniai-fe/uds-templates 0.5.28 → 0.6.0

package/src/weather/types/page-header.ts

@@ -1,15 +1,12 @@
 import type {
-  API_Res_WeatherKoreaForecast,
-  API_Res_WeatherKoreaNextDays,
-  API_Res_WeatherKoreaNow,
+  API_Res_WeatherAlertItem,
+  API_Res_WeatherForecast,
+  API_Res_WeatherNextDays,
+  API_Res_WeatherNow,
 } from "./api";
-import type {
-  OWM_Res_Weather_Forecast,
-  OWM_Res_Weather_Now,
-} from "./open-weather-map";
 
 /**
- * Weather Page Header; locale 옵션
+ * Weather Page Header; locale 옵션.
  * @property {string} [locale] 표시 언어 코드. 기본 지원값은 ko, en, ja이며 타입은 확장 가능한 string으로 유지한다.
  */
 export interface WeatherLocaleOptions {
@@ -20,7 +17,7 @@ export interface WeatherLocaleOptions {
 }
 
 /**
- * Weather Page Header; 텍스트 옵션
+ * Weather Page Header; 텍스트 옵션.
  * @property {string} currentWeatherLoading 현재 날씨 로딩 문구
  * @property {string} forecastWeatherLoading 예보 날씨 로딩 문구
  * @property {string} alertLoading 특보 로딩 문구
@@ -106,11 +103,15 @@ export interface WeatherPageHeaderTexts {
 }
 
 /**
- * Weather Page Header; locale과 텍스트 override 조합 옵션
+ * Weather Page Header; locale과 텍스트 override 조합 옵션.
  * @property {string} [locale] 표시 언어 코드
  * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
  */
 export interface WeatherPageHeaderLocaleOptions extends WeatherLocaleOptions {
+  /**
+   * 표시 언어 코드
+   */
+  locale?: string;
   /**
    * 서비스에서 주입한 표시 문구
    */
@@ -118,47 +119,32 @@ export interface WeatherPageHeaderLocaleOptions extends WeatherLocaleOptions {
 }
 
 /**
- * Weather Page Header; KMA weather query 결과
- * @property {API_Res_WeatherKoreaNow} [now] 현재 날씨 응답
- * @property {API_Res_WeatherKoreaForecast} [forecast] 예보 날씨 응답
+ * Weather Page Header; 통합 weather query 결과.
+ * @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 interface WeatherPageHeaderKoreaWeather {
+export interface WeatherPageHeaderWeather {
   /**
    * 현재 날씨 응답
    */
-  now?: API_Res_WeatherKoreaNow;
+  now?: API_Res_WeatherNow;
   /**
    * 예보 날씨 응답
    */
-  forecast?: API_Res_WeatherKoreaForecast;
-  /**
-   * 현재 날씨 조회 상태
-   */
-  isFetchingNow: boolean;
-  /**
-   * 예보 날씨 조회 상태
-   */
-  isFetchingForecast: boolean;
-}
-
-/**
- * Weather Page Header; OpenWeatherMap query 결과
- * @property {OWM_Res_Weather_Now} [now] 현재 날씨 응답
- * @property {OWM_Res_Weather_Forecast} [forecast] 예보 날씨 응답
- * @property {boolean} isFetchingNow 현재 날씨 조회 상태
- * @property {boolean} isFetchingForecast 예보 날씨 조회 상태
- */
-export interface WeatherPageHeaderOpenWeatherMapWeather {
+  forecast?: API_Res_WeatherForecast;
   /**
-   * 현재 날씨 응답
+   * 특보 목록
    */
-  now?: OWM_Res_Weather_Now;
+  alert: API_Res_WeatherAlertItem[];
   /**
-   * 예보 날씨 응답
+   * 현재/예보/특보 조회 상태
    */
-  forecast?: OWM_Res_Weather_Forecast;
+  isFetching: boolean;
   /**
    * 현재 날씨 조회 상태
    */
@@ -167,73 +153,137 @@ export interface WeatherPageHeaderOpenWeatherMapWeather {
    * 예보 날씨 조회 상태
    */
   isFetchingForecast: boolean;
+  /**
+   * 특보 조회 상태
+   */
+  isFetchingAlert: boolean;
 }
 
 /**
- * Weather Page Header; 상위 container에서 준비한 weather query 결과
- * @property {WeatherPageHeaderKoreaWeather} [koreaWeather] KMA weather query 결과
- * @property {WeatherPageHeaderOpenWeatherMapWeather} [openWeatherMapWeather] OpenWeatherMap query 결과
+ * Weather Page Header; 상위 container에서 준비한 weather query 결과.
+ * @property {WeatherPageHeaderWeather} [weather] 통합 weather query 결과
  */
 export interface WeatherPageHeaderDataOptions {
   /**
-   * KMA weather query 결과
+   * 통합 weather query 결과
    */
-  koreaWeather?: WeatherPageHeaderKoreaWeather;
-  /**
-   * OpenWeatherMap query 결과
-   */
-  openWeatherMapWeather?: WeatherPageHeaderOpenWeatherMapWeather;
+  weather?: WeatherPageHeaderWeather;
 }
 
 /**
- * Weather Page Header; container props
+ * Weather Page Header; container props.
  * @property {string} [locale] 표시 언어 코드
  * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
  */
-export type WeatherPageHeaderContainerProps = WeatherPageHeaderLocaleOptions;
+export interface WeatherPageHeaderContainerProps extends WeatherPageHeaderLocaleOptions {
+  /**
+   * 표시 언어 코드
+   */
+  locale?: string;
+  /**
+   * 서비스에서 주입한 표시 문구
+   */
+  texts?: Partial<WeatherPageHeaderTexts>;
+}
 
 /**
- * Weather Page Header; address props
+ * Weather Page Header; address props.
  * @property {string} [locale] 표시 언어 코드
  * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
  */
-export type WeatherPageHeaderAddressProps = WeatherPageHeaderLocaleOptions;
+export interface WeatherPageHeaderAddressProps extends WeatherPageHeaderLocaleOptions {
+  /**
+   * 표시 언어 코드
+   */
+  locale?: string;
+  /**
+   * 서비스에서 주입한 표시 문구
+   */
+  texts?: Partial<WeatherPageHeaderTexts>;
+}
 
 /**
- * Weather Page Header; today props
+ * Weather Page Header; today props.
  * @property {string} [locale] 표시 언어 코드
  * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
- * @property {WeatherPageHeaderKoreaWeather} [koreaWeather] KMA weather query 결과
- * @property {WeatherPageHeaderOpenWeatherMapWeather} [openWeatherMapWeather] OpenWeatherMap query 결과
+ * @property {WeatherPageHeaderWeather} [weather] 상위 container에서 준비한 통합 weather query 결과
  */
-export type WeatherPageHeaderTodayProps = WeatherPageHeaderLocaleOptions &
-  WeatherPageHeaderDataOptions;
+export interface WeatherPageHeaderTodayProps
+  extends WeatherPageHeaderLocaleOptions, WeatherPageHeaderDataOptions {
+  /**
+   * 표시 언어 코드
+   */
+  locale?: string;
+  /**
+   * 서비스에서 주입한 표시 문구
+   */
+  texts?: Partial<WeatherPageHeaderTexts>;
+  /**
+   * 통합 weather query 결과
+   */
+  weather?: WeatherPageHeaderWeather;
+}
 
 /**
- * Weather Page Header; forecast props
+ * Weather Page Header; forecast props.
  * @property {string} [locale] 표시 언어 코드
  * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
- * @property {WeatherPageHeaderKoreaWeather} [koreaWeather] KMA weather query 결과
- * @property {WeatherPageHeaderOpenWeatherMapWeather} [openWeatherMapWeather] OpenWeatherMap query 결과
+ * @property {WeatherPageHeaderWeather} [weather] 상위 container에서 준비한 통합 weather query 결과
  */
-export type WeatherPageHeaderForecastProps = WeatherPageHeaderLocaleOptions &
-  WeatherPageHeaderDataOptions;
+export interface WeatherPageHeaderForecastProps
+  extends WeatherPageHeaderLocaleOptions, WeatherPageHeaderDataOptions {
+  /**
+   * 표시 언어 코드
+   */
+  locale?: string;
+  /**
+   * 서비스에서 주입한 표시 문구
+   */
+  texts?: Partial<WeatherPageHeaderTexts>;
+  /**
+   * 통합 weather query 결과
+   */
+  weather?: WeatherPageHeaderWeather;
+}
 
 /**
- * Weather Page Header; alert props
+ * Weather Page Header; alert props.
  * @property {string} [locale] 표시 언어 코드
  * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
+ * @property {WeatherPageHeaderWeather} [weather] 상위 container에서 준비한 통합 weather query 결과
  */
-export type WeatherPageHeaderAlertProps = WeatherPageHeaderLocaleOptions;
+export interface WeatherPageHeaderAlertProps
+  extends WeatherPageHeaderLocaleOptions, WeatherPageHeaderDataOptions {
+  /**
+   * 표시 언어 코드
+   */
+  locale?: string;
+  /**
+   * 서비스에서 주입한 표시 문구
+   */
+  texts?: Partial<WeatherPageHeaderTexts>;
+  /**
+   * 통합 weather query 결과
+   */
+  weather?: WeatherPageHeaderWeather;
+}
 
 /**
- * Weather Page Header; next days props
+ * Weather Page Header; next days props.
  * @property {string} title 날짜 라벨
- * @property {API_Res_WeatherKoreaNextDays} [data] 예보 데이터
+ * @property {API_Res_WeatherNextDays} [data] 예보 데이터
  * @property {string} [locale] 표시 언어 코드
  * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
  */
 export interface WeatherPageHeaderNextDaysProps extends WeatherPageHeaderLocaleOptions {
+  /**
+   * 표시 언어 코드
+   */
+  locale?: string;
+  /**
+   * 서비스에서 주입한 표시 문구
+   */
+  texts?: Partial<WeatherPageHeaderTexts>;
   /**
    * 날짜 라벨
    */
@@ -241,11 +291,11 @@ export interface WeatherPageHeaderNextDaysProps extends WeatherPageHeaderLocaleO
   /**
    * 예보 데이터
    */
-  data?: API_Res_WeatherKoreaNextDays;
+  data?: API_Res_WeatherNextDays;
 }
 
 /**
- * Weather Icon; 날씨 아이콘 props
+ * Weather Icon; 날씨 아이콘 props.
  * @property {string | null} [code] 날씨 아이콘 코드
  * @property {string | null} [name] 날씨 상태 이름
  * @property {string} [alt] 아이콘 대체 텍스트 fallback
@@ -266,7 +316,7 @@ export interface WeatherIconProps {
 }
 
 /**
- * Weather Address Icon; 위치 아이콘 props
+ * Weather Address Icon; 위치 아이콘 props.
  * @property {string} [alt] 아이콘 대체 텍스트
  */
 export interface WeatherAddressIconProps {

package/src/weather/utils/index.ts

@@ -1,5 +1,7 @@
 export * from "./location";
-export * from "./date-time";
-export * from "./weather";
-export * from "./alert";
-export * from "./locale";
+export {
+  isWeatherForecastResponse,
+  isWeatherNowResponse,
+  isWeatherSummaryResponse,
+} from "./weather";
+export { getWeatherLocaleKey, resolveWeatherPageHeaderTexts } from "./locale";

package/src/weather/utils/locale.ts

@@ -1,8 +1,4 @@
-import type {
-  WeatherPageHeaderTexts,
-  WeatherProviderCapabilityRegistry,
-  WeatherProviderKey,
-} from "../types";
+import type { WeatherPageHeaderTexts } from "../types";
 
 const WEATHER_PAGE_HEADER_DEFAULT_TEXTS: WeatherPageHeaderTexts = {
   currentWeatherLoading: "현재 날씨 불러오는 중...",
@@ -23,34 +19,10 @@ const WEATHER_PAGE_HEADER_DEFAULT_TEXTS: WeatherPageHeaderTexts = {
   alertIssueCommandLabel: "발령",
 };
 
-const OPEN_WEATHER_MAP_LANG_BY_LOCALE: Record<string, string> = {
-  ko: "kr",
-  en: "en",
-  ja: "ja",
-};
-
-const WEATHER_DEFAULT_PROVIDER: WeatherProviderKey = "openWeatherMap";
-
-const WEATHER_PROVIDER_BY_LOCALE_KEY: Record<string, WeatherProviderKey> = {
-  ko: "kma",
-};
-
-export const WEATHER_PROVIDER_CAPABILITIES: WeatherProviderCapabilityRegistry =
-  {
-    kma: {
-      now: true,
-      forecast: true,
-      alert: true,
-    },
-    openWeatherMap: {
-      now: true,
-      forecast: true,
-      alert: false,
-    },
-  };
-
 /**
- * Weather Locale; locale 기준 키 정규화
+ * Weather Locale; locale 기준 키 정규화.
+ * @util
+ * @desc service locale 문자열에서 weather API/표시 로직에 사용할 기본 언어 키를 추출한다.
  * @param {string} [locale] locale 코드
  * @return {string} 전달된 locale의 기본 언어 코드
  * @example
@@ -60,30 +32,9 @@ export const getWeatherLocaleKey = (locale?: string): string =>
   locale?.trim().toLowerCase().split(/[-_]/)[0] || "ko";
 
 /**
- * Weather Locale; locale 기준 provider 선택
- * @param {string} [locale] locale 코드
- * @return {WeatherProviderKey} 현재 locale에 사용할 weather provider
- * @example
- * resolveWeatherProvider("ko-KR")
- */
-export const resolveWeatherProvider = (locale?: string): WeatherProviderKey => {
-  const localeKey = getWeatherLocaleKey(locale);
-
-  return WEATHER_PROVIDER_BY_LOCALE_KEY[localeKey] ?? WEATHER_DEFAULT_PROVIDER;
-};
-
-/**
- * Weather Locale; KMA provider 사용 여부
- * @param {string} [locale] locale 코드
- * @return {boolean} KMA provider 대상 locale 여부
- * @example
- * isKoreaWeatherLocale("ko-KR")
- */
-export const isKoreaWeatherLocale = (locale?: string): boolean =>
-  resolveWeatherProvider(locale) === "kma";
-
-/**
- * Weather Locale; page-header 텍스트 병합
+ * Weather Locale; page-header 텍스트 병합.
+ * @util
+ * @desc service가 주입한 일부 표시 문구를 weather page-header 기본 문구와 병합한다.
  * @param {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 텍스트
  * @return {WeatherPageHeaderTexts} 기본 fallback과 서비스 주입 텍스트를 병합한 텍스트
  * @example
@@ -95,16 +46,3 @@ export const resolveWeatherPageHeaderTexts = (
   ...WEATHER_PAGE_HEADER_DEFAULT_TEXTS,
   ...texts,
 });
-
-/**
- * Weather Locale; OpenWeatherMap API lang 값 변환
- * @param {string} [locale] locale 코드
- * @return {string} OpenWeatherMap lang 파라미터
- * @example
- * getOpenWeatherMapLang("ko")
- */
-export const getOpenWeatherMapLang = (locale?: string): string => {
-  const localeKey = getWeatherLocaleKey(locale);
-
-  return OPEN_WEATHER_MAP_LANG_BY_LOCALE[localeKey] ?? localeKey;
-};

package/src/weather/utils/location.ts

@@ -1,18 +1,13 @@
-import type {
-  GeoCoordinate,
-  KMA_GridCoordinate,
-  KMA_Req_BaseGridCoordinate,
-  WeatherCoordinate,
-} from "../types";
+import type { GeoCoordinate } from "../types";
 
 /**
- * 날씨 도구; 접속위치 추출
+ * 날씨 도구; 접속위치 추출.
  * @util
- * @return {GeoCoordinate}}
+ * @desc 브라우저 geolocation API에서 현재 위치를 읽고, 사용할 수 없으면 null 좌표를 반환한다.
+ * @return {Promise<GeoCoordinate>} 브라우저 geolocation에서 읽은 위경도
  */
 export const userLocation = async (): Promise<GeoCoordinate> => {
   if (typeof window === "undefined" || !window.navigator.geolocation) {
-    // console.log("[userLocation] window 없음");
     return { latitude: null, longitude: null };
   }
 
@@ -22,143 +17,13 @@ export const userLocation = async (): Promise<GeoCoordinate> => {
         window.navigator.geolocation.getCurrentPosition(resolve, reject);
       },
     );
-    // console.log("[userLocation] 위치 정보:", position.coords);
-    const res = {
+
+    return {
       latitude: position.coords.latitude,
       longitude: position.coords.longitude,
     };
-    return res;
   } catch (error) {
     console.error("[userLocation] 위치 정보 에러", error);
     return { latitude: null, longitude: null };
   }
 };
-
-/**
- * 날씨 도구; 위경도 -> 격자 좌표 변환
- * @util
- * @param {GeoCoordinate} coordinate - 위경도 좌표
- * @param {number} coordinate.latitude - 위도
- * @param {number} coordinate.longitude - 경도
- * @return {KMA_GridCoordinate} 격자 좌표
- * @desc
- * - 위경도 좌표를 기상청 격자 좌표로 변환합니다.
- * - 출처: 기상청
- * @see https://apihub.kma.go.kr/
- * @see https://apihub.kma.go.kr/getAttachFile.do?fileName=%EB%8B%A8%EA%B8%B0%EC%98%88%EB%B3%B4%20%EC%A1%B0%ED%9A%8C%EC%84%9C%EB%B9%84%EC%8A%A4_API%ED%99%9C%EC%9A%A9%EA%B0%80%EC%9D%B4%EB%93%9C_241128.docx
- */
-export function convertCoordinateToGrid({
-  latitude,
-  longitude,
-}: GeoCoordinate): KMA_GridCoordinate {
-  const res: KMA_GridCoordinate = { x: 0, y: 0 };
-
-  if (latitude === null || longitude === null) return res;
-
-  const RE = 6371.00877; // Earth radius (km)
-  const GRID = 5.0; // Grid spacing (km)
-  const SLAT1 = 30.0; // Projection latitude 1 (degree)
-  const SLAT2 = 60.0; // Projection latitude 2 (degree)
-  const ORIGIN_LONGITUDE = 126.0; // Origin longitude (degree)
-  const ORIGIN_LATITUDE = 38.0; // Origin latitude (degree)
-  const XO = 43; // Origin X coordinate (GRID)
-  const YO = 136; // Origin Y coordinate (GRID)
-
-  const RADIAN = Math.PI / 180.0;
-  const re = RE / GRID;
-  const slat1 = SLAT1 * RADIAN;
-  const slat2 = SLAT2 * RADIAN;
-  const origin_longitude = ORIGIN_LONGITUDE * RADIAN;
-  const origin_latitude = ORIGIN_LATITUDE * RADIAN;
-
-  const sn =
-    Math.log(Math.cos(slat1) / Math.cos(slat2)) /
-    Math.log(
-      Math.tan(Math.PI * 0.25 + slat2 * 0.5) /
-        Math.tan(Math.PI * 0.25 + slat1 * 0.5),
-    );
-
-  const sf = Math.tan(Math.PI * 0.25 + slat1 * 0.5);
-  const sfPow = (Math.pow(sf, sn) * Math.cos(slat1)) / sn;
-
-  const ro =
-    (re * sfPow) /
-    Math.pow(Math.tan(Math.PI * 0.25 + origin_latitude * 0.5), sn);
-
-  const ra =
-    (re * sfPow) /
-    Math.pow(Math.tan(Math.PI * 0.25 + latitude * RADIAN * 0.5), sn);
-  let theta = longitude * RADIAN - origin_longitude;
-  if (theta > Math.PI) theta -= 2.0 * Math.PI;
-  if (theta < -Math.PI) theta += 2.0 * Math.PI;
-  theta *= sn;
-
-  res.x = Math.floor(ra * Math.sin(theta) + XO + 0.5);
-  res.y = Math.floor(ro - ra * Math.cos(theta) + YO + 0.5);
-
-  // console.log("[WEATHER] 위/경도 -> 기상청 격자값", res);
-
-  return res;
-}
-
-/**
- * 날씨 도구; 위도/경도 -> 기상청 격자 좌표 변환
- * @util
- * @param {WeatherCoordinate} [coordinate] - 사용자 위치 이외의 특정 위도/경도 좌표
- * @param {number} coordinate.lat - 위도
- * @param {number} coordinate.lng - 경도
- * @return {KMA_Req_BaseGridCoordinate} 기상청 격자 좌표
- */
-export async function getWeatherGridLocation(
-  coordinate?: WeatherCoordinate,
-): Promise<KMA_Req_BaseGridCoordinate> {
-  const res: KMA_Req_BaseGridCoordinate = { nx: 0, ny: 0 };
-
-  if (typeof window === "undefined") return res;
-
-  const geo: GeoCoordinate = {
-    latitude: coordinate?.lat ?? null,
-    longitude: coordinate?.lng ?? null,
-  };
-  const hasInjectedAddress =
-    typeof coordinate?.address === "string" && coordinate.address.trim() !== "";
-
-  // console.log("[getWeatherLocation] 특정 좌표지정 확인", coordinate);
-
-  // 변경 설명: 서비스가 address만 명시적으로 주입한 경우에는 geolocation fallback을 재시도하지 않는다.
-  if (
-    typeof window !== "undefined" &&
-    !hasInjectedAddress &&
-    (typeof coordinate === "undefined" ||
-      geo.latitude === null ||
-      geo.longitude === null)
-  ) {
-    const { latitude, longitude } = await userLocation();
-
-    if (latitude === null || longitude === null) {
-      // console.log("[getWeatherLocation] window.navigator 실패", geo);
-      return res;
-    }
-    geo.latitude = latitude;
-    geo.longitude = longitude;
-    // console.log("[getWeatherLocation] 사용자 위치", geo);
-  }
-
-  // 위경도 좌표를 기상청 격자좌표로 변환
-  const grid = convertCoordinateToGrid(geo);
-
-  if (grid.x === 0 || grid.y === 0) {
-    // console.error("[getWeatherLocation] 위치 정보를 가져오는데 실패했습니다.", {
-    //   latitude: geo.latitude,
-    //   longitude: geo.longitude,
-    // });
-    return res;
-  }
-  // console.log("[getWeatherLocation] 기상청 격자좌표", grid);
-
-  res.nx = grid.x;
-  res.ny = grid.y;
-
-  // console.log("[getWeatherLocation] result", res);
-  return res;
-}