GA 수수료 정산 솔루션

법인보험대리점(GA) 수수료 정산 시스템 — Multi-module Spring Boot + React.

기술 스택

영역	기술
Backend	Java 17, Spring Boot 3.2, Spring Security, Spring Batch
ORM	MyBatis 3 + PageHelper
DB	PostgreSQL 16
Cache	Redis 7
Build	Gradle 멀티모듈
Frontend	React 18 + Vite + TypeScript + Ant Design 5 + AG Grid + React Query + Zustand
Infra	Docker Compose, Nginx

모듈 구조

ga-commission-system/
├── ga-common/    # 공통 프레임워크 (인증/권한/로그/엑셀/공통코드/메뉴)
├── ga-core/      # 도메인 코어 (VO, Mapper, SQL)
├── ga-api/       # REST API (포트 8080)
├── ga-batch/     # Spring Batch (포트 8081)
├── ga-admin/     # 관리자 라이브러리
└── ga-frontend/  # React SPA (포트 3000)

빠른 시작 (Docker Compose)

docker compose up -d --build
# 프론트:   http://localhost:3000
# API:     http://localhost:8080/swagger-ui.html
# Batch:   http://localhost:8081 (내부)

로컬 개발

1. PostgreSQL + Redis 기동

docker compose up -d postgres redis

2. ga-api 실행 (Flyway 자동 마이그레이션)

./gradlew :ga-api:bootRun

3. ga-batch 실행

./gradlew :ga-batch:bootRun

4. 프론트 실행

cd ga-frontend
npm install
npm run dev
# http://localhost:3000

주요 기능

백엔드

• 인증/권한: JWT (HS256), 메뉴×권한 RBAC, BCrypt 비밀번호
• 공통코드: Redis 캐시, 시스템코드 잠금, REST CRUD
• 메뉴: 트리 구조, 사용자별 동적 메뉴 + 권한 매트릭스
• 엑셀: SXSSF+Cursor 다운로드(100만건), SAX+배치 업로드(70만건)
• 로그: 로그인/API/데이터변경 자동 기록 (비동기)
• 암호화: AES-256 CBC (resident_no, account_no)

도메인

• 조직: 트리 구조, CTE 재귀, 인사 이력
• 계약: 보험사/상품/계약 관리
• 수수료 규정: 보험사율, 지급율, 오버라이드, 환수, 예외코드
• 원장: 모집/유지/예외 (PageHelper, AG Grid 서버사이드 가능)
• 정산: 8 Step 배치 (수신→변환→대사→모집→유지→환수/예외→오버라이드→집계)
• 지급: 이체파일 생성, 상태 추적

정산 배치 8 Step

1. receiveData — 보험사별 DataReceiver → raw_commission_data 적재
2. transformData — MappingEngine으로 표준 변환
3. reconcile — 보험사 통보액 vs 시스템 계산액 대사
4. calcRecruit — 모집수수료 (계약시점 규정 적용)
5. calcMaintain — 유지수수료 (납입주기 매칭)
6. chargebackException — 환수 자동생성
7. calcOverride — 조직 트리 오버라이드
8. aggregate — 통합 집계 → settle_master UPSERT (3.3% 세금)

신입 개발자 표준 패턴

Backend (5분)

// 1) VO (XxxVO + XxxResp + XxxSaveReq + XxxSearchParam)
@Data
public class FooSearchParam extends SearchParam { }

// 2) Mapper Interface + XML
@Mapper
public interface FooMapper {
    List<FooResp> selectList(FooSearchParam p);
}

// 3) Service
@Service @RequiredArgsConstructor
public class FooService {
    private final FooMapper mapper;
    public PageResponse<FooResp> list(FooSearchParam p) {
        p.startPage();
        return PageResponse.of(mapper.selectList(p));
    }
}

// 4) Controller
@RestController @RequestMapping("/api/foos") @RequiredArgsConstructor
public class FooController {
    private final FooService service;
    @GetMapping
    @RequirePermission(menu = "FOO", perm = "READ")
    public ApiResponse<PageResponse<FooResp>> list(FooSearchParam p) {
        return ApiResponse.ok(service.list(p));
    }
}

보안

• JWT (HS256) — 액세스 2시간, 리프레시 7일
• AES-256 CBC 암호화 (자동 적용 — EncryptTypeHandler)
• RBAC — role_menu_permission 매트릭스
• @DataChangeLog — 데이터 변경 이력 AOP 자동
• API 접근 로그 — 비동기 저장

DB 마이그레이션

• V1~V8: 도메인 스키마 + 초기 데이터
• V9~V12: 공통코드/메뉴/시스템관리 + 초기 데이터
• V13: 인덱스 최적화
• V14: 파티셔닝 helper 함수
• V15: 통계/리포트 뷰 (v_agent_monthly_summary, v_org_settle_summary, v_chargeback_risk)

진행 상황

• 1단계 — 프로젝트 뼈대 + DB (V1~V15)
• ga-common — 공통 프레임워크 (model/exception/auth/security/code/menu/excel/file/system/notification)
• ga-core — 22개 테이블의 VO/Mapper/XML
• ga-api — Auth + 도메인 컨트롤러 (org/product/rule/receive/ledger/settle/payment/system)
• ga-batch — MonthlySettlementJob 8 Step
• Docker — docker-compose + multi-stage Dockerfile + nginx
• ga-frontend — Vite + React + AntD + React Query 스켈레톤 (로그인 + 대시보드 + 동적 메뉴)

향후 확장

• 프론트 페이지 추가: menu 테이블 등록 → React 페이지 구현 → 동적 라우팅 적용
• 신규 보험사: company_profile + company_field_mapping 등록 + DataReceiver 구현
• 신규 정산 규정: commission_rate/payout_rule/override_rule/chargeback_rule 의 effective_from 만 다른 버전으로 추가