# 02_COMMON_SPEC — ga-common 공통 프레임워크

> 모든 다른 모듈이 의존하는 핵심. 신입 개발자가 학습하기 쉬운 단순/명시적 코드 우선.

## 패키지 구조

```
ga-common/src/main/java/com/ga/common/
├── annotation/   # @RequirePermission, @DataChangeLog, @ExcelColumn, @Mask
├── aop/          # PermissionAspect, DataChangeLogAspect, ApiLogAspect
├── auth/         # JwtTokenProvider, JwtAuthFilter, LoginUser
├── code/         # CommonCodeService/Controller/Mapper (Redis 캐시)
├── config/       # RedisConfig, SwaggerConfig, WebMvcConfig, AsyncConfig
├── exception/    # ErrorCode (enum), BizException, GlobalExceptionHandler
├── excel/        # ExcelService (Export 100만, Import 70만)
├── file/         # FileService/Controller (multipart 업로드/다운로드)
├── grid/         # GridSearchParam, GridResponse (AG Grid 서버사이드)
├── menu/         # MenuService/Controller, MenuTreeBuilder, PermissionChecker
├── model/        # ApiResponse<T>, PageResponse<T>, SearchParam, TreeNode
├── mybatis/      # BaseMapper, JsonTypeHandler, EncryptTypeHandler(+Initializer), AuditInterceptor
├── notification/ # NotificationService/Controller
├── security/     # SecurityConfig, JwtAuthEntryPoint, AccessDeniedHandlerImpl
├── system/       # SystemConfigService, DataChangeLogService, ApiAccessLogService, SystemLogController
└── util/         # DateUtil, MoneyUtil, MaskUtil, EncryptUtil, SecurityUtil

ga-common/src/main/resources/
├── mybatis/mybatis-config.xml
└── mapper/common/   # CommonCodeMapper.xml, MenuMapper.xml, FileMapper.xml, SystemConfigMapper.xml
```

build.gradle 핵심: `api 'org.springframework.boot:spring-boot-starter-{web,security,aop,validation,data-redis,cache}'`,
`api 'org.mybatis.spring.boot:mybatis-spring-boot-starter:3.0.3'`,
`api 'com.github.pagehelper:pagehelper-spring-boot-starter:2.1.0'`,
`api 'io.jsonwebtoken:jjwt-api:0.12.5'`, `api 'org.apache.poi:poi-ooxml:5.2.5'`,
`api 'com.monitorjbl:xlsx-streamer:2.2.0'`, `api 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'`

---

## 1. 공통 모델 (`model/`)

### `ApiResponse<T>` — 모든 API 응답 표준
```java
public class ApiResponse<T> {
    private boolean success;
    private String code;          // "0000" 성공
    private String message;
    private T data;
    private LocalDateTime timestamp;

    public static <T> ApiResponse<T> ok(T data) { ... }
    public static <T> ApiResponse<T> ok(T data, String msg) { ... }
    public static ApiResponse<Void> ok() { ... }
    public static <T> ApiResponse<T> fail(ErrorCode e) { ... }
    public static <T> ApiResponse<T> fail(String code, String msg) { ... }
}
```

### `PageResponse<T>` — PageHelper 연동
```java
public class PageResponse<T> {
    private List<T> list;
    private int pageNum, pageSize, pages;
    private long total;
    public static <T> PageResponse<T> of(List<T> list) {
        PageInfo<T> p = new PageInfo<>(list);
        // ...
    }
}
```

### `SearchParam` — 공통 검색 파라미터
```java
public class SearchParam {
    private int pageNum = 1, pageSize = 20;
    private String searchType, searchKeyword;
    private String startDate, endDate;
    private String status;
    private String sortField, sortOrder;     // ASC / DESC

    public void startPage() {
        PageHelper.startPage(pageNum, pageSize);
        if (sortField != null) PageHelper.orderBy(sortField + " " + sortOrder);
    }
}
```

