@uniai-fe/uds-templates 0.6.0 → 0.6.2

package/README.md

@@ -11,7 +11,7 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
 - `@uniai-fe/uds-foundation@^0.0.1` (CSS 토큰 + reset)
 - `@uniai-fe/uds-primitives@^0.0.2` (템플릿 내부 UI 컴포넌트)
 - `react` `>= 19`, `react-dom` `>= 19`
-- Storybook/로컬 개발용으로는 `@uniai-fe/uds-foundation/css`를 앱 루트에서 한 번만 import 해야 합니다.
+- Storybook/로컬 개발과 서비스 앱 모두 style load 순서를 명시해야 합니다. 자세한 기준은 아래 "스타일 전역 주입"을 따릅니다.
 
 > 템플릿은 primitives 위에서 동작하므로, `@uniai-fe/uds-primitives`가 설치되어 있지 않으면 빌드 타임에 peer dependency 경고가 발생합니다.
 
@@ -21,16 +21,30 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - 로그인/회원가입/아이디·비밀번호 찾기 등 `/auth/**`
   - 로그인 이후 화면을 위한 모바일 페이지 프레임 `/page-frame/mobile`(PC는 추후 `/page-frame/pc`)
 - Raw TS 배포:
-  - `package.json` `exports`가 `src/**`를 가리키며, 번들 없이 즉시 import 가능한 형태로 제공합니다.
+  - `package.json` root export가 `src/index.tsx`를 가리키며, 번들 없이 root namespace에서 즉시 import 가능한 형태로 제공합니다.
 - 디자인시스템 일관성:
-  - 스타일은 항상 `@uniai-fe/uds-foundation/css`에서 제공하는 CSS 변수(토큰)를 통해만 정의됩니다.
+  - 스타일은 foundation style entry가 제공하는 CSS 변수(토큰)를 통해만 정의됩니다.
   - UI 요소는 모두 `@uniai-fe/uds-primitives` 컴포넌트를 조합해 구성합니다.
 - 역할 분리:
   - **templates**는 레이아웃/플로우/상태 표현까지 담당하고,
   - API 호출, 인증 토큰 관리, 라우팅, i18n 등 비즈니스 로직은 서비스 앱에서 구현합니다.
 
+## Public import surface
+
+`@uniai-fe/uds-templates`의 공식 안정 public surface는 root namespace import다.
+
+```tsx
+import { Auth, Modal, Frame } from "@uniai-fe/uds-templates";
+```
+
+- `@uniai-fe/uds-templates/auth`, `@uniai-fe/uds-templates/modal`, `@uniai-fe/uds-templates/page-frame` 같은 category subpath는 현재 package export map에 없으므로 공식 사용 예시로 안내하지 않는다.
+- root에는 UI template namespace뿐 아니라 일부 API/helper/state surface도 함께 포함되어 있다. 이 책임 경계는 숨기지 않고 후속 package/API contract gate에서 정리한다.
+- category subpath 공개 여부는 package contract gate 후보로 남긴다.
+
 ## 확인 완료 도구 목록
 
+아래 `/modal`, `/weather` 같은 표기는 API inventory를 묶는 카테고리 label이다. 실제 consumer import path는 현재 root namespace import를 기준으로 한다.
+
 - `/modal`
   - `Modal.Provider`
   - `Modal.StackProvider`
@@ -189,15 +203,14 @@ export default nextConfig;
 
 ### 2) 스타일 전역 주입
 
-템플릿은 primitives 위에 구성되므로, 앱 루트에서 `@uniai-fe/uds-templates/styles`(Sass) 또는 `@uniai-fe/uds-templates/css`(번들 CSS) 중 하나를 **한 번만** import 하면 foundation 토큰, primitives, templates 스타일이 모두 초기화됩니다.
+templates style entry는 templates styles만 제공하며 foundation/primitives style을 다시 로드하지 않습니다. 서비스 앱은 app root 또는 global stylesheet에서 `foundation -> primitives -> templates` 순서로 style entry를 명시적으로 로드해야 합니다.
 
