Overview

목적

테이블오더 가맹점의 정산 현황을 한 화면에서 빠르게 파악하고, 기간별 매출·수수료·정산 예정액 및 개별 정산 내역을 확인하는 관리자용 운영 콘솔입니다.

브랜드 톤은 별도 지정이 없으므로, 신뢰감 있는 금융 운영 도구 + 빠르게 읽히는 데이터 중심 UI를 기준으로 설계합니다.

핵심 사용자

• 가맹점 운영 관리자
• 본사 정산·재무 담당자
• 매출 및 지급 상태를 확인하는 CS 담당자

핵심 사용자 플로우

1. 정산 대시보드 진입
2. 기간 필터 선택
   • 오늘
   • 최근 7일
   • 최근 30일
   • 직접 선택
3. 총 매출·수수료·정산 예정액 확인
4. 일별 매출 추이 확인
5. 최근 정산 내역에서 특정 행 선택
6. 우측 상세 패널에서 정산 구성 및 상태 확인
7. 필요 시 보류 사유, 지급 예정일, 거래 상세 확인

---

Component Tree

SettlementDashboardPage
├─ AppShell
│  ├─ SidebarNavigation
│  │  ├─ BrandLogo
│  │  ├─ MainNavigation
│  │  ├─ SettingsLink
│  │  └─ ThemeToggle
│  └─ TopBar
│     ├─ Breadcrumb
│     ├─ PageTitle
│     └─ UserMenu
│
├─ DashboardContent
│  ├─ PageHeader
│  │  ├─ PageHeading
│  │  ├─ LastUpdatedText
│  │  └─ RefreshButton
│  │
│  ├─ SettlementFilterBar
│  │  ├─ PresetPeriodTabs
│  │  │  ├─ PeriodTab: 오늘
│  │  │  ├─ PeriodTab: 7일
│  │  │  ├─ PeriodTab: 30일
│  │  │  └─ PeriodTab: 직접 선택
│  │  ├─ DateRangePicker
│  │  └─ ApplyButton
│  │
│  ├─ SettlementMetricGrid
│  │  ├─ MetricCard: 총 매출
│  │  ├─ MetricCard: 수수료
│  │  └─ MetricCard: 정산 예정액
│  │
│  ├─ DailyRevenueSection
│  │  ├─ SectionHeader
│  │  ├─ ChartLegend
│  │  ├─ RevenueLineChart
│  │  │  ├─ ChartGrid
│  │  │  ├─ ChartTooltip
│  │  │  └─ ChartEmptyState
│  │  └─ ChartSummary
│  │
│  └─ RecentSettlementSection
│     ├─ SectionHeader
│     ├─ SettlementTable
│     │  ├─ SettlementTableHeader
│     │  ├─ SettlementTableBody
│     │  │  └─ SettlementTableRow
│     │  │     ├─ MerchantCell
│     │  │     ├─ AmountCell
│     │  │     ├─ SettlementDateCell
│     │  │     └─ StatusBadge
│     │  └─ SettlementTableFooter
│     └─ TableEmptyState
│
└─ SettlementDetailDrawer
   ├─ DrawerOverlay
   ├─ DrawerHeader
   │  ├─ DrawerTitle
   │  └─ CloseButton
   ├─ SettlementSummary
   │  ├─ MerchantName
   │  ├─ SettlementStatusBadge
   │  └─ SettlementAmount
   ├─ SettlementMetaList
   │  ├─ SettlementId
   │  ├─ SettlementPeriod
   │  ├─ ExpectedPaymentDate
   │  └─ CompletedDate
   ├─ SettlementBreakdown
   │  ├─ GrossSalesRow
   │  ├─ CommissionRow
   │  ├─ AdjustmentsRow
   │  └─ NetSettlementRow
   ├─ HoldReasonAlert
   └─ DrawerFooter

재사용 컴포넌트

• Button
• IconButton
• Badge
• Card
• DateRangePicker
• DataTable
• Drawer
• Tooltip
• Skeleton
• EmptyState
• ErrorState
• VisuallyHidden
• CurrencyText
• StatusBadge

---

Design Tokens

