sam-docs/dev/dev_plans/barobill-service-launch-plan.md

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

작성일: 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 환경 준비

# 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 호출 실패	잔액 모니터링 + 자동 알림

---

관련 문서

문서	설명
바로빌 연동 시스템	전체 구조, 모드, 과금
테넌트 온보딩	온보딩 6단계 프로세스
바로빌 API 명세	REST API 42개 엔드포인트
이관 현황	MNG→API+React 전체 이관 현황

---

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