@uniai-fe/uds-templates 0.6.25 → 0.6.27

package/README.md

@@ -104,7 +104,6 @@ import { Auth, Modal, Frame } from "@uniai-fe/uds-templates";
   - `useCctvContext`
   - `useCctvRtcStream`
   - `getServerCompanyList`
-  - `getServerCctvToken`
   - `postCctvRtcToken`
 - `/page-frame`
   - `Frame`

package/package.json

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

package/src/cctv/apis/client.ts

@@ -7,16 +7,42 @@ import type {
   API_Res_CctvRtcToken,
 } from "../types";
 
+/**
+ * CCTV; RTC token fallback max age
+ * @desc
+ * JWT exp를 읽을 수 없는 token은 React Query dataUpdatedAt 기준으로 이 시간까지만 신규 WHEP 연결에 재사용한다.
+ */
 export const CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS = 5 * 60 * 1000;
+
+/**
+ * CCTV; RTC token query cache retention
+ * @desc
+ * focus/reconnect 자동 refetch는 막되, 오래된 token이 무기한 신규 연결에 쓰이지 않게 fallback max age와 동일하게 제한한다.
+ */
 export const CCTV_RTC_TOKEN_GC_TIME_MS = CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS;
 
+/**
+ * CCTV; client company-list fetcher
+ * @param {object} params 요청 파라미터
+ * @param {string} [params.url] service에서 주입한 company-list API 경로
+ * @returns {Promise<API_Res_CctvCompany>} CCTV company-list 응답
+ */
 export const getClientCctvCompanyList = async ({
   url,
 }: {
   url?: string;
 }): Promise<API_Res_CctvCompany> =>
+  // Provider에서 listUrl을 주입하지 않으면 UDS 기본 Next route를 사용한다.
   await (await fetch(url ?? "/api/cctv/company-list")).json();
 
