@uniai-fe/uds-templates 0.1.15 → 0.1.17

package/src/weather/types/korea.ts

@@ -0,0 +1,228 @@
+/**
+ * 기상청 격자 좌표.
+ * @property {number} x 경도 격자값
+ * @property {number} y 위도 격자값
+ */
+export type KMA_GridCoordinate = {
+  /** 경도 격자값 */
+  x: number;
+  /** 위도 격자값 */
+  y: number;
+};
+
+/**
+ * 기상청 기본 요청 필수 파라미터.
+ * @property {string} pageNo 페이지 번호
+ * @property {string} numOfRows 페이지당 결과 수
+ * @property {string} authKey 인증키
+ * @property {string} dataType 응답 타입(JSON/XML)
+ */
+export type KMA_Req_Base = {
+  /** 페이지 번호 */
+  pageNo: string;
+  /** 페이지당 결과 수 */
+  numOfRows: string;
+  /** 인증 키 */
+  authKey: string;
+  /** 응답 포맷 */
+  dataType: string;
+};
+
+/**
+ * 기상청 요청/응답 공통 시각 정보.
+ * @property {string} base_date 기준 날짜(YYYYMMDD)
+ * @property {string} base_time 기준 시각(HH00)
+ */
+export type KMA_Req_BaseMoments = {
+  /** 기준 날짜(YYYYMMDD) */
+  base_date: string;
+  /** 기준 시각(HH00) */
+  base_time: string;
+};
+
+/**
+ * 기상청 격자 좌표 파라미터.
+ * @property {number} nx 격자 X
+ * @property {number} ny 격자 Y
+ */
+export type KMA_Req_BaseGridCoordinate = {
+  /** 격자 X */
+  nx: number;
+  /** 격자 Y */
+  ny: number;
+};
+
+/**
+ * 기상청 날씨 API 요청 조합.
+ */
+export type KMA_Req_Weather = KMA_Req_Base &
+  KMA_Req_BaseMoments &
+  KMA_Req_BaseGridCoordinate;
+
+/**
+ * 기상청 API 응답; 예보변수
+ * @desc
+ * - SKY(하늘상태) 코드 - 1(맑음), 2(구름조금), 3(구름많음), 4(흐림)
+ * - PTY(강수형태) 코드 - 0(없음), 1(비), 2(비/눈), 3(눈), 4(소나기)
+ * - POP(강수확률) %
+ * - PCP(1시간 강수량) 1mm
+ * - SNO(1시간 신적설) 1cm
+ * - TMP(기온) ℃
+ * - TMX(최고기온) ℃
+ * - TMN(최저기온) ℃
+ * - REH(습도) %
+ * - UUU(풍속; 동서바람성분) m/s
+ * - VVV(풍속; 남북바람성분) m/s
+ * - VEC(풍향) deg
+ * - WSD(풍속) m/s
+ * - WAV(파고) m
+ */
+export type KMA_Res_WeatherVariablesCategory =
+  | "TMP"
+  | "TMX"
+  | "TMN"
+  | "UUU"
+  | "VVV"
+  | "VEC"
+  | "WSD"
+  | "SKY"
+  | "PTY"
+  | "POP"
+  | "PCP"
+  | "SNO"
+  | "REH"
+  | "WAV";
+
+/**
+ * 기상청 예보 데이터 기본 구조.
+ * @property {string} baseDate 발표 날짜
+ * @property {string} baseTime 발표 시각
+ * @property {KMA_Res_WeatherVariablesCategory} category 변수 종류
+ * @property {number} nx 격자 X
+ * @property {number} ny 격자 Y
+ */
+export type KMA_Res_WeatherItemBase = {
+  /** 발표 날짜 */
+  baseDate: string;
+  /** 발표 시각 */
+  baseTime: string;
+  /** 변수 종류 */
+  category: KMA_Res_WeatherVariablesCategory;
+} & KMA_Req_BaseGridCoordinate;
+
+/**
+ * 기상청 예보 데이터.
+ * @property {string} fcstDate 예보 날짜
+ * @property {string} fcstTime 예보 시각
+ * @property {string} fcstValue 예보 값
+ */
+export type KMA_Res_WeatherItem = KMA_Res_WeatherItemBase & {
+  /** 예보 날짜 */
+  fcstDate: string;
+  /** 예보 시각 */
+  fcstTime: string;
+  /** 예보 값 */
+  fcstValue: string;
+};
+
+// /**
+//  * 기상청 API 응답; 현재 날씨 데이터
+//  */
+// export type KMA_Res_WeatherItemNow = KMA_Res_WeatherItemBase & {
+//   obsrValue: string;
+// };
+
+/**
+ * 기상청 응답 헤더.
+ * @property {string} resultCode 응답 코드
+ * @property {string} resultMsg 응답 메시지
+ */
+export type KMA_Res_Header = {
+  /** 응답 코드 */
+  resultCode: string;
+  /** 응답 메시지 */
+  resultMsg: string;
+};
+
+/**
+ * 기상청 응답 바디.
+ * @property {string} dataType 응답 타입
+ * @property {{ item: Item[] }} items 데이터 목록
+ * @property {number} pageNo 페이지 번호
+ * @property {number} numOfRows 페이지당 건수
+ * @property {number} totalCount 전체 건수
+ */
+export type KMA_Res_Body<Item> = {
+  /** 응답 포맷 */
+  dataType: string;
+  /** 데이터 목록 */
+  items: { item: Item[] };
+  /** 페이지 번호 */
+  pageNo: number;
+  /** 페이지당 건수 */
+  numOfRows: number;
+  /** 전체 건수 */
+  totalCount: number;
+};
+
+/**
+ * 기상청 응답 공통 구조.
+ * @property {KMA_Res_Header} header 헤더
+ * @property {KMA_Res_Body<Item>} body 바디
+ */
+export type KMA_Res_Base<Item> = {
+  response: {
+    /** 헤더 */
+    header: KMA_Res_Header;
+    /** 바디 */
+    body: KMA_Res_Body<Item>;
+  };
+};
+
+/** * * 기상청 API 응답; 현재 날씨.
+ * */
+export type KMA_Res_WeatherNow = KMA_Res_Base<KMA_Res_WeatherItem>;
+
+/** * * 기상청 API 응답; 예보.
+ * */
+export type KMA_Res_WeatherForecast = KMA_Res_Base<KMA_Res_WeatherItem>;
+
+// export type KMA_Res_MetaRegionCodeItem = {
+//   warningAreaCode: string;
+//   korName: string;
+// };
+// export type KMA_Res_MetaRegionCodes = KMA_Res_Base<KMA_Res_MetaRegionCodeItem>;
+
+/**
+ * 기상청 API 응답; 특보 종류
+ * @see https://apihub.kma.go.kr/static/html/attach/wrn_table.html
+ */
+export type KMA_Res_AlertType =
+  | "강풍"
+  | "호우"
+  | "한파"
+  | "건조"
+  | "해일"
+  | "지진해일"
+  | "풍량"
+  | "태풍"
+  | "대설"
+  | "황사"
+  | "폭염";
+/**
+ * 기상청 API 응답; 특보 수준
+ * @see https://apihub.kma.go.kr/static/html/attach/wrn_table.html
+ */
+export type KMA_Res_AlertLevel = "예비특보" | "주의보" | "경보";
+/**
+ * 기상청 API 응답; 특보 명령
+ * @see https://apihub.kma.go.kr/static/html/attach/wrn_table.html
+ */
+export type KMA_Res_AlertCommand =
+  | "발표"
+  | "대치"
+  | "해제"
+  | "대치해제"
+  | "연장"
+  | "변경"
+  | "변경해제";

