docs: HANDOFF §3-16 계약 승계(V86) 추가 + 재개 절차 갱신(v86/ga-batch 트리거)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

HANDOFF.md

@@ -1,4 +1,4 @@
-# Handoff Note — 2026-05-14 (Round 2 완료)
+# Handoff Note — 최신 갱신 2026-05-29 (계약 승계 V86 §3-16) / Round 2 기준 2026-05-14
 
 다음 세션에서 이어가기 위한 핸드오프 문서. Agent Teams 기반 자동 체인으로 진행 중인 작업의 현재 상태와 잔여 작업, 재개 절차를 기록한다.
 
@@ -414,6 +414,36 @@ ga-api 8082 / ga-frontend 3000 / ga-mobile-pwa 3001 모두 라이브.
 | 카카오 알림톡 본체 | 비즈채널·템플릿 승인 |
 | 푸시 알림 (FCM 등) | 외부 채널 결정 |
 
+## 3-16. 계약 승계 (contract_succession, V86 — 완료, 2026-05-29 라이브 적용)
+
+설계사 해촉/이관 시 보험계약의 **유지수수료(maintain) 귀속 설계사를 승계월 기준 후임으로 전환**.
+모집수수료(1회차)는 원 모집설계사 귀속 유지 — 한국 고아계약 승계 표준. 후임 설계사는 본인 등급의 payout 비율로 수령.
+
+| 레이어 | 산출물 |
+|---|---|
+| DB (V86) | `contract_succession`(contract_id/from_agent_id/to_agent_id/succession_date/reason/status) + 인덱스 3 + 메뉴 `CONTRACT_SUCCESSION`(GRP_PRD, path `/contracts/successions`) + 권한 READ/CREATE/UPDATE/DELETE + 역할부여(SUPER_ADMIN·ADMIN 전체 / MANAGER READ) + 공통코드 SUCCESSION_REASON·SUCCESSION_STATUS + 테스트데이터 1건 |
+| core | `ContractSuccession` VO/Resp/SaveReq/SearchParam + Mapper(.java/.xml). 핵심 `selectEffectiveSuccessions(settleMonth)` = 계약별 최근 ACTIVE 승계 1건(DISTINCT ON, `TO_CHAR(succession_date,'YYYYMM') <= settleMonth`) |
+| api | `ContractSuccessionService/Controller` (`/api/contract-successions`) CRUD + `/{id}/cancel`. from==to 가드(E411) |
+| batch | `CalcMaintainStep`: effective 승계 Map 사전로드(N+1 회피) → `effectiveAgentId = getOrDefault(contractId, c.agentId)` → `CommissionCalculator.calcMaintainLedger(c, month, year, effectiveAgentId)` 오버로드(후임 등급 payout + `led.setAgentId(effectiveAgentId)`). **AggregateStep 무변경** — ledger의 agent_id로 집계하므로 후임 귀속 자동 전파 |
+| frontend | `api/succession.ts` + `pages/contracts/ContractSuccessions.tsx` + App.tsx 라우트 `contracts/successions` |
+
+핵심 산출물 커밋: `bd5ff4e`.
+
+**부수 버그 수정 (커밋 `4dbc688`, 승계 무관)**:
+- `AgentDeductionMapper.updateStatusBatch` 가 인터페이스 선언만 있고 XML 구문 누락 → AggregateStep(Step8) 이 PENDING 차감 일괄 APPLIED 전이 시 `Invalid bound statement (not found)` 로 aggregate 전체 FAILED 되던 잠복 버그(P0-2부터 존재). `updateStatus` 동일 패턴 + foreach IN 으로 보강. e2e 도중 발견.
+
+통합 검증 (2026-05-29):
+- 5모듈 compileJava BUILD SUCCESSFUL + ga-frontend tsc 0 오류
+- Flyway V86 자동 적용 → 운영 DB schema **v86**
+- API CRUD + cancel + from==to 가드(E411) 라이브 PASS
+- **배치 풀잡 e2e**: ga-batch 8081 기동, `POST /internal/jobs/monthly-settlement`(JWT 필요 — ga-api admin 토큰 재사용). 테스트 승계(계약59 agent39→agent2, 2026-01-01) 등록 후 202605 정산 실행:
+  - maintain_ledger 계약59 = **agent2(후임)** / 5520(후임 등급 재계산, 원래 agent39/19320)
+  - settle_master agent2 maintain = 142700 = ledger 합 / agent39 = 191100 = ledger 합
+  - 무결성 **ledger 총합 == settle_master maintain 총합 = 17,556,135 정확 일치**
+  - (202604는 전 행 status=CONFIRMED → upsert 불변 가드 `WHERE status NOT IN ('CONFIRMED','PAID')` 로 settle_master 미갱신 = 정상 동작)
+- e2e 테스트 DB 부산물(승계 레코드 / 202605 정산데이터 / 회계분개 / 차감 전이 / batch_job_log)은 단일 트랜잭션으로 전부 롤백 완료, pre-e2e 상태 복원 검증.
+- **주의**: AccountingEntryGenerateStep(Step8b)은 멱등이 아님 — 동일 월 재실행 시 분개 중복 INSERT(주석상 existsByPaymentId 중복방어 언급되나 코드 미구현). 동일 월 재정산 전 기존 분개 정리 필요.
+
 ## 3-9. P5-W3 메뉴/권한 전수 정합 보강 (V74 — 완료, 2026-05-21 라이브 적용)
 
 | 항목 | 상태 |
