sam-docs/features/finance/bank-accounts.md

보유계좌관리

개요

보유계좌관리는 회사의 은행계좌 정보를 중앙 집중식으로 관리하는 기능입니다. 계좌 등록/수정/삭제, 잔액 조회, 바로빌 연동 최신 잔액 업데이트를 지원합니다.

• 라우트: GET /finance/accounts
• 라우트 이름: finance.accounts.index
• UI 기술: Blade + HTMX

파일 구조

mng/
├── app/Http/Controllers/
│   ├── Finance/
│   │   └── BankAccountController.php           # 웹 컨트롤러
│   └── Api/Admin/
│       └── BankAccountController.php           # API 컨트롤러
├── app/Services/
│   └── BankAccountService.php                  # 비즈니스 로직
├── app/Models/Finance/
│   ├── BankAccount.php                         # 계좌 모델
│   └── BankTransaction.php                     # 거래내역 모델
└── resources/views/finance/accounts/
    ├── index.blade.php                         # 목록 페이지
    ├── create.blade.php                        # 등록 폼
    ├── edit.blade.php                          # 수정 폼
    ├── show.blade.php                          # 상세 (거래내역 포함)
    └── partials/
        └── table.blade.php                     # 테이블 partial (HTMX)

라우트

웹 라우트

// routes/web.php (finance prefix 그룹 내)
Route::get('/accounts', [BankAccountController::class, 'index'])->name('accounts.index');
Route::get('/accounts/create', [..., 'create'])->name('accounts.create');
Route::get('/accounts/{id}', [..., 'show'])->name('accounts.show');
Route::get('/accounts/{id}/edit', [..., 'edit'])->name('accounts.edit');

API 라우트

// routes/api.php (admin/bank-accounts prefix)
GET    /all                     → 전체 계좌 (드롭다운용)
GET    /summary                 → 요약 통계
GET    /                        → 목록 (페이지네이션)
POST   /                        → 신규 등록
GET    /{id}                    → 상세 조회
PUT    /{id}                    → 수정
DELETE /{id}                    → 삭제 (Soft Delete)
POST   /{id}/restore            → 복원
DELETE /{id}/force              → 영구 삭제 (슈퍼관리자만)
POST   /{id}/toggle-active      → 활성/비활성 토글
GET    /{id}/transactions       → 거래내역 조회
POST   /bulk-delete             → 일괄 삭제
POST   /bulk-restore            → 일괄 복원

컨트롤러

BankAccountController (웹)

메서드	설명	특이사항
index()	계좌 목록	HTMX 감지 → HX-Redirect (JS 실행 보장)
create()	등록 폼	-
show(id)	상세 + 거래내역	바로빌 거래 연동
edit(id)	수정 폼	404 에러 처리

서비스 클래스

BankAccountService

메서드	설명
getAccounts(filters, perPage)	목록 (페이지네이션) + 바로빌 최신 거래일
getAllAccounts()	모든 활성 계좌 (드롭다운용)
getStatsByBank()	은행별 통계
getAccountById(id, withTrashed)	단일 조회
createAccount(data)	신규 등록
updateAccount(account, data)	수정
deleteAccount(account)	Soft Delete
restoreAccount(account)	복원
forceDeleteAccount(account)	영구 삭제
toggleActive(account)	활성/비활성 토글
getTransactions(accountId, filters, perPage)	계좌별 거래내역
getSummary()	전체 요약 (총 계좌 수, 총 잔액)
bulkDelete(ids)	일괄 삭제
bulkRestore(ids)	일괄 복원

바로빌 연동: getAccounts() 실행 시 서브쿼리로 barobill_bank_transactions 테이블의 최신 거래 날짜/시간을 조회하여 계좌 데이터에 병합합니다.

// 계좌번호 매칭: 하이픈 제거
REPLACE(account_number, '-', '') = barobill_bank_transactions.bank_account_num

모델

BankAccount

테이블: bank_accounts

주요 필드

