동기화

HANDOFF.md

@@ -1,4 +1,4 @@
-# Handoff Note — 2026-05-12
+# Handoff Note — 2026-05-14 (Round 2 완료)
 
 다음 세션에서 이어가기 위한 핸드오프 문서. Agent Teams 기반 자동 체인으로 진행 중인 작업의 현재 상태와 잔여 작업, 재개 절차를 기록한다.
 
@@ -64,48 +64,87 @@
 - P1-3-b(core) + P1-1-c TODO 교체(api) 2명 동시
 - 모듈이 다른 사람끼리 묶어 머지 충돌 없음
 
-## 3. 잔여 작업
+## 3. Round 2 완료 사항 (2026-05-14)
 
-### 3-1. P1 정산 통합 (보류 권장)
-- ga-batch의 8 Step 정산 잡에 TaxCalculator/DeductionService/RegulatoryLimitChecker/InstallmentService/ChargebackCalculator 통합
-- batch-engineer 작업
-- 운영 비즈니스 룰 의존이 커 **인프라만 완성하고 통합은 사용자 결정 후** 진행 권장
-- 보류 가능 — 현 시점에 인프라/CRUD/API는 모두 동작
-
-### 3-2. 도메인 P2 — 8개 항목 (Wave 방식)
-| # | 도메인 | 마이그레이션 | 핵심 |
+### 3-1. P2 — 8 도메인 (V29~V36, ~50 VO·Mapper, 18 Service+Controller)
+| # | 도메인 | 마이그레이션 | 상태 |
 |---|---|---|---|
-| P2-1 | 마감 (Period Close) | V29 | period_close 테이블 + 마감 후 수정 차단 AOP |
-| P2-2 | 정정 (Correction) | V30 | settle_correction + 원본 참조 + 정정 사유 |
-| P2-3 | 이의 신청 (Dispute) | V31 | commission_dispute + OPEN/IN_REVIEW/APPROVED/REJECTED |
-| P2-4 | 보류 사유 (Hold Reasons) | V32 | settle_master.hold_reason_code + HOLD_REASON 코드그룹 |
-| P2-5 | 시책·인센티브 | V33 | incentive_program + incentive_payment |
-| P2-6 | 해촉 정산 (Termination) | V34 | termination_settlement (agent_org_history 연계) |
-| P2-7 | 세금계산서 (Tax Invoice) | V35 | tax_invoice 발행 이력 (SUPPLY/PURCHASE) |
-| P2-8 | 외부 회신 | V36 | carrier_reconciliation_out (보험사 회신 인터페이스) |
+| P2-1 | 마감 (Period Close) | V29 | 완료 |
+| P2-2 | 정정 (Correction) | V30 | 완료 |
+| P2-3 | 이의신청 (Dispute) | V31 | 완료 |
+| P2-4 | 보류사유 (Hold Reasons) | V32 | 완료 |
+| P2-5 | 시책·인센티브 | V33 | 완료 |
+| P2-6 | 해촉정산 (Termination) | V34 | 완료 |
+| P2-7 | 세금계산서 (Tax Invoice) | V35 | 완료 |
+| P2-8 | 외부회신 | V36 | 완료 |
 
-**Wave 디스패치 계획**:
-- Wave 1 (dba): V29~V36 8개 마이그레이션 한 번에
-- Wave 2 (core): 8개 도메인 VO/Mapper 한 번에
-- Wave 3 (api): 8개 도메인 Service/Controller 한 번에
-- 디스패치 24 → 3으로 축소
+화면: ga-frontend Wave 4 에서 P4-B 화면과 함께 작성됨.
 
