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/     # 관리자 기능 — 예정
```

## 진행 상황

- [x] 1단계 — 프로젝트 뼈대 + DB 마이그레이션
  - [x] Gradle 멀티모듈 + 5개 모듈
  - [x] Flyway V1~V12 (조직/상품/규정/수신/원장/정산/배치/공통코드/메뉴/시스템/초기데이터)

- [x] **ga-common — 공통 프레임워크 (완성)**
  - [x] `model/`        — ApiResponse, PageResponse, SearchParam, TreeNode
  - [x] `exception/`    — ErrorCode, BizException, GlobalExceptionHandler
  - [x] `annotation/`   — @RequirePermission, @DataChangeLog, @ExcelColumn, @Mask
  - [x] `aop/`          — Permission/DataChangeLog/ApiLog Aspect
  - [x] `auth/`         — JwtTokenProvider, JwtAuthFilter, LoginUser
  - [x] `security/`     — SecurityConfig, JwtAuthEntryPoint, AccessDeniedHandler
  - [x] `config/`       — MyBatis/Redis/Swagger/Web/Async Config
  - [x] `mybatis/`      — BaseMapper, EncryptTypeHandler, JsonTypeHandler, AuditInterceptor
  - [x] `code/`         — CommonCodeService(Redis 캐시) + Controller + Mapper
  - [x] `menu/`         — MenuService, PermissionChecker, MenuTreeBuilder + Controller
  - [x] `excel/`        — 대용량 Export(SXSSF+Cursor) / Import(SAX+배치)
  - [x] `file/`         — FileService + Controller
  - [x] `system/`       — SystemConfig, DataChangeLog, ApiAccessLog Service
  - [x] `notification/` — NotificationService + Controller
  - [x] `util/`         — DateUtil, MoneyUtil, MaskUtil, EncryptUtil, SecurityUtil
  - [x] `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만 우선 검증)

```bash
# 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) 컨트롤러 표준 패턴
```java
@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) 서비스 표준 패턴
```java
public PageResponse<AgentResp> list(AgentSearchParam param) {
    param.startPage();                      // PageHelper
    return PageResponse.of(mapper.selectList(param));
}
```

### 3) 공통코드 검증
```java
codeService.validateCode("AGENT_STATUS", req.getStatus());  // 없으면 예외
String name = codeService.getCodeName("AGENT_STATUS", "ACTIVE");  // "정상"
```

### 4) 대용량 엑셀 다운로드
```java
@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` 기반 메뉴×권한 매트릭스