필드	타입	설명
tenant_id	bigint	테넌트 ID
bank_code	string	은행 코드 (000=한국은행, 020=우리은행 등)
bank_name	string	은행명
account_number	string	계좌번호 (하이픈 포함)
account_holder	string	예금주명
account_name	string	계좌 별칭
account_type	string	예금종류 (보통예금, 정기예금, 적금)
balance	decimal(15,2)	현재 잔액
currency	string	통화 (KRW)
opened_at	date	개설일자
last_transaction_at	datetime	최종 거래일시
branch_name	string	지점명
memo	text	메모
status	string	active / inactive
is_primary	boolean	대표계좌 여부
sort_order	int	정렬 순서

Traits

• BelongsToTenant - 테넌트 기반 자동 필터링
• SoftDeletes - Soft Delete 지원

주요 Scope

->active()       // status = 'active'
->primary()      // is_primary = true
->byBank($name)  // 은행별 필터
->byType($type)  // 예금종류별 필터
->ordered()      // sort_order 정렬

주요 Accessor

$account->formatted_balance       // "1억 2,345만원" 형식
$account->masked_account_number   // "110-***-5678"

뷰 구성

index.blade.php

┌─ 페이지 헤더 ──────────────────────
│  제목: "보유계좌관리"
│  버튼: "계좌 등록" (파란색)
│
├─ 요약 카드 (3열) ─────────────────
│  총 계좌 수 | 총 잔액 | 은행 수
│
├─ 테이블 컨테이너 ─────────────────
│  ├─ 헤더: 검색, 상태 필터
│  └─ HTMX 로드 영역 (#accounts-table)
│     └─ GET /admin/bank-accounts/
│
├─ partials/table.blade.php ────────
│  컬럼: 은행 | 계좌번호 | 예금종류 | 잔액 | 개설일자 | 최종처리일시 | 작업
│  ├─ 활성 항목: 수정/삭제 버튼
│  └─ 삭제된 항목: 복원/영구삭제 (opacity-50 bg-red-50)
│
└─ JavaScript: refreshAccountBalances()
   └─ GET /barobill/eaccount/latest-balances
   └─ DOM에서 잔액 실시간 업데이트

테이블 Partial 특징

컬럼	특이사항
은행	show/{id} 링크
예금종류	컬러 배지 (보통예금=파랑, 정기=보라, 적금=초록)
잔액	data-account-number 속성으로 동적 업데이트
최종처리일시	바로빌 거래일 또는 로컬 데이터
작업	HTMX 기반 토글/삭제/복원

데이터 흐름

사용자 (브라우저)
    ↓
BankAccountController::index()
    ↓
BankAccountService::getSummary()
    ↓ (bank_accounts: 총 계좌 수, 총 잔액)
View: finance/accounts/index
    ├─ 요약 카드 표시
    ├─ HTMX 테이블 로드
    │   ↓
    │   Api\Admin\BankAccountController
    │   ↓
    │   BankAccountService::getAccounts()
    │   │   ↓
    │   │   bank_accounts + 바로빌 최신 거래일 서브쿼리
    │   └─ JSON/HTML 반환
    │
    └─ refreshAccountBalances()
        ↓
        EaccountController::latestBalances()
        ↓
        barobill_bank_transactions (최신 잔액)
        ↓
        DOM 업데이트

데이터베이스 스키마

bank_accounts

마이그레이션: api/database/migrations/2025_12_17_120001_create_bank_accounts_table.php

CREATE TABLE bank_accounts (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    tenant_id BIGINT NOT NULL,
    bank_code VARCHAR(10),
    bank_name VARCHAR(50),
    account_number VARCHAR(50),
    account_holder VARCHAR(100),
    account_name VARCHAR(100),
    account_type VARCHAR(20),
    balance DECIMAL(15,2) DEFAULT 0,
    currency VARCHAR(3) DEFAULT 'KRW',
    opened_at DATE,
    last_transaction_at DATETIME,
    branch_name VARCHAR(100),
    memo TEXT,
    status VARCHAR(20) DEFAULT 'active',
    is_primary BOOLEAN DEFAULT FALSE,
    sort_order INT DEFAULT 0,
    created_by BIGINT, updated_by BIGINT, deleted_by BIGINT,
    created_at TIMESTAMP, updated_at TIMESTAMP, deleted_at TIMESTAMP
);

HTMX 호환성

• Blade + HTMX 기반 (HX-Redirect 사용 - JavaScript 있음)
• 테이블은 HTMX partial로 동적 로드
• 토글/삭제/복원 액션은 HTMX로 처리