ERP / Channel Integration
가비아 하이웍스 Pharos ERP 채널 연동
- Java 11
- Spring Boot 2.7
- Spring Security
- Spring Data Redis
- MyBatis
- PostgreSQL
- NHN Cloud
- Jenkins
Overview
가비아 하이웍스 계정과 연동된 Pharos ERP 전용 서비스를 오픈한 프로젝트입니다. 하이웍스 계정 기반 진입·가입·로그인 플로우를 설계하고, 세금계산서 발행사를 팝빌에서 하이웍스 API로 전환했습니다.
Problem
- 하이웍스 클라이언트 토큰으로 Pharos 가입 여부를 판단하고 로그인 또는 회원가입으로 분기하는 연동 플로우가 필요했습니다.
- 기존 팝빌 세금계산서 발행 로직은 3,000라인 이상의 God Service에 API 호출, 검증, 저장, 발행 로직이 강하게 결합되어 있었습니다.
- 수정 세금계산서는 6가지 사유별로 발급 장수와 처리 방식이 달라 단순 분기 중심 구현은 유지보수성이 낮았습니다.
My Ownership
- 하이웍스 연동 인증 흐름과 세금계산서 발행사 전환 백엔드 구현을 리드했습니다.
- API 호출, 검증, 영속화, 포인트 롤백 책임을 독립 컴포넌트로 분리했습니다.
- 수정 세금계산서 사유별 처리 정책을 전략 + 템플릿메서드 구조로 구성했습니다.
Key Decisions
외부 API 분리API 호출 컴포넌트 분리
외부 발행사 변경 시 서비스 전체가 흔들리지 않도록 하이웍스 API 호출을 별도 컴포넌트로 분리하고 서비스는 발행 결과만 처리하도록 했습니다.
서비스 설계유스케이스 1개 = 서비스 1개
God Service의 영향 범위를 줄이고 수기 발행, 임시저장 발행, 수정 세금계산서, 전표 연동, 삭제, 조회를 독립 유스케이스로 분리했습니다.
수정 세금계산서전략 + 템플릿메서드 패턴
수정 사유별 처리 규칙이 달라 공통 발급 흐름은 추상화하고 사유별 세부 처리는 구현체에 위임했습니다.
Implementation
하이웍스 연동 플로우
하이웍스 클라이언트 토큰 발급 후 Pharos 서버가 사용자 정보를 조회하고, 가입 여부에 따라 로그인 또는 회원가입 흐름을 반환했습니다.
발행사 전환
팝빌 God Service를 분석한 뒤 하이웍스 발행 로직을 유스케이스별 독립 서비스로 신규 구축했습니다.
상태 동기화
국세청 신고가 비동기 처리되는 특성을 반영해 조회 시점에 전송 중 상태를 하이웍스 API로 확인하고 성공·실패 상태를 자동 반영했습니다.
Detailed Notes
하이웍스 연동 플로우
- 하이웍스 클라이언트 토큰 발급 후 Pharos로 진입하는 흐름을 구성했습니다.
- Pharos 서버가 토큰으로 하이웍스에서 사용자 정보를 조회하고, Pharos 가입 여부에 따라 로그인 또는 회원가입 응답을 반환했습니다.
- 하이웍스 API 의존성을 인터페이스로 추상화했습니다.
- 빈 문자열 null 처리를 위한 전용 ObjectMapper 설정을 분리했습니다.
- 하이웍스 API 에러 응답을 커스텀 예외로 변환해 서비스 계층의 처리 기준을 일원화했습니다.
팝빌 God Service 분석과 하이웍스 신규 구현
| 팝빌 God Service | 하이웍스 신규 구현 |
|---|---|
| 3,000+ 라인, 20+ 메서드에 모든 로직이 집중되어 있고 팝빌 API가 서비스 로직에 강결합되어 외부 API 전환 시 전체 수정이 필요했습니다. 검증·저장·발행 로직 중복으로 단위 테스트도 어려웠습니다. | 수기 발행, 임시저장 후 발행, 수정 세금계산서, 전표 연동, 거래명세서 연동, 삭제, 조회를 유스케이스별 독립 서비스로 신규 구축했습니다. 검증, API 호출, 영속화, 포인트 롤백을 독립 컴포넌트로 분리해 중복을 줄이고 테스트 가능한 구조를 확보했습니다. |
도메인 이벤트 기반 비동기 영속화
- 발행 완료 시 이벤트 스토어와 로그를 선적재한 뒤 세금계산서 테이블을 영속화했습니다.
- 영속화 실패 시 텔레그램 실시간 알림으로 운영자가 감지할 수 있게 했습니다.
- 이벤트 스토어 기반으로 재처리 가능한 구조를 만들었습니다.
수정 세금계산서 6가지 사유별 처리
수정 사유에 따라 발급 장수와 처리 방식이 달라 전략 + 템플릿메서드 패턴으로 공통 흐름과 사유별 처리를 분리했습니다.
| 수정 사유 | 발급 구성 |
|---|---|
| 기재사항 착오정정 | 취소분 1장 + 수정분 1장 (총 2장) |
| 공급가액 변동 | 변동분 수정 계산서 1장 |
| 환입 | 마이너스 세금계산서 1장 |
| 계약 해제 | 취소분 1장 |
| 내국신용장 사후개설 | 영세 계산서 1장 + 마이너스 계산서 1장 |
| 착오 이중발급 | 취소분 1장 |
포인트 롤백과 발행 상태 동기화
- 백오피스 포인트 모듈에 발행 전 선차감을 요청하고, 발행 성공건은 포인트를 유지하며 실패건은 즉시 롤백했습니다.
- 전체 예외 발생 시 전체 포인트를 롤백했습니다.
- 하이웍스 API의 국세청 신고 비동기 특성을 반영해 조회 시점에 전송 중 상태의 세금계산서를 하이웍스 API로 확인하고 성공·실패 상태를 자동 반영했습니다.
Result / Impact
- 하이웍스 클라이언트 토큰 기반 3단계 인증 흐름을 설계했습니다.
- 3,000라인 이상 God Service 기반 로직을 유스케이스별 독립 서비스로 전환했습니다.
- 수정 세금계산서 6가지 사유별 처리 규칙을 확장 가능한 정책 구조로 구현했습니다.