-```scss
-/* app/globals.scss (Sass 사용 프로젝트) */
-@use "@uniai-fe/uds-templates/styles";
-```
+CSS-only 소비:
 
 ```ts
-// app/layout.tsx (Sass 비사용 프로젝트)
+// app/layout.tsx
+import "@uniai-fe/uds-foundation/css";
+import "@uniai-fe/uds-primitives/css";
 import "@uniai-fe/uds-templates/css";
 
 export default function RootLayout(props: { children: React.ReactNode }) {
@@ -209,23 +222,40 @@ export default function RootLayout(props: { children: React.ReactNode }) {
 }
 ```
 
+Sass 소비:
+
+```scss
+/* app/globals.scss */
+@use "@uniai-fe/uds-foundation/scss";
+@use "@uniai-fe/uds-primitives/styles";
+@use "@uniai-fe/uds-templates/styles";
+```
+
 ## 간단 사용 예시
 
+아래는 root namespace import와 prop shape를 보여주는 개념 예시다. App Router server page에서 직접 event handler를 넘기지 말고, client wrapper 또는 서비스 앱 로그인 컨테이너에서 조합한다.
+
 ```tsx
-// app/(auth)/login/page.tsx
-import { AuthLoginTemplate } from "@uniai-fe/uds-templates/auth";
+"use client";
+
+import { Auth } from "@uniai-fe/uds-templates";
 
-export default function LoginPage() {
+export function LoginTemplateExample() {
   return (
-    <AuthLoginTemplate
-      text={{
-        title: "로그인",
-        description: "서비스 이용을 위해 로그인해 주세요.",
+    <Auth.Login.Container
+      header={<img src="/logo.svg" alt="서비스 로고" />}
+      fieldOptions={{
+        onLogin: async (values) => {
+          // 실제 로그인 API 호출은 서비스 앱에서 구현
+          // await login(values);
+        },
       }}
-      logoSlot={<img src="/logo.svg" alt="서비스 로고" />}
-      onSubmit={async (values) => {
-        // 실제 로그인 API 호출은 서비스 앱에서 구현
-        // await login(values);
+      linkOptions={{
+        find: {
+          id: "/auth/find-id",
+          password: "/auth/find-password",
+        },
+        signup: "/auth/signup",
       }}
     />
   );
@@ -235,7 +265,7 @@ export default function LoginPage() {
 > 위 예시는 개념을 설명하기 위한 형태이며,
 > 실제 props 구조/이름은 `CONTEXT-AUTH.md`에서 확정·관리합니다.
 
-> modules 레포 내부(Storybook 등)에서는 개발 편의를 위해 `@uniai-fe/uds-templates/styles` 엔트리를 import하지만, 외부 서비스/패키지는 `@uniai-fe/uds-templates/css` 엔트리만 사용해야 한다.
+> modules 레포 내부 Storybook은 local render setup으로 `@uniai-fe/uds-foundation/css` → `@uniai-fe/uds-primitives/styles` → `@uniai-fe/uds-templates/styles`를 사용한다. 이 설정은 Storybook 렌더링 검증용이며, 외부 consumer setup은 위 CSS-only/Sass 계약을 따른다.
 
 ### 최근 업데이트
 
@@ -245,9 +275,10 @@ export default function LoginPage() {
 
 ### 토큰 스코프 & ThemeProvider
 
-- templates SCSS는 모든 디자인 토큰을 `:root`에 선언하고, 빌드 시 `scripts/merge-theme-root.mjs`가 토큰 블록을 단일 `:root { ... }`로 합쳐 중복 선언을 제거합니다.
-- 서비스 앱은 foundation ThemeProvider가 주입하는 `.uds-theme-root`를 루트에 유지해야 하며, CSS import 순서는 `@uniai-fe/uds-foundation/css` → `@uniai-fe/uds-primitives/css` → `@uniai-fe/uds-templates/css` 입니다.
-- modules 레포(Storybook 등)는 SCSS 원본을 직접 사용하지만, 외부 프로젝트는 CSS 엔트리만 import한다는 규칙을 README/CODEX-RULES에 명시하고 있습니다.
+- templates CSS/styles는 templates module styles만 제공하며 upstream foundation/primitives styles를 초기화하지 않습니다.
+- 서비스 앱은 foundation ThemeProvider가 주입하는 `.uds-theme-root`를 루트에 유지할 수 있지만, ThemeProvider는 CSS를 import하지 않습니다.
+- CSS-only 소비자는 `@uniai-fe/uds-foundation/css` → `@uniai-fe/uds-primitives/css` → `@uniai-fe/uds-templates/css` 순서를 사용합니다.
+- Sass 소비자는 `@uniai-fe/uds-foundation/scss` → `@uniai-fe/uds-primitives/styles` → `@uniai-fe/uds-templates/styles` 순서를 사용합니다.
 
 ## Modal 모듈 사용법
 
@@ -260,8 +291,10 @@ ui-legacy에서 사용하던 모달 스택/옵션을 templates 레이어로 옮
 
 ```tsx
 // app/layout.tsx
