2950038b72
- 재무 대시보드 (finance-dashboard.md) - 일일자금일보 (daily-fund-report.md) - 자금계획일정 (fund-schedules.md) - 보유계좌관리 (bank-accounts.md) - 계좌입출금내역 (account-transactions.md) - README.md (전체 개요)
340 lines
11 KiB
Markdown
340 lines
11 KiB
Markdown
# 계좌입출금내역
|
||
|
||
## 개요
|
||
|
||
계좌입출금내역은 바로빌 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 기반 단일 페이지
|
||
```
|
||
|
||
## 라우트
|
||
|
||
### 웹 라우트
|
||
|
||
```php
|
||
// routes/web.php
|
||
Route::get('/finance/account-transactions', [EaccountController::class, 'index']);
|
||
```
|
||
|
||
### API 라우트
|
||
|
||
```php
|
||
// 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)
|
||
|
||
```php
|
||
// 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 네비게이션 시 전체 페이지 리로드 필수
|