173 lines
5.3 KiB
Markdown
173 lines
5.3 KiB
Markdown
# 바로빌 카드 사용내역 자동 동기화 스케줄러 추가
|
|
|
|
**날짜:** 2026-03-19
|
|
**작업자:** Claude Code
|
|
|
|
---
|
|
|
|
## 변경 개요
|
|
|
|
바로빌 카드 사용내역을 자동으로 동기화하는 스케줄러를 추가했다.
|
|
|
|
### 배경
|
|
|
|
- 기존: 사용자가 바로빌 카드 UI(`/barobill/ecard`)에서 수동으로 "조회 → 저장"해야만 DB에 반영됨
|
|
- 문제: 일반전표입력 화면에서 카드사용내역을 가져올 때, 바로빌에 새 거래가 있어도 DB에 없으면 누락됨
|
|
- 해결: 2시간마다 바로빌 SOAP API에서 최근 7일 카드 거래를 자동 동기화
|
|
|
|
---
|
|
|
|
## 수정된 파일
|
|
|
|
| 파일 | 변경 내용 |
|
|
|------|----------|
|
|
| `mng/app/Services/Barobill/BarobillCardSyncService.php` | 카드 거래 자동 동기화 서비스 (신규) |
|
|
| `mng/app/Console/Commands/SyncBarobillCardTransactions.php` | `barobill:sync-cards` Artisan 커맨드 (신규) |
|
|
| `mng/routes/console.php` | 스케줄러 등록 (2시간마다, 08~22시) |
|
|
|
|
---
|
|
|
|
## 상세 변경 사항
|
|
|
|
### 1. 동기화 흐름
|
|
|
|
```
|
|
스케줄러 (2시간마다, 08~22시)
|
|
↓ barobill:sync-cards --days=7
|
|
BarobillCardSyncService::syncAll()
|
|
↓ BarobillMember 테이블에서 전체 테넌트 조회
|
|
↓ 테넌트별:
|
|
│ ├─ initFromConfig() — SOAP 클라이언트 초기화 (CARD.asmx)
|
|
│ ├─ getRegisteredCards() — GetCardEx2 SOAP 호출
|
|
│ └─ 카드별:
|
|
│ ├─ fetchTransactions() — GetPeriodCardApprovalLog SOAP 호출
|
|
│ └─ upsertTransactions() — DB에 Upsert
|
|
↓
|
|
barobill_card_transactions 테이블
|
|
├─ 신규 거래 → 자동 생성 (사용자 입력 필드는 null)
|
|
└─ 기존 거래 → 바로빌 원본 필드만 갱신
|
|
```
|
|
|
|
### 2. Upsert 정책
|
|
|
|
#### 고유 키 (기존과 동일)
|
|
|
|
```
|
|
tenant_id + card_num + use_dt + approval_num + approval_amount
|
|
```
|
|
|
|
#### 신규 거래 (DB에 없는 건)
|
|
|
|
바로빌 원본 데이터로 생성. 사용자 입력 필드는 비워둠:
|
|
|
|
| 자동 설정 | 비워두는 필드 (사용자가 나중에 입력) |
|
|
|----------|--------------------------------------|
|
|
| `card_num`, `use_dt`, `approval_amount` | `account_code` (계정과목) |
|
|
| `merchant_name`, `tax` 등 | `account_name` |
|
|
| | `deduction_type` (공제/불공제) |
|
|
| | `modified_supply_amount` |
|
|
| | `description`, `evidence_name` |
|
|
|
|
#### 기존 거래 (DB에 이미 있는 건)
|
|
|
|
바로빌 원본 필드만 갱신, **사용자 편집 필드 보존**:
|
|
|
|
```
|
|
✅ 갱신 대상: merchant_name, merchant_biz_num, merchant_addr, memo 등
|
|
❌ 보존 대상: account_code, account_name, deduction_type, modified_supply_amount, description
|
|
```
|
|
|
|
### 3. 스케줄 설정
|
|
|
|
```php
|
|
// routes/console.php
|
|
Schedule::command('barobill:sync-cards --days=7')
|
|
->everyTwoHours()
|
|
->between('08:00', '22:00')
|
|
->withoutOverlapping();
|
|
```
|
|
|
|
| 항목 | 값 |
|
|
|------|------|
|
|
| 실행 주기 | 2시간마다 |
|
|
| 실행 시간 | 08:00 ~ 22:00 (영업시간) |
|
|
| 동기화 범위 | 최근 7일 |
|
|
| 중복 방지 | `withoutOverlapping()` |
|
|
|
|
### 4. Artisan 커맨드
|
|
|
|
```bash
|
|
# 전체 테넌트 동기화 (기본 7일)
|
|
php artisan barobill:sync-cards
|
|
|
|
# 특정 테넌트만
|
|
php artisan barobill:sync-cards --tenant=1
|
|
|
|
# 기간 조정
|
|
php artisan barobill:sync-cards --days=30
|
|
|
|
# Docker 로컬 실행
|
|
docker exec sam-mng-1 php artisan barobill:sync-cards --days=30
|
|
```
|
|
|
|
---
|
|
|
|
## 서버 설정 필요 사항
|
|
|
|
> **경고: MNG 스케줄러가 서버에서 실행되려면 crontab 등록이 필요하다.**
|
|
|
|
현재 서버에 **API 스케줄러만** 등록되어 있다. MNG 스케줄러를 추가해야 한다:
|
|
|
|
```bash
|
|
# /etc/crontab에 추가 (개발서버 + 운영서버 모두)
|
|
* * * * * hskwon cd /home/webservice/mng && php artisan schedule:run >> /dev/null 2>&1
|
|
```
|
|
|
|
**현재 등록 현황:**
|
|
|
|
```
|
|
✅ * * * * * hskwon cd /home/webservice/api && php artisan schedule:run ← 기존
|
|
❌ * * * * * hskwon cd /home/webservice/mng && php artisan schedule:run ← 미등록
|
|
```
|
|
|
|
> 미등록 시 MNG의 모든 스케줄 작업이 실행되지 않음:
|
|
> - `attendance:mark-absent` (매일 23:50 자동 결근)
|
|
> - `barobill:sync-cards` (2시간마다 카드 동기화)
|
|
|
|
---
|
|
|
|
## 동작 확인 결과 (2026-03-19)
|
|
|
|
| 테넌트 | 모드 | 카드 수 | DB 기존 건수 | 동기화 결과 |
|
|
|--------|------|---------|-------------|-----------|
|
|
| 1 (본사) | production | 5 | 156 | 신규 0, 갱신 0 (이미 동기화) |
|
|
| 290 | test | 2 | 0 | 거래 없음 |
|
|
| 289 | test | 2 | 0 | 거래 없음 |
|
|
| 287 | test | 2 | 0 | 거래 없음 |
|
|
|
|
---
|
|
|
|
## 아키텍처 참고
|
|
|
|
### 기존 동기화 서비스와의 비교
|
|
|
|
| 항목 | BarobillBankSyncService (계좌) | BarobillCardSyncService (카드) |
|
|
|------|-------------------------------|-------------------------------|
|
|
| SOAP 엔드포인트 | `BANKACCOUNT.asmx` | `CARD.asmx` |
|
|
| 조회 메서드 | `GetPeriodBankAccountTransLog` | `GetPeriodCardApprovalLog` |
|
|
| 목록 메서드 | `GetBankAccountEx` | `GetCardEx2` |
|
|
| 캐시 전략 | `BankSyncStatus` 테이블 (월별 캐시) | 없음 (매 실행 시 조회) |
|
|
| 트리거 | 화면 조회 시 자동 (`syncIfNeeded`) | 스케줄러 자동 (2시간) |
|
|
| 사용자 필드 | 없음 | 보존 (account_code 등) |
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- [바로빌 연동 시스템](../features/barobill/README.md)
|
|
- [바로빌 API SOAP 참조](../features/barobill/api-soap-reference.md)
|
|
|
|
---
|
|
|
|
**최종 업데이트**: 2026-03-19
|