색상 시스템

브랜드 포인트 컬러는 신뢰감을 해치지 않는 딥 인디고 + 앰버 포인트를 권장합니다.

Light mode

토큰	값	용도
background	#F6F7F9	전체 배경
surface	#FFFFFF	카드, 테이블, 패널
surface-subtle	#F0F2F5	입력 영역, 보조 배경
text-primary	#18202B	주요 텍스트
text-secondary	#667085	보조 텍스트
text-tertiary	#98A2B3	비활성 텍스트
border	#E4E7EC	기본 경계선
brand	#303B70	주요 액션, 활성 상태
brand-hover	#252F5D	브랜드 hover
revenue	#3B6FB6	매출 그래프
success	#16794C	완료
success-bg	#E7F6EE	완료 배지 배경
warning	#A15C00	대기
warning-bg	#FFF3D6	대기 배지 배경
danger	#B42318	오류, 보류
danger-bg	#FEECEB	보류 배지 배경

Dark mode

토큰	값	용도
background	#10141C	전체 배경
surface	#171D27	카드, 테이블, 패널
surface-subtle	#202936	입력 영역, hover
text-primary	#F3F5F7	주요 텍스트
text-secondary	#AAB4C2	보조 텍스트
text-tertiary	#768397	비활성 텍스트
border	#2B3544	기본 경계선
brand	#98A7F2	주요 액션
brand-hover	#B0BCFF	브랜드 hover
revenue	#78A9EB	매출 그래프
success	#73D6A1	완료
success-bg	#153A2A	완료 배지 배경
warning	#F2BD62	대기
warning-bg	#453314	대기 배지 배경
danger	#F08B83	보류
danger-bg	#461F21	보류 배지 배경

상태는 색상만으로 구분하지 않고 반드시 텍스트를 함께 표시합니다.

• 대기: 시계 아이콘 + 대기
• 완료: 체크 아이콘 + 완료
• 보류: 느낌표 아이콘 + 보류

Typography

권장 폰트:

font-family:
  "Pretendard Variable",
  "Noto Sans KR",
  system-ui,
  sans-serif;

토큰	크기	굵기	용도
display-sm	28px / 36px	700	페이지 핵심 숫자
heading-lg	22px / 30px	700	페이지 제목
heading-md	18px / 26px	700	섹션 제목
body-lg	16px / 24px	500	강조 본문
body-md	14px / 22px	400	기본 본문
body-sm	13px / 20px	400	보조 정보
label	12px / 18px	600	필드명, 배지
caption	11px / 16px	500	타임스탬프

금액은 숫자 정렬을 위해 font-variant-numeric: tabular-nums를 적용합니다.

Spacing

4px 기반 스케일을 사용합니다.

space-1: 4px
space-2: 8px
space-3: 12px
space-4: 16px
space-5: 20px
space-6: 24px
space-8: 32px
space-10: 40px
space-12: 48px
space-16: 64px

주요 레이아웃 간격:

• 페이지 좌우 여백: 데스크톱 40px, 태블릿 24px, 모바일 16px
• 섹션 간격: 32px
• 카드 내부 패딩: 24px
• 테이블 셀 패딩: 16px 20px
• 폼 컨트롤 간격: 12px

Radius / Elevation

radius-sm: 6px
radius-md: 10px
radius-lg: 14px
radius-pill: 999px

• 카드: radius-lg
• 버튼, 입력: radius-md
• 상태 배지: radius-pill
• 테이블: 외곽 radius-lg, 내부 행은 radius 사용하지 않음

그림자는 최소화합니다.

shadow-panel:
0 8px 24px rgba(16, 24, 40, 0.12)

shadow-focus:
0 0 0 3px rgba(48, 59, 112, 0.22)

---

Interaction Rules

기간 필터

• 기본 선택값: 최근 30일
• 선택된 탭은 브랜드 컬러 배경 또는 명확한 하단 인디케이터로 표시
• 직접 선택 선택 시 날짜 범위 선택기 노출
• 시작일이 종료일보다 늦으면 인라인 오류 표시
• 미래 날짜는 선택 불가
• 날짜 범위 변경 시 그래프와 테이블을 함께 갱신

