@uniai-fe/uds-templates 0.6.1 → 0.6.3

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.1",
+  "version": "0.6.3",
   "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/apis/server.ts

@@ -224,16 +224,6 @@ export async function getServerCctvToken({
     token: "",
   };
 
-  const BODY_PRESET: API_Req_CctvRtcTokenOrigin = {
-    site: "company_id",
-    username: "harim",
-    password: "harim",
-    action: "read",
-    path: "cam_id",
-    ttl_seconds: 3600,
-    kid: "streaming-auth-1",
-  };
-
   if (!reqBody || !reqBody.username || !reqBody.company_id || !reqBody.cam_id) {
     nextAPILog("POST", routeUrl, query_url, { reqBody });
     return {
@@ -257,11 +247,13 @@ export async function getServerCctvToken({
 
   // 토큰 요청 payload 구성
   const bodyData: API_Req_CctvRtcTokenOrigin = {
-    ...BODY_PRESET,
     site,
     username,
     password,
+    action: "read",
     path,
+    ttl_seconds: 3600,
+    kid: "streaming-auth-1",
   };
 
   nextAPILog("POST", routeUrl, query_url, { bodyData });

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;