# 바로빌 서비스 출시 단계별 준비 계획

> **작성일**: 2026-03-17
> **상태**: 계획 수립
> **담당**: R&D실

---

## 1. 개요

### 1.1 목적

MNG에서 운영 중인 바로빌 연동 시스템을 서비스(API+React)로 이관하여, 멀티테넌트 고객이 직접 사용할 수 있는 SaaS 형태로 출시한다.

### 1.2 현재 상태

- **MNG (백오피스)**: 바로빌 SOAP 연동 완료, tenant_id=1 (코드브릿지엑스)에서 실무 운영 중
- **API**: DB 모델 15개 + REST API 42개 엔드포인트 구현 완료 (데이터 조회/분개용)
- **React**: 바로빌 설정 페이지 기본 구현

### 1.3 목표

고객(테넌트)이 SAM 서비스에서 바로빌 기능을 직접 설정하고 사용할 수 있도록 한다:
- 계좌조회, 카드내역, 홈택스 세금계산서 자동 수집
- 전자세금계산서 발행
- 카카오톡/SMS 알림

---

## 2. 단계별 로드맵

```
Phase 1          Phase 2          Phase 3          Phase 4
SOAP 이관        UI 구현          베타테스트        정식 출시
(API 개발)       (React 개발)     (내부→외부)       (온보딩 가동)
───────────── → ───────────── → ───────────── → ─────────────
```

---

## 3. Phase 1: SOAP 연동 이관 (API 개발)

> **핵심**: MNG의 BarobillService를 API로 이관하여 멀티테넌트 지원

### 3.1 작업 목록

| # | 작업 | 상세 | 난이도 |
|---|------|------|--------|
| 1-1 | BarobillService 이관 | MNG 1,761줄 → API로 이동, 멀티테넌트 리팩토링 | 상 |
| 1-2 | 회원사 관리 API | 등록/수정/조회/상태확인 엔드포인트 | 중 |
| 1-3 | 인증서 관리 API | 등록URL/유효성/만료일 조회 엔드포인트 | 중 |
| 1-4 | 계좌 관리 API | 등록/목록/입출금 조회 엔드포인트 | 중 |
| 1-5 | 카드 관리 API | 등록/수정/해지/사용내역 조회 엔드포인트 | 중 |
| 1-6 | 세금계산서 발행 API | 작성/발행/조회 엔드포인트 | 상 |
| 1-7 | 동기화 스케줄러 | 은행/카드/홈택스 자동 수집 (Queue Job) | 중 |
| 1-8 | 테스트/운영 모드 전환 API | 회원사별 server_mode 전환 | 하 |

### 3.2 기술 과제

| 과제 | 설명 | 대응 방안 |
|------|------|----------|
| CERTKEY 관리 | 현재 전역 1개 → 멀티테넌트 대응 필요 | 바로빌 파트너 계약 구조 확인 후 결정 |
| PHP SOAP 확장 | API 서버에 `php-soap` 설치 필요 | Docker/서버 환경 확인 |
| 암호화 키 공유 | MNG/API 간 `APP_KEY` 동일해야 복호화 가능 | 현재 동일 키 사용 중 (확인 필요) |
| 동기화 부하 | 테넌트 수 증가 시 SOAP 호출량 증가 | Queue 분산, 호출 간격 조절 |

### 3.3 환경 준비

```bash
# API 서버에 PHP SOAP 확장 확인
php -m | grep soap

# 없으면 설치 (개발 서버 Level 2)
sudo apt install php8.4-soap
sudo systemctl restart php8.4-fpm

# .env 설정 추가
BAROBILL_CERT_KEY_TEST=<테스트 인증키>
BAROBILL_CERT_KEY_PROD=<운영 인증키>
BAROBILL_CORP_NUM=<파트너 사업자번호>
BAROBILL_TEST_MODE=true
```

---

## 4. Phase 2: UI 구현 (React 개발)

> **핵심**: 고객이 직접 바로빌을 설정하고 데이터를 조회할 수 있는 화면

### 4.1 작업 목록

| # | 작업 | 상세 | 난이도 |
|---|------|------|--------|
| 2-1 | 바로빌 설정 페이지 | 회원사 등록/수정, 서버 모드 표시 | 중 |
| 2-2 | 인증서 관리 화면 | 등록 URL 안내, 유효기간 표시, 갱신 알림 | 중 |
| 2-3 | 계좌 관리 화면 | 등록 계좌 목록, 등록 URL 안내 | 중 |
| 2-4 | 카드 관리 화면 | 등록 카드 목록, 추가/해지 | 중 |
| 2-5 | 카드 거래내역 조회 | 기간별 조회, 분개 연동, 숨김/분할 | 상 |
| 2-6 | 은행 거래내역 조회 | 기간별 조회, 분개 연동, 오버라이드/분할 | 상 |
| 2-7 | 홈택스 세금계산서 | 매출/매입 조회, 분개 연동 | 중 |
| 2-8 | 세금계산서 발행 화면 | 작성/발행 폼, 미리보기 | 상 |

### 4.2 화면 구성 (메뉴 구조)

```
재무관리
├─ 계좌관리
│  ├─ 보유계좌 관리 (바로빌 계좌 등록 포함)
│  └─ 계좌 입출금 내역
├─ 카드관리
│  ├─ 법인카드 관리 (바로빌 카드 등록 포함)
│  └─ 카드 사용내역
├─ 세금계산서
│  ├─ 매출 세금계산서
│  ├─ 매입 세금계산서
│  └─ 세금계산서 발행
└─ 설정
   └─ 바로빌 연동 설정 (인증서, 모드, 충전잔액)
```