메트릭 카드

각 카드에는 다음 정보를 표시합니다.

• 지표명
• 금액
• 전 기간 대비 증감률
• 증감 방향 아이콘
• 비교 기준 텍스트

예시:

총 매출
₩24,580,000
↑ 12.4% 지난 30일 대비

증감률은 색상만으로 전달하지 않습니다.

• 상승: 상승 12.4%
• 하락: 하락 8.2%
• 변화 없음: 변동 없음

그래프

• 선 그래프의 기본 포인트는 마우스 hover 또는 키보드 focus 시 표시
• 툴팁에는 날짜, 매출액, 전일 대비 증감률 표시
• 포인트 간 연결선은 2px
• 주요 값은 탭 또는 화살표 키로 탐색 가능
• 데이터가 많은 경우 x축 라벨을 자동 축약
• 모바일에서는 그래프를 가로 스크롤 가능하게 하되, 핵심 범례는 고정

테이블

• 전체 행은 클릭 가능한 영역
• hover 시 배경색 변화
• 키보드 focus 시 2px outline
• 행 클릭 시 우측 상세 패널 열림
• 상태 배지는 텍스트를 포함
• 금액은 우측 정렬
• 사업자명은 좌측 정렬
• 테이블 헤더는 스크롤 시 고정 가능

상세 사이드 패널

• 데스크톱: 우측에서 440px 너비로 진입
• 모바일: 화면 하단에서 올라오는 full-width sheet
• 닫기 방법:
  • 닫기 버튼
  • Escape
  • 오버레이 클릭
• 패널 진입 시 첫 번째 제목 또는 닫기 버튼에 focus 이동
• 패널 종료 후 기존 테이블 행으로 focus 복귀

전환 규칙

fast: 120ms ease-out
normal: 180ms cubic-bezier(0.22, 1, 0.36, 1)
drawer: 240ms cubic-bezier(0.22, 1, 0.36, 1)

적용 대상:

• 버튼 hover: 120ms
• 배지 및 필터 상태: 120ms
• drawer 진입·퇴장: 240ms
• 페이지 초기 카드 등장: 180ms씩 순차 노출

prefers-reduced-motion: reduce 환경에서는 transform 및 opacity 애니메이션을 제거합니다.

---

State Handling

Loading

초기 로딩 시 레이아웃을 유지하는 skeleton을 사용합니다.

• 메트릭 카드: 라벨 skeleton + 숫자 skeleton
• 그래프: 축 영역 유지 + 그래프 skeleton
• 테이블: 5개 행 skeleton
• 필터: 비활성화하지 않고 현재 선택값 유지

Loading state:
- aria-busy="true"
- 화면 전환 없이 skeleton 표시
- 8초 이상 지연 시 "데이터를 불러오는 중입니다" 메시지 표시

Empty

매출 데이터 없음

선택한 기간의 매출 데이터가 없습니다.
다른 기간을 선택하면 매출 추이를 확인할 수 있습니다.

액션: 기간 다시 선택

정산 내역 없음

최근 정산 내역이 없습니다.
정산이 생성되면 이곳에서 지급 상태를 확인할 수 있습니다.

필터가 적용된 상태라면 선택한 기간도 함께 안내합니다.

Error

전체 API 오류

정산 데이터를 불러오지 못했습니다.
잠시 후 다시 시도해 주세요.

액션: 다시 시도

부분 오류

그래프 오류가 테이블까지 차단하지 않도록 독립적으로 처리합니다.

매출 추이를 불러오지 못했습니다.

액션: 다시 시도

상세 패널 오류

행 기본 정보는 유지하고 상세 정보 영역에 오류 표시:

상세 정산 정보를 불러오지 못했습니다.

Edge states

• 정산 예정액이 0원인 경우: ₩0 표시
• 수수료가 없는 경우: ₩0
• 금액이 매우 큰 경우: 축약하지 않고 전체 금액 표시
• 가맹점명이 긴 경우: 1줄 ellipsis + tooltip
• 동일 날짜 데이터가 여러 건이면 일별 합산
• 보류 상태는 보류 사유와 문의 안내를 함께 표시
• 데이터가 한 건뿐이면 그래프에 단일 포인트와 안내 문구 표시
• 정산 상태가 알 수 없는 값이면 확인 필요로 fallback
• 세션 만료 시 현재 필터를 유지한 채 로그인 안내 표시

