GA Pro
11 KiB
11 KiB
Handoff Note — 2026-05-14 (Round 2 완료)
다음 세션에서 이어가기 위한 핸드오프 문서. Agent Teams 기반 자동 체인으로 진행 중인 작업의 현재 상태와 잔여 작업, 재개 절차를 기록한다.
1. 핸드오프 시점 상태
- 마지막 커밋: P1-3-c (ChargebackCalculator + ChargebackGradeService + Controller)
- 빌드 상태:
./gradlew :ga-common:compileJava :ga-core:compileJava :ga-api:compileJava모두 BUILD SUCCESSFUL - 이번 세션 누적 커밋 수: 26개 (Agent Teams 설정 1 + 코드 품질 7 + 도메인 P0 9 + 도메인 P1 11)
- 변경 사항 없음 (working tree clean)
2. 완료된 작업
2-1. 코드 품질 자동 체인 (7 커밋)
초기 ga-api 5명 리뷰 결과를 바탕으로 P0 이슈 일괄 해결.
| 단계 | 커밋 | 내용 |
|---|---|---|
| 1 | 5e58a54 |
OrganizationSaveReq + 상태 Enum 4종 (Agent/Contract/Settle/Approve) |
| 2 | a8f0b6e |
Controller→Service 분리 5개 + 매직 스트링 Enum 교체 + @DataChangeLog 17곳 |
| 3a | 693275e |
UserStatus + ExceptionLedgerStatus Enum |
| 3b | af3c6b9 |
Map→SaveReq DTO 4종 + 입력 검증 + 잔여 Enum 적용 |
| 4 | 498d0d4 |
LookupCache 동시성 + UploadService/TransferFile 트랜잭션 분해 + readOnly 일괄 |
| 5a | 4b211ec |
AgentOrgHistoryResp + MapStruct mapper 3종 + AgentMapper.xml 조인 |
| 5b | b16e678 |
MapStruct 적용 + Resp 적용 + PaymentService/UploadTemplateService 신설 + PageHelper 통일 |
2-2. 도메인 P0 — 세무·공제·명세서 (9 커밋)
| 도메인 | a (DB) | b (core) | c (api) |
|---|---|---|---|
| P0-1 세무 | ad5d62e V23 |
92f3217 |
f8c7d84 TaxCalculator |
| P0-2 공제 | 0e73eb6 V24 |
a3ba7fa |
b8f33f1 DeductionService |
| P0-3 명세서 | 930335c V25 |
4f5a2f0 |
f5efcaa ExcelStatementGenerator |
핵심 산출물:
- 표준 세율 system_config 외부화 (3.3%/8.8%/10%/10%)
agent에 tax_type/business_no/vat_type 컬럼payment에 income_tax_amount/local_tax_amount/vat_amount/net_amountagent_deduction(월별 차감 마스터) +payment_deduction_detail(이체 명세)commission_statement(명세서 발급 마스터, agent+settle_month+statement_type UNIQUE)- TaxCalculator pure 도메인 + ExcelStatementGenerator (PDF는 향후)
2-3. 도메인 P1 — 1200%룰·분급·차등환수 (11 커밋)
| 도메인 | a (DB) | b (core) | c (api) |
|---|---|---|---|
| P1-1 1200%룰 | 6a6ba9f V26 |
1109253 |
bba4a33 RegulatoryLimitChecker |
| P1-2 분급 | 434e778 V27 |
5029bc5 |
(P1-2-c 커밋) InstallmentPlanGenerator |
| P1-3 차등환수 | cc5d0e5 V28 |
44dbbf3 |
(P1-3-c 커밋) ChargebackCalculator |
P1 보강 (병렬 트랙):
1aa31deRecruitLedger/MaintainLedger sumByContract 메서드 추가f6142a1RegulatoryLimitChecker TODO 해소 (실제 누적값 사용)
핵심 산출물:
regulatory_limit마스터 (1200%/35%/7년 한도, effective_from/to 이력 추적)installment_ratio+installment_plan(분급 7년 비율 35/25/15/10/7/5/3)chargeback_grade(5단계: 112개월 100% → 85개월0%)- RegulatoryLimitChecker / InstallmentPlanGenerator / ChargebackCalculator pure 도메인
2-4. 병렬화 적용 (P1 후반부)
초반 직렬 a→b→c 패턴에서 후반에 도메인 간 sub-step 병렬로 전환.
- P1-2-c(api) + P1-3-a(dba) + P1 보강(core) 3명 동시 활성화
- P1-3-b(core) + P1-1-c TODO 교체(api) 2명 동시
- 모듈이 다른 사람끼리 묶어 머지 충돌 없음
3. Round 2 완료 사항 (2026-05-14)
3-1. P2 — 8 도메인 (V29~V36, ~50 VO·Mapper, 18 Service+Controller)
| # | 도메인 | 마이그레이션 | 상태 |
|---|---|---|---|
| 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 | 완료 |
화면: ga-frontend Wave 4 에서 P4-B 화면과 함께 작성됨.
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 — 회계/분석 보강 (다음 라운드)
| 항목 | 설명 |
|---|---|
| 회계 전표 자동 분개 | 수수료 지급액 → 분개 엔트리 자동 생성 |
| 원천세 신고 자료 | 분기별 사업소득세 집계 + 국세청 포맷 |
| 부가세 신고 자료 | tax_invoice 기반 매출/매입 집계 |
| 결산 | period_close 와 별개의 월/분기/연 회계 마감 |
| 이상치·예측 KPI | 13M/25M 유지율 이상 탐지 + 차월 예측 |
| 연말 지급명세서 | 설계사 연 사업소득 세무 자료 PDF |
P6 — 외부 연동 (P5 이후)
| 항목 | 설명 |
|---|---|
| 펌뱅킹 실연동 | withdraw_request 결재 완료 → 은행 API 직접 호출 |
| SMS/카카오 발송 | user_notification 채널 실연동 |
| 모바일 셀프 조회 | 설계사 전용 모바일 앱 or PWA |
운영 DB 마이그레이션 (중요 공지)
운영 DB 192.168.0.60:55432/trading_ai/ga 에는 현재 V17(또는 V22) 까지만 적용되어 있습니다.
ga-api 를 재시작하면 Flyway 가 V18V55 를 자동 순차 적용합니다.
재시작 전까지 P2P4 신규 도메인 API 는 테이블이 없어 동작하지 않습니다.
단위/통합 테스트는 SqlSessionFactory 환경 설정 문제로 아직 미작성 상태입니다.
5. 재개 절차 (다음 세션 — P5 라운드)
- Claude Code 시작 시 cwd 확인:
C:\Users\kyu\Desktop\ga_pro(현재 세션과 동일) - Agent Teams 활성화 확인:
.claude/settings.json이미 커밋되어 있음 (418ff7c) - 팀 재생성: 새 세션은 팀이 없음. 다음 명령 흐름:
- PL 역할로
TeamCreate(team_name="ga-pro-team", agent_type="pl", description="...")호출 - 7명 팀원 spawn (common/core/api/batch/frontend/dba/infra) — 첫 세션과 동일
- PL 역할로
- HANDOFF.md 읽기: 본 문서 + 최근 git log로 컨텍스트 확보
- 권장 시작 지점: P5 Wave 1 — dba-architect에게 V56~V61 (회계 전표 / 원천세 / 부가세 / 결산 / 이상치 / 연말 지급명세서)
- ga-api 재시작 필요: 운영 DB 에 V18~V55 적용하려면 ga-api 재시작 후 Flyway 자동 실행 확인
- 사용자 결정 필요 항목:
- P5 시작 전 ga-api 재시작해서 V18~V55 운영 DB 반영 여부
- P2-1 마감 도메인의 마감 후 수정 차단 AOP 구현 방식 (전역 AOP vs Service-level 가드)
6. PL 가이드 (다음 세션 유의사항)
- 시간차 중복 메시지: 팀원이 SendMessage로 같은 보고를 2~3번 보내는 경우 있음. 짧게 acknowledge만.
- idle 알림: 팀원이 작업 끝낼 때마다 idle 알림 보냄. 정상. 액션 필요 없음.
- 책임 경계: dba=Flyway/SQL, core=VO/Mapper/Enum, api=Service/Controller. api-developer가 가끔 ga-core Mapper에 메서드 추가하는데 작은 변경이면 통과 가능, 큰 변경은 core-architect에 위임.
- TODO 잔존: api-developer가 부족한 ga-core 메서드 발견 시 TODO로 남기고 보고 → PL이 후속 보강 디스패치. 같은 단계에서 멈추지 말고 흐름 유지.
- 자동 정책:
- 각 단계 완료 후 자동 커밋 (push 안 함)
- 빌드/테스트 실패 시 담당 팀원에 재지시
- 컴파일은 PL이 직접 검증, 테스트는 환경 문제(SqlSessionFactory)로 통과 안 되는 게 알려진 상태
7. 표준 가정 (도메인 작업 진행 시 채택한 값)
도메인 룰은 한국 보험업감독규정 표준 가정을 외부화 가능한 구조로 등록. 실제 회사 정책과 다르면 system_config / regulatory_limit / installment_ratio / chargeback_grade의 데이터만 수정하면 됨.
| 항목 | 표준값 | 근거 |
|---|---|---|
| 사업소득 원천징수 | 3.3% | 한국 표준 |
| 기타소득 원천징수 | 8.8% | 한국 표준 |
| 지방소득세 | 원천세의 10% | 한국 표준 |
| 부가세 | 10% | 한국 표준 |
| 1200% 룰 총 한도 | 1200% | 보험업감독규정 제5-15조의5 |
| 1차년 한도 | 35% | 2024년 기준 |
| 분급 연한 | 7년 | 2024년 기준 |
| 분급 비율 | 35/25/15/10/7/5/3 (합 100%) | 가정값 |
| 차등 환수 | 1 |
가정값 |
가정값과 실제가 다르면 운영 데이터 수정으로 해결 가능. 코드 변경 불필요.