From b8776959c2f8792945e0804af82f652413074353 Mon Sep 17 00:00:00 2001
From: HeHelee <selly3109@naver.com>
Date: Fri, 28 Nov 2025 10:38:56 +0900
Subject: [PATCH 1/5] =?UTF-8?q?feat:=20=EC=A3=BC=EC=84=9D=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../rack/api/deleteRackEquipments.ts          |  13 ++
 .../serverView/rack/api/getRackEquipments.ts  |  14 ++
 .../rack/api/getUnassignedEquipments.ts       |  19 ++
 .../rack/api/postPlaceEquipments.ts           |  15 ++
 .../serverView/rack/api/postRackEquipments.ts |  16 ++
 .../rack/api/updateRackEquipments.ts          |  14 ++
 .../serverView/rack/components/Button.tsx     |  17 ++
 .../serverView/rack/components/Card.tsx       |  15 ++
 .../rack/components/ClickableIcon.tsx         |  19 ++
 .../serverView/rack/components/Device.tsx     |  28 ++-
 .../serverView/rack/components/Dropdown.tsx   |  24 +++
 .../serverView/rack/components/Rack.tsx       |  38 ++++
 .../serverView/rack/components/RackHeader.tsx |  15 ++
 .../serverView/rack/components/RackView.tsx   |  58 ++++-
 .../serverView/rack/components/Sidebar.tsx    |  27 +++
 .../serverView/rack/components/Tools.tsx      |  18 ++
 .../serverView/rack/components/Tooltip.tsx    |  18 ++
 .../rack/constants/rackConstants.ts           |  17 ++
 .../rack/hooks/useDeleteRackEquipments.ts     |  18 ++
 .../rack/hooks/useGetRackEquipments.ts        |  14 ++
 .../rack/hooks/useGetUnassignedEquipments.ts  |  15 ++
 .../serverView/rack/hooks/useImageLoad.ts     |  10 +
 .../rack/hooks/usePostPlaceEquipments.ts      |  12 ++
 .../rack/hooks/usePostRackEquipments.ts       |   9 +
 .../serverView/rack/hooks/useRackManager.ts   |  65 +++++-
 .../rack/hooks/useUpdateRackEquipments.ts     |  17 ++
 src/domains/serverView/rack/types/index.ts    |  35 ++++
 src/domains/serverView/rack/utils/colorMap.ts |  15 ++
 .../serverView/rack/utils/deviceImageMap.ts   |  15 ++
 .../serverView/rack/utils/dragBound.ts        |  19 +-
 .../serverView/rack/utils/rackCalculation.ts  |  54 ++++-
 .../rack/utils/rackCollisionDetection.ts      |  36 +++-
 .../serverView/rack/utils/rackLayout.ts       |  15 ++
 .../serverDashboard/api/updateEquipments.ts   |  17 ++
 .../components/AreaLineChart.tsx              |  24 +++
 .../serverDashboard/components/BarChart.tsx   |  24 +++
 .../serverDashboard/components/Button.tsx     |  18 ++
 .../components/ButtonPlaceholder.tsx          |  18 ++
 .../serverDashboard/components/ChartCard.tsx  |  17 ++
 .../serverDashboard/components/GaugeChart.tsx |  19 ++
 .../components/ServerDashboard.tsx            |  39 +++-
 .../components/ServerDashboardHeader.tsx      |  16 ++
 .../components/SmoothLineChart.tsx            |  23 ++
 .../components/ThresholdHeader.tsx            |  39 +++-
 .../components/ThresholdmetricInput.tsx       |  64 +++++-
 .../serverDashboard/constants/index.ts        |  17 +-
 .../serverDashboard/css/chartCard.css         |  24 ++-
 .../serverDashboard/css/serverDashboard.css   |  21 +-
 .../hooks/useAllEquipmentBackgroundSSE.ts     |  36 ++++
 .../serverDashboard/hooks/useEquipmentSSE.ts  | 198 +++++++-----------
 .../hooks/useUpdateEquipment.ts               |  18 ++
 .../serverDashboard/stores/monitoringStore.ts |  46 +++-
 .../types/event-source-polyfill.d.ts          |  23 ++
 .../serverView/serverDashboard/types/index.ts |  17 ++
 .../serverDashboard/utils/chartDataBuilder.ts |  74 ++++++-
 .../serverDashboard/utils/monitoring.ts       |  43 ++++
 src/domains/serverView/types/index.ts         |  59 ++++--
 57 files changed, 1429 insertions(+), 199 deletions(-)

diff --git a/src/domains/serverView/rack/api/deleteRackEquipments.ts b/src/domains/serverView/rack/api/deleteRackEquipments.ts
index 5cbb8da..211d2cb 100644
--- a/src/domains/serverView/rack/api/deleteRackEquipments.ts
+++ b/src/domains/serverView/rack/api/deleteRackEquipments.ts
@@ -1,11 +1,24 @@
+/**
+ * @author 구희원
+ * @description 랙 장비 삭제 API
+ */
+
 import client from "@/api/client";
 
+/**
+ * 장비 삭제 API 응답
+ */
 interface DeleteEquipmentsResponse {
   statusCode: number;
   message: string;
   data: null;
 }
 