---

Accessibility Notes

Contrast

• 본문 텍스트 대비율 WCAG AA 이상
• 작은 텍스트는 최소 4.5:1
• 큰 텍스트는 최소 3:1
• 상태 배지는 배경색과 텍스트의 대비를 별도로 검증
• 그래프 선은 색상 외에 포인트, tooltip, 표 형태의 대체 정보를 제공

Keyboard navigation

권장 탭 순서:

1. 사이드바 메뉴
2. 기간 필터
3. 날짜 선택기
4. 새로고침 버튼
5. 메트릭 카드의 보조 링크
6. 그래프 데이터 포인트
7. 테이블 행
8. 상세 패널 컨트롤

지원 키:

• Tab / Shift + Tab: 포커스 이동
• Enter / Space: 버튼, 탭, 테이블 행 실행
• Arrow keys: 그래프 포인트 탐색
• Escape: drawer 및 날짜 선택기 닫기

ARIA

<section aria-labelledby="settlement-title">
  <h1 id="settlement-title">정산 대시보드</h1>
</section>

• 탭: role="tablist", role="tab", aria-selected
• 그래프: role="img" 또는 접근 가능한 차트 라이브러리 사용
• 테이블: 실제 <table> 요소 사용
• 테이블 행: tabindex="0" 및 aria-label
• drawer: role="dialog", aria-modal="true
• 로딩 영역: aria-busy="true
• 오류 메시지: role="alert
• 성공·갱신 안내: aria-live="polite"

색맹 사용자를 위해 상태 아이콘과 텍스트를 항상 함께 제공합니다.

---

Frontend Mapping

추천 구조

src/
├─ app/
│  └─ settlements/
│     └─ page.tsx
├─ components/
│  ├─ layout/
│  │  ├─ AppShell.tsx
│  │  ├─ SidebarNavigation.tsx
│  │  └─ TopBar.tsx
│  ├─ settlement/
│  │  ├─ SettlementFilterBar.tsx
│  │  ├─ SettlementMetricGrid.tsx
│  │  ├─ SettlementMetricCard.tsx
│  │  ├─ DailyRevenueChart.tsx
│  │  ├─ RecentSettlementTable.tsx
│  │  ├─ SettlementTableRow.tsx
│  │  └─ SettlementDetailDrawer.tsx
│  └─ ui/
│     ├─ Badge.tsx
│     ├─ Button.tsx
│     ├─ Card.tsx
│     ├─ Drawer.tsx
│     ├─ Skeleton.tsx
│     └─ EmptyState.tsx
├─ hooks/
│  ├─ useSettlementFilters.ts
│  └─ useSettlementDetail.ts
├─ lib/
│  ├─ formatCurrency.ts
│  └─ settlementApi.ts
└─ types/
   └─ settlement.ts

주요 타입

type SettlementStatus = "pending" | "completed" | "on_hold";

type SettlementPeriod = "today" | "7d" | "30d" | "custom";

interface SettlementSummary {
  totalRevenue: number;
  commission: number;
  expectedSettlement: number;
  revenueChangeRate: number;
  commissionChangeRate: number;
  settlementChangeRate: number;
}

interface SettlementRecord {
  id: string;
  merchantName: string;
  amount: number;
  status: SettlementStatus;
  settlementDate: string;
  expectedPaymentDate?: string;
  holdReason?: string;
}

interface DailyRevenue {
  date: string;
  revenue: number;
}

컴포넌트 Props

interface SettlementFilterBarProps {
  period: SettlementPeriod;
  startDate?: Date;
  endDate?: Date;
  onPeriodChange: (period: SettlementPeriod) => void;
  onDateChange: (range: { start: Date; end: Date }) => void;
  onApply: () => void;
}

