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

---

## 🚀 실행 가이드

### 환경 요구사항

- **Java 17+** (`java -version` 확인)
- **Node.js 18+** + npm
- **PostgreSQL 14+** (운영: `192.168.0.60:55432/trading_ai/ga` schema)
- **Redis 7+** (선택 — 공통코드/세션 캐시)
- **Gradle** (또는 IDE: IntelliJ IDEA 권장 — 자동으로 Gradle wrapper 생성)

### 시나리오 A — 운영 DB(trading_ai/ga) 에 연결해서 실행 ⭐ 권장

V1~V17 마이그레이션 + 테스트 데이터(보험사 5 / 상품 20 / 설계사 50 / 계약 200)가
`192.168.0.60:55432/trading_ai/ga` 스키마에 적용되어 있습니다.

> **운영 DB 상태 (2026-05-17 기준)**: V73 적용 완료. V74(메뉴/권한 전수보강) 작성 완료, 대기 중.
> ga-api 를 재시작하면 Flyway 가 V74 를 자동 적용합니다(멱등).
> DB 복귀 후 `python verify_v74.py` 로 보강 결과를 검증하세요.

#### 1) Backend (ga-api) 실행

```bash
# 1-1. Gradle wrapper 가 없다면 한 번 생성 (Gradle 설치 필요)
gradle wrapper --gradle-version 8.6

# 1-2. 빌드
./gradlew :ga-api:bootJar

# 1-3. 실행 (trading_ai 프로파일 — 운영 DB 연결)
./gradlew :ga-api:bootRun --args='--spring.profiles.active=trading_ai'

# 또는 환경변수로 비밀번호/Redis 호스트 오버라이드
export DB_PASSWORD=your-password
export REDIS_HOST=localhost
java -jar ga-api/build/libs/ga-api.jar --spring.profiles.active=trading_ai
```

확인:
- API:     http://localhost:8080
- Swagger: http://localhost:8080/swagger-ui.html

#### 2) Backend (ga-batch) 실행 — 정산 배치 트리거 처리

```bash
./gradlew :ga-batch:bootRun --args='--spring.profiles.active=trading_ai'
# 또는
java -jar ga-batch/build/libs/ga-batch.jar --spring.profiles.active=trading_ai
```

기본 포트 8081. ga-api 가 `/api/batch/settlement/run` 호출 시 batch_job_log 에
`REQUESTED` 상태로 기록되며, ga-batch 가 이를 폴링/직접 호출로 실행합니다.

#### 3) Frontend 실행

```bash
cd ga-frontend
npm install
npm run dev    # http://localhost:3000 (Vite dev server)
```

기본적으로 `/api/*` 요청은 Vite 프록시로 `http://localhost:8080` 으로 전달됩니다.

#### 4) 로그인 & 동작 확인

```
URL : http://localhost:3000
ID  : admin
PW  : admin1234!
```

로그인 후 사이드바 메뉴 — 좌측에 동적으로 메뉴가 그려져야 합니다.
주요 화면:

| 메뉴 | 경로 | 설명 |
|------|------|------|
| 대시보드 | `/` | 정산 요약 카드 |
| 설계사 관리 | `/org/agents` | 50명 더미 + 검색/등록/수정/엑셀 |
| 계약 관리 | `/contracts` | 200건 더미 + 상태/보험사 필터 |
| 모집수수료 원장 | `/ledger/recruit` | AG Grid 호환 테이블 + 엑셀 다운로드 |
| 예외금액 원장 | `/ledger/exception` | 승인/반려 |
| 정산 결과 | `/settle` | 월 요약 + 확정/보류 |
| 정산 배치 | `/settle/batch` | 배치 실행 + 진행률 폴링 |
| 지급 관리 | `/payments` | 지급 상태 추적 |
| 연말 사업소득 명세서 | `/settle/annual-income` | 설계사별 연간 사업소득 집계 + 재집계 (P5-W1) |
| 분개장 | `/settle/accounting-journal` | 회계 자동분개 엔트리 + 마감 처리 (P5-W1) |
| 원천세 신고 | `/tax/withholding-tax` | 분기별 원천세 신고 집계 + 재집계 + 제출완료 처리 (P5-W2) |
| 부가세 신고 | `/tax/vat` | 분기별 부가세 신고 집계 + 재집계 + 제출완료 처리 (P5-W2) |
| 사용자 관리 | `/system/users` | 비번 초기화/잠금 해제 |
| 역할/권한 | `/system/roles` | 권한 매트릭스 (메뉴 × 6권한) |
| 공통코드 | `/system/codes` | 그룹별 코드 조회 |

