@uniai-fe/uds-templates 0.5.5 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@10.33.2",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -70,7 +70,7 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.99.0",
+    "@tanstack/react-query": "^5.100.1",
     "@types/node": "^24.10.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -89,7 +89,7 @@
     "jotai": "^2.19.1",
     "next": "^15.5.11",
     "prettier": "^3.8.3",
-    "react-hook-form": "^7.72.1",
+    "react-hook-form": "^7.73.1",
     "sass": "^1.99.0",
     "typescript": "5.9.3"
   }

package/src/cctv/apis/client.ts

@@ -6,31 +6,22 @@ import type {
   API_Res_CctvCompany,
   API_Res_CctvRtcToken,
 } from "../types";
-import { getQueryString } from "@uniai-fe/util-functions";
 
 export const getClientCctvCompanyList = async ({
-  username,
   url,
 }: {
-  username: string;
   url?: string;
-}) =>
-  await (
-    await fetch(
-      `${url ?? "/api/cctv/company-list"}${getQueryString({ username })}`,
-    )
-  ).json();
+}): Promise<API_Res_CctvCompany> =>
+  await (await fetch(url ?? "/api/cctv/company-list")).json();
 
 export const useQueryCctvCompanyList = ({
-  username,
   url,
 }: {
-  username: string;
   url?: string;
 }): UseQueryResult<API_Res_CctvCompany> =>
   useQuery({
-    queryKey: ["cctv_company_list", username, url],
-    queryFn: () => getClientCctvCompanyList({ username, url }),
+    queryKey: ["cctv_company_list", url],
+    queryFn: () => getClientCctvCompanyList({ url }),
   });
 
 export const postCctvRtcToken = async ({

package/src/cctv/apis/server.ts

@@ -132,46 +132,39 @@ export function classifyGroups(
 /**
  * CCTV; company-list API route.ts 로직
  * @api
- * @route /v1/users/{username}/cctvs
+ * @route /common/cctvs/{me|all}
  * @param {API_Req_GetCompanyListParams} params
  * @property {string} domain API 요청 도메인(서버)
  * @property {string} routeUrl Next.js app/api 이하 경로 url
  * @property {string} [queryUrl] 백엔드 요청 url
- * @property {URLSearchParams | object} searchParams 요청 searchParams
+ * @property {"me" | "all"} [scope] common/cctvs 조회 범위
  */
 export async function getServerCompanyList({
   domain,
   routeUrl,
   queryUrl,
-  searchParams,
+  scope = "me",
 }: API_Req_GetCompanyListParams): Promise<{
   res: API_Res_CctvCompany;
   domain: string;
   queryUrl: string;
   options?: ResponseInit;
 }> {
-  const username = searchParams.get("username") || "";
-  const query_url = queryUrl || `/v1/users/${username}/cctvs`;
+  const query_url = queryUrl || `/common/cctvs/${scope}`;
 
-  const alternateResponse = {
-    data: [],
-    total_count: 0,
+  const alternateResponse: API_Res_CctvCompany = {
+    status: "error",
+    data: {
+      items: [],
+      total_count: 0,
+    },
+    errors: [],
   };
   const API_OPTION = {
     domain,
     queryUrl: query_url,
-    // searchParams,
   };
 
-  if (!queryUrl && !username) {
-    nextAPILog("GET", routeUrl, query_url, { searchParams });
-    return {
-      res: alternateResponse,
-      ...API_OPTION,
-      options: { status: 400, statusText: "유저 아이디를 확인할 수 없습니다." },
-    };
-  }
-
   // 요청 URL 구성
   const url = generateQueryUrl({
     routeUrl,
@@ -181,12 +174,9 @@ export async function getServerCompanyList({
   try {
     const originRes: API_Res_CctvCompany = await (await fetch(url)).json();
 
-    // 응답 그룹/농장
-    const originGroups = originRes?.data || [];
-    const resGourps = classifyGroups(originGroups);
-
+    // 변경: server helper는 common/cctvs raw 응답을 유지하고 template 변환은 hook에서 처리한다.
     return {
-      res: { data: resGourps, total_count: originRes.total_count || 0 },
+      res: originRes,
       ...API_OPTION,
     };
   } catch (err) {

package/src/cctv/components/Provider.tsx

@@ -2,6 +2,7 @@
 
 import { createContext, useContext } from "react";
 import { Form } from "@uniai-fe/uds-primitives";
+import type { DefaultValues } from "react-hook-form";
 
 import type {
   CctvApiUrlContext,
@@ -39,26 +40,32 @@ export function useCctvApiUrl(): CctvApiUrlContext {
  * @property {string} [listUrl] company-list API 요청 경로
  * @property {string} [tokenUrl] token API 요청 경로
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
+ * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
  * @property {React.ReactNode} children
  */
-export default function CCTVProvider({
+export default function CCTVProvider<ContextExtension extends object = object>({
   username,
   company_id,
   cam_id,
   listUrl,
   tokenUrl,
+  defaultValues,
   children,
-}: CctvProviderProps) {
+}: CctvProviderProps<ContextExtension>) {
+  const mergedDefaultValues = {
+    // 변경 설명: service 확장 context 기본값을 core CCTV form context와 한 RHF scope에서 병합한다.
+    ...defaultValues,
+    ...CCTV_CONTEXT_DEFAULT_VALUES,
+    username,
+    company_id,
+    cam_id,
+  } as DefaultValues<CctvContext<ContextExtension>>;
+
   return (
     <ApiUrlContext.Provider value={{ listUrl, tokenUrl }}>
-      <Form.Provider<CctvContext>
+      <Form.Provider<CctvContext<ContextExtension>>
         options={{
-          defaultValues: {
-            ...CCTV_CONTEXT_DEFAULT_VALUES,
-            username,
-            company_id,
-            cam_id,
-          },
+          defaultValues: mergedDefaultValues,
         }}
       >
         {children}

package/src/cctv/hooks/useCompanyData.tsx

@@ -1,47 +1,48 @@
 "use client";
 
 import { useEffect, useMemo } from "react";
-import { useQueryCctvCompanyList } from "../apis";
+import { classifyGroups, useQueryCctvCompanyList } from "../apis";
 import { useCctvApiUrl } from "../components/Provider";
 import useCctvContext from "./useContext";
-import type { UseCctvCompanyDataReturn } from "../types";
+import type {
+  UseCctvCompanyDataParams,
+  UseCctvCompanyDataReturn,
+} from "../types";
 
 /**
  * CCTV 회사 리스트 API를 호출해 데이터를 가져오는 훅.
  * @hook
  * @param {UseCctvCompanyDataParams} [params] 훅 파라미터
- * @property {string} [username] 사용자 계정 아이디 (Provider에서 주입된 기본값 대신 사용)
  * @property {string} [url] 회사 리스트 API URL (Provider에서 주입된 기본값 대신 사용)
  * @return {UseCctvCompanyDataReturn} 회사 리스트 쿼리 반환값
  * @desc
  * return {
- *   data, // 회사 리스트 API 응답 데이터
+ *   data, // common/cctvs 원본 API 응답 데이터
  *   isFetching, // 데이터 로딩 중 상태
  *   isError, // 데이터 로딩 에러 상태
  *   ...rest, // react-query useQuery 반환값
  * }
  */
-export default function useCctvCompanyData(params?: {
-  username?: string;
-  url?: string;
-}): UseCctvCompanyDataReturn {
-  // 외부에서 username/url을 덮어쓸 수 있도록 받고, 없으면 Provider 값을 사용한다.
-  const { username, url } = params || {};
+export default function useCctvCompanyData(
+  params?: UseCctvCompanyDataParams,
+): UseCctvCompanyDataReturn {
+  // 변경: list 조회 계약은 URL만 override 대상으로 유지한다.
+  const { url } = params || {};
 
   const { listUrl } = useCctvApiUrl();
   const resolvedUrl = useMemo(() => url ?? listUrl, [url, listUrl]);
-  const { username: contextUsername, setValue } = useCctvContext();
+  const { setValue } = useCctvContext();
 
-  // 사용자/URL에 맞춰 회사 리스트 API를 호출한다.
+  // URL에 맞춰 회사 리스트 API를 호출한다.
   const { data, isFetching, isError, ...rest } = useQueryCctvCompanyList({
-    username: username ?? contextUsername,
     url: resolvedUrl,
   });
 
   // 응답 데이터를 react-hook-form rawData 필드로 반영한다.
   useEffect(() => {
-    if (data?.data) {
-      setValue("rawData", data?.data);
+    if (data?.data?.items) {
+      // 변경: common/cctvs raw items를 template form data 계약에 맞게 재분류한다.
+      setValue("rawData", classifyGroups(data.data.items));
     }
   }, [data, setValue]);
 

package/src/cctv/hooks/useContext.ts

@@ -11,7 +11,7 @@ import type {
   CctvCompanyCameraList,
   CctvCompanyGroup,
   CctvCompanyGroupItems,
-  CctvContext,
+  CctvBaseContext,
   UseCctvContextReturn,
 } from "../types";
 import { initCompanyList } from "../utils/data";
@@ -49,7 +49,7 @@ export default function useCctvContext(): UseCctvContextReturn {
   const setCtx = useSetAtom(cctvSelectedContext);
   const liveRegistry = useAtomValue(cctvRtcLiveRegistryAtom);
   // react-hook-form context에서 control/setValue 등을 꺼낸다.
-  const { control, setValue, ...context } = useFormContext<CctvContext>();
+  const { control, setValue, ...context } = useFormContext<CctvBaseContext>();
 
   // 폼 상태를 watch 하여 실시간 컨텍스트 값을 얻는다.
   const username = useWatch({ control, name: "username" });

package/src/cctv/types/api.ts

@@ -1,3 +1,4 @@
+import type { API_Res_Base } from "@uniai-fe/util-api";
 import type { UtilQueryBaseParams } from "@uniai-fe/util-functions";
 import type { NextRequest } from "next/server";
 
@@ -6,20 +7,25 @@ import type { NextRequest } from "next/server";
  * @property {string} domain API 요청 도메인(서버)
  * @property {string} routeUrl Next.js app/api 이하 경로 url
  * @property {string} [queryUrl] 백엔드 요청 url
- * @property {URLSearchParams} searchParams api 요청 search params
+ * @property {"me" | "all"} [scope] common/cctvs 조회 범위
  */
-export interface API_Req_GetCompanyListParams extends Omit<
-  UtilQueryBaseParams,
-  "queryUrl"
-> {
+export interface API_Req_GetCompanyListParams {
+  /**
+   * API 도메인
+   */
+  domain: string;
+  /**
+   * Next.js app/api 이하 경로 url
+   */
+  routeUrl: string;
   /**
    * 백엔드 요청 url
    */
   queryUrl?: string;
   /**
-   * api 요청 search params
+   * common/cctvs 조회 범위
    */
-  searchParams: URLSearchParams;
+  scope?: "me" | "all";
 }
 
 /**
@@ -115,15 +121,27 @@ export interface API_Res_CctvCompanyGroup {
 }
 
 /**
- * CCTV; API 업체 목록 조회 응답
- * @property {API_Res_CctvCompanyGroup[]} data
- * @property {number} total_count
+ * CCTV; common/cctvs 원본 응답 데이터
+ * @property {API_Res_CctvCompanyGroup[]} items 백엔드 원본 업체 그룹 목록
+ * @property {number} total_count 전체 업체 그룹 수
  */
-export interface API_Res_CctvCompany {
-  data: API_Res_CctvCompanyGroup[];
+export interface API_Res_CctvCompanyData {
+  /**
+   * 백엔드 원본 업체 그룹 목록
+   */
+  items: API_Res_CctvCompanyGroup[];
+  /**
+   * 전체 업체 그룹 수
+   */
   total_count: number;
 }
 
+/**
+ * CCTV; common/cctvs 원본 응답
+ * @typedef {API_Res_Base<API_Res_CctvCompanyData>} API_Res_CctvCompany
+ */
+export type API_Res_CctvCompany = API_Res_Base<API_Res_CctvCompanyData>;
+
 /**
  * CCTV; 실시간 스트리밍 토큰 요청 (Next.js API 요청)
  * @property {string} company_id 업체 id코드

package/src/cctv/types/context.ts

@@ -59,13 +59,17 @@ export interface CctvApiUrlContext {
  * CCTV; 실시간 영상보기 컨텍스트
  * @property {string} [company_id] 선택된 업체 id코드
  * @property {string} [cam_id] 선택된 카메라 id코드
+ * @property {string} username CCTV 조회시 권한 확인을 위한 계정명
  * @property {string} [search] 검색 키워드 (입력값)
  * @property {string} [filter] 검색 키워드 (필터값)
  * @property {API_Res_CctvCompanyGroup[]} rawData 원본 데이터 배열
  * @property {boolean} isFetching 데이터 로딩 상태
  * @property {boolean} isError 데이터 에러 상태
  */
-export interface CctvContext extends CctvSelectedContext {
+export interface CctvBaseContext extends CctvSelectedContext {
+  /**
+   * CCTV 조회시 권한 확인을 위한 계정명
+   */
   username: string;
   /**
    * 검색 키워드 (입력값)
@@ -79,21 +83,56 @@ export interface CctvContext extends CctvSelectedContext {
    * 원본 데이터 배열
    */
   rawData: API_Res_CctvCompanyGroup[];
+  /**
+   * 데이터 로딩 상태
+   */
   isFetching: boolean;
+  /**
+   * 데이터 에러 상태
+   */
   isError: boolean;
 }
 
+/**
+ * CCTV; Provider form context
+ * @template ContextExtension
+ * @typedef {CctvBaseContext & ContextExtension} CctvContext
+ * @property {string} [company_id] 선택된 업체 id코드
+ * @property {string} [cam_id] 선택된 카메라 id코드
+ * @property {string} username CCTV 조회시 권한 확인을 위한 계정명
+ * @property {string} search 검색 키워드 입력값
+ * @property {string} filter 검색 키워드 필터값
+ * @property {API_Res_CctvCompanyGroup[]} rawData 원본 데이터 배열
+ * @property {boolean} isFetching 데이터 로딩 상태
+ * @property {boolean} isError 데이터 에러 상태
+ */
+export type CctvContext<ContextExtension extends object = object> =
+  CctvBaseContext & ContextExtension;
+
 /**
  * CCTV; Provider props
+ * @template ContextExtension
  * @property {string} [company_id] 선택된 업체 id코드
  * @property {string} [cam_id] 선택된 카메라 id코드
  * @property {string} [listUrl] company-list API 요청 경로
  * @property {string} [tokenUrl] token API 요청 경로
  * @property {string} [username] CCTV 조회시 권한 확인을 위한 계정명
+ * @property {ContextExtension} [defaultValues] 서비스 확장 context 기본값
  * @property {React.ReactNode} children
  */
-export type CctvProviderProps = CctvSelectedContext &
-  CctvApiUrlContext & {
-    username?: string;
-    children: React.ReactNode;
-  };
+export type CctvProviderProps<ContextExtension extends object = object> =
+  CctvSelectedContext &
+    CctvApiUrlContext & {
+      /**
+       * CCTV 조회시 권한 확인을 위한 계정명
+       */
+      username?: string;
+      /**
+       * 서비스 확장 context 기본값
+       */
+      defaultValues?: ContextExtension;
+      /**
+       * Provider 하위 콘텐츠
+       */
+      children: React.ReactNode;
+    };

package/src/cctv/types/hook.ts

@@ -7,7 +7,7 @@ import type {
   CctvCompanyGroupItems,
 } from "./list";
 import type { UseFormReturn } from "react-hook-form";
-import type { CctvContext } from "./context";
+import type { CctvBaseContext } from "./context";
 
 /**
  * CCTV; useCctvRtcStream params
@@ -92,14 +92,9 @@ export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
 
 /**
  * CCTV; useCctvCompanyData params
- * @property {string} [username] 사용자 계정 아이디
  * @property {string} [url] 업체 리스트 API URL
  */
 export interface UseCctvCompanyDataParams {
-  /**
-   * 사용자 계정 아이디
-   */
-  username?: string;
   /**
    * 업체 리스트 API URL
    */
@@ -108,7 +103,7 @@ export interface UseCctvCompanyDataParams {
 
 /**
  * CCTV; useCctvCompanyData return
- * @property {API_Res_CctvCompany | undefined} data 업체 리스트 API 응답 데이터
+ * @property {API_Res_CctvCompany | undefined} data common/cctvs 원본 API 응답 데이터
  * @property {boolean} isFetching 데이터 로딩 중 상태
  * @property {boolean} isError 데이터 로딩 에러 상태
  */
@@ -140,7 +135,7 @@ export interface UseCctvCompanyDataReturn extends Omit<
  * @property {(cam_id: string) => void} onOpenCamera 카메라 선택 함수
  * @property {() => void} onCloseCamera 카메라 선택 해제 함수
  */
-export interface UseCctvContextReturn extends UseFormReturn<CctvContext> {
+export interface UseCctvContextReturn extends UseFormReturn<CctvBaseContext> {
   /**
    * 데이터 로딩 중 상태
    */