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                # 메인 뷰
```

## 라우트

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

## 컨트롤러

### FinanceDashboardController

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

### index() 데이터 수집

```php
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 기능

```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()

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

### FundScheduleService::getSummary()

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

### FundScheduleService::getMonthlySummary()

```php
[
    '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()` 함수만 포함