sam-docs/features/finance/account-transactions.md

계좌입출금내역

개요

계좌입출금내역은 바로빌 SOAP API를 통해 은행 거래내역을 실시간으로 조회하고, 회계 분류(계정과목 지정), 분개(1거래→N계정과목), 수동 거래 등록 등을 지원하는 기능입니다.

• 라우트: GET /finance/account-transactions
• UI 기술: React 18 + Babel (브라우저 트랜스파일링)
• 컨트롤러: EaccountController (1,772줄)

파일 구조

mng/
├── app/Http/Controllers/Barobill/
│   └── EaccountController.php               # 메인 컨트롤러 (1772줄, 16개+ 메서드)
├── app/Models/Barobill/
│   ├── BankTransaction.php                  # 바로빌 거래내역 모델
│   ├── BankTransactionOverride.php          # 거래 수정(적요/내용)
│   ├── BankTransactionSplit.php             # 거래 분개
│   ├── AccountCode.php                      # 계정과목 마스터
│   ├── BarobillConfig.php                   # 바로빌 API 설정
│   └── BarobillMember.php                   # 테넌트별 바로빌 연동 정보
└── resources/views/barobill/eaccount/
    └── index.blade.php                      # React 기반 단일 페이지

라우트

웹 라우트

// routes/web.php
Route::get('/finance/account-transactions', [EaccountController::class, 'index']);

API 라우트

// routes/web.php (barobill/eaccount prefix)
GET    /accounts              → 등록된 계좌 목록 (바로빌)
GET    /latest-balances       → 계좌별 최신 잔액 (DB)
GET    /transactions          → 거래내역 조회 (API + DB 병합)
GET    /account-codes         → 계정과목 목록 (테넌트별)
GET    /account-codes/all     → 전체 계정과목
POST   /account-codes         → 계정과목 등록
PUT    /account-codes/{id}    → 계정과목 수정
DELETE /account-codes/{id}    → 계정과목 삭제
POST   /save                  → 거래 저장 (회계 분류)
GET    /export                → Excel 내보내기
POST   /save-override         → 거래 적요/내용 수정
POST   /manual                → 수동 거래 등록
PUT    /manual/{id}           → 수동 거래 수정
DELETE /manual/{id}           → 수동 거래 삭제
GET    /splits                → 분개 내역 조회
POST   /splits                → 분개 저장
DELETE /splits                → 분개 삭제

컨트롤러

EaccountController

메서드	HTTP	설명
__construct()	-	SOAP 클라이언트 초기화 (BarobillConfig)
index()	GET	React 페이지 렌더링 (HX-Redirect 적용)
accounts()	GET	바로빌 등록 계좌 목록
latestBalances()	GET	DB 기반 최신 잔액
transactions()	GET	거래내역 조회 (API + DB 병합)
accountCodes()	GET	계정과목 목록
accountCodesAll()	GET	전체 계정과목
accountCodeStore()	POST	계정과목 등록
accountCodeUpdate()	PUT	계정과목 수정
accountCodeDestroy()	DELETE	계정과목 삭제
save()	POST	거래 저장 (계정과목 지정)
exportExcel()	GET	Excel 내보내기
saveOverride()	POST	적요/내용 수정 (override)
storeManual()	POST	수동 거래 등록
updateManual()	PUT	수동 거래 수정
destroyManual()	DELETE	수동 거래 삭제
splits()	GET	분개 내역 조회
saveSplits()	POST	분개 저장
deleteSplits()	DELETE	분개 삭제

바로빌 SOAP API 연동

설정 구조

BarobillConfig (barobill_configs 테이블)
├─ environment: 'test' 또는 'production'
├─ cert_key: 인증서 키
├─ corp_num: 법인번호
└─ base_url: SOAP URL

BarobillMember (barobill_members 테이블)
├─ tenant_id: 테넌트별 분리
├─ barobill_id: 바로빌 로그인 ID
├─ barobill_pwd: 암호화된 비밀번호
└─ server_mode: 'test' 또는 'production' (테넌트별)

사용 SOAP 메서드

WSDL	메서드	기능
BANKACCOUNT.asmx	GetBankAccountEx	등록된 계좌 목록
BANKACCOUNT.asmx	GetPeriodBankAccountTransLog	기간별 거래내역 조회

에러 코드

코드	의미
-25005	데이터 없음 (정상)
-25001	데이터 없음 (정상)
기타	에러 메시지 반환

핵심 로직

거래내역 조회 흐름 (transactions)

React 컴포넌트 (날짜/계좌 선택)
    ↓
GET /barobill/eaccount/transactions
    ↓
1. BarobillMember 조회 (barobill_id)
    ↓
2. 테넌트별 서버 모드 적용
   └─ BarobillConfig 재로드 → SOAP 클라이언트 재초기화
    ↓
3. [단일 계좌 조회]
   ├─ DB 조회: barobill_bank_transactions (저장된 데이터)
   ├─ SOAP 호출: GetPeriodBankAccountTransLog
   ├─ Override 데이터 병합 (수정된 적요)
   ├─ 수동 거래 병합 (중복 제거)
   ├─ 분개 데이터 병합
   ├─ 잔액 재계산 (기간 전 잔액 기준)
   └─ 정렬 (최신순) + 페이지네이션
    ↓
4. [전체 계좌 조회]
   ├─ GetBankAccountEx로 계좌 목록 조회
   ├─ 각 계좌별로 3번 반복
   └─ 모든 거래 병합 및 정렬
    ↓