### `TreeNode` — 트리 응답 공통 (메뉴/조직)
```java
public class TreeNode {
    private Object id, parentId;
    private String name, type;
    private int level, sortOrder;
    private List<TreeNode> children = new ArrayList<>();
}
```

### `GridSearchParam extends SearchParam` — AG Grid 서버사이드용
```java
public class GridSearchParam extends SearchParam {
    private List<Map<String,Object>> filterModel;   // AG Grid 필터
    private List<Map<String,String>> sortModel;     // AG Grid 정렬
    public String buildFilterSql() { ... }
}
```

---

## 2. 예외 처리 (`exception/`)

### `ErrorCode` enum
```java
SUCCESS("0000", 200), BAD_REQUEST("E400", 400),
UNAUTHORIZED("E401", 401), FORBIDDEN("E403", 403),
NOT_FOUND("E404", 404), INVALID_PARAMETER("E411", 400),
INTERNAL_ERROR("E500", 500),

TOKEN_EXPIRED("A001", 401), LOGIN_FAIL("A003", 401), ACCOUNT_LOCKED("A004", 403),

ALREADY_CONFIRMED("B001", 400), RULE_VERSION_CONFLICT("B002", 409),
APPROVAL_REQUIRED("B003", 400), SYSTEM_CODE_LOCKED("B008", 400),
DUPLICATE_DATA("B009", 409), BATCH_RUNNING("B010", 409),

FILE_NOT_FOUND("F001", 404), FILE_UPLOAD_FAIL("F002", 500);
```

### `BizException`
```java
@Getter
public class BizException extends RuntimeException {
    private final ErrorCode errorCode;
    private final String customMessage;
    public BizException(ErrorCode e) { ... }
    public BizException(ErrorCode e, String msg) { ... }
}
```

### `GlobalExceptionHandler`
- `BizException` → `ApiResponse.fail(errorCode)`
- `MethodArgumentNotValidException` → 필드별 에러 목록
- `AccessDeniedException` → 403
- `DuplicateKeyException` → "중복된 데이터입니다"
- `Exception` → 500 + log.error

---

## 3. MyBatis 공통 (`mybatis/`)

### `BaseMapper<T>` (선택적 상속)
```java
public interface BaseMapper<T> {
    T selectById(Long id);
    List<T> selectList(SearchParam param);
    int insert(T entity);
    int update(T entity);
    int deleteById(Long id);
    int countByCondition(SearchParam param);
}
```

### `JsonTypeHandler` — JSONB ↔ JsonNode
```java
@MappedTypes(JsonNode.class)
public class JsonTypeHandler extends BaseTypeHandler<JsonNode> { ... }
```

### `EncryptTypeHandler` — AES-256 컬럼 암호화
- **중요**: `@Component` 등록하면 mybatis-spring-boot-starter 가
  자동으로 모든 String 컬럼에 적용해버림 → 일반 클래스로 둠.
- 사용처: `<result property="residentNo" column="resident_no"
  typeHandler="com.ga.common.mybatis.EncryptTypeHandler"/>` 형태로 컬럼별 명시.
- `EncryptTypeHandlerInitializer` (`@Configuration`) 가 부팅 시
  `EncryptUtil` 을 정적 주입.
- 적용 컬럼: `agent.resident_no`, `agent.account_no`, `payment.account_no`.

### `AuditInterceptor` (Plugin)
- `INSERT` 시 `created_at`, `created_by` 자동
- `UPDATE` 시 `updated_at`, `updated_by` 자동
- 현재 로그인 사용자: `SecurityUtil.currentUserId()`

