동기화

HANDOFF.md

@@ -118,14 +118,53 @@
 ### 3-6. P1 정산 통합 (batch-engineer 완료)
 - ga-batch 8 Step에 TaxCalculator / DeductionService / RegulatoryLimitChecker / InstallmentPlanGenerator / ChargebackCalculator 통합 완료
 
-## 4. 잔여 작업 (P5/P6)
+## 3-7. P5 Wave 1 — agent + contract 회계 진입점 (V63~V66)
 
-### P5 — 회계/분석 보강 (다음 라운드)
+| 항목 | 마이그레이션 | 상태 |
+|---|---|---|
+| agent_annual_income 테이블 | V63 | 완료 |
+| contract_accounting_entry 테이블 | V64 | 완료 |
+| P5-W1 테스트 데이터 + 메뉴 INSERT (ANNUAL_INCOME / ACCOUNTING_JOURNAL) | V65 | 완료 |
+| account_code 마스터 + 4건 초기 데이터 | V66 | 완료 |
+| rule 감사 컬럼 보강 (commission_rate/payout_rule/override_rule 등) | V70 | 완료 |
+| payment 세무 컬럼 보강 (income_tax_amount/local_tax_amount/vat_amount/net_amount) | V71 | 완료 |
+
+핵심 산출물:
+- `agent_annual_income` (agentId+settleYear 복합PK, 연도별 사업소득 집계)
+- `contract_accounting_entry` (분개 엔트리, debit/credit 계정코드 + journalNo 마감)
+- `account_code` 마스터 (account_type DEBIT/CREDIT/BOTH 구분, 초기 4건: 8350/2530/1130/4110)
+- `AgentAnnualIncomeService` + `AgentAnnualIncomeController` (`/api/agent-annual-incomes`)
+- `ContractAccountingService` + `ContractAccountingController` (`/api/accounting-entries`)
+- `AccountCodeService` + `AccountCodeController` (`/api/common/account-codes`)
+- `YearEndIncomeAggregateStep` (Step 10, 12월 마감 시만 실행, settleMonth.endsWith("12") 조건)
+- `AccountingEntryGenerateStep` (Step 9, 매월 정산 후 분개 생성, ledger UNION 기반 contract_id 확보, journal_no=NULL 미전기)
+- 프론트 화면: `AgentAnnualIncomeList` (`/commission/annual-income`) + `AccountingJournalList` (`/commission/accounting-journal`)
+
+통합 검증 결과 (2026-05-15):
+- Flyway: V63/V64/V65/V66/V70/V71 적용 확인 (현재 ga schema V71)
+- GET /api/agent-annual-incomes → 200 OK
+- POST /api/agent-annual-incomes/regenerate?year=2025 → 200 OK, affected=0 (payment 데이터 없음, 정상)
+- GET /api/accounting-entries → 200 OK
+- GET /api/common/account-codes?accountType=DEBIT → 200 OK, 2 items
+
+보정 사항 (통합 검증 중 발견):
+- App.tsx 라우트와 V65 menu_path 모두 `/commission/annual-income`, `/commission/accounting-journal`로 일치
+- ANNUAL_INCOME EXECUTE 권한 누락 → DB 직접 INSERT로 보정
+- payment 세무 컬럼 미적용 (V23 체크섬 충돌 이력) → V71로 idempotent 보강
+
+운영 DB 적용: ga-api 재시작 → Flyway V18~V71 일괄 자동 적용.
+
+## 4. 잔여 작업 (P5-W2/W3 + P6)
+
+### P5-W2 — rule + payout_rule + payment (V67~V69 예정)
 | 항목 | 설명 |
 |---|---|
-| 회계 전표 자동 분개 | 수수료 지급액 → 분개 엔트리 자동 생성 |
 | 원천세 신고 자료 | 분기별 사업소득세 집계 + 국세청 포맷 |
 | 부가세 신고 자료 | tax_invoice 기반 매출/매입 집계 |
+
+### P5-W3 — 결산 / 이상치 / 연말 명세서
+| 항목 | 설명 |
+|---|---|
 | 결산 | period_close 와 별개의 월/분기/연 회계 마감 |
 | 이상치·예측 KPI | 13M/25M 유지율 이상 탐지 + 차월 예측 |
 | 연말 지급명세서 | 설계사 연 사업소득 세무 자료 PDF |