SamProject/sam-docs

Fork 0

Files

김보곤 6484e73976 docs: [barobill] 카드 자동 동기화 스케줄러 변경이력 추가

2026-03-19 19:20:33 +09:00

5.3 KiB

Raw Blame History

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

날짜: 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. 스케줄 설정

// 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 커맨드

# 전체 테넌트 동기화 (기본 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 스케줄러를 추가해야 한다:

# /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 등)

5.3 KiB Raw Blame History