+/**
+ * CCTV; company-list query hook
+ * @hook
+ * @param {object} params query 파라미터
+ * @param {string} [params.url] service에서 주입한 company-list API 경로
+ * @param {readonly unknown[]} [params.queryKeyDeps] service별 목록 cache 분리용 key dependency
+ * @returns {UseQueryResult<API_Res_CctvCompany>} company-list query 결과
+ */
 export const useQueryCctvCompanyList = ({
   url,
   queryKeyDeps = [],
@@ -25,17 +51,28 @@ export const useQueryCctvCompanyList = ({
   queryKeyDeps?: readonly unknown[];
 }): UseQueryResult<API_Res_CctvCompany> =>
   useQuery({
+    // username/site 등 service-local 조건이 바뀌면 queryKeyDeps로 cache를 분리한다.
     queryKey: ["cctv_company_list", url, ...queryKeyDeps],
     queryFn: () => getClientCctvCompanyList({ url }),
   });
 
+/**
+ * CCTV; RTC token POST fetcher
+ * @param {API_Req_CctvRtcToken & { url?: string }} params token 요청 파라미터
+ * @param {string} params.company_id 업체 id코드
+ * @param {string} params.cam_id 카메라 id코드
+ * @param {string} params.username CCTV token 권한 확인용 계정명
+ * @param {string} [params.url] service에서 주입한 token API 경로
+ * @returns {Promise<API_Res_CctvRtcToken>} RTC token 응답
+ */
 export const postCctvRtcToken = async ({
   company_id,
   cam_id,
   username,
   url,
 }: API_Req_CctvRtcToken & { url?: string }): Promise<API_Res_CctvRtcToken> =>
-  await (
+  await // token route는 service-local proxy가 있으면 그 경로를 우선 사용한다.
+  (
     await fetch(url ?? "/api/cctv/token", {
       method: "POST",
       headers: {
@@ -45,20 +82,37 @@ export const postCctvRtcToken = async ({
     })
   ).json();
 
+/**
+ * CCTV; RTC token query hook
+ * @hook
+ * @param {API_Req_CctvRtcToken & { enabled?: boolean; url?: string }} params token query 파라미터
+ * @param {string} params.company_id 업체 id코드
+ * @param {string} params.cam_id 카메라 id코드
+ * @param {boolean} [params.enabled] scheduler grant 이후 token query를 열기 위한 외부 gate
+ * @param {string} params.username CCTV token 권한 확인용 계정명
+ * @param {string} [params.url] service에서 주입한 token API 경로
+ * @returns {UseQueryResult<API_Res_CctvRtcToken>} RTC token query 결과
+ */
 export const useQueryCctvRtcToken = ({
   company_id,
   cam_id,
+  enabled = true,
   username,
   url,
 }: API_Req_CctvRtcToken & {
+  enabled?: boolean;
   url?: string;
 }): UseQueryResult<API_Res_CctvRtcToken> =>
   useQuery({
+    // token은 username/company/cam/API route 조합별로 분리한다.
     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),
+    // scheduler grant 전에는 token burst가 생기지 않도록 enabled를 false로 유지한다.
+    enabled: enabled && Boolean(username && company_id && cam_id),
+    // exp decode가 불가한 token은 fallback age를 넘기면 신규 WHEP 연결에 쓰지 않는다.
     staleTime: CCTV_RTC_TOKEN_FALLBACK_MAX_AGE_MS,
     gcTime: CCTV_RTC_TOKEN_GC_TIME_MS,
+    // focus/reconnect/mount가 곧바로 다수 WHEP 재협상으로 이어지지 않도록 자동 refetch를 막는다.
     refetchOnMount: false,
     refetchOnReconnect: false,
     refetchOnWindowFocus: false,

package/src/cctv/apis/server.ts

@@ -1,14 +1,7 @@
-import {
-  fetchWithBody,
-  generateQueryUrl,
-  nextAPILog,
-} from "@uniai-fe/util-api";
+import { generateQueryUrl, nextAPILog } from "@uniai-fe/util-api";
 import type {
   API_Req_GetCompanyListParams,
-  API_Req_GetCctvTokenParams,
-  API_Req_CctvRtcTokenOrigin,
   API_Res_CctvCompanyGroup,
-  API_Res_CctvRtcToken,
   API_Res_CctvCompany,
 } from "../types";
 
@@ -50,8 +43,6 @@ export const GROUP_PRESET: API_Res_CctvCompanyGroup[] = [
   },
 ];
 
-const CCTV_RTC_TOKEN_DEFAULT_TTL_SECONDS = 5 * 60;
-
 export function getMatchedGroupList(
   data: API_Res_CctvCompanyGroup[] = [],
   { code, method }: { code: string; method: string },
@@ -191,113 +182,3 @@ export async function getServerCompanyList({
     };
   }
 }
-
-/**
- * CCTV; token API route.ts 로직
- * @api
- * @route /token
- * @param {API_Req_GetCctvTokenParams} params
- * @property {string} domain API 요청 도메인(서버)
- * @property {string} routeUrl Next.js app/api 이하 경로 url
- * @property {string} [queryUrl] 백엔드 요청 url
- * @property {NextRequest} req Next.js API body 데이터
- */
-export async function getServerCctvToken({
-  domain,
-  routeUrl,
-  queryUrl,
-  req,
-  headers,
-  tokenPreset,
-}: API_Req_GetCctvTokenParams): Promise<{
-  res: API_Res_CctvRtcToken;
-  domain: string;
-  queryUrl: string;
-  options?: ResponseInit;
-}> {
-  const query_url = queryUrl || "/token";
-  const reqBody = await req.json();
-
-  const API_OPTION = {
-    domain,
-    queryUrl: query_url,
-  };
-
-  const alternateResponse: API_Res_CctvRtcToken = {
-    token: "",
-  };
-
-  const password =
-    reqBody?.password || tokenPreset?.password || reqBody?.username || "";
-
-  if (
-    !reqBody ||
-    !reqBody.username ||
-    !reqBody.company_id ||
-    !reqBody.cam_id ||
-    !password
-  ) {
-    nextAPILog("POST", routeUrl, query_url, {
-      hasUsername: Boolean(reqBody?.username),
-      hasCompanyId: Boolean(reqBody?.company_id),
-      hasCamId: Boolean(reqBody?.cam_id),
-      hasPassword: Boolean(password),
-    });
-    return {
-      res: alternateResponse,
-      ...API_OPTION,
-      options: {
-        status: 400,
-        statusText: "토큰 요청 파라미터가 올바르지 않습니다.",
-      },
-    };
-  }
-
-  const site = !isNaN(Number(reqBody.company_id))
-    ? `farm${reqBody.company_id}`
-    : String(reqBody.company_id);
-  const username = reqBody.username;
-  const path = !isNaN(Number(reqBody.cam_id))
-    ? `cam${reqBody.cam_id}`
-    : String(reqBody.cam_id);
-
-  // 토큰 요청 payload 구성
-  const bodyData: API_Req_CctvRtcTokenOrigin = {
-    site,
-    username,
-    password,
-    action: "read",
-    path,
-    ttl_seconds: tokenPreset?.ttl_seconds ?? CCTV_RTC_TOKEN_DEFAULT_TTL_SECONDS,
-    kid: tokenPreset?.kid ?? "streaming-auth-1",
-  };
-
-  nextAPILog("POST", routeUrl, query_url, {
-    hasRequiredParams: true,
-    ttlSeconds: bodyData.ttl_seconds,
-  });
-
-  try {
-    const res = await fetchWithBody<string, API_Res_CctvRtcToken>({
-      method: "POST",
-      routeUrl,
-      ...API_OPTION,
-      headers: {
-        accept: "application/json",
-        "Content-Type": "application/json",
-        ...(headers || {}),
-      },
-      body: JSON.stringify(bodyData),
-      alternateResponse,
-    });
-
-    return { res, ...API_OPTION };
-  } catch (error) {
-    nextAPILog("POST", routeUrl, query_url, { error });
-    return {
-      res: alternateResponse,
-      ...API_OPTION,
-      options: { status: 500 },
-    };
-  }
-}

package/src/cctv/components/Provider.tsx

@@ -14,6 +14,10 @@ import {
   createCctvRtcStreamRegistry,
   type CctvRtcStreamRegistry,
 } from "../hooks/streamRegistry";
+import {
+  createCctvRtcStreamScheduler,
+  type CctvRtcStreamScheduler,
+} from "../hooks/streamScheduler";
 
 /**
  * CCTV; API 경로 컨텍스트
@@ -28,6 +32,9 @@ const ApiUrlContext = createContext<CctvApiUrlContext>({
 const RtcStreamRegistryContext = createContext<CctvRtcStreamRegistry | null>(
   null,
 );
+const RtcStreamSchedulerContext = createContext<CctvRtcStreamScheduler | null>(
+  null,
+);
 
 /**
  * CCTV; API 경로 컨텍스트
@@ -40,6 +47,13 @@ export function useCctvApiUrl(): CctvApiUrlContext {
   return useContext(ApiUrlContext);
 }
 
+/**
+ * CCTV; RTC stream registry context hook
+ * @hook
+ * @returns {CctvRtcStreamRegistry} Provider instance 단위 stream registry
+ * @desc
+ * registry는 WHEP PeerConnection/MediaStream을 Provider lifecycle 안에서 유지하고 list/viewer video reattach를 담당한다.
+ */
 export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
   const registry = useContext(RtcStreamRegistryContext);
   if (!registry) {
@@ -50,6 +64,23 @@ export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
   return registry;
 }
 
+/**
+ * CCTV; RTC stream scheduler context hook
+ * @hook
+ * @returns {CctvRtcStreamScheduler} Provider instance 단위 stream scheduler
+ * @desc
+ * scheduler는 item UI 렌더와 token/WHEP 시작 시점을 분리해 초기 요청 burst를 batch 단위로 줄인다.
+ */
+export function useCctvRtcStreamScheduler(): CctvRtcStreamScheduler {
+  const scheduler = useContext(RtcStreamSchedulerContext);
+  if (!scheduler) {
+    throw new Error(
+      "CCTV.Provider 내부에서 useCctvRtcStreamScheduler를 사용해야 합니다.",
+    );
+  }
+  return scheduler;
+}
+
 /**
  * CCTV; Provider props
  * @component
@@ -60,6 +91,7 @@ export function useCctvRtcStreamRegistry(): CctvRtcStreamRegistry {
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
  * @property {string} [whepUsername] WHEP endpoint username 덮어쓰기 값
  * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
+ * @property {CctvRtcStreamOptions} [streamOptions] stream lazy loading 옵션
  * @property {React.ReactNode} children
  */
 export default function CCTVProvider<ContextExtension extends object = object>({
@@ -70,15 +102,39 @@ export default function CCTVProvider<ContextExtension extends object = object>({
   listUrl,
   tokenUrl,
   defaultValues,
+  streamOptions,
   children,
 }: CctvProviderProps<ContextExtension>) {
+  // streamOptions object identity가 매 렌더 바뀌어도 primitive option 값 기준으로만 scheduler를 교체한다.
+  const streamBatchSize = streamOptions?.batchSize;
+  const streamBatchIntervalMs = streamOptions?.batchIntervalMs;
+  const hasStreamOptions =
+    streamBatchSize !== undefined || streamBatchIntervalMs !== undefined;
+
+  // registry는 Provider lifetime 동안 유지해 list/viewer 전환 시 기존 MediaStream을 재사용한다.
   const streamRegistry = useMemo(() => createCctvRtcStreamRegistry(), []);
 
+  // scheduler는 Provider option이 바뀌는 경우에만 새 batch 정책으로 다시 만든다.
+  const streamScheduler = useMemo(
+    () =>
+      createCctvRtcStreamScheduler(
+        hasStreamOptions
+          ? {
+              batchIntervalMs: streamBatchIntervalMs,
+              batchSize: streamBatchSize,
+            }
+          : undefined,
+      ),
+    [hasStreamOptions, streamBatchIntervalMs, streamBatchSize],
+  );
+
   useEffect(() => {
     return () => {
+      // Provider unmount가 CCTV stream lifecycle의 최종 정리 지점이다.
       streamRegistry.closeAll();
+      streamScheduler.clear();
     };
-  }, [streamRegistry]);
+  }, [streamRegistry, streamScheduler]);
 
   const mergedDefaultValues = {
     // 변경 설명: service 확장 context 기본값을 core CCTV form context와 한 RHF scope에서 병합한다.
@@ -93,13 +149,15 @@ export default function CCTVProvider<ContextExtension extends object = object>({
   return (
     <ApiUrlContext.Provider value={{ listUrl, tokenUrl }}>
       <RtcStreamRegistryContext.Provider value={streamRegistry}>
-        <Form.Provider<CctvContext<ContextExtension>>
-          options={{
-            defaultValues: mergedDefaultValues,
-          }}
-        >
-          {children}
-        </Form.Provider>
+        <RtcStreamSchedulerContext.Provider value={streamScheduler}>
+          <Form.Provider<CctvContext<ContextExtension>>
+            options={{
+              defaultValues: mergedDefaultValues,
+            }}
+          >
+            {children}
+          </Form.Provider>
+        </RtcStreamSchedulerContext.Provider>
       </RtcStreamRegistryContext.Provider>
     </ApiUrlContext.Provider>
   );

package/src/cctv/components/cam-list/Item.tsx

@@ -25,8 +25,10 @@ export default function CCTVCamListItem({
   renderOverlay,
   ...cam
 }: CctvCamListItemProps) {
+  // item은 즉시 렌더하지만 token/WHEP 시작은 hook 내부 scheduler grant 이후로 지연된다.
   const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
+  // live/error/message는 video-state util 하나를 기준으로 계산해 CamList와 Viewer 표시 규칙을 맞춘다.
   const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const overlayMessage = useMemo(
@@ -44,9 +46,11 @@ export default function CCTVCamListItem({
       )}
     >
       <CCTVVideoTemplate
+        // hook이 반환한 ref에 registry MediaStream이 attach된다.
         ref={videoRef}
         cam={cam}
         className="cctv-cam-list-video-container"
+        // list card에서는 live/share 상태를 header에 노출하고 제목은 footer로 내려 보낸다.
         headerOptions={{
           activeLiveState: true,
           activeTitle: false,
@@ -58,9 +62,11 @@ export default function CCTVCamListItem({
         // 변경 설명: list item custom overlay는 template seam 하나만 따라간다.
         renderOverlay={renderOverlay}
         {...{
+          // Video.Template이 overlay/body/footer를 한 번에 판단할 수 있도록 stream 상태를 함께 넘긴다.
           isError,
           overlayMessage,
           isLive,
+          streamStage: rtcCtx.streamStage,
           canReconnect: rtcCtx.canReconnect,
           reconnectStream: rtcCtx.reconnectStream,
         }}

package/src/cctv/components/pagination/list/Item.tsx

@@ -11,14 +11,29 @@ import {
   getIsError,
 } from "../../../utils/video-state";
 
+/**
+ * CCTV; pagination list item
+ * @component
+ * @param {object} props
+ * @param {string} [props.className] pagination thumbnail item 클래스
+ * @param {string} props.cam_id 카메라 id코드
+ * @param {string} props.cam_name 카메라명
+ * @param {string} props.company_id 업체 id코드
+ * @param {boolean} props.cam_online 카메라 온라인 여부
+ * @param {string} props.cam_rtc WebRTC endpoint base URL
+ * @desc
+ * viewer 하단 thumbnail에서도 동일한 `useCctvRtcStream` 경로를 사용해 list/viewer 전환 시 registry reattach 계약을 유지한다.
+ */
 export default function CCTVPaginationListItem({
   className,
   ...cam
 }: {
   className?: string;
 } & CctvCompanyCameraData) {
+  // thumbnail은 즉시 렌더하고, 실제 token/WHEP 시작은 Provider scheduler가 batch 단위로 grant한다.
   const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
+  // CamList item과 동일한 util을 사용해 overlay 상태 판정 drift를 막는다.
   const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
   const overlayMessage = useMemo(
@@ -26,6 +41,7 @@ export default function CCTVPaginationListItem({
     [cam, rtcCtx],
   );
 
+  // cam.onSelect는 render data에 주입된 선택 handler라 있을 때만 호출한다.
   const handleSelect = useCallback(() => {
     if (typeof cam.onSelect === "function") cam.onSelect();
   }, [cam]);
@@ -47,9 +63,11 @@ export default function CCTVPaginationListItem({
         aria-label={`${cam.cam_name} 선택`}
       >
         <CCTVVideoTemplate
+          // registry가 같은 streamKey의 MediaStream을 thumbnail video에 attach한다.
           ref={videoRef}
           cam={cam}
           className="cctv-pagination-list-video-container"
+          // thumbnail에서는 header live/share 상태만 보이고 footer action은 최소화한다.
           headerOptions={{
             activeLiveState: true,
             activeTitle: false,
@@ -59,9 +77,11 @@ export default function CCTVPaginationListItem({
           }}
           footerOptions={{ cam }}
           {...{
+            // Video.Template overlay가 queued/token-loading/connecting/error 상태를 통합 표시한다.
             isError,
             overlayMessage,
             isLive,
+            streamStage: rtcCtx.streamStage,
             canReconnect: rtcCtx.canReconnect,
             reconnectStream: rtcCtx.reconnectStream,
           }}

package/src/cctv/components/video/Template.tsx

@@ -17,6 +17,7 @@ import type { CctvVideoTemplateProps } from "../../types/props";
  * @property {boolean} [isError]
  * @property {React.ReactNode} [overlayMessage]
  * @property {boolean} [isLive]
+ * @property {CctvRtcStreamStage} [streamStage]
  * @property {CctvCompanyCameraData} [cam]
  * @property {boolean} [canReconnect]
  * @property {CctvRtcReconnectTrigger} [reconnectStream]
@@ -33,6 +34,7 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
       isError,
       isLive,
       overlayMessage,
+      streamStage,
       canReconnect,
       reconnectStream,
       renderOverlay,
@@ -60,6 +62,7 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
             isError,
             isLive,
             overlayMessage,
+            streamStage,
             canReconnect,
             reconnectStream,
           })

package/src/cctv/components/viewer/desktop/Video.tsx

@@ -61,6 +61,7 @@ export default function CCTVViewerDesktopVideo({
         isError,
         overlayMessage,
         isLive,
+        streamStage: rtcCtx.streamStage,
         canReconnect: rtcCtx.canReconnect,
         reconnectStream: rtcCtx.reconnectStream,
       }}