@@ -461,13 +491,14 @@ ga-api 8082 / ga-frontend 3000 / ga-mobile-pwa 3001 모두 라이브.
 ## 5. 재개 절차 (다음 세션)
 
 1. **Claude Code 시작 시 cwd 확인**: `C:\Users\kyu\Desktop\ga_pro`
-2. **HANDOFF.md 읽기**: 본 문서 §3-15(P6 후속) + 최근 git log
+2. **HANDOFF.md 읽기**: 본 문서 §3-16(계약 승계) + §3-15(P6 후속) + 최근 git log
-3. **운영 DB 상태**: **V85 적용 완료**, 변경 없음. ga-api 8082 + ga-frontend 3000 + ga-mobile-pwa 3001 가동 중
+3. **운영 DB 상태**: **V86 적용 완료** (계약 승계). ga-api 8082 가동. ga-frontend 3000 / ga-mobile-pwa 3001 은 필요 시 기동. origin/main 동기화 완료(HEAD `4dbc688`, 2026-05-29 push).
 4. **재기동이 필요한 경우**:
    - `cd ga-commission-system && nohup ./gradlew :ga-api:bootRun --args='--spring.profiles.active=trading_ai' > ../ga-api-bootrun.log 2>&1 & disown`
    - `cd ga-commission-system/ga-frontend && npm run dev` (3000)
    - `cd ga-commission-system/ga-mobile-pwa && npm run dev` (3001)
-5. **PWA 테스트 계정**: `agent01` / `agent1234!` (userId=4, agentId=1, AGENT role)
+   - 정산 배치: `nohup ./gradlew :ga-batch:bootRun --args='--spring.profiles.active=trading_ai' > ../ga-batch-bootrun.log 2>&1 &` (8081). 트리거 `POST :8081/internal/jobs/monthly-settlement {"settleMonth":"yyyyMM"}` — **JWT 필요(ga-api `/api/auth/login` admin 토큰 재사용)**. 동기 실행.
+5. **테스트 계정 / DB**: `admin`/`admin1234!`(SUPER_ADMIN), `agent01`/`agent1234!`(userId=4·agentId=1·AGENT). 로그인 필드명 `loginId`. DB: psql17 `192.168.0.60:55432/trading_ai` user `kyu`/pw `7895123`, `SET search_path TO ga`.
 6. **사용자 결정 필요 항목 (외부 SDK 차단 사유)**:
    - KFTC 펌뱅킹 API 계약·인증 정보 → `KftcBankTransferAdapter` 본체 구현
    - NHN Toast / 카카오 비즈채널 계정 + 템플릿 코드 → `ToastMessageAdapter` 본체