5. JSON 응답

거래 고유 키 (unique_key)

// BankTransaction 모델
return implode('|', [
    $this->bank_account_num,
    $this->trans_dt,          // 거래일시
    (int) $this->deposit,
    (int) $this->withdraw,
    (int) $this->balance,
]);

분개 저장 흐름

React (분개 모달)
    ↓
POST /barobill/eaccount/splits
{
    originalUniqueKey: "계좌번호|거래일시|입금|출금|잔액",
    originalData: { bankAccountNum, transDate, ... },
    splits: [
        { amount: 50000, accountCode: "1000", accountName: "당좌예금" },
        { amount: 50000, accountCode: "2000", accountName: "미수금" }
    ]
}
    ↓
기존 분개 삭제 → 새 분개 생성 × N

Override 저장 로직

POST /barobill/eaccount/save-override
{
    uniqueKey: "거래 고유 키",
    modifiedSummary: "수정된 적요",
    modifiedCast: "수정된 내용"
}
    ↓
BankTransactionOverride::saveOverride()
  → 둘 다 null이면 delete
  → 아니면 upsert

모델

BankTransaction (Barobill)

테이블: barobill_bank_transactions

필드	설명
tenant_id	테넌트 ID
bank_account_num	계좌번호 (하이픈 없음)
bank_code / bank_name	은행 코드/명
trans_date	거래일 (YYYYMMDD)
trans_time	거래시간 (HHMMSS)
trans_dt	거래일시 (trans_date + trans_time)
deposit / withdraw	입금액 / 출금액
balance	거래 후 잔액
summary / cast	적요 / 내용
account_code / account_name	계정과목 코드/명
is_manual	수동 입력 여부

BankTransactionOverride

테이블: barobill_bank_transaction_overrides

필드	설명
unique_key	거래 고유 키
modified_summary	수정된 적요
modified_cast	수정된 내용

BankTransactionSplit

테이블: barobill_bank_transaction_splits

필드	설명
original_unique_key	원본 거래 고유 키
split_amount	분개 금액
account_code / account_name	계정과목
description / memo	설명 / 메모
sort_order	정렬 순서
bank_account_num / trans_dt / trans_date	원본 거래 정보
original_deposit / original_withdraw	원본 금액

AccountCode

테이블: account_codes

필드	설명
code	계정과목 코드 (예: "1000")
name	계정과목명 (예: "당좌예금")
category	분류 (자산, 부채, 자본 등)
sort_order	정렬 순서
is_active	활성 여부

BarobillConfig

테이블: barobill_configs

필드	설명
name	설정명
environment	'test' 또는 'production'
cert_key	바로빌 인증서 키
corp_num	법인번호
is_active	활성 여부

BarobillMember

테이블: barobill_members

필드	설명
tenant_id	테넌트 ID
biz_no	사업자번호
barobill_id / barobill_pwd	바로빌 로그인 정보
server_mode	'test' 또는 'production'
status	active / inactive / pending

뷰 구성 (React)

index.blade.php

┌─ 테넌트 정보 카드 (Blade) ──────────
│  회사명, 사업자번호, 바로빌 ID
│  바로빌 미연동 경고 (조건부)
│
├─ React 앱 (#eaccount-root) ─────────
│  ├─ 계좌 선택 드롭다운
│  ├─ 기간 선택 (이번달, 지난달, D-2~5월 버튼)
│  │
│  ├─ 통계 카드 ──────────
│  │  총 입금 | 총 출금 | 거래 건수
│  │
│  ├─ 거래 테이블 ────────
│  │  번호 | 거래일시 | 적요 | 입금 | 출금 | 잔액 | 계정과목
│  │  ├─ 인라인 편집 (적요, 계정과목)
│  │  ├─ 수동 거래: 보라색 표시
│  │  ├─ 숨긴 거래: 회색 처리
│  │  └─ 분개된 거래: 파란색 표시
│  │
│  ├─ 수동 거래 등록 모달 ──
│  │  날짜, 시간, 입금/출금, 금액, 적요, 계정과목
│  │
│  ├─ 분개 모달 ──────────
│  │  원본 거래 정보 → N개 분개 항목
│  │
│  └─ 내보내기/저장 버튼
│
└─ API 엔드포인트 상수 (Blade에서 정의)

React 주요 기능

기능	설명
계좌별 조회	드롭다운에서 계좌 선택
기간 선택	월 단위 버튼 (이번달 ~ D-5월)
인라인 편집	적요, 계정과목 직접 수정
분개	1거래 → N계정과목 분할
수동 입력	API 미제공 거래 추가
거래 숨김	특정 거래 숨기기/복원
Excel 내보내기	조회 데이터 다운로드
잔액 재계산	기간 전 잔액 기준 자동 계산

데이터베이스 테이블 요약

테이블	역할	마이그레이션 (API)
barobill_bank_transactions	거래내역 저장	2026_01_23_130000_...
barobill_bank_transaction_overrides	적요/내용 수정	2026_02_06_095159_...
barobill_bank_transaction_splits	분개 데이터	2026_02_06_200000_...
account_codes	계정과목 마스터	-
barobill_members	테넌트별 연동 정보	-
barobill_configs	API 설정 (환경별)	-

HTMX 호환성

• React 기반 페이지이므로 HX-Redirect 필요
• @push('scripts') 블록에 React/Babel 스크립트 포함
• HTMX 네비게이션 시 전체 페이지 리로드 필수