동기화

README.md

@@ -40,9 +40,13 @@ ga-commission-system/
 
 ### 시나리오 A — 운영 DB(trading_ai/ga) 에 연결해서 실행 ⭐ 권장
 
-이미 V1~V17 마이그레이션 + 테스트 데이터(보험사 5 / 상품 20 / 설계사 50 / 계약 200)가
+V1~V17 마이그레이션 + 테스트 데이터(보험사 5 / 상품 20 / 설계사 50 / 계약 200)가
 `192.168.0.60:55432/trading_ai/ga` 스키마에 적용되어 있습니다.
 
+> **주의**: 운영 DB 에는 현재 V1~V17(또는 V22 까지)만 적용되어 있습니다.
+> V18~V55 는 ga-api 를 재시작하면 Flyway 가 자동으로 순서대로 적용합니다.
+> 재시작 전까지 P2~P4 신규 도메인 API 는 테이블이 없어 동작하지 않습니다.
+
 #### 1) Backend (ga-api) 실행
 
 ```bash
@@ -119,7 +123,7 @@ PW  : admin1234!
 # 1) PostgreSQL + Redis 기동 (Docker)
 docker compose up -d postgres redis
 
-# 2) ga-api 실행 (Flyway 가 자동으로 V1~V17 마이그레이션)
+# 2) ga-api 실행 (Flyway 가 자동으로 V1~V55 마이그레이션)
 ./gradlew :ga-api:bootRun
 # 기본 프로파일은 application.yml — localhost:5432/ga 에 연결
 
@@ -219,21 +223,56 @@ UPDATE ga.users SET password = '$2b$10$...' WHERE login_id = 'admin';
 
 ## 📋 주요 기능
 
-### 백엔드
-- **인증/권한**: JWT (HS256), 메뉴×권한 RBAC, BCrypt 비밀번호
+### 공통 프레임워크 (ga-common)
+- **인증/권한**: JWT (HS256 액세스 2h/리프레시 7d), 메뉴×6권한 RBAC, BCrypt 비밀번호
 - **공통코드**: Redis 캐시, 시스템코드 잠금, REST CRUD
 - **메뉴**: 트리 구조, 사용자별 동적 메뉴 + 권한 매트릭스
 - **엑셀**: SXSSF+Cursor 다운로드(100만건), SAX+배치 업로드(70만건)
-- **로그**: 로그인/API/데이터변경 자동 기록 (비동기)
-- **암호화**: AES-256 CBC (`resident_no`, `account_no` 자동)
+- **로그**: 로그인/API/데이터변경 자동 기록 (비동기 `@DataChangeLog` AOP)
+- **암호화**: AES-256 CBC (`resident_no`, `account_no` TypeHandler 자동 적용)
+- **업로드 템플릿**: 동적 컬럼 매핑 + 변환 규칙 관리
 
-### 도메인
-- **조직**: 트리 구조, CTE 재귀, 인사 이력
-- **계약**: 보험사/상품/계약 관리
-- **수수료 규정**: 보험사율, 지급율, 오버라이드, 환수, 예외코드
-- **원장**: 모집/유지/예외 (PageHelper + AG Grid)
-- **정산**: 8 Step 배치 (수신→변환→대사→모집→유지→환수/예외→오버라이드→집계)
-- **지급**: 이체파일 생성, 상태 추적
+### 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 — 결재 + 펌뱅킹 송신 + 결과 반영
 
 ### 정산 배치 8 Step
 1. **receiveData** — 보험사별 DataReceiver → raw_commission_data 적재
@@ -305,6 +344,47 @@ public class FooController {
 | 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 등) |
+
+> 운영 DB (192.168.0.60) 에는 현재 V17(또는 V22) 까지만 적용되어 있습니다.
+> **ga-api 재시작 시** Flyway 가 V18~V55 를 자동으로 순차 적용합니다.
 
 ---
 
@@ -312,14 +392,24 @@ public class FooController {
 
 - [x] 1단계 — 프로젝트 뼈대 + DB (V1~V17)
 - [x] **ga-common** — 공통 프레임워크 일체
-- [x] **ga-core** — 22개 테이블 VO/Mapper/XML
-- [x] **ga-api** — Auth + 14개 도메인 컨트롤러
+- [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** — 13개 페이지 (대시보드/설계사/계약/원장/정산/지급/배치/시스템관리)
-- [x] **운영 DB 적용** — 192.168.0.60:55432/trading_ai/ga (V1~V17 + 테스트 데이터)
-- [ ] **단위/통합 테스트** — 미작성
+- [x] **ga-frontend** — 50+ 페이지 (대시보드/설계사/계약/원장/정산/지급/배치/KPI/수수료/시스템관리)
+- [x] **DB 마이그레이션** — V1~V55 (55개 파일, 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] **운영 DB** — 192.168.0.60:55432/trading_ai/ga (V17까지 적용, V18~V55는 재시작 시 자동 적용)
+- [ ] **단위/통합 테스트** — 미작성 (SqlSessionFactory 환경 문제로 보류)
 - [ ] **MappingEngine 정밀화** — 일부 변환 규칙은 단순화된 형태
+- [ ] **P5 회계/분석** — 전표 분개 / 원천세·부가세 신고 / 결산 / 이상치·예측 / 연말 지급명세서
+- [ ] **P6 외부 연동** — 펌뱅킹 실연동 / SMS·카카오 / 모바일 셀프 조회
 
 ---