-import "@uniai-fe/uds-templates/styles";
-import { Modal } from "@uniai-fe/uds-templates/modal";
+import "@uniai-fe/uds-foundation/css";
+import "@uniai-fe/uds-primitives/css";
+import "@uniai-fe/uds-templates/css";
+import { Modal } from "@uniai-fe/uds-templates";
 
 export default function RootLayout({
   children,
@@ -284,7 +317,7 @@ export default function RootLayout({
 
 ```tsx
 // 예: Alert/Confirm 호출
-import { Modal } from "@uniai-fe/uds-templates/modal";
+import { Modal } from "@uniai-fe/uds-templates";
 
 export function ExampleActions() {
   const { newModal } = Modal.useModal();

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
   "sideEffects": [
-    "./src/**/*.scss"
+    "./src/**/*.scss",
+    "./dist/styles.css"
   ],
   "license": "MIT",
   "homepage": "https://www.uniai.co.kr/",
@@ -70,9 +71,9 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.100.10",
+    "@tanstack/react-query": "^5.100.11",
     "@types/node": "^24.12.3",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "@uniai-fe/eslint-config": "workspace:*",
     "@uniai-fe/next-devkit": "workspace:*",
@@ -89,7 +90,7 @@
     "jotai": "^2.20.0",
     "next": "^15.5.18",
     "prettier": "^3.8.3",
-    "react-hook-form": "^7.75.0",
+    "react-hook-form": "^7.76.0",
     "sass": "^1.99.0",
     "typescript": "5.9.3"
   }

package/src/cctv/apis/client.ts

@@ -7,6 +7,9 @@ import type {
   API_Res_CctvRtcToken,
 } from "../types";
 
+export const CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS = 5 * 60 * 1000;
+export const CCTV_RTC_TOKEN_GC_TIME_MS = 60 * 60 * 1000;
+
 export const getClientCctvCompanyList = async ({
   url,
 }: {
@@ -54,8 +57,8 @@ export const useQueryCctvRtcToken = ({
     queryKey: ["cctv_rtc_token", username, company_id, cam_id, url],
     queryFn: () => postCctvRtcToken({ company_id, cam_id, username, url }),
     enabled: Boolean(username && company_id && cam_id),
-    staleTime: Infinity,
-    gcTime: Infinity,
+    staleTime: CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS,
+    gcTime: CCTV_RTC_TOKEN_GC_TIME_MS,
     refetchOnMount: false,
     refetchOnReconnect: false,
     refetchOnWindowFocus: false,

package/src/cctv/hooks/useRtcStream.ts

@@ -5,7 +5,10 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useSetAtom } from "jotai";
 
 // 토큰 발급 쿼리와 API URL 컨텍스트 훅, 타입, react-hook-form 유틸.
-import { useQueryCctvRtcToken } from "../apis/client";
+import {
+  CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS,
+  useQueryCctvRtcToken,
+} from "../apis/client";
 import {
   useCctvApiUrl,
   useCctvRtcStreamRegistry,
@@ -20,6 +23,52 @@ import { getIsLive } from "../utils/video-state";
 import { useFormContext, useWatch } from "react-hook-form";
 
 const AUTO_RECONNECT_INTERVAL_MS = 3000;
+const TOKEN_EXPIRY_SAFETY_MS = 30 * 1000;
+
+const decodeBase64Url = (value: string): string | null => {
+  try {
+    const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+
+    return atob(padded);
+  } catch {
+    return null;
+  }
+};
+
+const getJwtExpiresAt = (token: string): number | null => {
+  const payload = token.split(".")[1];
+  if (!payload) return null;
+
+  const decodedPayload = decodeBase64Url(payload);
+  if (!decodedPayload) return null;
+
+  try {
+    const parsedPayload = JSON.parse(decodedPayload) as { exp?: unknown };
+    const exp = parsedPayload.exp;
+
+    return typeof exp === "number" && Number.isFinite(exp) ? exp * 1000 : null;
+  } catch {
+    return null;
+  }
+};
+
+const canUseTokenForNewConnection = ({
+  dataUpdatedAt,
+  token,
+}: {
+  dataUpdatedAt: number;
+  token: string;
+}): boolean => {
+  const expiresAt = getJwtExpiresAt(token);
+  const now = Date.now();
+
+  if (expiresAt) {
+    return now + TOKEN_EXPIRY_SAFETY_MS < expiresAt;
+  }
+
+  return now - dataUpdatedAt <= CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS;
+};
 
 /**
  * CCTV 영상 스트림을 WebRTC로 연결하는 커스텀 훅.
@@ -60,6 +109,7 @@ export function useCctvRtcStream({
   const activeStreamKeyRef = useRef<string | null>(null);
   const activeStreamIdentityKeyRef = useRef<string | null>(null);
   const lastAutoReconnectAtRef = useRef(0);
+  const staleTokenRefreshKeyRef = useRef<string | null>(null);
 
   // RTCPeerConnectionState를 관찰해 UI에 노출하기 위한 상태값.
   const [connectionState, setConnectionState] =
@@ -95,7 +145,7 @@ export function useCctvRtcStream({
     return `${cam.cam_rtc.replace(/\/$/, "")}/whep${query}`;
   }, [cam?.cam_rtc, username]);
 
-  const streamKey = useMemo(() => {
+  const streamKeyCandidate = useMemo(() => {
     if (!cam?.cam_id || !cam.cam_online || !endpoint || !tokenQuery.data?.token)
       return "";
 
@@ -126,6 +176,65 @@ export function useCctvRtcStream({
     setHasConnected(false);
   }, [streamIdentityKey]);
 
+  const hasReusableRegistryStream = useMemo(() => {
+    if (!streamKeyCandidate) return false;
+
+    const snapshot = streamRegistry.getSnapshot(streamKeyCandidate);
+
+    return Boolean(
+      snapshot.stream ||
+      snapshot.isStreaming ||
+      snapshot.connectionState === "connected",
+    );
+  }, [streamKeyCandidate, streamRegistry]);
+
+  const canUseTokenForStream = useMemo(() => {
+    if (!streamKeyCandidate || !tokenQuery.data?.token) return false;
+    if (activeStreamKeyRef.current === streamKeyCandidate) return true;
+    if (hasReusableRegistryStream) return true;
+
+    return canUseTokenForNewConnection({
+      dataUpdatedAt: tokenQuery.dataUpdatedAt,
+      token: tokenQuery.data.token,
+    });
+  }, [
+    hasReusableRegistryStream,
+    streamKeyCandidate,
+    tokenQuery.data?.token,
+    tokenQuery.dataUpdatedAt,
+  ]);
+
+  const streamKey = canUseTokenForStream ? streamKeyCandidate : "";
+
+  useEffect(() => {
+    if (!streamKeyCandidate || canUseTokenForStream) {
+      staleTokenRefreshKeyRef.current = null;
+      return;
+    }
+
+    if (
+      !tokenQuery.data?.token ||
+      tokenQuery.isFetching ||
+      tokenQuery.isError
+    ) {
+      return;
+    }
+
+    if (staleTokenRefreshKeyRef.current === streamKeyCandidate) {
+      return;
+    }
+
+    staleTokenRefreshKeyRef.current = streamKeyCandidate;
+    void refetchRtcToken();
+  }, [
+    canUseTokenForStream,
+    refetchRtcToken,
+    streamKeyCandidate,
+    tokenQuery.data?.token,
+    tokenQuery.isError,
+    tokenQuery.isFetching,
+  ]);
+
   // 토큰과 endpoint가 준비되면 WebRTC 스트림을 연결한다.
   useEffect(() => {
     const currentVideo = videoRef.current;

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,
+  });