feat: project skeleton + DB migrations V1-V12 + ga-common framework

- Gradle multi-module: ga-common, ga-core, ga-api, ga-batch, ga-admin - Flyway V1-V12: org/product/rule/receive/ledger/settle/batch/code/menu/system + seed - ga-common (complete): - model: ApiResponse, PageResponse, SearchParam, TreeNode - exception: ErrorCode, BizException, GlobalExceptionHandler - annotation + aop: @RequirePermission, @DataChangeLog, ApiLog - auth + security: JWT, SecurityConfig - mybatis: BaseMapper, EncryptTypeHandler, JsonTypeHandler, AuditInterceptor - code (Redis cached) / menu (RBAC tree) / file / system / notification - excel: SXSSF+Cursor export, SAX+batch import (1M/700K rows) - util: Date/Money/Mask/Encrypt/Security
2026-05-09 21:29:18 +09:00
parent c716f5eb70
commit cef4e48e27
100 changed files with 4914 additions and 0 deletions
@@ -0,0 +1,113 @@
+# 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` 기반 메뉴×권한 매트릭스