@uniai-fe/uds-templates 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/weather/apis/client.ts

@@ -35,6 +35,14 @@ const hasQueryValue = (value: unknown): boolean =>
  * @param {number|string|null} [params.farm_idx] 농장 식별자
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 현재/예보 단일 route 재현용 날짜
+ * @param {string} [params.base_time] 현재/예보 단일 route 재현용 시각
+ * @param {string} [params.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [params.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [params.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [params.forecast_base_time] summary 예보 날씨 재현용 시각
  * @param {string} [params.locale] 요청 언어 코드
  * @param {boolean} [params.include_raw] 원본 응답 포함 여부
  * @return {API_Req_Weather} local route query 파라미터
@@ -43,12 +51,28 @@ export const getWeatherClientParams = ({
   farm_idx,
   lat,
   lng,
+  nx,
+  ny,
+  base_date,
+  base_time,
+  now_base_date,
+  now_base_time,
+  forecast_base_date,
+  forecast_base_time,
   locale,
   include_raw,
 }: API_Req_Weather): API_Req_Weather => ({
   ...(hasQueryValue(farm_idx) ? { farm_idx } : {}),
   ...(hasQueryValue(lat) ? { lat } : {}),
   ...(hasQueryValue(lng) ? { lng } : {}),
+  ...(hasQueryValue(nx) ? { nx } : {}),
+  ...(hasQueryValue(ny) ? { ny } : {}),
+  ...(hasQueryValue(base_date) ? { base_date } : {}),
+  ...(hasQueryValue(base_time) ? { base_time } : {}),
+  ...(hasQueryValue(now_base_date) ? { now_base_date } : {}),
+  ...(hasQueryValue(now_base_time) ? { now_base_time } : {}),
+  ...(hasQueryValue(forecast_base_date) ? { forecast_base_date } : {}),
+  ...(hasQueryValue(forecast_base_time) ? { forecast_base_time } : {}),
   ...(locale ? { locale } : {}),
   ...(typeof include_raw === "boolean" ? { include_raw } : {}),
 });
@@ -65,10 +89,12 @@ const getWeatherRoutePath = (
 ): string => routePath || fallbackRoutePath;
 
 /**
- * Weather Client; 현재/예보/summary 조회가 가능한 위치 입력인지 확인.
+ * Weather Client; 현재/예보 조회가 가능한 위치 입력인지 확인.
  * @param {API_Req_Weather} params 날씨 요청 파라미터
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
  * @return {boolean} 위치 기반 weather query 실행 가능 여부
  */
 const isWeatherLocationAvailable = ({ lat, lng }: API_Req_Weather): boolean =>
@@ -79,6 +105,23 @@ const isWeatherLocationAvailable = ({ lat, lng }: API_Req_Weather): boolean =>
   isValidNumber(lat) &&
   isValidNumber(lng);
 
+/**
+ * Weather Client; backend 격자 입력이 사용 가능한지 확인.
+ * @param {API_Req_Weather} params 날씨 요청 파라미터
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @return {boolean} 격자 기반 weather query 실행 가능 여부
+ */
+const isWeatherGridAvailable = ({ nx, ny }: API_Req_Weather): boolean =>
+  nx !== null &&
+  ny !== null &&
+  typeof nx !== "undefined" &&
+  typeof ny !== "undefined" &&
+  isValidNumber(nx) &&
+  isValidNumber(ny) &&
+  Number(nx) > 0 &&
+  Number(ny) > 0;
+
 /**
  * Weather Client; 특보 조회가 가능한 농장 식별자인지 확인.
  * @param {API_Req_WeatherAlert} params 특보 요청 파라미터
@@ -88,21 +131,66 @@ const isWeatherLocationAvailable = ({ lat, lng }: API_Req_Weather): boolean =>
 const isWeatherFarmAvailable = ({ farm_idx }: API_Req_WeatherAlert): boolean =>
   hasQueryValue(farm_idx) && Number(farm_idx) > 0;
 
+/**
+ * Weather Client; summary 조회에 필요한 입력인지 확인.
+ * @param {API_Req_Weather} params summary 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @return {boolean} summary query 실행 가능 여부
+ */
+const isWeatherSummaryAvailable = (params: API_Req_Weather): boolean =>
+  isWeatherFarmAvailable({ farm_idx: params.farm_idx ?? null }) &&
+  (isWeatherLocationAvailable(params) || isWeatherGridAvailable(params));
+
 /**
  * Weather Client; React Query key에 사용할 weather 요청 값을 정렬.
  * @param {API_Req_Weather} params 날씨 요청 파라미터
  * @param {number|string|null} [params.farm_idx] 농장 식별자
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 현재/예보 단일 route 재현용 날짜
+ * @param {string} [params.base_time] 현재/예보 단일 route 재현용 시각
+ * @param {string} [params.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [params.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [params.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [params.forecast_base_time] summary 예보 날씨 재현용 시각
  * @param {string} [params.locale] 요청 언어 코드
  * @param {boolean} [params.include_raw] 원본 응답 포함 여부
  * @return {readonly unknown[]} React Query key 값
  */
 const getWeatherQueryKeyValues = (params: API_Req_Weather) => {
-  const { farm_idx, lat, lng, locale, include_raw } =
-    getWeatherClientParams(params);
+  const {
+    farm_idx,
+    lat,
+    lng,
+    nx,
+    ny,
+    base_date,
+    base_time,
+    now_base_date,
+    now_base_time,
+    forecast_base_date,
+    forecast_base_time,
+    locale,
+    include_raw,
+  } = getWeatherClientParams(params);
 
-  return [farm_idx, lat, lng, locale, include_raw] as const;
+  return [
+    farm_idx,
+    lat,
+    lng,
+    nx,
+    ny,
+    base_date,
+    base_time,
+    now_base_date,
+    now_base_time,
+    forecast_base_date,
+    forecast_base_time,
+    locale,
+    include_raw,
+  ] as const;
 };
 
 /**
@@ -112,6 +200,10 @@ const getWeatherQueryKeyValues = (params: API_Req_Weather) => {
  * @param {number|string|null} [params.farm_idx] 농장 식별자
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 현재 날씨 재현용 날짜
+ * @param {string} [params.base_time] 현재 날씨 재현용 시각
  * @param {string} [params.locale] 요청 언어 코드
  * @param {boolean} [params.include_raw] 원본 응답 포함 여부
  * @param {WeatherClientRouteOptions} [options] local route 옵션
@@ -138,6 +230,10 @@ export const getWeatherNow = async <Data = API_Res_WeatherNow>(
  * @param {number|string|null} [params.farm_idx] 농장 식별자
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 예보 날씨 재현용 날짜
+ * @param {string} [params.base_time] 예보 날씨 재현용 시각
  * @param {string} [params.locale] 요청 언어 코드
  * @param {boolean} [params.include_raw] 원본 응답 포함 여부
  * @param {WeatherClientRouteOptions} [options] local route 옵션
@@ -164,6 +260,12 @@ export const getWeatherForecast = async <Data = API_Res_WeatherForecast>(
  * @param {number|string|null} [params.farm_idx] 농장 식별자
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [params.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [params.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [params.forecast_base_time] summary 예보 날씨 재현용 시각
  * @param {string} [params.locale] 요청 언어 코드
  * @param {boolean} [params.include_raw] 원본 응답 포함 여부
  * @param {WeatherClientRouteOptions} [options] local route 옵션
@@ -212,6 +314,10 @@ export const getWeatherAlert = async <Data = API_Res_WeatherAlert>(
  * @param {number|string|null} [params.farm_idx] 농장 식별자
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 현재 날씨 재현용 날짜
+ * @param {string} [params.base_time] 현재 날씨 재현용 시각
  * @param {string} [params.locale] 요청 언어 코드
  * @param {boolean} [params.include_raw] 원본 응답 포함 여부
  * @param {WeatherClientQueryOptions} [options] query 옵션
@@ -231,7 +337,9 @@ export const useQueryWeatherNow = <Data = API_Res_WeatherNow>(
   return useQuery({
     queryKey: ["weather_now", routePath, ...getWeatherQueryKeyValues(params)],
     queryFn: () => getWeatherNow<Data>(params, { routePath }),
-    enabled: (options.enabled ?? true) && isWeatherLocationAvailable(params),
+    enabled:
+      (options.enabled ?? true) &&
+      (isWeatherLocationAvailable(params) || isWeatherGridAvailable(params)),
     staleTime: 10 * 60 * 1000,
     refetchInterval: 5 * 60 * 1000,
     refetchOnWindowFocus: true,
@@ -245,6 +353,10 @@ export const useQueryWeatherNow = <Data = API_Res_WeatherNow>(
  * @param {number|string|null} [params.farm_idx] 농장 식별자
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 예보 날씨 재현용 날짜
+ * @param {string} [params.base_time] 예보 날씨 재현용 시각
  * @param {string} [params.locale] 요청 언어 코드
  * @param {boolean} [params.include_raw] 원본 응답 포함 여부
  * @param {WeatherClientQueryOptions} [options] query 옵션
@@ -268,7 +380,9 @@ export const useQueryWeatherForecast = <Data = API_Res_WeatherForecast>(
       ...getWeatherQueryKeyValues(params),
     ],
     queryFn: () => getWeatherForecast<Data>(params, { routePath }),
-    enabled: (options.enabled ?? true) && isWeatherLocationAvailable(params),
+    enabled:
+      (options.enabled ?? true) &&
+      (isWeatherLocationAvailable(params) || isWeatherGridAvailable(params)),
     staleTime: 30 * 60 * 1000,
   });
 };
@@ -280,6 +394,12 @@ export const useQueryWeatherForecast = <Data = API_Res_WeatherForecast>(
  * @param {number|string|null} [params.farm_idx] 농장 식별자
  * @param {number|null} [params.lat] 위도
  * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [params.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [params.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [params.forecast_base_time] summary 예보 날씨 재현용 시각
  * @param {string} [params.locale] 요청 언어 코드
  * @param {boolean} [params.include_raw] 원본 응답 포함 여부
  * @param {WeatherClientQueryOptions} [options] query 옵션
@@ -303,7 +423,7 @@ export const useQueryWeatherSummary = <Data = API_Res_WeatherSummary>(
       ...getWeatherQueryKeyValues(params),
     ],
     queryFn: () => getWeatherSummary<Data>(params, { routePath }),
-    enabled: (options.enabled ?? true) && isWeatherLocationAvailable(params),
+    enabled: (options.enabled ?? true) && isWeatherSummaryAvailable(params),
     staleTime: 10 * 60 * 1000,
   });
 };

package/src/weather/apis/server.ts

@@ -4,6 +4,7 @@ import { generateQueryUrl, nextAPILog } from "@uniai-fe/util-api";
 import { setDebugResponseHeaders } from "@uniai-fe/util-next";
 import type { NextResponse } from "next/server";
 import WEATHER_RESPONSE from "../data/response";
+import { convertWeatherCoordinateToGrid } from "../utils";
 import type {
   API_Res_WeatherAlert,
   API_Res_WeatherForecast,
@@ -23,34 +24,136 @@ const QUERY_URL = {
 };
 
 const { API_RES_BASE } = WEATHER_RESPONSE;
-const BACKEND_QUERY_KEYS = [
+type WeatherBackendRouteKind = keyof typeof QUERY_URL;
+
+const BACKEND_COMMON_QUERY_KEYS = [
   "farm_idx",
   "lat",
   "lng",
   "locale",
   "include_raw",
 ] as const;
+const BACKEND_DATE_TIME_QUERY_PAIRS = {
+  now: [["base_date", "base_time"]],
+  forecast: [["base_date", "base_time"]],
+  summary: [
+    ["now_base_date", "now_base_time"],
+    ["forecast_base_date", "forecast_base_time"],
+  ],
+  alert: [],
+} as const;
+
+/**
+ * Weather backend; query 값 존재 여부 확인.
+ * @param {string | null} value 확인할 query 값
+ * @return {boolean} query 값 존재 여부
+ */
+const hasSearchParamValue = (value: string | null): value is string =>
+  value !== null && value !== "";
+
+/**
+ * Weather backend; query 값을 숫자로 변환한다.
+ * @param {URLSearchParams} searchParams service app local route query
+ * @param {string} key 숫자로 읽을 query key
+ * @return {number | null} 변환된 숫자 또는 null
+ */
+const getSearchParamNumber = (
+  searchParams: URLSearchParams,
+  key: string,
+): number | null => {
+  const value = searchParams.get(key);
+
+  if (!hasSearchParamValue(value)) return null;
+
+  const parsed = Number(value);
+
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+/**
+ * Weather backend; 재현용 date/time query를 pair 단위로 전달한다.
+ * @param {URLSearchParams} params backend 전달 query
+ * @param {URLSearchParams} searchParams service app local route query
+ * @param {WeatherBackendRouteKind} routeKind backend weather route 종류
+ */
+const setBackendDateTimeSearchParams = (
+  params: URLSearchParams,
+  searchParams: URLSearchParams,
+  routeKind: WeatherBackendRouteKind,
+): void => {
+  BACKEND_DATE_TIME_QUERY_PAIRS[routeKind].forEach(([dateKey, timeKey]) => {
+    const date = searchParams.get(dateKey);
+    const time = searchParams.get(timeKey);
+
+    if (!hasSearchParamValue(date) || !hasSearchParamValue(time)) return;
+
+    params.set(dateKey, date);
+    params.set(timeKey, time);
+  });
+};
+
+/**
+ * Weather backend; nx/ny query를 직접 값 또는 lat/lng 변환값으로 전달한다.
+ * @param {URLSearchParams} params backend 전달 query
+ * @param {URLSearchParams} searchParams service app local route query
+ */
+const setBackendGridSearchParams = (
+  params: URLSearchParams,
+  searchParams: URLSearchParams,
+): void => {
+  const providedNx = getSearchParamNumber(searchParams, "nx");
+  const providedNy = getSearchParamNumber(searchParams, "ny");
+  const { nx, ny } =
+    providedNx !== null && providedNy !== null
+      ? { nx: providedNx, ny: providedNy }
+      : convertWeatherCoordinateToGrid({
+          lat: getSearchParamNumber(searchParams, "lat"),
+          lng: getSearchParamNumber(searchParams, "lng"),
+        });
+
+  if (nx !== null && nx > 0) params.set("nx", String(nx));
+  if (ny !== null && ny > 0) params.set("ny", String(ny));
+};
 
 /**
  * Weather backend; client route query를 backend 허용 query로 정리.
+ * @param {WeatherBackendRouteKind} routeKind backend weather route 종류
  * @param {URLSearchParams} searchParams service app local route query
  * @param {string} [searchParams.farm_idx] 농장 식별자
  * @param {string} [searchParams.lat] 위도
  * @param {string} [searchParams.lng] 경도
+ * @param {string} [searchParams.nx] backend 격자 X
+ * @param {string} [searchParams.ny] backend 격자 Y
+ * @param {string} [searchParams.base_date] 현재/예보 단일 route 재현용 날짜
+ * @param {string} [searchParams.base_time] 현재/예보 단일 route 재현용 시각
+ * @param {string} [searchParams.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [searchParams.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [searchParams.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [searchParams.forecast_base_time] summary 예보 날씨 재현용 시각
  * @param {string} [searchParams.locale] 요청 언어 코드
  * @param {string} [searchParams.include_raw] 원본 응답 포함 여부
  * @return {URLSearchParams} backend 전달 query
  */
 const getBackendSearchParams = (
+  routeKind: WeatherBackendRouteKind,
   searchParams: URLSearchParams,
 ): URLSearchParams => {
   const params = new URLSearchParams();
 
-  BACKEND_QUERY_KEYS.forEach(key => {
+  if (routeKind === "alert") {
+    const farmIdx = searchParams.get("farm_idx");
+    if (hasSearchParamValue(farmIdx)) params.set("farm_idx", farmIdx);
+    return params;
+  }
+
+  BACKEND_COMMON_QUERY_KEYS.forEach(key => {
     const value = searchParams.get(key);
-    if (value !== null && value !== "") params.set(key, value);
+    if (hasSearchParamValue(value)) params.set(key, value);
   });
 
+  setBackendGridSearchParams(params, searchParams);
+  setBackendDateTimeSearchParams(params, searchParams, routeKind);
+
   return params;
 };
 
@@ -124,6 +227,7 @@ const getWeatherSummaryDefault = (): API_Res_WeatherSummary => ({
  * @param {string} params.domain backend API domain
  * @param {string} params.routeUrl local route URL
  * @param {string} params.queryUrl backend weather route URL
+ * @param {"now"|"forecast"|"summary"|"alert"} params.routeKind backend weather route 종류
  * @param {URLSearchParams} params.searchParams client route query
  * @param {Data} params.fallback 실패 시 반환할 fallback 응답
  * @return {Promise<Data>} backend 응답 또는 fallback
@@ -132,6 +236,7 @@ const fetchWeatherBackend = async <Data>({
   domain,
   routeUrl,
   queryUrl,
+  routeKind,
   searchParams,
   fallback,
 }: WeatherBackendFetchParams<Data>): Promise<Data> => {
@@ -142,7 +247,7 @@ const fetchWeatherBackend = async <Data>({
     return fallback;
   }
 
-  const backendParams = getBackendSearchParams(searchParams);
+  const backendParams = getBackendSearchParams(routeKind, searchParams);
   const url = generateQueryUrl({
     domain,
     routeUrl,
@@ -185,6 +290,7 @@ export const routeWeatherNow = async ({
     domain,
     routeUrl,
     queryUrl: QUERY_URL.now,
+    routeKind: "now",
     searchParams,
     fallback: getWeatherNowDefault(),
   });
@@ -207,6 +313,7 @@ export const routeWeatherForecast = async ({
     domain,
     routeUrl,
     queryUrl: QUERY_URL.forecast,
+    routeKind: "forecast",
     searchParams,
     fallback: getWeatherForecastDefault(),
   });
@@ -229,6 +336,7 @@ export const routeWeatherSummary = async ({
     domain,
     routeUrl,
     queryUrl: QUERY_URL.summary,
+    routeKind: "summary",
     searchParams,
     fallback: getWeatherSummaryDefault(),
   });
@@ -251,6 +359,7 @@ export const routeWeatherAlert = async ({
     domain,
     routeUrl,
     queryUrl: QUERY_URL.alert,
+    routeKind: "alert",
     searchParams,
     fallback: getWeatherAlertDefault(),
   });
@@ -259,6 +368,6 @@ export const routeWeatherAlert = async ({
     res,
     domain,
     queryUrl: QUERY_URL.alert,
-    searchParams: getBackendSearchParams(searchParams),
+    searchParams: getBackendSearchParams("alert", searchParams),
   });
 };

package/src/weather/types/api.ts

@@ -2,6 +2,7 @@ import type {
   WeatherApiLocaleOptions,
   WeatherCoordinate,
   WeatherGeoCoordinate,
+  WeatherGridCoordinate,
 } from "./base";
 
 /**
@@ -9,11 +10,22 @@ import type {
  * @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> {
+  extends
+    WeatherApiLocaleOptions,
+    Partial<WeatherGeoCoordinate>,
+    Partial<WeatherGridCoordinate> {
   /**
    * 농장 식별자
    */
@@ -26,6 +38,38 @@ export interface API_Req_Weather
    * 경도
    */
   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;
   /**
    * 요청 언어 코드
    */
@@ -128,6 +172,7 @@ export interface WeatherServerRouteParams {
  * @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 WeatherBackendFetchParams<Data> = WeatherServerRouteParams & {
@@ -135,6 +180,10 @@ export type WeatherBackendFetchParams<Data> = WeatherServerRouteParams & {
    * backend weather route URL
    */
   queryUrl: string;
+  /**
+   * backend weather route 종류
+   */
+  routeKind: "now" | "forecast" | "summary" | "alert";
   /**
    * 실패 시 반환할 fallback 응답
    */

package/src/weather/types/base.ts

@@ -30,6 +30,22 @@ export type WeatherGeoCoordinate = {
   lng: number | null;
 };
 
+/**
+ * 날씨 backend에서 사용하는 격자 좌표.
+ * @property {number | null} nx 격자 X
+ * @property {number | null} ny 격자 Y
+ */
+export type WeatherGridCoordinate = {
+  /**
+   * 격자 X
+   */
+  nx: number | null;
+  /**
+   * 격자 Y
+   */
+  ny: number | null;
+};
+
 /**
  * 날씨 API locale 요청 옵션.
  * @property {string} [locale] 요청 언어 코드. 기본 지원값은 ko, en, ja이며 타입은 확장 가능한 string으로 유지한다.

package/src/weather/utils/location.ts

@@ -1,4 +1,8 @@
-import type { GeoCoordinate } from "../types";
+import type {
+  GeoCoordinate,
+  WeatherGeoCoordinate,
+  WeatherGridCoordinate,
+} from "../types";
 
 /**
  * 날씨 도구; 접속위치 추출.
@@ -27,3 +31,79 @@ export const userLocation = async (): Promise<GeoCoordinate> => {
     return { latitude: null, longitude: null };
   }
 };
+
+/**
+ * 날씨 도구; 위경도 좌표를 backend weather 격자 좌표로 변환한다.
+ * @util
+ * @param {GeoCoordinate} coordinate 위경도 좌표
+ * @param {number|null} coordinate.latitude 위도
+ * @param {number|null} coordinate.longitude 경도
+ * @return {WeatherGridCoordinate} backend weather 격자 좌표
+ */
+export const convertCoordinateToGrid = ({
+  latitude,
+  longitude,
+}: GeoCoordinate): WeatherGridCoordinate => {
+  const fallback: WeatherGridCoordinate = { nx: null, ny: null };
+
+  if (latitude === null || longitude === null) return fallback;
+
+  const RE = 6371.00877;
+  const GRID = 5.0;
+  const SLAT1 = 30.0;
+  const SLAT2 = 60.0;
+  const ORIGIN_LONGITUDE = 126.0;
+  const ORIGIN_LATITUDE = 38.0;
+  const XO = 43;
+  const YO = 136;
+
+  const RADIAN = Math.PI / 180.0;
+  const re = RE / GRID;
+  const slat1 = SLAT1 * RADIAN;
+  const slat2 = SLAT2 * RADIAN;
+  const originLongitude = ORIGIN_LONGITUDE * RADIAN;
+  const originLatitude = 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 + originLatitude * 0.5), sn);
+  const ra =
+    (re * sfPow) /
+    Math.pow(Math.tan(Math.PI * 0.25 + latitude * RADIAN * 0.5), sn);
+  let theta = longitude * RADIAN - originLongitude;
+
+  if (theta > Math.PI) theta -= 2.0 * Math.PI;
+  if (theta < -Math.PI) theta += 2.0 * Math.PI;
+  theta *= sn;
+
+  return {
+    nx: Math.floor(ra * Math.sin(theta) + XO + 0.5),
+    ny: Math.floor(ro - ra * Math.cos(theta) + YO + 0.5),
+  };
+};
+
+/**
+ * 날씨 도구; weather 위경도 좌표를 backend weather 격자 좌표로 변환한다.
+ * @util
+ * @param {Partial<WeatherGeoCoordinate>} coordinate weather 위경도 좌표
+ * @param {number|null} [coordinate.lat] 위도
+ * @param {number|null} [coordinate.lng] 경도
+ * @return {WeatherGridCoordinate} backend weather 격자 좌표
+ */
+export const convertWeatherCoordinateToGrid = ({
+  lat,
+  lng,
+}: Partial<WeatherGeoCoordinate>): WeatherGridCoordinate =>
+  convertCoordinateToGrid({
+    latitude: lat ?? null,
+    longitude: lng ?? null,
+  });