### 공통 SQL 조각 (`mapper/common/common-sql.xml`)
```xml
<sql id="searchCondition">
    <if test="searchKeyword != null and searchKeyword != ''">
        <choose>
            <when test="searchType == 'name'">AND name LIKE CONCAT('%', #{searchKeyword}, '%')</when>
            <when test="searchType == 'code'">AND code = #{searchKeyword}</when>
        </choose>
    </if>
    <if test="startDate != null">AND created_at &gt;= #{startDate}::timestamp</if>
    <if test="endDate != null">AND created_at &lt;= #{endDate}::timestamp + interval '1 day'</if>
    <if test="status != null and status != ''">AND status = #{status}</if>
</sql>
```

---

## 4. 인증/권한 (`auth/`, `security/`, `aop/`)

### JWT
- `JwtTokenProvider`: HS256, 액세스 2 시간 / 리프레시 7 일
- `JwtAuthFilter`: `Authorization: Bearer <token>` → SecurityContext 에 `LoginUser` 주입
- `LoginUser`: `userId`, `loginId`, `userName`, `roleCodes`, `agentId`

### `SecurityConfig`
- 기본 `permitAll`: `/api/auth/**`, `/swagger-ui/**`, `/v3/api-docs/**`, `/api/health`
- 그 외 `authenticated()` + JwtAuthFilter 적용
- 세션 STATELESS, CSRF disable, CORS allow `*` (개발), method-level `@PreAuthorize` 미사용 — `@RequirePermission` 으로 통일

### 어노테이션 + AOP

**`@RequirePermission(menu = "ORG_AGENT", perm = "READ")`**
- `PermissionAspect` 가 `PermissionChecker.hasPermission(userId, menuCode, permCode)` 호출
- `false` → `BizException(ErrorCode.FORBIDDEN)`

**`@DataChangeLog(menu = "RULE", table = "payout_rule")`**
- `DataChangeLogAspect` 가 메서드 실행 전 PK 로 before 조회 → 실행 → after 조회
- `data_change_log` 에 `before_data`/`after_data` JSONB 저장 (비동기)

**`@Mask(MaskType.RRN)` (응답 필드용 어노테이션)**
- `JsonSerializer` 또는 `@JsonComponent` 로 직렬화 시 마스킹

**`ApiLogAspect`**
- 모든 `@RestController` 자동 적용
- `request_uri`, `params` (민감정보 마스킹), `response_code`, `response_time_ms`
- `@Async` 비동기 저장 (`api_access_log`)

---

## 5. 유틸리티 (`util/`)

### `DateUtil`
- `today()` → `"2026-05-10"`
- `getSettleMonth()` → `"202605"`, `getSettleMonth(LocalDate)` 동일
- `getMonthRange("202605")` → `["2026-05-01", "2026-05-31"]`
- `calcMonthDiff(from, to)`, `addMonth("202401", 3)` → `"202404"`
- `parseDate(s, "yyyy-MM-dd")`, `format(date, pattern)`

### `MoneyUtil` (BigDecimal HALF_UP, 소수점 2)
- `add/sub/mul/div`, null 안전
- `pct(amount, ratePct)` → `amount × ratePct / 100`
- `tax(amount)` → 기본 3.3%, `tax(amount, rate)` 사용자 지정
- `fmt`/`fmtDec`/`fmtSign` (콤마 포맷)
- `isZero/isPositive/isNegative`

### `MaskUtil`
- `mask("홍길동", NAME)` → `"홍*동"`
- `mask("010-1234-5678", PHONE)` → `"010-****-5678"` (11자리/10자리 분기, 9자리 이하 원본)
- `mask("880101-1234567", RRN)` → `"880101-*******"`
- `mask("110-123-456789", ACCOUNT)` → `"110-***-******"`
- `mask("aaa@bbb.com", EMAIL)` → `"a**@bbb.com"`

### `EncryptUtil` (`@Component`)
- AES-256/CBC/PKCS5Padding, IV = key 의 앞 16 byte (운영은 별도 관리 권장)
- 키 32 byte 미만이면 0 패딩
- `encrypt(plain)` / `decrypt(b64)` round-trip
- 실패 시 `BizException(ErrorCode.INTERNAL_ERROR)`

