sam-docs/dev/dev_plans/barobill-full-migration-plan.md

# 바로빌 전체 서비스 이관 계획

> **작성일**: 2026-03-22
> **상태**: 이관 진행 중
> **담당**: R&D실

---

## 1. 개요

### 1.1 목적

MNG의 바로빌 관련 **전체** 회계/통신 기능을 API+React 서비스로 이관한다. 기존 출시 계획(`barobill-service-launch-plan.md`)은 Phase 1~4 로드맵이며, 이 문서는 **MNG 코드 단위의 상세 이관 추적**에 집중한다.

### 1.2 이관 원칙

```
✅ MNG 코드는 수정/삭제하지 않는다 (독립 운영 유지)
✅ API에 독립적으로 새로 구현한다 (SOAP 포함)
✅ 같은 DB(samdb)를 공유하되, 각각 독립 SOAP 호출
✅ 멀티테넌트(tenant_id) 격리 필수
```

---

## 2. 이관 현황 요약

### 2.1 영역별 상태

| # | 영역 | MNG | API | 상태 | 우선순위 |
|---|------|:---:|:---:|:----:|:--------:|
| 1 | SOAP 연동 서비스 (BarobillSoapService) | ✅ 1,761줄 | ✅ 57개 메서드 | ✅ 완료 | — |
| 2 | 바로빌 설정 (Config/Setting) | ✅ | ✅ BarobillSettingController | ✅ 완료 | — |
| 3 | 회원사 관리 (Member) | ✅ 32.6KB | ✅ BarobillSyncController | ✅ 완료 | — |
| 4 | 계좌 조회 (EAccount) | ✅ 83.8KB | ✅ BankTransaction + SyncService | ✅ 완료 | — |
| 5 | 카드 조회 (ECard) | ✅ 91.2KB | ✅ CardTransaction + SyncService | ✅ 완료 | — |
| 6 | 홈택스 매입/매출 (Hometax) | ✅ 79.7KB | ✅ HometaxInvoice + SyncService | ✅ 완료 | — |
| 7 | 자동 동기화 스케줄러 | ✅ (MNG 크론) | ✅ SyncBarobillDataJob | ✅ 완료 | — |
| 8 | 전자세금계산서 발행 (ETax) | ✅ EtaxController | ✅ TaxInvoiceController + BarobillService SOAP 발행/취소/상태 | ✅ 완료 | — |
| 9 | 카카오톡 발송 | ✅ KakaotalkController 14.5KB | ✅ BarobillKakaotalkController (12 EP) | ✅ 완료 | — |
| 10 | SMS 발송 | ✅ SmsController | ✅ BarobillSmsController (4 EP) | ✅ 완료 | — |
| 11 | 구독/과금 비즈니스 로직 | ✅ BillingService 8.4KB | ✅ BillingService + Controller (9 EP) | ✅ 완료 | — |
| 12 | 사용량 관리 | ✅ UsageService 9.6KB + Controller | ✅ UsageService + Controller (4 EP) | ✅ 완료 | — |

### 2.2 구현율

```
완료: 12/12 영역 (100%) — 전체 이관 완료
```

> **2026-03-22**: MNG 바로빌 기능 전체 API 이관 완료.

> **2026-03-22 정정**: 세금계산서 발행은 `BarobillService`에 `issueTaxInvoice()`, `cancelTaxInvoice()`, `checkNtsSendStatus()` SOAP 연동이 완전 구현되어 있음을 확인. P1→완료로 재분류.

---

## 3. ~~P1: 전자세금계산서~~ → ✅ 완료 확인 (2026-03-22)

API `BarobillService`에 SOAP 발행/취소/상태조회가 완전 구현됨:
- `issueTaxInvoice()` → SOAP `RegistAndIssueTaxInvoice`
- `cancelTaxInvoice()` → SOAP `CancelTaxInvoice`
- `checkNtsSendStatus()` → SOAP `GetTaxInvoiceState`
- `TaxInvoiceController` — 16개 엔드포인트 (CRUD + 발행/취소/일괄/상태/분개)
- `TaxInvoice` 모델 — 5단계 상태 (draft→issued→sent→cancelled/failed)

---

## 4. P1: 카카오톡/SMS 발송 (1순위 — 즉시 착수)

### 4.1 현재 상태

**API BarobillSoapService에 SOAP 메서드 구현 완료:**
- 카카오톡: 15개 메서드 (채널, 템플릿, 알림톡, 친구톡, 결과조회, 예약취소)
- SMS: 4개 메서드 (발송, 발신번호 확인/목록, 상태조회)

**미구현:** Controller, Service, Route

### 4.2 이관 작업 목록