---

## 5. Phase 3: 베타테스트

> **핵심**: 내부 → 외부 순서로 검증, 테스트 모드 사용

### 5.1 내부 베타테스트

| 항목 | 내용 |
|------|------|
| **대상** | tenant_id=1 (코드브릿지엑스 본사) |
| **기간** | 2주 |
| **모드** | 테스트 모드 |
| **검증 항목** | 전체 기능 동작, UI/UX, 데이터 정합성 |
| **비교 기준** | MNG 운영 데이터와 서비스 데이터 일치 확인 |

**내부 베타 체크리스트**:

- [ ] 회원사 등록/수정 정상 동작
- [ ] 인증서 등록 URL 정상 접근
- [ ] 계좌 등록 및 입출금 내역 조회
- [ ] 카드 등록 및 사용내역 조회
- [ ] 홈택스 매출/매입 세금계산서 수집
- [ ] 세금계산서 발행 (테스트 서버)
- [ ] 분개 연동 정상 동작
- [ ] 동기화 스케줄러 자동 수집 확인
- [ ] MNG 데이터와 서비스 데이터 일치

### 5.2 외부 베타테스트

| 항목 | 내용 |
|------|------|
| **대상** | 선별 고객사 2~3곳 |
| **기간** | 2~4주 |
| **모드** | 테스트 모드 |
| **검증 항목** | 실사용 시나리오, 다양한 사업자 유형, 피드백 수집 |

**외부 베타 체크리스트**:

- [ ] 다양한 사업자번호로 회원 등록
- [ ] 다양한 은행/카드사 연동 확인
- [ ] 고객 직접 인증서/계좌/카드 등록 가능 확인
- [ ] 고객 피드백 수집 및 반영
- [ ] 성능 (다수 테넌트 동시 동기화)

---

## 6. Phase 4: 정식 출시

> **핵심**: 운영 모드 전환, 과금 시작, 온보딩 프로세스 가동

### 6.1 출시 준비 체크리스트

**인프라**:
- [ ] API 서버 `php-soap` 확장 설치 확인
- [ ] 운영 `.env`에 `BAROBILL_CERT_KEY_PROD`, `BAROBILL_CORP_NUM` 설정
- [ ] `BAROBILL_TEST_MODE=false` 설정
- [ ] 동기화 스케줄러 Supervisor 등록
- [ ] 바로빌 운영 CERTKEY 충전잔액 확보

**과금**:
- [ ] `barobill_pricing_policies` 요금 정책 데이터 입력
- [ ] 월정액 구독 자동 과금 배치 등록 (매월 1일)
- [ ] 과금 내역 고객 조회 화면 (선택)

**운영**:
- [ ] 인증서 만료 알림 (이메일/카카오톡)
- [ ] 충전잔액 부족 알림
- [ ] 동기화 실패 알림 및 재시도 로직
- [ ] 바로빌 장애 시 대응 매뉴얼

### 6.2 온보딩 프로세스 정립

정식 출시 후 신규 고객 가입 시:

```
계약 → 테넌트 생성 → 회원등록(테스트) → 인증서/계좌/카드 → 검증 → 운영전환 → 실무사용
```

> 상세 프로세스: `features/barobill/tenant-onboarding.md` 참조

---

## 7. 바로빌 파트너 정책 확인 필요 사항

> **경고: 개발 착수 전 바로빌 측에 확인해야 할 사항**

| # | 확인 사항 | 이유 | 현재 상태 |
|---|----------|------|----------|
| 1 | 멀티테넌트 CERTKEY 구조 | 파트너 1개 키로 다수 회원사 관리 가능한지 | 미확인 |
| 2 | 테스트 서버 제한 | 테스트 API 호출 횟수/기간 제한 | 미확인 |
| 3 | 과금 구조 | 파트너 단가표 (건당/월정액) | 미확인 |
| 4 | SLA | 바로빌 API 가용성 보장 수준 | 미확인 |
| 5 | 회원사 대량 등록 | 일괄 등록 API 또는 제한 | 미확인 |
| 6 | 인증서 대리 등록 | 고객 대신 등록 가능 여부 | 미확인 |

---

## 8. 리스크 및 대응

| 리스크 | 영향 | 대응 |
|--------|------|------|
| 바로빌 API 장애 | 거래 데이터 수집 중단 | 재시도 로직 + 장애 알림 |
| 인증서 만료 | 계좌/세금계산서 조회 불가 | 만료 30일 전 알림 |
| SOAP 호출 지연 | 페이지 응답 지연 | 비동기 Queue 처리 |
| 테넌트 급증 | 동기화 부하 | 호출 간격 분산, 우선순위 큐 |
| 충전잔액 부족 | API 호출 실패 | 잔액 모니터링 + 자동 알림 |

---

## 관련 문서

| 문서 | 설명 |
|------|------|
| [바로빌 연동 시스템](../../features/barobill/README.md) | 전체 구조, 모드, 과금 |
| [테넌트 온보딩](../../features/barobill/tenant-onboarding.md) | 온보딩 6단계 프로세스 |
| [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | REST API 42개 엔드포인트 |
| [이관 현황](../../system/migration-status.md) | MNG→API+React 전체 이관 현황 |

---

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