+/**
+ * 랙 장비 삭제
+ * @param {number} id - 삭제할 장비 ID
+ * @returns {Promise<DeleteEquipmentsResponse>} 삭제 결과
+ */
 export const deleteRackEquipments = async (
   id: number
 ): Promise<DeleteEquipmentsResponse> => {
diff --git a/src/domains/serverView/rack/api/getRackEquipments.ts b/src/domains/serverView/rack/api/getRackEquipments.ts
index 642f301..f9eab7a 100644
--- a/src/domains/serverView/rack/api/getRackEquipments.ts
+++ b/src/domains/serverView/rack/api/getRackEquipments.ts
@@ -1,12 +1,26 @@
+/**
+ * @author 구희원
+ * @description 특정 랙의 장비 목록 조회 API
+ */
+
 import client from "@/api/client";
 import type { EquipmentType, EquipmentStatus } from "../types";
 
+/**
+ * 랙 장비 조회 파라미터
+ */
 export interface GetRackEquipmentsParams {
   status?: EquipmentStatus;
   type?: EquipmentType;
   sortBy?: string;
 }
 
+/**
+ * 특정 랙의 장비 목록 조회
+ * @param {number} rackId - 조회할 랙 ID
+ * @param {GetRackEquipmentsParams} params - 필터 옵션 (status, type, sortBy)
+ * @returns 장비 목록
+ */
 export const getRackEquipments = async (
   rackId: number,
   params?: GetRackEquipmentsParams
diff --git a/src/domains/serverView/rack/api/getUnassignedEquipments.ts b/src/domains/serverView/rack/api/getUnassignedEquipments.ts
index 5abec71..7d3f3f4 100644
--- a/src/domains/serverView/rack/api/getUnassignedEquipments.ts
+++ b/src/domains/serverView/rack/api/getUnassignedEquipments.ts
@@ -1,11 +1,22 @@
+/**
+ * @author 구희원
+ * @description 미할당 장비 목록 조회 API
+ */
+
 import client from "@/api/client";
 import type { UnassignedEquipment } from "../types";
 
+/**
+ * 미할당 장비 조회 파라미터
+ */
 export interface GetUnassignedEquipmentsParams {
   page?: number;
   onlyUnassigned?: boolean;
 }
 
+/**
+ * 페이지네이션 응답
+ */
 interface PaginatedResponse {
   content: UnassignedEquipment[];
   totalElements: number;
@@ -15,12 +26,20 @@ interface PaginatedResponse {
   last: boolean;
 }
 
+/**
+ * 미할당 장비 조회 API 응답
+ */
 interface GetUnassignedEquipmentsResponse {
   status_code: number;
   status_message: string;
   result: PaginatedResponse;
 }
 
+/**
+ * 미할당 장비 목록 조회
+ * @param {GetUnassignedEquipmentsParams} params - 조회 옵션 (page, onlyUnassigned)
+ * @returns {Promise<GetUnassignedEquipmentsResponse>} 미할당 장비 목록 (페이지당 5개)
+ */
 export const getUnassignedEquipments = async (
   params: GetUnassignedEquipmentsParams = {}
 ) => {
diff --git a/src/domains/serverView/rack/api/postPlaceEquipments.ts b/src/domains/serverView/rack/api/postPlaceEquipments.ts
index 47272bf..dd7f752 100644
--- a/src/domains/serverView/rack/api/postPlaceEquipments.ts
+++ b/src/domains/serverView/rack/api/postPlaceEquipments.ts
@@ -1,10 +1,25 @@
+/**
+ * @author 구희원
+ * @description 랙에 장비 배치 API
+ */
+
 import client from "@/api/client";
 
+/**
+ * 장비 배치 요청 파라미터
+ */
 interface postPlaceEquipmentsRequest {
   startUnit: number;
   unitSize: number;
 }
 
+/**
+ * 랙에 장비 배치
+ * @param {number} rackId - 배치할 랙 ID
+ * @param {number} id - 배치할 장비 ID
+ * @param {postPlaceEquipmentsRequest} data - 배치 정보 (startUnit, unitSize)
+ * @returns 배치 결과
+ */
 export const postPlaceEquipments = async (
   rackId: number,
   id: number,
diff --git a/src/domains/serverView/rack/api/postRackEquipments.ts b/src/domains/serverView/rack/api/postRackEquipments.ts
index f85f12d..66db070 100644
--- a/src/domains/serverView/rack/api/postRackEquipments.ts
+++ b/src/domains/serverView/rack/api/postRackEquipments.ts
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 랙 장비 생성 API
+ */
+
 import client from "@/api/client";
 import type { Equipments } from "../types";
 
+/**
+ * 장비 생성 요청 파라미터
+ */
 export type PostEquipmentRequest = Pick<
   Equipments,
   "equipmentName" | "equipmentType" | "startUnit" | "unitSize" | "status"
@@ -8,12 +16,20 @@ export type PostEquipmentRequest = Pick<
   rackId: number;
 };
 
+/**
+ * 장비 생성 API 응답
+ */
 export interface PostEquipmentResponse {
   statusCode: number;
   message: string;
   data: Equipments;
 }
 
+/**
+ * 랙 장비 생성
+ * @param {PostEquipmentRequest} equipment - 생성할 장비 정보
+ * @returns {Promise<PostEquipmentResponse>} 생성된 장비 정보
+ */
 export const postRackEquipment = async (
   equipment: PostEquipmentRequest
 ): Promise<PostEquipmentResponse> => {
diff --git a/src/domains/serverView/rack/api/updateRackEquipments.ts b/src/domains/serverView/rack/api/updateRackEquipments.ts
index d967e20..5e98b50 100644
--- a/src/domains/serverView/rack/api/updateRackEquipments.ts
+++ b/src/domains/serverView/rack/api/updateRackEquipments.ts
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 랙 장비 수정 API
+ */
+
 import client from "@/api/client";
 import type { Equipments } from "../types";
 
+/**
+ * 장비 수정 요청 파라미터
+ */
 export type UpdateRackEquipmentRequest = Pick<
   Equipments,
   "equipmentName" | "equipmentType" | "startUnit" | "unitSize" | "status"
@@ -8,6 +16,12 @@ export type UpdateRackEquipmentRequest = Pick<
   rackId: number;
 };
 
+/**
+ * 랙 장비 수정
+ * @param {number} id - 수정할 장비 ID
+ * @param {UpdateRackEquipmentRequest} data - 수정할 장비 정보
+ * @returns 수정된 장비 정보
+ */
 export const updateRackEquipments = async (
   id: number,
   data: UpdateRackEquipmentRequest
diff --git a/src/domains/serverView/rack/components/Button.tsx b/src/domains/serverView/rack/components/Button.tsx
index f5699cf..aff443c 100644
--- a/src/domains/serverView/rack/components/Button.tsx
+++ b/src/domains/serverView/rack/components/Button.tsx
@@ -1,8 +1,25 @@
+/**
+ * @author 구희원
+ * @description 뷰 전환 토글 버튼 컴포넌트
+ */
+
+/**
+ * 뷰 토글 버튼 props
+ */
 interface ViewToggleButtonProps {
   label: string;
   onClick: () => void;
   active?: boolean;
 }
+
+/**
+ * 뷰 토글 버튼
+ * @param {ViewToggleButtonProps} props - 버튼 속성
+ * @param {string} props.label - 버튼 라벨
+ * @param {() => void} props.onClick - 클릭 이벤트 핸들러
+ * @param {boolean} props.active - 활성화 상태 (기본값: false)
+ * @returns 토글 버튼 컴포넌트
+ */
 function Button({ label, onClick, active = false }: ViewToggleButtonProps) {
   return (
     <button
diff --git a/src/domains/serverView/rack/components/Card.tsx b/src/domains/serverView/rack/components/Card.tsx
index e840d30..219bcbd 100644
--- a/src/domains/serverView/rack/components/Card.tsx
+++ b/src/domains/serverView/rack/components/Card.tsx
@@ -1,8 +1,23 @@
+/**
+ * @author 구희원
+ * @description 랙 정보 카드 컴포넌트
+ */
+
+/**
+ * 랙 카드 props
+ */
 interface RackCardProps {
   value: number;
   label: "총 U 수" | "사용 중";
 }
 
+/**
+ * 랙 정보 카드
+ * @param {RackCardProps} props - 카드 속성
+ * @param {number} props.value - 표시할 U 수 값
+ * @param {"총 U 수" | "사용 중"} props.label - 카드 라벨
+ * @returns 랙 정보 카드 컴포넌트
+ */
 function Card({ value, label }: RackCardProps) {
   return (
     <div className="flex flex-col justify-center items-center bg-[#1e253f] rounded-lg p-4 w-32 h-24 shadow-md">
diff --git a/src/domains/serverView/rack/components/ClickableIcon.tsx b/src/domains/serverView/rack/components/ClickableIcon.tsx
index 9efcc7e..8000b38 100644
--- a/src/domains/serverView/rack/components/ClickableIcon.tsx
+++ b/src/domains/serverView/rack/components/ClickableIcon.tsx
@@ -1,5 +1,13 @@
+/**
+ * @author 구희원
+ * @description 클릭 가능한 아이콘 컴포넌트 (Konva)
+ */
+
 import { Group, Image } from "react-konva";
 
+/**
+ * 클릭 가능한 아이콘 props
+ */
 interface ClickableIconProps {
   image: HTMLImageElement | null;
   x: number;
@@ -9,6 +17,17 @@ interface ClickableIconProps {
   onClick: () => void;
 }
 
+/**
+ * 클릭 가능한 아이콘
+ * @param {ClickableIconProps} props - 아이콘 속성
+ * @param {HTMLImageElement | null} props.image - 표시할 이미지
+ * @param {number} props.x - X 좌표
+ * @param {number} props.y - Y 좌표
+ * @param {number} props.width - 너비
+ * @param {number} props.height - 높이
+ * @param {() => void} props.onClick - 클릭 이벤트 핸들러
+ * @returns 클릭 가능한 아이콘 컴포넌트
+ */
 function ClickableIcon({
   image,
   x,
diff --git a/src/domains/serverView/rack/components/Device.tsx b/src/domains/serverView/rack/components/Device.tsx
index a98cae6..fd4037b 100644
--- a/src/domains/serverView/rack/components/Device.tsx
+++ b/src/domains/serverView/rack/components/Device.tsx
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 랙 장비 디바이스 컴포넌트 (Konva)
+ */
+
 import { Group, Rect, Text, Line, Image } from "react-konva";
 import { useState, memo, useRef, useEffect } from "react";
 import { Html } from "react-konva-utils";
@@ -10,14 +15,23 @@ import deleteIcon from "../assets/delete.svg";
 import checkIcon from "../assets/check.svg";
 import ClickableIcon from "./ClickableIcon";
 
+/**
+ * 시스템 데이터
+ */
 interface SystemData {
   cpu: number;
   memory: number;
   disk: number;
 }
 
+/**
+ * 알림 상태 타입
+ */
 type AlertStatus = "normal" | "warning" | "critical";
 
+/**
+ * 디바이스 컴포넌트 props
+ */
 interface DeviceProps {
   device: Equipments;
   y: number;
@@ -40,6 +54,11 @@ interface DeviceProps {
   currentSystemData?: SystemData | null;
 }
 
+/**
+ * 랙 장비 디바이스
+ * @param {DeviceProps} props - 디바이스 속성
+ * @returns 디바이스 컴포넌트
+ */
 function Device({
   device,
   y,
@@ -78,7 +97,9 @@ function Device({
   const deleteImage = useImageLoad(deleteIcon);
   const checkImage = useImageLoad(checkIcon);
 
-  // 임계치 상태에 따른 색상 결정
+  /**
+   * 알림 상태에 따른 색상 반환
+   */
   const getAlertColor = () => {
     switch (alertStatus) {
       case "critical":
@@ -90,6 +111,9 @@ function Device({
     }
   };
 
+  /**
+   * 알림 상태에 따른 투명도 반환
+   */
   const getAlertOpacity = () => {
     switch (alertStatus) {
       case "critical":
@@ -211,7 +235,7 @@ function Device({
             <input
               ref={inputRef}
               type="text"
-              defaultValue={tempDeviceName} // value 대신 defaultValue
+              defaultValue={tempDeviceName}
               onCompositionStart={() => setIsComposing(true)}
               onCompositionEnd={() => setIsComposing(false)}
               onKeyDown={(e) => {
diff --git a/src/domains/serverView/rack/components/Dropdown.tsx b/src/domains/serverView/rack/components/Dropdown.tsx
index e5057d4..ed1557b 100644
--- a/src/domains/serverView/rack/components/Dropdown.tsx
+++ b/src/domains/serverView/rack/components/Dropdown.tsx
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 장비 선택 드롭다운 컴포넌트
+ */
+
 import { useEffect, useRef } from "react";
 import type { EquipmentCard } from "../types";
 
+/**
+ * 드롭다운 컴포넌트 props
+ */
 interface DropdownProps {
   open: boolean;
   position: { x: number; y: number };
@@ -13,6 +21,20 @@ interface DropdownProps {
   isFetchingNextPage?: boolean;
 }
 
+/**
+ * 장비 선택 드롭다운
+ * @param {DropdownProps} props - 드롭다운 속성
+ * @param {boolean} props.open - 드롭다운 열림 상태
+ * @param {{ x: number; y: number }} props.position - 드롭다운 위치
+ * @param {EquipmentCard[]} props.items - 장비 목록
+ * @param {(item: EquipmentCard) => void} props.onSelect - 장비 선택 핸들러
+ * @param {() => void} props.onClose - 드롭다운 닫기 핸들러
+ * @param {boolean} props.isLoading - 로딩 상태
+ * @param {boolean} props.hasNextPage - 다음 페이지 존재 여부
+ * @param {() => Promise<unknown>} props.fetchNextPage - 다음 페이지 조회 함수
+ * @param {boolean} props.isFetchingNextPage - 다음 페이지 조회 중 상태
+ * @returns 드롭다운 컴포넌트
+ */
 function Dropdown({
   open,
   position,
@@ -27,6 +49,7 @@ function Dropdown({
   const dropdownRef = useRef<HTMLDivElement>(null);
   const scrollContainerRef = useRef<HTMLDivElement>(null);
 
+  // 무한 스크롤 처리
   useEffect(() => {
     const scrollContainer = scrollContainerRef.current;
     if (!scrollContainer) {
@@ -49,6 +72,7 @@ function Dropdown({
     };
   }, [open, hasNextPage, isFetchingNextPage, fetchNextPage]);
 
+  // 외부 클릭 및 컨텍스트 메뉴 처리
   useEffect(() => {
     if (!open) return;
 
diff --git a/src/domains/serverView/rack/components/Rack.tsx b/src/domains/serverView/rack/components/Rack.tsx
index 79080f4..dbb248f 100644
--- a/src/domains/serverView/rack/components/Rack.tsx
+++ b/src/domains/serverView/rack/components/Rack.tsx
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 서버 랙 시각화 컴포넌트 (Konva)
+ */
+
 import { Stage, Layer, Rect, Line, Text } from "react-konva";
 import { useMemo, Fragment, useCallback } from "react";
 import type { KonvaEventObject } from "konva/lib/Node";
@@ -11,14 +16,23 @@ import {
 } from "../utils/rackCalculation";
 import { rackLayout } from "../utils/rackLayout";
 
+/**
+ * 간단한 메트릭 정보
+ */
 interface SimpleMetrics {
   cpu: number;
   memory: number;
   disk: number;
 }
 
+/**
+ * 알림 상태 타입
+ */
 type AlertStatus = "normal" | "warning" | "critical";
 
+/**
+ * 랙 컴포넌트 props
+ */
 interface RackProps {
   devices: Equipments[];
   floatingDevice: FloatingDevice | null;
@@ -39,8 +53,16 @@ interface RackProps {
   allDeviceMetrics: Map<number, SimpleMetrics>;
 }
 
+/**
+ * 플로팅 장비 임시 ID
+ */
 const FLOATING_DEVICE_ID = -1;
 
+/**
+ * 서버 랙 시각화
+ * @param {RackProps} props - 랙 속성
+ * @returns 랙 컴포넌트
+ */
 function Rack({
   devices,
   floatingDevice,
@@ -73,6 +95,9 @@ function Rack({
     [floatingDevice, rackHeight, baseY, unitHeight]
   );
 
+  /**
+   * 장비 드래그 종료 처리
+   */
   const handleDeviceDragEnd = useCallback(
     (deviceId: number, newY: number) => {
       const draggedDevice = devices.find((d) => d.id === deviceId);
@@ -89,6 +114,9 @@ function Rack({
     [devices, onDeviceDragEnd, baseY, unitHeight]
   );
 
+  /**
+   * 마우스 이동 처리
+   */
   const handleMouseMove = (e: KonvaEventObject<MouseEvent>) => {
     const stage = e.target.getStage();
     if (!stage) return;
@@ -97,12 +125,18 @@ function Rack({
     if (pos) onMouseMove(pos.y);
   };
 
+  /**
+   * 랙 클릭 처리
+   */
   const handleRackClick = () => {
     if (floatingDevice && floatingInfo) {
       onRackClick(floatingInfo.position);
     }
   };
 
+  /**
+   * 장비의 알림 상태 계산
+   */
   const getDeviceAlertStatus = (equipment: Equipments): AlertStatus => {
     const metrics = allDeviceMetrics.get(equipment.id);
     if (!metrics) return "normal";
@@ -147,6 +181,7 @@ function Rack({
         onClick={handleRackClick}
       >
         <Layer>
+          {/* 랙 본체 */}
           <Rect
             x={rackX}
             y={baseY}
@@ -157,6 +192,7 @@ function Rack({
             strokeWidth={1}
           />
 
+          {/* U 단위 그리드 및 라벨 */}
           {Array.from({ length: UNIT_COUNT + 1 }).map((_, i) => {
             const unitNumber = UNIT_COUNT - i;
             const yPos = baseY + i * unitHeight;
@@ -181,6 +217,7 @@ function Rack({
             );
           })}
 
+          {/* 배치된 장비들 */}
           {devices.map((device) => {
             const y = calculateDeviceY(
               device.startUnit,
@@ -225,6 +262,7 @@ function Rack({
             );
           })}
 
+          {/* 플로팅 장비 (드래그 중인 장비 미리보기) */}
           {floatingDevice && floatingInfo && (
             <Device
               device={{
diff --git a/src/domains/serverView/rack/components/RackHeader.tsx b/src/domains/serverView/rack/components/RackHeader.tsx
index f4143c9..981bb9c 100644
--- a/src/domains/serverView/rack/components/RackHeader.tsx
+++ b/src/domains/serverView/rack/components/RackHeader.tsx
@@ -1,8 +1,23 @@
+/**
+ * @author 구희원
+ * @description 랙 헤더 컴포넌트
+ */
+
+/**
+ * 랙 헤더 props
+ */
 interface RackHeaderProps {
   rackName?: string;
   onClose?: () => void;
 }
 
+/**
+ * 랙 헤더
+ * @param {RackHeaderProps} props - 헤더 속성
+ * @param {string} props.rackName - 랙 이름 (기본값: "N/A")
+ * @param {() => void} props.onClose - 닫기 버튼 클릭 핸들러
+ * @returns 랙 헤더 컴포넌트
+ */
 function RackHeader({ rackName = "N/A", onClose }: RackHeaderProps) {
   return (
     <div className="flex items-center justify-between w-full">
diff --git a/src/domains/serverView/rack/components/RackView.tsx b/src/domains/serverView/rack/components/RackView.tsx
index a98949d..52fa0f2 100644
--- a/src/domains/serverView/rack/components/RackView.tsx
+++ b/src/domains/serverView/rack/components/RackView.tsx
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 랙 상세 뷰 컴포넌트
+ */
+
 import Rack from "../components/Rack";
 import { useRackManager } from "../hooks/useRackManager";
 import Sidebar from "./Sidebar";
@@ -10,12 +15,23 @@ import { useEquipmentSSE } from "../../serverDashboard/hooks/useEquipmentSSE";
 import { useAllEquipmentBackgroundSSE } from "../../serverDashboard/hooks/useAllEquipmentBackgroundSSE";
 import { useAuthStore } from "@/domains/login/store/useAuthStore";
 
+/**
+ * 랙 뷰 props
+ */
 interface RackViewProps {
   onClose?: () => void;
   rackName?: string;
   serverRoomId: number;
 }
 
+/**
+ * 랙 상세 뷰
+ * @param {RackViewProps} props - 랙 뷰 속성
+ * @param {() => void} props.onClose - 닫기 핸들러
+ * @param {string} props.rackName - 랙 이름
+ * @param {number} props.serverRoomId - 서버룸 ID
+ * @returns 랙 상세 뷰 컴포넌트
+ */
 function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
   const [frontView, setFrontView] = useState(true);
   const [editMode, setEditMode] = useState(false);
@@ -36,6 +52,9 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
   const { user } = useAuthStore();
   const view = user?.role === "VIEWER";
 
+  /**
+   * 랙 이름에서 ID 추출
+   */
   const rackId = useMemo(() => {
     if (!rackName) return undefined;
     const parts = rackName.split("-");
@@ -49,11 +68,17 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
     frontView,
   });
 
+  /**
+   * 선택된 장비 정보
+   */
   const selectedEquipment = useMemo(
     () => rackManager.equipments?.find((eq) => eq.id === selectedDevice?.id),
     [rackManager.equipments, selectedDevice?.id]
   );
 
+  /**
+   * 모니터링 가능한 장비 ID 목록 (SERVER, STORAGE만)
+   */
   const selectableEquipmentIds = useMemo(
     () =>
       rackManager.equipments
@@ -65,13 +90,22 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
     [rackManager.equipments]
   );
 
+  /**
+   * 백그라운드 SSE 대상 장비 ID 목록
+   */
   const backgroundSSEEquipmentIds = useMemo(() => {
-    if (rackManager.isLoading || selectableEquipmentIds.length === 0) {
-      return [];
+    const shouldStart =
+      !rackManager.isLoading && selectableEquipmentIds.length > 0;
+
+    if (shouldStart) {
+      return selectableEquipmentIds;
     }
-    return selectableEquipmentIds.filter((id) => id !== selectedDevice?.id);
-  }, [rackManager.isLoading, selectableEquipmentIds, selectedDevice?.id]);
+    return [];
+  }, [rackManager.isLoading, selectableEquipmentIds]);
 
+  /**
+   * 백그라운드 SSE 콜백
+   */
   const backgroundCallbacks = useCallback(
     () => ({
       onMetricsUpdate: setDeviceMetrics,
@@ -85,6 +119,9 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
     [rackId, setDeviceMetrics]
   );
 
+  /**
+   * 선택된 장비 SSE 콜백
+   */
   const equipmentCallbacks = useCallback(
     () => ({
       onSystemData: setSystemData,
@@ -131,6 +168,9 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
 
   const displayRackName = rackManager.rack?.rackName || rackName || "N/A";
 
+  /**
+   * 장비 클릭 핸들러
+   */
   const handleDeviceClick = (deviceId: number, deviceName: string) => {
     const equipment = rackManager.equipments?.find((eq) => eq.id === deviceId);
     if (
@@ -143,10 +183,16 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
     }
   };
 
+  /**
+   * 대시보드 닫기 핸들러
+   */
   const handleDashboardClose = () => {
     setDashboardOpen(false);
   };
 
+  /**
+   * 사이드바 클릭 핸들러
+   */
   const handleSidebarClick = () => {
     if (dashboardOpen) {
       handleDashboardClose();
@@ -175,6 +221,7 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
 
   return (
     <div className="h-full flex text-white gap-2 p-2">
+      {/* 서버 대시보드 영역 */}
       <div
         className="flex-[2] overflow-hidden relative"
         onClick={handleSidebarClick}
@@ -190,8 +237,10 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
         />
       </div>
 
+      {/* 랙 뷰 영역 */}
       <div className="flex-1 overflow-visible relative">
         <div className="h-full flex flex-col bg-[#404452]/70 backdrop-blur-md border border-slate-300/40 rounded-xl">
+          {/* 헤더 */}
           <header className="flex justify-between items-center px-6 py-4 border-b border-slate-300/40 flex-shrink-0">
             <div className="flex-1">
               <RackHeader rackName={displayRackName} />
@@ -213,6 +262,7 @@ function RackView({ rackName, serverRoomId, onClose }: RackViewProps) {
             </div>
           </header>
 
+          {/* 메인 콘텐츠 */}
           <div className="flex flex-1 min-h-0 overflow-visible">
             <Sidebar
               onCardClick={rackManager.handleCardClick}
diff --git a/src/domains/serverView/rack/components/Sidebar.tsx b/src/domains/serverView/rack/components/Sidebar.tsx
index faeb252..968c072 100644
--- a/src/domains/serverView/rack/components/Sidebar.tsx
+++ b/src/domains/serverView/rack/components/Sidebar.tsx
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 랙 편집 사이드바 컴포넌트
+ */
+
 import { useState } from "react";
 import Tools from "./Tools";
 import Dropdown from "./Dropdown";
@@ -5,11 +10,21 @@ import type { EquipmentCard, UnassignedEquipment } from "../types";
 import { useUnassignedEquipments } from "../hooks/useGetUnassignedEquipments";
 import { deviceImageMap } from "../utils/deviceImageMap";
 
+/**
+ * 사이드바 props
+ */
 interface SidebarProps {
   onCardClick: (card: EquipmentCard) => void;
   isOpen: boolean;
 }
 
+/**
+ * 랙 편집 사이드바
+ * @param {SidebarProps} props - 사이드바 속성
+ * @param {(card: EquipmentCard) => void} props.onCardClick - 장비 카드 클릭 핸들러
+ * @param {boolean} props.isOpen - 사이드바 열림 상태
+ * @returns 사이드바 컴포넌트
+ */
 function Sidebar({ onCardClick, isOpen }: SidebarProps) {
   const [dropdownOpen, setDropdownOpen] = useState(false);
   const [dropdownPosition, setDropdownPosition] = useState({ x: 0, y: 0 });
@@ -20,6 +35,9 @@ function Sidebar({ onCardClick, isOpen }: SidebarProps) {
       enabled: dropdownOpen,
     });
 
+  /**
+   * 컨텍스트 메뉴(우클릭) 핸들러
+   */
   const handleContextMenu = (e: React.MouseEvent, card: EquipmentCard) => {
     e.preventDefault();
     e.stopPropagation();
@@ -40,15 +58,24 @@ function Sidebar({ onCardClick, isOpen }: SidebarProps) {
     setDropdownOpen(true);
   };
 
+  /**
+   * 드롭다운 장비 선택 핸들러
+   */
   const handleDropdownSelect = (item: EquipmentCard) => {
     onCardClick(item);
     setDropdownOpen(false);
   };
 
+  /**
+   * 드롭다운 닫기 핸들러
+   */
   const handleDropdownClose = () => {
     setDropdownOpen(false);
   };
 
+  /**
+   * 선택된 타입에 맞는 미할당 장비 필터링
+   */
   const getFilteredEquipments = (): EquipmentCard[] => {
     if (!selectedCard || !data?.allEquipments) {
       return [];
diff --git a/src/domains/serverView/rack/components/Tools.tsx b/src/domains/serverView/rack/components/Tools.tsx
index fa07e5a..2da80f9 100644
--- a/src/domains/serverView/rack/components/Tools.tsx
+++ b/src/domains/serverView/rack/components/Tools.tsx
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 장비 타입 선택 도구 컴포넌트
+ */
+
 import serverImg from "../assets/server.svg";
 import storageImg from "../assets/storage.svg";
 import switchImg from "../assets/switch.svg";
@@ -9,12 +14,25 @@ import type { EquipmentCard } from "../types";
 import { typeColorMap } from "../utils/colorMap";
 import Tooltip from "./Tooltip";
 
+/**
+ * 도구 컴포넌트 props
+ */
 interface ToolsProps {
   onCardClick: (card: EquipmentCard) => void;
   onContextMenu: (e: React.MouseEvent, card: EquipmentCard) => void;
 }
 
+/**
+ * 장비 타입 선택 도구
+ * @param {ToolsProps} props - 도구 속성
+ * @param {(card: EquipmentCard) => void} props.onCardClick - 카드 클릭 핸들러
+ * @param {(e: React.MouseEvent, card: EquipmentCard) => void} props.onContextMenu - 컨텍스트 메뉴 핸들러
+ * @returns 도구 컴포넌트
+ */
 function Tools({ onCardClick, onContextMenu }: ToolsProps) {
+  /**
+   * 사용 가능한 장비 타입 목록
+   */
   const deviceCards: EquipmentCard[] = [
     {
       key: "server",
diff --git a/src/domains/serverView/rack/components/Tooltip.tsx b/src/domains/serverView/rack/components/Tooltip.tsx
index d76ad3d..6ba3e3f 100644
--- a/src/domains/serverView/rack/components/Tooltip.tsx
+++ b/src/domains/serverView/rack/components/Tooltip.tsx
@@ -1,15 +1,33 @@
+/**
+ * @author 구희원
+ * @description 툴팁 컴포넌트
+ */
+
 import { useState } from "react";
 import { createPortal } from "react-dom";
 
+/**
+ * 툴팁 props
+ */
 interface TooltipProps {
   children: React.ReactNode;
   content: string;
 }
 
+/**
+ * 툴팁
+ * @param {TooltipProps} props - 툴팁 속성
+ * @param {React.ReactNode} props.children - 툴팁을 표시할 대상 요소
+ * @param {string} props.content - 툴팁 내용
+ * @returns 툴팁 컴포넌트
+ */
 function Tooltip({ children, content }: TooltipProps) {
   const [visible, setVisible] = useState(false);
   const [coords, setCoords] = useState({ x: 0, y: 0, height: 0 });
 
+  /**
+   * 마우스 진입 핸들러
+   */
   const handleEnter = (e: React.MouseEvent) => {
     const rect = e.currentTarget.getBoundingClientRect();
     setCoords({ x: rect.right, y: rect.top, height: rect.height });
diff --git a/src/domains/serverView/rack/constants/rackConstants.ts b/src/domains/serverView/rack/constants/rackConstants.ts
index 3a2f9c1..c5e3c8b 100644
--- a/src/domains/serverView/rack/constants/rackConstants.ts
+++ b/src/domains/serverView/rack/constants/rackConstants.ts
@@ -1,5 +1,22 @@
+/**
+ * @author 구희원
+ * @description 랙 설정 상수
+ */
+
+/**
+ * 랙의 총 U 수 (42U 표준 랙)
+ */
 export const UNIT_COUNT = 42;
 
+/**
+ * 랙 렌더링 설정
+ * @property {number} width - 랙 너비 (px)
+ * @property {number} height - 랙 높이 (px)
+ * @property {number} frameThickness - 프레임 두께 (px)
+ * @property {number} panelWidth - 패널 너비 (px)
+ * @property {number} leftPanelOffset - 왼쪽 패널 오프셋 (px)
+ * @property {number} unitHeight - 1U 높이 (px)
+ */
 export const RACK_CONFIG = {
   width: 350,
   height: 700,
diff --git a/src/domains/serverView/rack/hooks/useDeleteRackEquipments.ts b/src/domains/serverView/rack/hooks/useDeleteRackEquipments.ts
index e46a3bb..6e28ea0 100644
--- a/src/domains/serverView/rack/hooks/useDeleteRackEquipments.ts
+++ b/src/domains/serverView/rack/hooks/useDeleteRackEquipments.ts
@@ -1,18 +1,33 @@
+/**
+ * @author 구희원
+ * @description 랙 장비 삭제 훅
+ */
+
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { deleteRackEquipments } from "../api/deleteRackEquipments";
 import type { RackEquipmentsResult } from "../types";
 
+/**
+ * 랙 장비 API 응답
+ */
 interface RackEquipmentResponse {
   status_code: number;
   status_message: string;
   result: RackEquipmentsResult;
 }
 
+/**
+ * 장비 삭제 파라미터
+ */
 interface DeleteEquipmentParams {
   id: number;
   rackId: number;
 }
 
+/**
+ * 랙 장비 삭제 훅
+ * @returns {UseMutationResult} 장비 삭제 mutation
+ */
 export const useDeleteEquipments = () => {
   const queryClient = useQueryClient();
 
@@ -20,6 +35,7 @@ export const useDeleteEquipments = () => {
     mutationFn: (params: DeleteEquipmentParams) =>
       deleteRackEquipments(params.id),
 
+    // Optimistic Update
     onMutate: async (params: DeleteEquipmentParams) => {
       await queryClient.cancelQueries({
         queryKey: ["rackEquipments", params.rackId],
@@ -53,6 +69,7 @@ export const useDeleteEquipments = () => {
     },
     retry: false,
 
+    // 에러 발생 시 롤백
     onError: (_, __, context) => {
       if (context?.previousData && context?.rackId) {
         queryClient.setQueryData(
@@ -62,6 +79,7 @@ export const useDeleteEquipments = () => {
       }
     },
 
+    // 완료 후 쿼리 무효화
     onSettled: (_, __, variables) => {
       queryClient.invalidateQueries({
         queryKey: ["rackEquipments", variables.rackId],
diff --git a/src/domains/serverView/rack/hooks/useGetRackEquipments.ts b/src/domains/serverView/rack/hooks/useGetRackEquipments.ts
index 6dec57f..fb22b79 100644
--- a/src/domains/serverView/rack/hooks/useGetRackEquipments.ts
+++ b/src/domains/serverView/rack/hooks/useGetRackEquipments.ts
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 랙 장비 목록 조회 훅
+ */
+
 import { useQuery } from "@tanstack/react-query";
 import {
   getRackEquipments,
@@ -5,12 +10,21 @@ import {
 } from "../api/getRackEquipments";
 import type { RackEquipmentsResult } from "../types";
 
+/**
+ * 랙 장비 API 응답
+ */
 interface RackEquipmentResponse {
   status_code: number;
   status_message: string;
   result: RackEquipmentsResult;
 }
 
+/**
+ * 랙 장비 목록 조회 훅
+ * @param {number} rackId - 조회할 랙 ID
+ * @param {GetRackEquipmentsParams} params - 조회 파라미터 (status, type, sortBy)
+ * @returns 랙 장비 목록 및 상태
+ */
 export const useGetRackEquipments = (
   rackId: number,
   params?: GetRackEquipmentsParams
diff --git a/src/domains/serverView/rack/hooks/useGetUnassignedEquipments.ts b/src/domains/serverView/rack/hooks/useGetUnassignedEquipments.ts
index c1545cd..4cd5bb5 100644
--- a/src/domains/serverView/rack/hooks/useGetUnassignedEquipments.ts
+++ b/src/domains/serverView/rack/hooks/useGetUnassignedEquipments.ts
@@ -1,14 +1,29 @@
+/**
+ * @author 구희원
+ * @description 미할당 장비 목록 조회 훅 (무한 스크롤)
+ */
+
 import { useInfiniteQuery } from "@tanstack/react-query";
 import {
   getUnassignedEquipments,
   type GetUnassignedEquipmentsParams,
 } from "../api/getUnassignedEquipments";
 
+/**
+ * 미할당 장비 조회 옵션
+ */
 interface UseUnassignedEquipmentsOptions {
   params?: GetUnassignedEquipmentsParams;
   enabled?: boolean;
 }
 
+/**
+ * 미할당 장비 목록 조회 훅 (무한 스크롤)
+ * @param {UseUnassignedEquipmentsOptions} options - 조회 옵션
+ * @param {GetUnassignedEquipmentsParams} options.params - 조회 파라미터
+ * @param {boolean} options.enabled - 쿼리 활성화 여부
+ * @returns 미할당 장비 목록 및 페이지네이션 상태
+ */
 export const useUnassignedEquipments = (
   options: UseUnassignedEquipmentsOptions = {}
 ) => {
diff --git a/src/domains/serverView/rack/hooks/useImageLoad.ts b/src/domains/serverView/rack/hooks/useImageLoad.ts
index c0859a3..6a743cc 100644
--- a/src/domains/serverView/rack/hooks/useImageLoad.ts
+++ b/src/domains/serverView/rack/hooks/useImageLoad.ts
@@ -1,5 +1,15 @@
+/**
+ * @author 구희원
+ * @description 이미지 로드 훅
+ */
+
 import { useState, useEffect } from "react";
 
+/**
+ * 이미지 로드 훅
+ * @param {string} src - 이미지 소스 URL
+ * @returns {HTMLImageElement | null} 로드된 이미지 객체 (로드 전에는 null)
+ */
 export function useImageLoad(src: string) {
   const [image, setImage] = useState<HTMLImageElement | null>(null);
 
diff --git a/src/domains/serverView/rack/hooks/usePostPlaceEquipments.ts b/src/domains/serverView/rack/hooks/usePostPlaceEquipments.ts
index 2a9861d..eb4c9be 100644
--- a/src/domains/serverView/rack/hooks/usePostPlaceEquipments.ts
+++ b/src/domains/serverView/rack/hooks/usePostPlaceEquipments.ts
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 랙에 장비 배치 훅
+ */
+
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { postPlaceEquipments } from "../api/postPlaceEquipments";
 
+/**
+ * 장비 배치 파라미터
+ */
 interface PostPlaceEquipmentParams {
   rackId: number;
   id: number;
@@ -10,6 +18,10 @@ interface PostPlaceEquipmentParams {
   };
 }
 
+/**
+ * 랙에 장비 배치 훅
+ * @returns {UseMutationResult} 장비 배치 mutation
+ */
 export const usePostPlaceEquipments = () => {
   const queryClient = useQueryClient();
 
diff --git a/src/domains/serverView/rack/hooks/usePostRackEquipments.ts b/src/domains/serverView/rack/hooks/usePostRackEquipments.ts
index 7c60779..609c57b 100644
--- a/src/domains/serverView/rack/hooks/usePostRackEquipments.ts
+++ b/src/domains/serverView/rack/hooks/usePostRackEquipments.ts
@@ -1,7 +1,16 @@
+/**
+ * @author 구희원
+ * @description 랙 장비 생성 훅
+ */
+
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { postRackEquipment } from "../api/postRackEquipments";
 import type { PostEquipmentRequest } from "../api/postRackEquipments";
 
+/**
+ * 랙 장비 생성 훅
+ * @returns {UseMutationResult} 장비 생성 mutation
+ */
 export const usePostEquipment = () => {
   const queryClient = useQueryClient();
 
diff --git a/src/domains/serverView/rack/hooks/useRackManager.ts b/src/domains/serverView/rack/hooks/useRackManager.ts
index 6f16305..f973de7 100644
--- a/src/domains/serverView/rack/hooks/useRackManager.ts
+++ b/src/domains/serverView/rack/hooks/useRackManager.ts
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 랙 관리 훅 (장비 배치, 드래그, 삭제 등 전체 로직)
+ */
+
 import { useState, useCallback, useMemo } from "react";
 import type { Equipments, FloatingDevice, EquipmentCard } from "../types";
 import { checkCollision } from "../utils/rackCollisionDetection";
@@ -9,12 +14,25 @@ import { useUpdateRackEquipments } from "./useUpdateRackEquipments";
 import type { GetRackEquipmentsParams } from "../api/getRackEquipments";
 import type { PostEquipmentRequest } from "../api/postRackEquipments";
 
+/**
+ * 랙 매니저 props
+ */
 interface UseRackManagerProps {
   rackId: number;
   params?: GetRackEquipmentsParams;
   frontView?: boolean;
   serverRoomId: number;
 }
+
+/**
+ * 랙 관리 훅
+ * @param {UseRackManagerProps} props - 랙 매니저 속성
+ * @param {number} props.rackId - 랙 ID
+ * @param {GetRackEquipmentsParams} props.params - 장비 조회 파라미터
+ * @param {boolean} props.frontView - 앞면/뒷면 뷰 상태
+ * @param {number} props.serverRoomId - 서버룸 ID
+ * @returns 랙 관리 상태 및 핸들러 함수들
+ */
 export function useRackManager({
   rackId,
   params,
@@ -30,28 +48,33 @@ export function useRackManager({
     new Map()
   );
 
-  //GET
+  // GET - 장비 목록 조회
   const { equipments, rack, isLoading, error } = useGetRackEquipments(
     rackId || 0,
     params
   );
 
-  //POST
+  // POST - 장비 생성 및 배치
   const { mutate: postEquipment } = usePostEquipment();
   const { mutate: postPlaceEquipments } = usePostPlaceEquipments();
 
-  //DELETE
+  // DELETE - 장비 삭제
   const { mutate: deleteEquipment } = useDeleteEquipments();
 
-  //UPDATE
+  // UPDATE - 장비 수정
   const { mutate: updateEquipment } = useUpdateRackEquipments();
 
+  /**
+   * 설치된 장비 목록 (서버 데이터 + 임시 장비)
+   */
   const installedDevices = useMemo(() => {
     const devices = [...(equipments || []), ...tempDevices];
     return devices;
   }, [equipments, tempDevices]);
 
-  // 카드 클릭 핸들러
+  /**
+   * 장비 카드 클릭 핸들러
+   */
   const handleCardClick = useCallback((card: EquipmentCard) => {
     setFloatingDevice({
       card,
@@ -59,12 +82,16 @@ export function useRackManager({
     });
   }, []);
 
-  // 마우스 이동
+  /**
+   * 마우스 이동 핸들러
+   */
   const handleMouseMove = useCallback((mouseY: number) => {
     setFloatingDevice((prev) => (prev ? { ...prev, mouseY } : null));
   }, []);
 
-  // 드래그 종료 핸들러
+  /**
+   * 장비 드래그 종료 핸들러
+   */
   const handleDeviceDragEnd = useCallback(
     (deviceId: number, newPosition: number) => {
       const draggedDevice = installedDevices.find((d) => d.id === deviceId);
@@ -102,7 +129,9 @@ export function useRackManager({
     [updateEquipment, rackId, installedDevices]
   );
 
-  // 랙 클릭 핸들러
+  /**
+   * 랙 클릭 핸들러 (장비 배치)
+   */
   const handleRackClick = useCallback(
     (position: number) => {
       setFloatingDevice((prevFloating) => {
@@ -119,7 +148,7 @@ export function useRackManager({
           return prevFloating;
         }
 
-        //드롭다운에서 선택한 기존 장비인 경우
+        // 드롭다운에서 선택한 기존 장비인 경우
         if (prevFloating.card.id) {
           postPlaceEquipments({
             rackId,
@@ -132,6 +161,7 @@ export function useRackManager({
           return null;
         }
 
+        // 새 장비 생성 (임시)
         const tempId = Date.now();
         const newDevice: Equipments = {
           id: tempId,
@@ -172,6 +202,9 @@ export function useRackManager({
     [frontView, editingDeviceId, installedDevices, postPlaceEquipments, rackId]
   );
 
+  /**
+   * 장비명 변경 핸들러
+   */
   const handleDeviceNameChange = useCallback(
     (deviceId: number, name: string) => {
       setTempDeviceName((prev) => {
@@ -183,7 +216,9 @@ export function useRackManager({
     []
   );
 
-  // Enter 누름 → 이름 확정 & 배치 → 그 다음 서버 요청
+  /**
+   * 장비명 확정 핸들러 (Enter 또는 확인 버튼)
+   */
   const handleDeviceNameConfirm = useCallback(
     (device: Equipments, inputName?: string) => {
       const name = inputName ?? tempDeviceName.get(device.id) ?? "";
@@ -234,6 +269,9 @@ export function useRackManager({
     [rackId, postEquipment, tempDeviceName]
   );
 
+  /**
+   * 장비명 입력 취소 핸들러 (ESC 또는 취소 버튼)
+   */
   const handleDeviceNameCancel = useCallback((deviceId: number) => {
     setTempDevices((prevDevices) =>
       prevDevices.filter((device) => device.id !== deviceId)
@@ -246,7 +284,9 @@ export function useRackManager({
     setEditingDeviceId(null);
   }, []);
 
-  //장비 삭제 함수 추가
+  /**
+   * 장비 삭제 핸들러
+   */
   const handleDeviceDelete = useCallback(
     (deviceId: number) => {
       deleteEquipment({ id: deviceId, rackId });
@@ -254,6 +294,9 @@ export function useRackManager({
     [deleteEquipment, rackId]
   );
 
+  /**
+   * 임시 장비명 조회
+   */
   const getDeviceName = useCallback(
     (deviceId: number) => {
       return tempDeviceName.get(deviceId) || "";
diff --git a/src/domains/serverView/rack/hooks/useUpdateRackEquipments.ts b/src/domains/serverView/rack/hooks/useUpdateRackEquipments.ts
index f7abac4..4d49adc 100644
--- a/src/domains/serverView/rack/hooks/useUpdateRackEquipments.ts
+++ b/src/domains/serverView/rack/hooks/useUpdateRackEquipments.ts
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 랙 장비 수정 훅
+ */
+
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import {
   updateRackEquipments,
@@ -5,12 +10,19 @@ import {
 } from "../api/updateRackEquipments";
 import type { RackEquipmentsResult } from "../types";
 
+/**
+ * 랙 장비 API 응답
+ */
 interface RackEquipmentResponse {
   status_code: number;
   status_message: string;
   result: RackEquipmentsResult;
 }
 
+/**
+ * 랙 장비 수정 훅
+ * @returns {UseMutationResult} 장비 수정 mutation
+ */
 export const useUpdateRackEquipments = () => {
   const queryClient = useQueryClient();
 
@@ -25,6 +37,7 @@ export const useUpdateRackEquipments = () => {
       return updateRackEquipments(id, data);
     },
 
+    // Optimistic Update
     onMutate: async ({ id, data }) => {
       await queryClient.cancelQueries({
         queryKey: ["rackEquipments", data.rackId],
@@ -59,6 +72,8 @@ export const useUpdateRackEquipments = () => {
     },
 
     retry: false,
+
+    // 성공 시 쿼리 무효화
     onSuccess: (_, variables) => {
       if (variables.data?.rackId) {
         queryClient.invalidateQueries({
@@ -69,6 +84,8 @@ export const useUpdateRackEquipments = () => {
       }
       console.log("장비 수정 성공");
     },
+
+    // 에러 발생 시 롤백
     onError: (error, _, context) => {
       console.error("장비 수정 실패", error);
       if (context?.previousData) {
diff --git a/src/domains/serverView/rack/types/index.ts b/src/domains/serverView/rack/types/index.ts
index a4779be..ef8bf56 100644
--- a/src/domains/serverView/rack/types/index.ts
+++ b/src/domains/serverView/rack/types/index.ts
@@ -1,3 +1,11 @@
+/**
+ * @author 구희원
+ * @description 랙 뷰 타입 정의
+ */
+
+/**
+ * 장비 타입
+ */
 export type EquipmentType =
   | "SERVER"
   | "SWITCH"
@@ -7,6 +15,9 @@ export type EquipmentType =
   | "LOAD_BALANCER"
   | "KVM";
 
+/**
+ * 장비 상태
+ */
 export type EquipmentStatus =
   | "NORMAL"
   | "WARNING"
@@ -15,8 +26,14 @@ export type EquipmentStatus =
   | "POWERED_OFF"
   | "DECOMMISSIONED";
 
+/**
+ * 장비 위치 (앞면/뒷면)
+ */
 export type EquipmentPosition = "FRONT" | "BACK";
 
+/**
+ * 장비 정보
+ */
 export interface Equipments {
   id: number;
   equipmentName: string;
@@ -38,18 +55,27 @@ export interface Equipments {
   diskThresholdCritical?: number;
 }
 
+/**
+ * 랙 정보
+ */
 export interface Rack {
   rackName: string;
   rackId: number;
   serverRoomId: number;
 }
 
+/**
+ * 랙 장비 목록 결과
+ */
 export interface RackEquipmentsResult {
   rack: Rack;
   equipments: Equipments[];
   totalEquipmentCount: number;
 }
 
+/**
+ * 장비 카드 정보
+ */
 export interface EquipmentCard {
   key: string;
   label: string;
@@ -60,16 +86,25 @@ export interface EquipmentCard {
   id?: number;
 }
 
+/**
+ * 플로팅 장비 (드래그 중인 장비)
+ */
 export interface FloatingDevice {
   card: EquipmentCard;
   mouseY: number;
 }
 
+/**
+ * 미할당 장비
+ */
 export interface UnassignedEquipment extends Equipments {
   rackId: number | null;
   rackName: string | null;
 }
 
+/**
+ * 장비 수정 요청
+ */
 export interface UpdateEquipmentRequest
   extends Pick<
     Equipments,
diff --git a/src/domains/serverView/rack/utils/colorMap.ts b/src/domains/serverView/rack/utils/colorMap.ts
index 6d37102..e4e8acf 100644
--- a/src/domains/serverView/rack/utils/colorMap.ts
+++ b/src/domains/serverView/rack/utils/colorMap.ts
@@ -1,3 +1,18 @@
+/**
+ * @author 구희원
+ * @description 장비 타입별 색상 매핑
+ */
+
+/**
+ * 장비 타입별 색상 맵
+ * @property {string} SERVER - 서버 색상 (하늘색)
+ * @property {string} SWITCH - 스위치 색상 (빨강)
+ * @property {string} ROUTER - 라우터 색상 (노랑)
+ * @property {string} STORAGE - 스토리지 색상 (초록)
+ * @property {string} FIREWALL - 방화벽 색상 (진한 빨강)
+ * @property {string} LOAD_BALANCER - 로드밸런서 색상 (청록)
+ * @property {string} KVM - KVM 색상 (분홍)
+ */
 export const typeColorMap: Record<string, string> = {
   SERVER: "#38bdf8",
   SWITCH: "#E80054",
diff --git a/src/domains/serverView/rack/utils/deviceImageMap.ts b/src/domains/serverView/rack/utils/deviceImageMap.ts
index a3a85d1..3b624d6 100644
--- a/src/domains/serverView/rack/utils/deviceImageMap.ts
+++ b/src/domains/serverView/rack/utils/deviceImageMap.ts
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 장비 타입별 이미지 매핑 (앞면/뒷면)
+ */
+
 import serverFrontImg from "../assets/serverFront.png";
 import serverBackImg from "../assets/serverBack.png";
 import storageFrontImg from "../assets/storageFront.png";
@@ -13,6 +18,16 @@ import loadBalanceBackImg from "../assets/loadbalanceBack.png";
 import routerBackImg from "../assets/routerBack.png";
 import StorageBackImg from "../assets/storageBack.png";
 
+/**
+ * 장비 타입별 이미지 맵
+ * @property {Object} SERVER - 서버 이미지
+ * @property {Object} STORAGE - 스토리지 이미지
+ * @property {Object} SWITCH - 스위치 이미지
+ * @property {Object} ROUTER - 라우터 이미지
+ * @property {Object} KVM - KVM 이미지
+ * @property {Object} FIREWALL - 방화벽 이미지
+ * @property {Object} LOAD_BALANCER - 로드밸런서 이미지
+ */
 export const deviceImageMap: Record<string, { front: string; back: string }> = {
   SERVER: { front: serverFrontImg, back: serverBackImg },
   STORAGE: { front: storageFrontImg, back: StorageBackImg },
diff --git a/src/domains/serverView/rack/utils/dragBound.ts b/src/domains/serverView/rack/utils/dragBound.ts
index 17c3228..5c46916 100644
--- a/src/domains/serverView/rack/utils/dragBound.ts
+++ b/src/domains/serverView/rack/utils/dragBound.ts
@@ -1,3 +1,20 @@
+/**
+ * @author 구희원
+ * @description 장비 드래그 경계 제한 유틸리티
+ */
+
+/**
+ * 장비 드래그 시 경계 제한 및 그리드 스냅
+ * @param {Object} pos - 현재 마우스 위치
+ * @param {number} pos.x - X 좌표
+ * @param {number} pos.y - Y 좌표
+ * @param {Object} config - 랙 설정
+ * @param {number} config.baseY - 랙 시작 Y 좌표
+ * @param {number} config.rackHeight - 랙 높이
+ * @param {number} config.deviceHeight - 장비 높이
+ * @param {number} config.unitHeight - 1U 높이
+ * @returns {Object} 제한된 위치 좌표 { x, y }
+ */
 export function dragBound(
   pos: { x: number; y: number },
   config: {
@@ -5,7 +22,7 @@ export function dragBound(
     rackHeight: number;
     deviceHeight: number;
     unitHeight: number;
-  },
+  }
 ) {
   const minY = config.baseY;
   const maxY = config.baseY + config.rackHeight - config.deviceHeight;
diff --git a/src/domains/serverView/rack/utils/rackCalculation.ts b/src/domains/serverView/rack/utils/rackCalculation.ts
index 3fd2776..17d4db7 100644
--- a/src/domains/serverView/rack/utils/rackCalculation.ts
+++ b/src/domains/serverView/rack/utils/rackCalculation.ts
@@ -1,11 +1,22 @@
+/**
+ * @author 구희원
+ * @description 랙 내 장비 위치 계산 유틸리티
+ */
+
 import { UNIT_COUNT } from "../constants/rackConstants";
 import type { FloatingDevice } from "../types";
 
-// 장비의 Y좌표를 랙 U위치로 변환
+/**
+ * 장비의 Y좌표를 랙 U위치로 변환
+ * @param {number} mouseY - 마우스 Y 좌표
+ * @param {number} baseY - 랙 시작 Y 좌표
+ * @param {number} unitHeight - 1U 높이
+ * @returns {number} U 위치 (1-42)
+ */
 export function calculationPosition(
   mouseY: number,
   baseY: number,
-  unitHeight: number,
+  unitHeight: number
 ): number {
   const relativeY = mouseY - baseY;
   const unit = Math.floor(relativeY / unitHeight);
@@ -13,33 +24,49 @@ export function calculationPosition(
   return Math.max(1, Math.min(UNIT_COUNT, position));
 }
 
-// Y좌표 계산
+/**
+ * U 위치를 Y좌표로 변환
+ * @param {number} position - U 위치
+ * @param {number} deviceHeight - 장비 높이 (U)
+ * @param {number} rackHeight - 랙 전체 높이
+ * @param {number} baseY - 랙 시작 Y 좌표
+ * @param {number} unitHeight - 1U 높이
+ * @returns {number} Y 좌표
+ */
 export function calculateDeviceY(
   position: number,
   deviceHeight: number,
   rackHeight: number,
   baseY: number,
-  unitHeight: number,
+  unitHeight: number
 ): number {
   return (
     rackHeight - (position - 1) * unitHeight - deviceHeight * unitHeight + baseY
   );
 }
 
-// 떠있는 장비의 렌더링 정보 계산
+/**
+ * 플로팅 장비의 렌더링 정보 계산
+ * @param {FloatingDevice | null} floatingDevice - 플로팅 장비 정보
+ * @param {Object} rackConfig - 랙 설정
+ * @param {number} rackConfig.rackHeight - 랙 높이
+ * @param {number} rackConfig.baseY - 랙 시작 Y 좌표
+ * @param {number} rackConfig.unitHeight - 1U 높이
+ * @returns {Object | null} 플로팅 장비 위치 정보 { position, y, height }
+ */
 export function getFloatingDeviceInfo(
   floatingDevice: FloatingDevice | null,
   rackConfig: {
     rackHeight: number;
     baseY: number;
     unitHeight: number;
-  },
+  }
 ) {
   if (!floatingDevice) return null;
   let position = calculationPosition(
     floatingDevice.mouseY,
     rackConfig.baseY,
-    rackConfig.unitHeight,
+    rackConfig.unitHeight
   );
 
   const minPosition = 1;
@@ -51,18 +78,25 @@ export function getFloatingDeviceInfo(
     floatingDevice.card.height,
     rackConfig.rackHeight,
     rackConfig.baseY,
-    rackConfig.unitHeight,
+    rackConfig.unitHeight
   );
   const height = rackConfig.unitHeight * floatingDevice.card.height;
   return { position, y, height };
 }
 
-// 드래그된 장비의 새 위치 계산
+/**
+ * 드래그된 장비의 새 위치 계산
+ * @param {number} newY - 새 Y 좌표
+ * @param {number} deviceHeight - 장비 높이 (U)
+ * @param {number} baseY - 랙 시작 Y 좌표
+ * @param {number} unitHeight - 1U 높이
+ * @returns {number} 새 U 위치
+ */
 export function calculateDraggedPosition(
   newY: number,
   deviceHeight: number,
   baseY: number,
-  unitHeight: number,
+  unitHeight: number
 ): number {
   // 1. 상단의 상대 Y 좌표
   const relativeY = newY - baseY;
diff --git a/src/domains/serverView/rack/utils/rackCollisionDetection.ts b/src/domains/serverView/rack/utils/rackCollisionDetection.ts
index e71de75..12c1995 100644
--- a/src/domains/serverView/rack/utils/rackCollisionDetection.ts
+++ b/src/domains/serverView/rack/utils/rackCollisionDetection.ts
@@ -1,6 +1,20 @@
+/**
+ * @author 구희원
+ * @description 랙 내 장비 충돌 감지 유틸리티
+ */
+
 import type { Equipments } from "../types";
 
-// 두 장비가 겹치는 지 확인
+/**
+ * 두 장비의 U 범위가 겹치는지 확인
+ * @param {Object} range1 - 첫 번째 장비 범위
+ * @param {number} range1.bottom - 하단 U 위치
+ * @param {number} range1.top - 상단 U 위치
+ * @param {Object} range2 - 두 번째 장비 범위
+ * @param {number} range2.bottom - 하단 U 위치
+ * @param {number} range2.top - 상단 U 위치
+ * @returns {boolean} 겹침 여부
+ */
 function Overlapping(
   range1: { bottom: number; top: number },
   range2: { bottom: number; top: number }
@@ -8,7 +22,15 @@ function Overlapping(
   return !(range1.top < range2.bottom || range1.bottom > range2.top);
 }
 
-// 새 장비가 기존 장비들과 충돌하는지 검사
+/**
+ * 새 장비가 기존 장비들과 충돌하는지 검사
+ * @param {Object} newDevice - 새 장비 정보
+ * @param {number} newDevice.position - 시작 U 위치
+ * @param {number} newDevice.height - 장비 높이 (U)
+ * @param {Equipments[]} existingDevices - 기존 장비 목록
+ * @param {number} excludeDeviceId - 제외할 장비 ID (자기 자신 제외용)
+ * @returns {boolean} 충돌 여부
+ */
 export function checkCollision(
   newDevice: {
     position: number;
@@ -36,7 +58,15 @@ export function checkCollision(
   });
 }
 
-//충돌하는 장비 찾기
+/**
+ * 충돌하는 장비 찾기
+ * @param {Object} newDevice - 새 장비 정보
+ * @param {number} newDevice.position - 시작 U 위치
+ * @param {number} newDevice.height - 장비 높이 (U)
+ * @param {Equipments[]} existingDevices - 기존 장비 목록
+ * @param {number} excludeDeviceId - 제외할 장비 ID (자기 자신 제외용)
+ * @returns {Equipments | null} 충돌하는 장비 또는 null
+ */
 export function findCollidingDevice(
   newDevice: {
     position: number;
diff --git a/src/domains/serverView/rack/utils/rackLayout.ts b/src/domains/serverView/rack/utils/rackLayout.ts
index 4164d28..a20ac6e 100644
--- a/src/domains/serverView/rack/utils/rackLayout.ts
+++ b/src/domains/serverView/rack/utils/rackLayout.ts
@@ -1,5 +1,20 @@
+/**
+ * @author 구희원
+ * @description 랙 레이아웃 계산 유틸리티
+ */
+
 import { RACK_CONFIG, UNIT_COUNT } from "../constants/rackConstants";
 
+/**
+ * 랙 레이아웃 계산
+ * @param {typeof RACK_CONFIG} config - 랙 설정
+ * @returns {Object} 계산된 랙 레이아웃
+ * @returns {number} rackHeight - 랙 높이
+ * @returns {number} baseY - 랙 시작 Y 좌표
+ * @returns {number} fullWidth - 전체 너비 (프레임 포함)
+ * @returns {number} fullHeight - 전체 높이 (프레임 포함)
+ * @returns {number} rackX - 랙 X 좌표 (중앙 정렬)
+ */
 export function rackLayout(config: typeof RACK_CONFIG) {
   const rackHeight = UNIT_COUNT * config.unitHeight;
   const baseY = config.frameThickness;
diff --git a/src/domains/serverView/serverDashboard/api/updateEquipments.ts b/src/domains/serverView/serverDashboard/api/updateEquipments.ts
index 521de75..4d24580 100644
--- a/src/domains/serverView/serverDashboard/api/updateEquipments.ts
+++ b/src/domains/serverView/serverDashboard/api/updateEquipments.ts
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 장비 상세 정보 수정 API
+ */
+
 import client from "@/api/client";
 import type { UpdateEquipmentRequest } from "../types";
 
+/**
+ * 장비 상세 정보
+ */
 export interface EquipmentDetail {
   id: number;
   equipmentName: string;
@@ -37,12 +45,21 @@ export interface EquipmentDetail {
   diskThresholdCritical: number;
 }
 
+/**
+ * 장비 수정 API 응답
+ */
 export interface UpdateEquipmentResponse {
   status_code: number;
   status_message: string;
   result: EquipmentDetail;
 }
 
+/**
+ * 장비 상세 정보 수정
+ * @param {number} id - 수정할 장비 ID
+ * @param {UpdateEquipmentRequest} data - 수정할 장비 정보
+ * @returns {Promise<UpdateEquipmentResponse>} 수정된 장비 정보
+ */
 export const updateEquipment = async (
   id: number,
   data: UpdateEquipmentRequest
diff --git a/src/domains/serverView/serverDashboard/components/AreaLineChart.tsx b/src/domains/serverView/serverDashboard/components/AreaLineChart.tsx
index 9dadda8..b293ede 100644
--- a/src/domains/serverView/serverDashboard/components/AreaLineChart.tsx
+++ b/src/domains/serverView/serverDashboard/components/AreaLineChart.tsx
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 영역 채움 라인 차트 컴포넌트 (ECharts)
+ */
+
 import ReactECharts from "echarts-for-react";
 import { useEffect, useState } from "react";
 
+/**
+ * 시리즈 데이터
+ */
 interface SeriesData {
   name: string;
   data: number[] | null;
@@ -10,6 +18,9 @@ interface SeriesData {
   lineType?: "solid" | "dashed" | "dotted";
 }
 
+/**
+ * 영역 라인 차트 props
+ */
 interface AreaLineChartProps {
   xAxisData: string[];
   series: SeriesData[];
@@ -18,6 +29,9 @@ interface AreaLineChartProps {
   showToolbox?: boolean;
 }
 
+/**
+ * 툴팁 파라미터
+ */
 interface TooltipParams {
   axisValue: string;
   marker: string;
@@ -26,6 +40,16 @@ interface TooltipParams {
   color: string;
 }
 
+/**
+ * 영역 채움 라인 차트
+ * @param {AreaLineChartProps} props - 차트 속성
+ * @param {string[]} props.xAxisData - X축 데이터
+ * @param {SeriesData[]} props.series - 시리즈 데이터
+ * @param {string} props.yAxisUnit - Y축 단위
+ * @param {string} props.height - 차트 높이
+ * @param {boolean} props.showToolbox - 툴박스 표시 여부
+ * @returns 영역 라인 차트 컴포넌트
+ */
 function AreaLineChart({
   xAxisData,
   series,
diff --git a/src/domains/serverView/serverDashboard/components/BarChart.tsx b/src/domains/serverView/serverDashboard/components/BarChart.tsx
index cf0569a..ee6a96a 100644
--- a/src/domains/serverView/serverDashboard/components/BarChart.tsx
+++ b/src/domains/serverView/serverDashboard/components/BarChart.tsx
@@ -1,12 +1,23 @@
+/**
+ * @author 구희원
+ * @description 막대 차트 컴포넌트 (ECharts)
+ */
+
 import ReactECharts from "echarts-for-react";
 import { useEffect, useState } from "react";
 
+/**
+ * 시리즈 데이터
+ */
 interface SeriesData {
   name: string;
   data: (number | null)[];
   color: string;
 }
 
+/**
+ * 막대 차트 props
+ */
 interface BarChartProps {
   xAxisData: string[];
   series: SeriesData[];
@@ -15,6 +26,9 @@ interface BarChartProps {
   stacked?: boolean;
 }
 
+/**
+ * 툴팁 파라미터
+ */
 interface TooltipParams {
   axisValue: string;
   marker: string;
@@ -22,6 +36,16 @@ interface TooltipParams {
   value: number | string;
 }
 
+/**
+ * 막대 차트
+ * @param {BarChartProps} props - 차트 속성
+ * @param {string[]} props.xAxisData - X축 데이터
+ * @param {SeriesData[]} props.series - 시리즈 데이터
+ * @param {string} props.yAxisUnit - Y축 단위 (기본값: "%")
+ * @param {string} props.height - 차트 높이 (기본값: "100%")
+ * @param {boolean} props.stacked - 스택형 차트 여부 (기본값: true)
+ * @returns 막대 차트 컴포넌트
+ */
 function BarChart({
   xAxisData,
   series,
diff --git a/src/domains/serverView/serverDashboard/components/Button.tsx b/src/domains/serverView/serverDashboard/components/Button.tsx
index 4d4c4a6..3b40f78 100644
--- a/src/domains/serverView/serverDashboard/components/Button.tsx
+++ b/src/domains/serverView/serverDashboard/components/Button.tsx
@@ -1,3 +1,11 @@
+/**
+ * @author 구희원
+ * @description 아이콘 버튼 컴포넌트
+ */
+
+/**
+ * 버튼 props
+ */
 interface ButtonProps {
   onClick: () => void;
   icon: string;
@@ -6,6 +14,16 @@ interface ButtonProps {
   disabled?: boolean;
 }
 
+/**
+ * 아이콘 버튼
+ * @param {ButtonProps} props - 버튼 속성
+ * @param {() => void} props.onClick - 클릭 이벤트 핸들러
+ * @param {string} props.icon - 아이콘 이미지 경로
+ * @param {string} props.title - 버튼 제목 (툴팁)
+ * @param {boolean} props.editMode - 편집 모드 여부
+ * @param {boolean} props.disabled - 비활성화 여부
+ * @returns 아이콘 버튼 컴포넌트
+ */
 function Button({ onClick, icon, title, editMode, disabled }: ButtonProps) {
   return (
     <button
diff --git a/src/domains/serverView/serverDashboard/components/ButtonPlaceholder.tsx b/src/domains/serverView/serverDashboard/components/ButtonPlaceholder.tsx
index fbd67bd..f1429a6 100644
--- a/src/domains/serverView/serverDashboard/components/ButtonPlaceholder.tsx
+++ b/src/domains/serverView/serverDashboard/components/ButtonPlaceholder.tsx
@@ -1,7 +1,15 @@
+/**
+ * @author 구희원
+ * @description 버튼 플레이스홀더 컴포넌트 (초기화, 저장, 편집 토글)
+ */
+
 import ResetIcon from "../assets/reset.svg";
 import CheckIcon from "../assets/check.svg";
 import Button from "./Button";
 
+/**
+ * 버튼 플레이스홀더 props
+ */
 interface ButtonPlaceholderProps {
   editMode: boolean;
   onReset: () => void;
@@ -10,6 +18,16 @@ interface ButtonPlaceholderProps {
   isLoading?: boolean;
 }
 
+/**
+ * 버튼 플레이스홀더
+ * @param {ButtonPlaceholderProps} props - 버튼 플레이스홀더 속성
+ * @param {boolean} props.editMode - 편집 모드 여부
+ * @param {() => void} props.onReset - 초기화 핸들러
+ * @param {() => void} props.onSave - 저장 핸들러
+ * @param {() => void} props.onToggleEdit - 편집 모드 토글 핸들러
+ * @param {boolean} props.isLoading - 로딩 상태
+ * @returns 버튼 플레이스홀더 컴포넌트
+ */
 function ButtonPlaceholder({
   editMode,
   onReset,
diff --git a/src/domains/serverView/serverDashboard/components/ChartCard.tsx b/src/domains/serverView/serverDashboard/components/ChartCard.tsx
index 5c2542b..3840dda 100644
--- a/src/domains/serverView/serverDashboard/components/ChartCard.tsx
+++ b/src/domains/serverView/serverDashboard/components/ChartCard.tsx
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 차트 카드 컨테이너 컴포넌트
+ */
+
 import "../css/chartCard.css";
 import type { ReactNode } from "react";
 
+/**
+ * 차트 카드 props
+ */
 interface ChartCardProps {
   title: string;
   icon?: string;
@@ -8,6 +16,15 @@ interface ChartCardProps {
   children: ReactNode;
 }
 
+/**
+ * 차트 카드
+ * @param {ChartCardProps} props - 차트 카드 속성
+ * @param {string} props.title - 카드 제목
+ * @param {string} props.icon - 아이콘 이미지 경로
+ * @param {"small" | "medium" | "large"} props.size - 카드 크기 (기본값: "medium")
+ * @param {ReactNode} props.children - 차트 내용
+ * @returns 차트 카드 컴포넌트
+ */
 function ChartCard({ title, icon, size = "medium", children }: ChartCardProps) {
   return (
     <div className={`chart-card chart-card-${size}`}>
diff --git a/src/domains/serverView/serverDashboard/components/GaugeChart.tsx b/src/domains/serverView/serverDashboard/components/GaugeChart.tsx
index 9a0a28b..2892f5b 100644
--- a/src/domains/serverView/serverDashboard/components/GaugeChart.tsx
+++ b/src/domains/serverView/serverDashboard/components/GaugeChart.tsx
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 게이지 차트 컴포넌트 (ECharts)
+ */
+
 import { useEffect, useState } from "react";
 import ReactECharts from "echarts-for-react";
 
+/**
+ * 게이지 차트 props
+ */
 interface GaugeChartProps {
   value: number;
   max?: number;
@@ -9,6 +17,16 @@ interface GaugeChartProps {
   unit?: string;
 }
 
+/**
+ * 게이지 차트
+ * @param {GaugeChartProps} props - 차트 속성
+ * @param {number} props.value - 현재 값
+ * @param {number} props.max - 최대값 (기본값: 100)
+ * @param {number} props.min - 최소값 (기본값: 0)
+ * @param {string} props.color - 차트 색상 (기본값: "#58D9F9")
+ * @param {string} props.unit - 단위 (기본값: "%")
+ * @returns 게이지 차트 컴포넌트
+ */
 function GaugeChart({
   value,
   max = 100,
@@ -21,6 +39,7 @@ function GaugeChart({
   useEffect(() => {
     setMounted(true);
   }, []);
+
   const option = {
     series: [
       {
diff --git a/src/domains/serverView/serverDashboard/components/ServerDashboard.tsx b/src/domains/serverView/serverDashboard/components/ServerDashboard.tsx
index c3e2f63..68235f5 100644
--- a/src/domains/serverView/serverDashboard/components/ServerDashboard.tsx
+++ b/src/domains/serverView/serverDashboard/components/ServerDashboard.tsx
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 서버 모니터링 대시보드 컴포넌트
+ */
+
 import { useMemo } from "react";
 import "../css/serverDashboard.css";
 import ServerDashboardHeader from "./ServerDashboardHeader";
@@ -16,6 +21,9 @@ import { buildChartData, type HistoryRecord } from "../utils/chartDataBuilder";
 import { DEFAULT_THRESHOLD_VALUES } from "../constants";
 import type { Equipments } from "../../rack/types";
 
+/**
+ * 서버 대시보드 props
+ */
 interface ServerDashboardProps {
   deviceId: number;
   deviceName: string;
@@ -26,12 +34,27 @@ interface ServerDashboardProps {
   currentEquipment?: Equipments;
 }
 
+/**
+ * 임계값 설정
+ */
 interface ThresholdValues {
   cpu: { warning: number; critical: number };
   memory: { warning: number; critical: number };
   disk: { warning: number; critical: number };
 }
 
+/**
+ * 서버 모니터링 대시보드
+ * @param {ServerDashboardProps} props - 대시보드 속성
+ * @param {number} props.deviceId - 장비 ID
+ * @param {string} props.deviceName - 장비 이름
+ * @param {() => void} props.onClose - 닫기 핸들러
+ * @param {boolean} props.isOpen - 대시보드 열림 상태
+ * @param {number} props.rackId - 랙 ID
+ * @param {number} props.serverRoomId - 서버룸 ID
+ * @param {Equipments} props.currentEquipment - 현재 장비 정보
+ * @returns 서버 대시보드 컴포넌트
+ */
 function ServerDashboard({
   deviceName,
   isOpen,
@@ -46,7 +69,9 @@ function ServerDashboard({
   const { systemData, diskData, systemHistory, diskHistory, networkHistory } =
     useMonitoringStore();
 
-  // 임계값 초기화
+  /**
+   * 임계값 초기화
+   */
   const initialThresholds = useMemo<ThresholdValues>(() => {
     if (!currentEquipment) {
       return DEFAULT_THRESHOLD_VALUES;
@@ -68,7 +93,9 @@ function ServerDashboard({
     };
   }, [currentEquipment]);
 
-  // 임계값 저장
+  /**
+   * 임계값 저장 핸들러
+   */
   const handleSaveThresholds = (values: ThresholdValues) => {
     if (!currentEquipment) {
       console.error("장비 정보를 찾을 수 없습니다.");
@@ -105,6 +132,9 @@ function ServerDashboard({
     );
   };
 
+  /**
+   * 차트 데이터 생성
+   */
   const chartData = useMemo(() => {
     return buildChartData({
       systemData,
@@ -143,6 +173,7 @@ function ServerDashboard({
 
       <div className="dashboard-content scrollbar-none">
         <div className="chart-grid">
+          {/* CPU, Memory, Disk 게이지 */}
           <div className="chart-row-small">
             <ChartCard title="CPU 사용률" icon={CpuIcon} size="small">
               <GaugeChart
@@ -172,6 +203,7 @@ function ServerDashboard({
             </ChartCard>
           </div>
 
+          {/* CPU 모드 분포 & 시스템 부하 */}
           <div className="chart-row-medium">
             <ChartCard title="CPU 사용 모드별 분포" size="medium">
               <BarChart
@@ -190,6 +222,7 @@ function ServerDashboard({
             </ChartCard>
           </div>
 
+          {/* 메모리 & 스왑 */}
           <div className="chart-row-large">
             <ChartCard title="메모리 & 스왑 사용률" size="large">
               <SmoothLineChart
@@ -200,6 +233,7 @@ function ServerDashboard({
             </ChartCard>
           </div>
 
+          {/* 네트워크 & CPU Wait */}
           <div className="chart-row-medium">
             <ChartCard title="네트워크 대역폭" size="medium">
               <AreaLineChart
@@ -218,6 +252,7 @@ function ServerDashboard({
             </ChartCard>
           </div>
 
+          {/* 디스크 I/O & Inode */}
           <div className="chart-row-medium">
             <ChartCard title="디스크 읽기/쓰기 속도" size="medium">
               <AreaLineChart
diff --git a/src/domains/serverView/serverDashboard/components/ServerDashboardHeader.tsx b/src/domains/serverView/serverDashboard/components/ServerDashboardHeader.tsx
index 47d0fca..cb8416f 100644
--- a/src/domains/serverView/serverDashboard/components/ServerDashboardHeader.tsx
+++ b/src/domains/serverView/serverDashboard/components/ServerDashboardHeader.tsx
@@ -1,9 +1,25 @@
+/**
+ * @author 구희원
+ * @description 서버 대시보드 헤더 컴포넌트
+ */
+
 import DoubleArrow from "../assets/doubleArrow.svg";
 
+/**
+ * 서버 대시보드 헤더 props
+ */
 interface ServerDashboardHeaderProps {
   deviceName: string;
   onClose: () => void;
 }
+
+/**
+ * 서버 대시보드 헤더
+ * @param {ServerDashboardHeaderProps} props - 헤더 속성
+ * @param {string} props.deviceName - 장비 이름
+ * @param {() => void} props.onClose - 닫기 핸들러
+ * @returns 대시보드 헤더 컴포넌트
+ */
 function ServerDashboardHeader({
   deviceName,
   onClose,
diff --git a/src/domains/serverView/serverDashboard/components/SmoothLineChart.tsx b/src/domains/serverView/serverDashboard/components/SmoothLineChart.tsx
index 34f2e28..9841c0c 100644
--- a/src/domains/serverView/serverDashboard/components/SmoothLineChart.tsx
+++ b/src/domains/serverView/serverDashboard/components/SmoothLineChart.tsx
@@ -1,6 +1,14 @@
+/**
+ * @author 구희원
+ * @description 부드러운 라인 차트 컴포넌트 (ECharts)
+ */
+
 import { useEffect, useState } from "react";
 import ReactECharts from "echarts-for-react";
 
+/**
+ * 시리즈 데이터
+ */
 interface SeriesData {
   name: string;
   data: (number | null)[];
@@ -11,6 +19,9 @@ interface SeriesData {
   lineType?: "solid" | "dashed" | "dotted";
 }
 
+/**
+ * 부드러운 라인 차트 props
+ */
 interface SmoothLineChartProps {
   xAxisData: string[];
   series: SeriesData[];
@@ -18,6 +29,9 @@ interface SmoothLineChartProps {
   height?: string;
 }
 
+/**
+ * 툴팁 파라미터
+ */
 interface TooltipParams {
   axisValue: string;
   marker: string;
@@ -25,6 +39,15 @@ interface TooltipParams {
   value: number | string;
 }
 
+/**
+ * 부드러운 라인 차트
+ * @param {SmoothLineChartProps} props - 차트 속성
+ * @param {string[]} props.xAxisData - X축 데이터
+ * @param {SeriesData[]} props.series - 시리즈 데이터
+ * @param {string} props.yAxisUnit - Y축 단위
+ * @param {string} props.height - 차트 높이 (기본값: "100%")
+ * @returns 부드러운 라인 차트 컴포넌트
+ */
 function SmoothLineChart({
   xAxisData,
   series,
diff --git a/src/domains/serverView/serverDashboard/components/ThresholdHeader.tsx b/src/domains/serverView/serverDashboard/components/ThresholdHeader.tsx
index ad4e674..81eb4e7 100644
--- a/src/domains/serverView/serverDashboard/components/ThresholdHeader.tsx
+++ b/src/domains/serverView/serverDashboard/components/ThresholdHeader.tsx
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 임계치 설정 헤더 컴포넌트
+ */
+
 import { useState, useEffect } from "react";
 import CpuIcon from "../assets/cpu.svg";
 import MemoryIcon from "../assets/memory.svg";
@@ -5,12 +10,18 @@ import DiskIcon from "../assets/disk.svg";
 import ThresholdMetricInput from "./ThresholdmetricInput";
 import ButtonPlaceholder from "./ButtonPlaceholder";
 
+/**
+ * 임계치 값
+ */
 export interface ThresholdValues {
   cpu: { warning: number; critical: number };
   memory: { warning: number; critical: number };
   disk: { warning: number; critical: number };
 }
 
+/**
+ * 임계치 헤더 props
+ */
 interface ThresholdHeaderProps {
   initialValues?: ThresholdValues;
   onSave?: (values: ThresholdValues) => void;
@@ -18,6 +29,15 @@ interface ThresholdHeaderProps {
   isLoading?: boolean;
 }
 
+/**
+ * 임계치 설정 헤더
+ * @param {ThresholdHeaderProps} props - 헤더 속성
+ * @param {ThresholdValues} props.initialValues - 초기 임계치 값
+ * @param {(values: ThresholdValues) => void} props.onSave - 저장 핸들러
+ * @param {boolean} props.isOpen - 대시보드 열림 상태
+ * @param {boolean} props.isLoading - 저장 중 로딩 상태
+ * @returns 임계치 설정 헤더 컴포넌트
+ */
 function ThresholdHeader({
   initialValues = {
     cpu: { warning: 70, critical: 90 },
@@ -31,12 +51,16 @@ function ThresholdHeader({
   const [editMode, setEditMode] = useState(false);
   const [values, setValues] = useState<ThresholdValues>(initialValues);
 
+  // 대시보드가 닫히면 편집 모드 해제
   useEffect(() => {
     if (!isOpen) {
       setEditMode(false);
     }
   }, [isOpen]);
 
+  /**
+   * 임계치 값 변경 핸들러
+   */
   const handleValueChange = (
     metric: keyof ThresholdValues,
     type: "warning" | "critical",
@@ -54,6 +78,9 @@ function ThresholdHeader({
     });
   };
 
+  /**
+   * 저장 핸들러
+   */
   const handleSave = () => {
     onSave?.(values);
     if (!isLoading) {
@@ -61,11 +88,17 @@ function ThresholdHeader({
     }
   };
 
+  /**
+   * 초기화 핸들러
+   */
   const handleReset = () => {
     setValues(initialValues);
     setEditMode(false);
   };
 
+  /**
+   * 편집 모드 토글 핸들러
+   */
   const handleToggleEdit = () => {
     if (editMode) {
       setValues(initialValues);
@@ -76,12 +109,12 @@ function ThresholdHeader({
   return (
     <div className="bg-white/5 border border-slate-300/40 rounded-xl p-4">
       <div className="flex items-center gap-7">
-        {/* Left: Title */}
+        {/* 제목 */}
         <div className="flex items-center gap-3 flex-shrink-0">
           <span className="text-white text-sm font-semibold">임계치 설정</span>
         </div>
 
-        {/* Center: Metrics */}
+        {/* 메트릭 입력 필드 */}
         <div className="flex items-center gap-3 flex-1">
           {/* CPU */}
           <ThresholdMetricInput
@@ -129,7 +162,7 @@ function ThresholdHeader({
           />
         </div>
 
-        {/* Right: Actions */}
+        {/* 액션 버튼 */}
         <div className="flex items-center gap-3">
           <ButtonPlaceholder
             editMode={editMode}
diff --git a/src/domains/serverView/serverDashboard/components/ThresholdmetricInput.tsx b/src/domains/serverView/serverDashboard/components/ThresholdmetricInput.tsx
index 52540f2..81d1b56 100644
--- a/src/domains/serverView/serverDashboard/components/ThresholdmetricInput.tsx
+++ b/src/domains/serverView/serverDashboard/components/ThresholdmetricInput.tsx
@@ -1,5 +1,13 @@
+/**
+ * @author 구희원
+ * @description 임계치 메트릭 입력 컴포넌트
+ */
+
 import { useState, useEffect } from "react";
 
+/**
+ * 임계치 메트릭 props
+ */
 interface ThresholdMetricProps {
   label: string;
   icon: string;
@@ -10,6 +18,18 @@ interface ThresholdMetricProps {
   onCriticalChange: (value: number) => void;
 }
 
+/**
+ * 임계치 메트릭 입력
+ * @param {ThresholdMetricProps} props - 메트릭 속성
+ * @param {string} props.label - 메트릭 라벨 (CPU, MEM, DISK)
+ * @param {string} props.icon - 아이콘 이미지 경로
+ * @param {number} props.warningValue - 경고 임계값
+ * @param {number} props.criticalValue - 위험 임계값
+ * @param {boolean} props.editMode - 편집 모드 여부
+ * @param {(value: number) => void} props.onWarningChange - 경고 임계값 변경 핸들러
+ * @param {(value: number) => void} props.onCriticalChange - 위험 임계값 변경 핸들러
+ * @returns 임계치 메트릭 입력 컴포넌트
+ */
 function ThresholdMetricInput({
   label,
   icon,
@@ -29,6 +49,7 @@ function ThresholdMetricInput({
   const [warningChanged, setWarningChanged] = useState(false);
   const [criticalChanged, setCriticalChanged] = useState(false);
 
+  // 경고 임계값 초기화
   useEffect(() => {
     if (!editingWarning) {
       setTempWarning(warningValue);
@@ -36,6 +57,7 @@ function ThresholdMetricInput({
     }
   }, [warningValue, editingWarning, label, tempWarning, warningChanged]);
 
+  // 위험 임계값 초기화
   useEffect(() => {
     if (!editingCritical) {
       setTempCritical(criticalValue);
@@ -43,20 +65,29 @@ function ThresholdMetricInput({
     }
   }, [criticalValue, editingCritical]);
 
+  /**
+   * 경고 임계값 클릭 핸들러
+   */
   const handleWarningClick = () => {
     if (!editMode) return;
     setEditingWarning(true);
     setTempWarning(warningValue);
-    setWarningChanged(false); // 클릭 시 리셋
+    setWarningChanged(false);
   };
 
+  /**
+   * 위험 임계값 클릭 핸들러
+   */
   const handleCriticalClick = () => {
     if (!editMode) return;
     setEditingCritical(true);
     setTempCritical(criticalValue);
-    setCriticalChanged(false); // 클릭 시 리셋
+    setCriticalChanged(false);
   };
 
+  /**
+   * 경고 임계값 저장
+   */
   const saveWarning = () => {
     if (!warningChanged) {
       setEditingWarning(false);
@@ -68,6 +99,7 @@ function ThresholdMetricInput({
         ? 0
         : Math.max(0, Math.min(100, tempWarning));
 
+    // 경고값이 위험값보다 클 수 없음
     if (criticalValue > 0 && value > criticalValue) {
       value = criticalValue;
     }
@@ -77,6 +109,9 @@ function ThresholdMetricInput({
     setWarningChanged(false);
   };
 
+  /**
+   * 위험 임계값 저장
+   */
   const saveCritical = () => {
     if (!criticalChanged) {
       setEditingCritical(false);
@@ -88,6 +123,7 @@ function ThresholdMetricInput({
         ? 0
         : Math.max(0, Math.min(100, tempCritical));
 
+    // 위험값이 경고값보다 작을 수 없음
     if (warningValue > 0 && value < warningValue) {
       value = warningValue;
     }
@@ -97,6 +133,9 @@ function ThresholdMetricInput({
     setCriticalChanged(false);
   };
 
+  /**
+   * 경고 임계값 입력 변경 핸들러
+   */
   const handleWarningChange = (val: string) => {
     setWarningChanged(true);
     if (val === "") {
@@ -109,6 +148,9 @@ function ThresholdMetricInput({
     }
   };
 
+  /**
+   * 위험 임계값 입력 변경 핸들러
+   */
   const handleCriticalChange = (val: string) => {
     setCriticalChanged(true);
     if (val === "") {
@@ -121,6 +163,9 @@ function ThresholdMetricInput({
     }
   };
 
+  /**
+   * 경고 임계값 키보드 이벤트 핸들러
+   */
   const handleWarningKeyDown = (e: React.KeyboardEvent) => {
     if (e.key === "Enter") {
       saveWarning();
@@ -130,6 +175,9 @@ function ThresholdMetricInput({
     }
   };
 
+  /**
+   * 위험 임계값 키보드 이벤트 핸들러
+   */
   const handleCriticalKeyDown = (e: React.KeyboardEvent) => {
     if (e.key === "Enter") {
       saveCritical();
@@ -147,7 +195,7 @@ function ThresholdMetricInput({
           : "border-slate-300/40 hover:border-white/30"
       }`}
     >
-      {/* Icon */}
+      {/* 아이콘 */}
       <div className={`w-5 h-5 rounded flex items-center justify-center`}>
         {typeof icon === "string" ? (
           <img src={icon} alt={label} className="w-3.5 h-3.5" />
@@ -156,12 +204,12 @@ function ThresholdMetricInput({
         )}
       </div>
 
-      {/* Label */}
+      {/* 라벨 */}
       <span className="text-white text-xs font-medium min-w-[2.5rem]">
         {label}
       </span>
 
-      {/* Warning Value */}
+      {/* 경고 임계값 */}
       <div className="flex items-center gap-1">
         {editingWarning ? (
           <input
@@ -195,10 +243,10 @@ function ThresholdMetricInput({
         )}
       </div>
 
-      {/* Separator */}
+      {/* 구분자 */}
       <span className="text-white text-sm">/</span>
 
-      {/* Critical Value */}
+      {/* 위험 임계값 */}
       <div className="flex items-center gap-1">
         {editingCritical ? (
           <input
@@ -230,7 +278,7 @@ function ThresholdMetricInput({
         )}
       </div>
 
-      {/* Unit */}
+      {/* 단위 */}
       <span className="text-white text-xs">%</span>
     </div>
   );
diff --git a/src/domains/serverView/serverDashboard/constants/index.ts b/src/domains/serverView/serverDashboard/constants/index.ts
index 0c502fa..7c25094 100644
--- a/src/domains/serverView/serverDashboard/constants/index.ts
+++ b/src/domains/serverView/serverDashboard/constants/index.ts
@@ -1,3 +1,13 @@
+/**
+ * @author 구희원
+ * @description 서버 대시보드 차트 설정 상수
+ */
+
+/**
+ * 차트 설정
+ * @property {number} MAX_POINTS - 차트에 표시할 최대 데이터 포인트 수
+ * @property {Object} COLORS - 차트 색상 맵
+ */
 export const CHART_CONFIG = {
   MAX_POINTS: 12,
   COLORS: {
@@ -16,7 +26,12 @@ export const CHART_CONFIG = {
   },
 } as const;
 
-// 임계값 기본값
+/**
+ * 임계값 기본값
+ * @property {Object} cpu - CPU 임계값 (warning: 경고, critical: 위험)
+ * @property {Object} memory - 메모리 임계값
+ * @property {Object} disk - 디스크 임계값
+ */
 export const DEFAULT_THRESHOLD_VALUES = {
   cpu: { warning: 0, critical: 0 },
   memory: { warning: 0, critical: 0 },
diff --git a/src/domains/serverView/serverDashboard/css/chartCard.css b/src/domains/serverView/serverDashboard/css/chartCard.css
index a86e84b..396f246 100644
--- a/src/domains/serverView/serverDashboard/css/chartCard.css
+++ b/src/domains/serverView/serverDashboard/css/chartCard.css
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 차트 카드 스타일시트
+ */
+
 @import "tailwindcss";
 
 /* 기본 차트 카드 */
@@ -5,29 +10,34 @@
   @apply bg-white/5 border border-slate-300/40 rounded-lg flex flex-col;
 }
 
-/* 크기별 스타일 */
+/* 차트 카드 크기별 스타일 */
+
+/* Small 사이즈 */
 .chart-card-small {
   @apply flex-1;
 }
 
-/* small 사이즈의 컨텐츠 margin 제거 */
-.chart-header-with-icon {
-  @apply flex items-center gap-2 px-3 pt-3;
-}
-
+/* Small 사이즈의 컨텐츠 margin 제거 */
 .chart-card-small .chart-content {
   @apply mx-0 mb-0;
 }
 
+/* Medium 사이즈 */
 .chart-card-medium {
   @apply flex-1;
 }
 
+/* Large 사이즈 */
 .chart-card-large {
   @apply flex-1;
 }
 
-/* 차트 헤더 */
+/* 차트 헤더 - 아이콘 포함 */
+.chart-header-with-icon {
+  @apply flex items-center gap-2 px-3 pt-3;
+}
+
+/* 차트 헤더 - 기본 */
 .chart-header {
   @apply flex items-center m-3;
 }
diff --git a/src/domains/serverView/serverDashboard/css/serverDashboard.css b/src/domains/serverView/serverDashboard/css/serverDashboard.css
index d6e04a5..2946e1c 100644
--- a/src/domains/serverView/serverDashboard/css/serverDashboard.css
+++ b/src/domains/serverView/serverDashboard/css/serverDashboard.css
@@ -1,5 +1,11 @@
+/**
+ * @author 구희원
+ * @description 서버 대시보드 스타일시트
+ */
+
 @import "tailwindcss";
 
+/* 스크롤바 숨김 유틸리티 */
 @layer utilities {
   .scrollbar-none {
     scrollbar-width: none;
@@ -7,7 +13,7 @@
   }
 }
 
-/* 의사 요소는 밖에서 */
+/* 웹킷 브라우저 스크롤바 숨김 */
 .scrollbar-none::-webkit-scrollbar {
   display: none;
 }
@@ -19,18 +25,19 @@
   @apply transition-transform duration-300 ease-out px-4 py-3;
 }
 
+/* 대시보드 열림 상태 */
 .dashboard-container.open {
   @apply translate-x-0;
 }
 
+/* 대시보드 닫힘 상태 */
 .dashboard-container.closed {
   @apply translate-x-full;
 }
 
-/* 컨텐츠 영역 */
+/* 대시보드 컨텐츠 영역 */
 .dashboard-content {
   @apply flex-1 overflow-y-auto mt-3;
-  /* scrollbar-none 제거됨 */
 }
 
 /* 차트 그리드 컨테이너 */
@@ -38,17 +45,19 @@
   @apply flex flex-col gap-3;
 }
 
-/* 차트 행 (3개 열 - small) */
+/* 차트 행 레이아웃 */
+
+/* Small 사이즈 행 (3개 열) */
 .chart-row-small {
   @apply flex gap-3 h-70;
 }
 
-/* 차트 행 (2개 열 - medium) */
+/* Medium 사이즈 행 (2개 열) */
 .chart-row-medium {
   @apply flex gap-3 h-80;
 }
 
-/* 차트 행 (1개 열 - large) */
+/* Large 사이즈 행 (1개 열) */
 .chart-row-large {
   @apply flex gap-3 h-96;
 }
diff --git a/src/domains/serverView/serverDashboard/hooks/useAllEquipmentBackgroundSSE.ts b/src/domains/serverView/serverDashboard/hooks/useAllEquipmentBackgroundSSE.ts
index b32adc3..8eb0dd6 100644
--- a/src/domains/serverView/serverDashboard/hooks/useAllEquipmentBackgroundSSE.ts
+++ b/src/domains/serverView/serverDashboard/hooks/useAllEquipmentBackgroundSSE.ts
@@ -1,33 +1,56 @@
+/**
+ * @author 구희원
+ * @description 모든 장비의 백그라운드 SSE 연결 훅
+ */
+
 import { useEffect, useRef } from "react";
 import { EventSourcePolyfill } from "event-source-polyfill";
 import { getAccessToken, BASE_URL } from "@/api/client";
 import type { DiskMonitoringData, SystemMonitoringData } from "../types";
 
+/**
+ * SSE 이벤트
+ */
 interface SSEEvent extends Event {
   data: string;
 }
 
+/**
+ * 간단한 메트릭 정보
+ */
 export interface SimpleMetrics {
   cpu: number;
   memory: number;
   disk: number;
 }
 
+/**
+ * 백그라운드 SSE 콜백
+ */
 interface BackgroundSSECallbacks {
   onMetricsUpdate: (equipmentId: number, metrics: SimpleMetrics) => void;
   onConnectionError?: (equipmentId: number, error: Event) => void;
 }
 
+/**
+ * System 모니터링 데이터 타입 가드
+ */
 const isSystemMonitoringData = (
   data: unknown
 ): data is SystemMonitoringData => {
   return typeof data === "object" && data !== null && "cpuIdle" in data;
 };
 
+/**
+ * Disk 모니터링 데이터 타입 가드
+ */
 const isDiskMonitoringData = (data: unknown): data is DiskMonitoringData => {
   return typeof data === "object" && data !== null && "usedPercentage" in data;
 };
 
+/**
+ * System 및 Disk 데이터에서 메트릭 추출
+ */
 const extractMetricsFromSystemData = (
   systemData: SystemMonitoringData | null,
   diskData: DiskMonitoringData | null
@@ -45,6 +68,15 @@ const extractMetricsFromSystemData = (
   };
 };
 
+/**
+ * 모든 장비의 백그라운드 SSE 연결 훅
+ *
+ * 여러 장비의 실시간 모니터링 데이터를 동시에 수신하여 메트릭을 업데이트합니다.
+ * 연결 실패 시 지수 백오프 전략으로 재연결을 시도합니다.
+ *
+ * @param {number[]} equipmentIds - 모니터링할 장비 ID 목록
+ * @param {BackgroundSSECallbacks} callbacks - SSE 이벤트 콜백
+ */
 export const useAllEquipmentBackgroundSSE = (
   equipmentIds: number[],
   callbacks: BackgroundSSECallbacks
@@ -67,6 +99,9 @@ export const useAllEquipmentBackgroundSSE = (
 
     const eventSourceMap = new Map<number, EventSource>();
 
+    /**
+     * 특정 장비에 SSE 연결
+     */
     const connectToEquipment = (equipmentId: number) => {
       try {
         const url = `${BASE_URL}/monitoring/subscribe/equipment/${equipmentId}`;
@@ -133,6 +168,7 @@ export const useAllEquipmentBackgroundSSE = (
           }
         });
 
+        // 에러 처리 및 재연결
         eventSource.onerror = (error: Event) => {
           console.error(
             `[Equipment ${equipmentId}] SSE connection error:`,
diff --git a/src/domains/serverView/serverDashboard/hooks/useEquipmentSSE.ts b/src/domains/serverView/serverDashboard/hooks/useEquipmentSSE.ts
index 73d39da..68ce183 100644
--- a/src/domains/serverView/serverDashboard/hooks/useEquipmentSSE.ts
+++ b/src/domains/serverView/serverDashboard/hooks/useEquipmentSSE.ts
@@ -1,4 +1,8 @@
-// useEquipmentSSE.ts - 타입 수정
+/**
+ * @author 구희원
+ * @description 단일 장비 SSE 연결 훅
+ */
+
 import { useEffect, useRef } from "react";
 import { EventSourcePolyfill } from "event-source-polyfill";
 import { getAccessToken, BASE_URL } from "@/api/client";
@@ -8,6 +12,9 @@ import type {
   SystemMonitoringData,
 } from "../types";
 
+/**
+ * SSE 콜백
+ */
 interface SSECallbacks {
   onSystemData?: (data: SystemMonitoringData) => void;
   onDiskData?: (data: DiskMonitoringData) => void;
@@ -15,142 +22,97 @@ interface SSECallbacks {
   onError?: (error: Event) => void;
 }
 
+/**
+ * 단일 장비 SSE 연결 훅
+ *
+ * 선택된 장비의 실시간 모니터링 데이터(System, Disk, Network)를 수신합니다.
+ * 대시보드가 열려있고 장비가 선택된 경우에만 연결됩니다.
+ *
+ * @param {number | null} equipmentId - 모니터링할 장비 ID
+ * @param {SSECallbacks} callbacks - SSE 이벤트 콜백
+ * @param {boolean} enabled - SSE 연결 활성화 여부 (기본값: true)
+ */
 export const useEquipmentSSE = (
   equipmentId: number | null,
   callbacks: SSECallbacks,
   enabled: boolean = true
 ) => {
   const callbacksRef = useRef(callbacks);
-  const reconnectAttemptsRef = useRef(0);
-  const MAX_RECONNECT_ATTEMPTS = 5;
-  const RECONNECT_DELAY = 3000;
 
   useEffect(() => {
     callbacksRef.current = callbacks;
   }, [callbacks]);
 
   useEffect(() => {
-    if (!enabled || !equipmentId) {
-      reconnectAttemptsRef.current = 0;
-      return;
-    }
+    if (!enabled || !equipmentId) return;
 
     const token = getAccessToken();
     if (!token) return;
 
     const url = `${BASE_URL}/monitoring/subscribe/equipment/${equipmentId}`;
-    let eventSource: EventSource | null = null;
-    let reconnectTimeout: number | null = null; // 🔥 여기 수정
-
-    const connect = () => {
-      try {
-        console.log(
-          `[Equipment ${equipmentId}] Establishing SSE connection...`
-        );
-
-        eventSource = new EventSourcePolyfill(url, {
-          headers: {
-            Authorization: `Bearer ${token}`,
-          },
-          withCredentials: true,
-          heartbeatTimeout: 120000,
-        }) as EventSource;
-
-        eventSource.addEventListener("system", (event) => {
-          try {
-            const data: SystemMonitoringData = JSON.parse(event.data);
-            reconnectAttemptsRef.current = 0;
-            callbacksRef.current.onSystemData?.(data);
-          } catch (error) {
-            console.error(
-              `[Equipment ${equipmentId}] System data parse error:`,
-              error
-            );
-          }
-        });
-
-        eventSource.addEventListener("disk", (event) => {
-          try {
-            const data: DiskMonitoringData = JSON.parse(event.data);
-            callbacksRef.current.onDiskData?.(data);
-          } catch (error) {
-            console.error(
-              `[Equipment ${equipmentId}] Disk data parse error:`,
-              error
-            );
-          }
-        });
-
-        eventSource.addEventListener("network", (event) => {
-          try {
-            const data: NetworkMonitoringData[] = JSON.parse(event.data);
-            callbacksRef.current.onNetworkData?.(data);
-          } catch (error) {
-            console.error(
-              `[Equipment ${equipmentId}] Network data parse error:`,
-              error
-            );
-          }
-        });
-
-        eventSource.onerror = (error) => {
-          console.error(`[Equipment ${equipmentId}] SSE Error:`, error);
-
-          if (eventSource) {
-            eventSource.close();
-            eventSource = null;
-          }
-
-          callbacksRef.current.onError?.(error);
 
-          if (reconnectAttemptsRef.current < MAX_RECONNECT_ATTEMPTS) {
-            reconnectAttemptsRef.current++;
-            const delay =
-              RECONNECT_DELAY * Math.pow(2, reconnectAttemptsRef.current - 1);
-
-            console.log(
-              `[Equipment ${equipmentId}] Reconnecting in ${delay}ms... (attempt ${reconnectAttemptsRef.current}/${MAX_RECONNECT_ATTEMPTS})`
-            );
-
-            reconnectTimeout = window.setTimeout(() => {
-              // 🔥 window.setTimeout으로 명시
-              if (enabled) {
-                connect();
-              }
-            }, delay);
-          } else {
-            console.error(
-              `[Equipment ${equipmentId}] Max reconnection attempts reached`
-            );
-          }
-        };
-
-        eventSource.onopen = () => {
-          console.log(`[Equipment ${equipmentId}] SSE connection established`);
-          reconnectAttemptsRef.current = 0;
-        };
-      } catch (error) {
-        console.error(
-          `[Equipment ${equipmentId}] Failed to create SSE connection:`,
-          error
-        );
-      }
-    };
-
-    connect();
-
-    return () => {
-      console.log(`[Equipment ${equipmentId}] Closing SSE connection`);
-
-      if (reconnectTimeout !== null) {
-        window.clearTimeout(reconnectTimeout); // 🔥 window.clearTimeout으로 명시
-      }
-
-      if (eventSource) {
+    try {
+      const eventSource = new EventSourcePolyfill(url, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+        withCredentials: true,
+      });
+
+      // System 데이터 수신
+      eventSource.addEventListener("system", (event) => {
+        try {
+          const data: SystemMonitoringData = JSON.parse(event.data);
+          callbacksRef.current.onSystemData?.(data);
+        } catch (error) {
+          console.error(
+            `[Equipment ${equipmentId}] System data parse error:`,
+            error
+          );
+        }
+      });
+
+      // Disk 데이터 수신
+      eventSource.addEventListener("disk", (event) => {
+        try {
+          const data: DiskMonitoringData = JSON.parse(event.data);
+          callbacksRef.current.onDiskData?.(data);
+        } catch (error) {
+          console.error(
+            `[Equipment ${equipmentId}] Disk data parse error:`,
+            error
+          );
+        }
+      });
+
+      // Network 데이터 수신
+      eventSource.addEventListener("network", (event) => {
+        try {
+          const data: NetworkMonitoringData[] = JSON.parse(event.data);
+          callbacksRef.current.onNetworkData?.(data);
+        } catch (error) {
+          console.error(
+            `[Equipment ${equipmentId}] Network data parse error:`,
+            error
+          );
+        }
+      });
+
+      // 에러 처리
+      eventSource.onerror = (error) => {
+        console.error(`[Equipment ${equipmentId}] SSE Error:`, error);
         eventSource.close();
-      }
+      };
 
-      reconnectAttemptsRef.current = 0;
-    };
+      // Cleanup
+      return () => {
+        eventSource.close();
+      };
+    } catch (error) {
+      console.error(
+        `[Equipment ${equipmentId}] Failed to create SSE connection:`,
+        error
+      );
+    }
   }, [equipmentId, enabled]);
 };
diff --git a/src/domains/serverView/serverDashboard/hooks/useUpdateEquipment.ts b/src/domains/serverView/serverDashboard/hooks/useUpdateEquipment.ts
index d47a268..09f8ecf 100644
--- a/src/domains/serverView/serverDashboard/hooks/useUpdateEquipment.ts
+++ b/src/domains/serverView/serverDashboard/hooks/useUpdateEquipment.ts
@@ -1,12 +1,28 @@
+/**
+ * @author 구희원
+ * @description 장비 정보 수정 훅
+ */
+
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { updateEquipment } from "../api/updateEquipments";
 import type { UpdateEquipmentRequest } from "../types";
 
+/**
+ * 장비 수정 파라미터
+ */
 interface UpdateEquipmentParams {
   id: number;
   data: UpdateEquipmentRequest;
 }
 
+/**
+ * 장비 정보 수정 훅
+ *
+ * 장비의 상세 정보 및 임계값을 수정합니다.
+ * 수정 성공 시 관련 쿼리를 무효화하여 최신 데이터를 반영합니다.
+ *
+ * @returns {UseMutationResult} 장비 수정 mutation
+ */
 export const useUpdateEquipment = () => {
   const queryClient = useQueryClient();
 
@@ -14,10 +30,12 @@ export const useUpdateEquipment = () => {
     mutationFn: ({ id, data }: UpdateEquipmentParams) =>
       updateEquipment(id, data),
     onSuccess: (response, variables) => {
+      // 장비 상세 정보 쿼리 무효화
       queryClient.invalidateQueries({
         queryKey: ["equipment", variables.id],
       });
 
+      // 랙 장비 목록 쿼리 무효화
       queryClient.invalidateQueries({
         queryKey: ["rackEquipments", variables.data.rackId],
       });
diff --git a/src/domains/serverView/serverDashboard/stores/monitoringStore.ts b/src/domains/serverView/serverDashboard/stores/monitoringStore.ts
index 541d20e..e23c4cb 100644
--- a/src/domains/serverView/serverDashboard/stores/monitoringStore.ts
+++ b/src/domains/serverView/serverDashboard/stores/monitoringStore.ts
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 모니터링 데이터 전역 상태 관리 스토어
+ */
+
 import { create } from "zustand";
 import type {
   SystemMonitoringData,
@@ -5,19 +10,27 @@ import type {
   NetworkMonitoringData,
 } from "../types";
 
+/**
+ * 간단한 메트릭 정보
+ */
 export interface SimpleMetrics {
   cpu: number;
   memory: number;
   disk: number;
 }
 
-// 장비별 히스토리 저장 구조
+/**
+ * 장비별 히스토리 저장 구조
+ */
 interface DeviceHistory {
   systemHistory: SystemMonitoringData[];
   diskHistory: DiskMonitoringData[];
   networkHistory: NetworkMonitoringData[][];
 }
 
+/**
+ * 모니터링 상태
+ */
 interface MonitoringState {
   // 현재 선택된 장비
   selectedDeviceId: number | null;
@@ -49,8 +62,18 @@ interface MonitoringState {
   clearHistory: () => void;
 }
 
+/**
+ * 최대 히스토리 길이 (120개 데이터 포인트)
+ */
 const MAX_HISTORY_LENGTH = 120;
 
+/**
+ * 모니터링 데이터 전역 상태 관리 스토어
+ *
+ * - 선택된 장비의 실시간 모니터링 데이터 및 히스토리 관리
+ * - 모든 장비의 최신 메트릭 관리 (임계치 표시용)
+ * - 장비별 히스토리 캐싱으로 장비 전환 시 데이터 유지
+ */
 export const useMonitoringStore = create<MonitoringState>((set, get) => ({
   selectedDeviceId: null,
   systemData: null,
@@ -62,6 +85,9 @@ export const useMonitoringStore = create<MonitoringState>((set, get) => ({
   deviceMetricsMap: new Map(),
   deviceHistoryMap: new Map(),
 
+  /**
+   * 선택된 장비 ID 설정
+   */
   setSelectedDeviceId: (deviceId: number | null) => {
     set({ selectedDeviceId: deviceId });
 
@@ -79,6 +105,9 @@ export const useMonitoringStore = create<MonitoringState>((set, get) => ({
     }
   },
 
+  /**
+   * System 데이터 설정 및 히스토리 업데이트
+   */
   setSystemData: (data) =>
     set((state) => {
       const selectedDeviceId = state.selectedDeviceId;
@@ -107,6 +136,9 @@ export const useMonitoringStore = create<MonitoringState>((set, get) => ({
       };
     }),
 
+  /**
+   * Disk 데이터 설정 및 히스토리 업데이트
+   */
   setDiskData: (data) =>
     set((state) => {
       const selectedDeviceId = state.selectedDeviceId;
@@ -135,6 +167,9 @@ export const useMonitoringStore = create<MonitoringState>((set, get) => ({
       };
     }),
 
+  /**
+   * Network 데이터 설정 및 히스토리 업데이트
+   */
   setNetworkData: (data) =>
     set((state) => {
       const selectedDeviceId = state.selectedDeviceId;
@@ -174,6 +209,9 @@ export const useMonitoringStore = create<MonitoringState>((set, get) => ({
       };
     }),
 
+  /**
+   * 장비의 메트릭 설정 (백그라운드 모니터링용)
+   */
   setDeviceMetrics: (deviceId: number, metrics: SimpleMetrics) =>
     set((state) => {
       const newMap = new Map(state.deviceMetricsMap);
@@ -181,6 +219,9 @@ export const useMonitoringStore = create<MonitoringState>((set, get) => ({
       return { deviceMetricsMap: newMap };
     }),
 
+  /**
+   * 장비 히스토리 로드 (선택된 장비가 바뀔 때 호출)
+   */
   loadDeviceHistory: (deviceId: number) => {
     const state = get();
     const deviceHistory = state.deviceHistoryMap.get(deviceId);
@@ -219,6 +260,9 @@ export const useMonitoringStore = create<MonitoringState>((set, get) => ({
     }
   },
 
+  /**
+   * 모든 히스토리 초기화
+   */
   clearHistory: () =>
     set({
       systemHistory: [],
diff --git a/src/domains/serverView/serverDashboard/types/event-source-polyfill.d.ts b/src/domains/serverView/serverDashboard/types/event-source-polyfill.d.ts
index 05363e4..ab4c8eb 100644
--- a/src/domains/serverView/serverDashboard/types/event-source-polyfill.d.ts
+++ b/src/domains/serverView/serverDashboard/types/event-source-polyfill.d.ts
@@ -1,13 +1,36 @@
+/**
+ * @author 구희원
+ * @description EventSourcePolyfill 타입 정의 확장
+ */
+
 import "event-source-polyfill";
 
+/**
+ * EventSourcePolyfill 모듈 타입 확장
+ *
+ * event-source-polyfill 라이브러리의 타입 정의를 확장하여
+ * addEventListener 및 removeEventListener 메서드의 타입을 명시합니다.
+ */
 declare module "event-source-polyfill" {
   interface EventSourcePolyfill {
+    /**
+     * 이벤트 리스너 추가
+     * @param type - 이벤트 타입
+     * @param listener - 이벤트 리스너 함수
+     * @param options - 리스너 옵션
+     */
     addEventListener(
       type: string,
       listener: (event: MessageEvent) => void,
       options?: boolean | AddEventListenerOptions
     ): void;
 
+    /**
+     * 이벤트 리스너 제거
+     * @param type - 이벤트 타입
+     * @param listener - 이벤트 리스너 함수
+     * @param options - 리스너 옵션
+     */
     removeEventListener(
       type: string,
       listener: (event: MessageEvent) => void,
diff --git a/src/domains/serverView/serverDashboard/types/index.ts b/src/domains/serverView/serverDashboard/types/index.ts
index 71fe28d..9da0711 100644
--- a/src/domains/serverView/serverDashboard/types/index.ts
+++ b/src/domains/serverView/serverDashboard/types/index.ts
@@ -1,5 +1,13 @@
+/**
+ * @author 구희원
+ * @description 서버 모니터링 타입 정의
+ */
+
 import type { Equipments } from "../../rack/types/index";
 
+/**
+ * 장비 수정 요청
+ */
 export interface UpdateEquipmentRequest
   extends Pick<
     Equipments,
@@ -15,6 +23,9 @@ export interface UpdateEquipmentRequest
   diskThresholdCritical: number;
 }
 
+/**
+ * 시스템 모니터링 데이터
+ */
 export interface SystemMonitoringData {
   id: number;
   equipmentId: number;
@@ -44,6 +55,9 @@ export interface SystemMonitoringData {
   usedSwapPercentage: number;
 }
 
+/**
+ * 디스크 모니터링 데이터
+ */
 export interface DiskMonitoringData {
   id: number;
   equipmentId: number;
@@ -63,6 +77,9 @@ export interface DiskMonitoringData {
   usedInodePercentage: number;
 }
 
+/**
+ * 네트워크 모니터링 데이터
+ */
 export interface NetworkMonitoringData {
   id: number;
   equipmentId: number;
diff --git a/src/domains/serverView/serverDashboard/utils/chartDataBuilder.ts b/src/domains/serverView/serverDashboard/utils/chartDataBuilder.ts
index 5d39193..a0819eb 100644
--- a/src/domains/serverView/serverDashboard/utils/chartDataBuilder.ts
+++ b/src/domains/serverView/serverDashboard/utils/chartDataBuilder.ts
@@ -1,3 +1,8 @@
+/**
+ * @author 구희원
+ * @description 차트 데이터 빌더 유틸리티
+ */
+
 import {
   generateTimeLabels,
   bytesToMbps,
@@ -6,6 +11,9 @@ import {
 import { CHART_CONFIG } from "../constants";
 import type { NetworkMonitoringData } from "../types";
 
+/**
+ * 차트 시리즈 데이터
+ */
 interface ChartSeries {
   name: string;
   data: number[];
@@ -15,6 +23,9 @@ interface ChartSeries {
   averageColor?: string;
 }
 
+/**
+ * 시스템 데이터
+ */
 interface SystemData {
   cpuIdle: number;
   usedMemoryPercentage: number;
@@ -30,11 +41,17 @@ interface SystemData {
   cpuSteal?: number;
 }
 
+/**
+ * 디스크 데이터
+ */
 interface DiskData {
   usedPercentage: number;
   usedInodePercentage?: number;
 }
 
+/**
+ * 히스토리 레코드
+ */
 export interface HistoryRecord {
   cpuUser?: number;
   cpuSystem?: number;
@@ -55,12 +72,18 @@ export interface HistoryRecord {
   [key: string]: unknown;
 }
 
+/**
+ * 집계된 네트워크 데이터
+ */
 interface AggregatedNetwork {
   rx: number[];
   tx: number[];
   timeLabels: string[];
 }
 
+/**
+ * 차트 데이터 상태
+ */
 interface ChartDataState {
   systemData: SystemData | null;
   diskData: DiskData | null;
@@ -69,6 +92,9 @@ interface ChartDataState {
   networkHistory: NetworkMonitoringData[][];
 }
 
+/**
+ * 차트 데이터 결과
+ */
 interface ChartDataResult {
   timeLabels: string[];
   networkTimeLabels: string[];
@@ -86,7 +112,9 @@ interface ChartDataResult {
 
 const { MAX_POINTS, COLORS } = CHART_CONFIG;
 
-// 공통 series 생성 헬퍼
+/**
+ * 시리즈 생성 옵션
+ */
 interface CreateSeriesOptions {
   name: string;
   data: number[];
@@ -96,6 +124,9 @@ interface CreateSeriesOptions {
   averageColor?: string;
 }
 
+/**
+ * 차트 시리즈 생성 헬퍼
+ */
 const createSeries = ({
   name,
   data,
@@ -114,7 +145,9 @@ const createSeries = ({
   }),
 });
 
-// 빈 차트 데이터 결과
+/**
+ * 빈 차트 데이터
+ */
 const EMPTY_CHART_DATA: ChartDataResult = {
   timeLabels: [],
   networkTimeLabels: [],
@@ -130,7 +163,9 @@ const EMPTY_CHART_DATA: ChartDataResult = {
   inodeUsage: [],
 };
 
-// CPU 모드 series 생성
+/**
+ * CPU 모드 시리즈 생성
+ */
 const buildCpuModes = (history: HistoryRecord[]): ChartSeries[] => [
   createSeries({
     name: "User",
@@ -159,7 +194,9 @@ const buildCpuModes = (history: HistoryRecord[]): ChartSeries[] => [
   }),
 ];
 
-// Load Average series 생성
+/**
+ * Load Average 시리즈 생성
+ */
 const buildLoadAverage = (history: HistoryRecord[]): ChartSeries[] => [
   createSeries({
     name: "1분 평균",
@@ -178,7 +215,9 @@ const buildLoadAverage = (history: HistoryRecord[]): ChartSeries[] => [
   }),
 ];
 
-// Memory & Swap series 생성
+/**
+ * Memory & Swap 시리즈 생성
+ */
 const buildMemorySwap = (history: HistoryRecord[]): ChartSeries[] => [
   createSeries({
     name: "메모리",
@@ -194,7 +233,9 @@ const buildMemorySwap = (history: HistoryRecord[]): ChartSeries[] => [
   }),
 ];
 
-// Network Bandwidth series 생성
+/**
+ * Network Bandwidth 시리즈 생성
+ */
 const buildNetworkBandwidth = (
   aggregated: AggregatedNetwork
 ): ChartSeries[] => [
@@ -210,7 +251,9 @@ const buildNetworkBandwidth = (
   }),
 ];
 
-// CPU Overhead series 생성
+/**
+ * CPU Overhead 시리즈 생성
+ */
 const buildCpuOverhead = (history: HistoryRecord[]): ChartSeries[] => [
   createSeries({
     name: "I/O Wait (%)",
@@ -230,7 +273,9 @@ const buildCpuOverhead = (history: HistoryRecord[]): ChartSeries[] => [
   }),
 ];
 
-// Disk I/O series 생성
+/**
+ * Disk I/O 시리즈 생성
+ */
 const buildDiskIO = (history: HistoryRecord[]): ChartSeries[] => [
   createSeries({
     name: "읽기",
@@ -244,7 +289,9 @@ const buildDiskIO = (history: HistoryRecord[]): ChartSeries[] => [
   }),
 ];
 
-// Inode Usage series 생성
+/**
+ * Inode Usage 시리즈 생성
+ */
 const buildInodeUsage = (history: HistoryRecord[]): ChartSeries[] => [
   createSeries({
     name: "Disk 사용률",
@@ -264,7 +311,14 @@ const buildInodeUsage = (history: HistoryRecord[]): ChartSeries[] => [
   }),
 ];
 
-// 메인: 차트 데이터 빌드
+/**
+ * 차트 데이터 빌드
+ *
+ * 모니터링 데이터 히스토리를 차트에 표시할 형식으로 변환합니다.
+ *
+ * @param {ChartDataState} state - 차트 데이터 상태
+ * @returns {ChartDataResult} 변환된 차트 데이터
+ */
 export const buildChartData = ({
   systemData,
   diskData,
diff --git a/src/domains/serverView/serverDashboard/utils/monitoring.ts b/src/domains/serverView/serverDashboard/utils/monitoring.ts
index ba3ac90..fb2a8d3 100644
--- a/src/domains/serverView/serverDashboard/utils/monitoring.ts
+++ b/src/domains/serverView/serverDashboard/utils/monitoring.ts
@@ -1,5 +1,19 @@
+/**
+ * @author 구희원
+ * @description 모니터링 데이터 처리 유틸리티
+ */
+
 import type { NetworkMonitoringData } from "../types";
 
+/**
+ * 시간 레이블 생성
+ *
+ * 히스토리 데이터에서 시간 레이블을 생성합니다 (HH:MM:SS 형식).
+ *
+ * @param {T[]} history - 시간 정보가 있는 히스토리 데이터
+ * @param {number} maxPoints - 최대 포인트 수 (기본값: 12)
+ * @returns {string[]} 시간 레이블 배열
+ */
 export const generateTimeLabels = <T extends { generateTime: string }>(
   history: T[],
   maxPoints: number = 12
@@ -13,22 +27,51 @@ export const generateTimeLabels = <T extends { generateTime: string }>(
   });
 };
 
+/**
+ * Bytes를 GB로 변환
+ * @param {number} bytes - 바이트 값
+ * @returns {number} GB 값
+ */
 export const bytesToGB = (bytes: number): number => {
   return bytes / 1024 ** 3;
 };
 
+/**
+ * Bytes를 MB로 변환
+ * @param {number} bytes - 바이트 값
+ * @returns {number} MB 값
+ */
 export const bytesToMB = (bytes: number): number => {
   return bytes / 1024 ** 2;
 };
 
+/**
+ * KB를 MB로 변환
+ * @param {number} kb - KB 값
+ * @returns {number} MB 값
+ */
 export const kbToMB = (kb: number): number => {
   return kb / 1024;
 };
 
+/**
+ * Bytes를 Mbps로 변환
+ * @param {number} bytes - 바이트 값
+ * @returns {number} Mbps 값
+ */
 export const bytesToMbps = (bytes: number): number => {
   return (bytes * 8) / (1024 * 1024);
 };
 
+/**
+ * 네트워크 데이터를 시간별로 집계
+ *
+ * 여러 네트워크 인터페이스의 데이터를 시간대별로 그룹화하고 합산합니다.
+ *
+ * @param {NetworkMonitoringData[]} networkHistory - 네트워크 히스토리 데이터
+ * @param {number} maxPoints - 최대 포인트 수 (기본값: 12)
+ * @returns {{ rx: number[]; tx: number[]; timeLabels: string[] }} 집계된 네트워크 데이터
+ */
 export const aggregateNetworkByTime = (
   networkHistory: NetworkMonitoringData[],
   maxPoints: number = 12
diff --git a/src/domains/serverView/types/index.ts b/src/domains/serverView/types/index.ts
index e0a559d..59b27f7 100644
--- a/src/domains/serverView/types/index.ts
+++ b/src/domains/serverView/types/index.ts
@@ -1,3 +1,11 @@
+/**
+ * @author 구희원
+ * @description 3D 서버룸 장비 타입 정의
+ */
+
+/**
+ * 장비 타입
+ */
 export type EquipmentType =
   | "server"
   | "door"
@@ -6,6 +14,9 @@ export type EquipmentType =
   | "thermometer"
   | "aircon";
 
+/**
+ * 3D 장비 정보
+ */
 export interface Equipment3D {
   id: string; // 프론트엔드에서 사용하는 로컬 ID (equipmentId로부터 생성)
   type: EquipmentType;
@@ -19,7 +30,9 @@ export interface Equipment3D {
   metadata?: EquipmentMetadata; // 추가 정보
 }
 
-// 장비 추가 정보
+/**
+ * 장비 메타데이터
+ */
 export interface EquipmentMetadata {
   name?: string;
   code?: string;
@@ -35,7 +48,9 @@ export interface EquipmentMetadata {
   [key: string]: unknown; // 기타 메타데이터
 }
 
-// 백엔드 API 응답 타입 (새로운 구조)
+/**
+ * 서버룸 장비 API 응답
+ */
 export interface ServerRoomEquipmentResponse {
   status_code: number;
   status_message: string;
@@ -50,7 +65,9 @@ export interface ServerRoomEquipmentResponse {
   };
 }
 
-// 백엔드에서 받는 장비(디바이스) 데이터 구조
+/**
+ * 백엔드 장비 데이터
+ */
 export interface BackendDevice {
   id: number; // DB의 장비 ID
   deviceName: string;
@@ -67,7 +84,9 @@ export interface BackendDevice {
   doorDirection?: "FRONT" | "BACK"; // 랙의 문 방향 (server 타입인 경우)
 }
 
-// 새 장비 생성 요청 데이터 구조
+/**
+ * 장비 생성 요청
+ */
 export interface CreateDeviceRequest {
   deviceName: string;
   deviceCode: string;
@@ -87,14 +106,18 @@ export interface CreateDeviceRequest {
   serverRoomId: number;
 }
 
-// 장비 생성 응답 구조
+/**
+ * 장비 생성 응답
+ */
 export interface CreateDeviceResponse {
   status_code: number;
   status_message: string;
   result: BackendDevice;
 }
 
-// 장비 수정 요청 데이터 구조
+/**
+ * 장비 수정 요청
+ */
 export interface UpdateDeviceRequest {
   gridY: number;
   gridX: number;
@@ -110,14 +133,18 @@ export interface UpdateDeviceRequest {
   notes?: string;
 }
 
-// 장비 수정 응답 구조
+/**
+ * 장비 수정 응답
+ */
 export interface UpdateDeviceResponse {
   status_code: number;
   status_message: string;
   result: BackendDevice;
 }
 
-// 랙 생성 요청 데이터 구조
+/**
+ * 랙 생성 요청
+ */
 export interface CreateRackRequest {
   rackName: string;
   gridX: number;
@@ -134,7 +161,9 @@ export interface CreateRackRequest {
   serverRoomId: number;
 }
 
-// 랙 생성 응답 구조
+/**
+ * 랙 생성 응답
+ */
 export interface CreateRackResponse {
   status_code: number;
   status_message: string;
@@ -156,7 +185,9 @@ export interface CreateRackResponse {
   };
 }
 
-// 이전 구조 호환성을 위한 타입 (deprecated)
+/**
+ * 백엔드 장비 (이전 구조 - deprecated)
+ */
 export interface BackendEquipment {
   equipmentId: string; // DB의 UUID
   equipmentType: EquipmentType;
@@ -170,14 +201,18 @@ export interface BackendEquipment {
   metadata?: EquipmentMetadata;
 }
 
-// 격자 설정
+/**
+ * 격자 설정
+ */
 export interface GridConfig {
   rows: number; // 격자 행 개수
   columns: number; // 격자 열 개수
   cellSize: number; // 한 격자 크기
 }
 
-// 장비 팔레트 아이템
+/**
+ * 장비 팔레트 아이템
+ */
 export interface EquipmentPaletteItem {
   type: EquipmentType;
   name: string;

From 4f92ee76a4abb1cd4fdf291f5d7c2bc93406343f Mon Sep 17 00:00:00 2001
From: HeHelee <selly3109@naver.com>
Date: Fri, 28 Nov 2025 10:47:50 +0900
Subject: [PATCH 2/5] =?UTF-8?q?feat:=20=EC=A3=BC=EC=84=9D=20=EC=88=98?=
 =?UTF-8?q?=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/domains/serverView/types/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/domains/serverView/types/index.ts b/src/domains/serverView/types/index.ts
index 59b27f7..29f8747 100644
--- a/src/domains/serverView/types/index.ts
+++ b/src/domains/serverView/types/index.ts
@@ -1,5 +1,5 @@
 /**
- * @author 구희원
+ * @author 김대호
  * @description 3D 서버룸 장비 타입 정의
  */
 

From bd4bee8a1a12c18cc1503aef67d3cf1d0ff26458 Mon Sep 17 00:00:00 2001
From: HeHelee <selly3109@naver.com>
Date: Fri, 28 Nov 2025 11:57:02 +0900
Subject: [PATCH 3/5] =?UTF-8?q?feat:=20=EC=A3=BC=EC=84=9D=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80=E3=85=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/api/client.ts                             | 55 ++++++++++++++++--
 src/domains/login/api/loginApi.ts             | 26 +++++++++
 src/domains/login/api/refreshApi.ts           | 20 +++++++
 .../login/components/AnimationBackground.tsx  | 41 +++++++------
 src/domains/login/components/Button.tsx       | 20 +++++++
 src/domains/login/components/Circle.tsx       | 25 ++++++++
 src/domains/login/components/Input.tsx        | 43 ++++++++++++++
 .../login/components/NetworkAnimation.tsx     | 25 ++++++++
 src/domains/login/css/LoginPage.css           | 54 +++++++++++++++++
 src/domains/login/css/circle.css              | 32 ++++++++++
 src/domains/login/css/input.css               | 58 ++++++++++++++++++-
 src/domains/login/hooks/useLogin.ts           | 26 ++++++++-
 src/domains/login/store/useAuthStore.ts       | 50 ++++++++++++++--
 src/domains/login/types/circle.ts             | 24 ++++++++
 src/domains/login/types/login.ts              | 22 +++++++
 15 files changed, 488 insertions(+), 33 deletions(-)

diff --git a/src/api/client.ts b/src/api/client.ts
index 384f710..ad087d5 100644
--- a/src/api/client.ts
+++ b/src/api/client.ts
@@ -1,27 +1,54 @@
+/**
+ * @author 구희원 김대호
+ * @description Axios 기반 API 클라이언트 설정 및 In-Memory Access Token 관리 로직
+ *
+ * - In-memory에 Access Token 저장 및 참조
+ * - 요청 인터셉터에서 Authorization 헤더 자동 주입
+ * - 401 발생 시 Refresh Token 기반 토큰 재발급 처리
+ * - 재발급 실패 시 자동 로그아웃 및 메인 페이지로 이동
+ */
+
 import axios from "axios";
 
 // const BASE_URL = "http://localhost:8080/api";
 export const BASE_URL = "https://api.serverway.shop/api";
 
-// 메모리에 토큰 저장
+/**
+ * Access Token을 메모리에 저장하기 위한 변수 (새로고침 시 초기화됨)
+ * HttpOnly 쿠키로 Refresh Token을 관리하는 구조이므로 Access Token만 메모리 관리
+ */
 let accessTokenInMemory: string | null = null;
 
+/**
+ * Access Token 저장
+ * @param {string | null} token - 저장할 액세스 토큰
+ */
 export const setAccessToken = (token: string | null) => {
   accessTokenInMemory = token;
 };
 
+/**
+ * 현재 In-Memory Access Token 반환
+ * @returns {string | null} Access Token
+ */
 export const getAccessToken = () => accessTokenInMemory;
 
+/**
+ * Axios 기본 클라이언트 설정
+ */
 const client = axios.create({
   baseURL: BASE_URL,
   headers: {
     "Content-Type": "application/json",
     Accept: "application/json",
   },
-  withCredentials: true, // HttpOnly 쿠키 전송 (Refresh Token)
+  withCredentials: true, // Refresh Token(HttpOnly Cookie) 자동 전송
 });
 
-// 요청 인터셉터
+/**
+ * 요청 인터셉터
+ * - In-Memory Access Token이 존재하면 Authorization 헤더 자동 추가
+ */
 client.interceptors.request.use(
   (config) => {
     if (accessTokenInMemory) {
@@ -32,17 +59,25 @@ client.interceptors.request.use(
   (error) => Promise.reject(error)
 );
 
-// 응답 인터셉터
+/**
+ * 응답 인터셉터
+ *
+ * - 401(Unauthorized) 발생 시 Refresh Token을 사용해 토큰 재발급 시도
+ * - 재발급 성공 시 자동으로 원래 요청 재시도
+ * - 실패 시 Access Token 삭제 및 메인 페이지로 리다이렉트
+ */
 client.interceptors.response.use(
   (response) => response,
+
   async (error) => {
     const originalRequest = error.config;
 
+    // 401 + 재시도한 적 없는 요청만 처리
     if (error.response?.status === 401 && !originalRequest._retry) {
       originalRequest._retry = true;
 
       try {
-        // Refresh Token은 HttpOnly 쿠키로 자동 전송됨
+        // Refresh Token은 HttpOnly 쿠키로 자동 포함됨
         const response = await axios.post(
           `${BASE_URL}/auth/refresh`,
           {},
@@ -50,17 +85,25 @@ client.interceptors.response.use(
         );
 
         const newToken = response.data.accessToken;
-        setAccessToken(newToken); // 메모리에 저장
 
+        // 새 Access Token 메모리에 저장
+        setAccessToken(newToken);
+
+        // 원래 요청에 새로운 토큰 적용
         originalRequest.headers["Authorization"] = `Bearer ${newToken}`;
+
         return client(originalRequest);
       } catch (error) {
         console.error("Token refresh failed:", error);
+
+        // 토큰 삭제 및 로그아웃 처리
         setAccessToken(null);
         window.location.href = "/";
+
         return Promise.reject(error);
       }
     }
+
     return Promise.reject(error);
   }
 );
diff --git a/src/domains/login/api/loginApi.ts b/src/domains/login/api/loginApi.ts
index fdd6161..3a4ed64 100644
--- a/src/domains/login/api/loginApi.ts
+++ b/src/domains/login/api/loginApi.ts
@@ -1,14 +1,40 @@
+/**
+ * @author 구희원
+ * @description 로그인 API 호출 모듈
+ *
+ * - 서버에 로그인 요청을 보내고 Access Token 발급
+ * - 반환된 데이터는 LoginResponse 타입으로 변환
+ * - Axios 인스턴스(@api/client) 사용
+ */
+
 import client from "@api/client";
 import type { LoginRequest, LoginResponse } from "../types/login";
 
+/**
+ * API 응답 타입 정의
+ */
 interface LoginApiResponse {
   status_code: number;
   status_message: string;
   result: LoginResponse;
 }
 
+/**
+ * 로그인 요청 함수
+ *
+ * @param {LoginRequest} data - 로그인 요청 데이터 (username, password 등)
+ * @returns {Promise<LoginResponse>} 로그인 성공 시 반환되는 사용자 정보 및 토큰
+ *
+ * @example
+ * const loginData = { username: "user1", password: "1234" };
+ * const result = await loginApi(loginData);
+ * console.log(result.accessToken);
+ */
 export const loginApi = async (data: LoginRequest): Promise<LoginResponse> => {
   console.log("Using client:", client.defaults.withCredentials);
+
   const response = await client.post<LoginApiResponse>("/auth/login", data);
+
+  // API의 result 필드만 반환
   return response.data.result;
 };
diff --git a/src/domains/login/api/refreshApi.ts b/src/domains/login/api/refreshApi.ts
index f179ade..b43aa98 100644
--- a/src/domains/login/api/refreshApi.ts
+++ b/src/domains/login/api/refreshApi.ts
@@ -1,5 +1,20 @@
+/**
+ * @author 구희원
+ * @description Access Token 갱신 API 호출 유틸리티
+ *
+ * - 서버에 Refresh Token 기반 요청
+ * - 새 Access Token을 반환
+ */
+
 import client from "@api/client";
 
+/**
+ * @interface RefreshApiResponse
+ * @description Refresh API 응답 타입
+ * @property {number} status_code - 상태 코드
+ * @property {string} status_message - 상태 메시지
+ * @property {{ accessToken: string }} result - 새로 발급된 Access Token
+ */
 interface RefreshApiResponse {
   status_code: number;
   status_message: string;
@@ -8,6 +23,11 @@ interface RefreshApiResponse {
   };
 }
 
+/**
+ * @function refreshTokenApi
+ * @description Refresh Token으로 새로운 Access Token 발급
+ * @returns {Promise<string>} - 새 Access Token
+ */
 export const refreshTokenApi = async (): Promise<string> => {
   const response = await client.post<RefreshApiResponse>("/auth/refresh");
   return response.data.result.accessToken;
diff --git a/src/domains/login/components/AnimationBackground.tsx b/src/domains/login/components/AnimationBackground.tsx
index ff98705..f141719 100644
--- a/src/domains/login/components/AnimationBackground.tsx
+++ b/src/domains/login/components/AnimationBackground.tsx
@@ -1,6 +1,18 @@
+/**
+ * @author 구희원
+ * @description 배경 애니메이션용 Circle 컴포넌트 모음
+ *
+ * - 여러 Circle 컴포넌트를 지정된 위치, 크기, 색상으로 배치
+ * - Tailwind CSS를 활용한 위치 및 z-index 관리
+ * - 화면 전체를 덮는 고정 배경으로 설정
+ */
+
 import Circle from "./Circle";
 import type { CircleConfig } from "../types/circle";
 
+/**
+ * 각 Circle의 설정 정보
+ */
 const CIRCLE_CONFIGS: CircleConfig[] = [
   { id: "1", size: "small", gradient: "blue", position: "top-1/3 left-1/12" },
   {
@@ -10,27 +22,20 @@ const CIRCLE_CONFIGS: CircleConfig[] = [
     position: "bottom-1/4 left-1/12",
   },
   { id: "3", size: "medium", gradient: "pink", position: "top-1/4 left-1/3" },
-  {
-    id: "4",
-    size: "medium",
-    gradient: "orange",
-    position: "top-1/2 left-1/3",
-  },
+  { id: "4", size: "medium", gradient: "orange", position: "top-1/2 left-1/3" },
   { id: "5", size: "small", gradient: "blue", position: "top-1/2 right-1/4" },
-  {
-    id: "6",
-    size: "small",
-    gradient: "purple",
-    position: "top-1/2 right-1/7",
-  },
-  {
-    id: "7",
-    size: "small",
-    gradient: "pink",
-    position: "top-1/6 right-1/12",
-  },
+  { id: "6", size: "small", gradient: "purple", position: "top-1/2 right-1/7" },
+  { id: "7", size: "small", gradient: "pink", position: "top-1/6 right-1/12" },
 ];
 
+/**
+ * 배경 애니메이션 컴포넌트
+ *
+ * @returns {JSX.Element} 배경에 고정된 Circle 애니메이션 요소
+ *
+ * @example
+ * <AnimationBackground />
+ */
 function AnimationBackground() {
   return (
     <div className="fixed inset-0 -z-10 overflow-hidden">
diff --git a/src/domains/login/components/Button.tsx b/src/domains/login/components/Button.tsx
index 7feb724..180a590 100644
--- a/src/domains/login/components/Button.tsx
+++ b/src/domains/login/components/Button.tsx
@@ -1,9 +1,29 @@
+/**
+ * @author 구희원
+ * @description 재사용 가능한 버튼 컴포넌트
+ *
+ * - 텍스트와 disabled 상태를 받아 버튼 생성
+ * - Tailwind CSS를 활용한 스타일링
+ * - 기본 type="submit"
+ */
+
 interface ButtonProps {
+  /** 버튼에 표시될 텍스트 */
   text: string;
 
+  /** 버튼 활성화 여부 (기본값: false) */
   disabled?: boolean;
 }
 
+/**
+ * 버튼 컴포넌트
+ *
+ * @param {ButtonProps} props - 버튼 속성
+ * @returns {JSX.Element} 스타일이 적용된 버튼 요소
+ *
+ * @example
+ * <Button text="생성" disabled={false} />
+ */
 function Button({ text, disabled }: ButtonProps) {
   return (
     <button
diff --git a/src/domains/login/components/Circle.tsx b/src/domains/login/components/Circle.tsx
index 21a3a71..fcb319f 100644
--- a/src/domains/login/components/Circle.tsx
+++ b/src/domains/login/components/Circle.tsx
@@ -1,17 +1,33 @@
+/**
+ * @author 구희원
+ * @description 애니메이션 원(Circle) 컴포넌트
+ *
+ * - 크기(size), 그라데이션(gradient), 위치(position)를 받아 원형 요소 생성
+ * - Tailwind CSS 클래스와 커스텀 CSS 애니메이션(animate-twinkle-slow) 적용
+ * - 배경 그라데이션은 지정된 컬러 팔레트 중 선택
+ */
+
 import type { CircleSize, CircleGradient } from "../types/circle";
 import "../css/circle.css";
 
 interface CircleProps {
+  /** 원의 배경 그라데이션 */
   gradient: CircleGradient;
+
+  /** 화면 내 위치 (Tailwind CSS 클래스 문자열) */
   position: string;
+
+  /** 원의 크기 */
   size: CircleSize;
 }
 
+/** Circle 크기 매핑 */
 const sizes: Record<CircleSize, string> = {
   small: "15vw",
   medium: "20vw",
 };
 
+/** Circle 그라데이션 색상 매핑 */
 const gradients: Record<CircleGradient, string> = {
   blue: "linear-gradient(to right, #06b6d4, #14b8a6)",
   purple: "linear-gradient(to right, #4F39F6, #9810FA)",
@@ -21,6 +37,15 @@ const gradients: Record<CircleGradient, string> = {
   green: "linear-gradient(to right, #10b981, #06b6d4)",
 };
 
+/**
+ * Circle 컴포넌트
+ *
+ * @param {CircleProps} props - Circle 속성
+ * @returns {JSX.Element} 애니메이션이 적용된 원형 요소
+ *
+ * @example
+ * <Circle size="small" gradient="blue" position="top-1/3 left-1/12" />
+ */
 const Circle = ({ size, gradient, position }: CircleProps) => {
   return (
     <div
diff --git a/src/domains/login/components/Input.tsx b/src/domains/login/components/Input.tsx
index ae17611..6cfc338 100644
--- a/src/domains/login/components/Input.tsx
+++ b/src/domains/login/components/Input.tsx
@@ -1,17 +1,60 @@
+/**
+ * @author 구희원
+ * @description 재사용 가능한 Input 컴포넌트
+ *
+ * - 라벨, 아이콘, 에러 메시지, disabled 상태 등을 지원
+ * - Tailwind 또는 커스텀 CSS(input.css)로 스타일링
+ * - 외부에서 상태(value)와 onChange 핸들러를 받아 제어 컴포넌트로 사용
+ */
+
 import "../css/input.css";
 
 interface InputProps {
+  /** 입력 필드 placeholder */
   placeholder: string;
+
+  /** 입력 타입 (기본값: text) */
   type?: string;
+
+  /** 입력 값 */
   value: string;
+
+  /** 입력 필드 라벨 */
   label: string;
+
+  /** 입력 필드 id */
   id: string;
+
+  /** 값 변경 시 호출되는 핸들러 */
   onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+
+  /** 에러 메시지 */
   error?: string;
+
+  /** 입력 필드 앞에 표시할 아이콘 */
   icon: React.ReactNode;
+
+  /** 입력 필드 비활성화 여부 */
   disabled?: boolean;
 }
 
+/**
+ * Input 컴포넌트
+ *
+ * @param {InputProps} props - Input 속성
+ * @returns {JSX.Element} 라벨, 아이콘, 에러 메시지가 포함된 입력 필드
+ *
+ * @example
+ * <Input
+ *   id="username"
+ *   label="사용자 이름"
+ *   placeholder="이름을 입력하세요"
+ *   value={username}
+ *   onChange={(e) => setUsername(e.target.value)}
+ *   icon={<UserIcon />}
+ *   error={usernameError}
+ * />
+ */
 function Input({
   placeholder,
   type = "text",
diff --git a/src/domains/login/components/NetworkAnimation.tsx b/src/domains/login/components/NetworkAnimation.tsx
index 308e8f4..f8bc494 100644
--- a/src/domains/login/components/NetworkAnimation.tsx
+++ b/src/domains/login/components/NetworkAnimation.tsx
@@ -1,5 +1,16 @@
+/**
+ * @author 구희원
+ * @description 네트워크 노드와 연결선을 애니메이션으로 시각화하는 컴포넌트
+ *
+ * - Framer Motion과 SVG를 활용하여 노드, 연결선, 입자 애니메이션 구현
+ * - 노드의 크기, 색상, 위치 및 애니메이션 속성 정의
+ * - 연결선(line)과 입자(particles) 애니메이션 포함
+ * - 네트워크 그래프와 유사한 시각적 효과 제공
+ */
+
 import { motion } from "framer-motion";
 
+/** 노드 설정 */
 const nodes = [
   { cx: 100, cy: 100, r: 35, color: "#22c55e", delay: 0.1, duration: 2.2 },
   { cx: 250, cy: 80, r: 28, color: "#10b981", delay: 0.2, duration: 2.5 },
@@ -11,6 +22,7 @@ const nodes = [
   { cx: 600, cy: 220, r: 40, color: "#22c55e", delay: 0.8, duration: 2.1 },
 ];
 
+/** 연결선 설정 */
 const lines = [
   { x1: 100, y1: 100, x2: 250, y2: 80, gradient: 1, delay: 0.1 },
   { x1: 100, y1: 100, x2: 200, y2: 225, gradient: 2, delay: 0.15 },
@@ -30,6 +42,7 @@ const lines = [
   { x1: 500, y1: 280, x2: 600, y2: 220, gradient: 2, delay: 0.85 },
 ];
 
+/** 입자 애니메이션 설정 */
 const particles = [
   { path: "M100,100 L250,80", color: "#22c55e", duration: 2.5, begin: "0s" },
   { path: "M100,100 L200,225", color: "#10b981", duration: 3, begin: "0.3s" },
@@ -41,6 +54,14 @@ const particles = [
   { path: "M500,280 L600,220", color: "#10b981", duration: 2.7, begin: "2.1s" },
 ];
 
+/**
+ * 네트워크 애니메이션 컴포넌트
+ *
+ * @returns {JSX.Element} 노드, 연결선, 입자 애니메이션이 포함된 SVG
+ *
+ * @example
+ * <NetworkAnimation />
+ */
 function NetworkAnimation() {
   return (
     <div className="relative flex items-start justify-center px-8 -mt-8">
@@ -50,6 +71,7 @@ function NetworkAnimation() {
         xmlns="http://www.w3.org/2000/svg"
       >
         <defs>
+          {/* 선 그라데이션 정의 */}
           <linearGradient id="lineGradient" x1="0%" y1="0%" x2="100%" y2="0%">
             <stop offset="0%" stopColor="#22c55e" stopOpacity="0.2" />
             <stop offset="50%" stopColor="#22c55e" stopOpacity="0.6" />
@@ -69,6 +91,7 @@ function NetworkAnimation() {
           </filter>
         </defs>
 
+        {/* 연결선 렌더링 */}
         {lines.map((line, i) => (
           <motion.line
             key={`line-${i}`}
@@ -84,6 +107,7 @@ function NetworkAnimation() {
           />
         ))}
 
+        {/* 노드 렌더링 */}
         {nodes.map((node, i) => {
           const innerR = node.r * 0.63;
           const coreR = node.r * 0.31;
@@ -139,6 +163,7 @@ function NetworkAnimation() {
           );
         })}
 
+        {/* 입자 렌더링 */}
         {particles.map((particle, i) => (
           <motion.circle
             key={`particle-${i}`}
diff --git a/src/domains/login/css/LoginPage.css b/src/domains/login/css/LoginPage.css
index 636fb86..4ddbc41 100644
--- a/src/domains/login/css/LoginPage.css
+++ b/src/domains/login/css/LoginPage.css
@@ -1,45 +1,99 @@
+/**
+ * @author 구희원
+ * @description 로그인 페이지 Tailwind CSS 스타일
+ *
+ * - 로그인 화면 레이아웃 및 폼, 로고, 히어로 영역, 네트워크 애니메이션 스타일 정의
+ * - 반응형 단위 vw 사용, 배경 블러와 반투명 효과 적용
+ */
+
 @import "tailwindcss";
 
+/** 
+ * @description 로그인 페이지 전체 컨테이너
+ * - 화면 전체 차지
+ * - 패딩 적용
+ */
 .login-page {
   @apply relative h-screen w-screen p-[4vw];
 }
 
+/** 
+ * @description 로그인 박스 컨테이너
+ * - flex 배치, 반투명 배경, 둥근 테두리, 블러 효과
+ */
 .login-container {
   @apply flex h-full w-full gap-[2vw] rounded-[32px] border border-white/20 bg-white/10 backdrop-blur-[20px];
 }
 
+/** 
+ * @description 로그인 폼 영역 컨테이너
+ * - 화면 좌측 절반
+ * - 수직 정렬, 패딩, 요소 간 간격
+ */
 .login-form-container {
   @apply flex h-full w-1/2 flex-col items-start justify-center gap-[2vw] pl-[4vw];
 }
 
+/** 
+ * @description 로그인 폼 내부
+ * - flex-col, 요소 간 간격, 최대 너비 제한
+ */
 .login-form {
   @apply flex w-full max-w-[28vw] flex-col gap-[1.5vw];
 }
 
+/** 
+ * @description 로그인 로고 이미지
+ */
 .login-logo {
   @apply w-[4vw];
 }
 
+/** 
+ * @description 회전 로고 영역 컨테이너
+ * - 화면 우측 절반
+ * - flex 컬럼 배치, 패딩, 요소 간 간격
+ */
 .rotating-logo-container {
   @apply flex h-full w-1/2 flex-col items-start justify-center gap-[2vw] p-[4vw];
 }
 
+/** 
+ * @description 히어로 컨텐츠 영역
+ * - 수직 배치, 요소 간 간격
+ */
 .hero-content {
   @apply flex w-full flex-col gap-[0.5vw];
 }
 
+/** 
+ * @description 히어로 텍스트 스타일
+ * - 큰 글자, 행간 조정
+ */
 .hero-text {
   @apply text-[4.5vw] leading-[1.3];
 }
 
+/** 
+ * @description 히어로 텍스트 그라디언트
+ * - bg-clip-text와 텍스트 투명 처리로 그라디언트 적용
+ */
 .hero-text-gradient {
   @apply bg-gradient-to-r from-green-500 via-emerald-500 to-cyan-500 bg-clip-text text-transparent;
 }
 
+/** 
+ * @description 히어로 서브텍스트
+ * - 마진, 글자 크기, 줄간격, 투명 흰색
+ */
 .hero-subtext {
   @apply mt-[1vw] text-[1.1vw] leading-[1.6] text-white/60;
 }
 
+/** 
+ * @description 네트워크 애니메이션 래퍼
+ * - 전체 너비, 기본 스케일
+ */
 .network-animation-wrapper {
   @apply w-full scale-100;
 }
diff --git a/src/domains/login/css/circle.css b/src/domains/login/css/circle.css
index 3666ec8..9c81a9f 100644
--- a/src/domains/login/css/circle.css
+++ b/src/domains/login/css/circle.css
@@ -1,6 +1,20 @@
+/**
+ * @author 구희원
+ * @description Tailwind CSS 기반 커스텀 트윙클(Twinkle) 애니메이션 유틸리티
+ *
+ * - opacity 변화를 통해 요소에 천천히 깜박이는 효과를 적용
+ * - 3가지 속도 옵션 제공: 느림(slow), 중간(medium), 빠름(fast)
+ * - Tailwind @layer utilities를 활용하여 재사용 가능한 클래스 정의
+ */
+
 @import "tailwindcss";
 
 @layer utilities {
+  /** 
+   * @description 트윙클 애니메이션 키프레임
+   * - 0%와 100%: opacity 0.5
+   * - 30%: opacity 0.3
+   */
   @keyframes twinkle {
     0%,
     100% {
@@ -11,14 +25,32 @@
     }
   }
 
+  /**
+   * @description 느린 트윙클 애니메이션
+   * - duration: 8초
+   * - ease-in-out
+   * - 무한 반복
+   */
   .animate-twinkle-slow {
     @apply animate-[twinkle_8s_ease-in-out_infinite];
   }
 
+  /**
+   * @description 중간 속도 트윙클 애니메이션
+   * - duration: 6초
+   * - ease-in-out
+   * - 무한 반복
+   */
   .animate-twinkle-medium {
     @apply animate-[twinkle_6s_ease-in-out_infinite];
   }
 
+  /**
+   * @description 빠른 트윙클 애니메이션
+   * - duration: 4초
+   * - ease-in-out
+   * - 무한 반복
+   */
   .animate-twinkle-fast {
     @apply animate-[twinkle_4s_ease-in-out_infinite];
   }
diff --git a/src/domains/login/css/input.css b/src/domains/login/css/input.css
index 0d30b2f..9478273 100644
--- a/src/domains/login/css/input.css
+++ b/src/domains/login/css/input.css
@@ -1,41 +1,88 @@
+/**
+ * @author 구희원
+ * @description Input 컴포넌트용 Tailwind CSS 스타일
+ *
+ * - 입력창과 아이콘, 오류 메시지 등 UI 구성 요소 스타일 정의
+ * - 유연한 레이아웃과 배경, 그림자, 텍스트 색상 적용
+ * - 웹킷 자동완성(Auto-fill) 스타일 제거 및 통일
+ */
+
 @import "tailwindcss";
 
+/** 
+ * @description 입력 컨테이너
+ * - 수직 정렬(flex-col)
+ * - 요소 간 간격(gap-2)
+ */
 .input-container {
   @apply flex flex-col gap-2;
 }
 
+/** 
+ * @description 입력창 래퍼
+ * - 아이콘과 입력창 flex 배치
+ * - 둥근 테두리, 배경, 패딩, 그림자 적용
+ */
 .input-wrapper {
   @apply flex items-center gap-2.5 rounded-lg border border-white/30 bg-white/5 px-4 py-3.5 shadow-md backdrop-blur-[10px];
 }
 
+/** 
+ * @description 입력창 아이콘 컨테이너
+ * - 고정 크기 6x6
+ * - flex 정렬
+ */
 .input-icon {
   @apply flex h-6 w-6 flex-shrink-0 items-center justify-center;
 }
 
+/** 
+ * @description 아이콘 이미지와 SVG
+ * - 컨테이너 크기에 맞게 조정
+ */
 .input-icon img,
 .input-icon svg {
   @apply h-6 w-6 flex-shrink-0 object-contain;
 }
 
+/** 
+ * @description 기본 input 스타일
+ * - 배경 투명, 경계 없음
+ * - 텍스트 및 placeholder 색상 설정
+ */
 input {
   @apply flex-1 border-none bg-transparent text-gray-400 outline-none placeholder:text-gray-500;
 }
 
+/** 
+ * @description 입력창 hover, focus, active 상태
+ * - 그림자 제거
+ * - 테두리 없음
+ */
 input:hover,
 input:focus,
 input:active {
   @apply border-none outline-none shadow-none;
 }
 
+/** 
+ * @description 오류 메시지 텍스트
+ * - 빨간색, 작은 글씨
+ */
 .input-error {
   @apply text-sm text-red-600;
 }
 
+/** 
+ * @description 오류 메시지 컨테이너 높이
+ */
 .input-error-container {
   @apply h-[1.2rem];
 }
 
-/* Autofill 스타일 */
+/** 
+ * @description 웹킷 자동완성 스타일 제거
+ */
 input:-webkit-autofill,
 input:-webkit-autofill:hover,
 input:-webkit-autofill:focus,
@@ -48,14 +95,23 @@ input:-webkit-autofill:active {
   transition: background-color 5000s ease-in-out 0s;
 }
 
+/** 
+ * @description placeholder 텍스트 스타일
+ */
 input::placeholder {
   @apply text-gray-50;
 }
 
+/** 
+ * @description input 필드 텍스트 스타일
+ */
 .input-field {
   @apply appearance-none text-sm font-medium text-gray-50 bg-transparent outline-none;
 }
 
+/** 
+ * @description 다양한 브라우저 placeholder 색상 통일
+ */
 input::-webkit-input-placeholder {
   @apply text-gray-50;
 }
diff --git a/src/domains/login/hooks/useLogin.ts b/src/domains/login/hooks/useLogin.ts
index 153be67..d576c39 100644
--- a/src/domains/login/hooks/useLogin.ts
+++ b/src/domains/login/hooks/useLogin.ts
@@ -1,22 +1,44 @@
+/**
+ * @author 구희원
+ * @description 로그인 API 연동 및 상태 관리 훅
+ *
+ * - React Query의 useMutation을 사용하여 로그인 요청 처리
+ * - 로그인 성공 시 Zustand를 통해 인증 상태 갱신
+ * - 로그인 성공 시 대시보드 페이지로 이동
+ * - 로그인 실패 시 콘솔에 에러 출력
+ */
+
 import { useMutation } from "@tanstack/react-query";
 import { useNavigate } from "react-router-dom";
 import { useAuthStore } from "../store/useAuthStore";
 import { loginApi } from "../api/loginApi";
 import type { LoginRequest } from "../types/login";
 
+/**
+ * @function useLogin
+ * @returns {Mutation<LoginResponse, unknown, LoginRequest>}
+ *   - login: 로그인 요청 함수
+ *   - isLoading, isError 등 React Query 상태 포함
+ */
 export const useLogin = () => {
   const navigate = useNavigate();
   const { login } = useAuthStore();
 
   const mutation = useMutation({
+    // 로그인 API 호출
     mutationFn: (data: LoginRequest) => loginApi(data),
+
+    // 로그인 성공 시 처리
     onSuccess: (response) => {
-      login(response);
-      navigate("/dashboard");
+      login(response); // Zustand 상태 업데이트
+      navigate("/dashboard"); // 대시보드 페이지 이동
     },
+
+    // 로그인 실패 시 처리
     onError: (error) => {
       console.error("Login failed:", error);
     },
   });
+
   return mutation;
 };
diff --git a/src/domains/login/store/useAuthStore.ts b/src/domains/login/store/useAuthStore.ts
index 3f3e089..e7ca7a0 100644
--- a/src/domains/login/store/useAuthStore.ts
+++ b/src/domains/login/store/useAuthStore.ts
@@ -1,11 +1,34 @@
+/**
+ * @author 구희원 김대호
+ * @description Zustand 기반 인증 상태 관리 스토어
+ *
+ * - Access Token과 사용자 정보 관리
+ * - 로그인, 로그아웃, 인증 상태 복원 기능 제공
+ * - localStorage에는 보안상 토큰을 저장하지 않고 사용자 정보와 인증 상태만 저장
+ */
+
 import { create } from "zustand";
 import { persist } from "zustand/middleware";
 import type { LoginResponse } from "../types/login";
 import { setAccessToken } from "@api/client";
 import { refreshTokenApi } from "../api/refreshApi";
 
+/**
+ * @typedef User
+ * @description 로그인 응답에서 Access Token을 제외한 사용자 정보
+ */
 type User = Omit<LoginResponse, "accessToken">;
 
+/**
+ * @interface AuthStore
+ * @description 인증 상태 및 관련 메서드 정의
+ * @property {string | null} accessToken - 메모리에 저장된 Access Token
+ * @property {User | null} user - 사용자 정보
+ * @property {boolean} authenticated - 인증 여부
+ * @property {(response: LoginResponse) => void} login - 로그인 처리
+ * @property {() => void} logout - 로그아웃 처리
+ * @property {() => Promise<void>} restoreAuth - 인증 상태 복원
+ */
 interface AuthStore {
   accessToken: string | null;
   user: User | null;
@@ -15,6 +38,10 @@ interface AuthStore {
   restoreAuth: () => void;
 }
 
+/**
+ * @function useAuthStore
+ * @description Zustand 인증 스토어 훅
+ */
 export const useAuthStore = create<AuthStore>()(
   persist(
     (set, get) => ({
@@ -22,9 +49,13 @@ export const useAuthStore = create<AuthStore>()(
       user: null,
       authenticated: false,
 
+      /**
+       * 로그인 처리
+       * - 메모리에 Access Token 저장
+       * - 사용자 정보와 인증 상태 업데이트
+       */
       login: (response) => {
         const { accessToken, ...user } = response;
-        // 메모리에 Access Token 저장 (client.ts)
         setAccessToken(accessToken);
         set({
           accessToken,
@@ -33,8 +64,12 @@ export const useAuthStore = create<AuthStore>()(
         });
       },
 
+      /**
+       * 로그아웃 처리
+       * - 메모리에서 Access Token 제거
+       * - 사용자 정보 및 인증 상태 초기화
+       */
       logout: () => {
-        // 메모리에서 Access Token 제거
         setAccessToken(null);
         set({
           accessToken: null,
@@ -43,9 +78,14 @@ export const useAuthStore = create<AuthStore>()(
         });
       },
 
+      /**
+       * 인증 상태 복원
+       * - localStorage에서 사용자 정보와 인증 상태 확인
+       * - refresh token으로 새 Access Token 발급 시도
+       * - 실패 시 로그아웃 처리
+       */
       restoreAuth: async () => {
         const state = get();
-        // localStorage에 인증 상태가 있으면 refresh token으로 새 access token 발급
         if (state.authenticated && state.user) {
           try {
             const newAccessToken = await refreshTokenApi();
@@ -53,7 +93,6 @@ export const useAuthStore = create<AuthStore>()(
             set({ accessToken: newAccessToken });
           } catch (error) {
             console.error("Failed to restore auth:", error);
-            // refresh token도 만료된 경우 로그아웃
             set({
               accessToken: null,
               user: null,
@@ -66,8 +105,7 @@ export const useAuthStore = create<AuthStore>()(
     {
       name: "auth-storage",
       partialize: (state) => ({
-        // 보안을 위해 토큰은 localStorage에 저장하지 않음
-        // accessToken: state.accessToken,
+        // 보안을 위해 Access Token은 localStorage에 저장하지 않음
         user: state.user,
         authenticated: state.authenticated,
       }),
diff --git a/src/domains/login/types/circle.ts b/src/domains/login/types/circle.ts
index a5a37df..779149f 100644
--- a/src/domains/login/types/circle.ts
+++ b/src/domains/login/types/circle.ts
@@ -1,4 +1,20 @@
+/**
+ * @author 구희원
+ * @description Circle 컴포넌트 관련 타입 정의
+ */
+
+/**
+ * @typedef CircleSize
+ * @description Circle의 크기 옵션
+ * @type {"small" | "medium"}
+ */
 export type CircleSize = "small" | "medium";
+
+/**
+ * @typedef CircleGradient
+ * @description Circle의 색상 그라디언트 옵션
+ * @type {"blue" | "purple" | "orange" | "yellow" | "pink" | "green"}
+ */
 export type CircleGradient =
   | "blue"
   | "purple"
@@ -7,6 +23,14 @@ export type CircleGradient =
   | "pink"
   | "green";
 
+/**
+ * @interface CircleConfig
+ * @description Circle 컴포넌트 렌더링을 위한 설정 객체
+ * @property {string} id - Circle 고유 식별자
+ * @property {CircleSize} size - Circle 크기
+ * @property {CircleGradient} gradient - Circle 색상 그라디언트
+ * @property {string} position - Circle 위치(CSS position 클래스)
+ */
 export interface CircleConfig {
   id: string;
   size: CircleSize;
diff --git a/src/domains/login/types/login.ts b/src/domains/login/types/login.ts
index b543511..0e5771b 100644
--- a/src/domains/login/types/login.ts
+++ b/src/domains/login/types/login.ts
@@ -1,8 +1,30 @@
+/**
+ * @author 구희원
+ * @description 로그인 요청/응답 타입 정의
+ */
+
+/**
+ * @interface LoginRequest
+ * @description 로그인 API 호출 시 전송하는 데이터
+ * @property {string} userName - 사용자 아이디
+ * @property {string} password - 비밀번호
+ */
 export interface LoginRequest {
   userName: string;
   password: string;
 }
 
+/**
+ * @interface LoginResponse
+ * @description 로그인 API 응답 데이터
+ * @property {string} accessToken - 인증용 액세스 토큰
+ * @property {number} id - 사용자 고유 ID
+ * @property {string} userName - 사용자 아이디
+ * @property {string} name - 사용자 이름
+ * @property {string} role - 사용자 역할
+ * @property {string} companyName - 소속 회사 이름
+ * @property {number} [companyId] - 소속 회사 ID (선택)
+ */
 export interface LoginResponse {
   accessToken: string;
   id: number;

From 337757372385c561615213c324283741805e7089 Mon Sep 17 00:00:00 2001
From: HeHelee <selly3109@naver.com>
Date: Fri, 28 Nov 2025 11:57:09 +0900
Subject: [PATCH 4/5] =?UTF-8?q?feat:=20=EC=A3=BC=EC=84=9D=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/domains/login/api/refreshApi.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/domains/login/api/refreshApi.ts b/src/domains/login/api/refreshApi.ts
index b43aa98..1ee2418 100644
--- a/src/domains/login/api/refreshApi.ts
+++ b/src/domains/login/api/refreshApi.ts
@@ -1,5 +1,5 @@
 /**
- * @author 구희원
+ * @author 김대호
  * @description Access Token 갱신 API 호출 유틸리티
  *
  * - 서버에 Refresh Token 기반 요청

From f0301b3f752f7b07509c1e9e3fba500b92ad22bf Mon Sep 17 00:00:00 2001
From: HeHelee <selly3109@naver.com>
Date: Fri, 28 Nov 2025 12:03:36 +0900
Subject: [PATCH 5/5] =?UTF-8?q?chore:=20=EC=A3=BC=EC=84=9D=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/domains/login/api/loginApi.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/domains/login/api/loginApi.ts b/src/domains/login/api/loginApi.ts
index 9ee5f74..ddae8cf 100644
--- a/src/domains/login/api/loginApi.ts
+++ b/src/domains/login/api/loginApi.ts
@@ -1,5 +1,5 @@
 /**
- * @author 김대호
+ * @author 김대호 구희원
  * @description 로그인 API - 사용자 인증을 처리하는 API 호출
  * 아이디와 비밀번호를 서버로 전송하여 인증 토큰 및 사용자 정보 반환
  * 응답은 API 표준 형식(status_code, status_message, result)을 따름