| # | 작업 | 상세 |
|---|------|------|
| 9-1 | KakaotalkController 생성 | 채널/템플릿 조회, 발송, 이력, 예약취소 API |
| 9-2 | KakaotalkService 생성 | 발송 로직, 이력 저장, 예약 관리 |
| 9-3 | SmsController 생성 | 발송, 발신번호 관리, 상태 조회 API |
| 9-4 | SmsService 생성 | 발송 로직, 이력 관리 |
| 9-5 | Route 등록 | `routes/api/v1/finance.php`에 추가 |
| 9-6 | 발송 이력 테이블 (선택) | 발송 기록 저장 필요 시 마이그레이션 |

### 4.3 MNG 참조 파일

```
mng/app/Http/Controllers/Barobill/KakaotalkController.php   (14.5KB)
mng/app/Http/Controllers/Barobill/SmsController.php
mng/app/Http/Controllers/Api/Admin/Barobill/BarobillKakaotalkController.php
mng/app/Http/Controllers/Api/Admin/Barobill/BarobillSmsController.php
```

### 4.4 MNG 엔드포인트 → API 매핑

**카카오톡:**

| MNG 엔드포인트 | API 대응 | 상태 |
|---------------|---------|:----:|
| `GET /api/admin/barobill/kakaotalk/channels` | `GET /v1/barobill/kakaotalk/channels` | ❌ |
| `GET /api/admin/barobill/kakaotalk/channels/management-url` | `GET /v1/barobill/kakaotalk/channels/management-url` | ❌ |
| `GET /api/admin/barobill/kakaotalk/templates` | `GET /v1/barobill/kakaotalk/templates` | ❌ |
| `POST /api/admin/barobill/kakaotalk/send` | `POST /v1/barobill/kakaotalk/send` | ❌ |
| `GET /api/admin/barobill/kakaotalk/send-history` | `GET /v1/barobill/kakaotalk/history` | ❌ |
| `DELETE /api/admin/barobill/kakaotalk/send/{sendKey}/cancel` | `DELETE /v1/barobill/kakaotalk/{sendKey}` | ❌ |

**SMS:**

| MNG 엔드포인트 | API 대응 | 상태 |
|---------------|---------|:----:|
| `POST /api/admin/barobill/sms/send` | `POST /v1/barobill/sms/send` | ❌ |
| `GET /api/admin/barobill/sms/from-numbers` | `GET /v1/barobill/sms/from-numbers` | ❌ |
| `POST /api/admin/barobill/sms/check-from-number` | `POST /v1/barobill/sms/check-from-number` | ❌ |
| `GET /api/admin/barobill/sms/send-state/{sendKey}` | `GET /v1/barobill/sms/{sendKey}/status` | ❌ |

---

## 5. P2: 구독/과금/사용량 (2순위)

### 5.1 현재 상태

**API에 있는 것 (모델/마이그레이션만):**
- `BarobillSubscription` — 월정액 구독
- `BarobillBillingRecord` — 과금 기록
- `BarobillMonthlySummary` — 월별 요약
- `BarobillPricingPolicy` — 가격 정책

**미구현:** Controller, Service (비즈니스 로직)

### 5.2 이관 작업 목록

| # | 작업 | 상세 |
|---|------|------|
| 11-1 | BillingService 생성 | 구독 CRUD, 월별 과금 처리, 사용량 기반 과금 |
| 11-2 | BillingController 생성 | 구독 관리, 과금 기록 조회, 요약 |
| 11-3 | UsageService 생성 | 서비스별 사용량 집계, 통계 |
| 11-4 | UsageController 생성 | 사용량 목록, 통계, 내보내기 |
| 11-5 | 월별 과금 배치 Job | 매월 1일 자동 과금 처리 |
| 11-6 | Route 등록 | admin 영역 또는 v1 영역 |

### 5.3 MNG 참조 파일

```
mng/app/Services/Barobill/BarobillBillingService.php   (8.4KB)
mng/app/Services/Barobill/BarobillUsageService.php     (9.6KB → 실제 13.95KB)
mng/app/Http/Controllers/Api/Admin/Barobill/BarobillBillingController.php  (15.2KB)
mng/app/Http/Controllers/Api/Admin/Barobill/BarobillUsageController.php    (9.6KB)
```

---

## 6. 코드 매핑 전체표

### 6.1 MNG → API 파일 대응

