# 바로빌 테넌트 온보딩 프로세스

> **작성일**: 2026-03-17
> **상태**: 설계 중 (서비스 이관 준비)

---

## 1. 온보딩(Onboarding)이란

### 1.1 정의

**온보딩**: 새로운 고객(테넌트)이 서비스에 가입하여 실제 사용을 시작하기까지의 초기 설정 과정.

SAM 바로빌 맥락에서는 **정식 계약 고객이 바로빌 연동 기능(계좌조회, 카드내역, 세금계산서 등)을 실무에서 사용할 수 있도록 초기 세팅하는 일련의 절차**를 의미한다.

### 1.2 온보딩 vs 베타테스트

| 구분 | 온보딩 | 베타테스트 |
|------|--------|----------|
| **대상** | 정식 계약 고객 | 서비스 출시 전 검증 참여자 |
| **목적** | 고객이 기능을 쓸 수 있게 초기 세팅 | 서비스 안정성/기능 검증 |
| **시점** | 고객 가입할 때마다 반복 발생 | 서비스 출시 전 1회성 |
| **테스트 모드** | 초기 세팅 확인용으로 잠깐 사용 가능 | 전체 기간 테스트 모드로 운영 |
| **데이터** | 실제 업무 데이터 | 검증용 테스트 데이터 |
| **과금** | 정식 과금 (운영 모드 전환 후) | 무과금 |

### 1.3 단계별 관계

서비스 이관 완료 후 다음 순서로 진행한다:

```
서비스 이관 (개발)
  └─ 베타테스트 (출시 전 검증)
      └─ 정식 출시
          └─ 테넌트 온보딩 (고객 가입 시마다 반복)
```

---

## 2. 바로빌 온보딩 전체 흐름

### 2.1 단계별 프로세스

```
Phase 1: 테넌트 계약
┌──────────────────────────────────────────┐
│  고객사 SAM 서비스 계약 체결              │
│  └─ SAM 테넌트 생성 (tenant_id 발급)     │
│  └─ 바로빌 서비스 이용 여부 확인          │
└──────────────────────┬───────────────────┘
                       ▼
Phase 2: 바로빌 회원 등록 (테스트 모드)
┌──────────────────────────────────────────┐
│  바로빌 회원사 등록 (BarobillService)     │
│  ├─ 사업자번호, 상호, 대표자 등록         │
│  ├─ 바로빌 ID/PW 생성                    │
│  ├─ server_mode = 'test' (기본값)         │
│  └─ 테스트 서버에서 연동 확인             │
└──────────────────────┬───────────────────┘
                       ▼
Phase 3: 인증서 및 계좌/카드 연결
┌──────────────────────────────────────────┐
│  공동인증서 등록                          │
│  ├─ getCertificateRegistUrl() → 고객 직접│
│  ├─ 인증서 유효성 확인                    │
│  └─ 인증서 만료일 모니터링 설정           │
│                                          │
│  계좌 연결                                │
│  ├─ getBankAccountScrapRequestUrl()       │
│  └─ 고객이 직접 계좌 등록                 │
│                                          │
│  카드 연결                                │
│  ├─ registCard()                          │
│  └─ 카드사별 등록                         │
└──────────────────────┬───────────────────┘
                       ▼
Phase 4: 연동 검증
┌──────────────────────────────────────────┐
│  테스트 모드에서 기능 확인                 │
│  ├─ 계좌 입출금 내역 조회 확인            │
│  ├─ 카드 사용내역 조회 확인               │
│  ├─ 홈택스 세금계산서 수집 확인           │
│  └─ 문제 없으면 다음 단계                 │
└──────────────────────┬───────────────────┘
                       ▼
Phase 5: 운영 모드 전환
┌──────────────────────────────────────────┐
│  관리자가 server_mode → 'production' 전환 │
│  ├─ 운영 CERTKEY로 SOAP 재연결            │
│  ├─ 실제 데이터 수집 시작                 │
│  └─ 과금 시작 (구독 등록)                 │
└──────────────────────┬───────────────────┘
                       ▼
Phase 6: 실무 사용 시작
┌──────────────────────────────────────────┐
│  정기 동기화 스케줄러 활성화              │
│  ├─ 은행 거래 자동 수집                   │
│  ├─ 카드 내역 자동 수집                   │
│  ├─ 홈택스 세금계산서 자동 수집           │
│  └─ 월정액 과금 자동 처리                 │
└──────────────────────────────────────────┘
```

