From 4dbb55f6e11c547a8ac487ef2db608eb5db2490a Mon Sep 17 00:00:00 2001
From: dohyeons <ddhhss0603@gmail.com>
Date: Tue, 14 Oct 2025 10:29:56 +0900
Subject: [PATCH 1/6] =?UTF-8?q?=EB=8B=AC=EB=A0=A5=20=EC=9C=84=EC=A0=AF=20?=
 =?UTF-8?q?=EA=B5=AC=ED=98=84=20md=ED=8C=8C=EC=9D=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../admin/dashboard/CALENDAR_WIDGET_PLAN.md   | 228 ++++++++++++++++++
 1 file changed, 228 insertions(+)
 create mode 100644 frontend/components/admin/dashboard/CALENDAR_WIDGET_PLAN.md

diff --git a/frontend/components/admin/dashboard/CALENDAR_WIDGET_PLAN.md b/frontend/components/admin/dashboard/CALENDAR_WIDGET_PLAN.md
new file mode 100644
index 00000000..84f2a4dc
--- /dev/null
+++ b/frontend/components/admin/dashboard/CALENDAR_WIDGET_PLAN.md
@@ -0,0 +1,228 @@
+# 📅 달력 위젯 구현 계획
+
+## 개요
+
+대시보드에 추가할 수 있는 달력 위젯을 구현합니다. 사용자가 날짜를 확인하고 일정을 관리할 수 있는 인터랙티브한 달력 기능을 제공합니다.
+
+## 주요 기능
+
+### 1. 달력 뷰 타입
+
+- **월간 뷰**: 한 달 전체를 보여주는 기본 뷰
+- **주간 뷰**: 일주일을 세로로 보여주는 뷰
+- **일간 뷰**: 하루의 시간대별 일정 뷰
+
+### 2. 달력 설정
+
+- **시작 요일**: 월요일 시작 / 일요일 시작 선택
+- **주말 강조**: 주말 색상 다르게 표시
+- **오늘 날짜 강조**: 오늘 날짜 하이라이트
+- **공휴일 표시**: 한국 공휴일 표시 (선택 사항)
+
+### 3. 테마 및 스타일
+
+- **Light 테마**: 밝은 배경
+- **Dark 테마**: 어두운 배경
+- **사용자 지정**: 커스텀 색상 선택
+
+### 4. 일정 기능 (향후 확장)
+
+- 간단한 메모 추가
+- 일정 표시 (외부 연동)
+
+## 구현 단계
+
+### ✅ Step 1: 타입 정의
+
+- [ ] `CalendarConfig` 인터페이스 정의
+- [ ] `types.ts`에 달력 설정 타입 추가
+- [ ] 요소 타입에 'calendar' subtype 추가
+
+### ✅ Step 2: 기본 달력 컴포넌트
+
+- [ ] `CalendarWidget.tsx` - 메인 위젯 컴포넌트
+- [ ] `MonthView.tsx` - 월간 달력 뷰
+- [ ] `WeekView.tsx` - 주간 달력 뷰 (선택)
+- [ ] 날짜 계산 유틸리티 함수
+
+### ✅ Step 3: 달력 네비게이션
+
+- [ ] 이전/다음 월 이동 버튼
+- [ ] 오늘로 돌아가기 버튼
+- [ ] 월/연도 선택 드롭다운
+
+### ✅ Step 4: 설정 UI
+
+- [ ] `CalendarSettings.tsx` - Popover 내장 설정 컴포넌트
+- [ ] 뷰 타입 선택 (월간/주간/일간)
+- [ ] 시작 요일 설정
+- [ ] 테마 선택
+- [ ] 표시 옵션 (주말 강조, 공휴일 등)
+
+### ✅ Step 5: 스타일링
+
+- [ ] 달력 그리드 레이아웃
+- [ ] 날짜 셀 디자인
+- [ ] 오늘 날짜 하이라이트
+- [ ] 주말/평일 구분
+- [ ] 반응형 디자인 (크기별 최적화)
+
+### ✅ Step 6: 통합
+
+- [ ] `DashboardSidebar`에 달력 위젯 추가
+- [ ] `CanvasElement`에서 달력 위젯 렌더링
+- [ ] `DashboardDesigner`에 기본값 설정
+
+### ✅ Step 7: 공휴일 데이터
+
+- [ ] 한국 공휴일 데이터 정의
+- [ ] 공휴일 표시 기능
+- [ ] 공휴일 이름 툴팁
+
+### ✅ Step 8: 테스트 및 최적화
+
+- [ ] 다양한 크기에서 테스트
+- [ ] 날짜 계산 로직 검증
+- [ ] 성능 최적화
+- [ ] 접근성 개선
+
+## 기술 스택
+
+### UI 컴포넌트
+
+- **shadcn/ui**: Button, Select, Switch, Popover, Card
+- **lucide-react**: Settings, ChevronLeft, ChevronRight, Calendar
+
+### 날짜 처리
+
+- **JavaScript Date API**: 기본 날짜 계산
+- **Intl.DateTimeFormat**: 날짜 형식화
+- 외부 라이브러리 없이 순수 구현
+
+### 스타일링
+
+- **Tailwind CSS**: 반응형 그리드 레이아웃
+- **CSS Grid**: 달력 레이아웃
+
+## 컴포넌트 구조
+
+```
+widgets/
+├── CalendarWidget.tsx       # 메인 위젯 (설정 버튼 포함)
+├── CalendarSettings.tsx     # 설정 UI (Popover 내부)
+├── MonthView.tsx           # 월간 뷰
+├── WeekView.tsx            # 주간 뷰 (선택)
+├── DayView.tsx             # 일간 뷰 (선택)
+└── calendarUtils.ts        # 날짜 계산 유틸리티
+```
+
+## 데이터 구조
+
+```typescript
+interface CalendarConfig {
+  view: "month" | "week" | "day"; // 뷰 타입
+  startWeekOn: "monday" | "sunday"; // 주 시작 요일
+  highlightWeekends: boolean; // 주말 강조
+  highlightToday: boolean; // 오늘 강조
+  showHolidays: boolean; // 공휴일 표시
+  theme: "light" | "dark" | "custom"; // 테마
+  customColor?: string; // 사용자 지정 색상
+  showWeekNumbers?: boolean; // 주차 표시 (선택)
+}
+```
+
+## UI/UX 고려사항
+
+### 반응형 디자인
+
+- **2x2**: 미니 달력 (월간 뷰만, 날짜만 표시)
+- **3x3**: 기본 달력 (월간 뷰, 요일 헤더 포함)
+- **4x4 이상**: 풀 달력 (모든 기능, 일정 표시 가능)
+
+### 인터랙션
+
+- 날짜 클릭 시 해당 날짜 정보 표시 (선택)
+- 드래그로 월 변경 (선택)
+- 키보드 네비게이션 지원
+
+### 접근성
+
+- 날짜 셀에 적절한 aria-label
+- 키보드 네비게이션 지원
+- 스크린 리더 호환
+
+## 공휴일 데이터 구조
+
+```typescript
+interface Holiday {
+  date: string; // 'MM-DD' 형식
+  name: string; // 공휴일 이름
+  isRecurring: boolean; // 매년 반복 여부
+}
+
+// 2025년 한국 공휴일 예시
+const KOREAN_HOLIDAYS: Holiday[] = [
+  { date: "01-01", name: "신정", isRecurring: true },
+  { date: "01-28", name: "설날 연휴", isRecurring: false },
+  { date: "01-29", name: "설날", isRecurring: false },
+  { date: "01-30", name: "설날 연휴", isRecurring: false },
+  { date: "03-01", name: "삼일절", isRecurring: true },
+  { date: "05-05", name: "어린이날", isRecurring: true },
+  { date: "06-06", name: "현충일", isRecurring: true },
+  { date: "08-15", name: "광복절", isRecurring: true },
+  { date: "10-03", name: "개천절", isRecurring: true },
+  { date: "10-09", name: "한글날", isRecurring: true },
+  { date: "12-25", name: "크리스마스", isRecurring: true },
+];
+```
+
+## 향후 확장 기능
+
+### Phase 2 (선택)
+
+- [ ] 일정 추가/수정/삭제
+- [ ] 반복 일정 설정
+- [ ] 카테고리별 색상 구분
+- [ ] 다른 달력 서비스 연동 (Google Calendar, Outlook 등)
+- [ ] 일정 알림 기능
+- [ ] 드래그 앤 드롭으로 일정 이동
+
+### Phase 3 (선택)
+
+- [ ] 여러 달력 레이어 지원
+- [ ] 일정 검색 기능
+- [ ] 월별 통계 (일정 개수 등)
+- [ ] CSV/iCal 내보내기
+
+## 참고사항
+
+### 장점
+
+- 순수 JavaScript로 구현 (외부 의존성 최소화)
+- shadcn/ui 컴포넌트 활용으로 일관된 디자인
+- 시계 위젯과 동일한 패턴 (내장 설정 UI)
+
+### 주의사항
+
+- 날짜 계산 로직 정확성 검증 필요
+- 윤년 처리
+- 타임존 고려 (필요시)
+- 다양한 크기에서의 가독성
+
+## 완료 기준
+
+- [x] 월간 뷰 달력이 정확하게 표시됨
+- [x] 이전/다음 월 네비게이션이 작동함
+- [x] 오늘 날짜가 하이라이트됨
+- [x] 주말이 다른 색상으로 표시됨
+- [x] 공휴일이 표시되고 이름이 보임
+- [x] 설정 UI에서 모든 옵션을 변경할 수 있음
+- [x] 테마 변경이 즉시 반영됨
+- [x] 2x2 크기에서도 깔끔하게 표시됨
+- [x] 4x4 크기에서 모든 기능이 정상 작동함
+
+---
+
+## 구현 시작
+
+이제 단계별로 구현을 시작합니다!
-- 
2.43.0


From 2311729338eee57f5dd2742ca85c87b66ce11275 Mon Sep 17 00:00:00 2001
From: dohyeons <ddhhss0603@gmail.com>
Date: Tue, 14 Oct 2025 10:48:17 +0900
Subject: [PATCH 2/6] =?UTF-8?q?=EB=8B=AC=EB=A0=A5=20=EC=9C=84=EC=A0=AF=20?=
 =?UTF-8?q?=EA=B5=AC=ED=98=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../admin/dashboard/CALENDAR_WIDGET_PLAN.md   |  60 ++---
 .../admin/dashboard/CanvasElement.tsx         |  57 +++--
 .../admin/dashboard/DashboardDesigner.tsx     |  17 +-
 .../admin/dashboard/DashboardSidebar.tsx      |   8 +
 .../admin/dashboard/ElementConfigModal.tsx    |  39 +---
 frontend/components/admin/dashboard/types.ts  |  16 +-
 .../dashboard/widgets/CalendarSettings.tsx    | 207 ++++++++++++++++++
 .../dashboard/widgets/CalendarWidget.tsx      | 121 ++++++++++
 .../dashboard/widgets/ClockConfigModal.tsx    | 205 -----------------
 .../admin/dashboard/widgets/MonthView.tsx     | 117 ++++++++++
 .../admin/dashboard/widgets/calendarUtils.ts  | 162 ++++++++++++++
 11 files changed, 715 insertions(+), 294 deletions(-)
 create mode 100644 frontend/components/admin/dashboard/widgets/CalendarSettings.tsx
 create mode 100644 frontend/components/admin/dashboard/widgets/CalendarWidget.tsx
 delete mode 100644 frontend/components/admin/dashboard/widgets/ClockConfigModal.tsx
 create mode 100644 frontend/components/admin/dashboard/widgets/MonthView.tsx
 create mode 100644 frontend/components/admin/dashboard/widgets/calendarUtils.ts

diff --git a/frontend/components/admin/dashboard/CALENDAR_WIDGET_PLAN.md b/frontend/components/admin/dashboard/CALENDAR_WIDGET_PLAN.md
index 84f2a4dc..e127be43 100644
--- a/frontend/components/admin/dashboard/CALENDAR_WIDGET_PLAN.md
+++ b/frontend/components/admin/dashboard/CALENDAR_WIDGET_PLAN.md
@@ -34,57 +34,57 @@
 
 ### ✅ Step 1: 타입 정의
 
-- [ ] `CalendarConfig` 인터페이스 정의
-- [ ] `types.ts`에 달력 설정 타입 추가
-- [ ] 요소 타입에 'calendar' subtype 추가
+- [x] `CalendarConfig` 인터페이스 정의
+- [x] `types.ts`에 달력 설정 타입 추가
+- [x] 요소 타입에 'calendar' subtype 추가
 
 ### ✅ Step 2: 기본 달력 컴포넌트
 
-- [ ] `CalendarWidget.tsx` - 메인 위젯 컴포넌트
-- [ ] `MonthView.tsx` - 월간 달력 뷰
-- [ ] `WeekView.tsx` - 주간 달력 뷰 (선택)
-- [ ] 날짜 계산 유틸리티 함수
+- [x] `CalendarWidget.tsx` - 메인 위젯 컴포넌트
+- [x] `MonthView.tsx` - 월간 달력 뷰
+- [x] 날짜 계산 유틸리티 함수 (`calendarUtils.ts`)
+- [ ] `WeekView.tsx` - 주간 달력 뷰 (향후 추가)
 
 ### ✅ Step 3: 달력 네비게이션
 
-- [ ] 이전/다음 월 이동 버튼
-- [ ] 오늘로 돌아가기 버튼
-- [ ] 월/연도 선택 드롭다운
+- [x] 이전/다음 월 이동 버튼
+- [x] 오늘로 돌아가기 버튼
+- [ ] 월/연도 선택 드롭다운 (향후 추가)
 
 ### ✅ Step 4: 설정 UI
 
-- [ ] `CalendarSettings.tsx` - Popover 내장 설정 컴포넌트
-- [ ] 뷰 타입 선택 (월간/주간/일간)
-- [ ] 시작 요일 설정
-- [ ] 테마 선택
-- [ ] 표시 옵션 (주말 강조, 공휴일 등)
+- [x] `CalendarSettings.tsx` - Popover 내장 설정 컴포넌트
+- [x] 뷰 타입 선택 (월간 - 현재 구현)
+- [x] 시작 요일 설정
+- [x] 테마 선택 (light/dark/custom)
+- [x] 표시 옵션 (주말 강조, 공휴일, 오늘 강조)
 
 ### ✅ Step 5: 스타일링
 
-- [ ] 달력 그리드 레이아웃
-- [ ] 날짜 셀 디자인
-- [ ] 오늘 날짜 하이라이트
-- [ ] 주말/평일 구분
-- [ ] 반응형 디자인 (크기별 최적화)
+- [x] 달력 그리드 레이아웃
+- [x] 날짜 셀 디자인
+- [x] 오늘 날짜 하이라이트
+- [x] 주말/평일 구분
+- [x] 반응형 디자인 (크기별 최적화)
 
 ### ✅ Step 6: 통합
 
-- [ ] `DashboardSidebar`에 달력 위젯 추가
-- [ ] `CanvasElement`에서 달력 위젯 렌더링
-- [ ] `DashboardDesigner`에 기본값 설정
+- [x] `DashboardSidebar`에 달력 위젯 추가
+- [x] `CanvasElement`에서 달력 위젯 렌더링
+- [x] `DashboardDesigner`에 기본값 설정
 
 ### ✅ Step 7: 공휴일 데이터
 
-- [ ] 한국 공휴일 데이터 정의
-- [ ] 공휴일 표시 기능
-- [ ] 공휴일 이름 툴팁
+- [x] 한국 공휴일 데이터 정의
+- [x] 공휴일 표시 기능
+- [x] 공휴일 이름 툴팁
 
 ### ✅ Step 8: 테스트 및 최적화
 
-- [ ] 다양한 크기에서 테스트
-- [ ] 날짜 계산 로직 검증
-- [ ] 성능 최적화
-- [ ] 접근성 개선
+- [ ] 다양한 크기에서 테스트 (사용자 테스트 필요)
+- [x] 날짜 계산 로직 검증
+- [ ] 성능 최적화 (필요시)
+- [ ] 접근성 개선 (필요시)
 
 ## 기술 스택
 
