diff --git a/changes/20260122_tax_simulation_api.md b/changes/20260122_tax_simulation_api.md new file mode 100644 index 0000000..ee32165 --- /dev/null +++ b/changes/20260122_tax_simulation_api.md @@ -0,0 +1,104 @@ +# 변경 내용 요약 + +**날짜:** 2026-01-22 +**작업자:** Claude Code +**계획 문서:** docs/plans/card-management-section-plan.md +**Phase:** 1.3 세금 시뮬레이션 API 개발 + +## 📋 변경 개요 +CEO 대시보드 카드/가지급금 관리 섹션(cm2)의 세금 시뮬레이션 API 엔드포인트 신규 추가. +가지급금으로 인한 법인세 및 소득세 추가 부담을 시뮬레이션하여 세금 비교 분석 데이터 제공. + +## 📁 수정된 파일 +- `api/app/Services/LoanService.php` - taxSimulation() 메서드 추가 +- `api/app/Http/Controllers/Api/V1/LoanController.php` - taxSimulation() 액션 추가 +- `api/routes/api.php` - /tax-simulation 라우트 등록 +- `api/app/Swagger/v1/LoanApi.php` - LoanTaxSimulation 스키마 및 엔드포인트 문서화 + +## 🔧 상세 변경 사항 + +### 1. LoanService.php +**신규 메서드:** +- `taxSimulation(int $year)` - 세금 시뮬레이션 데이터 반환 + - 기존 `summary()` 호출하여 미정산 가지급금 총액 획득 + - 기존 `calculateInterest()` 호출하여 인정이자 계산 + - 법인세 비교 (가지급금 유무에 따른 세금 차이) + - 소득세 비교 (대표이사 상여처분 시나리오) + +**응답 구조:** +```php +[ + 'year' => int, // 시뮬레이션 연도 + 'loan_summary' => [ + 'total_outstanding' => float, // 가지급금 잔액 + 'recognized_interest' => float, // 인정이자 + 'interest_rate' => float, // 이자율 (4.6%) + ], + 'corporate_tax' => [ // 법인세 비교 + 'without_loan' => [ + 'taxable_income' => float, + 'tax_amount' => float, + ], + 'with_loan' => [ + 'taxable_income' => float, // 인정이자 + 'tax_amount' => float, // 인정이자 × 19% + ], + 'difference' => float, // 추가 법인세 + 'rate_info' => string, // "법인세 19% 적용" + ], + 'income_tax' => [ // 소득세 비교 + 'without_loan' => [ + 'taxable_income' => float, + 'tax_rate' => string, + 'tax_amount' => float, + ], + 'with_loan' => [ + 'taxable_income' => float, + 'tax_rate' => string, // "35%" + 'tax_amount' => float, + ], + 'difference' => float, + 'breakdown' => [ + 'income_tax' => float, // 소득세 (35%) + 'local_tax' => float, // 지방소득세 (소득세의 10%) + 'insurance' => float, // 4대보험 추정 (9%) + ], + ], +] +``` + +### 2. LoanController.php +**신규 액션:** +```php +public function taxSimulation(LoanCalculateInterestRequest $request): JsonResponse +``` + +### 3. api/routes/api.php +**신규 라우트:** +```php +Route::get('/tax-simulation', [LoanController::class, 'taxSimulation']) + ->name('v1.loans.tax-simulation'); +``` + +### 4. LoanApi.php (Swagger) +**신규 스키마:** +- `LoanTaxSimulation` - 세금 시뮬레이션 응답 전체 구조 + +**신규 엔드포인트:** +- `GET /api/v1/loans/tax-simulation?year={year}` + +## ✅ 테스트 체크리스트 +- [x] Pint 코드 스타일 검증 통과 +- [x] 라우트 등록 확인 (php artisan route:list) +- [x] Swagger 문서 생성 완료 +- [ ] API 호출 테스트 (Swagger UI) +- [ ] 프론트엔드 연동 테스트 + +## ⚠️ 배포 시 주의사항 +특이사항 없음 (DB 스키마 변경 없음) + +## 🔗 관련 문서 +- 계획 문서: `docs/plans/card-management-section-plan.md` +- Phase 1.1 변경: `docs/changes/20260122_card_transaction_dashboard_api.md` +- Phase 1.2 변경: `docs/changes/20260122_loan_dashboard_api.md` +- 기존 API 문서: `api/app/Swagger/v1/LoanApi.php` \ No newline at end of file diff --git a/plans/card-management-section-plan.md b/plans/card-management-section-plan.md index 1b85009..f4bc46e 100644 --- a/plans/card-management-section-plan.md +++ b/plans/card-management-section-plan.md @@ -11,9 +11,9 @@ | 항목 | 내용 | |------|------| -| **마지막 완료 작업** | Phase 1.2 가지급금 대시보드 API 개발 완료 | -| **다음 작업** | Phase 1.3 세금 시뮬레이션 API 개발 | -| **진행률** | 2/12 (17%) | +| **마지막 완료 작업** | Phase 1.3 세금 시뮬레이션 API 개발 완료 | +| **다음 작업** | Phase 2.1 API 타입 정의 | +| **진행률** | 3/12 (25%) | | **마지막 업데이트** | 2026-01-22 | --- @@ -134,7 +134,7 @@ CEO 대시보드의 카드/가지급금 관리 섹션은 4개의 카드로 구 |---|----------|:----:|------| | 1.1 | 카드 거래 대시보드 API 개발 | ✅ | 월별 추이, 사용자별 비율 | | 1.2 | 가지급금 대시보드 API 개발 | ✅ | 대시보드 요약 + 목록 | -| 1.3 | 세금 시뮬레이션 API 개발 | ⏳ | 법인세/종합소득세 비교 | +| 1.3 | 세금 시뮬레이션 API 개발 | ✅ | 법인세/종합소득세 비교 | ### 3.2 Phase 2: 프론트엔드 타입 및 API 연동 @@ -358,6 +358,7 @@ interface UseCardManagementModalsReturn { | 날짜 | 항목 | 변경 내용 | 파일 | 승인 | |------|------|----------|------|------| +| 2026-01-22 | Phase 1.3 | 세금 시뮬레이션 API 개발 완료 | LoanService, LoanController, LoanApi | ✅ | | 2026-01-22 | Phase 1.2 | 가지급금 대시보드 API 개발 완료 | LoanService, LoanController, LoanApi | ✅ | | 2026-01-22 | Phase 1.1 | 카드 거래 대시보드 API 개발 완료 | CardTransactionService, CardTransactionController, CardTransactionApi | ✅ | | 2026-01-22 | - | 문서 초안 작성 | - | - |