-### 3-3. 도메인 P3 — KPI 대시보드
-| 작업 | 담당 |
+### 3-2. P3 — KPI 대시보드 (V37~V39)
+- dba: mv_monthly_summary / mv_org_summary / mv_retention_rate / mv_cumulative (V37)
+- dba: 리포트 메뉴 + KPI 메뉴 INSERT (V38, V39)
+- core: KpiMapper.java + XML
+- api: KpiService + KpiController (`/api/kpi/*`)
+- frontend: KpiMonthlySummary / KpiOrgSummary / KpiRetention / KpiCumulative (4개 화면)
+
+### 3-3. P4-A — 수수료 종류 보강 (V40~V44, 5 도메인)
+| # | 도메인 | 마이그레이션 | 상태 |
+|---|---|---|---|
+| P4-A-1 | commission_type 코드 + commission_master 통합 | V40 | 완료 |
+| P4-A-2 | 수금수수료 (collection_commission_rule/ledger) | V41 | 완료 |
+| P4-A-3 | 갱신·부활수수료 (renewal/reinstatement) | V42 | 완료 |
+| P4-A-4 | 유지보수수당 (persistency_bonus_rule/bonus) | V43 | 완료 |
+| P4-A-5 | 오버라이드 원장 (override_ledger/summary) | V44 | 완료 |
+
+### 3-4. P4-B — 운영 필수 9 도메인 (V45~V53)
+| # | 도메인 | 마이그레이션 | 상태 |
+|---|---|---|---|
+| P4-B-1 | 위촉계약 (agent_contract) | V45 | 완료 |
+| P4-B-2 | 자격관리 (agent_license) | V46 | 완료 |
+| P4-B-3 | 보수교육 (agent_training) | V47 | 완료 |
+| P4-B-4 | 계약변경 (contract_endorsement) | V48 | 완료 |
+| P4-B-5 | 민원관리 (complaint) | V49 | 완료 |
+| P4-B-6 | 결재워크플로우 (approval_line/request) | V50 | 완료 |
+| P4-B-7 | 공지·알림 (notice/user_notification) | V51 | 완료 |
+| P4-B-8 | 첨부파일 (attachment) | V52 | 완료 |
+| P4-B-9 | 출금신청 (withdraw_request) | V53 | 완료 |
+
+### 3-5. V54~V55 + 프론트
+- V54: P4 메뉴 INSERT (P4-A + P4-B 14개 메뉴)
+- V55: P4 공통코드 추가 (approval_type, complaint_type, license_type, withdraw_status 등)
+- 프론트: ErrorBoundary 전역 적용 + 토스 디자인 시스템 토큰 (`RADIUS`, `GRAY`, `SHADOW`) 일관 적용
+- 프론트 화면 추가: AgentContracts / AgentLicenses / AgentTrainings / Complaints / ContractEndorsements / CollectionCommission / CommissionMaster / OverrideLedger / PersistencyBonus / ReinstatementCommission / RenewalCommission / WithdrawRequest / Approvals / Notices (14개)
+
+### 3-6. P1 정산 통합 (batch-engineer 완료)
+- ga-batch 8 Step에 TaxCalculator / DeductionService / RegulatoryLimitChecker / InstallmentPlanGenerator / ChargebackCalculator 통합 완료
+
+## 4. 잔여 작업 (P5/P6)
+
+### P5 — 회계/분석 보강 (다음 라운드)
+| 항목 | 설명 |
 |---|---|
-| V37 Materialized View 4종 (월별/조직별/유지율/누계) | dba-architect |
-| KPI VO/Mapper | core-architect |
-| KpiService + KpiController | api-developer |
-| KPI 대시보드 화면 (AG Grid 합계행, 차트) | frontend-developer |
+| 회계 전표 자동 분개 | 수수료 지급액 → 분개 엔트리 자동 생성 |
+| 원천세 신고 자료 | 분기별 사업소득세 집계 + 국세청 포맷 |
+| 부가세 신고 자료 | tax_invoice 기반 매출/매입 집계 |
+| 결산 | period_close 와 별개의 월/분기/연 회계 마감 |
+| 이상치·예측 KPI | 13M/25M 유지율 이상 탐지 + 차월 예측 |
+| 연말 지급명세서 | 설계사 연 사업소득 세무 자료 PDF |
 
-### 3-4. 마무리 통합
-| 작업 | 담당 |
+### P6 — 외부 연동 (P5 이후)
+| 항목 | 설명 |
 |---|---|
