@t3q-ui/design-system 0.0.0-stage → 1.56.0

package/skills/tds/examples/dashboard-page.tsx

@@ -0,0 +1,344 @@
+/**
+ * TDS 대시보드 예제 — "헤더(새로고침·갱신 시각) → 요약 타일 → 추이 차트 2개(기간 선택) → 표 → 최근 이벤트" 흐름.
+ * 이 파일은 TDS 저장소의 타입 검사(`pnpm typecheck`)와 렌더 테스트를 통과한 코드다. 새 대시보드는 이 구조에서 시작한다.
+ *
+ * 이 예제가 보여 주는 것 (자주 틀리는 곳):
+ * - DashboardLayout 이 헤더·요약 타일·섹션 간격·로딩·오류·없음 상태를 그린다. 타일·섹션 제목을 직접 만들지 않는다
+ * - 사용률 타일은 `ratio`(0~1 → 진행 막대) + `tone`(80% 초과면 'warning') → 숫자 색·경고 아이콘·막대 색이 함께 바뀐다
+ * - 새로고침은 `titleRight` 에 `PageHeaderRefreshButton`(아이콘 버튼 + "방금 업데이트" 라벨) — 목록·상세 화면과 같은 모양
+ * - 전체를 못 불러왔으면 `error` + `onRetry`, 데이터가 전혀 없으면 `empty` → 패턴이 아이콘·제목·설명·다시 시도 상자로 그린다.
+ *   Alert 줄이나 `<div>` 로 직접 만들지 않는다. 패널 하나만 비었으면 `DashboardPanel empty`
+ * - 차트 패널은 `DashboardSection columns={2}` 안에 `DashboardPanel`(제목·현재값·단위·최고값) → 차트는 소비 앱 몫(여기서는 SVG 면 채우기 + "경고 기준 80%" 라벨)
+ * - 기간 선택은 섹션 `action` 에 `ToggleGroup type='single'`
+ * - 표는 `AgGridTable`, 80% 초과 셀은 `Badge variant='warning'`(아이콘 + 값)으로 경고 — 글자색을 직접 칠하지 않는다.
+ *   `warning30` 같은 30단계는 채움·배경용이라 흰 배경에 글자로 쓰면 대비가 1.75:1 밖에 안 된다(axe color-contrast)
+ * - 최근 이벤트는 `EventList`(레벨 색 띠 + Badge + 상대 시각)
+ */
+import { useCallback, useEffect, useState } from 'react'
+import {
+  AgGridTable,
+  Badge,
+  EventList,
+  LucideIcon,
+  PageHeaderRefreshButton,
+  ToggleGroup,
+  ToggleGroupItem,
+} from '@t3q-ui/design-system'
+import {
+  DashboardLayout,
+  DashboardPanel,
+  DashboardSection,
+  type DashboardStat,
+} from '@t3q-ui/design-system/patterns'
+import type { ColDef, ICellRendererParams } from 'ag-grid-community'
+
+export type Period = '1h' | '6h' | '24h'
+type UsagePoint = { time: string; cpuPercent: number; memoryPercent: number }
+type Node = {
+  name: string
+  status: 'Ready' | 'NotReady'
+  cpuPercent: number | null
+  memoryPercent: number | null
+  gpu: { used: number; total: number } | null
+}
+type ClusterEvent = {
+  id: string
+  time: string
+  level: 'info' | 'warning' | 'error'
+  message: string
+}
+/** 목 API 응답. null 이면 "데이터 없음" */
+export type ResourceData = {
+  cpu: { used: number; total: number }
+  memory: { used: number; total: number }
+  gpu: { used: number; total: number }
+  runningJobs: number
+  usage: UsagePoint[]
+  nodes: Node[]
+  events: ClusterEvent[]
+} | null
+
+const WARN = 0.8
+const PERIODS: { value: Period; label: string }[] = [
+  { value: '1h', label: '1시간' },
+  { value: '6h', label: '6시간' },
+  { value: '24h', label: '24시간' },
+]
+const pct = (ratio: number) => `${(ratio * 100).toFixed(1)}%`
+const tone = (ratio: number): DashboardStat['tone'] => (ratio > WARN ? 'warning' : 'default')
+
+/** "3분 전" 식 상대 시각 — 이벤트 목록의 `time` 은 소비 앱이 포맷해 넘긴다 */
+function relative(iso: string, now: number) {
+  const min = Math.max(0, Math.round((now - new Date(iso).getTime()) / 60_000))
+  if (min < 1) return '방금'
+  if (min < 60) return `${min}분 전`
+  return `${Math.floor(min / 60)}시간 ${min % 60}분 전`
+}
+
+/** 면 채우기 추이 차트 (소비 앱 몫 — 차트 라이브러리 없이 SVG). 경고 기준선에 라벨을 붙인다 */
+function UsageChart({
+  points,
+  pick,
+  label,
+}: {
+  points: UsagePoint[]
+  pick: (p: UsagePoint) => number
+  label: string
+}) {
+  const W = 600
+  const H = 160
+  const PAD = { left: 40, right: 12, top: 12, bottom: 24 }
+  const x = (i: number) =>
+    PAD.left + (i / Math.max(1, points.length - 1)) * (W - PAD.left - PAD.right)
+  const y = (v: number) => PAD.top + (1 - v / 100) * (H - PAD.top - PAD.bottom)
+  const line = points.map((p, i) => `${i ? 'L' : 'M'}${x(i)},${y(pick(p))}`).join(' ')
+  const area = `${line} L${x(points.length - 1)},${y(0)} L${x(0)},${y(0)} Z`
+  const last = points.length ? pick(points[points.length - 1]) : 0
+  return (
+    <svg
+      viewBox={`0 0 ${W} ${H}`}
+      className='h-[160px] w-full'
+      role='img'
+      aria-label={`${label} 추이. 최근 ${last}%`}
+    >
+      {[0, 25, 50, 75, 100].map((t) => (
+        <g key={t}>
+          <line
+            x1={PAD.left}
+            x2={W - PAD.right}
+            y1={y(t)}
+            y2={y(t)}
+            className='stroke-sys-divider-subtler'
+          />
+          <text
+            x={PAD.left - 6}
+            y={y(t)}
+            textAnchor='end'
+            dominantBaseline='middle'
+            className='fill-sys-text-subtler text-[10px]'
+          >
+            {t}%
+          </text>
+        </g>
+      ))}
+      <line
+        x1={PAD.left}
+        x2={W - PAD.right}
+        y1={y(WARN * 100)}
+        y2={y(WARN * 100)}
+        className='stroke-warning30'
+        strokeDasharray='4 4'
+      />
+      <text x={PAD.left + 4} y={y(WARN * 100) - 4} className='fill-warning40 text-[10px]'>
+        경고 기준 {WARN * 100}%
+      </text>
+      <path d={area} className='fill-primary30' fillOpacity={0.12} />
+      <path d={line} className='stroke-primary30' strokeWidth={2} fill='none' />
+      {points.length ? (
+        <text
+          x={x(points.length - 1)}
+          y={y(last) - 6}
+          textAnchor='end'
+          className='fill-sys-text-main text-[11px]'
+        >
+          {last}%
+        </text>
+      ) : null}
+    </svg>
+  )
+}
+
+function WarnCell({ value, text }: { value: number | null; text: string }) {
+  if (value == null) return <span>-</span>
+  return value > WARN * 100 ? (
+    <Badge variant='warning'>
+      <LucideIcon iconComponentName='TriangleAlert' aria-hidden size={12} />
+      {text}
+    </Badge>
+  ) : (
+    <span>{text}</span>
+  )
+}
+
+const NODE_COLUMNS: ColDef<Node>[] = [
+  { field: 'name', headerName: '이름', flex: 1, minWidth: 160 },
+  {
+    field: 'status',
+    headerName: '상태',
+    width: 120,
+    cellRenderer: (p: ICellRendererParams<Node>) =>
+      p.data ? (
+        <Badge variant={p.data.status === 'Ready' ? 'success' : 'danger'}>
+          {p.data.status === 'Ready' ? (
+            <LucideIcon iconComponentName='circle-check' />
+          ) : (
+            <LucideIcon iconComponentName='circle-x' />
+          )}
+          {p.data.status}
+        </Badge>
+      ) : null,
+  },
+  // 숫자 열은 type: 'number' — 셀·제목 오른쪽 정렬(셀 렌더러가 있어도 적용된다)
+  {
+    field: 'cpuPercent',
+    headerName: 'CPU(%)',
+    width: 120,
+    type: 'number',
+    cellRenderer: (p: ICellRendererParams<Node>) =>
+      p.data ? <WarnCell value={p.data.cpuPercent} text={`${p.data.cpuPercent ?? ''}%`} /> : null,
+  },
+  {
+    field: 'memoryPercent',
+    headerName: '메모리(%)',
+    width: 120,
+    type: 'number',
+    cellRenderer: (p: ICellRendererParams<Node>) =>
+      p.data ? (
+        <WarnCell value={p.data.memoryPercent} text={`${p.data.memoryPercent ?? ''}%`} />
+      ) : null,
+  },
+  {
+    field: 'gpu',
+    headerName: 'GPU(사용/전체)',
+    width: 140,
+    type: 'number',
+    valueFormatter: (p) => (p.data?.gpu ? `${p.data.gpu.used} / ${p.data.gpu.total}` : '-'),
+  },
+]
+
+export function ResourceDashboardPage({
+  fetchResources,
+}: {
+  fetchResources: (period: Period) => Promise<ResourceData>
+}) {
+  const [period, setPeriod] = useState<Period>('1h')
+  const [data, setData] = useState<ResourceData | undefined>() // undefined = 로딩 중, null = 데이터 없음
+  const [error, setError] = useState<string | null>(null)
+  const [updatedAt, setUpdatedAt] = useState<number | undefined>()
+  const [refreshing, setRefreshing] = useState(false)
+
+  const load = useCallback(() => {
+    setError(null)
+    setRefreshing(true)
+    fetchResources(period)
+      .then((d) => {
+        setData(d)
+        setUpdatedAt(Date.now())
+      })
+      .catch(() => setError('리소스 서버에 연결할 수 없습니다. (503 Service Unavailable)'))
+      .finally(() => setRefreshing(false))
+  }, [fetchResources, period])
+  useEffect(load, [load])
+
+  const now = updatedAt ?? Date.now()
+  const stats: DashboardStat[] | undefined = data
+    ? [
+        {
+          label: 'CPU 사용률',
+          value: pct(data.cpu.used / data.cpu.total),
+          caption: `${data.cpu.used} / ${data.cpu.total} 코어`,
+          ratio: data.cpu.used / data.cpu.total,
+          tone: tone(data.cpu.used / data.cpu.total),
+        },
+        {
+          label: '메모리 사용률',
+          value: pct(data.memory.used / data.memory.total),
+          caption: `${data.memory.used.toLocaleString()} / ${data.memory.total.toLocaleString()} GB`,
+          ratio: data.memory.used / data.memory.total,
+          tone: tone(data.memory.used / data.memory.total),
+        },
+        {
+          label: 'GPU 사용률',
+          value: pct(data.gpu.used / data.gpu.total),
+          caption: `${data.gpu.used} / ${data.gpu.total} 개 사용 중`,
+          ratio: data.gpu.used / data.gpu.total,
+          tone: tone(data.gpu.used / data.gpu.total),
+        },
+        { label: '실행 중 작업', value: `${data.runningJobs}개`, caption: '학습·추론·노트북 포함' },
+      ]
+    : undefined
+  const latest = data?.usage[data.usage.length - 1]
+  const peak = (pick: (p: UsagePoint) => number) => Math.max(...(data?.usage ?? []).map(pick))
+
+  return (
+    <DashboardLayout
+      title='리소스'
+      description='클러스터의 CPU·메모리·GPU 사용 현황과 노드 상태, 최근 이벤트를 확인합니다.'
+      titleRight={
+        <PageHeaderRefreshButton onClick={load} lastUpdatedAt={updatedAt} refreshing={refreshing} />
+      }
+      stats={stats}
+      loading={data === undefined && !error}
+      error={error}
+      onRetry={load}
+      empty={
+        data === null ? '클러스터에 노드가 등록되면 사용 현황이 여기에 나타납니다.' : undefined
+      }
+    >
+      <DashboardSection
+        title='사용률 추이'
+        columns={2}
+        action={
+          <ToggleGroup
+            type='single'
+            variant='outline'
+            aria-label='조회 기간'
+            value={period}
+            onValueChange={(v) => v && setPeriod(v as Period)}
+          >
+            {PERIODS.map((p) => (
+              <ToggleGroupItem key={p.value} value={p.value}>
+                {p.label}
+              </ToggleGroupItem>
+            ))}
+          </ToggleGroup>
+        }
+      >
+        <DashboardPanel
+          title='CPU 사용률'
+          value={latest ? latest.cpuPercent : undefined}
+          unit='%'
+          stats={data ? [{ label: '최고', value: `${peak((p) => p.cpuPercent)}%` }] : undefined}
+          loading={data === undefined}
+          empty={data && data.usage.length === 0 ? true : undefined}
+        >
+          {data?.usage.length ? (
+            <UsageChart points={data.usage} pick={(p) => p.cpuPercent} label='CPU 사용률' />
+          ) : null}
+        </DashboardPanel>
+        <DashboardPanel
+          title='메모리 사용률'
+          value={latest ? latest.memoryPercent : undefined}
+          unit='%'
+          stats={data ? [{ label: '최고', value: `${peak((p) => p.memoryPercent)}%` }] : undefined}
+          loading={data === undefined}
+          empty={data && data.usage.length === 0 ? true : undefined}
+        >
+          {data?.usage.length ? (
+            <UsageChart points={data.usage} pick={(p) => p.memoryPercent} label='메모리 사용률' />
+          ) : null}
+        </DashboardPanel>
+      </DashboardSection>
+
+      <DashboardSection title='노드'>
+        <AgGridTable
+          rowData={data?.nodes ?? []}
+          columnDefs={NODE_COLUMNS}
+          loading={data === undefined}
+          domLayout='autoHeight'
+        />
+      </DashboardSection>
+
+      <DashboardSection title='최근 이벤트 (최신 10개)'>
+        <EventList
+          items={(data?.events ?? []).slice(0, 10).map((e) => ({
+            id: e.id,
+            time: relative(e.time, now),
+            level: e.level,
+            message: e.message,
+          }))}
+        />
+      </DashboardSection>
+    </DashboardLayout>
+  )
+}