package/src/weather/types/open-weather-map.ts

@@ -0,0 +1,164 @@
+/**
+ * OpenWeatherMap 위/경도 좌표.
+ * @property {number} lat 위도
+ * @property {number} lon 경도
+ */
+export type OWM_Res_Coord = {
+  lat: number;
+  lon: number;
+};
+
+/**
+ * @see https://openweathermap.org/weather-conditions
+ */
+export type OWM_Res_Condition = {
+  /**
+   * 날씨 코드
+   * @see https://openweathermap.org/weather-conditions
+   * @desc
+   * - 800: 맑음
+   * - 801: 구름조금
+   * - 802: 구름많음
+   * - 803: 흐림
+   * - 804: 흐림
+   * - 7XX: 안개, 연무, 황사 등
+   * - 6XX: 눈
+   * - 5XX: 비
+   * - 3XX: 이슬비, 빗방울 등
+   * - 2XX: 천둥번개
+   */
+  id: number;
+  /** * 개황 (영문) */
+  main: string;
+  /** * 개황 (한글) */
+  description: string;
+  /**
+   * 아이콘 코드
+   * @see https://openweathermap.org/weather-conditions
+   * @desc
+   * - 01d: 맑음 (clear sky)
+   * - 02d: 구름조금 (few clouds)
+   * - 03d: 구름많음 (scattered clouds)
+   * - 04d: 흐림 (broken clouds)
+   * - 09d: 소나기 (shower rain)
+   * - 10d: 비 (rain)
+   * - 11d: 천둥번개 (thunderstorm)
+   * - 13d: 눈 (snow)
+   * - 50d: 안개 (mist)
+   */
+  icon: string;
+};
+
+/**
+ * 측정값
+ * - 온도: 섭씨온도 (°C)
+ * - 습도: 백분율 (%)
+ * - 기압: hPa
+ */
+export type OWM_Res_Weather_Degrees = {
+  /** * 현재 온도 (°C) */
+  temp: number;
+  /** * 체감 온도 (°C) */
+  feels_like: number;
+  /** * 최저 온도 (°C) */
+  temp_min: number;
+  /** * 최고 온도 (°C) */
+  temp_max: number;
+  /** * 해면기압 (hPa) */
+  pressure: number;
+  /** * 습도 (%) */
+  humidity: number;
+  /** * 해면기압 (hPa) */
+  sea_level: number;
+  /** * 현지기압 (hPa) */
+  grnd_level: number;
+};
+
+/**
+ * 바람 관련 응답.
+ * @property {number} speed 풍속(m/s)
+ * @property {number} deg 풍향(deg)
+ * @property {number} gust 돌풍(m/s)
+ */
+export type OWM_Res_Wind = {
+  /** * 풍속 (m/s) */
+  speed: number;
+  /**
+   * 풍향 (deg)
+   * - 0: 북쪽
+   * - 90: 동쪽
+   * - 180: 남쪽
+   * - 270: 서쪽
+   */
+  deg: number;
+  /** * 돌풍 (m/s) */
+  gust: number;
+};
+
+/**
+ * 구름량 정보.
+ * @property {number} all 구름량(%)
+ */
+export type OWM_Res_Clouds = {
+  /** * 구름량 (0-100, %) */
+  all: number;
+};
+
+/**
+ * 일출/일몰 정보.
+ * @property {string} country 국가 코드
+ * @property {number} sunrise 일출 시각 timestamp
+ * @property {number} sunset 일몰 시각 timestamp
+ */
+export type OWM_Res_Sun = {
+  country: string; // 국가 코드 "KR";
+  sunrise: number; // 일출 timestamp 1748290711;
+  sunset: number; // 일몰 timestamp 1748342383;
+};
+
+/**
+ * OpenWeatherMap API 응답; 현재 날씨
+ * @see https://openweathermap.org/current
+ */
+export type OWM_Res_Weather_Now = {
+  /** * 위/경도 좌표 */
+  coord: OWM_Res_Coord;
+  /** * 개황 정보 */
+  weather: OWM_Res_Condition[];
+  /** 내부 지표값 */
+  base: string;
+  /** * 측정 정보 */
+  main: OWM_Res_Weather_Degrees;
+  /** * 시정거리 (m) */
+  visibility: number;
+  /** * 바람 정보 */
+  wind: OWM_Res_Wind;
+  /** * 구름량 정보 */
+  clouds: OWM_Res_Clouds;
+  /** * 데이터 연산 시간 timestamp (UTC, sec) */
+  dt: number;
+  /** * 일출/일몰 정보 */
+  sys: OWM_Res_Sun;
+  /**
+   * UTC로부터 현지 시간 보정 (sec)
+   * - 한국 : 9시간 (3600 * 9 = 32400)
+   */
+  timezone: number;
+  /**
+   * 도시 ID
+   * @deprecated
+   */
+  /** 도시 ID */
+  id: number;
+  /**
+   * 도시 이름
+   * @deprecated
+   */
+  /** 도시 이름 */
+  name: number;
+  /**
+   * API 응답 정보
+   */
+  /** API 응답 코드 */
+  cod: number;
+};

