# 자금일보 바로빌 자동동기화 및 계정과목 데이터 정리

**날짜:** 2026-03-11
**작업자:** Claude Code

---

## 변경 개요

두 가지 문제를 수정한다:

1. **자금일보 출금 내역 누락** — `periodReport()`가 DB 캐시만 조회하고 바로빌 API 동기화를 트리거하지 않아, 최신 거래내역이 반영되지 않는 문제
2. **홈택스 분개 계정과목 오류** — 드롭다운에 2,549개 코드 표시(정상: 163개), 분개 기본값에 존재하지 않는 코드 사용

---

## 수정된 파일

| 파일 | 프로젝트 | 변경 내용 |
|------|---------|----------|
| `app/Services/Barobill/BarobillBankSyncService.php` | MNG (신규) | 바로빌 계좌 거래내역 동기화 서비스 |
| `app/Http/Controllers/Finance/DailyFundController.php` | MNG | `periodReport()`에 자동 동기화 호출 추가 |
| `resources/views/barobill/hometax/index.blade.php` | MNG | 분개 기본 계정과목 코드 수정 |
| `database/migrations/2026_03_11_101502_fix_account_codes_duplicate_data.php` | API (신규) | 중복 계정과목 비활성화 + 분개 코드 일괄 수정 |

---

## 상세 변경 사항

### 1. 바로빌 자동 동기화 서비스 (MNG)

**문제**: `DailyFundController::periodReport()`는 `barobill_bank_transactions` 테이블만 조회한다. 바로빌 API에서 데이터를 가져오는 동기화는 `EaccountController`에서만 수행되어, 자금일보 페이지에서는 캐시가 갱신되지 않으면 최신 거래가 누락된다.

**해결**: `EaccountController`의 동기화 로직을 `BarobillBankSyncService`로 분리하여 재사용 가능하게 한다.

```
DailyFundController::periodReport()
    │
    ├── BarobillBankSyncService::syncIfNeeded()  ← 신규
    │   ├── BarobillMember 조회 (바로빌 인증)
    │   ├── SOAP 클라이언트 초기화
    │   ├── 등록 계좌 목록 조회
    │   └── 월별 청크 순회
    │       ├── BankSyncStatus 캐시 판단
    │       │   ├── 과거 월: 항상 캐시 (API 호출 안 함)
    │       │   └── 현재 월: 10분 이내면 캐시
    │       └── 필요 시 API 호출 → DB 캐시 저장
    │
    └── DB에서 거래내역 조회 (기존 로직)
```

**캐시 정책**:

| 조건 | 동작 |
|------|------|
| 과거 월 + 동기화 이력 있음 | 캐시 사용 (API 호출 안 함) |
| 현재 월 + 10분 이내 동기화 | 캐시 사용 |
| 현재 월 + 10분 초과 | API에서 갱신 |
| 동기화 이력 없음 | API에서 갱신 |

**실패 처리**: 동기화 실패 시 예외를 catch하고 로그만 남기며, 기존 DB 캐시로 응답을 계속한다.

---

### 2. 계정과목 중복 데이터 정리 (API 마이그레이션)

**문제**: `account_codes` 테이블에 비표준 코드가 대량 등록되어 드롭다운이 오염되었다.

| 코드 유형 | 건수 | 예시 | 상태 |
|----------|------|------|------|
| 3자리 더존 표준 코드 | 163개 | `101` 현금, `108` 외상매출금 | ✅ 정상 |
| 5자리 KIS 코드 (중복) | ~2,290개 | `10100` Cash, `10800` Accounts Receivable | ❌ 비활성화 |
| 1~2자리 카테고리 헤더 | ~96개 | `1` Assets, `10` Current Assets | ❌ 비활성화 |

**해결**: `LENGTH(code) != 3`인 코드를 `is_active = false`로 비활성화한다. 데이터는 삭제하지 않으며 필요 시 복원 가능하다.

---

### 3. 홈택스 분개 기본 코드 수정

**문제**: `getDefaultLines()` 함수에서 하드코딩된 계정과목 코드가 실제 DB 코드와 불일치한다.

| 거래 유형 | 항목 | 기존 코드 | 수정 코드 | 비고 |
|----------|------|----------|----------|------|
| 매출 | 부가세예수금 | `255` (장기미지급금) | `208` | 코드 불일치 |
| 매입 | 부가세대급금 | `135` (미존재) | `117` | DB에 없는 코드 |
| 매입 | 외상매입금 | `251` (장기차입금) | `201` | 코드 불일치 |
| 매입 | 적요명 | 상품매입 | 상품매출원가 | `501` 코드에 맞는 명칭 |

**API 마이그레이션으로 기존 분개 데이터도 일괄 수정**:

```sql
-- 135 → 117 (부가세대급금)
UPDATE hometax_invoice_journals SET account_code='117', account_name='부가세대급금' WHERE account_code='135';

-- 251 → 201 (외상매입금)
UPDATE hometax_invoice_journals SET account_code='201' WHERE account_code='251' AND account_name='외상매입금';

-- 255 → 208 (부가세예수금)
UPDATE hometax_invoice_journals SET account_code='208' WHERE account_code='255' AND account_name='부가세예수금';
```

---

## 배포

| 프로젝트 | 커밋 | develop | main |
|---------|------|---------|------|
| MNG | `ca36e8e5` (동기화 서비스), `afa64280` (계정과목 수정) | ✅ 푸시 완료 | ✅ 체리픽 완료 |
| API | `6f48b86` (데이터 마이그레이션) | ✅ 푸시 완료 | ✅ 체리픽 완료 |

Jenkins가 양쪽 서버에서 자동 배포 및 마이그레이션 실행을 완료했다.

---

## 테스트 체크리스트

- [x] 로컬 DB에서 `account_codes` 비표준 코드 비활성화 확인
- [x] 바로빌 동기화 후 2026-03-10 거래내역 10건 정상 조회
- [x] 홈택스 분개 기본값에 올바른 코드(`117`, `201`, `208`) 반영
- [x] 개발 서버 마이그레이션 실행 확인
- [x] 운영 서버 마이그레이션 자동 실행 확인

---

## 관련 문서

- [재무 관리](../../features/finance/README.md)
- [DB 스키마 - 재무](../../system/database/finance.md)

---

**최종 업데이트**: 2026-03-11
