docs: [barobill] 카드 자동 동기화 스케줄러 변경이력 추가
This commit is contained in:
김보곤
1
INDEX.md
1
INDEX.md
@@ -284,6 +284,7 @@ DB 도메인별:
|
||||
| [20260319_account_ledger_keyboard_navigation.md](changes/20260319_account_ledger_keyboard_navigation.md) | 계정별원장 계정과목 검색 키보드 방향키 네비게이션 추가 |
|
||||
| [20260319_condolence_dashboard_integration.md](changes/20260319_condolence_dashboard_integration.md) | 경조사비 대시보드 연동 (condolence_summary 필드 추가) |
|
||||
| [20260319_esign_salary_year_regex_fix.md](changes/20260319_esign_salary_year_regex_fix.md) | 전자계약 근로계약서 연봉계약종료연도 정규식 버그 수정 (두음법칙 불일치) |
|
||||
| [20260319_barobill_card_auto_sync.md](changes/20260319_barobill_card_auto_sync.md) | 바로빌 카드 사용내역 자동 동기화 스케줄러 추가 (2시간마다, 서버 crontab 필요) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
172
changes/20260319_barobill_card_auto_sync.md
Normal file
172
changes/20260319_barobill_card_auto_sync.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# 바로빌 카드 사용내역 자동 동기화 스케줄러 추가
|
||||
|
||||
**날짜:** 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
|
||||
Reference in New Issue
Block a user