package/src/weather/utils/alert.ts

@@ -0,0 +1,30 @@
+/**
+ * 특보 도구; 지역 ID 추출
+ * @param {Array} params
+ * @param {Array<{ lat:number; lon:number; regId:string; }>} params.regions - 지역 목록
+ * @param {[number, number]} params.coordinate - [위도, 경도]
+ */
+export const getRegId = ({
+  regions,
+  coordinate,
+}: {
+  regions: Array<{
+    [dataKey: string]: unknown;
+    lat: number;
+    lon: number;
+    regId: string;
+  }>;
+  coordinate: [number, number];
+}): string | null => {
+  const [lat, lng] = coordinate;
+  let bestId: string | null = null;
+  let min = Infinity;
+  for (const z of regions) {
+    const d = Math.hypot(lat - z.lat, lng - z.lon);
+    if (d < min) {
+      min = d;
+      bestId = z.regId;
+    }
+  }
+  return bestId;
+};

package/src/weather/utils/date-time.ts

@@ -0,0 +1,65 @@
+import type { KMA_Req_BaseMoments, WeatherUtilDateTimeMoments } from "../types";
+import { dateFormat } from "@uniai-fe/util-functions";
+
+export const getWeatherBaseMoments = (
+  category: "now" | "forecast",
+): KMA_Req_BaseMoments => {
+  const FORECAST_HOURS = [2, 5, 8, 11, 14, 17, 20, 23]; // 발표 시각
+
+  const now = new Date();
+
+  let base_date = "";
+  let base_time = "";
+
+  if (category === "now") {
+    const base = new Date(now.getTime() - 10 * 60 * 1000); // 10분 보정
+    base_date = dateFormat(base).replace(/-/g, "");
+    base_time = `${base.getHours().toString().padStart(2, "0")}00`;
+  } else {
+    const hour = now.getHours();
+    const base = new Date(now);
+    let base_hour: number = hour;
+    if (hour < 2) {
+      base.setDate(base.getDate() - 1);
+      base_hour = 23;
+    }
+
+    // 현재 시각 이전 중 가장 가까운 발표 시각
+    const validHour = FORECAST_HOURS.reduce(
+      (prev, curr) => (curr <= base_hour ? curr : prev),
+      FORECAST_HOURS[0],
+    );
+
+    base_date = dateFormat(base).replace(/-/g, "");
+    base_time = `${validHour.toString().padStart(2, "0")}00`;
+  }
+
+  return { base_date, base_time };
+};
+
+/**
+ * 날씨 도구; 현재 날씨/예보 시각
+ * @util
+ * @return {WeatherUtilDateTimeMoments}
+ * @desc
+ * - now: Date 객체
+ * - today: YYYYMMDD 형식의 문자열
+ * - tomorrow: YYYYMMDD 형식의 문자열
+ * - dayAfterTomorrow: YYYYMMDD 형식의 문자열
+ */
+export const getMoments = (): WeatherUtilDateTimeMoments => {
+  const now = new Date();
+  const today = now.toISOString().slice(0, 10).replace(/-/g, "");
+
+  const tomorrow = new Date(now.getTime() + 86400000)
+    .toISOString()
+    .slice(0, 10)
+    .replace(/-/g, "");
+
+  const dayAfterTomorrow = new Date(now.getTime() + 2 * 86400000)
+    .toISOString()
+    .slice(0, 10)
+    .replace(/-/g, "");
+
+  return { now, today, tomorrow, dayAfterTomorrow };
+};