### `SecurityUtil`
- `currentUserId()`, `currentLoginUser()`, `hasRole(roleCode)`

---

## 6. 공통코드 (`code/`) — Redis 캐시

```java
@Service @RequiredArgsConstructor
public class CommonCodeService {
    @Cacheable(value = "commonCode", key = "#groupCode")
    public List<CommonCodeVO> getCodesByGroup(String groupCode) {...}

    public String getCodeName(String groupCode, String code) {...}
    public void   validateCode(String groupCode, String code)  // 미존재 시 INVALID_PARAMETER

    @CacheEvict(value = "commonCode", key = "#groupCode")
    public void refreshCache(String groupCode) {}

    @CacheEvict(value = "commonCode", allEntries = true)
    public void refreshAll() {}

    // 그룹 CRUD: 시스템 그룹(is_system='Y')은 update/delete 시 SYSTEM_CODE_LOCKED
    // 상세 CRUD: 동일 (group, code) 중복 시 DUPLICATE_DATA
    //          시스템 그룹 코드 update 시 code/groupCode 변경 무시
}
```

REST: `GET /api/common/codes/{groupCode}` (캐시 적중), `POST /api/common/codes/groups`,
       `PUT/DELETE /api/common/codes/groups/{groupCode}`, 상세 코드 동일.

---

## 7. 메뉴 / 권한 (`menu/`)

### `MenuTreeBuilder` (정적 유틸)
```java
public static List<MenuResp> build(List<MenuVO> flat,
                                   Map<Long, List<String>> permissionsByMenuId)
// - parent_menu_id null → root
// - 부모 미존재 (고아) → root 로 끌어올림
// - sortOrder 로 재귀 정렬
// - permissionsByMenuId null 이면 권한 주입 스킵
```

### `PermissionChecker`
```java
@Component @RequiredArgsConstructor
public class PermissionChecker {
    @Cacheable(value = "userPerm",
        key = "T(java.lang.String).format('%d_%s_%s', #userId, #menuCode, #permCode)",
        unless = "#result == false")
    public boolean hasPermission(Long userId, String menuCode, String permCode) {
        if (userId == null) return false;
        return menuMapper.hasPermission(userId, menuCode, permCode) > 0;
    }
}
```

### `MenuService`
- `getMyMenus(userId)` → 사용자 권한 기반 메뉴 트리 (CTE 재귀)
- `getMenuTree()` → 전체 메뉴 트리 (관리자용)

REST: `GET /api/menus/my`, `GET /api/menus/tree`, 메뉴 CRUD + 권한 매트릭스.

---

## 8. 엑셀 엔진 (`excel/`)

성능 목표: **다운로드 100만건 < 2분 / 업로드 70만건 < 3분**

### `@ExcelColumn` 어노테이션
```java
@Target(FIELD) @Retention(RUNTIME)
public @interface ExcelColumn {
    String header();
    int order();
    int width() default 15;
    String format() default "";          // "#,##0", "yyyy-MM-dd"
    String codeGroup() default "";        // 자동 코드명 변환
    boolean masked() default false;       // 다운로드 시 마스킹
    String defaultValue() default "";
    boolean required() default false;
}
```

### `ExcelService`
**Export — `SXSSFWorkbook(100)` + `MyBatis Cursor`**
```java
public <T> void exportLargeExcel(String fileName, Class<T> clazz,
        Supplier<Cursor<T>> cursorSupplier, HttpServletResponse response) {
    // 1) SXSSFWorkbook (메모리 100행만 유지, gzip 임시파일)
    // 2) ExcelColumnParser.parse(clazz) → 헤더 자동 생성
    // 3) Cursor 로 1건씩 읽어 Row 생성
    // 4) 10만건마다 progress 로그
    // 5) workbook.write(response.getOutputStream()), workbook.dispose()
}
```

