> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 대시보드

> AI 기반 패널 대시보드 — 자연어로 SQL 차트를 자동 생성하고, 공유·내보내기까지

<Info>관리자 › 모니터링 › 대시보드</Info>

대시보드는 **자연어 한 줄**로 SQL 차트를 자동 생성합니다.

* AI 어시스턴트와 대화하며 패널을 추가·수정하고, 완성된 대시보드를 팀에 공유하거나 HTML로 내보낼 수 있습니다.

| 방법    | 과정                         |   소요 시간  |
| ----- | -------------------------- | :------: |
| 수동 작업 | SQL 작성 → 실행 → 엑셀 차트 → 슬라이드 | 30분\~수시간 |
| 대시보드  | 자연어 입력 → AI가 차트 자동 생성      |  **30초** |

<Frame caption="관리자 > 모니터링 > 대시보드 — 생성된 대시보드 목록">
  <img src="https://mintcdn.com/cloocus/e2STMIwiJ94E5-9q/images/monitoring/dashboard-main.png?fit=max&auto=format&n=e2STMIwiJ94E5-9q&q=85&s=ab63816030a8e5a9998ea4c82e64ec8c" alt="대시보드 목록" width="2880" height="1800" data-path="images/monitoring/dashboard-main.png" />
</Frame>

## 접근 경로

| 권한              |      대시보드 목록      | 생성/수정/삭제 | 공유된 대시보드 |
| --------------- | :---------------: | :------: | :------: |
| Admin (모니터링 쓰기) |         전체        |     O    |     O    |
| Admin (모니터링 읽기) |         전체        |     X    |     O    |
| 일반 사용자          | 본인 소유 + 공개/공유된 것만 |     X    |     O    |

***

## 대시보드 만들기

