feat: P5-W3 본론 완료 — 회계결산/이상치예측/연말명세서 (V74~V78)

P5-W2 원천세·부가세 분기신고 미커밋분 + P5-W3 메뉴/권한 보강(V74) + P5-W3 본론(V75~V78)을 일괄 정리.

- V75 accounting_close / account_balance_snapshot (회계 결산)
- V76 retention_anomaly_alert / forecast_kpi_monthly (이상치·예측 KPI)
- V77 year_end_statement (연말 지급명세서)
- V78 P5-W3 본론 메뉴 4 + 권한 + 공통코드 7그룹 + 테스트데이터
- api: AccountingClose/YearEndStatement/ForecastKpi/RetentionAnomaly Service+Controller
- batch: BatchConfig Step 11/12 (원천세·부가세 분기) 연결
- frontend: 4화면(AccountingClose/YearEndStatement/RetentionAnomaly/ForecastKpi) + API 모듈 4 + 라우트
- frontend: usePermission/PermissionButton EXECUTE 권한 누락 보강
- fix: YearEndStatementMapper.xml 미존재 컬럼 a.agent_code 참조 제거

통합검증: Flyway V74~V78 운영DB 적용(v78), 4모듈 compileJava + 프론트 build PASS,
스모크 GET 8/8 + 쓰기 4/4 PASS, verify_v74.py 20/20 PASS.

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

HANDOFF.md

@@ -154,20 +154,46 @@
 
 운영 DB 적용: ga-api 재시작 → Flyway V18~V71 일괄 자동 적용.
 
-## 4. 잔여 작업 (P5-W2/W3 + P6)
+## 3-8. P5 Wave 2 — 원천세/부가세 분기신고 (V67~V69)
 
-### P5-W2 — rule + payout_rule + payment (V67~V69 예정)
-| 항목 | 설명 |
-|---|---|
-| 원천세 신고 자료 | 분기별 사업소득세 집계 + 국세청 포맷 |
-| 부가세 신고 자료 | tax_invoice 기반 매출/매입 집계 |
+| 항목 | 마이그레이션 | 상태 |
+|---|---|---|
+| withholding_tax_report 테이블 (원천세 분기신고) | V67 | 완료 |
+| vat_report 테이블 (부가세 분기신고) | V68 | 완료 |
+| P5-W2 테스트 데이터 + 메뉴 INSERT (WITHHOLDING_TAX / VAT_REPORT) | V69 | 완료 |
+| EXECUTE 권한 보강 (WITHHOLDING_TAX / VAT_REPORT) | V73 | 완료 |
 