**Import — `xlsx-streamer (StreamingReader)` + 배치 INSERT**
```java
public <T> ExcelImportResult importLargeExcel(MultipartFile file, Class<T> clazz,
        int batchSize, Consumer<List<T>> batchConsumer) {
    // 1) StreamingReader (rowCacheSize 100, bufferSize 4KB)
    // 2) 1행 헤더 스킵
    // 3) ExcelRowParser.parse(row, clazz) → VO
    // 4) Bean Validation → 실패 시 ExcelErrorRow 누적
    // 5) batchSize(1000) 마다 batchConsumer.accept(batch)
    // 6) 잔여분 flush
    // 7) 에러 있으면 에러 엑셀 생성 → result.errorFileId
}
```

**`ExcelImportResult`**: `totalCount`, `successCount`, `errorCount`, `errorFileId`,
`List<ExcelErrorRow>` (처음 100건).

**Template Download**:
`exportTemplate(fileName, clazz, response)` — 빈 헤더 + `codeGroup` 컬럼에
드롭다운 유효성검사 + `required=true` 헤더 빨간색.

---

## 9. 파일 / 알림 / 시스템관리

### `FileService`
- 업로드: `MultipartFile` → `file_storage` 적재, `groupId` 로 그룹화, 최대 100MB
- 다운로드: `download_count` 증가, `Content-Disposition` 한글 파일명 인코딩
- 삭제: 논리 삭제 (`is_deleted='Y'`)

REST: `POST /api/files/upload` (`groupId` param), `GET /api/files/{fileId}`,
       `DELETE /api/files/{fileId}`, `GET /api/files?groupId=...`

### `NotificationService`
- 생성/조회/읽음 처리, 미읽음 카운트 (`/api/notifications/unread-count`)
- 발송은 비동기 (Redis pub/sub 또는 `@Async`)

### `SystemConfigService`
- key-value 설정. `is_encrypted='Y'` 인 값은 응답 시 마스킹.
- Cache 적용 가능 (`commonCode` 와 동일 패턴)

### 로그 서비스 (비동기)
- `ApiAccessLogService.save(...)` — `api_access_log` 적재
- `DataChangeLogService.save(...)` — `data_change_log` JSONB 적재
- 둘 다 `@Async("taskExecutor")` (`AsyncConfig`)

REST: `/api/system/logs/login`, `/api/system/logs/api`, `/api/system/logs/changes`
       (`/api/system/config`, `/api/system/config/{key}` PUT)

---

## 10. ga-frontend 공통 (함께 작성)

### 폴더 구조
```
ga-frontend/src/
├── api/             # request.ts (axios) + 도메인별 함수
├── components/
│   ├── common/      # 본 spec 의 공통 컴포넌트
│   └── biz/         # 업무 재사용
├── hooks/           # useCommonCodes, useMenuTree, usePermission, useSearchParam
├── layouts/         # MainLayout
├── pages/           # 화면 (06_FRONTEND_SPEC.md)
├── router/          # 동적 라우터
├── stores/          # Zustand (auth, menu, notification)
├── types/           # TS 타입
└── utils/           # formatMoney, formatDate
```

### `api/request.ts`
```typescript
const api = axios.create({ baseURL: import.meta.env.VITE_API_URL ?? '' });
api.interceptors.request.use(c => {
  const t = localStorage.getItem('accessToken');
  if (t) c.headers.Authorization = `Bearer ${t}`;
  return c;
});
api.interceptors.response.use(r => r, err => {
  if (err.response?.status === 401) { localStorage.removeItem('accessToken'); location.href = '/login'; }
  if (err.response?.status === 403) message.error('권한이 없습니다');
  return Promise.reject(err);
});
export type ApiResponse<T> = { success: boolean; code: string; message: string; data: T; };
export type PageResponse<T> = { list: T[]; pageNum: number; pageSize: number; total: number; pages: number; };
```