diff --git a/frontend/components/admin/dashboard/CanvasElement.tsx b/frontend/components/admin/dashboard/CanvasElement.tsx
index d830263d..aced2eb9 100644
--- a/frontend/components/admin/dashboard/CanvasElement.tsx
+++ b/frontend/components/admin/dashboard/CanvasElement.tsx
@@ -19,6 +19,8 @@ const ExchangeWidget = dynamic(() => import("@/components/dashboard/widgets/Exch
 
 // 시계 위젯 임포트
 import { ClockWidget } from "./widgets/ClockWidget";
+// 달력 위젯 임포트
+import { CalendarWidget } from "./widgets/CalendarWidget";
 
 interface CanvasElementProps {
   element: DashboardElement;
@@ -130,26 +132,30 @@ export function CanvasElement({
         let newX = resizeStart.elementX;
         let newY = resizeStart.elementY;
 
-        const minSize = GRID_CONFIG.CELL_SIZE * 2; // 최소 2셀
+        // 최소 크기 설정: 달력은 2x3, 나머지는 2x2
+        const minWidthCells = 2;
+        const minHeightCells = element.type === "widget" && element.subtype === "calendar" ? 3 : 2;
+        const minWidth = GRID_CONFIG.CELL_SIZE * minWidthCells;
+        const minHeight = GRID_CONFIG.CELL_SIZE * minHeightCells;
 
         switch (resizeStart.handle) {
           case "se": // 오른쪽 아래
-            newWidth = Math.max(minSize, resizeStart.width + deltaX);
-            newHeight = Math.max(minSize, resizeStart.height + deltaY);
+            newWidth = Math.max(minWidth, resizeStart.width + deltaX);
+            newHeight = Math.max(minHeight, resizeStart.height + deltaY);
             break;
           case "sw": // 왼쪽 아래
-            newWidth = Math.max(minSize, resizeStart.width - deltaX);
-            newHeight = Math.max(minSize, resizeStart.height + deltaY);
+            newWidth = Math.max(minWidth, resizeStart.width - deltaX);
+            newHeight = Math.max(minHeight, resizeStart.height + deltaY);
             newX = resizeStart.elementX + deltaX;
             break;
           case "ne": // 오른쪽 위
-            newWidth = Math.max(minSize, resizeStart.width + deltaX);
-            newHeight = Math.max(minSize, resizeStart.height - deltaY);
+            newWidth = Math.max(minWidth, resizeStart.width + deltaX);
+            newHeight = Math.max(minHeight, resizeStart.height - deltaY);
             newY = resizeStart.elementY + deltaY;
             break;
           case "nw": // 왼쪽 위
-            newWidth = Math.max(minSize, resizeStart.width - deltaX);
-            newHeight = Math.max(minSize, resizeStart.height - deltaY);
+            newWidth = Math.max(minWidth, resizeStart.width - deltaX);
+            newHeight = Math.max(minHeight, resizeStart.height - deltaY);
             newX = resizeStart.elementX + deltaX;
             newY = resizeStart.elementY + deltaY;
             break;
@@ -281,6 +287,8 @@ export function CanvasElement({
           return "bg-gradient-to-br from-cyan-400 to-indigo-800";
         case "clock":
           return "bg-gradient-to-br from-teal-400 to-cyan-600";
+        case "calendar":
+          return "bg-gradient-to-br from-indigo-400 to-purple-600";
         default:
           return "bg-gray-200";
       }
@@ -310,16 +318,17 @@ export function CanvasElement({
       <div className="flex cursor-move items-center justify-between border-b border-gray-200 bg-gray-50 p-3">
         <span className="text-sm font-bold text-gray-800">{element.title}</span>
         <div className="flex gap-1">
-          {/* 설정 버튼 (시계 위젯은 자체 설정 UI 사용) */}
-          {onConfigure && !(element.type === "widget" && element.subtype === "clock") && (
-            <button
-              className="hover:bg-accent0 flex h-6 w-6 items-center justify-center rounded text-gray-400 transition-colors duration-200 hover:text-white"
-              onClick={() => onConfigure(element)}
-              title="설정"
-            >
-              ⚙️
-            </button>
-          )}
+          {/* 설정 버튼 (시계, 달력 위젯은 자체 설정 UI 사용) */}
+          {onConfigure &&
+            !(element.type === "widget" && (element.subtype === "clock" || element.subtype === "calendar")) && (
+              <button
+                className="hover:bg-accent0 flex h-6 w-6 items-center justify-center rounded text-gray-400 transition-colors duration-200 hover:text-white"
+                onClick={() => onConfigure(element)}
+                title="설정"
+              >
+                ⚙️
+              </button>
+            )}
           {/* 삭제 버튼 */}
           <button
             className="element-close hover:bg-destructive/100 flex h-6 w-6 items-center justify-center rounded text-gray-400 transition-colors duration-200 hover:text-white"
@@ -376,6 +385,16 @@ export function CanvasElement({
               }}
             />
           </div>
+        ) : element.type === "widget" && element.subtype === "calendar" ? (
+          // 달력 위젯 렌더링
+          <div className="h-full w-full">
+            <CalendarWidget
+              element={element}
+              onConfigUpdate={(newConfig) => {
+                onUpdate(element.id, { calendarConfig: newConfig });
+              }}
+            />
+          </div>
         ) : (
           // 기타 위젯 렌더링
           <div
diff --git a/frontend/components/admin/dashboard/DashboardDesigner.tsx b/frontend/components/admin/dashboard/DashboardDesigner.tsx
index c8feffd4..f88cc588 100644
--- a/frontend/components/admin/dashboard/DashboardDesigner.tsx
+++ b/frontend/components/admin/dashboard/DashboardDesigner.tsx
@@ -79,8 +79,15 @@ export default function DashboardDesigner() {
   // 새로운 요소 생성 (고정 그리드 기반 기본 크기)
   const createElement = useCallback(
     (type: ElementType, subtype: ElementSubtype, x: number, y: number) => {
-      // 기본 크기: 차트는 4x3 셀, 위젯은 2x2 셀
-      const defaultCells = type === "chart" ? { width: 4, height: 3 } : { width: 2, height: 2 };
+      // 기본 크기 설정
+      let defaultCells = { width: 2, height: 2 }; // 기본 위젯 크기
+
+      if (type === "chart") {
+        defaultCells = { width: 4, height: 3 }; // 차트
+      } else if (type === "widget" && subtype === "calendar") {
+        defaultCells = { width: 2, height: 3 }; // 달력 최소 크기
+      }
+
       const cellWithGap = GRID_CONFIG.CELL_SIZE + GRID_CONFIG.GAP;
 
       const defaultWidth = defaultCells.width * cellWithGap - GRID_CONFIG.GAP;
@@ -232,7 +239,7 @@ export default function DashboardDesigner() {
       <div className="relative flex-1 overflow-auto border-r-2 border-gray-300 bg-gray-100">
         {/* 편집 중인 대시보드 표시 */}
         {dashboardTitle && (
-          <div className="bg-accent0 absolute left-6 top-6 z-10 rounded-lg px-3 py-1 text-sm font-medium text-white shadow-lg">
+          <div className="bg-accent0 absolute top-6 left-6 z-10 rounded-lg px-3 py-1 text-sm font-medium text-white shadow-lg">
             📝 편집 중: {dashboardTitle}
           </div>
         )}
@@ -291,6 +298,8 @@ function getElementTitle(type: ElementType, subtype: ElementSubtype): string {
         return "☁️ 날씨 위젯";
       case "clock":
         return "⏰ 시계 위젯";
+      case "calendar":
+        return "📅 달력 위젯";
       default:
         return "🔧 위젯";
     }
@@ -319,6 +328,8 @@ function getElementContent(type: ElementType, subtype: ElementSubtype): string {
         return "서울\n23°C\n구름 많음";
       case "clock":
         return "clock";
+      case "calendar":
+        return "calendar";
       default:
         return "위젯 내용이 여기에 표시됩니다";
     }
diff --git a/frontend/components/admin/dashboard/DashboardSidebar.tsx b/frontend/components/admin/dashboard/DashboardSidebar.tsx
index 41888172..82ce27c3 100644
--- a/frontend/components/admin/dashboard/DashboardSidebar.tsx
+++ b/frontend/components/admin/dashboard/DashboardSidebar.tsx
@@ -111,6 +111,14 @@ export function DashboardSidebar() {
             onDragStart={handleDragStart}
             className="border-l-4 border-teal-500"
           />
+          <DraggableItem
+            icon="📅"
+            title="달력 위젯"
+            type="widget"
+            subtype="calendar"
+            onDragStart={handleDragStart}
+            className="border-l-4 border-indigo-500"
+          />
         </div>
       </div>
     </div>
diff --git a/frontend/components/admin/dashboard/ElementConfigModal.tsx b/frontend/components/admin/dashboard/ElementConfigModal.tsx
index dc9d3f32..31fdee8b 100644
--- a/frontend/components/admin/dashboard/ElementConfigModal.tsx
+++ b/frontend/components/admin/dashboard/ElementConfigModal.tsx
@@ -1,10 +1,9 @@
 "use client";
 
 import React, { useState, useCallback } from "react";
-import { DashboardElement, ChartDataSource, ChartConfig, QueryResult, ClockConfig } from "./types";
+import { DashboardElement, ChartDataSource, ChartConfig, QueryResult } from "./types";
 import { QueryEditor } from "./QueryEditor";
 import { ChartConfigPanel } from "./ChartConfigPanel";
-import { ClockConfigModal } from "./widgets/ClockConfigModal";
 
 interface ElementConfigModalProps {
   element: DashboardElement;
@@ -57,46 +56,14 @@ export function ElementConfigModal({ element, isOpen, onClose, onSave }: Element
     onClose();
   }, [element, dataSource, chartConfig, onSave, onClose]);
 
-  // 시계 위젯 설정 저장
-  const handleClockConfigSave = useCallback(
-    (clockConfig: ClockConfig) => {
-      const updatedElement: DashboardElement = {
-        ...element,
-        clockConfig,
-      };
-      onSave(updatedElement);
-    },
-    [element, onSave],
-  );
-
   // 모달이 열려있지 않으면 렌더링하지 않음
   if (!isOpen) return null;
 
-  // 시계 위젯은 자체 설정 UI를 가지고 있으므로 모달 표시하지 않음
-  if (element.type === "widget" && element.subtype === "clock") {
+  // 시계, 달력 위젯은 자체 설정 UI를 가지고 있으므로 모달 표시하지 않음
+  if (element.type === "widget" && (element.subtype === "clock" || element.subtype === "calendar")) {
     return null;
   }
 
-  // 이전 코드 호환성 유지 (아래 주석 처리된 코드는 제거 예정)
-  if (false && element.type === "widget" && element.subtype === "clock") {
-    return (
-      <ClockConfigModal
-        config={
-          element.clockConfig || {
-            style: "digital",
-            timezone: "Asia/Seoul",
-            showDate: true,
-            showSeconds: true,
-            format24h: true,
-            theme: "light",
-          }
-        }
-        onSave={handleClockConfigSave}
-        onClose={onClose}
-      />
-    );
-  }
-
   return (
     <div className="bg-opacity-50 fixed inset-0 z-50 flex items-center justify-center bg-black">
       <div className="flex h-[80vh] w-full max-w-4xl flex-col rounded-lg bg-white shadow-xl">
diff --git a/frontend/components/admin/dashboard/types.ts b/frontend/components/admin/dashboard/types.ts
index d304c9f3..2ac0bb6d 100644
--- a/frontend/components/admin/dashboard/types.ts
+++ b/frontend/components/admin/dashboard/types.ts
@@ -14,7 +14,8 @@ export type ElementSubtype =
   | "combo" // 차트 타입
   | "exchange"
   | "weather"
-  | "clock"; // 위젯 타입
+  | "clock"
+  | "calendar"; // 위젯 타입
 
 export interface Position {
   x: number;
@@ -37,6 +38,7 @@ export interface DashboardElement {
   dataSource?: ChartDataSource; // 데이터 소스 설정
   chartConfig?: ChartConfig; // 차트 설정
   clockConfig?: ClockConfig; // 시계 설정
+  calendarConfig?: CalendarConfig; // 달력 설정
 }
 
 export interface DragData {
@@ -86,3 +88,15 @@ export interface ClockConfig {
   theme: "light" | "dark" | "custom"; // 테마
   customColor?: string; // 사용자 지정 색상 (custom 테마일 때)
 }
+
+// 달력 위젯 설정
+export interface CalendarConfig {
+  view: "month" | "week" | "day"; // 뷰 타입
+  startWeekOn: "monday" | "sunday"; // 주 시작 요일
+  highlightWeekends: boolean; // 주말 강조
+  highlightToday: boolean; // 오늘 강조
+  showHolidays: boolean; // 공휴일 표시
+  theme: "light" | "dark" | "custom"; // 테마
+  customColor?: string; // 사용자 지정 색상
+  showWeekNumbers?: boolean; // 주차 표시 (선택)
+}
diff --git a/frontend/components/admin/dashboard/widgets/CalendarSettings.tsx b/frontend/components/admin/dashboard/widgets/CalendarSettings.tsx
new file mode 100644
index 00000000..89633cc8
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/CalendarSettings.tsx
@@ -0,0 +1,207 @@
+"use client";
+
+import { useState } from "react";
+import { CalendarConfig } from "../types";
+import { Button } from "@/components/ui/button";
+import { Label } from "@/components/ui/label";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { Input } from "@/components/ui/input";
+import { Card } from "@/components/ui/card";
+import { Separator } from "@/components/ui/separator";
+
+interface CalendarSettingsProps {
+  config: CalendarConfig;
+  onSave: (config: CalendarConfig) => void;
+  onClose: () => void;
+}
+
+/**
+ * 달력 위젯 설정 UI (Popover 내부용)
+ */
+export function CalendarSettings({ config, onSave, onClose }: CalendarSettingsProps) {
+  const [localConfig, setLocalConfig] = useState<CalendarConfig>(config);
+
+  const handleSave = () => {
+    onSave(localConfig);
+  };
+
+  return (
+    <div className="flex max-h-[600px] flex-col">
+      {/* 헤더 */}
+      <div className="border-b p-4">
+        <h3 className="flex items-center gap-2 text-lg font-semibold">
+          <span>📅</span>
+          달력 설정
+        </h3>
+      </div>
+
+      {/* 내용 - 스크롤 가능 */}
+      <div className="flex-1 space-y-4 overflow-y-auto p-4">
+        {/* 뷰 타입 선택 (현재는 month만) */}
+        <div className="space-y-2">
+          <Label className="text-sm font-semibold">뷰 타입</Label>
+          <Select
+            value={localConfig.view}
+            onValueChange={(value) => setLocalConfig({ ...localConfig, view: value as any })}
+          >
+            <SelectTrigger className="w-full" size="sm">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="month">월간 뷰</SelectItem>
+              {/* <SelectItem value="week">주간 뷰 (준비 중)</SelectItem>
+              <SelectItem value="day">일간 뷰 (준비 중)</SelectItem> */}
+            </SelectContent>
+          </Select>
+        </div>
+
+        <Separator />
+
+        {/* 시작 요일 선택 */}
+        <div className="space-y-2">
+          <Label className="text-sm font-semibold">주 시작 요일</Label>
+          <div className="grid grid-cols-2 gap-2">
+            <Button
+              type="button"
+              variant={localConfig.startWeekOn === "sunday" ? "default" : "outline"}
+              onClick={() => setLocalConfig({ ...localConfig, startWeekOn: "sunday" })}
+              size="sm"
+            >
+              일요일
+            </Button>
+            <Button
+              type="button"
+              variant={localConfig.startWeekOn === "monday" ? "default" : "outline"}
+              onClick={() => setLocalConfig({ ...localConfig, startWeekOn: "monday" })}
+              size="sm"
+            >
+              월요일
+            </Button>
+          </div>
+        </div>
+
+        <Separator />
+
+        {/* 테마 선택 */}
+        <div className="space-y-2">
+          <Label className="text-sm font-semibold">테마</Label>
+          <div className="grid grid-cols-3 gap-2">
+            {[
+              {
+                value: "light",
+                label: "Light",
+                gradient: "bg-gradient-to-br from-white to-gray-100",
+                text: "text-gray-900",
+              },
+              {
+                value: "dark",
+                label: "Dark",
+                gradient: "bg-gradient-to-br from-gray-800 to-gray-900",
+                text: "text-white",
+              },
+              {
+                value: "custom",
+                label: "사용자",
+                gradient: "bg-gradient-to-br from-blue-400 to-purple-600",
+                text: "text-white",
+              },
+            ].map((theme) => (
+              <Button
+                key={theme.value}
+                type="button"
+                variant="outline"
+                onClick={() => setLocalConfig({ ...localConfig, theme: theme.value as any })}
+                className={`relative h-auto overflow-hidden p-0 ${
+                  localConfig.theme === theme.value ? "ring-primary ring-2 ring-offset-2" : ""
+                }`}
+                size="sm"
+              >
+                <div className={`${theme.gradient} ${theme.text} w-full rounded px-3 py-2 text-xs font-medium`}>
+                  {theme.label}
+                </div>
+              </Button>
+            ))}
+          </div>
+
+          {/* 사용자 지정 색상 */}
+          {localConfig.theme === "custom" && (
+            <Card className="mt-2 border p-3">
+              <Label className="mb-2 block text-xs font-medium">강조 색상</Label>
+              <div className="flex items-center gap-2">
+                <Input
+                  type="color"
+                  value={localConfig.customColor || "#3b82f6"}
+                  onChange={(e) => setLocalConfig({ ...localConfig, customColor: e.target.value })}
+                  className="h-10 w-16 cursor-pointer"
+                />
+                <Input
+                  type="text"
+                  value={localConfig.customColor || "#3b82f6"}
+                  onChange={(e) => setLocalConfig({ ...localConfig, customColor: e.target.value })}
+                  placeholder="#3b82f6"
+                  className="flex-1 font-mono text-xs"
+                />
+              </div>
+            </Card>
+          )}
+        </div>
+
+        <Separator />
+
+        {/* 표시 옵션 */}
+        <div className="space-y-2">
+          <Label className="text-sm font-semibold">표시 옵션</Label>
+          <div className="space-y-2">
+            {/* 오늘 강조 */}
+            <div className="flex items-center justify-between rounded-lg border p-3">
+              <div className="flex items-center gap-2">
+                <span className="text-lg">📍</span>
+                <Label className="cursor-pointer text-sm">오늘 날짜 강조</Label>
+              </div>
+              <Switch
+                checked={localConfig.highlightToday}
+                onCheckedChange={(checked) => setLocalConfig({ ...localConfig, highlightToday: checked })}
+              />
+            </div>
+
+            {/* 주말 강조 */}
+            <div className="flex items-center justify-between rounded-lg border p-3">
+              <div className="flex items-center gap-2">
+                <span className="text-lg">🎨</span>
+                <Label className="cursor-pointer text-sm">주말 색상 강조</Label>
+              </div>
+              <Switch
+                checked={localConfig.highlightWeekends}
+                onCheckedChange={(checked) => setLocalConfig({ ...localConfig, highlightWeekends: checked })}
+              />
+            </div>
+
+            {/* 공휴일 표시 */}
+            <div className="flex items-center justify-between rounded-lg border p-3">
+              <div className="flex items-center gap-2">
+                <span className="text-lg">🎉</span>
+                <Label className="cursor-pointer text-sm">공휴일 표시</Label>
+              </div>
+              <Switch
+                checked={localConfig.showHolidays}
+                onCheckedChange={(checked) => setLocalConfig({ ...localConfig, showHolidays: checked })}
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* 푸터 */}
+      <div className="flex justify-end gap-2 border-t p-4">
+        <Button variant="outline" size="sm" onClick={onClose}>
+          취소
+        </Button>
+        <Button size="sm" onClick={handleSave}>
+          저장
+        </Button>
+      </div>
+    </div>
+  );
+}
+
diff --git a/frontend/components/admin/dashboard/widgets/CalendarWidget.tsx b/frontend/components/admin/dashboard/widgets/CalendarWidget.tsx
new file mode 100644
index 00000000..4f54ac65
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/CalendarWidget.tsx
@@ -0,0 +1,121 @@
+"use client";
+
+import { useState } from "react";
+import { DashboardElement, CalendarConfig } from "../types";
+import { MonthView } from "./MonthView";
+import { CalendarSettings } from "./CalendarSettings";
+import { generateCalendarDays, getMonthName, navigateMonth } from "./calendarUtils";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { Button } from "@/components/ui/button";
+import { Settings, ChevronLeft, ChevronRight, Calendar } from "lucide-react";
+
+interface CalendarWidgetProps {
+  element: DashboardElement;
+  onConfigUpdate?: (config: CalendarConfig) => void;
+}
+
+/**
+ * 달력 위젯 메인 컴포넌트
+ * - 월간/주간/일간 뷰 지원
+ * - 네비게이션 (이전/다음 월, 오늘)
+ * - 내장 설정 UI
+ */
+export function CalendarWidget({ element, onConfigUpdate }: CalendarWidgetProps) {
+  // 현재 표시 중인 년/월
+  const today = new Date();
+  const [currentYear, setCurrentYear] = useState(today.getFullYear());
+  const [currentMonth, setCurrentMonth] = useState(today.getMonth());
+  const [settingsOpen, setSettingsOpen] = useState(false);
+
+  // 기본 설정값
+  const config = element.calendarConfig || {
+    view: "month",
+    startWeekOn: "sunday",
+    highlightWeekends: true,
+    highlightToday: true,
+    showHolidays: true,
+    theme: "light",
+  };
+
+  // 설정 저장 핸들러
+  const handleSaveSettings = (newConfig: CalendarConfig) => {
+    onConfigUpdate?.(newConfig);
+    setSettingsOpen(false);
+  };
+
+  // 이전 월로 이동
+  const handlePrevMonth = () => {
+    const { year, month } = navigateMonth(currentYear, currentMonth, "prev");
+    setCurrentYear(year);
+    setCurrentMonth(month);
+  };
+
+  // 다음 월로 이동
+  const handleNextMonth = () => {
+    const { year, month } = navigateMonth(currentYear, currentMonth, "next");
+    setCurrentYear(year);
+    setCurrentMonth(month);
+  };
+
+  // 오늘로 돌아가기
+  const handleToday = () => {
+    setCurrentYear(today.getFullYear());
+    setCurrentMonth(today.getMonth());
+  };
+
+  // 달력 날짜 생성
+  const calendarDays = generateCalendarDays(currentYear, currentMonth, config.startWeekOn);
+
+  // 크기에 따른 컴팩트 모드 판단
+  const isCompact = element.size.width < 400 || element.size.height < 400;
+
+  return (
+    <div className="relative flex h-full w-full flex-col">
+      {/* 헤더 - 네비게이션 */}
+      <div className="flex items-center justify-between border-b border-gray-200 p-2">
+        {/* 이전 월 버튼 */}
+        <Button variant="ghost" size="icon" className="h-7 w-7" onClick={handlePrevMonth}>
+          <ChevronLeft className="h-4 w-4" />
+        </Button>
+
+        {/* 현재 년월 표시 */}
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-semibold">
+            {currentYear}년 {getMonthName(currentMonth)}
+          </span>
+          {!isCompact && (
+            <Button variant="outline" size="sm" className="h-6 px-2 text-xs" onClick={handleToday}>
+              오늘
+            </Button>
+          )}
+        </div>
+
+        {/* 다음 월 버튼 */}
+        <Button variant="ghost" size="icon" className="h-7 w-7" onClick={handleNextMonth}>
+          <ChevronRight className="h-4 w-4" />
+        </Button>
+      </div>
+
+      {/* 달력 콘텐츠 */}
+      <div className="flex-1 overflow-hidden">
+        {config.view === "month" && <MonthView days={calendarDays} config={config} isCompact={isCompact} />}
+        {/* 추후 WeekView, DayView 추가 가능 */}
+      </div>
+
+      {/* 설정 버튼 - 우측 하단 */}
+      <div className="absolute bottom-2 right-2">
+        <Popover open={settingsOpen} onOpenChange={setSettingsOpen}>
+          <PopoverTrigger asChild>
+            <Button variant="ghost" size="icon" className="h-8 w-8 bg-white/80 hover:bg-white">
+              <Settings className="h-4 w-4" />
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent className="w-[450px] p-0" align="end">
+            <CalendarSettings config={config} onSave={handleSaveSettings} onClose={() => setSettingsOpen(false)} />
+          </PopoverContent>
+        </Popover>
+      </div>
+    </div>
+  );
+}
+
diff --git a/frontend/components/admin/dashboard/widgets/ClockConfigModal.tsx b/frontend/components/admin/dashboard/widgets/ClockConfigModal.tsx
deleted file mode 100644
index 26067b48..00000000
--- a/frontend/components/admin/dashboard/widgets/ClockConfigModal.tsx
+++ /dev/null
@@ -1,205 +0,0 @@
-"use client";
-
-import { useState } from "react";
-import { ClockConfig } from "../types";
-import { Button } from "@/components/ui/button";
-import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from "@/components/ui/dialog";
-import { Label } from "@/components/ui/label";
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
-import { Switch } from "@/components/ui/switch";
-import { Input } from "@/components/ui/input";
-import { Card } from "@/components/ui/card";
-import { X } from "lucide-react";
-
-interface ClockConfigModalProps {
-  config: ClockConfig;
-  onSave: (config: ClockConfig) => void;
-  onClose: () => void;
-}
-
-/**
- * 시계 위젯 설정 모달
- * - 스타일 선택 (아날로그/디지털/둘다)
- * - 타임존 선택
- * - 테마 선택
- * - 옵션 토글 (날짜, 초, 24시간)
- */
-export function ClockConfigModal({ config, onSave, onClose }: ClockConfigModalProps) {
-  const [localConfig, setLocalConfig] = useState<ClockConfig>(config);
-
-  const handleSave = () => {
-    onSave(localConfig);
-    onClose();
-  };
-
-  return (
-    <Dialog open={true} onOpenChange={onClose}>
-      <DialogContent className="max-h-[90vh] max-w-2xl overflow-hidden p-0">
-        <DialogHeader className="border-b p-6">
-          <DialogTitle className="flex items-center gap-2 text-xl">
-            <span>⏰</span>
-            시계 위젯 설정
-          </DialogTitle>
-        </DialogHeader>
-
-        {/* 내용 - 스크롤 가능 */}
-        <div className="flex-1 space-y-6 overflow-y-auto px-6 py-4">
-          {/* 스타일 선택 */}
-          <div className="space-y-3">
-            <Label className="text-sm font-semibold">시계 스타일</Label>
-            <div className="grid grid-cols-3 gap-3">
-              {[
-                { value: "digital", label: "디지털", icon: "🔢" },
-                { value: "analog", label: "아날로그", icon: "🕐" },
-                { value: "both", label: "둘 다", icon: "⏰" },
-              ].map((style) => (
-                <Button
-                  key={style.value}
-                  type="button"
-                  variant={localConfig.style === style.value ? "default" : "outline"}
-                  onClick={() => setLocalConfig({ ...localConfig, style: style.value as any })}
-                  className="flex h-auto flex-col items-center gap-2 p-4"
-                >
-                  <span className="text-3xl">{style.icon}</span>
-                  <span className="text-sm font-medium">{style.label}</span>
-                </Button>
-              ))}
-            </div>
-          </div>
-
-          {/* 타임존 선택 */}
-          <div className="space-y-3">
-            <Label className="text-sm font-semibold">타임존</Label>
-            <Select
-              value={localConfig.timezone}
-              onValueChange={(value) => setLocalConfig({ ...localConfig, timezone: value })}
-            >
-              <SelectTrigger className="w-full">
-                <SelectValue />
-              </SelectTrigger>
-              <SelectContent>
-                <SelectItem value="Asia/Seoul">🇰🇷 서울 (KST)</SelectItem>
-                <SelectItem value="Asia/Tokyo">🇯🇵 도쿄 (JST)</SelectItem>
-                <SelectItem value="Asia/Shanghai">🇨🇳 베이징 (CST)</SelectItem>
-                <SelectItem value="America/New_York">🇺🇸 뉴욕 (EST)</SelectItem>
-                <SelectItem value="America/Los_Angeles">🇺🇸 LA (PST)</SelectItem>
-                <SelectItem value="Europe/London">🇬🇧 런던 (GMT)</SelectItem>
-                <SelectItem value="Europe/Paris">🇫🇷 파리 (CET)</SelectItem>
-                <SelectItem value="Australia/Sydney">🇦🇺 시드니 (AEDT)</SelectItem>
-              </SelectContent>
-            </Select>
-          </div>
-
-          {/* 테마 선택 */}
-          <div className="space-y-3">
-            <Label className="text-sm font-semibold">테마</Label>
-            <div className="grid grid-cols-3 gap-3">
-              {[
-                {
-                  value: "light",
-                  label: "Light",
-                  gradient: "bg-gradient-to-br from-white to-gray-100",
-                  text: "text-gray-900",
-                },
-                {
-                  value: "dark",
-                  label: "Dark",
-                  gradient: "bg-gradient-to-br from-gray-800 to-gray-900",
-                  text: "text-white",
-                },
-                {
-                  value: "custom",
-                  label: "사용자 지정",
-                  gradient: "bg-gradient-to-br from-blue-400 to-purple-600",
-                  text: "text-white",
-                },
-              ].map((theme) => (
-                <Button
-                  key={theme.value}
-                  type="button"
-                  variant="outline"
-                  onClick={() => setLocalConfig({ ...localConfig, theme: theme.value as any })}
-                  className={`relative h-auto overflow-hidden p-0 ${
-                    localConfig.theme === theme.value ? "ring-primary ring-2 ring-offset-2" : ""
-                  }`}
-                >
-                  <div className={`${theme.gradient} ${theme.text} w-full rounded p-3 text-center text-xs font-medium`}>
-                    {theme.label}
-                  </div>
-                </Button>
-              ))}
-            </div>
-
-            {/* 사용자 지정 색상 선택 */}
-            {localConfig.theme === "custom" && (
-              <Card className="border p-4">
-                <Label className="mb-2 block text-sm font-medium">배경 색상 선택</Label>
-                <div className="flex items-center gap-3">
-                  <Input
-                    type="color"
-                    value={localConfig.customColor || "#3b82f6"}
-                    onChange={(e) => setLocalConfig({ ...localConfig, customColor: e.target.value })}
-                    className="h-12 w-20 cursor-pointer"
-                  />
-                  <div className="flex-1">
-                    <Input
-                      type="text"
-                      value={localConfig.customColor || "#3b82f6"}
-                      onChange={(e) => setLocalConfig({ ...localConfig, customColor: e.target.value })}
-                      placeholder="#3b82f6"
-                      className="font-mono"
-                    />
-                    <p className="text-muted-foreground mt-1 text-xs">시계의 배경색이나 강조색으로 사용됩니다</p>
-                  </div>
-                </div>
-              </Card>
-            )}
-          </div>
-
-          {/* 옵션 토글 */}
-          <div className="space-y-3">
-            <Label className="text-sm font-semibold">표시 옵션</Label>
-            <div className="grid grid-cols-3 gap-3">
-              {/* 날짜 표시 */}
-              <Card className="hover:bg-accent flex cursor-pointer flex-col items-center justify-center border p-4 text-center transition-colors">
-                <span className="mb-2 text-2xl">📅</span>
-                <Label className="mb-1 cursor-pointer text-sm font-medium">날짜 표시</Label>
-                <Switch
-                  checked={localConfig.showDate}
-                  onCheckedChange={(checked) => setLocalConfig({ ...localConfig, showDate: checked })}
-                />
-              </Card>
-
-              {/* 초 표시 */}
-              <Card className="hover:bg-accent flex cursor-pointer flex-col items-center justify-center border p-4 text-center transition-colors">
-                <span className="mb-2 text-2xl">⏱️</span>
-                <Label className="mb-1 cursor-pointer text-sm font-medium">초 표시</Label>
-                <Switch
-                  checked={localConfig.showSeconds}
-                  onCheckedChange={(checked) => setLocalConfig({ ...localConfig, showSeconds: checked })}
-                />
-              </Card>
-
-              {/* 24시간 형식 */}
-              <Card className="hover:bg-accent flex cursor-pointer flex-col items-center justify-center border p-4 text-center transition-colors">
-                <span className="mb-2 text-2xl">🕐</span>
-                <Label className="mb-1 cursor-pointer text-sm font-medium">24시간 형식</Label>
-                <Switch
-                  checked={localConfig.format24h}
-                  onCheckedChange={(checked) => setLocalConfig({ ...localConfig, format24h: checked })}
-                />
-              </Card>
-            </div>
-          </div>
-        </div>
-
-        <DialogFooter className="border-t p-6">
-          <Button variant="outline" onClick={onClose}>
-            취소
-          </Button>
-          <Button onClick={handleSave}>저장</Button>
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
-  );
-}
diff --git a/frontend/components/admin/dashboard/widgets/MonthView.tsx b/frontend/components/admin/dashboard/widgets/MonthView.tsx
new file mode 100644
index 00000000..c0fd3871
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/MonthView.tsx
@@ -0,0 +1,117 @@
+"use client";
+
+import { CalendarConfig } from "../types";
+import { CalendarDay, getWeekDayNames } from "./calendarUtils";
+
+interface MonthViewProps {
+  days: CalendarDay[];
+  config: CalendarConfig;
+  isCompact?: boolean; // 작은 크기 (2x2, 3x3)
+}
+
+/**
+ * 월간 달력 뷰 컴포넌트
+ */
+export function MonthView({ days, config, isCompact = false }: MonthViewProps) {
+  const weekDayNames = getWeekDayNames(config.startWeekOn);
+
+  // 테마별 스타일
+  const getThemeStyles = () => {
+    if (config.theme === "custom" && config.customColor) {
+      return {
+        todayBg: config.customColor,
+        holidayText: config.customColor,
+        weekendText: "#dc2626",
+      };
+    }
+
+    if (config.theme === "dark") {
+      return {
+        todayBg: "#3b82f6",
+        holidayText: "#f87171",
+        weekendText: "#f87171",
+      };
+    }
+
+    // light 테마
+    return {
+      todayBg: "#3b82f6",
+      holidayText: "#dc2626",
+      weekendText: "#dc2626",
+    };
+  };
+
+  const themeStyles = getThemeStyles();
+
+  // 날짜 셀 스타일 클래스
+  const getDayCellClass = (day: CalendarDay) => {
+    const baseClass = "flex aspect-square items-center justify-center rounded-lg transition-colors";
+    const sizeClass = isCompact ? "text-xs" : "text-sm";
+
+    let colorClass = "text-gray-700";
+
+    // 현재 월이 아닌 날짜
+    if (!day.isCurrentMonth) {
+      colorClass = "text-gray-300";
+    }
+    // 오늘
+    else if (config.highlightToday && day.isToday) {
+      colorClass = "text-white font-bold";
+    }
+    // 공휴일
+    else if (config.showHolidays && day.isHoliday) {
+      colorClass = "font-semibold";
+    }
+    // 주말
+    else if (config.highlightWeekends && day.isWeekend) {
+      colorClass = "text-red-600";
+    }
+
+    const bgClass = config.highlightToday && day.isToday ? "" : "hover:bg-gray-100";
+
+    return `${baseClass} ${sizeClass} ${colorClass} ${bgClass}`;
+  };
+
+  return (
+    <div className="flex h-full flex-col p-2">
+      {/* 요일 헤더 */}
+      {!isCompact && (
+        <div className="mb-2 grid grid-cols-7 gap-1">
+          {weekDayNames.map((name, index) => {
+            const isWeekend = config.startWeekOn === "sunday" ? index === 0 || index === 6 : index === 5 || index === 6;
+            return (
+              <div
+                key={name}
+                className={`text-center text-xs font-semibold ${isWeekend && config.highlightWeekends ? "text-red-600" : "text-gray-600"}`}
+              >
+                {name}
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      {/* 날짜 그리드 */}
+      <div className="grid flex-1 grid-cols-7 gap-1">
+        {days.map((day, index) => (
+          <div
+            key={index}
+            className={getDayCellClass(day)}
+            style={{
+              backgroundColor:
+                config.highlightToday && day.isToday ? themeStyles.todayBg : undefined,
+              color:
+                config.showHolidays && day.isHoliday && day.isCurrentMonth
+                  ? themeStyles.holidayText
+                  : undefined,
+            }}
+            title={day.isHoliday ? day.holidayName : undefined}
+          >
+            {day.day}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
diff --git a/frontend/components/admin/dashboard/widgets/calendarUtils.ts b/frontend/components/admin/dashboard/widgets/calendarUtils.ts
new file mode 100644
index 00000000..4bdb8deb
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/calendarUtils.ts
@@ -0,0 +1,162 @@
+/**
+ * 달력 유틸리티 함수
+ */
+
+// 한국 공휴일 데이터 (2025년 기준)
+export interface Holiday {
+  date: string; // 'MM-DD' 형식
+  name: string;
+  isRecurring: boolean;
+}
+
+export const KOREAN_HOLIDAYS: Holiday[] = [
+  { date: "01-01", name: "신정", isRecurring: true },
+  { date: "01-28", name: "설날 연휴", isRecurring: false },
+  { date: "01-29", name: "설날", isRecurring: false },
+  { date: "01-30", name: "설날 연휴", isRecurring: false },
+  { date: "03-01", name: "삼일절", isRecurring: true },
+  { date: "05-05", name: "어린이날", isRecurring: true },
+  { date: "06-06", name: "현충일", isRecurring: true },
+  { date: "08-15", name: "광복절", isRecurring: true },
+  { date: "10-03", name: "개천절", isRecurring: true },
+  { date: "10-09", name: "한글날", isRecurring: true },
+  { date: "12-25", name: "크리스마스", isRecurring: true },
+];
+
+/**
+ * 특정 월의 첫 날 Date 객체 반환
+ */
+export function getFirstDayOfMonth(year: number, month: number): Date {
+  return new Date(year, month, 1);
+}
+
+/**
+ * 특정 월의 마지막 날짜 반환
+ */
+export function getLastDateOfMonth(year: number, month: number): number {
+  return new Date(year, month + 1, 0).getDate();
+}
+
+/**
+ * 특정 월의 첫 날의 요일 반환 (0=일요일, 1=월요일, ...)
+ */
+export function getFirstDayOfWeek(year: number, month: number): number {
+  return new Date(year, month, 1).getDay();
+}
+
+/**
+ * 달력 그리드에 표시할 날짜 배열 생성
+ * @param year 년도
+ * @param month 월 (0-11)
+ * @param startWeekOn 주 시작 요일 ('monday' | 'sunday')
+ * @returns 6주 * 7일 = 42개의 날짜 정보 배열
+ */
+export interface CalendarDay {
+  date: Date;
+  day: number;
+  isCurrentMonth: boolean;
+  isToday: boolean;
+  isWeekend: boolean;
+  isHoliday: boolean;
+  holidayName?: string;
+}
+
+export function generateCalendarDays(
+  year: number,
+  month: number,
+  startWeekOn: "monday" | "sunday" = "sunday",
+): CalendarDay[] {
+  const days: CalendarDay[] = [];
+  const firstDay = getFirstDayOfWeek(year, month);
+  const lastDate = getLastDateOfMonth(year, month);
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+
+  // 시작 오프셋 계산
+  let startOffset = firstDay;
+  if (startWeekOn === "monday") {
+    startOffset = firstDay === 0 ? 6 : firstDay - 1;
+  }
+
+  // 이전 달 날짜들
+  const prevMonthLastDate = getLastDateOfMonth(year, month - 1);
+  for (let i = startOffset - 1; i >= 0; i--) {
+    const date = new Date(year, month - 1, prevMonthLastDate - i);
+    days.push(createCalendarDay(date, false, today));
+  }
+
+  // 현재 달 날짜들
+  for (let day = 1; day <= lastDate; day++) {
+    const date = new Date(year, month, day);
+    days.push(createCalendarDay(date, true, today));
+  }
+
+  // 다음 달 날짜들 (42개 채우기)
+  const remainingDays = 42 - days.length;
+  for (let day = 1; day <= remainingDays; day++) {
+    const date = new Date(year, month + 1, day);
+    days.push(createCalendarDay(date, false, today));
+  }
+
+  return days;
+}
+
+/**
+ * CalendarDay 객체 생성
+ */
+function createCalendarDay(date: Date, isCurrentMonth: boolean, today: Date): CalendarDay {
+  const dayOfWeek = date.getDay();
+  const isToday = date.getTime() === today.getTime();
+  const isWeekend = dayOfWeek === 0 || dayOfWeek === 6;
+
+  // 공휴일 체크
+  const monthStr = String(date.getMonth() + 1).padStart(2, "0");
+  const dayStr = String(date.getDate()).padStart(2, "0");
+  const dateKey = `${monthStr}-${dayStr}`;
+  const holiday = KOREAN_HOLIDAYS.find((h) => h.date === dateKey);
+
+  return {
+    date,
+    day: date.getDate(),
+    isCurrentMonth,
+    isToday,
+    isWeekend,
+    isHoliday: !!holiday,
+    holidayName: holiday?.name,
+  };
+}
+
+/**
+ * 요일 이름 배열 반환
+ */
+export function getWeekDayNames(startWeekOn: "monday" | "sunday" = "sunday"): string[] {
+  const sundayFirst = ["일", "월", "화", "수", "목", "금", "토"];
+  const mondayFirst = ["월", "화", "수", "목", "금", "토", "일"];
+  return startWeekOn === "monday" ? mondayFirst : sundayFirst;
+}
+
+/**
+ * 월 이름 반환
+ */
+export function getMonthName(month: number): string {
+  const months = ["1월", "2월", "3월", "4월", "5월", "6월", "7월", "8월", "9월", "10월", "11월", "12월"];
+  return months[month];
+}
+
+/**
+ * 이전/다음 월로 이동
+ */
+export function navigateMonth(year: number, month: number, direction: "prev" | "next"): { year: number; month: number } {
+  if (direction === "prev") {
+    if (month === 0) {
+      return { year: year - 1, month: 11 };
+    }
+    return { year, month: month - 1 };
+  } else {
+    if (month === 11) {
+      return { year: year + 1, month: 0 };
+    }
+    return { year, month: month + 1 };
+  }
+}
+
-- 
2.43.0


From 0d4b985d5aad1eaec64f9a3fed0a8eff8206ed4c Mon Sep 17 00:00:00 2001
From: dohyeons <ddhhss0603@gmail.com>
Date: Tue, 14 Oct 2025 11:26:53 +0900
Subject: [PATCH 3/6] =?UTF-8?q?=EA=B8=B0=EC=82=AC=20=EA=B4=80=EB=A6=AC=20?=
 =?UTF-8?q?=EC=9C=84=EC=A0=AF=20=EA=B5=AC=ED=98=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../admin/dashboard/CanvasElement.tsx         |  21 +-
 .../DRIVER_MANAGEMENT_WIDGET_PLAN.md          | 345 ++++++++++++++++++
 .../admin/dashboard/DashboardDesigner.tsx     |   6 +-
 .../admin/dashboard/DashboardSidebar.tsx      |   8 +
 .../admin/dashboard/ElementConfigModal.tsx    |   9 +-
 frontend/components/admin/dashboard/types.ts  |  31 +-
 .../dashboard/widgets/DriverListView.tsx      | 161 ++++++++
 .../widgets/DriverManagementSettings.tsx      | 195 ++++++++++
 .../widgets/DriverManagementWidget.tsx        | 159 ++++++++
 .../admin/dashboard/widgets/driverMockData.ts | 181 +++++++++
 .../admin/dashboard/widgets/driverUtils.ts    | 256 +++++++++++++
 11 files changed, 1365 insertions(+), 7 deletions(-)
 create mode 100644 frontend/components/admin/dashboard/DRIVER_MANAGEMENT_WIDGET_PLAN.md
 create mode 100644 frontend/components/admin/dashboard/widgets/DriverListView.tsx
 create mode 100644 frontend/components/admin/dashboard/widgets/DriverManagementSettings.tsx
 create mode 100644 frontend/components/admin/dashboard/widgets/DriverManagementWidget.tsx
 create mode 100644 frontend/components/admin/dashboard/widgets/driverMockData.ts
 create mode 100644 frontend/components/admin/dashboard/widgets/driverUtils.ts

diff --git a/frontend/components/admin/dashboard/CanvasElement.tsx b/frontend/components/admin/dashboard/CanvasElement.tsx
index 393f3141..589edb0f 100644
--- a/frontend/components/admin/dashboard/CanvasElement.tsx
+++ b/frontend/components/admin/dashboard/CanvasElement.tsx
@@ -26,6 +26,8 @@ const CalculatorWidget = dynamic(() => import("@/components/dashboard/widgets/Ca
 import { ClockWidget } from "./widgets/ClockWidget";
 // 달력 위젯 임포트
 import { CalendarWidget } from "./widgets/CalendarWidget";
+// 기사 관리 위젯 임포트
+import { DriverManagementWidget } from "./widgets/DriverManagementWidget";
 
 interface CanvasElementProps {
   element: DashboardElement;
@@ -294,6 +296,8 @@ export function CanvasElement({
           return "bg-gradient-to-br from-teal-400 to-cyan-600";
         case "calendar":
           return "bg-gradient-to-br from-indigo-400 to-purple-600";
+        case "driver-management":
+          return "bg-gradient-to-br from-blue-400 to-indigo-600";
         default:
           return "bg-gray-200";
       }
@@ -323,9 +327,12 @@ export function CanvasElement({
       <div className="flex cursor-move items-center justify-between border-b border-gray-200 bg-gray-50 p-3">
         <span className="text-sm font-bold text-gray-800">{element.title}</span>
         <div className="flex gap-1">
-          {/* 설정 버튼 (시계, 달력 위젯은 자체 설정 UI 사용) */}
+          {/* 설정 버튼 (시계, 달력, 기사관리 위젯은 자체 설정 UI 사용) */}
           {onConfigure &&
-            !(element.type === "widget" && (element.subtype === "clock" || element.subtype === "calendar")) && (
+            !(
+              element.type === "widget" &&
+              (element.subtype === "clock" || element.subtype === "calendar" || element.subtype === "driver-management")
+            ) && (
               <button
                 className="hover:bg-accent0 flex h-6 w-6 items-center justify-center rounded text-gray-400 transition-colors duration-200 hover:text-white"
                 onClick={() => onConfigure(element)}
@@ -405,6 +412,16 @@ export function CanvasElement({
               }}
             />
           </div>
+        ) : element.type === "widget" && element.subtype === "driver-management" ? (
+          // 기사 관리 위젯 렌더링
+          <div className="h-full w-full">
+            <DriverManagementWidget
+              element={element}
+              onConfigUpdate={(newConfig) => {
+                onUpdate(element.id, { driverManagementConfig: newConfig });
+              }}
+            />
+          </div>
         ) : (
           // 기타 위젯 렌더링
           <div
diff --git a/frontend/components/admin/dashboard/DRIVER_MANAGEMENT_WIDGET_PLAN.md b/frontend/components/admin/dashboard/DRIVER_MANAGEMENT_WIDGET_PLAN.md
new file mode 100644
index 00000000..e1643fd1
--- /dev/null
+++ b/frontend/components/admin/dashboard/DRIVER_MANAGEMENT_WIDGET_PLAN.md
@@ -0,0 +1,345 @@
+# 기사 관리 위젯 구현 계획
+
+## 개요
+
+대시보드에 추가할 수 있는 기사 관리 위젯을 구현합니다. 실시간으로 기사와 차량의 운행 상태를 확인하고 관리할 수 있는 기능을 제공합니다.
+
+## 주요 기능
+
+### 1. 기사 정보 표시
+
+- **차량 번호**: 예) 12가 3456
+- **기사 이름**: 예) 홍길동
+- **출발지**: 예) 서울시 강남구
+- **목적지**: 예) 경기도 성남시
+- **차량 유형**: 예) 1톤 트럭, 2.5톤 트럭, 5톤 트럭, 카고, 탑차, 냉동차 등
+- **운행 상태**: 대기중, 운행중, 휴식중, 점검중
+- **연락처**: 기사 전화번호
+- **운행 시작 시간**: 출발 시간
+- **예상 도착 시간**: 목적지 도착 예정 시간
+
+### 2. 운행 상태 구분
+
+- **대기중** (회색): 출발지/목적지가 없는 상태
+- **운행중** (초록색): 출발지/목적지가 있고 운행 중
+- **휴식중** (주황색): 휴게 중
+- **점검중** (빨간색): 차량 점검 또는 수리 중
+
+### 3. 뷰 타입
+
+- **리스트 뷰**: 테이블 형식으로 전체 기사 목록 표시
+- **맵 뷰** (향후 확장): 지도에 기사 위치 표시
+
+### 4. 필터링 및 검색
+
+- **상태별 필터**: 운행중, 대기중, 휴식중, 점검중
+- **차량 유형별 필터**: 1톤, 2.5톤, 5톤 등
+- **검색**: 기사 이름, 차량 번호로 검색
+
+### 5. 정렬 기능
+
+- 기사 이름순
+- 차량 번호순
+- 출발 시간순
+- 운행 상태별
+
+### 6. 설정 옵션
+
+- **뷰 타입**: 리스트
+- **자동 새로고침**: 실시간 데이터 갱신 (10초, 30초, 1분)
+- **표시 항목**: 사용자가 원하는 컬럼만 표시
+- **테마**: Light, Dark, 사용자 지정
+
+## 데이터 구조
+
+```typescript
+interface DriverInfo {
+  id: string; // 기사 고유 ID
+  name: string; // 기사 이름
+  vehicleNumber: string; // 차량 번호
+  vehicleType: string; // 차량 유형
+  phone: string; // 연락처
+  status: "standby" | "driving" | "resting" | "maintenance"; // 운행 상태
+  departure?: string; // 출발지 (운행 중일 때)
+  destination?: string; // 목적지 (운행 중일 때)
+  departureTime?: string; // 출발 시간
+  estimatedArrival?: string; // 예상 도착 시간
+  progress?: number; // 운행 진행률 (0-100)
+}
+```
+
+## 목업 데이터
+
+```typescript
+const MOCK_DRIVERS: DriverInfo[] = [
+  {
+    id: "DRV001",
+    name: "홍길동",
+    vehicleNumber: "12가 3456",
+    vehicleType: "1톤 트럭",
+    phone: "010-1234-5678",
+    status: "driving",
+    departure: "서울시 강남구",
+    destination: "경기도 성남시",
+    departureTime: "2025-10-14T09:00:00",
+    estimatedArrival: "2025-10-14T11:30:00",
+    progress: 65,
+  },
+  {
+    id: "DRV002",
+    name: "김철수",
+    vehicleNumber: "34나 7890",
+    vehicleType: "2.5톤 트럭",
+    phone: "010-2345-6789",
+    status: "standby",
+  },
+  {
+    id: "DRV003",
+    name: "이영희",
+    vehicleNumber: "56다 1234",
+    vehicleType: "5톤 트럭",
+    phone: "010-3456-7890",
+    status: "driving",
+    departure: "인천광역시",
+    destination: "충청남도 천안시",
+    departureTime: "2025-10-14T08:30:00",
+    estimatedArrival: "2025-10-14T10:00:00",
+    progress: 85,
+  },
+  {
+    id: "DRV004",
+    name: "박민수",
+    vehicleNumber: "78라 5678",
+    vehicleType: "카고",
+    phone: "010-4567-8901",
+    status: "resting",
+  },
+  {
+    id: "DRV005",
+    name: "정수진",
+    vehicleNumber: "90마 9012",
+    vehicleType: "냉동차",
+    phone: "010-5678-9012",
+    status: "maintenance",
+  },
+];
+```
+
+## 구현 단계
+
+### ✅ Step 1: 타입 정의
+
+- [x] `DriverManagementConfig` 인터페이스 정의
+- [x] `DriverInfo` 인터페이스 정의
+- [x] `types.ts`에 기사 관리 설정 타입 추가
+- [x] 요소 타입에 'driver-management' subtype 추가
+
+### ✅ Step 2: 목업 데이터 생성
+
+- [x] `driverMockData.ts` - 기사 목업 데이터 생성
+- [x] 다양한 운행 상태의 샘플 데이터 (15개)
+- [x] 차량 유형별 샘플 데이터
+
+### ✅ Step 3: 유틸리티 함수
+
+- [x] `driverUtils.ts` - 기사 관리 유틸리티 함수
+- [x] 운행 상태별 색상 반환
+- [x] 진행률 계산
+- [x] 시간 포맷팅
+- [x] 필터링/정렬 로직
+
+### ✅ Step 4: 리스트 뷰 컴포넌트
+
+- [x] `DriverListView.tsx` - 테이블 형식 리스트 뷰
+- [x] 상태별 색상 구분
+- [x] 정렬 기능 (유틸리티에서 처리)
+- [x] 반응형 테이블 디자인 (컴팩트 모드 포함)
+
+### ✅ Step 5: 카드 뷰 컴포넌트
+
+- [x] 카드 뷰는 현재 구현하지 않음 (리스트 뷰만 사용)
+- [ ] `DriverCardView.tsx` - 향후 추가 예정
+
+### ✅ Step 6: 메인 위젯 컴포넌트
+
+- [x] `DriverManagementWidget.tsx` - 메인 위젯
+- [x] 리스트 뷰 표시
+- [x] 필터링 UI (상태별)
+- [x] 검색 기능
+- [x] 자동 새로고침 (시뮬레이션)
+
+### ✅ Step 7: 설정 UI
+
+- [x] `DriverManagementSettings.tsx` - 설정 컴포넌트
+- [x] 자동 새로고침 간격 설정
+- [x] 표시 컬럼 선택
+- [x] 테마 설정
+- [x] 정렬 기준 설정
+
+### ✅ Step 8: 통합
+
+- [x] `DashboardSidebar`에 기사 관리 위젯 추가
+- [x] `CanvasElement`에서 기사 관리 위젯 렌더링
+- [x] `DashboardDesigner`에 기본값 설정
+- [x] `ElementConfigModal`에 예외 처리 추가
+
+### ✅ Step 9: 스타일링 및 최적화
+
+- [ ] 반응형 디자인 (다양한 위젯 크기 대응)
+- [ ] 컴팩트 모드 (작은 크기)
+- [ ] 로딩 상태 처리
+- [ ] 빈 데이터 상태 처리
+
+### ✅ Step 10: 향후 확장 기능
+
+- [ ] 실제 REST API 연동
+- [ ] 웹소켓을 통한 실시간 업데이트
+- [ ] 맵 뷰 (지도에 기사 위치 표시)
+- [ ] 기사별 상세 정보 모달
+- [ ] 운행 이력 조회
+- [ ] 알림 기능 (지연, 긴급 상황 등)
+
+## 위젯 크기별 최적화
+
+### 2x2 (최소 크기)
+
+- 요약 정보만 표시 (운행중 기사 수, 대기 기사 수)
+- 간단한 상태 표시
+
+### 3x3
+
+- 카드 뷰 (2-3개 기사 표시)
+- 기본 정보 표시
+
+### 4x3 이상 (권장)
+
+- 리스트 뷰 또는 카드 뷰 전체 표시
+- 필터링 및 검색 기능
+- 모든 정보 표시
+
+## 완료 기준
+
+- [x] 기본 타입 정의 완료
+- [x] 목업 데이터 생성 완료
+- [x] 리스트 뷰 구현 완료
+- [ ] 카드 뷰 구현 완료 (향후 추가)
+- [x] 필터링/검색 기능 구현 완료
+- [x] 설정 UI 구현 완료
+- [x] 대시보드 통합 완료
+- [ ] 다양한 크기에서 테스트 완료 (사용자 테스트 필요)
+
+## 주의사항
+
+1. **성능 최적화**: 많은 기사 데이터를 처리할 때 가상 스크롤링 고려
+2. **실시간 업데이트**: 자동 새로고침 시 부드러운 전환 애니메이션
+3. **접근성**: 키보드 네비게이션 지원
+4. **에러 처리**: API 연동 시 에러 상태 처리
+5. **반응형**: 작은 크기에서도 정보가 잘 보이도록 디자인
+
+## 추가 개선 사항 제안
+
+### 1. 통계 정보
+
+- 오늘 총 운행 건수
+- 평균 운행 시간
+- 차량 유형별 운행 통계
+
+### 2. 긴급 상황 알림
+
+- 운행 지연 알림 (예상 시간 초과)
+- 차량 점검 필요 알림
+- 기사 연락 두절 알림
+
+### 3. 배차 관리 (고급 기능)
+
+- 대기 중인 기사에게 배차
+- 운행 스케줄 관리
+- 경로 최적화 제안
+
+### 4. 보고서 기능
+
+- 일일 운행 보고서
+- 기사별 운행 실적
+- 차량별 가동률
+
+---
+
+## 🎯 구현 우선순위
+
+1. **필수 (Phase 1)**
+   - 타입 정의
+   - 목업 데이터
+   - 리스트 뷰
+   - 기본 필터링
+
+2. **중요 (Phase 2)**
+   - 카드 뷰
+   - 검색 기능
+   - 설정 UI
+   - 자동 새로고침
+
+3. **추가 (Phase 3)**
+   - 통계 정보
+   - 상세 정보 모달
+   - 운행 이력
+
+4. **향후 (Phase 4)**
+   - 맵 뷰
+   - 실시간 위치 추적
+   - 배차 관리
+   - 보고서 기능
+
+---
+
+**구현 시작일**: 2025-10-14
+**구현 완료일**: 2025-10-14
+**현재 진행률**: 90% (카드 뷰 및 최종 테스트 제외)
+
+## 🎉 구현 완료!
+
+기사 관리 위젯의 핵심 기능이 모두 구현되었습니다!
+
+### ✅ 구현된 기능
+
+1. **데이터 구조**
+   - DriverInfo, DriverManagementConfig 타입 정의
+   - 15개의 다양한 목업 데이터
+   - 6가지 차량 유형 지원
+
+2. **리스트 뷰**
+   - 테이블 형식의 깔끔한 UI
+   - 상태별 색상 구분 (운행중/대기중/휴식중/점검중)
+   - 컴팩트 모드 지원 (2x2 크기)
+
+3. **필터링 및 검색**
+   - 상태별 필터 (전체/운행중/대기중/휴식중/점검중)
+   - 기사명, 차량번호 검색
+   - 실시간 필터링
+
+4. **정렬 기능**
+   - 기사명, 차량번호, 운행상태, 출발시간 기준 정렬
+   - 오름차순/내림차순 지원
+
+5. **자동 새로고침**
+   - 10초/30초/1분/5분 간격 설정 가능
+   - 실시간 데이터 시뮬레이션
+
+6. **설정 UI**
+   - Popover 방식의 직관적인 설정
+   - 표시 컬럼 선택 (9개 컬럼)
+   - 테마 설정 (Light/Dark/Custom)
+   - 정렬 기준 및 순서 설정
+
+7. **대시보드 통합**
+   - 사이드바에 드래그 가능한 위젯 추가
+   - 캔버스에서 자유로운 배치 및 크기 조절
+   - 설정 저장 및 불러오기
+
+### 🚀 향후 개선 사항
+
+- 카드 뷰 구현
+- 맵 뷰 (지도 연동)
+- 실제 REST API 연동
+- 웹소켓 실시간 업데이트
+- 통계 정보 추가
+- 배차 관리 기능
diff --git a/frontend/components/admin/dashboard/DashboardDesigner.tsx b/frontend/components/admin/dashboard/DashboardDesigner.tsx
index e0f5a325..3dd939f4 100644
--- a/frontend/components/admin/dashboard/DashboardDesigner.tsx
+++ b/frontend/components/admin/dashboard/DashboardDesigner.tsx
@@ -239,7 +239,7 @@ export default function DashboardDesigner() {
       <div className="relative flex-1 overflow-auto border-r-2 border-gray-300 bg-gray-100">
         {/* 편집 중인 대시보드 표시 */}
         {dashboardTitle && (
-          <div className="bg-accent0 absolute top-6 left-6 z-10 rounded-lg px-3 py-1 text-sm font-medium text-white shadow-lg">
+          <div className="bg-accent0 absolute left-6 top-6 z-10 rounded-lg px-3 py-1 text-sm font-medium text-white shadow-lg">
             📝 편집 중: {dashboardTitle}
           </div>
         )}
@@ -302,6 +302,8 @@ function getElementTitle(type: ElementType, subtype: ElementSubtype): string {
         return "🧮 계산기 위젯";
       case "calendar":
         return "📅 달력 위젯";
+      case "driver-management":
+        return "🚚 기사 관리 위젯";
       default:
         return "🔧 위젯";
     }
@@ -334,6 +336,8 @@ function getElementContent(type: ElementType, subtype: ElementSubtype): string {
         return "calculator";
       case "calendar":
         return "calendar";
+      case "driver-management":
+        return "driver-management";
       default:
         return "위젯 내용이 여기에 표시됩니다";
     }
diff --git a/frontend/components/admin/dashboard/DashboardSidebar.tsx b/frontend/components/admin/dashboard/DashboardSidebar.tsx
index 7946815d..ee8fa13d 100644
--- a/frontend/components/admin/dashboard/DashboardSidebar.tsx
+++ b/frontend/components/admin/dashboard/DashboardSidebar.tsx
@@ -127,6 +127,14 @@ export function DashboardSidebar() {
             onDragStart={handleDragStart}
             className="border-l-4 border-indigo-500"
           />
+          <DraggableItem
+            icon="🚚"
+            title="기사 관리 위젯"
+            type="widget"
+            subtype="driver-management"
+            onDragStart={handleDragStart}
+            className="border-l-4 border-blue-500"
+          />
         </div>
       </div>
     </div>
diff --git a/frontend/components/admin/dashboard/ElementConfigModal.tsx b/frontend/components/admin/dashboard/ElementConfigModal.tsx
index 31fdee8b..8bcacd2c 100644
--- a/frontend/components/admin/dashboard/ElementConfigModal.tsx
+++ b/frontend/components/admin/dashboard/ElementConfigModal.tsx
@@ -59,13 +59,16 @@ export function ElementConfigModal({ element, isOpen, onClose, onSave }: Element
   // 모달이 열려있지 않으면 렌더링하지 않음
   if (!isOpen) return null;
 
-  // 시계, 달력 위젯은 자체 설정 UI를 가지고 있으므로 모달 표시하지 않음
-  if (element.type === "widget" && (element.subtype === "clock" || element.subtype === "calendar")) {
+  // 시계, 달력, 기사관리 위젯은 자체 설정 UI를 가지고 있으므로 모달 표시하지 않음
+  if (
+    element.type === "widget" &&
+    (element.subtype === "clock" || element.subtype === "calendar" || element.subtype === "driver-management")
+  ) {
     return null;
   }
 
   return (
-    <div className="bg-opacity-50 fixed inset-0 z-50 flex items-center justify-center bg-black">
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-50">
       <div className="flex h-[80vh] w-full max-w-4xl flex-col rounded-lg bg-white shadow-xl">
         {/* 모달 헤더 */}
         <div className="flex items-center justify-between border-b border-gray-200 p-6">
diff --git a/frontend/components/admin/dashboard/types.ts b/frontend/components/admin/dashboard/types.ts
index 2e753d1b..6d01fc01 100644
--- a/frontend/components/admin/dashboard/types.ts
+++ b/frontend/components/admin/dashboard/types.ts
@@ -16,7 +16,8 @@ export type ElementSubtype =
   | "weather"
   | "clock"
   | "calendar"
-  | "calculator"; // 위젯 타입
+  | "calculator"
+  | "driver-management"; // 위젯 타입
 
 export interface Position {
   x: number;
@@ -40,6 +41,7 @@ export interface DashboardElement {
   chartConfig?: ChartConfig; // 차트 설정
   clockConfig?: ClockConfig; // 시계 설정
   calendarConfig?: CalendarConfig; // 달력 설정
+  driverManagementConfig?: DriverManagementConfig; // 기사 관리 설정
 }
 
 export interface DragData {
@@ -101,3 +103,30 @@ export interface CalendarConfig {
   customColor?: string; // 사용자 지정 색상
   showWeekNumbers?: boolean; // 주차 표시 (선택)
 }
+
+// 기사 관리 위젯 설정
+export interface DriverManagementConfig {
+  viewType: "list"; // 뷰 타입 (현재는 리스트만)
+  autoRefreshInterval: number; // 자동 새로고침 간격 (초)
+  visibleColumns: string[]; // 표시할 컬럼 목록
+  theme: "light" | "dark" | "custom"; // 테마
+  customColor?: string; // 사용자 지정 색상
+  statusFilter: "all" | "driving" | "standby" | "resting" | "maintenance"; // 상태 필터
+  sortBy: "name" | "vehicleNumber" | "status" | "departureTime"; // 정렬 기준
+  sortOrder: "asc" | "desc"; // 정렬 순서
+}
+
+// 기사 정보
+export interface DriverInfo {
+  id: string; // 기사 고유 ID
+  name: string; // 기사 이름
+  vehicleNumber: string; // 차량 번호
+  vehicleType: string; // 차량 유형
+  phone: string; // 연락처
+  status: "standby" | "driving" | "resting" | "maintenance"; // 운행 상태
+  departure?: string; // 출발지
+  destination?: string; // 목적지
+  departureTime?: string; // 출발 시간
+  estimatedArrival?: string; // 예상 도착 시간
+  progress?: number; // 운행 진행률 (0-100)
+}
diff --git a/frontend/components/admin/dashboard/widgets/DriverListView.tsx b/frontend/components/admin/dashboard/widgets/DriverListView.tsx
new file mode 100644
index 00000000..f5df6944
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/DriverListView.tsx
@@ -0,0 +1,161 @@
+"use client";
+
+import React from "react";
+import { DriverInfo, DriverManagementConfig } from "../types";
+import { getStatusColor, getStatusLabel, formatTime, COLUMN_LABELS } from "./driverUtils";
+import { Progress } from "@/components/ui/progress";
+
+interface DriverListViewProps {
+  drivers: DriverInfo[];
+  config: DriverManagementConfig;
+  isCompact?: boolean; // 작은 크기 (2x2 등)
+}
+
+export function DriverListView({ drivers, config, isCompact = false }: DriverListViewProps) {
+  const { visibleColumns } = config;
+
+  // 컴팩트 모드: 요약 정보만 표시
+  if (isCompact) {
+    const stats = {
+      driving: drivers.filter((d) => d.status === "driving").length,
+      standby: drivers.filter((d) => d.status === "standby").length,
+      resting: drivers.filter((d) => d.status === "resting").length,
+      maintenance: drivers.filter((d) => d.status === "maintenance").length,
+    };
+
+    return (
+      <div className="flex h-full flex-col items-center justify-center space-y-3 p-4">
+        <div className="text-center">
+          <div className="text-3xl font-bold text-gray-900">{drivers.length}</div>
+          <div className="text-sm text-gray-600">전체 기사</div>
+        </div>
+        <div className="grid w-full grid-cols-2 gap-2 text-center text-xs">
+          <div className="rounded-lg bg-green-100 p-2">
+            <div className="font-semibold text-green-800">{stats.driving}</div>
+            <div className="text-green-600">운행중</div>
+          </div>
+          <div className="rounded-lg bg-gray-100 p-2">
+            <div className="font-semibold text-gray-800">{stats.standby}</div>
+            <div className="text-gray-600">대기중</div>
+          </div>
+          <div className="rounded-lg bg-orange-100 p-2">
+            <div className="font-semibold text-orange-800">{stats.resting}</div>
+            <div className="text-orange-600">휴식중</div>
+          </div>
+          <div className="rounded-lg bg-red-100 p-2">
+            <div className="font-semibold text-red-800">{stats.maintenance}</div>
+            <div className="text-red-600">점검중</div>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // 빈 데이터 처리
+  if (drivers.length === 0) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-gray-500">조회된 기사 정보가 없습니다</div>
+    );
+  }
+
+  return (
+    <div className="h-full w-full overflow-auto">
+      <table className="min-w-full divide-y divide-gray-200">
+        <thead className="sticky top-0 z-10 bg-gray-50">
+          <tr>
+            {visibleColumns.includes("status") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.status}</th>
+            )}
+            {visibleColumns.includes("name") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.name}</th>
+            )}
+            {visibleColumns.includes("vehicleNumber") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.vehicleNumber}</th>
+            )}
+            {visibleColumns.includes("vehicleType") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.vehicleType}</th>
+            )}
+            {visibleColumns.includes("departure") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.departure}</th>
+            )}
+            {visibleColumns.includes("destination") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.destination}</th>
+            )}
+            {visibleColumns.includes("departureTime") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.departureTime}</th>
+            )}
+            {visibleColumns.includes("estimatedArrival") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">
+                {COLUMN_LABELS.estimatedArrival}
+              </th>
+            )}
+            {visibleColumns.includes("phone") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.phone}</th>
+            )}
+            {visibleColumns.includes("progress") && (
+              <th className="px-3 py-2 text-left text-xs font-semibold text-gray-700">{COLUMN_LABELS.progress}</th>
+            )}
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-gray-200 bg-white">
+          {drivers.map((driver) => {
+            const statusColors = getStatusColor(driver.status);
+            return (
+              <tr key={driver.id} className="transition-colors hover:bg-gray-50">
+                {visibleColumns.includes("status") && (
+                  <td className="px-3 py-2">
+                    <span
+                      className={`inline-flex items-center rounded-full px-2 py-1 text-xs font-medium ${statusColors.bg} ${statusColors.text}`}
+                    >
+                      {getStatusLabel(driver.status)}
+                    </span>
+                  </td>
+                )}
+                {visibleColumns.includes("name") && (
+                  <td className="px-3 py-2 text-sm font-medium text-gray-900">{driver.name}</td>
+                )}
+                {visibleColumns.includes("vehicleNumber") && (
+                  <td className="px-3 py-2 text-sm text-gray-700">{driver.vehicleNumber}</td>
+                )}
+                {visibleColumns.includes("vehicleType") && (
+                  <td className="px-3 py-2 text-sm text-gray-600">{driver.vehicleType}</td>
+                )}
+                {visibleColumns.includes("departure") && (
+                  <td className="px-3 py-2 text-sm text-gray-700">
+                    {driver.departure || <span className="text-gray-400">-</span>}
+                  </td>
+                )}
+                {visibleColumns.includes("destination") && (
+                  <td className="px-3 py-2 text-sm text-gray-700">
+                    {driver.destination || <span className="text-gray-400">-</span>}
+                  </td>
+                )}
+                {visibleColumns.includes("departureTime") && (
+                  <td className="px-3 py-2 text-sm text-gray-600">{formatTime(driver.departureTime)}</td>
+                )}
+                {visibleColumns.includes("estimatedArrival") && (
+                  <td className="px-3 py-2 text-sm text-gray-600">{formatTime(driver.estimatedArrival)}</td>
+                )}
+                {visibleColumns.includes("phone") && (
+                  <td className="px-3 py-2 text-sm text-gray-600">{driver.phone}</td>
+                )}
+                {visibleColumns.includes("progress") && (
+                  <td className="px-3 py-2">
+                    {driver.progress !== undefined ? (
+                      <div className="flex items-center space-x-2">
+                        <Progress value={driver.progress} className="h-2 w-16" />
+                        <span className="text-xs text-gray-600">{driver.progress}%</span>
+                      </div>
+                    ) : (
+                      <span className="text-gray-400">-</span>
+                    )}
+                  </td>
+                )}
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/frontend/components/admin/dashboard/widgets/DriverManagementSettings.tsx b/frontend/components/admin/dashboard/widgets/DriverManagementSettings.tsx
new file mode 100644
index 00000000..a77dfda5
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/DriverManagementSettings.tsx
@@ -0,0 +1,195 @@
+"use client";
+
+import { useState } from "react";
+import { DriverManagementConfig } from "../types";
+import { Button } from "@/components/ui/button";
+import { Label } from "@/components/ui/label";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { Input } from "@/components/ui/input";
+import { Card } from "@/components/ui/card";
+import { COLUMN_LABELS, DEFAULT_VISIBLE_COLUMNS } from "./driverUtils";
+
+interface DriverManagementSettingsProps {
+  config: DriverManagementConfig;
+  onSave: (config: DriverManagementConfig) => void;
+  onClose: () => void;
+}
+
+export function DriverManagementSettings({ config, onSave, onClose }: DriverManagementSettingsProps) {
+  const [localConfig, setLocalConfig] = useState<DriverManagementConfig>(config);
+
+  const handleSave = () => {
+    onSave(localConfig);
+  };
+
+  // 컬럼 토글
+  const toggleColumn = (column: string) => {
+    const newColumns = localConfig.visibleColumns.includes(column)
+      ? localConfig.visibleColumns.filter((c) => c !== column)
+      : [...localConfig.visibleColumns, column];
+    setLocalConfig({ ...localConfig, visibleColumns: newColumns });
+  };
+
+  return (
+    <div className="flex h-full max-h-[600px] flex-col overflow-hidden">
+      <div className="flex-1 space-y-6 overflow-y-auto p-6">
+        {/* 자동 새로고침 */}
+        <div className="space-y-3">
+          <Label className="text-sm font-semibold">자동 새로고침</Label>
+          <Select
+            value={String(localConfig.autoRefreshInterval)}
+            onValueChange={(value) => setLocalConfig({ ...localConfig, autoRefreshInterval: parseInt(value) })}
+          >
+            <SelectTrigger className="w-full">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="0">사용 안 함</SelectItem>
+              <SelectItem value="10">10초마다</SelectItem>
+              <SelectItem value="30">30초마다</SelectItem>
+              <SelectItem value="60">1분마다</SelectItem>
+              <SelectItem value="300">5분마다</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+
+        {/* 정렬 설정 */}
+        <div className="space-y-3">
+          <Label className="text-sm font-semibold">정렬 기준</Label>
+          <div className="grid grid-cols-2 gap-3">
+            <Select
+              value={localConfig.sortBy}
+              onValueChange={(value) =>
+                setLocalConfig({ ...localConfig, sortBy: value as DriverManagementConfig["sortBy"] })
+              }
+            >
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="name">기사명</SelectItem>
+                <SelectItem value="vehicleNumber">차량번호</SelectItem>
+                <SelectItem value="status">운행상태</SelectItem>
+                <SelectItem value="departureTime">출발시간</SelectItem>
+              </SelectContent>
+            </Select>
+
+            <Select
+              value={localConfig.sortOrder}
+              onValueChange={(value) =>
+                setLocalConfig({ ...localConfig, sortOrder: value as DriverManagementConfig["sortOrder"] })
+              }
+            >
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="asc">오름차순</SelectItem>
+                <SelectItem value="desc">내림차순</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+        </div>
+
+        {/* 테마 설정 */}
+        <div className="space-y-3">
+          <Label className="text-sm font-semibold">테마</Label>
+          <div className="grid grid-cols-3 gap-3">
+            <Button
+              type="button"
+              variant={localConfig.theme === "light" ? "default" : "outline"}
+              className="w-full"
+              onClick={() => setLocalConfig({ ...localConfig, theme: "light" })}
+            >
+              ☀️ Light
+            </Button>
+            <Button
+              type="button"
+              variant={localConfig.theme === "dark" ? "default" : "outline"}
+              className="w-full"
+              onClick={() => setLocalConfig({ ...localConfig, theme: "dark" })}
+            >
+              🌙 Dark
+            </Button>
+            <Button
+              type="button"
+              variant={localConfig.theme === "custom" ? "default" : "outline"}
+              className="w-full"
+              onClick={() => setLocalConfig({ ...localConfig, theme: "custom" })}
+            >
+              🎨 Custom
+            </Button>
+          </div>
+
+          {/* 사용자 지정 색상 */}
+          {localConfig.theme === "custom" && (
+            <Card className="border p-4">
+              <Label className="mb-2 block text-sm font-medium">배경 색상 선택</Label>
+              <div className="flex items-center gap-3">
+                <Input
+                  type="color"
+                  value={localConfig.customColor || "#3b82f6"}
+                  onChange={(e) => setLocalConfig({ ...localConfig, customColor: e.target.value })}
+                  className="h-12 w-20 cursor-pointer"
+                />
+                <div className="flex-1">
+                  <Input
+                    type="text"
+                    value={localConfig.customColor || "#3b82f6"}
+                    onChange={(e) => setLocalConfig({ ...localConfig, customColor: e.target.value })}
+                    placeholder="#3b82f6"
+                    className="font-mono"
+                  />
+                  <p className="text-muted-foreground mt-1 text-xs">테이블 배경색으로 사용됩니다</p>
+                </div>
+              </div>
+            </Card>
+          )}
+        </div>
+
+        {/* 표시 컬럼 선택 */}
+        <div className="space-y-3">
+          <div className="flex items-center justify-between">
+            <Label className="text-sm font-semibold">표시 컬럼</Label>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              onClick={() => setLocalConfig({ ...localConfig, visibleColumns: DEFAULT_VISIBLE_COLUMNS })}
+            >
+              기본값으로
+            </Button>
+          </div>
+          <div className="grid grid-cols-2 gap-2">
+            {Object.entries(COLUMN_LABELS).map(([key, label]) => (
+              <Card
+                key={key}
+                className={`cursor-pointer border p-3 transition-colors ${
+                  localConfig.visibleColumns.includes(key) ? "border-primary bg-primary/5" : "hover:bg-gray-50"
+                }`}
+                onClick={() => toggleColumn(key)}
+              >
+                <div className="flex items-center justify-between">
+                  <Label className="cursor-pointer text-sm font-medium">{label}</Label>
+                  <Switch
+                    checked={localConfig.visibleColumns.includes(key)}
+                    onCheckedChange={() => toggleColumn(key)}
+                  />
+                </div>
+              </Card>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      {/* 푸터 - 고정 */}
+      <div className="flex flex-shrink-0 justify-end gap-3 border-t border-gray-200 bg-gray-50 p-4">
+        <Button variant="outline" onClick={onClose}>
+          취소
+        </Button>
+        <Button onClick={handleSave}>저장</Button>
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/components/admin/dashboard/widgets/DriverManagementWidget.tsx b/frontend/components/admin/dashboard/widgets/DriverManagementWidget.tsx
new file mode 100644
index 00000000..60d5c615
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/DriverManagementWidget.tsx
@@ -0,0 +1,159 @@
+"use client";
+
+import React, { useState, useEffect } from "react";
+import { DashboardElement, DriverManagementConfig, DriverInfo } from "../types";
+import { DriverListView } from "./DriverListView";
+import { DriverManagementSettings } from "./DriverManagementSettings";
+import { MOCK_DRIVERS } from "./driverMockData";
+import { filterDrivers, sortDrivers, DEFAULT_VISIBLE_COLUMNS } from "./driverUtils";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Settings, Search, RefreshCw } from "lucide-react";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+
+interface DriverManagementWidgetProps {
+  element: DashboardElement;
+  onConfigUpdate?: (config: DriverManagementConfig) => void;
+}
+
+export function DriverManagementWidget({ element, onConfigUpdate }: DriverManagementWidgetProps) {
+  const [drivers, setDrivers] = useState<DriverInfo[]>(MOCK_DRIVERS);
+  const [searchTerm, setSearchTerm] = useState("");
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [lastRefresh, setLastRefresh] = useState(new Date());
+
+  // 기본 설정
+  const config = element.driverManagementConfig || {
+    viewType: "list",
+    autoRefreshInterval: 30,
+    visibleColumns: DEFAULT_VISIBLE_COLUMNS,
+    theme: "light",
+    statusFilter: "all",
+    sortBy: "name",
+    sortOrder: "asc",
+  };
+
+  // 자동 새로고침
+  useEffect(() => {
+    if (config.autoRefreshInterval <= 0) return;
+
+    const interval = setInterval(() => {
+      // 실제 환경에서는 API 호출
+      setDrivers(MOCK_DRIVERS);
+      setLastRefresh(new Date());
+    }, config.autoRefreshInterval * 1000);
+
+    return () => clearInterval(interval);
+  }, [config.autoRefreshInterval]);
+
+  // 수동 새로고침
+  const handleRefresh = () => {
+    setDrivers(MOCK_DRIVERS);
+    setLastRefresh(new Date());
+  };
+
+  // 설정 저장
+  const handleSaveSettings = (newConfig: DriverManagementConfig) => {
+    onConfigUpdate?.(newConfig);
+    setSettingsOpen(false);
+  };
+
+  // 필터링 및 정렬
+  const filteredDrivers = sortDrivers(
+    filterDrivers(drivers, config.statusFilter, searchTerm),
+    config.sortBy,
+    config.sortOrder,
+  );
+
+  // 컴팩트 모드 판단 (위젯 크기가 작을 때)
+  const isCompact = element.size.width < 400 || element.size.height < 300;
+
+  return (
+    <div className="relative flex h-full w-full flex-col bg-white">
+      {/* 헤더 - 컴팩트 모드가 아닐 때만 표시 */}
+      {!isCompact && (
+        <div className="flex-shrink-0 border-b border-gray-200 bg-gray-50 px-3 py-2">
+          <div className="flex items-center justify-between gap-2">
+            {/* 검색 */}
+            <div className="relative max-w-xs flex-1">
+              <Search className="absolute left-2 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-gray-400" />
+              <Input
+                type="text"
+                placeholder="기사명, 차량번호 검색"
+                value={searchTerm}
+                onChange={(e) => setSearchTerm(e.target.value)}
+                className="h-8 pl-8 text-xs"
+              />
+            </div>
+
+            {/* 상태 필터 */}
+            <Select
+              value={config.statusFilter}
+              onValueChange={(value) => {
+                onConfigUpdate?.({
+                  ...config,
+                  statusFilter: value as DriverManagementConfig["statusFilter"],
+                });
+              }}
+            >
+              <SelectTrigger className="h-8 w-24 text-xs">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="all">전체</SelectItem>
+                <SelectItem value="driving">운행중</SelectItem>
+                <SelectItem value="standby">대기중</SelectItem>
+                <SelectItem value="resting">휴식중</SelectItem>
+                <SelectItem value="maintenance">점검중</SelectItem>
+              </SelectContent>
+            </Select>
+
+            {/* 새로고침 버튼 */}
+            <Button variant="ghost" size="icon" className="h-8 w-8" onClick={handleRefresh}>
+              <RefreshCw className="h-4 w-4" />
+            </Button>
+
+            {/* 설정 버튼 */}
+            <Popover open={settingsOpen} onOpenChange={setSettingsOpen}>
+              <PopoverTrigger asChild>
+                <Button variant="ghost" size="icon" className="h-8 w-8">
+                  <Settings className="h-4 w-4" />
+                </Button>
+              </PopoverTrigger>
+              <PopoverContent className="w-[500px] p-0" align="end">
+                <DriverManagementSettings
+                  config={config}
+                  onSave={handleSaveSettings}
+                  onClose={() => setSettingsOpen(false)}
+                />
+              </PopoverContent>
+            </Popover>
+          </div>
+
+          {/* 통계 정보 */}
+          <div className="mt-2 flex items-center gap-3 text-xs text-gray-600">
+            <span>
+              전체 <span className="font-semibold text-gray-900">{filteredDrivers.length}</span>명
+            </span>
+            <span className="text-gray-400">|</span>
+            <span>
+              운행중{" "}
+              <span className="font-semibold text-green-600">
+                {filteredDrivers.filter((d) => d.status === "driving").length}
+              </span>
+              명
+            </span>
+            <span className="text-gray-400">|</span>
+            <span className="text-xs text-gray-500">최근 업데이트: {lastRefresh.toLocaleTimeString("ko-KR")}</span>
+          </div>
+        </div>
+      )}
+
+      {/* 리스트 뷰 */}
+      <div className="flex-1 overflow-hidden">
+        <DriverListView drivers={filteredDrivers} config={config} isCompact={isCompact} />
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/components/admin/dashboard/widgets/driverMockData.ts b/frontend/components/admin/dashboard/widgets/driverMockData.ts
new file mode 100644
index 00000000..85271e16
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/driverMockData.ts
@@ -0,0 +1,181 @@
+import { DriverInfo } from "../types";
+
+/**
+ * 기사 관리 목업 데이터
+ * 실제 환경에서는 REST API로 대체됨
+ */
+export const MOCK_DRIVERS: DriverInfo[] = [
+  {
+    id: "DRV001",
+    name: "홍길동",
+    vehicleNumber: "12가 3456",
+    vehicleType: "1톤 트럭",
+    phone: "010-1234-5678",
+    status: "driving",
+    departure: "서울시 강남구",
+    destination: "경기도 성남시",
+    departureTime: "2025-10-14T09:00:00",
+    estimatedArrival: "2025-10-14T11:30:00",
+    progress: 65,
+  },
+  {
+    id: "DRV002",
+    name: "김철수",
+    vehicleNumber: "34나 7890",
+    vehicleType: "2.5톤 트럭",
+    phone: "010-2345-6789",
+    status: "standby",
+  },
+  {
+    id: "DRV003",
+    name: "이영희",
+    vehicleNumber: "56다 1234",
+    vehicleType: "5톤 트럭",
+    phone: "010-3456-7890",
+    status: "driving",
+    departure: "인천광역시",
+    destination: "충청남도 천안시",
+    departureTime: "2025-10-14T08:30:00",
+    estimatedArrival: "2025-10-14T10:00:00",
+    progress: 85,
+  },
+  {
+    id: "DRV004",
+    name: "박민수",
+    vehicleNumber: "78라 5678",
+    vehicleType: "카고",
+    phone: "010-4567-8901",
+    status: "resting",
+  },
+  {
+    id: "DRV005",
+    name: "정수진",
+    vehicleNumber: "90마 9012",
+    vehicleType: "냉동차",
+    phone: "010-5678-9012",
+    status: "maintenance",
+  },
+  {
+    id: "DRV006",
+    name: "최동욱",
+    vehicleNumber: "11아 3344",
+    vehicleType: "1톤 트럭",
+    phone: "010-6789-0123",
+    status: "driving",
+    departure: "부산광역시",
+    destination: "울산광역시",
+    departureTime: "2025-10-14T07:45:00",
+    estimatedArrival: "2025-10-14T09:15:00",
+    progress: 92,
+  },
+  {
+    id: "DRV007",
+    name: "강미선",
+    vehicleNumber: "22자 5566",
+    vehicleType: "탑차",
+    phone: "010-7890-1234",
+    status: "standby",
+  },
+  {
+    id: "DRV008",
+    name: "윤성호",
+    vehicleNumber: "33차 7788",
+    vehicleType: "2.5톤 트럭",
+    phone: "010-8901-2345",
+    status: "driving",
+    departure: "대전광역시",
+    destination: "세종특별자치시",
+    departureTime: "2025-10-14T10:20:00",
+    estimatedArrival: "2025-10-14T11:00:00",
+    progress: 45,
+  },
+  {
+    id: "DRV009",
+    name: "장혜진",
+    vehicleNumber: "44카 9900",
+    vehicleType: "냉동차",
+    phone: "010-9012-3456",
+    status: "resting",
+  },
+  {
+    id: "DRV010",
+    name: "임태양",
+    vehicleNumber: "55타 1122",
+    vehicleType: "5톤 트럭",
+    phone: "010-0123-4567",
+    status: "driving",
+    departure: "광주광역시",
+    destination: "전라남도 목포시",
+    departureTime: "2025-10-14T06:30:00",
+    estimatedArrival: "2025-10-14T08:45:00",
+    progress: 78,
+  },
+  {
+    id: "DRV011",
+    name: "오준석",
+    vehicleNumber: "66파 3344",
+    vehicleType: "카고",
+    phone: "010-1111-2222",
+    status: "standby",
+  },
+  {
+    id: "DRV012",
+    name: "한소희",
+    vehicleNumber: "77하 5566",
+    vehicleType: "1톤 트럭",
+    phone: "010-2222-3333",
+    status: "maintenance",
+  },
+  {
+    id: "DRV013",
+    name: "송민재",
+    vehicleNumber: "88거 7788",
+    vehicleType: "탑차",
+    phone: "010-3333-4444",
+    status: "driving",
+    departure: "경기도 수원시",
+    destination: "경기도 평택시",
+    departureTime: "2025-10-14T09:50:00",
+    estimatedArrival: "2025-10-14T11:20:00",
+    progress: 38,
+  },
+  {
+    id: "DRV014",
+    name: "배수지",
+    vehicleNumber: "99너 9900",
+    vehicleType: "2.5톤 트럭",
+    phone: "010-4444-5555",
+    status: "driving",
+    departure: "강원도 춘천시",
+    destination: "강원도 원주시",
+    departureTime: "2025-10-14T08:00:00",
+    estimatedArrival: "2025-10-14T09:30:00",
+    progress: 72,
+  },
+  {
+    id: "DRV015",
+    name: "신동엽",
+    vehicleNumber: "00더 1122",
+    vehicleType: "5톤 트럭",
+    phone: "010-5555-6666",
+    status: "standby",
+  },
+];
+
+/**
+ * 차량 유형 목록
+ */
+export const VEHICLE_TYPES = ["1톤 트럭", "2.5톤 트럭", "5톤 트럭", "카고", "탑차", "냉동차"];
+
+/**
+ * 운행 상태별 통계 계산
+ */
+export function getDriverStatistics(drivers: DriverInfo[]) {
+  return {
+    total: drivers.length,
+    driving: drivers.filter((d) => d.status === "driving").length,
+    standby: drivers.filter((d) => d.status === "standby").length,
+    resting: drivers.filter((d) => d.status === "resting").length,
+    maintenance: drivers.filter((d) => d.status === "maintenance").length,
+  };
+}
diff --git a/frontend/components/admin/dashboard/widgets/driverUtils.ts b/frontend/components/admin/dashboard/widgets/driverUtils.ts
new file mode 100644
index 00000000..bd2ddbd3
--- /dev/null
+++ b/frontend/components/admin/dashboard/widgets/driverUtils.ts
@@ -0,0 +1,256 @@
+import { DriverInfo, DriverManagementConfig } from "../types";
+
+/**
+ * 운행 상태별 색상 반환
+ */
+export function getStatusColor(status: DriverInfo["status"]) {
+  switch (status) {
+    case "driving":
+      return {
+        bg: "bg-green-100",
+        text: "text-green-800",
+        border: "border-green-300",
+        badge: "bg-green-500",
+      };
+    case "standby":
+      return {
+        bg: "bg-gray-100",
+        text: "text-gray-800",
+        border: "border-gray-300",
+        badge: "bg-gray-500",
+      };
+    case "resting":
+      return {
+        bg: "bg-orange-100",
+        text: "text-orange-800",
+        border: "border-orange-300",
+        badge: "bg-orange-500",
+      };
+    case "maintenance":
+      return {
+        bg: "bg-red-100",
+        text: "text-red-800",
+        border: "border-red-300",
+        badge: "bg-red-500",
+      };
+    default:
+      return {
+        bg: "bg-gray-100",
+        text: "text-gray-800",
+        border: "border-gray-300",
+        badge: "bg-gray-500",
+      };
+  }
+}
+
+/**
+ * 운행 상태 한글 변환
+ */
+export function getStatusLabel(status: DriverInfo["status"]) {
+  switch (status) {
+    case "driving":
+      return "운행중";
+    case "standby":
+      return "대기중";
+    case "resting":
+      return "휴식중";
+    case "maintenance":
+      return "점검중";
+    default:
+      return "알 수 없음";
+  }
+}
+
+/**
+ * 시간 포맷팅 (HH:MM)
+ */
+export function formatTime(dateString?: string): string {
+  if (!dateString) return "-";
+  const date = new Date(dateString);
+  return date.toLocaleTimeString("ko-KR", {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  });
+}
+
+/**
+ * 날짜 시간 포맷팅 (MM/DD HH:MM)
+ */
+export function formatDateTime(dateString?: string): string {
+  if (!dateString) return "-";
+  const date = new Date(dateString);
+  return date.toLocaleString("ko-KR", {
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  });
+}
+
+/**
+ * 운행 진행률 계산 (실제로는 GPS 데이터 기반)
+ */
+export function calculateProgress(driver: DriverInfo): number {
+  if (!driver.departureTime || !driver.estimatedArrival) return 0;
+
+  const now = new Date();
+  const departure = new Date(driver.departureTime);
+  const arrival = new Date(driver.estimatedArrival);
+
+  const totalTime = arrival.getTime() - departure.getTime();
+  const elapsedTime = now.getTime() - departure.getTime();
+
+  const progress = Math.min(100, Math.max(0, (elapsedTime / totalTime) * 100));
+  return Math.round(progress);
+}
+
+/**
+ * 기사 필터링
+ */
+export function filterDrivers(
+  drivers: DriverInfo[],
+  statusFilter: DriverManagementConfig["statusFilter"],
+  searchTerm: string,
+): DriverInfo[] {
+  let filtered = drivers;
+
+  // 상태 필터
+  if (statusFilter !== "all") {
+    filtered = filtered.filter((driver) => driver.status === statusFilter);
+  }
+
+  // 검색어 필터
+  if (searchTerm.trim()) {
+    const term = searchTerm.toLowerCase();
+    filtered = filtered.filter(
+      (driver) =>
+        driver.name.toLowerCase().includes(term) ||
+        driver.vehicleNumber.toLowerCase().includes(term) ||
+        driver.phone.includes(term),
+    );
+  }
+
+  return filtered;
+}
+
+/**
+ * 기사 정렬
+ */
+export function sortDrivers(
+  drivers: DriverInfo[],
+  sortBy: DriverManagementConfig["sortBy"],
+  sortOrder: DriverManagementConfig["sortOrder"],
+): DriverInfo[] {
+  const sorted = [...drivers];
+
+  sorted.sort((a, b) => {
+    let compareResult = 0;
+
+    switch (sortBy) {
+      case "name":
+        compareResult = a.name.localeCompare(b.name, "ko-KR");
+        break;
+      case "vehicleNumber":
+        compareResult = a.vehicleNumber.localeCompare(b.vehicleNumber);
+        break;
+      case "status":
+        const statusOrder = { driving: 0, resting: 1, standby: 2, maintenance: 3 };
+        compareResult = statusOrder[a.status] - statusOrder[b.status];
+        break;
+      case "departureTime":
+        const timeA = a.departureTime ? new Date(a.departureTime).getTime() : 0;
+        const timeB = b.departureTime ? new Date(b.departureTime).getTime() : 0;
+        compareResult = timeA - timeB;
+        break;
+    }
+
+    return sortOrder === "asc" ? compareResult : -compareResult;
+  });
+
+  return sorted;
+}
+
+/**
+ * 테마별 색상 반환
+ */
+export function getThemeColors(theme: string, customColor?: string) {
+  if (theme === "custom" && customColor) {
+    const lighterColor = adjustColor(customColor, 40);
+    const darkerColor = adjustColor(customColor, -40);
+
+    return {
+      background: lighterColor,
+      text: darkerColor,
+      border: customColor,
+      hover: customColor,
+    };
+  }
+
+  if (theme === "dark") {
+    return {
+      background: "#1f2937",
+      text: "#f3f4f6",
+      border: "#374151",
+      hover: "#374151",
+    };
+  }
+
+  // light theme (default)
+  return {
+    background: "#ffffff",
+    text: "#1f2937",
+    border: "#e5e7eb",
+    hover: "#f3f4f6",
+  };
+}
+
+/**
+ * 색상 밝기 조정
+ */
+function adjustColor(color: string, amount: number): string {
+  const clamp = (num: number) => Math.min(255, Math.max(0, num));
+
+  const hex = color.replace("#", "");
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+
+  const newR = clamp(r + amount);
+  const newG = clamp(g + amount);
+  const newB = clamp(b + amount);
+
+  return `#${newR.toString(16).padStart(2, "0")}${newG.toString(16).padStart(2, "0")}${newB.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * 기본 표시 컬럼 목록
+ */
+export const DEFAULT_VISIBLE_COLUMNS = [
+  "status",
+  "name",
+  "vehicleNumber",
+  "vehicleType",
+  "departure",
+  "destination",
+  "departureTime",
+  "estimatedArrival",
+  "phone",
+];
+
+/**
+ * 컬럼 라벨 매핑
+ */
+export const COLUMN_LABELS: Record<string, string> = {
+  status: "상태",
+  name: "기사명",
+  vehicleNumber: "차량번호",
+  vehicleType: "차량유형",
+  departure: "출발지",
+  destination: "목적지",
+  departureTime: "출발시간",
+  estimatedArrival: "도착예정",
+  phone: "연락처",
+  progress: "진행률",
+};
-- 
2.43.0


From d149f0baaa9e3e4dbfb24207c6936f8c840a7b24 Mon Sep 17 00:00:00 2001
From: dohyeons <ddhhss0603@gmail.com>
Date: Tue, 14 Oct 2025 11:46:14 +0900
Subject: [PATCH 4/6] =?UTF-8?q?=EA=B8=B0=EC=82=AC=20=EA=B4=80=EB=A6=AC=20?=
 =?UTF-8?q?=EC=9C=84=EC=A0=AF=EC=97=90=EC=84=9C=20=ED=85=8C=EB=A7=88=20?=
 =?UTF-8?q?=EA=B4=80=EB=A0=A8=20=EC=BD=94=EB=93=9C=20=EC=82=AD=EC=A0=9C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../widgets/DriverManagementSettings.tsx      | 62 +------------------
 1 file changed, 3 insertions(+), 59 deletions(-)

diff --git a/frontend/components/admin/dashboard/widgets/DriverManagementSettings.tsx b/frontend/components/admin/dashboard/widgets/DriverManagementSettings.tsx
index a77dfda5..0f09286e 100644
--- a/frontend/components/admin/dashboard/widgets/DriverManagementSettings.tsx
+++ b/frontend/components/admin/dashboard/widgets/DriverManagementSettings.tsx
@@ -44,7 +44,7 @@ export function DriverManagementSettings({ config, onSave, onClose }: DriverMana
             <SelectTrigger className="w-full">
               <SelectValue />
             </SelectTrigger>
-            <SelectContent>
+            <SelectContent className="z-[9999]">
               <SelectItem value="0">사용 안 함</SelectItem>
               <SelectItem value="10">10초마다</SelectItem>
               <SelectItem value="30">30초마다</SelectItem>
@@ -67,7 +67,7 @@ export function DriverManagementSettings({ config, onSave, onClose }: DriverMana
               <SelectTrigger>
                 <SelectValue />
               </SelectTrigger>
-              <SelectContent>
+              <SelectContent className="z-[9999]">
                 <SelectItem value="name">기사명</SelectItem>
                 <SelectItem value="vehicleNumber">차량번호</SelectItem>
                 <SelectItem value="status">운행상태</SelectItem>
@@ -84,7 +84,7 @@ export function DriverManagementSettings({ config, onSave, onClose }: DriverMana
               <SelectTrigger>
                 <SelectValue />
               </SelectTrigger>
-              <SelectContent>
+              <SelectContent className="z-[9999]">
                 <SelectItem value="asc">오름차순</SelectItem>
                 <SelectItem value="desc">내림차순</SelectItem>
               </SelectContent>
@@ -92,62 +92,6 @@ export function DriverManagementSettings({ config, onSave, onClose }: DriverMana
           </div>
         </div>
 
-        {/* 테마 설정 */}
-        <div className="space-y-3">
-          <Label className="text-sm font-semibold">테마</Label>
-          <div className="grid grid-cols-3 gap-3">
-            <Button
-              type="button"
-              variant={localConfig.theme === "light" ? "default" : "outline"}
-              className="w-full"
-              onClick={() => setLocalConfig({ ...localConfig, theme: "light" })}
-            >
-              ☀️ Light
-            </Button>
-            <Button
-              type="button"
-              variant={localConfig.theme === "dark" ? "default" : "outline"}
-              className="w-full"
-              onClick={() => setLocalConfig({ ...localConfig, theme: "dark" })}
-            >
-              🌙 Dark
-            </Button>
-            <Button
-              type="button"
-              variant={localConfig.theme === "custom" ? "default" : "outline"}
-              className="w-full"
-              onClick={() => setLocalConfig({ ...localConfig, theme: "custom" })}
-            >
-              🎨 Custom
-            </Button>
-          </div>
-
-          {/* 사용자 지정 색상 */}
-          {localConfig.theme === "custom" && (
-            <Card className="border p-4">
-              <Label className="mb-2 block text-sm font-medium">배경 색상 선택</Label>
-              <div className="flex items-center gap-3">
-                <Input
-                  type="color"
-                  value={localConfig.customColor || "#3b82f6"}
-                  onChange={(e) => setLocalConfig({ ...localConfig, customColor: e.target.value })}
-                  className="h-12 w-20 cursor-pointer"
-                />
-                <div className="flex-1">
-                  <Input
-                    type="text"
-                    value={localConfig.customColor || "#3b82f6"}
-                    onChange={(e) => setLocalConfig({ ...localConfig, customColor: e.target.value })}
-                    placeholder="#3b82f6"
-                    className="font-mono"
-                  />
-                  <p className="text-muted-foreground mt-1 text-xs">테이블 배경색으로 사용됩니다</p>
-                </div>
-              </div>
-            </Card>
-          )}
-        </div>
-
         {/* 표시 컬럼 선택 */}
         <div className="space-y-3">
           <div className="flex items-center justify-between">
-- 
2.43.0


From 2b104b8455f4723ee156dfb20cc23fe826d722f9 Mon Sep 17 00:00:00 2001
From: dohyeons <ddhhss0603@gmail.com>
Date: Tue, 14 Oct 2025 11:53:40 +0900
Subject: [PATCH 5/6] =?UTF-8?q?=EB=B6=88=ED=95=84=EC=9A=94=ED=95=9C=20?=
 =?UTF-8?q?=EA=B0=80=EC=A0=B8=EC=98=A4=EA=B8=B0=20=EC=82=AD=EC=A0=9C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/components/admin/dashboard/widgets/DriverListView.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/frontend/components/admin/dashboard/widgets/DriverListView.tsx b/frontend/components/admin/dashboard/widgets/DriverListView.tsx
index f5df6944..cddbe6c6 100644
--- a/frontend/components/admin/dashboard/widgets/DriverListView.tsx
+++ b/frontend/components/admin/dashboard/widgets/DriverListView.tsx
@@ -1,6 +1,5 @@
 "use client";
 
-import React from "react";
 import { DriverInfo, DriverManagementConfig } from "../types";
 import { getStatusColor, getStatusLabel, formatTime, COLUMN_LABELS } from "./driverUtils";
 import { Progress } from "@/components/ui/progress";
-- 
2.43.0


From 5cd5ad6c49ded17a39f19d018e14a59d8c8c4f10 Mon Sep 17 00:00:00 2001
From: dohyeons <ddhhss0603@gmail.com>
Date: Tue, 14 Oct 2025 13:20:17 +0900
Subject: [PATCH 6/6] =?UTF-8?q?=EC=BA=94=EB=B2=84=EC=8A=A4=20=EB=84=88?=
 =?UTF-8?q?=EB=B9=84=20=EC=B4=88=EA=B3=BC=ED=95=98=EB=8A=94=20=EB=B0=B0?=
 =?UTF-8?q?=EC=B9=98=20=EB=A7=89=EC=9D=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../admin/dashboard/CanvasElement.tsx         | 104 +++++-------------
 .../admin/dashboard/DashboardCanvas.tsx       |   8 +-
 2 files changed, 31 insertions(+), 81 deletions(-)

diff --git a/frontend/components/admin/dashboard/CanvasElement.tsx b/frontend/components/admin/dashboard/CanvasElement.tsx
index 3decd573..43ce5163 100644
--- a/frontend/components/admin/dashboard/CanvasElement.tsx
+++ b/frontend/components/admin/dashboard/CanvasElement.tsx
@@ -131,9 +131,13 @@ export function CanvasElement({
         const deltaY = e.clientY - dragStart.y;
 
         // 임시 위치 계산 (스냅 안 됨)
-        const rawX = Math.max(0, dragStart.elementX + deltaX);
+        let rawX = Math.max(0, dragStart.elementX + deltaX);
         const rawY = Math.max(0, dragStart.elementY + deltaY);
 
+        // X 좌표가 캔버스 너비를 벗어나지 않도록 제한
+        const maxX = GRID_CONFIG.CANVAS_WIDTH - element.size.width;
+        rawX = Math.min(rawX, maxX);
+
         setTempPosition({ x: rawX, y: rawY });
       } else if (isResizing) {
         const deltaX = e.clientX - resizeStart.x;
@@ -173,21 +177,29 @@ export function CanvasElement({
             break;
         }
 
+        // 가로 너비가 캔버스를 벗어나지 않도록 제한
+        const maxWidth = GRID_CONFIG.CANVAS_WIDTH - newX;
+        newWidth = Math.min(newWidth, maxWidth);
+
         // 임시 크기/위치 저장 (스냅 안 됨)
         setTempPosition({ x: Math.max(0, newX), y: Math.max(0, newY) });
         setTempSize({ width: newWidth, height: newHeight });
       }
     },
-    [isDragging, isResizing, dragStart, resizeStart],
+    [isDragging, isResizing, dragStart, resizeStart, element.size.width, element.type, element.subtype],
   );
 
   // 마우스 업 처리 (그리드 스냅 적용)
   const handleMouseUp = useCallback(() => {
     if (isDragging && tempPosition) {
       // 드래그 종료 시 그리드에 스냅 (동적 셀 크기 사용)
-      const snappedX = snapToGrid(tempPosition.x, cellSize);
+      let snappedX = snapToGrid(tempPosition.x, cellSize);
       const snappedY = snapToGrid(tempPosition.y, cellSize);
 
+      // X 좌표가 캔버스 너비를 벗어나지 않도록 최종 제한
+      const maxX = GRID_CONFIG.CANVAS_WIDTH - element.size.width;
+      snappedX = Math.min(snappedX, maxX);
+
       onUpdate(element.id, {
         position: { x: snappedX, y: snappedY },
       });
@@ -199,9 +211,13 @@ export function CanvasElement({
       // 리사이즈 종료 시 그리드에 스냅 (동적 셀 크기 사용)
       const snappedX = snapToGrid(tempPosition.x, cellSize);
       const snappedY = snapToGrid(tempPosition.y, cellSize);
-      const snappedWidth = snapSizeToGrid(tempSize.width, 2, cellSize);
+      let snappedWidth = snapSizeToGrid(tempSize.width, 2, cellSize);
       const snappedHeight = snapSizeToGrid(tempSize.height, 2, cellSize);
 
+      // 가로 너비가 캔버스를 벗어나지 않도록 최종 제한
+      const maxWidth = GRID_CONFIG.CANVAS_WIDTH - snappedX;
+      snappedWidth = Math.min(snappedWidth, maxWidth);
+
       onUpdate(element.id, {
         position: { x: snappedX, y: snappedY },
         size: { width: snappedWidth, height: snappedHeight },
@@ -213,7 +229,7 @@ export function CanvasElement({
 
     setIsDragging(false);
     setIsResizing(false);
-  }, [isDragging, isResizing, tempPosition, tempSize, element.id, onUpdate, cellSize]);
+  }, [isDragging, isResizing, tempPosition, tempSize, element.id, element.size.width, onUpdate, cellSize]);
 
   // 전역 마우스 이벤트 등록
   React.useEffect(() => {
@@ -251,12 +267,11 @@ export function CanvasElement({
         executionTime: 0,
       });
     } catch (error) {
-      // console.error('❌ 데이터 로딩 오류:', error);
       setChartData(null);
     } finally {
       setIsLoadingData(false);
     }
-  }, [element.dataSource?.query, element.type, element.subtype]);
+  }, [element.dataSource?.query, element.type]);
 
   // 컴포넌트 마운트 시 및 쿼리 변경 시 데이터 로딩
   useEffect(() => {
@@ -372,7 +387,7 @@ export function CanvasElement({
             ) : (
               <ChartRenderer
                 element={element}
-                data={chartData}
+                data={chartData || undefined}
                 width={element.size.width}
                 height={element.size.height - 45}
               />
@@ -381,16 +396,12 @@ export function CanvasElement({
         ) : element.type === "widget" && element.subtype === "weather" ? (
           // 날씨 위젯 렌더링
           <div className="widget-interactive-area h-full w-full">
-            <WeatherWidget city={element.config?.city || "서울"} refreshInterval={600000} />
+            <WeatherWidget city="서울" refreshInterval={600000} />
           </div>
         ) : element.type === "widget" && element.subtype === "exchange" ? (
           // 환율 위젯 렌더링
           <div className="widget-interactive-area h-full w-full">
-            <ExchangeWidget
-              baseCurrency={element.config?.baseCurrency || "KRW"}
-              targetCurrency={element.config?.targetCurrency || "USD"}
-              refreshInterval={600000}
-            />
+            <ExchangeWidget baseCurrency="KRW" targetCurrency="USD" refreshInterval={600000} />
           </div>
         ) : element.type === "widget" && element.subtype === "clock" ? (
           // 시계 위젯 렌더링
@@ -487,68 +498,3 @@ function ResizeHandle({ position, onMouseDown }: ResizeHandleProps) {
     />
   );
 }
-
-/**
- * 샘플 데이터 생성 함수 (실제 API 호출 대신 사용)
- */
-function generateSampleData(query: string, chartType: string): QueryResult {
-  // 쿼리에서 키워드 추출하여 적절한 샘플 데이터 생성
-  const isMonthly = query.toLowerCase().includes("month");
-  const isSales = query.toLowerCase().includes("sales") || query.toLowerCase().includes("매출");
-  const isUsers = query.toLowerCase().includes("users") || query.toLowerCase().includes("사용자");
-  const isProducts = query.toLowerCase().includes("product") || query.toLowerCase().includes("상품");
-
-  let columns: string[];
-  let rows: Record<string, any>[];
-
-  if (isMonthly && isSales) {
-    // 월별 매출 데이터
-    columns = ["month", "sales", "order_count"];
-    rows = [
-      { month: "2024-01", sales: 1200000, order_count: 45 },
-      { month: "2024-02", sales: 1350000, order_count: 52 },
-      { month: "2024-03", sales: 1180000, order_count: 41 },
-      { month: "2024-04", sales: 1420000, order_count: 58 },
-      { month: "2024-05", sales: 1680000, order_count: 67 },
-      { month: "2024-06", sales: 1540000, order_count: 61 },
-    ];
-  } else if (isUsers) {
-    // 사용자 가입 추이
-    columns = ["week", "new_users"];
-    rows = [
-      { week: "2024-W10", new_users: 23 },
-      { week: "2024-W11", new_users: 31 },
-      { week: "2024-W12", new_users: 28 },
-      { week: "2024-W13", new_users: 35 },
-      { week: "2024-W14", new_users: 42 },
-      { week: "2024-W15", new_users: 38 },
-    ];
-  } else if (isProducts) {
-    // 상품별 판매량
-    columns = ["product_name", "total_sold", "revenue"];
-    rows = [
-      { product_name: "스마트폰", total_sold: 156, revenue: 234000000 },
-      { product_name: "노트북", total_sold: 89, revenue: 178000000 },
-      { product_name: "태블릿", total_sold: 134, revenue: 67000000 },
-      { product_name: "이어폰", total_sold: 267, revenue: 26700000 },
-      { product_name: "스마트워치", total_sold: 98, revenue: 49000000 },
-    ];
-  } else {
-    // 기본 샘플 데이터
-    columns = ["category", "value", "count"];
-    rows = [
-      { category: "A", value: 100, count: 10 },
-      { category: "B", value: 150, count: 15 },
-      { category: "C", value: 120, count: 12 },
-      { category: "D", value: 180, count: 18 },
-      { category: "E", value: 90, count: 9 },
-    ];
-  }
-
-  return {
-    columns,
-    rows,
-    totalRows: rows.length,
-    executionTime: Math.floor(Math.random() * 100) + 50, // 50-150ms
-  };
-}
diff --git a/frontend/components/admin/dashboard/DashboardCanvas.tsx b/frontend/components/admin/dashboard/DashboardCanvas.tsx
index d8b7007e..1a4ec333 100644
--- a/frontend/components/admin/dashboard/DashboardCanvas.tsx
+++ b/frontend/components/admin/dashboard/DashboardCanvas.tsx
@@ -33,7 +33,7 @@ export const DashboardCanvas = forwardRef<HTMLDivElement, DashboardCanvasProps>(
       onRemoveElement,
       onSelectElement,
       onConfigureElement,
-      backgroundColor = '#f9fafb',
+      backgroundColor = "#f9fafb",
     },
     ref,
   ) => {
@@ -72,9 +72,13 @@ export const DashboardCanvas = forwardRef<HTMLDivElement, DashboardCanvasProps>(
           const rawY = e.clientY - rect.top + (ref.current?.scrollTop || 0);
 
           // 그리드에 스냅 (고정 셀 크기 사용)
-          const snappedX = snapToGrid(rawX, GRID_CONFIG.CELL_SIZE);
+          let snappedX = snapToGrid(rawX, GRID_CONFIG.CELL_SIZE);
           const snappedY = snapToGrid(rawY, GRID_CONFIG.CELL_SIZE);
 
+          // X 좌표가 캔버스 너비를 벗어나지 않도록 제한
+          const maxX = GRID_CONFIG.CANVAS_WIDTH - GRID_CONFIG.CELL_SIZE * 2; // 최소 2칸 너비 보장
+          snappedX = Math.max(0, Math.min(snappedX, maxX));
+
           onCreateElement(dragData.type, dragData.subtype, snappedX, snappedY);
         } catch (error) {
           // console.error('드롭 데이터 파싱 오류:', error);
-- 
2.43.0