-### P5-W3 — 결산 / 이상치 / 연말 명세서
-| 항목 | 설명 |
-|---|---|
-| 결산 | period_close 와 별개의 월/분기/연 회계 마감 |
-| 이상치·예측 KPI | 13M/25M 유지율 이상 탐지 + 차월 예측 |
-| 연말 지급명세서 | 설계사 연 사업소득 세무 자료 PDF |
+핵심 산출물:
+- `withholding_tax_report` (분기별 원천세 신고 집계: settleQuarter/agentId/totalIncome/totalWithheld/totalLocalTax)
+- `vat_report` (분기별 부가세 신고 집계: settleQuarter/totalSales/totalPurchase/totalVatPayable/taxInvoiceCount)
+- `WithholdingTaxReportMapper` + `WithholdingTaxReportMapper.xml` (selectList/selectDetailById/upsertQuarterlyAggregate/updateFileStatusToFiled)
+- `VatReportMapper` + `VatReportMapper.xml` (selectList/selectDetailById/upsertQuarterlyAggregate/updateFileStatusToFiled)
+- `WithholdingTaxReportService` + `WithholdingTaxReportController` (`/api/withholding-tax-reports`)
+- `VatReportService` + `VatReportController` (`/api/vat-reports`)
+- `WithholdingTaxQuarterlyStep` (batch Step 11, 분기 마지막 월 실행)
+- `VatReportQuarterlyStep` (batch Step 12, 분기 마지막 월 실행)
+- 프론트 API 모듈: `ga-frontend/src/api/withholdingTax.ts` + `ga-frontend/src/api/vat.ts`
+
+통합 검증 결과 (2026-05-17):
+- Flyway: 운영 DB ga schema V73 (V67/V68/V69/V73 모두 적용 확인)
+- GET  /api/withholding-tax-reports               → 200 OK, list 반환 (집계 데이터 있음)
+- GET  /api/withholding-tax-reports/1             → 200 OK, 단건 상세 반환
+- POST /api/withholding-tax-reports/regenerate {"settleQuarter":"2025-Q4"} → 200 OK, affected=0 (이미 존재, 정상)
+- PUT  /api/withholding-tax-reports/complete {"ids":[1]}                   → 200 OK
+- GET  /api/vat-reports                           → 200 OK, list 반환
+- GET  /api/vat-reports/1                         → 200 OK, 단건 상세 반환
+- POST /api/vat-reports/regenerate {"settleQuarter":"2025-Q4"}             → 200 OK, affected=1
+- PUT  /api/vat-reports/complete {"ids":[1]}                               → 200 OK
+
+보정 사항 (통합 검증 중 발견):
+- frontend build 실패: ChargebackGradeList/InstallmentRatioList/DeductionList validator 파라미터 implicit any, CommissionDispute/IncentiveProgram/TaxInvoiceList parser 반환타입 불일치 → 명시적 타입 어노테이션으로 수정 (6개 파일)
+- complete 엔드포인트 요청 바디: `{"ids":[id]}` 형식 (단일 reportId 아님)
+
+운영 DB 최신 상태: ga schema V73 적용 완료.
+
+## 4. 잔여 작업 (P6)
+
+P5-W2 / P5-W3(메뉴·권한 보강 V74 + 본론 V75~V78) 모두 완료. 잔여는 P6뿐.
 
 ### P6 — 외부 연동 (P5 이후)
 | 항목 | 설명 |
@@ -176,26 +202,66 @@
 | SMS/카카오 발송 | user_notification 채널 실연동 |
 | 모바일 셀프 조회 | 설계사 전용 모바일 앱 or PWA |
 
-### 운영 DB 마이그레이션 (중요 공지)
-운영 DB `192.168.0.60:55432/trading_ai/ga` 에는 현재 **V17(또는 V22) 까지만** 적용되어 있습니다.
-`ga-api 를 재시작`하면 Flyway 가 V18~V55 를 자동 순차 적용합니다.
-재시작 전까지 P2~P4 신규 도메인 API 는 테이블이 없어 동작하지 않습니다.
+### 운영 DB 마이그레이션 상태
+운영 DB `192.168.0.60:55432/trading_ai/ga` 현재 **V78 적용 완료** (2026-05-21).
+V74~V78 Flyway 자동 적용 확인. ga-api 8082 가동 중.
 
 단위/통합 테스트는 SqlSessionFactory 환경 설정 문제로 아직 미작성 상태입니다.
 