### 공통 훅 (`hooks/`)
- `useCommonCodes(groupCode)` — React Query 캐시 (`staleTime: 10분`)
- `useMenuTree()` — 사용자 메뉴 트리
- `usePermission(menuCode)` — `{ canRead, canCreate, canUpdate, canDelete, canApprove, canExport }`
- `useSearchParam(defaults)` — URL 동기화 + 페이징
- `useGridApi()` — AG Grid 서버사이드 datasource

### 공통 컴포넌트 (`components/common/`)

**데이터 표시**
- `<CodeSelect groupCode="AGENT_STATUS" />` — Ant Select + 공통코드
- `<CodeRadio groupCode="PAY_CYCLE" />`
- `<CodeBadge groupCode="SETTLE_STATUS" value="CONFIRMED" />` — 색 자동
  - 초록: CONFIRMED/APPROVED/ACTIVE/PAID
  - 파랑: PENDING/CALCULATED
  - 빨강: HOLD/SUSPEND/REJECTED
  - 회색: DRAFT/NEW
- `<MonthPicker />` — 정산월
- `<MoneyText value={amt} />` — 양수 검정 / 음수 빨강 / 콤마 / null → "-"

**검색 / 목록**
- `<SearchForm conditions={[ {type:'text'|'code'|'dateRange'|'month', name, label, ...} ]} onSearch onReset />`
- `<DataTable>` — Ant Design Table 래퍼 (단순 목록, 페이징, 행 클릭)
- `<DataGrid>` — AG Grid Community 래퍼 (서버사이드 페이징/정렬/필터, 셀 편집,
  컬럼 고정, 합계행 `pinnedBottomRow`, 엑셀 내보내기)

**액션**
- `<PermissionButton permCode="CREATE">등록</PermissionButton>`
- `<ExcelExportButton url="/api/.../export" params fileName showProgress maxRows={1000000} />`
- `<ExcelImportButton url=... templateUrl=... onComplete maxSize={100} />`
- `<FileUpload groupId="settle-202605" maxCount={5} />`
- `<AuditTrail table="payout_rule" recordId={id} />` — 변경이력 타임라인

### 동적 라우터 (`router/`)
- 로그인 → `GET /api/menus/my` → 메뉴 트리
- `menu.component_path` 기반 `React.lazy()` 동적 import
- 좌측 Sider 자동 렌더링, 권한 없는 URL → 403 페이지

### 레이아웃 (`layouts/MainLayout.tsx`)
- Ant Design Layout (Sider + Header + Content)
- Header: 알림 벨 (숫자 뱃지), 사용자 드롭다운, 정산월 표시
- Sider: 동적 메뉴 트리 (접기/펼치기, 아이콘)
- Content: Breadcrumb + 페이지

---

## 11. 단위 테스트 가이드 (선택)

`spring-boot-starter-test` 가 JUnit5 + Mockito + AssertJ 모두 포함.

대상:
- `MoneyUtilTest` (10) — pct/tax/mul/div HALF_UP, null 안전
- `DateUtilTest` (10) — 정산월 범위, 윤년/평년, 월 차이/가산
- `MaskUtilTest` (7)  — NAME/PHONE/RRN/ACCOUNT/EMAIL
- `EncryptUtilTest` (6) — round-trip, 한글, 짧은 키 패딩
- `MenuTreeBuilderTest` (6) — 트리 빌드, 정렬, 고아 노드
- `PermissionCheckerTest` (4) — userId null 단락, mapper 위임
- `CommonCodeServiceTest` (14) — 그룹·상세 CRUD, 시스템 코드 잠금

주의: `@Cacheable`/`@CacheEvict` 는 단위 테스트(직접 인스턴스 호출)에서 동작하지 않음 — 비즈니스 로직만 검증.
Mockito strict stubbing → `@BeforeEach` 의 stub 은 모든 테스트가 사용해야 함.