interface SettlementMetricCardProps {
  label: string;
  amount: number;
  changeRate?: number;
  comparisonLabel?: string;
  tone?: "neutral" | "positive" | "negative";
  loading?: boolean;
}

interface StatusBadgeProps {
  status: SettlementStatus;
  size?: "sm" | "md";
}

interface SettlementDetailDrawerProps {
  settlementId?: string;
  open: boolean;
  onClose: () => void;
}

Tailwind 예시 매핑

<div className="grid grid-cols-1 gap-4 md:grid-cols-3">
  <SettlementMetricCard />
  <SettlementMetricCard />
  <SettlementMetricCard />
</div>

<aside
  className="
    fixed inset-y-0 right-0 z-50 w-full max-w-[440px]
    border-l border-border bg-surface
    shadow-panel transition-transform duration-200
    data-[open=false]:translate-x-full
    md:block
  "
  role="dialog"
  aria-modal="true"
>
  <SettlementDetailDrawer />
</aside>

상태 배지는 cva 또는 유사한 variant 시스템으로 관리합니다.

const statusBadgeVariants = cva(
  "inline-flex items-center gap-1 rounded-full px-2 py-1 text-xs font-semibold",
  {
    variants: {
      status: {
        pending: "bg-warning-bg text-warning",
        completed: "bg-success-bg text-success",
        on_hold: "bg-danger-bg text-danger",
      },
    },
  }
);

---

Implementation Notes

Layout System

Desktop

• 전체 화면: display: grid
• 사이드바: 240px 고정
• 콘텐츠: minmax(0, 1fr)
• 콘텐츠 최대 너비: 1440px
• 콘텐츠 내부 좌우 패딩: 40px
• 메트릭 카드: 3열
• 그래프와 테이블: 기본 1열 수직 배치
• 상세 drawer가 열려도 본문 폭은 유지하고 drawer가 위에 표시

Desktop ≥ 1280px
Sidebar 240px | Main content fluid
Main max-width: 1440px

Tablet

• 사이드바를 축소형 또는 상단 네비게이션으로 전환
• 콘텐츠 패딩: 24px
• 메트릭 카드 3열 유지 가능
• 테이블은 수평 스크롤 허용

Mobile

• 사이드바는 drawer 메뉴로 전환
• 콘텐츠 패딩: 16px
• 메트릭 카드: 1열 또는 가로 스크롤 카드
• 필터 탭: 수평 스크롤
• 날짜 선택기: 전체 폭
• 그래프: 최소 너비 640px의 가로 스크롤 영역
• 테이블은 카드형 행으로 재구성하거나 수평 스크롤
• 상세 정산 패널: 하단 sheet, 화면 높이 최대 90%

데이터 및 캐싱

• 필터가 변경되면 summary, chart, table을 동일한 query key로 관리
• React Query 또는 SWR 사용 권장
• 마지막 성공 데이터를 유지한 채 백그라운드 갱신
• 새로고침 버튼은 중복 요청 방지
• 금액 포맷은 서버 원본 숫자를 기준으로 클라이언트에서 처리

const formatCurrency = (value: number) =>
  new Intl.NumberFormat("ko-KR", {
    style: "currency",
    currency: "KRW",
    maximumFractionDigits: 0,
  }).format(value);

구현 우선순위

1. 기간 필터와 API query state
2. 메트릭 카드
3. 정산 테이블 및 상태 배지
4. 상세 drawer와 focus 관리
5. 매출 그래프
6. loading / empty / error 상태
7. 다크모드
8. 반응형 및 접근성 검증

완료 기준

• 모든 기간 필터가 URL 또는 전역 상태와 동기화됨
• 선택 기간에 따라 카드·그래프·테이블이 일관되게 갱신됨
• 테이블 행 클릭 및 키보드 실행으로 상세 패널이 열림
• drawer close 후 원래 행으로 focus 복귀
• 상태값이 색상·아이콘·텍스트로 함께 표현됨
• light/dark mode에서 대비 기준 충족
• 모바일에서 핵심 정산 정보와 상세 내역 확인 가능
• 로딩·빈 상태·오류·보류 상태가 각각 독립적으로 처리됨