SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: [barobill] 테넌트 온보딩 개념 정의 문서 추가

Browse Source 
- 온보딩 vs 베타테스트 개념 구분
- 6단계 온보딩 프로세스 정의
- 테스트→운영 모드 전환 체크리스트
- 개발→베타→출시→온보딩 단계별 관계 정리
This commit is contained in:
김보곤
2026-03-17 09:00:00 +09:00
parent 469efce440
commit 79ca132d1a
3 changed files with 192 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
INDEX.md
View File

@@ -172,6 +172,7 @@ DB 도메인별:
| [sales/demo-tenant-policy.md](features/sales/demo-tenant-policy.md) | 영업파트너 데모 테넌트 정책 (3-Tier 전략) |
| [sales/demo-tenant-usage-guide.md](features/sales/demo-tenant-usage-guide.md) | 데모 테넌트 사용 가이드 (영업파트너/관리자용) |
| [barobill/README.md](features/barobill/README.md) | 바로빌 연동 시스템 (SOAP API, 테스트/운영 모드, 과금, 이관 계획) |
| [barobill/tenant-onboarding.md](features/barobill/tenant-onboarding.md) | 바로빌 테넌트 온보딩 (개념 정의, 6단계 프로세스, 베타테스트와의 차이) |
| [barobill-kakaotalk/README.md](features/barobill-kakaotalk/README.md) | 바로빌 카카오톡 |
| [quality-management/README.md](features/quality-management/README.md) | 품질관리 (제품검사, 실적신고) |
| [approvals/README.md](features/approvals/README.md) | 결재관리 시스템 |

1
features/barobill/README.md
View File

@@ -387,6 +387,7 @@ tenant_id=N (고객사) → 해당 고객사 데이터만 접근
| 문서 | 설명 |
|------|------|
| [테넌트 온보딩](./tenant-onboarding.md) | 온보딩 개념 정의, 테스트→운영 전환 프로세스 |
| [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | 카드/은행/홈택스 REST API 42개 엔드포인트 |
| [바로빌 회원 마이그레이션](../../dev/guides/barobill-members-migration.md) | 회원 데이터 이관 가이드 |
| [바로빌 카카오톡](../barobill-kakaotalk/README.md) | 카카오톡 알림톡 연동 |

190
features/barobill/tenant-onboarding.md Normal file
View File

@@ -0,0 +1,190 @@
# 바로빌 테넌트 온보딩 프로세스
> **작성일**: 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