package/src/weather/utils/index.ts

@@ -0,0 +1,4 @@
+export * from "./location";
+export * from "./date-time";
+export * from "./weather";
+export * from "./alert";

package/src/weather/utils/location.ts

@@ -0,0 +1,161 @@
+import type {
+  GeoCoordinate,
+  KMA_GridCoordinate,
+  KMA_Req_BaseGridCoordinate,
+  WeatherCoordinate,
+} from "../types";
+
+/**
+ * 날씨 도구; 접속위치 추출
+ * @util
+ * @return {GeoCoordinate}}
+ */
+export const userLocation = async (): Promise<GeoCoordinate> => {
+  if (typeof window === "undefined" || !window.navigator.geolocation) {
+    // console.log("[userLocation] window 없음");
+    return { latitude: null, longitude: null };
+  }
+
+  try {
+    const position = await new Promise<GeolocationPosition>(
+      (resolve, reject) => {
+        window.navigator.geolocation.getCurrentPosition(resolve, reject);
+      },
+    );
+    // console.log("[userLocation] 위치 정보:", position.coords);
+    const res = {
+      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,
+  };
+
+  // console.log("[getWeatherLocation] 특정 좌표지정 확인", coordinate);
+
+  // 특정 위경도 좌표를 받지 못하는 경우, 현재 사용자 위치로 지정
+  if (
+    typeof window !== "undefined" &&
+    (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;
+}

package/src/weather/utils/validate.ts

@@ -0,0 +1,9 @@
+import type { KMA_Req_BaseGridCoordinate } from "../types";
+
+export const isValidGridCoordinate = ({
+  nx,
+  ny,
+}: KMA_Req_BaseGridCoordinate) => {
+  if (isNaN(Number(nx)) || isNaN(Number(ny))) return false;
+  return nx > 0 && ny > 0;
+};