From 3588bb3dd7e9ef23825054540cb5181555ddef9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Tue, 17 Mar 2026 14:53:30 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[barobill]=20API=20SOAP=20=EA=B5=AC?= =?UTF-8?q?=EC=B6=95=20=EC=99=84=EB=A3=8C=20=EB=B0=98=EC=98=81=20+=20?= =?UTF-8?q?=EA=B8=B0=EC=88=A0=20=EC=B0=B8=EC=A1=B0=20=EB=AC=B8=EC=84=9C=20?= =?UTF-8?q?=EC=8B=A0=EA=B7=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: 현재 상태 업데이트 (API SOAP 100% 구축 완료, 아키텍처 다이어그램) - api-soap-reference.md: 신규 — 전체 메서드 49+7개, 동기화, 스케줄러, 테스트 환경 데이터 - tenant-onboarding.md: 구현 현황/테스트 시나리오 추가 - INDEX.md: 신규 문서 등록 --- INDEX.md | 4 +- features/barobill/README.md | 163 ++++++----- features/barobill/api-soap-reference.md | 354 ++++++++++++++++++++++++ features/barobill/tenant-onboarding.md | 48 +++- 4 files changed, 496 insertions(+), 73 deletions(-) create mode 100644 features/barobill/api-soap-reference.md diff --git a/INDEX.md b/INDEX.md index e239ac5..cc172e6 100644 --- a/INDEX.md +++ b/INDEX.md @@ -24,7 +24,8 @@ | 견적관리 | `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 연동, 테스트/운영 모드, 과금, 멀티테넌트, 이관 계획 | +| 바로빌 시스템 | `features/barobill/README.md` | SOAP 연동, 테스트/운영 모드, 과금, 멀티테넌트 (API 구축 완료) | +| 바로빌 API SOAP | `features/barobill/api-soap-reference.md` | API SOAP 49+7 메서드, 동기화 서비스, 스케줄러, MNG 대응표 | | 바로빌 출시 계획 | `dev/dev_plans/barobill-service-launch-plan.md` | 4단계 출시 로드맵 (SOAP 이관→UI→베타→출시) | | 바로빌 온보딩 가이드 | `guides/barobill-onboarding-guide.md` | 신규 고객 바로빌 연동 실행 절차 (7단계, API 예시, 트러블슈팅) | | 재공품 생산 정책 | `rules/wip-production-policy.md` | 재공품(WIP) 개념, 제조업 공통 패턴, SAM 처리 방식 | @@ -177,6 +178,7 @@ DB 도메인별: | [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/api-soap-reference.md](features/barobill/api-soap-reference.md) | API SOAP 서비스 기술 참조 (49+7 메서드, 동기화, 스케줄러, MNG 대응표) | | [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) | 결재관리 시스템 | diff --git a/features/barobill/README.md b/features/barobill/README.md index 075756a..9f6845b 100644 --- a/features/barobill/README.md +++ b/features/barobill/README.md @@ -1,7 +1,7 @@ # 바로빌(Barobill) 연동 시스템 > **작성일**: 2026-03-17 -> **상태**: MNG 운영 중 / 서비스 이관 준비 +> **상태**: MNG 운영 중 / API SOAP 서비스 구축 완료 (2026-03-17) --- @@ -15,15 +15,30 @@ | 항목 | MNG (백오피스) | API (서비스) | React (프론트) | |------|:------------:|:----------:|:------------:| -| SOAP 연동 서비스 | ✅ 완료 (1,761줄) | 기본 설정만 | — | -| 회원사 관리 | ✅ 운영 중 | 모델만 존재 | 설정 페이지 | -| 카드 거래 조회 | ✅ 운영 중 | ✅ REST API 16개 | — | -| 은행 거래 조회 | ✅ 운영 중 | ✅ REST API 13개 | — | -| 홈택스 세금계산서 | ✅ 운영 중 | ✅ REST API 13개 | — | -| 카카오톡/SMS | ✅ 운영 중 | — | — | -| 과금 시스템 | ✅ 구현 완료 | — | — | +| SOAP 연동 서비스 | ✅ 완료 (1,761줄) | ✅ **구축 완료** (49+7 메서드) | — | +| 회원사 관리 | ✅ 운영 중 | ✅ SOAP 등록/수정/상태 | 설정 페이지 | +| 카드 거래 조회 | ✅ 운영 중 | ✅ REST 16개 + SOAP 동기화 | — | +| 은행 거래 조회 | ✅ 운영 중 | ✅ REST 13개 + SOAP 동기화 | — | +| 홈택스 세금계산서 | ✅ 운영 중 | ✅ REST 13개 + upsert 동기화 | — | +| 카카오톡/SMS | ✅ 운영 중 | ✅ **SOAP 메서드 구현** (19개) | — | +| 과금 시스템 | ✅ 구현 완료 | — (모델만 존재) | — | +| 자동 동기화 | MNG 수동 | ✅ Queue Job + 스케줄러 | — | -> **핵심**: tenant_id=1 (코드브릿지엑스 본사)에서 실무 운영 중. 서비스 이관 시 멀티테넌트 SOAP 연동이 핵심 과제. +> **현재 상태 (2026-03-17)**: API SOAP 서비스가 MNG와 100% 동등하게 구축되었다. MNG(본사 tenant_id=1)와 API(서비스 tenant_id=2~N)가 각각 독립적으로 SOAP 호출하며, 같은 DB(samdb)를 공유한다. + +``` +MNG (본사 전용, 수정 없음) API (서비스 고객용, 신규 구축 완료) +┌──────────────────────┐ ┌──────────────────────┐ +│ BarobillService │ │ BarobillSoapService │ +│ (1,761줄 그대로) │ │ (49+7 메서드) │ +│ BankSyncService │ │ BankSyncService │ +│ HometaxSyncService │ │ CardSyncService │ +│ │ │ HometaxSyncService │ +│ tenant_id=1 본사 │ │ tenant_id=2~N 고객 │ +└──────────┬───────────┘ └──────────┬───────────┘ + │ │ + └────────── 같은 DB (samdb) ────────────┘ +``` ### 1.3 바로빌 공식 자료 @@ -120,43 +135,33 @@ BAROBILL_TEST_MODE=true # 기본값: 테스트 모드 ### 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 컴포넌트│ -└─────────────────────────────────┘ + 바로빌 SOAP API (ws.baroservice.com / testws.baroservice.com) + │ │ + SOAP (6개 서비스) SOAP (6개 서비스) + ▼ ▼ +┌──────────────────────────────┐ ┌──────────────────────────────────┐ +│ MNG (BarobillService) │ │ API (BarobillSoapService) │ +│ 본사 전용 (tenant_id=1) │ │ 서비스 고객 (tenant_id=2~N) │ +│ ├─ CORPSTATE 회원관리 │ │ ├─ CORPSTATE 회원관리 │ +│ ├─ TI 세금계산서 │ │ ├─ TI 세금계산서 │ +│ ├─ BANKACCOUNT 계좌 │ │ ├─ BANKACCOUNT 계좌 │ +│ ├─ CARD 카드 │ │ ├─ CARD 카드 │ +│ ├─ KAKAOTALK 알림톡 │ │ ├─ KAKAOTALK 알림톡 │ +│ └─ SMS 문자 │ │ └─ SMS 문자 │ +└──────────┬───────────────────┘ │ + BankSyncService (동기화) │ + │ │ + CardSyncService (동기화) │ + │ │ + HometaxSyncService (동기화) │ + │ │ + SyncBarobillDataJob (스케줄러)│ + │ └──────────┬───────────────────────┘ + │ │ + └─────────── MySQL (samdb) ─────────┘ + │ + REST API (53개 엔드포인트) + │ + ▼ + ┌────────────────────┐ + │ React (사용자 UI) │ + └────────────────────┘ ``` ### 3.2 SOAP 서비스 목록 @@ -284,13 +289,19 @@ tenant_id=N (고객사) → 해당 고객사 데이터만 접근 ### 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개 바로빌 관련) | +| 유형 | 경로 | 설명 | +|------|------|------| +| **SOAP 서비스** | `app/Services/Barobill/BarobillSoapService.php` | 6개 SOAP 서비스, 49+7 메서드 | +| **동기화** | `app/Services/Barobill/BarobillBankSyncService.php` | 은행 거래 SOAP→DB 동기화 | +| **동기화** | `app/Services/Barobill/BarobillCardSyncService.php` | 카드 거래 SOAP→DB 동기화 | +| **동기화** | `app/Services/Barobill/HometaxSyncService.php` | 홈택스 세금계산서 upsert | +| **기존 서비스** | `app/Services/BarobillService.php` | REST 설정/세금계산서 발행 (기존) | +| **Queue Job** | `app/Jobs/Barobill/SyncBarobillDataJob.php` | 자동 동기화 스케줄러 Job | +| **컨트롤러** | `app/Http/Controllers/Api/V1/BarobillSyncController.php` | SOAP 동기화/회원/인증서 API | +| **컨트롤러** | `app/Http/Controllers/Api/V1/BarobillController.php` | 기존 설정/URL API (보강됨) | +| 모델 | `app/Models/Barobill/` (15개) | 기존 모델 | +| 라우트 | `routes/api/v1/finance.php` | 기존 42개 + 신규 11개 | +| 스케줄러 | `routes/console.php` | 06:00 은행, 06:30 카드 동기화 | ### 6.3 React (`/home/aweso/sam/react`) @@ -359,27 +370,34 @@ tenant_id=N (고객사) → 해당 고객사 데이터만 접근 ## 9. 서비스 이관 계획 -### 9.1 이관 범위 +### 9.1 이관 현황 (2026-03-17 기준) -| 기능 | MNG (현재) | API 이관 | React 이관 | 우선순위 | -|------|:---------:|:-------:|:---------:|:-------:| -| SOAP 연동 서비스 | ✅ | 🔴 필수 | — | P1 | -| 회원사 등록/관리 | ✅ | 🔴 필수 | 🔴 필수 | P1 | -| 테스트/운영 모드 전환 | ✅ | 🔴 필수 | 🟡 관리자 | P1 | -| 카드 거래 동기화 | ✅ | 🟡 중요 | ✅ 완료 | P2 | -| 은행 거래 동기화 | ✅ | 🟡 중요 | — | P2 | -| 홈택스 동기화 | ✅ | 🟡 중요 | — | P2 | -| 세금계산서 발행 | ✅ | 🟡 중요 | 🟡 중요 | P2 | -| 과금 시스템 | ✅ | 🟢 권장 | 🟢 권장 | P3 | -| 카카오톡/SMS | ✅ | 🟢 권장 | — | P3 | +| 기능 | MNG | API 이관 | React | 상태 | +|------|:---:|:-------:|:-----:|:----:| +| SOAP 연동 서비스 (6개) | ✅ | ✅ **완료** | — | 49 메서드 100% | +| 회원사 등록/관리 | ✅ | ✅ **완료** | 설정 페이지 | API 3개 엔드포인트 | +| 테스트/운영 모드 전환 | ✅ | ✅ **완료** | — | initForMember() | +| 은행 거래 동기화 | ✅ | ✅ **완료** | — | BankSyncService | +| 카드 거래 동기화 | ✅ | ✅ **완료** | — | CardSyncService | +| 홈택스 동기화 | ✅ | ✅ **완료** | — | HometaxSyncService | +| 자동 동기화 스케줄러 | — | ✅ **완료** | — | 06:00/06:30 Job | +| 카카오톡 (15개) | ✅ | ✅ **완료** | — | SOAP 메서드 | +| SMS (4개) | ✅ | ✅ **완료** | — | SOAP 메서드 | +| 세금계산서 발행 | ✅ | ✅ 기존 REST | — | BarobillService | +| 과금 시스템 | ✅ | 모델만 | — | **미이관** | +| 카카오톡/SMS API 엔드포인트 | ✅ | — | — | **미구현** (SOAP만) | +| 온보딩 대시보드 (MNG) | — | — | — | **기획 중** | -### 9.2 이관 시 핵심 과제 +### 9.2 남은 과제 -1. **SOAP 서비스 이관**: MNG의 `BarobillService` (1,761줄)를 API로 이동 -2. **멀티테넌트 CERTKEY**: 테넌트별로 바로빌 파트너 계약이 필요한지, 공용 CERTKEY로 처리 가능한지 확인 -3. **테스트 모드 관리**: 신규 테넌트는 테스트 모드로 시작 → 관리자가 운영 모드로 전환 -4. **동기화 스케줄러**: MNG에서 실행 중인 은행/카드/홈택스 동기화를 API Queue로 이관 -5. **인증서 관리**: 공동인증서 등록 URL을 테넌트 사용자에게 제공하는 플로우 +| 우선순위 | 과제 | 설명 | +|---------|------|------| +| 🔴 P1 | 온보딩 실제 테스트 | 테스트 테넌트로 풀 시나리오 검증 | +| 🔴 P1 | 카카오톡/SMS REST API 엔드포인트 | SOAP 메서드는 구현됨, Controller+Route 추가 필요 | +| 🟡 P2 | React 바로빌 관리 화면 | 동기화 트리거, 인증서/계좌/카드 관리 | +| 🟡 P2 | MNG 온보딩 대시보드 | 테넌트별 연동 진행 상태 시각화 | +| 🟢 P3 | 과금 시스템 API 이관 | BillingService, UsageService | +| 🟢 P3 | 인증서 만료/잔액 부족 알림 | 스케줄러 기반 자동 알림 | --- @@ -388,9 +406,12 @@ tenant_id=N (고객사) → 해당 고객사 데이터만 접근 | 문서 | 설명 | |------|------| | [테넌트 온보딩](./tenant-onboarding.md) | 온보딩 개념 정의, 테스트→운영 전환 프로세스 | +| [API SOAP 기술 참조](./api-soap-reference.md) | API BarobillSoapService 전체 메서드, 동기화, 스케줄러 | +| [온보딩 실행 가이드](../../guides/barobill-onboarding-guide.md) | 7단계 실행 절차, API 예시, 트러블슈팅, 고객 안내 | | [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | 카드/은행/홈택스 REST API 42개 엔드포인트 | | [바로빌 회원 마이그레이션](../../dev/guides/barobill-members-migration.md) | 회원 데이터 이관 가이드 | | [바로빌 카카오톡](../barobill-kakaotalk/README.md) | 카카오톡 알림톡 연동 | +| [바로빌 출시 계획](../../dev/dev_plans/barobill-service-launch-plan.md) | 4단계 출시 로드맵 | | [재무관리](../finance/README.md) | 재무/자금관리 전체 개요 | --- diff --git a/features/barobill/api-soap-reference.md b/features/barobill/api-soap-reference.md new file mode 100644 index 0000000..28b08c6 --- /dev/null +++ b/features/barobill/api-soap-reference.md @@ -0,0 +1,354 @@ +# 바로빌 API SOAP 서비스 기술 참조 + +> **작성일**: 2026-03-17 +> **상태**: 구축 완료 (MNG 100% 동등) +> **코드 위치**: `api/app/Services/Barobill/` + +--- + +## 1. 개요 + +API 프로젝트에 독립적으로 구축된 바로빌 SOAP 연동 서비스. MNG의 `BarobillService`(1,761줄)를 참고하되 수정하지 않고, API용으로 새로 작성했다. MNG(본사 tenant_id=1)와 API(서비스 tenant_id=2~N)가 각각 독립적으로 SOAP 호출하며, 같은 DB(samdb)를 공유한다. + +### 1.1 설계 원칙 + +``` +✅ MNG 코드는 절대 수정/삭제하지 않는다 +✅ API와 MNG는 같은 DB를 공유하지만, 각자 독립적으로 SOAP 호출 +✅ API Service는 extends Service (tenantId(), apiUserId() 사용) +✅ SOAP 클라이언트는 lazy 초기화, 모드 전환 시 리셋 +``` + +--- + +## 2. 파일 구조 + +``` +api/app/ +├── Services/ +│ ├── Barobill/ +│ │ ├── BarobillSoapService.php ← SOAP 클라이언트 래퍼 (핵심) +│ │ ├── BarobillBankSyncService.php ← 은행 거래 동기화 +│ │ ├── BarobillCardSyncService.php ← 카드 거래 동기화 +│ │ └── HometaxSyncService.php ← 홈택스 세금계산서 동기화 +│ └── BarobillService.php ← 기존 REST (세금계산서 발행 등) +├── Http/Controllers/Api/V1/ +│ ├── BarobillSyncController.php ← 동기화/회원/인증서 API (신규) +│ └── BarobillController.php ← 기존 설정/URL API (보강됨) +├── Jobs/Barobill/ +│ └── SyncBarobillDataJob.php ← 자동 동기화 스케줄러 Job +└── Models/Barobill/ ← 기존 16개 모델 +``` + +--- + +## 3. BarobillSoapService — 전체 메서드 목록 + +### 3.1 설정/초기화 (7개) + +| 메서드 | 설명 | +|--------|------| +| `__construct()` | `.env` 기본 설정 로드 | +| `switchServerMode(bool)` | 테스트/운영 전환 (클라이언트 리셋) | +| `setServerMode(string)` | `'test'` / `'production'` 문자열로 전환 | +| `getServerMode()` | 현재 모드 반환 | +| `checkConfiguration()` | CERTKEY/corpNum 설정 상태 확인 | +| `initForMember(BarobillMember)` | 회원사 기반 모드 자동 전환 | +| `call(service, method, params)` | 범용 SOAP 호출 (에러코드 매핑) | + +### 3.2 CORPSTATE — 회원관리 (3개) + +| 메서드 | SOAP 메서드 | 설명 | +|--------|-----------|------| +| `registCorp(data)` | `RegistCorp` | 회원사 등록 | +| `updateCorpInfo(data)` | `UpdateCorpInfo` | 회원사 정보 수정 | +| `getCorpState(corpNum)` | `GetCorpState` | 회원사 상태 조회 | + +### 3.3 BANKACCOUNT — 계좌조회 (13개) + +| 메서드 | SOAP 메서드 | 설명 | +|--------|-----------|------| +| `getBankAccounts(corpNum, availOnly)` | `GetBankAccountEx` | 등록계좌 목록 | +| `getPeriodBankAccountTransLog(...)` | `GetPeriodBankAccountTransLog` | 기간별 입출금 | +| `getDailyBankAccountTransLog(...)` | `GetDailyBankAccountTransLog` | 일별 입출금 | +| `getMonthlyBankAccountTransLog(...)` | `GetMonthlyBankAccountTransLog` | 월별 입출금 | +| `getBankAccountScrapRequestUrl(...)` | `GetBankAccountScrapRequestURL` | 계좌 등록 URL | +| `getBankAccountManagementUrl(...)` | `GetBankAccountManagementURL` | 계좌 관리 URL | +| `getBankAccountLogUrl(...)` | `GetBankAccountLogURL` | 입출금내역 URL | +| `getCertificateRegistUrl(...)` | `GetCertificateRegistURL` | 인증서 등록 URL | +| `checkCertificateValid(corpNum)` | `CheckCERTIsValid` | 인증서 유효성 | +| `getCertificateExpireDate(corpNum)` | `GetCertificateExpireDate` | 인증서 만료일 | +| `getCertificateRegistDate(corpNum)` | `GetCertificateRegistDate` | 인증서 등록일 | +| `getBalanceCostAmount(corpNum)` | `GetBalanceCostAmountEx` | 충전잔액 | +| `getCashChargeUrl(...)` | `GetCashChargeURL` | 현금충전 URL | +| `getBarobillUrl(...)` | `GetBaroBillURL` | 바로빌 범용 URL | + +### 3.4 CARD — 카드조회 (11개) + +| 메서드 | SOAP 메서드 | 설명 | +|--------|-----------|------| +| `getCards(corpNum, availOnly)` | `GetCardEx2` | 등록카드 목록 | +| `registCard(corpNum, cardData)` | `RegistCardEx` | 카드 등록 | +| `updateCard(corpNum, cardData)` | `UpdateCard` | 카드 정보 수정 | +| `stopCard(corpNum, cardNum)` | `StopCard` | 카드 해지 | +| `cancelStopCard(corpNum, cardNum)` | `CancelStopCard` | 카드 해지 취소 | +| `getPeriodCardLog(...)` | `GetPeriodCardLog` | 기간별 사용내역 | +| `getDailyCardLog(...)` | `GetDailyCardLog` | 일별 사용내역 | +| `getMonthlyCardLog(...)` | `GetMonthlyCardLog` | 월별 사용내역 | +| `getCardScrapRequestUrl(...)` | `GetCardScrapRequestURL` | 카드 등록 URL | +| `getCardManagementUrl(...)` | `GetCardManagementURL` | 카드 관리 URL | +| `getCardLogUrl(...)` | `GetCardLogURL` | 사용내역 URL | + +### 3.5 TI — 세금계산서 (3개) + +| 메서드 | SOAP 메서드 | 설명 | +|--------|-----------|------| +| `getHomeTaxUrl(...)` | `GetHomeTaxURL` | 매입/매출 관리 URL | +| `getTaxInvoiceIssueUrl(...)` | `GetTaxInvoiceIssueURL` | 세금계산서 발행 URL | +| `getTaxInvoiceListUrl(...)` | `GetTaxInvoiceListURL` | 세금계산서 목록 URL | + +### 3.6 KAKAOTALK — 카카오톡 (15개) + +| 메서드 | SOAP 메서드 | 설명 | +|--------|-----------|------| +| `getKakaotalkChannels(corpNum)` | `GetKakaotalkChannels` | 채널 목록 | +| `getKakaotalkChannelManagementUrl(...)` | `GetKakaotalkChannelManagementURL` | 채널 관리 URL | +| `getKakaotalkTemplates(corpNum, channelId)` | `GetKakaotalkTemplates` | 템플릿 목록 | +| `getKakaotalkTemplateManagementUrl(...)` | `GetKakaotalkTemplateManagementURL` | 템플릿 관리 URL | +| `sendATKakaotalk(...)` | `SendATKakaotalk` | 알림톡 단건 | +| `sendATKakaotalkEx(...)` | `SendATKakaotalkEx` | 알림톡 단건 (버튼) | +| `sendATKakaotalks(...)` | `SendATKakaotalks` | 알림톡 대량 | +| `sendFTKakaotalk(...)` | `SendFTKakaotalk` | 친구톡 텍스트 | +| `sendFTKakaotalks(...)` | `SendFTKakaotalks` | 친구톡 대량 | +| `sendFIKakaotalk(...)` | `SendFIKakaotalk` | 친구톡 이미지 | +| `sendFWKakaotalk(...)` | `SendFWKakaotalk` | 친구톡 와이드 이미지 | +| `getSendKakaotalk(corpNum, sendKey)` | `GetSendKakaotalk` | 전송결과 단건 | +| `getSendKakaotalks(corpNum, sendKeyList)` | `GetSendKakaotalks` | 전송결과 다건 | +| `cancelReservedKakaotalk(corpNum, sendKey)` | `CancelReservedKakaotalk` | 예약 취소 | + +### 3.7 SMS — 문자전송 (4개) + +| 메서드 | SOAP 메서드 | 설명 | +|--------|-----------|------| +| `sendSMSMessage(...)` | `SendSMSMessage` | SMS 단문 발송 | +| `checkSMSFromNumber(corpNum, fromNumber)` | `CheckSMSFromNumber` | 발신번호 확인 | +| `getSMSFromNumbers(corpNum)` | `GetSMSFromNumbers` | 발신번호 목록 | +| `getSMSSendState(corpNum, sendKey)` | `GetSMSSendState` | 전송 상태 | + +### 3.8 메서드 수 비교 + +| 카테고리 | MNG | API | 구현율 | +|---------|:---:|:---:|:------:| +| CORPSTATE | 3 | 3 | 100% | +| BANKACCOUNT | 13 | 14 | 100%+ | +| CARD | 11 | 11 | 100% | +| TI | 3 | 3 | 100% | +| KAKAOTALK | 15 | 15 | 100% | +| SMS | 4 | 4 | 100% | +| 유틸리티 | 5 | 7 | — | +| **합계** | **54** | **57** | **100%** | + +--- + +## 4. 동기화 서비스 + +### 4.1 BarobillBankSyncService + +은행 거래내역을 바로빌 SOAP에서 조회하여 `barobill_bank_transactions` 테이블에 캐시한다. + +``` +syncIfNeeded(tenantId, startYmd, endYmd) + ├─ BarobillMember 조회 → initForMember() + ├─ getRegisteredAccounts() — SOAP GetBankAccountEx + ├─ 월별 청크 분할 (splitDateRangeMonthly) + ├─ 캐시 판단: + │ ├─ 과거 월: 항상 캐시 (API 호출 안 함) + │ └─ 현재 월: 10분 이내면 캐시 + ├─ fetchAndCache() — SOAP GetPeriodBankAccountTransLog + ├─ cacheTransactions() — insertOrIgnore (100건씩 배치) + └─ updateSyncStatus() — BankSyncStatus 기록 +``` + +### 4.2 BarobillCardSyncService + +카드 거래내역을 바로빌 SOAP에서 조회하여 `barobill_card_transactions` 테이블에 캐시한다. + +``` +syncCardTransactions(tenantId, startYmd, endYmd) + ├─ BarobillMember 조회 → initForMember() + ├─ getRegisteredCards() — SOAP GetCardEx2 + ├─ 카드별 루프: + │ ├─ getPeriodCardLog() — SOAP 호출 + │ └─ cacheTransactions() — insertOrIgnore (100건씩 배치) + └─ 결과 반환 {synced, cards} +``` + +### 4.3 HometaxSyncService + +API 응답 데이터를 `hometax_invoices` 테이블에 upsert한다. + +``` +syncInvoices(invoices, tenantId, invoiceType) + ├─ nts_confirm_num 기준 upsert + ├─ 기존 레코드: API 필드만 업데이트 (memo/category/is_checked 보존) + ├─ 신규 레코드: create + └─ 트랜잭션 래핑 (실패 시 rollback) +``` + +--- + +## 5. API 엔드포인트 + +### 5.1 신규 추가 (11개) + +| Method | Path | 용도 | +|--------|------|------| +| `POST` | `/v1/barobill/sync/bank` | 수동 은행 동기화 | +| `POST` | `/v1/barobill/sync/card` | 수동 카드 동기화 | +| `POST` | `/v1/barobill/sync/hometax` | 수동 홈택스 동기화 | +| `GET` | `/v1/barobill/accounts` | 등록계좌 목록 (SOAP 실시간) | +| `GET` | `/v1/barobill/cards` | 등록카드 목록 (SOAP 실시간) | +| `GET` | `/v1/barobill/certificate` | 인증서 상태 (유효성/만료일) | +| `GET` | `/v1/barobill/balance` | 충전잔액 조회 | +| `POST` | `/v1/barobill/members` | 바로빌 회원 등록 (RegistCorp) | +| `PUT` | `/v1/barobill/members` | 바로빌 회원 수정 (UpdateCorpInfo) | +| `GET` | `/v1/barobill/members/status` | 바로빌 회원 상태 (GetCorpState) | + +### 5.2 기존 보강 (1개) + +| Method | Path | 변경 내용 | +|--------|------|----------| +| `GET` | `/v1/barobill/status` | 실제 계좌/카드 수 표시 (BarobillMember 연동) | + +### 5.3 기존 유지 (42개) + +은행 13개 + 카드 16개 + 홈택스 13개 — 변경 없음. + +--- + +## 6. 자동 동기화 스케줄러 + +### 6.1 Job 정의 + +`app/Jobs/Barobill/SyncBarobillDataJob.php` + +```php +// 생성자 파라미터로 동기화 유형 지정 +new SyncBarobillDataJob('bank') // 은행만 +new SyncBarobillDataJob('card') // 카드만 +new SyncBarobillDataJob('all') // 은행+카드 +``` + +### 6.2 스케줄러 등록 (`routes/console.php`) + +| 시간 | 유형 | 대상 | +|------|------|------| +| 매일 06:00 | `bank` | 전일 은행 거래내역 | +| 매일 06:30 | `card` | 전일 카드 거래내역 | + +### 6.3 대상 조건 + +`server_mode=production` AND `status=active`인 `barobill_members`만 동기화. + +--- + +## 7. 설정 구조 + +### 7.1 DB 설정 (`barobill_configs`) + +| id | environment | cert_key | corp_num | is_active | +|----|------------|----------|----------|-----------| +| 1 | test | `2DD6C76C-0...` | `6648603713` | true | +| 2 | production | `C0B36577-2...` | `6648603713` | true | + +### 7.2 설정 우선순위 + +``` +1. DB (barobill_configs) — BarobillConfig::getActive(isTestMode) +2. .env 폴백 — BAROBILL_CERT_KEY_TEST / BAROBILL_CERT_KEY_PROD +``` + +### 7.3 모드 결정 흐름 + +``` +BarobillMember.server_mode ('test' | 'production') + → BarobillSoapService.initForMember(member) + → switchServerMode(member.isTestMode()) + → initializeConfig() — DB 또는 .env에서 설정 로드 + → SOAP URL 구성 (testws / ws) +``` + +--- + +## 8. 현재 테스트 환경 데이터 + +### 8.1 등록된 바로빌 회원 (2026-03-17 기준) + +| id | tenant_id | 회사 | 바로빌 ID | 모드 | 상태 | +|----|-----------|------|----------|------|------| +| 1 | 1 | 테스트기업_wcg5c8 | `test_wcg5c8` | test | active | +| 2 | 1 | (주)코드브릿지엑스 | `cbx0913` | production | active | +| 3 | 290 | (주)주일기업 | `juil5130` | test | active | +| 4 | 289 | (주)경동기업 | `kd5130` | test | active | +| 5 | 287 | 프론트_테스트회사 | `testpro1` | test | active | +| 7 | 288 | 기획_테스트회사 | (없음) | test | pending | + +### 8.2 테스트 가능 테넌트 + +| 테넌트 | 사업자번호 | 바로빌 회원 | 테스트 적합성 | +|--------|----------|-----------|:----------:| +| 290 (주일기업) | 1388166437 | `juil5130` (test) | 즉시 테스트 가능 | +| 289 (경동기업) | 1398700333 | `kd5130` (test) | 즉시 테스트 가능 | +| 291 (미생성) | — | — | 풀 온보딩 테스트용 생성 필요 | +| 292 (데모제조) | 000-00-00000 | 없음 | 더미 사업자번호로 제한적 | + +### 8.3 온보딩 테스트 시나리오 + +**빠른 테스트** (기존 회원 활용): +```bash +# tenant_id=290으로 SOAP 연결 테스트 +docker exec sam-api-1 php artisan tinker --execute=" +\$soap = app(\App\Services\Barobill\BarobillSoapService::class); +\$member = \App\Models\Barobill\BarobillMember::withoutGlobalScopes()->find(3); +\$soap->initForMember(\$member); +dump(\$soap->checkConfiguration()); +dump(\$soap->getCorpState(\$member->biz_no)); +" +``` + +**풀 온보딩 테스트** (신규 테넌트): +``` +1. tinker로 tenant_id=291 생성 +2. POST /v1/barobill/members → RegistCorp +3. GET /v1/barobill/certificate-url → URL 확인 +4. GET /v1/barobill/accounts → 계좌 목록 +5. POST /v1/barobill/sync/bank → 동기화 테스트 +``` + +--- + +## 9. MNG 코드와의 대응 관계 + +| MNG 파일 | API 파일 | 비고 | +|----------|---------|------| +| `Services/Barobill/BarobillService.php` | `Services/Barobill/BarobillSoapService.php` | 독립 신규 작성, MNG 수정 없음 | +| `Services/Barobill/BarobillBankSyncService.php` | `Services/Barobill/BarobillBankSyncService.php` | 독립 신규 작성 | +| (EcardController 내 카드 동기화) | `Services/Barobill/BarobillCardSyncService.php` | 서비스로 분리 | +| `Services/Barobill/HometaxSyncService.php` | `Services/Barobill/HometaxSyncService.php` | 독립 신규 작성 | +| (MNG에 없음) | `Jobs/Barobill/SyncBarobillDataJob.php` | API 전용 신규 | +| `Controllers/Api/Admin/Barobill/*` | `Controllers/Api/V1/BarobillSyncController.php` | API용 컨트롤러 | + +--- + +## 관련 문서 + +| 문서 | 설명 | +|------|------| +| [바로빌 연동 시스템](./README.md) | 전체 구조, 모드, 과금, 테이블 | +| [테넌트 온보딩](./tenant-onboarding.md) | 6단계 프로세스 개념 | +| [온보딩 실행 가이드](../../guides/barobill-onboarding-guide.md) | 7단계 실행 절차 + API 예시 | +| [온보딩 실행 가이드 PPT](../../guides/barobill-onboarding-guide.pptx) | 12슬라이드 프레젠테이션 | + +--- + +**최종 업데이트**: 2026-03-17 diff --git a/features/barobill/tenant-onboarding.md b/features/barobill/tenant-onboarding.md index 859a67a..f4121bc 100644 --- a/features/barobill/tenant-onboarding.md +++ b/features/barobill/tenant-onboarding.md @@ -177,12 +177,58 @@ Phase 5 (운영 모드 전환) 전 확인: --- +## 5. 구현 현황 (2026-03-17) + +### 5.1 API SOAP 서비스 구축 완료 + +API에 MNG와 100% 동등한 SOAP 서비스가 독립 구축되었다. + +| 항목 | 파일 | 상태 | +|------|------|:----:| +| SOAP 래퍼 (6개 서비스, 49 메서드) | `BarobillSoapService.php` | ✅ | +| 은행 동기화 | `BarobillBankSyncService.php` | ✅ | +| 카드 동기화 | `BarobillCardSyncService.php` | ✅ | +| 홈택스 동기화 | `HometaxSyncService.php` | ✅ | +| 동기화/회원 API (11개) | `BarobillSyncController.php` | ✅ | +| 자동 동기화 Job | `SyncBarobillDataJob.php` | ✅ | + +> 상세: [API SOAP 기술 참조](./api-soap-reference.md) + +### 5.2 테스트 환경 데이터 + +| tenant_id | 회사 | 바로빌 ID | 모드 | 테스트 적합성 | +|-----------|------|----------|------|:----------:| +| 290 | (주)주일기업 | `juil5130` | test | 즉시 가능 (Step 3~7) | +| 289 | (주)경동기업 | `kd5130` | test | 즉시 가능 | +| 291 | (미생성) | — | — | 풀 온보딩 테스트용 | + +### 5.3 온보딩 테스트 시나리오 + +**시나리오 A: 빠른 SOAP 검증** (tenant_id=290) +``` +이미 바로빌 회원이 등록된 상태. +→ Step 3(인증서 URL 확인)부터 Step 7(동기화)까지 테스트. +→ 소요: 10분 +``` + +**시나리오 B: 풀 온보딩** (tenant_id=291 신규 생성) +``` +테넌트 생성 → 바로빌 회원 등록 → 인증서/계좌/카드 → 검증 → 운영 전환 +→ Step 1부터 Step 7까지 전 과정 테스트. +→ 소요: 1시간 (인증서/계좌 등록 포함) +``` + +--- + ## 관련 문서 | 문서 | 설명 | |------|------| | [바로빌 연동 시스템](./README.md) | 전체 구조, 테스트/운영 모드, 과금 정책 | -| [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | REST API 42개 엔드포인트 | +| [API SOAP 기술 참조](./api-soap-reference.md) | API SOAP 서비스 전체 메서드, 동기화, 스케줄러 | +| [온보딩 실행 가이드](../../guides/barobill-onboarding-guide.md) | 7단계 실행 절차, API 예시, 트러블슈팅 | +| [온보딩 실행 가이드 PPT](../../guides/barobill-onboarding-guide.pptx) | 12슬라이드 프레젠테이션 | +| [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | REST API 42개 + SOAP 11개 엔드포인트 | | [데모 테넌트 정책](../sales/demo-tenant-policy.md) | 영업파트너 데모 테넌트 3-Tier 전략 | ---