ga-commission-system/README.md

GA 수수료 정산 솔루션

법인보험대리점(GA) 수수료 정산 시스템.

기술 스택

영역	기술
Backend	Java 17, Spring Boot 3.2, Spring Security, Spring Batch
ORM	MyBatis 3 + PageHelper
DB	PostgreSQL 14+
Cache	Redis 7
Build	Gradle 멀티모듈
Frontend	(예정) React 18 + Ant Design 5 + AG Grid

모듈 구조

ga-commission-system/
├── ga-common/    # 공통 프레임워크 (인증/권한/로그/엑셀/공통코드/메뉴 등)
├── ga-core/      # 도메인 코어 (VO, Mapper, SQL) — 예정
├── ga-api/       # REST API (실행 모듈)
├── ga-batch/     # Spring Batch (실행 모듈) — 예정
└── ga-admin/     # 관리자 기능 — 예정

진행 상황

• 1단계 — 프로젝트 뼈대 + DB 마이그레이션

  • Gradle 멀티모듈 + 5개 모듈
  • Flyway V1~V12 (조직/상품/규정/수신/원장/정산/배치/공통코드/메뉴/시스템/초기데이터)

• ga-common — 공통 프레임워크 (완성)

  • model/ — ApiResponse, PageResponse, SearchParam, TreeNode
  • exception/ — ErrorCode, BizException, GlobalExceptionHandler
  • annotation/ — @RequirePermission, @DataChangeLog, @ExcelColumn, @Mask
  • aop/ — Permission/DataChangeLog/ApiLog Aspect
  • auth/ — JwtTokenProvider, JwtAuthFilter, LoginUser
  • security/ — SecurityConfig, JwtAuthEntryPoint, AccessDeniedHandler
  • config/ — MyBatis/Redis/Swagger/Web/Async Config
  • mybatis/ — BaseMapper, EncryptTypeHandler, JsonTypeHandler, AuditInterceptor
  • code/ — CommonCodeService(Redis 캐시) + Controller + Mapper
  • menu/ — MenuService, PermissionChecker, MenuTreeBuilder + Controller
  • excel/ — 대용량 Export(SXSSF+Cursor) / Import(SAX+배치)
  • file/ — FileService + Controller
  • system/ — SystemConfig, DataChangeLog, ApiAccessLog Service
  • notification/ — NotificationService + Controller
  • util/ — DateUtil, MoneyUtil, MaskUtil, EncryptUtil, SecurityUtil
  • grid/ — GridSearchParam, GridResponse (AG Grid 서버사이드)

• ga-core (예정) — 22개 테이블의 VO/Mapper/XML

• ga-api (예정) — Controller + Service

• ga-batch (예정) — MonthlySettlementJob 8 Step

• ga-frontend (예정) — React + AntD + AG Grid

실행 (DB만 우선 검증)

# PostgreSQL & Redis 기동 후 (예: docker compose)
psql -h localhost -U ga -c "CREATE DATABASE ga"

# Flyway 마이그레이션은 ga-api 부팅 시 자동 실행됨
# (ga-api의 spring.datasource 와 Flyway 설정에 따름)
./gradlew :ga-api:bootRun

핵심 사용 예시

1) 컨트롤러 표준 패턴

@RestController @RequestMapping("/api/agents")
@RequiredArgsConstructor
public class AgentController {
    private final AgentService service;

    @GetMapping
    @RequirePermission(menu = "ORG_AGENT", perm = "READ")
    public ApiResponse<PageResponse<AgentResp>> list(AgentSearchParam param) {
        return ApiResponse.ok(service.list(param));
    }
}

2) 서비스 표준 패턴

public PageResponse<AgentResp> list(AgentSearchParam param) {
    param.startPage();                      // PageHelper
    return PageResponse.of(mapper.selectList(param));
}

3) 공통코드 검증

codeService.validateCode("AGENT_STATUS", req.getStatus());  // 없으면 예외
String name = codeService.getCodeName("AGENT_STATUS", "ACTIVE");  // "정상"

4) 대용량 엑셀 다운로드

@GetMapping("/export")
@RequirePermission(menu = "LEDGER", perm = "EXPORT")
public void export(LedgerSearchParam param, HttpServletResponse res) {
    excelService.exportLargeExcel("모집수수료원장",
        RecruitLedgerExcelVO.class,
        () -> ledgerMapper.selectCursor(param), res);
}

보안

• JWT (HS256) — 액세스 2시간, 리프레시 7일
• AES-256 CBC 암호화 (resident_no, account_no) — EncryptTypeHandler 자동 적용
• RBAC — role_menu_permission 기반 메뉴×권한 매트릭스