ga-commission-system/README.md

# 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)

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

## 로컬 개발

### 1. PostgreSQL + Redis 기동
```bash
docker compose up -d postgres redis
```

### 2. ga-api 실행 (Flyway 자동 마이그레이션)
```bash
./gradlew :ga-api:bootRun
```

### 3. ga-batch 실행
```bash
./gradlew :ga-batch:bootRun
```

### 4. 프론트 실행
```bash
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분)
```java
// 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)

## 진행 상황

- [x] 1단계 — 프로젝트 뼈대 + DB (V1~V15)
- [x] **ga-common** — 공통 프레임워크 (model/exception/auth/security/code/menu/excel/file/system/notification)
- [x] **ga-core** — 22개 테이블의 VO/Mapper/XML
- [x] **ga-api** — Auth + 도메인 컨트롤러 (org/product/rule/receive/ledger/settle/payment/system)
- [x] **ga-batch** — MonthlySettlementJob 8 Step
- [x] **Docker** — docker-compose + multi-stage Dockerfile + nginx
- [x] **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 만 다른 버전으로 추가