docs: 세션 마무리 핸드오프 노트 — 잔여 P2/P3 작업 정리
2026-05-12 세션에서 코드 품질 5단계 + 도메인 P0/P1 완료(26 커밋). 다음 세션에서 P2 Wave 방식 진입을 위한 핸드오프 문서. 내용: - 핸드오프 시점 상태 (마지막 커밋, 빌드 상태) - 완료 작업 요약 (코드 품질 / P0 / P1) - 잔여 작업 (P1 정산 통합 / P2 8항목 / P3 KPI / 마무리 통합) - 재개 절차 (팀 재생성, 권장 시작점) - PL 가이드 (시간차 중복 메시지 처리, 책임 경계) - 채택한 표준 가정값 (세율/1200%/분급/차등환수)
This commit is contained in:
GA Pro
+148
@@ -0,0 +1,148 @@
|
||||
# Handoff Note — 2026-05-12
|
||||
|
||||
다음 세션에서 이어가기 위한 핸드오프 문서. 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_amount
|
||||
- `agent_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 보강 (병렬 트랙)**:
|
||||
- `1aa31de` RecruitLedger/MaintainLedger sumByContract 메서드 추가
|
||||
- `f6142a1` RegulatoryLimitChecker TODO 해소 (실제 누적값 사용)
|
||||
|
||||
핵심 산출물:
|
||||
- `regulatory_limit` 마스터 (1200%/35%/7년 한도, effective_from/to 이력 추적)
|
||||
- `installment_ratio` + `installment_plan` (분급 7년 비율 35/25/15/10/7/5/3)
|
||||
- `chargeback_grade` (5단계: 1~12개월 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. 잔여 작업
|
||||
|
||||
### 3-1. P1 정산 통합 (보류 권장)
|
||||
- ga-batch의 8 Step 정산 잡에 TaxCalculator/DeductionService/RegulatoryLimitChecker/InstallmentService/ChargebackCalculator 통합
|
||||
- batch-engineer 작업
|
||||
- 운영 비즈니스 룰 의존이 커 **인프라만 완성하고 통합은 사용자 결정 후** 진행 권장
|
||||
- 보류 가능 — 현 시점에 인프라/CRUD/API는 모두 동작
|
||||
|
||||
### 3-2. 도메인 P2 — 8개 항목 (Wave 방식)
|
||||
| # | 도메인 | 마이그레이션 | 핵심 |
|
||||
|---|---|---|---|
|
||||
| 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 (보험사 회신 인터페이스) |
|
||||
|
||||
**Wave 디스패치 계획**:
|
||||
- Wave 1 (dba): V29~V36 8개 마이그레이션 한 번에
|
||||
- Wave 2 (core): 8개 도메인 VO/Mapper 한 번에
|
||||
- Wave 3 (api): 8개 도메인 Service/Controller 한 번에
|
||||
- 디스패치 24 → 3으로 축소
|
||||
|
||||
### 3-3. 도메인 P3 — KPI 대시보드
|
||||
| 작업 | 담당 |
|
||||
|---|---|
|
||||
| V37 Materialized View 4종 (월별/조직별/유지율/누계) | dba-architect |
|
||||
| KPI VO/Mapper | core-architect |
|
||||
| KpiService + KpiController | api-developer |
|
||||
| KPI 대시보드 화면 (AG Grid 합계행, 차트) | frontend-developer |
|
||||
|
||||
### 3-4. 마무리 통합
|
||||
| 작업 | 담당 |
|
||||
|---|---|
|
||||
| ga-batch 8 Step에 도메인 로직 통합 (TaxCalculator/Deduction/Regulatory/Installment/Chargeback) | batch-engineer |
|
||||
| 통합 테스트 | infra-reviewer |
|
||||
| README/DEVELOPER_GUIDE 업데이트 | infra-reviewer |
|
||||
|
||||
## 4. 재개 절차 (다음 세션)
|
||||
|
||||
1. **Claude Code 시작 시 cwd 확인**: `C:\Users\kyu\Desktop\ga_pro` (현재 세션과 동일)
|
||||
2. **Agent Teams 활성화 확인**: `.claude/settings.json` 이미 커밋되어 있음 (`418ff7c`)
|
||||
3. **팀 재생성**: 새 세션은 팀이 없음. 다음 명령 흐름:
|
||||
- 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 후)
|
||||
- P2-1 마감 도메인의 마감 후 수정 차단 AOP 구현 방식 (전역 AOP vs Service-level 가드)
|
||||
|
||||
## 5. 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)로 통과 안 되는 게 알려진 상태
|
||||
|
||||
## 6. 표준 가정 (도메인 작업 진행 시 채택한 값)
|
||||
|
||||
도메인 룰은 한국 보험업감독규정 표준 가정을 외부화 가능한 구조로 등록. 실제 회사 정책과 다르면 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~12: 100%, 13~24: 50%, 25~36: 25%, 37~84: 10%, 85~: 0% | 가정값 |
|
||||
|
||||
가정값과 실제가 다르면 운영 데이터 수정으로 해결 가능. 코드 변경 불필요.
|
||||
Reference in New Issue
Block a user