-## 5. 재개 절차 (다음 세션 — P5 라운드)
+## 3-9. P5-W3 메뉴/권한 전수 정합 보강 (V74 — 완료, 2026-05-21 라이브 적용)
+
+| 항목 | 상태 |
+|---|---|
+| AUDIT_P5W3.md §4 갭 리포트 작성 | 완료 (2026-05-17, infra) |
+| V74 SQL 작성 | 완료 (2026-05-17, dba) |
+| V74 정적검증 (PL) | 완료 (멱등·ON CONFLICT·스코프 확인) |
+| 4모듈 compileJava | **PASS** (BUILD SUCCESSFUL) |
+| ga-frontend npm run build | **PASS** (TS 오류 0) |
+| 운영 DB 접속·Flyway V74 적용 | **완료** (2026-05-21, ga-api 재기동 시 자동 적용) |
+| 스모크 검증 | **완료** (verify_v74.py 20/20 PASS) |
+
+갭 요약 (총 27건):
+- (a) menu 없음: 0건
+- (b) menu_permission 없음: 3건 (NOTICE/DELETE, SYSTEM_DATA_DICT/DELETE, TERM_SETTLE/APPROVE)
+- (c) grant 없음: 6건 (위 3 perm × SUPER_ADMIN+ADMIN, ADMIN/SYSTEM_* 7건은 보안상 의도적 제외)
+- route/menu_path 불일치: 11건 (V74에서 UPDATE 처리)
+
+갭 재검증 (V74 적용 후): `python verify_v74.py` → **20/20 PASS** 확인 완료 (2026-05-21).
+
+## 3-10. P5-W3 본론 — 결산 / 이상치·예측 / 연말명세서 (V75~V78, 2026-05-21 완료)
+
+| 항목 | 마이그레이션 | 상태 |
+|---|---|---|
+| accounting_close + account_balance_snapshot (회계 결산) | V75 | 완료 |
+| retention_anomaly_alert + forecast_kpi_monthly (이상치·예측 KPI) | V76 | 완료 |
+| year_end_statement (연말 지급명세서) | V77 | 완료 |
+| P5-W3 본론 메뉴 4개 + 권한 + 공통코드 7그룹 + 테스트데이터 | V78 | 완료 |
+
+핵심 산출물:
+- `AccountingCloseService/Controller` (`/api/accounting-closes`) — DRAFT 생성 / 마감 실행(분개 채번+잔액 스냅샷) / 재오픈
+- `RetentionAnomalyAlertService/Controller` (`/api/retention-anomalies`) — 13M/25M 이상 탐지 / 검토 처리
+- `ForecastKpiMonthlyService/Controller` (`/api/forecast-kpi`) — 이동평균(SMA3/6/NAIVE) 차월 예측
+- `YearEndStatementService/Controller` (`/api/year-end-statements`) — 연 사업소득 명세서 재집계/발급/발송/엑셀
+- 배치: BatchConfig 에 Step 11(WithholdingTaxQuarterly) / Step 12(VatReportQuarterly) 연결
+- 프론트: `AccountingCloseList` / `YearEndStatementList` / `RetentionAnomalyList` / `ForecastKpiList` 4화면 + API 모듈 4개 + App.tsx 라우트 4개
+- 공통: `usePermission`/`PermissionButton` 에 `EXECUTE` 권한 누락 보강 (canExecute)
+
+통합 검증 (2026-05-21):
+- Flyway: 운영 DB V74~V78 자동 적용 → 현재 **v78**
+- 4모듈 compileJava + ga-frontend npm run build **PASS** (TS 오류 0)
+- 스모크: 신규 4 + 회귀 4 = **GET 8/8 PASS**, 쓰기(regenerate/detect/draft) 4/4 PASS
+- 보정: YearEndStatementMapper.xml 의 `a.agent_code` 미존재 컬럼 참조 제거 (agent 테이블에 agent_code 없음)
+
+## 5. 재개 절차 (다음 세션 — P6 라운드)
 
 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. **권장 시작 지점**: P5 Wave 1 — dba-architect에게 V56~V61 (회계 전표 / 원천세 / 부가세 / 결산 / 이상치 / 연말 지급명세서)
-6. **ga-api 재시작 필요**: 운영 DB 에 V18~V55 적용하려면 ga-api 재시작 후 Flyway 자동 실행 확인
-7. **사용자 결정 필요 항목**:
-   - P5 시작 전 ga-api 재시작해서 V18~V55 운영 DB 반영 여부
+2. **Agent Teams 활성화 확인**: `.claude/settings.json` 커밋되어 있음
+3. **HANDOFF.md 읽기**: 본 문서 + 최근 git log로 컨텍스트 확보
+4. **운영 DB 상태**: **V78 적용 완료**. ga-api 8082 가동 중 (필요 시 `python verify_v74.py` / `smoke_v78.py` 재실행)
+5. **권장 시작 지점**: P6 외부 연동 — 펌뱅킹 실연동 / SMS·카카오 발송 / 모바일 셀프 조회
+6. **사용자 결정 필요 항목**:
    - P2-1 마감 도메인의 마감 후 수정 차단 AOP 구현 방식 (전역 AOP vs Service-level 가드)
+   - P6 펌뱅킹/메시징 외부 연동처 실제 스펙 (현재 미정 → 착수 전 확인 필요)
 
 ## 6. PL 가이드 (다음 세션 유의사항)