-| ga-batch 8 Step에 도메인 로직 통합 (TaxCalculator/Deduction/Regulatory/Installment/Chargeback) | batch-engineer |
-| 통합 테스트 | infra-reviewer |
-| README/DEVELOPER_GUIDE 업데이트 | infra-reviewer |
+| 펌뱅킹 실연동 | withdraw_request 결재 완료 → 은행 API 직접 호출 |
+| SMS/카카오 발송 | user_notification 채널 실연동 |
+| 모바일 셀프 조회 | 설계사 전용 모바일 앱 or PWA |
 
-## 4. 재개 절차 (다음 세션)
+### 운영 DB 마이그레이션 (중요 공지)
+운영 DB `192.168.0.60:55432/trading_ai/ga` 에는 현재 **V17(또는 V22) 까지만** 적용되어 있습니다.
+`ga-api 를 재시작`하면 Flyway 가 V18~V55 를 자동 순차 적용합니다.
+재시작 전까지 P2~P4 신규 도메인 API 는 테이블이 없어 동작하지 않습니다.
+
+단위/통합 테스트는 SqlSessionFactory 환경 설정 문제로 아직 미작성 상태입니다.
+
+## 5. 재개 절차 (다음 세션 — P5 라운드)
 
 1. **Claude Code 시작 시 cwd 확인**: `C:\Users\kyu\Desktop\ga_pro` (현재 세션과 동일)
 2. **Agent Teams 활성화 확인**: `.claude/settings.json` 이미 커밋되어 있음 (`418ff7c`)
@@ -113,12 +152,13 @@
    - PL 역할로 `TeamCreate(team_name="ga-pro-team", agent_type="pl", description="...")` 호출
    - 7명 팀원 spawn (common/core/api/batch/frontend/dba/infra) — 첫 세션과 동일
 4. **HANDOFF.md 읽기**: 본 문서 + 최근 git log로 컨텍스트 확보
-5. **권장 시작 지점**: P2 Wave 1 디스패치 (dba-architect에게 V29~V36 8개 마이그레이션)
-6. **사용자 결정 필요 항목**:
-   - P1 정산 통합 진행 여부 (Wave 작업 전 또는 P3 후)
+5. **권장 시작 지점**: P5 Wave 1 — dba-architect에게 V56~V61 (회계 전표 / 원천세 / 부가세 / 결산 / 이상치 / 연말 지급명세서)
+6. **ga-api 재시작 필요**: 운영 DB 에 V18~V55 적용하려면 ga-api 재시작 후 Flyway 자동 실행 확인
+7. **사용자 결정 필요 항목**:
+   - P5 시작 전 ga-api 재시작해서 V18~V55 운영 DB 반영 여부
    - P2-1 마감 도메인의 마감 후 수정 차단 AOP 구현 방식 (전역 AOP vs Service-level 가드)
 
-## 5. PL 가이드 (다음 세션 유의사항)
+## 6. PL 가이드 (다음 세션 유의사항)
 
 - **시간차 중복 메시지**: 팀원이 SendMessage로 같은 보고를 2~3번 보내는 경우 있음. 짧게 acknowledge만.
 - **idle 알림**: 팀원이 작업 끝낼 때마다 idle 알림 보냄. 정상. 액션 필요 없음.
@@ -129,7 +169,7 @@
   - 빌드/테스트 실패 시 담당 팀원에 재지시
   - 컴파일은 PL이 직접 검증, 테스트는 환경 문제(SqlSessionFactory)로 통과 안 되는 게 알려진 상태
 
-## 6. 표준 가정 (도메인 작업 진행 시 채택한 값)
+## 7. 표준 가정 (도메인 작업 진행 시 채택한 값)
 
 도메인 룰은 한국 보험업감독규정 표준 가정을 외부화 가능한 구조로 등록. 실제 회사 정책과 다르면 system_config / regulatory_limit / installment_ratio / chargeback_grade의 데이터만 수정하면 됨.