Merge branch 'main' of http://114.203.209.83:3000/SamProject/sam-docs

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

@@ -0,0 +1,242 @@
+# 바로빌 서비스 출시 단계별 준비 계획
+
+> **작성일**: 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