From 6484e7397683fa6d7b513099efc34f325d67f48e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Thu, 19 Mar 2026 19:20:33 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[barobill]=20=EC=B9=B4=EB=93=9C=20?= =?UTF-8?q?=EC=9E=90=EB=8F=99=20=EB=8F=99=EA=B8=B0=ED=99=94=20=EC=8A=A4?= =?UTF-8?q?=EC=BC=80=EC=A4=84=EB=9F=AC=20=EB=B3=80=EA=B2=BD=EC=9D=B4?= =?UTF-8?q?=EB=A0=A5=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- INDEX.md | 1 + changes/20260319_barobill_card_auto_sync.md | 172 ++++++++++++++++++++ 2 files changed, 173 insertions(+) create mode 100644 changes/20260319_barobill_card_auto_sync.md diff --git a/INDEX.md b/INDEX.md index ecd0e11..7487234 100644 --- a/INDEX.md +++ b/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 필요) | --- diff --git a/changes/20260319_barobill_card_auto_sync.md b/changes/20260319_barobill_card_auto_sync.md new file mode 100644 index 0000000..cf3fca3 --- /dev/null +++ b/changes/20260319_barobill_card_auto_sync.md @@ -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