---

### 시나리오 B — 로컬 PostgreSQL 로 처음부터 (개발용)

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

# 2) ga-api 실행 (Flyway 가 자동으로 V1~V55 마이그레이션)
./gradlew :ga-api:bootRun
# 기본 프로파일은 application.yml — localhost:5432/ga 에 연결

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

# 4) 프론트
cd ga-frontend && npm install && npm run dev
```

`application.yml` 의 기본 DB:
```yaml
url: jdbc:postgresql://localhost:5432/ga
username: ga
password: ga
```

---

### 시나리오 C — Docker Compose 로 전체 기동

```bash
docker compose up -d --build
# postgres + redis + api + batch + frontend 모두 컨테이너로 기동
# - 프론트: http://localhost:3000
# - API:    http://localhost:8080/swagger-ui.html
# - Batch:  http://localhost:8081 (내부 통신용)
```

`docker-compose.yml` 환경변수:
- `JWT_SECRET` — JWT 서명 키 (256bit 이상)
- `ENCRYPT_KEY` — AES-256 키 (32바이트)

---

### DB 마이그레이션 직접 실행 (스크립트)

저장소 루트의 `migrate.py` (이 파일은 ga-commission-system 외부에 있음) — Python + pg8000 으로
V1~V17 SQL을 임의 DB에 일괄 적용:

```bash
pip install pg8000
python migrate.py
# host/port/db/user/schema 는 파일 상단 상수로 수정
```

`ga` 스키마가 이미 있으면 idempotent guard 로 멈춥니다.
완전 재설치는 `DROP SCHEMA ga CASCADE; CREATE SCHEMA ga;` 후 재실행.

---

## 🧪 데이터 확인 (운영 DB 기준)

| 테이블 | 건수 |
|--------|------|
| insurance_company | 5 (삼성/한화/교보/디비/KB) |
| product | 20 (보험사 × 4상품) |
| organization | 7 (본부 1 / 지점 3 / 팀 3) |
| agent | 50 (GM 3 / DM 3 / SMGR 6 / SFC 12 / FC 26) |
| contract | 200 (ACTIVE 190 / LAPSE 10) |
| commission_rate | 100 |
| payout_rule | 120 |
| override_rule | 10 |
| chargeback_rule | 4 |
| common_code (그룹/상세) | 18 / 42 |
| menu / menu_permission | 33 / 150 |
| role / role_menu_permission | 4 / 323 |

---

## 🔧 트러블슈팅

### Q. `./gradlew` 가 없다고 함
`gradle wrapper --gradle-version 8.6` 로 한번 생성하거나, IntelliJ 로 프로젝트 열면 자동 생성.

### Q. ga-api 부팅 시 `Failed to determine a suitable driver class`
JDBC URL 또는 자격증명 누락. `--spring.profiles.active=trading_ai` 가 적용됐는지 확인.

### Q. `NoSuchKey: ga` (Flyway)
운영 DB 의 `ga` 스키마를 인식하려면 `currentSchema=ga` 가 URL 에 있어야 함.
`application-trading_ai.yml` 에서 이미 설정되어 있음.

### Q. 프론트에서 401 / "토큰이 만료되었습니다"
`localStorage` 에 `accessToken` 이 만료됨. `/login` 으로 다시 로그인.

### Q. AG Grid 가 빈 화면으로 보임
`@ag-grid-community/styles/ag-theme-quartz.css` import 가 잘 됐는지 확인.

### Q. 비밀번호 변경
```sql
-- BCrypt 해시 생성 후 직접 UPDATE
UPDATE ga.users SET password = '$2b$10$...' WHERE login_id = 'admin';
```
또는 사용자 관리 화면 → "비번초기화" 액션.

---

## 📋 주요 기능

### 공통 프레임워크 (ga-common)
- **인증/권한**: JWT (HS256 액세스 2h/리프레시 7d), 메뉴×6권한 RBAC, BCrypt 비밀번호
- **공통코드**: Redis 캐시, 시스템코드 잠금, REST CRUD
- **메뉴**: 트리 구조, 사용자별 동적 메뉴 + 권한 매트릭스
- **엑셀**: SXSSF+Cursor 다운로드(100만건), SAX+배치 업로드(70만건)
- **로그**: 로그인/API/데이터변경 자동 기록 (비동기 `@DataChangeLog` AOP)
- **암호화**: AES-256 CBC (`resident_no`, `account_no` TypeHandler 자동 적용)
- **업로드 템플릿**: 동적 컬럼 매핑 + 변환 규칙 관리

### P0/P1 — 핵심 정산 도메인
- **세무 (P0-1)**: TaxCalculator 순수 도메인 — 사업소득 3.3% / 기타소득 8.8% / 지방세 10% / VAT 10%
- **공제 (P0-2)**: agent_deduction 월별 차감 마스터 + payment_deduction_detail 이체 명세
- **명세서 (P0-3)**: commission_statement 발급 마스터 + ExcelStatementGenerator (SXSSF)
- **1200%룰 (P1-1)**: regulatory_limit 마스터 + RegulatoryLimitChecker (효력일 이력 추적)
- **분급 (P1-2)**: installment_plan 7년 (35/25/15/10/7/5/3%) + InstallmentPlanGenerator
- **차등환수 (P1-3)**: chargeback_grade 5단계 + ChargebackCalculator

### P2 — 운영 필수 8 도메인 (V29~V36)
- **마감 (P2-1)**: period_close — 월 마감 + 마감 후 수정 차단 가드
- **정정 (P2-2)**: settle_correction — 원본 참조 정정 + 사유 코드
- **이의신청 (P2-3)**: commission_dispute — OPEN/IN_REVIEW/APPROVED/REJECTED 워크플로우
- **보류사유 (P2-4)**: settle_master.hold_reason_code + HOLD_REASON 코드그룹
- **시책·인센티브 (P2-5)**: incentive_program + incentive_payment
- **해촉정산 (P2-6)**: termination_settlement (agent_org_history 연계)
- **세금계산서 (P2-7)**: tax_invoice 발행 이력 (SUPPLY/PURCHASE)
- **외부회신 (P2-8)**: carrier_reconciliation_out — 보험사 회신 인터페이스

### P3 — KPI 대시보드 (V37~V39)
- **월별 KPI**: mv_monthly_summary Materialized View + AG Grid 합계행
- **조직별 KPI**: mv_org_summary — 조직 트리별 실적
- **유지율 KPI**: mv_retention_rate — 13M/25M 유지율 추적
- **누계 KPI**: mv_cumulative — 연초 누계 + 차트

### P4-A — 수수료 종류 보강 (V40~V44)
- **commission_master 통합 (P4-A-1)**: commission_type 9종 코드 통합 — 모집/유지/수금/오버라이드/갱신/부활/유지보수수당/시책/위촉
- **수금수수료 (P4-A-2)**: collection_commission_rule + collection_commission_ledger — 납입주기별 차등
- **갱신·부활수수료 (P4-A-3)**: renewal_commission_rule/ledger + reinstatement_commission_rule/ledger
- **유지보수수당 (P4-A-4)**: persistency_bonus_rule + persistency_bonus — 13M/25M/37M 유지율 1회 지급
- **오버라이드 원장 (P4-A-5)**: override_ledger + override_summary — 직급별/조직별 합계 + 검증

### P4-B — 운영 필수 9 도메인 (V45~V53)
- **위촉계약 (P4-B-1)**: agent_contract — 보험사별 위촉계약서 + 위촉수수료 + 효력 기간
- **자격관리 (P4-B-2)**: agent_license — 생보/손보/변액 자격증 + 만료일 + 갱신 이력
- **보수교육 (P4-B-3)**: agent_training — 의무 12시간/년 이수 추적
- **계약변경 (P4-B-4)**: contract_endorsement — 변경 유형 + 수수료 재계산 트리거
- **민원관리 (P4-B-5)**: complaint — 고객 민원 + 설계사 책임 + 환수 연동
- **결재워크플로우 (P4-B-6)**: approval_line + approval_request — 최대 3단계 다단 결재
- **공지·알림 (P4-B-7)**: notice + user_notification — 시스템 공지 + 읽음 여부
- **첨부파일 (P4-B-8)**: attachment — 도메인 무관 공통 첨부 (소속/경로/타입)
- **출금신청 (P4-B-9)**: withdraw_request — 결재 + 펌뱅킹 송신 + 결과 반영

### P5 Wave 2 — 원천세/부가세 분기신고 (V67~V69)
- **원천세 신고** (`/tax/withholding-tax`): 분기별 설계사 사업소득 원천세 신고 집계, 재집계 + 제출완료 처리
  - `GET /api/withholding-tax-reports` — 목록 조회 (settleQuarter/agentId/orgId/fileStatus 필터)
  - `GET /api/withholding-tax-reports/{id}` — 단건 상세
  - `POST /api/withholding-tax-reports/regenerate {"settleQuarter":"YYYY-Qn"}` — 분기 재집계 (EXECUTE 권한)
  - `PUT /api/withholding-tax-reports/complete {"ids":[...]}` — 제출완료 처리 (EXECUTE 권한)
- **부가세 신고** (`/tax/vat`): tax_invoice 기반 분기 매출/매입 VAT 집계, 재집계 + 제출완료 처리
  - `GET /api/vat-reports` — 목록 조회 (settleQuarter/fileStatus 필터)
  - `GET /api/vat-reports/{id}` — 단건 상세
  - `POST /api/vat-reports/regenerate {"settleQuarter":"YYYY-Qn"}` — 분기 재집계 (EXECUTE 권한)
  - `PUT /api/vat-reports/complete {"ids":[...]}` — 제출완료 처리 (EXECUTE 권한)

### P5 Wave 1 — 회계 진입점 (V63~V66)
- **연말 사업소득 명세서** (`/settle/annual-income`): 설계사별 귀속연도 사업소득 집계, 재집계 버튼
  - `GET /api/agent-annual-incomes` — 목록 조회 (settleYear/agentId/orgId 필터)
  - `GET /api/agent-annual-incomes/{agentId}/{settleYear}` — 단건 상세
  - `POST /api/agent-annual-incomes/regenerate?year=YYYY` — 연도 전체 재집계 (EXECUTE 권한)
- **분개장** (`/settle/accounting-journal`): 수수료 지급 자동분개 엔트리, 마감(journalNo 채번) 기능
  - `GET /api/accounting-entries` — 분개 목록 (settleMonth/journalNo/status 필터)
  - `POST /api/accounting-entries/generate` — 정산월 기준 분개 자동생성 (settleMonth or paymentIds)
  - `PUT /api/accounting-entries/close` — 분개 마감 처리 (entryIds + journalNo)
- **계정코드 마스터** (공통 드롭다운용)
  - `GET /api/common/account-codes?accountType=DEBIT|CREDIT|BOTH` — 활성 계정코드 목록
  - `GET /api/common/account-codes/all` — 전체 (시스템관리용)
  - `POST /api/common/account-codes` — 등록
  - `PUT /api/common/account-codes/{accountCode}` — 수정
  - `DELETE /api/common/account-codes/{accountCode}` — 삭제

### 정산 배치 10 Step
1. **receiveData** — 보험사별 DataReceiver → raw_commission_data 적재
2. **transformData** — MappingEngine 으로 raw → 표준 원장 (TRIM/UPPER/DATE/DIVIDE/CODE_MAP)
3. **reconcile** — 보험사 통보액 vs 시스템 계산액 대사
4. **calcRecruit** — 모집수수료 (계약시점 commission_rate/payout_rule 적용)
5. **calcMaintain** — 유지수수료 (납입주기 매칭, 1~5년차)
6. **chargebackException** — 실효 계약 환수 자동생성
7. **calcOverride** — 조직 트리 상향 탐색 → 상위 직급에 분배
8. **aggregate** — 설계사별 통합 집계 → settle_master UPSERT (3.3% 세금)
9. **accountingEntryGenerate** — recruit_ledger+maintain_ledger → contract_accounting_entry INSERT
10. **yearEndIncomeAggregate** — 12월 마감 시만 실행: payment 합산 → agent_annual_income UPSERT

---

## 🛠 신입 개발자 표준 패턴 (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 접근 로그 — 비동기 저장 (`api_access_log`)

---

## 🗄 DB 마이그레이션

| 버전 | 내용 |
|------|------|
| V1~V8 | 도메인 스키마 + 초기 데이터 (직급, 예외코드) |
| V9~V12 | 공통코드/메뉴/시스템관리 + 초기 데이터 |
| V13 | 인덱스 최적화 |
| V14 | 파티셔닝 helper 함수 |
| V15 | 통계/리포트 뷰 (v_agent_monthly_summary 등) |
| V16 | 관리자 계정 + 메뉴 상세 + 권한 매트릭스 |
| V17 | 테스트 데이터 (보험사 5 / 상품 20 / 설계사 50 / 계약 200 + 수수료 규정) |
| V18 | 메뉴 트리 구조 재정렬 (동적 사이드바용) |
| V19 | 업로드 템플릿 마스터 (upload_template / upload_column) |
| V20 | 데이터 사전 (data_domain / data_dictionary) |
| V21 | 프로필·이력서 도메인 (agent_profile) |
| V22 | 비즈니스 도메인 확장 (계약·정산 보조 컬럼) |
| V23 | 세무 처리 — agent.tax_type/business_no/vat_type, payment 세금 컬럼 |
| V24 | 공제차감 — agent_deduction + payment_deduction_detail |
| V25 | 수수료 명세서 — commission_statement |
| V26 | 규제한도 마스터 — regulatory_limit (1200%룰) |
| V27 | 분급 계획 — installment_ratio + installment_plan |
| V28 | 차등환수 룰 — chargeback_grade |
| V29 | 마감 마스터 — period_close |
| V30 | 정정 — settle_correction |
| V31 | 이의신청 — commission_dispute |
| V32 | 보류사유 코드 — HOLD_REASON 공통코드 그룹 |
| V33 | 시책·인센티브 — incentive_program + incentive_payment |
| V34 | 해촉정산 — termination_settlement |
| V35 | 세금계산서 — tax_invoice |
| V36 | 보험사 회신 인터페이스 — carrier_reconciliation_out |
| V37 | KPI Materialized View 4종 (월별/조직별/유지율/누계) |
| V38 | 리포트 메뉴 INSERT |
| V39 | KPI 메뉴 INSERT |
| V40 | 수수료종류 코드 + commission_master 통합 마스터 |
| V41 | 수금수수료 — collection_commission_rule + collection_commission_ledger |
| V42 | 갱신·부활수수료 — renewal/reinstatement commission rule+ledger |
| V43 | 유지보수수당 — persistency_bonus_rule + persistency_bonus |
| V44 | 오버라이드 원장 — override_ledger + override_summary |
| V45 | 위촉계약 — agent_contract |
| V46 | 자격관리 — agent_license |
| V47 | 보수교육 — agent_training + training_requirement |
| V48 | 계약변경 — contract_endorsement |
| V49 | 민원관리 — complaint |
| V50 | 결재 워크플로우 — approval_line + approval_line_step + approval_request + approval_history |
| V51 | 공지·알림 — notice + user_notification |
| V52 | 첨부파일 — attachment |
| V53 | 출금신청 — withdraw_request |
| V54 | P4 메뉴 INSERT (P4-A + P4-B 14개 메뉴) |
| V55 | P4 공통코드 추가 (approval_type, complaint_type, license_type 등) |
| V56 | agent 세무 컬럼 보강 (tax_type/business_no/vat_type — V23 체크섬 충돌 보정) |
| V57 | admin 계정 초기화 |
| V58 | 1200%룰 메뉴 권한 |
| V59 | 신규 메뉴 권한 |
| V60 | statement 메뉴 권한 |
| V61 | installment_plan 메뉴 권한 |
| V62 | 추가 메뉴 권한 |
| V63 | P5-W1: agent_annual_income 테이블 (설계사 연말 사업소득 집계) |
| V64 | P5-W1: contract_accounting_entry 테이블 (회계 분개 엔트리) |
| V65 | P5-W1: 테스트 데이터 + 메뉴 INSERT (ANNUAL_INCOME / ACCOUNTING_JOURNAL) |
| V66 | P5-W1: account_code 마스터 + 초기 4건 (8350/2530/1130/4110) |
| V67 | P5-W2: withholding_tax_report 테이블 (원천세 분기 신고) |
| V68 | P5-W2: vat_report 테이블 (부가세 분기 신고) |
| V69 | P5-W2: 테스트 데이터 + 메뉴 INSERT (원천세/부가세 신고) |
| V70 | rule 도메인 감사 컬럼 보강 (commission_rate/payout_rule/override_rule 등) |
| V71 | payment 세무 컬럼 보강 (income_tax_amount/local_tax_amount/vat_amount/net_amount) |
| V72 | P5-W1 EXECUTE 권한 보강 (ANNUAL_INCOME / ACCOUNTING_JOURNAL) |
| V73 | P5-W2 EXECUTE 권한 보강 (WITHHOLDING_TAX / VAT_REPORT) |

> 운영 DB (192.168.0.60) 현재 V73 까지 적용 완료.
> **ga-api 재시작 시** Flyway 가 신규 마이그레이션을 자동으로 순차 적용합니다.

---

## ✅ 진행 상황

- [x] 1단계 — 프로젝트 뼈대 + DB (V1~V17)
- [x] **ga-common** — 공통 프레임워크 일체
- [x] **ga-core** — 65+ 테이블 VO/Mapper/XML (P0~P4 전체)
- [x] **ga-api** — Auth + 50+ 도메인 컨트롤러 (128개 Java 파일)
- [x] **ga-batch** — MonthlySettlementJob 8 Step (실제 동작 로직 포함)
- [x] **Docker** — docker-compose + multi-stage Dockerfile + nginx
- [x] **ga-frontend** — 50+ 페이지 (대시보드/설계사/계약/원장/정산/지급/배치/KPI/수수료/시스템관리)
- [x] **DB 마이그레이션** — V1~V71 (71개 파일, ga-common/src/main/resources/db/migration)
- [x] **코드 품질** — Enum/DTO/MapStruct/readOnly 트랜잭션 일괄 정비
- [x] **P0 세무·공제·명세서** — TaxCalculator / DeductionService / ExcelStatementGenerator
- [x] **P1 1200%룰·분급·차등환수** — RegulatoryLimitChecker / InstallmentPlanGenerator / ChargebackCalculator
- [x] **P2 마감·정정·이의·보류·시책·해촉·세금계산서·외부회신** (8 도메인)
- [x] **P3 KPI 대시보드** — Materialized View 4종 + Service + 화면
- [x] **P4-A 수수료 종류 보강** — commission_master 통합 / 수금 / 갱신 / 부활 / 유지보수수당 / 오버라이드원장
- [x] **P4-B 운영 도메인** — 위촉계약 / 자격관리 / 보수교육 / 계약변경 / 민원 / 결재워크플로우 / 공지·알림 / 첨부파일 / 출금신청
- [x] **P5-W1 회계 진입점** — agent_annual_income / contract_accounting_entry / account_code (V63~V66, 통합검증 완료)
- [x] **P5-W2 원천세·부가세 분기신고** — withholding_tax_report / vat_report (V67~V69, 통합검증 완료 2026-05-17)
- [x] **운영 DB** — 192.168.0.60:55432/trading_ai/ga (V73 까지 적용 완료)
- [ ] **단위/통합 테스트** — 미작성 (SqlSessionFactory 환경 문제로 보류)
- [ ] **MappingEngine 정밀화** — 일부 변환 규칙은 단순화된 형태
- [ ] **P5-W3 결산 / 이상치 / 연말 지급명세서** — 미착수
- [ ] **P6 외부 연동** — 펌뱅킹 실연동 / SMS·카카오 / 모바일 셀프 조회

---

## 🔮 향후 확장

- **프론트 페이지 추가**: `menu` 테이블 등록 → React 페이지 구현 → 동적 라우팅 적용
- **신규 보험사**: `company_profile` + `company_field_mapping` 등록 + 필요 시 `DataReceiver` 구현
- **신규 정산 규정**: `commission_rate`/`payout_rule`/`override_rule`/`chargeback_rule` 에 `effective_from` 만 다른 버전으로 추가 (versioning)
- **이체파일 포맷**: 은행별 EBCDIC/CSV 출력 어댑터 추가

---

## 📡 외부 시스템 연결 정보 (요약)

| 항목 | 값 |
|------|-----|
| 운영 DB 호스트 | `192.168.0.60` |
| 운영 DB 포트 | `55432` |
| 운영 DB 데이터베이스 | `trading_ai` |
| 운영 DB 스키마 | `ga` |
| 운영 DB 사용자 | `kyu` |
| Git 원격 | https://gl.kyleyang.co.kr/kyu/ga-commission-system |
| 초기 관리자 | `admin / admin1234!` |