docs: [barobill] 바로빌 연동 시스템 문서 작성

- SOAP API 구조, 테스트/운영 모드 비교 - 과금 정책 및 멀티테넌트 처리 - 서비스 이관 계획 및 우선순위 - INDEX.md에 문서 등록
2026-03-17 08:54:02 +09:00
parent 7d280f3dd5
commit 469efce440
2 changed files with 399 additions and 0 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -24,6 +24,7 @@
 | 견적관리 | `features/quotes/README.md` | 견적 시스템, BOM 계산 |
 | 급여관리 API | `frontend/api-specs/payroll-api.md` | 급여관리 API 전체 명세 (18개 엔드포인트) |
 | 바로빌 회계 API | `frontend/api-specs/barobill-api.md` | 카드/은행/홈택스 REST API (42개 엔드포인트) |
+| 바로빌 시스템 | `features/barobill/README.md` | SOAP 연동, 테스트/운영 모드, 과금, 멀티테넌트, 이관 계획 |
 | 재공품 생산 정책 | `rules/wip-production-policy.md` | 재공품(WIP) 개념, 제조업 공통 패턴, SAM 처리 방식 |
 | 재고생산관리 API | `frontend/api-specs/stock-production-api.md` | 재고생산 API 명세 (기존 수주 API + STOCK 타입) |
 | 결재관리 | `dev/dev_plans/approval-system-unification-plan.md` | MNG→API 결재 통합 계획 |
@@ -170,6 +171,7 @@ DB 도메인별:
 | [sales/stock-production.md](features/sales/stock-production.md) | 재고생산관리 (내부 오더 방식, 수주 테이블 공유) |
 | [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-kakaotalk/README.md](features/barobill-kakaotalk/README.md) | 바로빌 카카오톡 |
 | [quality-management/README.md](features/quality-management/README.md) | 품질관리 (제품검사, 실적신고) |
 | [approvals/README.md](features/approvals/README.md) | 결재관리 시스템 |