<Steps>
  <Step title="대시보드 생성">
    대시보드 목록에서 **대시보드 생성** 버튼을 클릭합니다.

    | 필드     |  필수 | 설명                        |
    | ------ | :-: | ------------------------- |
    | **이름** |  O  | 대시보드 이름 (시스템 전체에서 고유해야 함) |
    | **설명** |  X  | 대시보드 용도 설명                |

    <Tip>
      DB 연결은 이 단계에서 설정하지 않습니다. 패널별로 다른 DB를 연결할 수 있으므로, 패널 추가 시 DB를 선택합니다.
    </Tip>
  </Step>

  <Step title="패널 추가">
    생성된 대시보드에서 **패널 추가** 또는 **AI 어시스턴트**로 패널을 추가합니다. 패널 추가 모달 상단에서 **차트 / 카드** 유형을 먼저 고릅니다.

    <Tabs>
      <Tab title="차트 (Chart)">
        SQL 실행 결과를 다양한 차트로 시각화합니다. 패널 편집기에서 **자연어 질문**을 입력하면 AI가 SQL을 자동 생성합니다.

        <Frame caption="차트 패널 추가 모달">
          <img src="https://mintcdn.com/cloocus/z12HbjPvLk3VcOGS/images/monitoring/dashboard-panel-add-chart.png?fit=max&auto=format&n=z12HbjPvLk3VcOGS&q=85&s=a8b7a284b104b0867434cf713c7486c5" alt="패널 추가 모달 — 차트 유형" width="1369" height="983" data-path="images/monitoring/dashboard-panel-add-chart.png" />
        </Frame>

        **지원 차트 유형:**

        | 차트              | 설명            | 활용 예시         |
        | --------------- | ------------- | ------------- |
        | **Table**       | 테이블 형태 데이터 표시 | 상세 데이터 조회     |
        | **Bar**         | 항목별 비교        | 모델별 사용 횟수     |
        | **Grouped Bar** | 여러 시리즈 그룹 비교  | 모델별·기간별 비용 비교 |
        | **Line**        | 시간에 따른 추이     | 일별 토큰 사용량 추이  |
        | **Area**        | 추이 + 면적 강조    | 누적 사용량 변화     |
        | **Pie**         | 비율 분포         | 에이전트별 사용 비율   |
        | **Scatter**     | 두 변수 간 상관관계   | 응답 시간 vs 토큰 수 |
        | **Histogram**   | 수치 분포         | 응답 시간 분포      |
        | **Heatmap**     | 2차원 매트릭스 값 분포 | 시간대별·요일별 사용량  |

        편집 모드에서 패널 상단의 차트 유형 아이콘을 클릭하면 즉시 전환됩니다.
      </Tab>

      <Tab title="카드 (Card)">
        핵심 KPI 수치를 한눈에 보여주는 요약 카드입니다.

        <Frame caption="카드 패널 추가 모달">
          <img src="https://mintcdn.com/cloocus/z12HbjPvLk3VcOGS/images/monitoring/dashboard-panel-add-card.png?fit=max&auto=format&n=z12HbjPvLk3VcOGS&q=85&s=c661e3136e34c1f73bd83206db99dd71" alt="패널 추가 모달 — 카드 유형" width="1369" height="983" data-path="images/monitoring/dashboard-panel-add-card.png" />
        </Frame>

        | 소스        | 설명                                 |
        | --------- | ---------------------------------- |
        | **직접 입력** | 고정값 직접 입력 (예: "1,234" 또는 "Active") |
        | **DB 쿼리** | 자연어 → SQL로 실시간 값 조회                |

        배경색을 지정하여 시각적으로 구분할 수 있습니다.
      </Tab>
    </Tabs>

    이후 [패널 편집기](#패널-편집기)에서 SQL·기간 필터를 설정하고, 대화형 생성은 [AI 어시스턴트](#ai-어시스턴트)를 참고하세요.
  </Step>

  <Step title="레이아웃 조정">
    **편집** 모드에서 패널을 드래그하여 위치를 이동하고, 우측 하단 핸들로 크기를 조절합니다. 12컬럼 그리드 기반으로 배치됩니다.
  </Step>
</Steps>

***

## 패널 구성

대시보드는 개별 **패널**로 구성됩니다.

* 각 패널은 독립된 DB 연결과 SQL을 가집니다.
* 패널 유형(차트·카드) 선택은 [패널 추가](#대시보드-만들기) 단계를 참고하세요.

<Frame caption="여러 패널로 구성된 대시보드 예시 — 상단 카드 지표와 차트 패널이 함께 배치됩니다">
  <img src="https://mintcdn.com/cloocus/z12HbjPvLk3VcOGS/images/monitoring/dashboard-panels.png?fit=max&auto=format&n=z12HbjPvLk3VcOGS&q=85&s=a0e7f91b429b6c5dcffea7b3a283dd44" alt="여러 패널로 구성된 사용량 대시보드" width="1296" height="992" data-path="images/monitoring/dashboard-panels.png" />
</Frame>

### 패널 편집기

**패널 추가** 버튼 또는 기존 패널의 편집 아이콘을 클릭하면 패널 편집 모달이 열립니다.

<Accordion title="패널 추가·편집 모달 필드" icon="sliders">
  | 필드            | 설명                                         |
  | ------------- | ------------------------------------------ |
  | **패널 이름**     | 패널 제목 (필수)                                 |
  | **데이터베이스 선택** | 연결할 DbSphere 선택                            |
  | **모델 선택**     | SQL 생성에 사용할 AI 모델                          |
  | **자연어 질문**    | 원하는 데이터를 자연어로 설명                           |
  | **SQL 생성**    | 자연어 질문을 AI가 SQL로 자동 변환 (생성된 SQL은 직접 수정 가능) |
  | **기간 필터 사용**  | 날짜 컬럼을 지정하여 대시보드 기간 필터와 연동                 |
  | **제목 표시**     | 패널 제목 표시 위치 선택 (헤더 / 내부 하단)                |
</Accordion>

<Info>
  생성된 SQL은 자유롭게 수정할 수 있습니다. AI가 생성한 SQL이 정확하지 않으면 직접 고쳐 사용하세요.
</Info>

***

## AI 어시스턴트

대시보드 화면 **우측 하단의 보라색 AI 어시스턴트 버튼**을 클릭하면 하단에 채팅 패널이 열립니다.

* 상단에서 **모델**을 고르고, 입력창에 원하는 작업을 자연어로 설명하면 됩니다.
* 처음이라면 제시되는 예시 프롬프트를 눌러 바로 시작할 수도 있습니다.

<Frame caption="관리자 > 모니터링 > 대시보드 — AI 어시스턴트 패널(모델 선택·예시 프롬프트·입력창)">
  <img src="https://mintcdn.com/cloocus/iRgCRr3H3czOaMhv/images/monitoring/dashboard-ai-assistant.png?fit=max&auto=format&n=iRgCRr3H3czOaMhv&q=85&s=1510b04de9fd05ccfef3e7f00607fc15" alt="AI 대시보드 어시스턴트 패널 — 자연어로 패널을 생성·수정하는 채팅 인터페이스" width="2880" height="1800" data-path="images/monitoring/dashboard-ai-assistant.png" />
</Frame>

### 대화형 대시보드 빌더

자연어로 대화하며 패널을 추가·수정·삭제할 수 있습니다.

<Steps>
  <Step title="AI 어시스턴트 열기">
    우측 하단 보라색 버튼 클릭. 상단에서 **DB**와 **모델**을 선택합니다.
  </Step>

  <Step title="자연어로 요청">
    예시:

    * "이번 달 모델별 토큰 사용량 차트 만들어줘"
    * "사용자별 비용 카드도 추가해줘"
    * "기간을 30일로 변경해줘"
    * "파이 차트를 바 차트로 바꿔줘"
  </Step>

  <Step title="AI 결과 확인">
    AI가 SQL을 생성하고 패널을 자동 배치합니다. 겹치지 않도록 위치를 자동 조정합니다.
  </Step>

  <Step title="반복 수정">
    추가 대화로 패널 수정·삭제·재배치를 계속할 수 있습니다. 대화 이력은 대시보드에 저장됩니다.
  </Step>
</Steps>

**예시 — 기존 차트 유형 바꾸기**

바꿀 패널을 지정해 요청하면, 같은 데이터를 즉시 다른 차트로 다시 그립니다. 예를 들어 다음과 같이 입력하면:

> `Revenue by City 바 차트를 파이 차트로 바꿔줘`

<Columns cols={2}>
  <Frame caption="변경 전 — 막대 차트">
    <img src="https://mintcdn.com/cloocus/iRgCRr3H3czOaMhv/images/monitoring/dashboard-ai-before.png?fit=max&auto=format&n=iRgCRr3H3czOaMhv&q=85&s=9722a0fc6b407ced524e44312aa8a075" alt="Revenue by City 막대 차트 (변경 전)" width="403" height="316" data-path="images/monitoring/dashboard-ai-before.png" />
  </Frame>

  <Frame caption="변경 후 — 파이 차트">
    <img src="https://mintcdn.com/cloocus/iRgCRr3H3czOaMhv/images/monitoring/dashboard-ai-after.png?fit=max&auto=format&n=iRgCRr3H3czOaMhv&q=85&s=6764fc6fb5850618958a24134f4817ce" alt="Revenue by City 파이 차트 (변경 후)" width="528" height="414" data-path="images/monitoring/dashboard-ai-after.png" />
  </Frame>
</Columns>

<Tip>
  AI가 버튼 형태의 선택지를 제시하는 경우가 있습니다. 클릭으로 빠르게 응답할 수 있습니다.
</Tip>

### 원클릭 자동 생성

빈 대시보드에서 처음 시작할 때, AI에게 대시보드의 **목적**을 설명하면 적합한 패널 세트를 한 번에 생성합니다.

* DB 연결을 자동으로 테스트한 후 정상인 경우에만 생성을 진행합니다.

***

## 필터링

대시보드 상단에 **기간 필터**와 **커스텀 필터**가 배치됩니다.

<AccordionGroup>
  <Accordion title="기간 필터 (TimeRangePicker)" icon="calendar">
    | 프리셋                     | 설명            |
    | ----------------------- | ------------- |
    | Today / Yesterday       | 오늘 / 어제       |
    | This Week / Last Week   | 이번 주 / 지난 주   |
    | This Month / Last Month | 이번 달 / 지난 달   |
    | 7d / 30d                | 최근 7일 / 30일   |
    | All                     | 전체 기간         |
    | Custom                  | 직접 시작일·종료일 지정 |

    기본값은 **Yesterday**입니다. 기간을 변경하면 `기간 필터`가 활성화된 모든 패널의 SQL이 자동으로 재실행됩니다.
  </Accordion>

  <Accordion title="커스텀 필터 (FilterBar)" icon="filter">
    편집 모드에서 **필터 추가** 버튼으로 대시보드 전체에 적용되는 필터를 추가할 수 있습니다.

    | 필터 타입          | 설명                    |
    | -------------- | --------------------- |
    | **Text**       | 자유 텍스트 입력 (예: 사용자 이름) |
    | **Date Range** | 시작일 \~ 종료일 범위         |
    | **Select**     | 선택형 옵션                |

    필터를 추가할 때 **표시 라벨**과 **DB 컬럼명**을 지정합니다. 활성화된 필터는 각 패널 상단에 파란색 뱃지로 표시됩니다.
  </Accordion>
</AccordionGroup>

***

## 공유

완성된 대시보드를 팀원에게 공유할 수 있습니다.

<Steps>
  <Step title="공유 버튼 클릭">
    대시보드 상단의 **공유** 버튼을 클릭하면 **대시보드 공유** 창이 열리고, 공유 URL이 자동으로 클립보드에 복사됩니다.

    <Frame caption="관리자 > 모니터링 > 대시보드 > 공유 — 대시보드 공유 창(공유 URL·공개 상태)">
      <img src="https://mintcdn.com/cloocus/-11XFSTLwtgmJLzZ/images/monitoring/dashboard-share.png?fit=max&auto=format&n=-11XFSTLwtgmJLzZ&q=85&s=d29d838e32d79c5a437f1351398436c3" alt="대시보드 공유 모달 — 공유 URL, 공개 상태, 접근 권한 수정 및 링크 복사" width="1360" height="992" data-path="images/monitoring/dashboard-share.png" />
    </Frame>

    공유 URL 형태: `https://{도메인}/dashboard/{share_id}`. **공유 링크 삭제**로 언제든 공유를 해제할 수 있습니다.
  </Step>

  <Step title="접근 권한 수정 (접근 제어)">
    **접근 권한 수정 및 링크 복사**를 누르면 **접근 제어** 창이 열립니다. 공개 범위와 접근 대상을 지정합니다.

    <Frame caption="관리자 > 모니터링 > 대시보드 > 공유 > 접근 권한 수정 — 접근 제어 창">
      <img src="https://mintcdn.com/cloocus/-11XFSTLwtgmJLzZ/images/monitoring/dashboard-share-access.png?fit=max&auto=format&n=-11XFSTLwtgmJLzZ&q=85&s=6989344e2d33a6ca915bc2903df9ca09" alt="접근 제어 모달 — 권한(공개/비공개), 그룹, 조직 단위" width="1360" height="992" data-path="images/monitoring/dashboard-share-access.png" />
    </Frame>

    | 항목        | 설명                                                |
    | --------- | ------------------------------------------------- |
    | **권한**    | **공개**(로그인한 모든 사용자) ↔ **비공개**(권한을 부여한 사용자·그룹만) 전환 |
    | **그룹**    | 접근할 그룹을 지정해 **읽기** 권한 부여                          |
    | **조직 단위** | 접근할 조직 단위(OU)를 지정해 **읽기** 권한 부여                   |

    지정을 마치면 **접근 권한 수정 및 링크 복사**로 변경을 저장하고 링크를 다시 복사합니다.
  </Step>
</Steps>

공유된 대시보드에서는 **보기 전용**으로 동작합니다 — 기간 필터와 커스텀 필터로 데이터를 조회할 수 있지만, 패널 편집·추가·삭제·AI 어시스턴트는 비활성화됩니다.

<Warning>
  공유 링크에 접근하려면 **로그인이 필요**합니다. 로그인하지 않은 사용자는 로그인 페이지로 이동한 후 자동으로 대시보드로 돌아옵니다.
</Warning>

***

## HTML 내보내기

대시보드를 **독립 실행 가능한 HTML 파일**로 내보낼 수 있습니다.

* 대시보드 상단의 **내보내기** 버튼을 클릭하면 현재 적용된 기간·필터 조건으로 SQL을 실행하여 최신 데이터가 포함된 HTML 파일이 다운로드됩니다.

**내보내기 파일 특성:**

| 항목          | 설명                          |
| ----------- | --------------------------- |
| **형식**      | 단일 HTML 파일 (외부 의존성 없음)      |
| **차트 인터랙션** | 호버, 줌 등 Plotly 기본 기능 지원     |
| **테마**      | 라이트/다크 모드 자동 지원 (시스템 설정 따름) |
| **레이아웃**    | 대시보드와 동일한 12컬럼 그리드          |
| **반응형**     | 윈도우 리사이즈 시 차트 자동 조정         |

<Tip>
  내보낸 HTML 파일은 이메일 첨부, 사내 공유 드라이브 업로드, 또는 예약 작업과 연동하여 **정기 보고서**로 활용할 수 있습니다. 자세한 내용은 [예약 작업](/ko/automation/schedules)을 참고하세요.
</Tip>

***

## 보안

| 항목         | 정책                                                      |
| ---------- | ------------------------------------------------------- |
| **SQL 실행** | `SELECT` 쿼리만 허용. INSERT/UPDATE/DELETE/DROP 등 변경 쿼리는 차단됨 |
| **필터 입력**  | SQL Injection 방지를 위해 특수문자 이스케이프 처리                      |
| **공유 접근**  | 접근 제어(공개/비공개 권한 + 그룹·조직 단위 지정) 기반 검증                    |
| **DB 연결**  | DbSphere에 등록된 읽기 전용 연결만 사용                              |

***

## 활용 예시

<AccordionGroup>
  <Accordion title="경영진 KPI 모니터링">
    1. "이번 달 주요 KPI 대시보드 만들어줘"로 AI 자동 생성
    2. 카드 패널로 핵심 수치(총 매출, 활성 사용자 수 등) 표시
    3. 라인 차트로 일별 추이 표시
    4. Public으로 공유하여 팀 전체 접근
  </Accordion>

  <Accordion title="정기 보고서 자동화">
    1. 대시보드에 월간 보고서용 패널 구성
    2. HTML 내보내기를 예약 작업에 연동
    3. 매주 월요일 아침 자동으로 HTML 보고서 생성 및 이메일 발송
  </Accordion>

  <Accordion title="모델 사용량 분석">
    1. "모델별 토큰 사용량과 비용을 비교해줘"로 차트 생성
    2. Grouped Bar로 모델별·기간별 비교
    3. 기간 필터로 최근 7일/30일/전체 전환하며 분석
  </Accordion>
</AccordionGroup>

***

## 관련 페이지

<Columns cols={3}>
  <Card title="데이터베이스 (DbSphere)" icon="database" href="/ko/workspace/database">
    대시보드가 연결하는 데이터베이스 설정
  </Card>

  <Card title="예약 작업" icon="clock" href="/ko/automation/schedules">
    대시보드 내보내기를 자동화하는 스케줄러
  </Card>

  <Card title="사용량" icon="chart-line" href="/ko/monitoring/usage">
    토큰 사용량 및 비용 통계 대시보드
  </Card>
</Columns>