# 바로빌 카드 사용내역 자동 동기화 스케줄러 추가

**날짜:** 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