| MNG 파일 | API 파일 | 상태 |
|----------|---------|:----:|
| **Services** | | |
| `Services/Barobill/BarobillService.php` (1,761줄) | `Services/Barobill/BarobillSoapService.php` | ✅ |
| `Services/Barobill/BarobillBankSyncService.php` | `Services/Barobill/BarobillBankSyncService.php` | ✅ |
| `Services/Barobill/BarobillCardSyncService.php` | `Services/Barobill/BarobillCardSyncService.php` | ✅ |
| `Services/Barobill/HometaxSyncService.php` | `Services/Barobill/HometaxSyncService.php` | ✅ |
| `Services/Barobill/BarobillBillingService.php` | `Services/Barobill/BarobillBillingService.php` | ✅ 완료 |
| `Services/Barobill/BarobillUsageService.php` | `Services/Barobill/BarobillUsageService.php` | ✅ 완료 |
| **Controllers (Web)** | | |
| `Controllers/Barobill/EaccountController.php` | `Controllers/Api/V1/BarobillBankTransactionController.php` | ✅ |
| `Controllers/Barobill/EcardController.php` | `Controllers/Api/V1/BarobillCardTransactionController.php` | ✅ |
| `Controllers/Barobill/HometaxController.php` | `Controllers/Api/V1/HometaxInvoiceController.php` | ✅ |
| `Controllers/Barobill/EtaxController.php` | `Controllers/Api/V1/TaxInvoiceController.php` | ✅ 완료 |
| `Controllers/Barobill/KakaotalkController.php` | `Controllers/Api/V1/BarobillKakaotalkController.php` | ✅ 완료 |
| `Controllers/Barobill/SmsController.php` | `Controllers/Api/V1/BarobillSmsController.php` | ✅ 완료 |
| `Controllers/Barobill/BarobillController.php` | `Controllers/Api/V1/BarobillController.php` | ✅ |
| **Controllers (Admin API)** | | |
| `Api/Admin/Barobill/BarobillConfigController.php` | `Controllers/Api/V1/BarobillSettingController.php` | ✅ |
| `Api/Admin/Barobill/BarobillMemberController.php` | `Controllers/Api/V1/BarobillSyncController.php` | ✅ |
| `Api/Admin/Barobill/BarobillSettingController.php` | `Controllers/Api/V1/BarobillSettingController.php` | ✅ |
| `Api/Admin/Barobill/BarobillBillingController.php` | `Controllers/Api/V1/BarobillBillingController.php` | ✅ 완료 |
| `Api/Admin/Barobill/BarobillUsageController.php` | `Controllers/Api/V1/BarobillUsageController.php` | ✅ 완료 |
| `Api/Admin/Barobill/BarobillKakaotalkController.php` | `Controllers/Api/V1/BarobillKakaotalkController.php` | ✅ 완료 |
| `Api/Admin/Barobill/BarobillSmsController.php` | `Controllers/Api/V1/BarobillSmsController.php` | ✅ 완료 |
| **Models (18개)** | | |
| `Models/Barobill/*` (18개) | `Models/Barobill/*` (17개) + `Models/Tenants/BarobillSetting` | ✅ |

### 6.2 SOAP 메서드 구현율

| 카테고리 | MNG | API | 구현율 | 비고 |
|---------|:---:|:---:|:------:|------|
| CORPSTATE (회원관리) | 3 | 3 | 100% | ✅ |
| BANKACCOUNT (계좌) | 13 | 14 | 100%+ | ✅ |
| CARD (카드) | 11 | 11 | 100% | ✅ |
| TI (세금계산서) | 3 | 3 | 100% | ⚠️ URL 조회만, 발행 로직 P1 |
| KAKAOTALK (카카오톡) | 15 | 15 | 100% | ❌ Controller 미구현 P2 |
| SMS (문자) | 4 | 4 | 100% | ❌ Controller 미구현 P2 |
| **합계** | **49** | **50** | **100%** | SOAP은 완료, Controller/Route가 부족 |

---

## 7. 작업 순서

### Phase A: P1 — 카카오톡/SMS (즉시 착수)

```
1. MNG KakaotalkController/SmsController 분석
2. API KakaotalkController + KakaotalkService 생성
3. API SmsController + SmsService 생성
4. Route 등록 (finance.php)
5. 발송 이력 테이블 필요 시 마이그레이션
6. 테스트
```

### Phase B: P2 — 구독/과금/사용량 (P1 완료 후)

```
1. BillingService + BillingController 생성
2. UsageService + UsageController 생성
3. 월별 과금 배치 Job 생성
4. Route 등록
5. 테스트
```

---

## 8. 진행 기록

| 날짜 | 작업 | 결과 |
|------|------|------|
| 2026-03-22 | 전체 이관 현황 조사 및 문서화 | 이 문서 작성 |
| 2026-03-22 | 세금계산서 발행 이관 상태 재확인 | 이미 완료 확인 (P1→완료) |
| 2026-03-22 | 카카오톡/SMS API 이관 (P1) | ✅ Controller 2개 + Route 16개 생성 |
| 2026-03-22 | 구독/과금/사용량 API 이관 (P2) | ✅ Service 2개 + Controller 2개 + Route 13개 생성 |

---

## 관련 문서

| 문서 | 설명 |
|------|------|
| [바로빌 연동 시스템](../../features/barobill/README.md) | 전체 구조, 모드, 과금, 멀티테넌트 |
| [바로빌 API SOAP 참조](../../features/barobill/api-soap-reference.md) | SOAP 57개 메서드, 동기화, MNG 대응표 |
| [바로빌 출시 계획](./barobill-service-launch-plan.md) | 4단계 출시 로드맵 |
| [바로빌 회계 API 명세](../../frontend/api-specs/barobill-api.md) | REST API 42개 엔드포인트 |
| [이관 현황](../../system/migration-status.md) | MNG→API+React 전체 이관 현황 |

---

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