### 2.2 역할 분담

| 단계 | 수행 주체 | 설명 |
|------|----------|------|
| 테넌트 생성 | SAM 관리자 | MNG에서 테넌트 생성 |
| 회원사 등록 | SAM 관리자 또는 고객 | 사업자 정보 입력 |
| 인증서 등록 | **고객 직접** | 바로빌 제공 URL에서 직접 등록 |
| 계좌/카드 등록 | **고객 직접** | 바로빌 제공 URL에서 직접 등록 |
| 연동 검증 | SAM 관리자 | 테스트 모드에서 데이터 수집 확인 |
| 운영 전환 | SAM 관리자 | `server_mode` 변경 |

---

## 3. 테스트 모드 활용

### 3.1 온보딩에서의 테스트 모드 역할

테스트 모드는 **온보딩 Phase 2~4에서 연동을 검증**하기 위해 사용한다.

```
✅ 바로빌 회원 등록이 정상적으로 되는지 확인
✅ 인증서/계좌/카드 연결이 작동하는지 확인
✅ API 호출이 정상 응답하는지 확인
❌ 실제 세금계산서 발행 (국세청 미전송)
❌ 실제 거래 데이터 수집 (테스트 데이터만)
```

### 3.2 테스트 모드 체크리스트

Phase 4 (연동 검증) 완료 기준:

- [ ] 바로빌 회원 상태: `active`
- [ ] 공동인증서: 등록됨 + 유효기간 확인
- [ ] 계좌: 1개 이상 등록, 입출금 조회 응답 정상
- [ ] 카드: 1개 이상 등록, 사용내역 조회 응답 정상
- [ ] 홈택스: 매출/매입 세금계산서 수집 응답 정상
- [ ] 에러 없이 모든 API 호출 성공

### 3.3 운영 전환 체크리스트

Phase 5 (운영 모드 전환) 전 확인:

- [ ] 테스트 모드 검증 완료
- [ ] 고객 동의 (실제 과금 시작 안내)
- [ ] 운영 CERTKEY 설정 확인
- [ ] 구독 등록 (월정액 과금 설정)
- [ ] `server_mode` → `production` 전환
- [ ] 운영 모드에서 첫 데이터 수집 성공 확인

---

## 4. 개발 시 주의사항

### 4.1 개발 단계에서의 테스트 모드

온보딩 프로세스와 별개로, **서비스 이관 개발 중에는 항상 테스트 모드를 사용**한다.

| 단계 | 모드 | 이유 |
|------|------|------|
| 서비스 이관 개발 | 테스트 | 코드 검증, 무과금 |
| 베타테스트 | 테스트 | 실사용 시나리오 검증, 무과금 |
| 고객 온보딩 Phase 2~4 | 테스트 | 연동 설정 확인, 무과금 |
| 고객 온보딩 Phase 5~ | **운영** | 실무 사용, 과금 시작 |

### 4.2 서비스 이관 완료 후 출시 순서

```
1. 서비스 이관 개발 완료 (테스트 모드)
2. 내부 베타테스트 (tenant_id=1, 코드브릿지엑스, 테스트 모드)
3. 외부 베타테스트 (선별 고객 2~3곳, 테스트 모드)
4. 정식 출시
5. 신규 고객 온보딩 프로세스 가동 (반복)
```

---

## 관련 문서

| 문서 | 설명 |
|------|------|
| [바로빌 연동 시스템](./README.md) | 전체 구조, 테스트/운영 모드, 과금 정책 |
| [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | REST API 42개 엔드포인트 |
| [데모 테넌트 정책](../sales/demo-tenant-policy.md) | 영업파트너 데모 테넌트 3-Tier 전략 |

---

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