--- a/features/barobill/README.md
+++ b/features/barobill/README.md
@@ -0,0 +1,397 @@
+# 바로빌(Barobill) 연동 시스템
+
+> **작성일**: 2026-03-17
+> **상태**: MNG 운영 중 / 서비스 이관 준비
+
+---
+
+## 1. 개요
+
+### 1.1 목적
+
+바로빌은 전자세금계산서, 계좌조회, 카드내역, 홈택스 연동, 카카오톡/SMS 발송 등을 제공하는 SOAP 기반 B2B 서비스다. SAM에서 재무/회계 데이터를 자동 수집하고 세금계산서를 발행하기 위해 연동한다.
+
+### 1.2 현재 상태
+
+| 항목 | MNG (백오피스) | API (서비스) | React (프론트) |
+|------|:------------:|:----------:|:------------:|
+| SOAP 연동 서비스 | ✅ 완료 (1,761줄) | 기본 설정만 | — |
+| 회원사 관리 | ✅ 운영 중 | 모델만 존재 | 설정 페이지 |
+| 카드 거래 조회 | ✅ 운영 중 | ✅ REST API 16개 | — |
+| 은행 거래 조회 | ✅ 운영 중 | ✅ REST API 13개 | — |
+| 홈택스 세금계산서 | ✅ 운영 중 | ✅ REST API 13개 | — |
+| 카카오톡/SMS | ✅ 운영 중 | — | — |
+| 과금 시스템 | ✅ 구현 완료 | — | — |
+
+> **핵심**: tenant_id=1 (코드브릿지엑스 본사)에서 실무 운영 중. 서비스 이관 시 멀티테넌트 SOAP 연동이 핵심 과제.
+
+### 1.3 바로빌 공식 자료
+
+- 개발자 센터: `https://dev.barobill.co.kr/`
+- 운영 WSDL: `https://ws.baroservice.com/`
+- 테스트 WSDL: `https://testws.baroservice.com/`
+
+---
+
+## 2. 테스트 모드 vs 운영 모드
+
+> **경고: 개발 시 반드시 테스트 모드를 사용한다. 운영 모드는 실제 과금이 발생한다.**
+
+### 2.1 모드 비교
+
+| 항목 | 테스트 모드 | 운영 모드 |
+|------|-----------|----------|
+| WSDL 엔드포인트 | `https://testws.baroservice.com/` | `https://ws.baroservice.com/` |
+| CERTKEY | 테스트용 별도 발급 | 운영용 별도 발급 |
+| 과금 | ❌ 무과금 | ✅ 실제 과금 |
+| 데이터 | 테스트 데이터 (초기화 가능) | 실제 세금계산서/거래 데이터 |
+| 국세청 전송 | ❌ 미전송 | ✅ 실제 전송 |
+| 회원사 등록 | 테스트 서버에 등록 | 운영 서버에 등록 |
+| 인증서 | 테스트 인증서 사용 가능 | 실제 공동인증서 필수 |
+
+### 2.2 모드 전환 구조
+
+```
+┌───────────────────────────────────────────────────────┐
+│                    모드 결정 흐름                       │
+├───────────────────────────────────────────────────────┤
+│                                                       │
+│  1. BarobillMember.server_mode                        │
+│     └─ 'test' 또는 'production' (회원사별 설정)        │
+│                                                       │
+│  2. BarobillService.switchServerMode(isTestMode)      │
+│     └─ SOAP 클라이언트 재초기화                        │
+│     └─ initializeConfig() 호출                        │
+│                                                       │
+│  3. initializeConfig()                                │
+│     ├─ DB 우선: BarobillConfig.getActive(isTestMode)  │
+│     │   └─ environment = 'test' | 'production'       │
+│     └─ .env 폴백:                                     │
+│         ├─ test → BAROBILL_CERT_KEY_TEST              │
+│         └─ prod → BAROBILL_CERT_KEY_PROD              │
+│                                                       │
+│  4. SOAP URL 구성                                     │
+│     ├─ test → testws.baroservice.com/*                │
+│     └─ prod → ws.baroservice.com/*                    │
+│                                                       │
+└───────────────────────────────────────────────────────┘
+```
+
+### 2.3 설정 우선순위
+
+1. **DB 설정** (`barobill_configs` 테이블) — 최우선
+2. **.env 환경변수** — DB 설정 없을 때 폴백
+
+```php
+// BarobillService::initializeConfig()
+$dbConfig = BarobillConfig::getActive($this->isTestMode);
+
+if ($dbConfig) {
+    // DB에서 cert_key, corp_num, base_url 사용
+} else {
+    // .env에서 BAROBILL_CERT_KEY_TEST/PROD, BAROBILL_CORP_NUM 사용
+}
+```
+
+### 2.4 환경변수
+
+```bash
+# .env (MNG, API 동일)
+BAROBILL_CERT_KEY_TEST=<테스트 인증키>
+BAROBILL_CERT_KEY_PROD=<운영 인증키>
+BAROBILL_CORP_NUM=<파트너 사업자번호>
+BAROBILL_TEST_MODE=true   # 기본값: 테스트 모드
+```
+
+### 2.5 개발 시 주의사항
+
+```
+✅ 로컬/개발 서버: BAROBILL_TEST_MODE=true (기본값)
+✅ 운영 서버: BAROBILL_TEST_MODE=false + 운영 CERTKEY
+✅ 회원사별 server_mode로 개별 전환 가능
+❌ 테스트 CERTKEY로 운영 서버 호출 불가 (에러 -11102)
+❌ 운영 모드에서 테스트 데이터 생성 금지 (실제 과금)
+```
+
+---
+
+## 3. 아키텍처
+
+### 3.1 전체 데이터 흐름
+
+```
+바로빌 SOAP API (ws.baroservice.com)
+        │
+        │ SOAP (6개 서비스)
+        ▼
+┌─────────────────────────────────┐
+│  MNG (BarobillService)          │
+│  ├─ CORPSTATE — 회원사 관리      │
+│  ├─ TI — 전자세금계산서          │
+│  ├─ BANKACCOUNT — 계좌조회       │
+│  ├─ CARD — 카드조회              │
+│  ├─ KAKAOTALK — 알림톡          │
+│  └─ SMS — 문자 발송             │
+└──────────┬──────────────────────┘
+           │ MySQL 저장
+           ▼
+┌─────────────────────────────────┐
+│  MySQL (samdb)                  │
+│  ├─ barobill_members            │
+│  ├─ barobill_card_transactions  │
+│  ├─ barobill_bank_transactions  │
+│  ├─ hometax_invoices            │
+│  └─ (18개 테이블)               │
+└──────────┬──────────────────────┘
+           │ REST API
+           ▼
+┌─────────────────────────────────┐
+│  API (42개 엔드포인트)           │
+│  ├─ /api/v1/barobill-card-*     │
+│  ├─ /api/v1/barobill-bank-*     │
+│  └─ /api/v1/hometax-invoices/*  │
+└──────────┬──────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────┐
+│  React (사용자 UI)              │
+│  └─ BarobillIntegration 컴포넌트│
+└─────────────────────────────────┘
+```
+
+### 3.2 SOAP 서비스 목록
+
+| 서비스 | WSDL 경로 | 기능 |
+|--------|----------|------|
+| CORPSTATE | `/CORPSTATE.asmx` | 회원사 등록/조회/수정 |
+| TI | `/TI.asmx` | 전자세금계산서 발행/조회 |
+| BANKACCOUNT | `/BANKACCOUNT.asmx` | 계좌 등록/입출금 내역 조회 |
+| CARD | `/CARD.asmx` | 카드 등록/사용내역 조회 |
+| KAKAOTALK | `/KAKAOTALK.asmx` | 카카오톡 알림톡 발송 |
+| SMS | `/SMS.asmx` | 문자 메시지 발송 |
+
+### 3.3 인증 구조
+
+```
+모든 API 호출
+  └─ CERTKEY (파트너 인증키) — 필수 파라미터
+      ├─ 바로빌 파트너 계약 시 발급
+      ├─ 테스트/운영 별도 키
+      └─ BarobillService.call()에서 자동 주입
+```
+
+---
+
+## 4. 과금 정책
+
+### 4.1 바로빌 과금 구조 (SAM 내부 정책)
+
+| 서비스 | 월정액 | 비고 |
+|--------|-------|------|
+| 계좌조회 (`bank_account`) | 10,000원/월 | 테넌트별 |
+| 카드내역 (`card`) | 10,000원/월 | 테넌트별 |
+| 홈택스 매입/매출 (`hometax`) | 0원 | 본사 부담 (무료 제공) |
+
+### 4.2 추가 과금 (건별)
+
+`BarobillPricingPolicy` 모델 기반:
+
+| 서비스 | 무료 기본량 | 추가 과금 단위 | 추가 금액 |
+|--------|-----------|-------------|----------|
+| 법인카드 등록 (`card`) | 정책 설정값 | 정책 설정값 | 정책 설정값 |
+| 계산서 발행 (`tax_invoice`) | 정책 설정값 | 건당 | 정책 설정값 |
+| 계좌조회 수집 (`bank_account`) | 정책 설정값 | 정책 설정값 | 정책 설정값 |
+
+> 과금 계산: `BarobillPricingPolicy::calculateBilling(usageCount)` — 무료 제공량 초과분만 과금
+
+### 4.3 과금 처리 흐름
+
+```
+매월 1일 (배치)
+  └─ BarobillBillingService::processMonthlyBilling()
+      ├─ 활성 구독 조회 (BarobillSubscription::active())
+      ├─ 이미 과금된 기록 중복 방지
+      ├─ BarobillBillingRecord 생성 (subscription 타입)
+      └─ BarobillMonthlySummary 갱신
+
+건별 발생 시
+  └─ BarobillBillingService::recordUsage()
+      ├─ BarobillBillingRecord 생성 (usage 타입)
+      └─ BarobillMonthlySummary 갱신
+```
+
+### 4.4 테스트 모드에서의 과금
+
+```
+✅ 테스트 모드: 바로빌 API 호출에 대한 바로빌 측 과금 없음
+✅ SAM 내부 과금 시스템은 모드와 무관하게 기록 가능 (테스트용)
+❌ 운영 모드: 바로빌 측 실제 과금 발생 (충전잔액 차감)
+```
+
+---
+
+## 5. 멀티테넌트 처리
+
+### 5.1 데이터 격리
+
+모든 바로빌 테이블은 `tenant_id` 컬럼으로 데이터를 격리한다.
+
+```
+tenant_id=1 (코드브릿지엑스) → 본사 실무 데이터
+tenant_id=N (고객사)        → 해당 고객사 데이터만 접근
+```
+
+### 5.2 회원사별 설정
+
+각 테넌트는 `barobill_members` 테이블에 독립된 바로빌 회원사 정보를 가진다:
+
+| 컬럼 | 설명 |
+|------|------|
+| `tenant_id` | 테넌트 FK |
+| `biz_no` | 사업자번호 (UNIQUE with tenant_id) |
+| `barobill_id` | 바로빌 로그인 ID |
+| `barobill_pwd` | 바로빌 비밀번호 (Laravel Encryption) |
+| `server_mode` | `test` 또는 `production` (회원사별 전환) |
+| `status` | `active` / `inactive` / `pending` |
+
+### 5.3 서비스 이관 시 고려사항
+
+```
+🔴 필수: 테넌트별 CERTKEY 관리 방안 (현재는 전역 1개)
+🔴 필수: 테넌트 온보딩 시 바로빌 회원 자동 등록 플로우
+🟡 중요: 테스트→운영 모드 전환 프로세스 정의
+🟡 중요: 과금 정책을 테넌트별로 다르게 적용 가능하도록 확장
+🟢 권장: 바로빌 API 호출 로그/모니터링
+```
+
+---
+
+## 6. 프로젝트별 코드 위치
+
+### 6.1 MNG (`/home/aweso/sam/mng`)
+
+| 유형 | 경로 |
+|------|------|
+| 서비스 | `app/Services/Barobill/BarobillService.php` (1,761줄, 핵심) |
+| 서비스 | `app/Services/Barobill/HometaxSyncService.php` |
+| 서비스 | `app/Services/Barobill/BarobillBillingService.php` |
+| 서비스 | `app/Services/Barobill/BarobillUsageService.php` |
+| 서비스 | `app/Services/Barobill/BarobillBankSyncService.php` |
+| 모델 | `app/Models/Barobill/` (18개 모델) |
+| 컨트롤러 | `app/Http/Controllers/Barobill/` (7개) |
+| Admin API | `app/Http/Controllers/Api/Admin/Barobill/` (7개) |
+| 뷰 | `resources/views/barobill/` (10개 페이지) |
+
+### 6.2 API (`/home/aweso/sam/api`)
+
+| 유형 | 경로 |
+|------|------|
+| 서비스 | `app/Services/BarobillService.php` (기본 설정만) |
+| 모델 | `app/Models/Barobill/` (15개) |
+| 모델 | `app/Models/Tenants/BarobillSetting.php` |
+| 컨트롤러 | `app/Http/Controllers/Api/V1/Barobill*Controller.php` |
+| 마이그레이션 | `database/migrations/` (19개 바로빌 관련) |
+
+### 6.3 React (`/home/aweso/sam/react`)
+
+| 유형 | 경로 |
+|------|------|
+| 컴포넌트 | `src/components/settings/BarobillIntegration/` |
+| 페이지 | `/settings/barobill-integration` |
+
+---
+
+## 7. DB 테이블 구조
+
+### 7.1 테이블 목록
+
+| 테이블 | 용도 | 마이그레이션 위치 |
+|--------|------|-----------------|
+| `barobill_members` | 회원사 정보 | API |
+| `barobill_configs` | API 설정 (test/prod 분리) | API |
+| `barobill_settings` | 테넌트별 서비스 설정 | API |
+| `barobill_subscriptions` | 월정액 구독 | API |
+| `barobill_billing_records` | 과금 기록 | API |
+| `barobill_monthly_summaries` | 월별 과금 요약 | API |
+| `barobill_pricing_policies` | 요금 정책 | API |
+| `hometax_invoices` | 홈택스 세금계산서 | API |
+| `hometax_invoice_journals` | 세금계산서 분개 | API |
+| `barobill_bank_transactions` | 은행 거래 내역 | API |
+| `barobill_bank_transaction_overrides` | 은행 적요 수정 | API |
+| `barobill_bank_transaction_splits` | 은행 거래 분할 | API |
+| `barobill_bank_sync_status` | 은행 동기화 상태 | API |
+| `barobill_card_transactions` | 카드 거래 내역 | API |
+| `barobill_card_transaction_splits` | 카드 거래 분할 | API |
+| `barobill_card_transaction_amount_logs` | 카드 금액 수정 로그 | API |
+| `barobill_card_transaction_hides` | 카드 거래 숨김 | API |
+| `account_codes` | 계정과목 마스터 | API |
+
+### 7.2 핵심 테이블 스키마
+
+**barobill_members**:
+- `tenant_id` + `biz_no` UNIQUE
+- `server_mode`: `test` | `production`
+- `barobill_pwd`: Laravel Encryption (복호화 가능, API 호출 시 필요)
+
+**hometax_invoices**:
+- `tenant_id` + `nts_confirm_num` + `invoice_type` UNIQUE
+- `invoice_type`: `sales` | `purchase`
+- `tax_type`: 1=과세, 2=영세, 3=면세
+- `issue_type`: 1=정발행, 2=역발행
+
+---
+
+## 8. 에러 코드 매핑
+
+| 코드 | 의미 | 대응 |
+|------|------|------|
+| -11101 | 사업자번호 미설정/유효하지 않음 | 회원사 정보 확인 |
+| -11102 | CERTKEY 유효하지 않음 | 테스트/운영 키 확인 |
+| -11103 | 인증서 만료/유효하지 않음 | 공동인증서 갱신 |
+| -11104 | 미등록 사업자 | 회원사 등록 먼저 |
+| -11105 | 이미 등록된 사업자 | 중복 등록 방지 |
+| -26001 | 공동인증서 미등록 | 인증서 등록 안내 |
+| -32001 | 사업자번호 형식 오류 | 10자리 숫자 확인 |
+| -32010 | 이미 등록된 사업자번호 | 기존 회원 확인 |
+| -32011 | 이미 등록된 아이디 | 다른 아이디 사용 |
+
+---
+
+## 9. 서비스 이관 계획
+
+### 9.1 이관 범위
+
+| 기능 | MNG (현재) | API 이관 | React 이관 | 우선순위 |
+|------|:---------:|:-------:|:---------:|:-------:|
+| SOAP 연동 서비스 | ✅ | 🔴 필수 | — | P1 |
+| 회원사 등록/관리 | ✅ | 🔴 필수 | 🔴 필수 | P1 |
+| 테스트/운영 모드 전환 | ✅ | 🔴 필수 | 🟡 관리자 | P1 |
+| 카드 거래 동기화 | ✅ | 🟡 중요 | ✅ 완료 | P2 |
+| 은행 거래 동기화 | ✅ | 🟡 중요 | — | P2 |
+| 홈택스 동기화 | ✅ | 🟡 중요 | — | P2 |
+| 세금계산서 발행 | ✅ | 🟡 중요 | 🟡 중요 | P2 |
+| 과금 시스템 | ✅ | 🟢 권장 | 🟢 권장 | P3 |
+| 카카오톡/SMS | ✅ | 🟢 권장 | — | P3 |
+
+### 9.2 이관 시 핵심 과제
+
+1. **SOAP 서비스 이관**: MNG의 `BarobillService` (1,761줄)를 API로 이동
+2. **멀티테넌트 CERTKEY**: 테넌트별로 바로빌 파트너 계약이 필요한지, 공용 CERTKEY로 처리 가능한지 확인
+3. **테스트 모드 관리**: 신규 테넌트는 테스트 모드로 시작 → 관리자가 운영 모드로 전환
+4. **동기화 스케줄러**: MNG에서 실행 중인 은행/카드/홈택스 동기화를 API Queue로 이관
+5. **인증서 관리**: 공동인증서 등록 URL을 테넌트 사용자에게 제공하는 플로우
+
+---
+
+## 관련 문서
+
+| 문서 | 설명 |
+|------|------|
+| [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | 카드/은행/홈택스 REST API 42개 엔드포인트 |
+| [바로빌 회원 마이그레이션](../../dev/guides/barobill-members-migration.md) | 회원 데이터 이관 가이드 |
+| [바로빌 카카오톡](../barobill-kakaotalk/README.md) | 카카오톡 알림톡 연동 |
+| [재무관리](../finance/README.md) | 재무/자금관리 전체 개요 |
+
+---
+
+**최종 업데이트**: 2026-03-17