sam-docs/features/finance/finance-dashboard.md

재무 대시보드

개요

재무 대시보드는 회사의 자금 현황을 한눈에 파악할 수 있는 종합 화면입니다. 총 잔액, 예정 수입/지출, 최근 거래내역, 계좌별 잔액 등을 요약하여 표시합니다.

• 라우트: GET /finance/dashboard
• 라우트 이름: finance.dashboard
• UI 기술: Blade + JavaScript (HTMX 불필요)

파일 구조

mng/
├── app/Http/Controllers/Finance/
│   └── FinanceDashboardController.php     # 메인 컨트롤러
├── app/Services/
│   ├── BankAccountService.php             # 계좌 데이터 서비스
│   └── FundScheduleService.php            # 자금일정 데이터 서비스
├── app/Models/
│   ├── Finance/
│   │   ├── BankAccount.php                # 계좌 모델
│   │   └── FundSchedule.php               # 자금일정 모델
│   └── Barobill/
│       ├── BankTransaction.php            # 바로빌 거래내역
│       ├── BankTransactionOverride.php    # 거래 수정 이력
│       └── CardTransaction.php            # 바로빌 카드거래
└── resources/views/finance/
    └── dashboard.blade.php                # 메인 뷰

라우트

// routes/web.php (finance prefix 그룹 내)
Route::get('/dashboard', [FinanceDashboardController::class, 'index'])->name('dashboard');

컨트롤러

FinanceDashboardController

메서드	HTTP	반환	설명
index()	GET	View	대시보드 메인 페이지

index() 데이터 수집

public function index(): View
{
    // 1. 계좌 요약 (총 잔액, 계좌 수)
    $accountSummary = $this->bankAccountService->getSummary();

    // 2. 자금일정 요약 (7일 내 일정 건수)
    $scheduleSummary = $this->fundScheduleService->getSummary();

    // 3. 이번 달 수입/지출 요약
    $monthlySummary = $this->fundScheduleService->getMonthlySummary($year, $month);

    // 4. 향후 7일 자금 일정
    $upcomingSchedules = $this->fundScheduleService->getUpcomingSchedules(7);

    // 5. 최근 7일 은행 거래내역 (최대 10건)
    $recentTransactions = BarobillBankTransaction::where(...)
        ->limit(10)->get();

    // 6. 최근 7일 카드 사용내역 (최대 10건)
    $recentCardTransactions = BarobillCardTransaction::where(...)
        ->limit(10)->get();

    // 7. 활성 계좌 잔액 목록
    $accountBalances = BankAccount::active()->ordered()->get();
}

뷰 구성

dashboard.blade.php

섹션	내용	데이터 소스
페이지 헤더	제목 + 현재 날짜 + 네비게이션 버튼	-
요약 카드 (4개)	총 잔액 / 예정 수입 / 예정 지출 / 7일내 일정	accountSummary, monthlySummary, scheduleSummary
월별 자금 일정 요약	수입/지출/순수익 (완료/예정 분리)	monthlySummary
계좌별 잔액 패널	활성 계좌 목록 + 잔액	accountBalances
향후 7일 자금 일정	예정 일정 (수입/지출 색상 구분)	upcomingSchedules
최근 거래내역	7일 은행 거래내역 테이블	recentTransactions
최근 카드 사용내역	7일 카드 거래 테이블	recentCardTransactions

JavaScript 기능

// 계좌 잔액 실시간 새로고침
function refreshAccountBalances() {
    // GET /barobill/eaccount/latest-balances
    // → 바로빌 DB에서 최신 잔액 조회
    // → DOM 업데이트 (잔액 수치 변경)
    // → 로딩/완료 상태 피드백
}

데이터 흐름

FinanceDashboardController::index()
│
├─ BankAccountService::getSummary()
│  └─ bank_accounts (총 계좌 수, 총 잔액, 은행별 그룹)
│
├─ FundScheduleService::getSummary()
│  └─ fund_schedules (예정 건수, 예정 수입/지출)
│
├─ FundScheduleService::getMonthlySummary()
│  └─ fund_schedules (월별 수입/지출, 완료/예정 분리)
│
├─ FundScheduleService::getUpcomingSchedules(7)
│  └─ fund_schedules (향후 7일 예정 일정)
│
├─ BarobillBankTransaction 조회
│  └─ barobill_bank_transactions (최근 7일, 10건)
│     └─ BankTransactionOverride 병합 (수정된 적요)
│
├─ BarobillCardTransaction 조회
│  └─ barobill_card_transactions (최근 7일, 10건)
│
└─ BankAccount::active()->ordered()
   └─ bank_accounts (계좌별 잔액)

서비스 반환 구조

BankAccountService::getSummary()

[
    'total_accounts' => int,           // 활성 계좌 수
    'total_balance' => float,          // 총 잔액
    'formatted_total_balance' => str,  // "1,000,000원"
    'by_bank' => [                     // 은행별 상세
        'bank_name' => ['count' => int, 'total' => float]
    ]
]

FundScheduleService::getSummary()

[
    'pending_count' => int,      // 예정 건수
    'pending_income' => float,   // 예정 수입
    'pending_expense' => float,  // 예정 지출
    'upcoming_7days' => int      // 7일 내 일정 건수
]

FundScheduleService::getMonthlySummary()

[
    'year' => int, 'month' => int,
    'total_count' => int,
    'income' => [
        'count' => int, 'total' => float,
        'pending' => float, 'completed' => float
    ],
    'expense' => [
        'count' => int, 'total' => float,
        'pending' => float, 'completed' => float
    ],
    'net' => float  // 순수익 (수입 - 지출)
]

관련 데이터베이스 테이블

테이블	용도
bank_accounts	계좌 잔액, 계좌 수 통계
fund_schedules	자금 일정 요약, 예정 수입/지출
barobill_bank_transactions	최근 은행 거래내역
barobill_card_transactions	최근 카드 사용내역
barobill_bank_transaction_overrides	거래 수정 이력 병합

HTMX 호환성

• 순수 Blade 템플릿 (복잡한 JavaScript 없음)
• HX-Redirect 불필요
• JavaScript는 refreshAccountBalances() 함수만 포함