From 0c1a1a57856964cc9e7c0f541004d344b35e50fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B6=8C=ED=98=81=EC=84=B1?= Date: Thu, 22 Jan 2026 22:28:41 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Phase=201.1=20=EC=B9=B4=EB=93=9C=20?= =?UTF-8?q?=EA=B1=B0=EB=9E=98=20=EB=8C=80=EC=8B=9C=EB=B3=B4=EB=93=9C=20API?= =?UTF-8?q?=20=EA=B0=9C=EB=B0=9C=20=EC=99=84=EB=A3=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 카드/가지급금 관리 섹션 계획 문서 추가 - 변경 이력 문서 추가 Co-Authored-By: Claude --- ...20260122_card_transaction_dashboard_api.md | 75 ++ plans/card-management-section-plan.md | 819 ++++++++++++++++++ 2 files changed, 894 insertions(+) create mode 100644 changes/20260122_card_transaction_dashboard_api.md create mode 100644 plans/card-management-section-plan.md diff --git a/changes/20260122_card_transaction_dashboard_api.md b/changes/20260122_card_transaction_dashboard_api.md new file mode 100644 index 0000000..2c2224d --- /dev/null +++ b/changes/20260122_card_transaction_dashboard_api.md @@ -0,0 +1,75 @@ +# 변경 내용 요약 + +**날짜:** 2026-01-22 +**작업자:** Claude Code +**계획 문서:** docs/plans/card-management-section-plan.md +**Phase:** 1.1 카드 거래 대시보드 API 개발 + +## 📋 변경 개요 +CEO 대시보드 카드/가지급금 관리 섹션(cm1)의 모달 팝업용 카드 거래 대시보드 API 엔드포인트 신규 추가. +기존 summary API를 확장하여 월별 추이, 사용자별 비율, 최근 거래 목록을 포함한 상세 데이터 제공. + +## 📁 수정된 파일 +- `api/app/Services/CardTransactionService.php` - dashboard() 메서드 및 헬퍼 메서드 추가 +- `api/app/Http/Controllers/Api/V1/CardTransactionController.php` - dashboard() 액션 추가 +- `api/routes/api.php` - /dashboard 라우트 등록 +- `api/app/Swagger/v1/CardTransactionApi.php` - 대시보드 스키마 및 엔드포인트 문서화 + +## 🔧 상세 변경 사항 + +### 1. CardTransactionService.php +**신규 메서드:** +- `dashboard()` - 대시보드 전체 데이터 반환 +- `getMonthTotal()` - 특정 기간 카드 사용액 합계 (private) +- `getMonthlyTrend()` - 최근 N개월 월별 추이 (private) +- `getUserRatio()` - 사용자별 카드 사용 비율 (private) +- `getRecentTransactions()` - 최근 거래 목록 (private) + +**응답 구조:** +```php +[ + 'summary' => [ + 'current_month_total' => float, + 'previous_month_total' => float, + 'change_rate' => float, + 'unprocessed_count' => int, + ], + 'monthly_trend' => [...], + 'user_ratio' => [...], + 'recent_transactions' => [...], +] +``` + +### 2. CardTransactionController.php +**신규 액션:** +```php +public function dashboard(): JsonResponse +``` + +### 3. api/routes/api.php +**신규 라우트:** +```php +Route::get('/dashboard', [CardTransactionController::class, 'dashboard']) + ->name('v1.card-transactions.dashboard'); +``` + +### 4. CardTransactionApi.php (Swagger) +**신규 스키마:** +- `CardTransactionDashboard` - 대시보드 응답 전체 구조 + +**신규 엔드포인트:** +- `GET /api/v1/card-transactions/dashboard` + +## ✅ 테스트 체크리스트 +- [x] Pint 코드 스타일 검증 통과 +- [x] 라우트 등록 확인 (php artisan route:list) +- [x] Swagger 문서 생성 완료 +- [ ] API 호출 테스트 (Swagger UI) +- [ ] 프론트엔드 연동 테스트 + +## ⚠️ 배포 시 주의사항 +특이사항 없음 (DB 스키마 변경 없음) + +## 🔗 관련 문서 +- 계획 문서: `docs/plans/card-management-section-plan.md` +- 기존 API 문서: `api/app/Swagger/v1/CardTransactionApi.php` \ No newline at end of file diff --git a/plans/card-management-section-plan.md b/plans/card-management-section-plan.md new file mode 100644 index 0000000..cb32802 --- /dev/null +++ b/plans/card-management-section-plan.md @@ -0,0 +1,819 @@ +# 카드/가지급금 관리 섹션 데이터 연동 계획 + +> **작성일**: 2026-01-22 +> **목적**: CEO 대시보드 카드/가지급금 관리 섹션의 4개 카드 데이터 연동 및 모달 팝업 내용 개발 +> **기준 문서**: `cardManagementConfigs.ts`, `LoanApi.php`, `CardTransactionApi.php` +> **상태**: 🔄 진행중 (Serena ID: card-management-plan-state) + +--- + +## 📍 현재 진행 상태 + +| 항목 | 내용 | +|------|------| +| **마지막 완료 작업** | Phase 1.1 카드 거래 대시보드 API 개발 완료 | +| **다음 작업** | Phase 1.2 가지급금 대시보드 API 개발 | +| **진행률** | 1/12 (8%) | +| **마지막 업데이트** | 2026-01-22 | + +--- + +## 1. 개요 + +### 1.1 배경 +CEO 대시보드의 카드/가지급금 관리 섹션은 4개의 카드로 구성되어 있으며, 현재 목업 데이터를 사용 중입니다. +각 카드 클릭 시 표시되는 모달 팝업도 하드코딩된 목업 데이터를 사용하고 있어 실제 API 연동이 필요합니다. + +**4개 카드 구성:** +- **cm1**: 카드 (당월 카드 사용액) +- **cm2**: 가지급금 (미정산 가지급금) +- **cm3**: 법인세 예상 가중 (가지급금으로 인한 법인세 추가) +- **cm4**: 대표자 종합세 예상 가중 (가지급금으로 인한 종합소득세 추가) + +### 1.2 기준 원칙 +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 🎯 핵심 원칙 │ +├─────────────────────────────────────────────────────────────────┤ +│ - 기존 API 최대 활용, 신규 API 최소화 │ +│ - 대시보드 전용 엔드포인트는 /dashboard 하위에 구성 │ +│ - 모달 데이터는 lazy loading (모달 열릴 때 호출) │ +│ - 에러 시 graceful degradation (목업 데이터 fallback) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 1.3 변경 승인 정책 + +| 분류 | 예시 | 승인 | +|------|------|------| +| ✅ 즉시 가능 | API 응답 필드 추가, 프론트엔드 타입 추가 | 불필요 | +| ⚠️ 컨펌 필요 | 신규 API 엔드포인트, 서비스 로직 변경 | **필수** | +| 🔴 금지 | DB 스키마 변경, 기존 API 응답 형식 변경 | 별도 협의 | + +### 1.4 준수 규칙 +- `docs/quickstart/quick-start.md` - 빠른 시작 가이드 +- `docs/standards/quality-checklist.md` - 품질 체크리스트 +- `api/CLAUDE.md` - SAM API Development Rules + +--- + +## 2. 기존 API 현황 분석 + +### 2.1 CardTransaction API (카드 거래) + +| 엔드포인트 | 설명 | 모달 활용 | +|-----------|------|----------| +| `GET /api/v1/card-transactions` | 카드 거래 목록 | cm1 테이블 | +| `GET /api/v1/card-transactions/summary` | 전월/당월 요약 | cm1 summaryCards | +| `GET /api/v1/card-transactions/{id}` | 상세 조회 | - | + +**summary 응답 구조:** +```json +{ + "previous_month_total": 1500000, + "current_month_total": 850000, + "total_count": 45, + "total_amount": 2350000 +} +``` + +**🔴 부족한 데이터:** +- 월별 추이 데이터 (barChart용) +- 사용자별/카드별 비율 데이터 (pieChart용) + +### 2.2 Loan API (가지급금) + +| 엔드포인트 | 설명 | 모달 활용 | +|-----------|------|----------| +| `GET /api/v1/loans` | 가지급금 목록 | cm2 테이블 | +| `GET /api/v1/loans/summary` | 가지급금 요약 | cm2 summaryCards | +| `POST /api/v1/loans/calculate-interest` | 인정이자 계산 | cm2, cm3, cm4 | +| `GET /api/v1/loans/interest-report/{year}` | 연간 리포트 | cm3, cm4 | + +**summary 응답 구조:** +```json +{ + "total_count": 10, + "outstanding_count": 5, + "settled_count": 3, + "partial_count": 2, + "total_amount": 50000000, + "total_settled": 30000000, + "total_outstanding": 20000000 +} +``` + +**calculate-interest 응답 구조:** +```json +{ + "year": 2026, + "interest_rate": 4.6, + "summary": { + "total_balance": 50000000, + "total_recognized_interest": 2300000, + "total_corporate_tax": 437000, + "total_income_tax": 805000, + "total_local_tax": 80500, + "total_tax": 1322500 + }, + "details": [...] +} +``` + +**🔴 부족한 데이터:** +- 법인세 비교 (가지급금 없을 때 vs 있을 때) +- 종합소득세 비교 (가지급금 없을 때 vs 있을 때) + +--- + +## 3. 대상 범위 + +### 3.1 Phase 1: API 개발 (Backend) + +| # | 작업 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 1.1 | 카드 거래 대시보드 API 개발 | ✅ | 월별 추이, 사용자별 비율 | +| 1.2 | 가지급금 대시보드 API 개발 | ⏳ | 대시보드 요약 + 목록 | +| 1.3 | 세금 시뮬레이션 API 개발 | ⏳ | 법인세/종합소득세 비교 | + +### 3.2 Phase 2: 프론트엔드 타입 및 API 연동 + +| # | 작업 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 2.1 | API 타입 정의 추가 | ⏳ | `lib/api/dashboard/types.ts` | +| 2.2 | API 엔드포인트 함수 추가 | ⏳ | `lib/api/dashboard/endpoints.ts` | +| 2.3 | 모달 데이터 훅 생성 | ⏳ | `useCardManagementModals.ts` | + +### 3.3 Phase 3: 모달 컴포넌트 연동 + +| # | 작업 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 3.1 | cm1 카드 모달 데이터 연동 | ⏳ | 카드 사용 상세 | +| 3.2 | cm2 가지급금 모달 데이터 연동 | ⏳ | 가지급금 상세 | +| 3.3 | cm3 법인세 모달 데이터 연동 | ⏳ | 법인세 예상 가중 상세 | +| 3.4 | cm4 종합소득세 모달 데이터 연동 | ⏳ | 대표자 종합소득세 상세 | + +### 3.4 Phase 4: 카드 데이터 연동 및 테스트 + +| # | 작업 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 4.1 | 4개 카드 데이터 연동 | ⏳ | 섹션 카드 표시 | +| 4.2 | 에러 핸들링 및 fallback | ⏳ | graceful degradation | + +--- + +## 4. 상세 작업 내용 + +### 4.1 Phase 1: API 개발 + +#### 1.1 카드 거래 대시보드 API + +**파일**: `api/app/Http/Controllers/Api/V1/CardTransactionController.php` + +**신규 엔드포인트:** +``` +GET /api/v1/card-transactions/dashboard +``` + +**응답 구조:** +```typescript +interface CardTransactionDashboardResponse { + summary: { + current_month_total: number; // 당월 카드 사용액 + previous_month_total: number; // 전월 카드 사용액 + change_rate: number; // 전월 대비 증감률 (%) + unprocessed_count: number; // 미정리 건수 + }; + monthly_trend: Array<{ // 최근 6개월 추이 + month: string; // "2026-01" + amount: number; + }>; + user_ratio: Array<{ // 사용자별 비율 + user_name: string; + amount: number; + percentage: number; + }>; + recent_transactions: Array<{ // 최근 거래 (10건) + id: number; + card_name: string; + user_name: string; + used_at: string; + merchant_name: string; + amount: number; + usage_type: string | null; // 계정과목 + }>; +} +``` + +#### 1.2 가지급금 대시보드 API + +**파일**: `api/app/Http/Controllers/Api/V1/LoanController.php` + +**신규 엔드포인트:** +``` +GET /api/v1/loans/dashboard +``` + +**응답 구조:** +```typescript +interface LoanDashboardResponse { + summary: { + total_outstanding: number; // 미정산 가지급금 총액 + recognized_interest: number; // 인정이자 (연 4.6%) + outstanding_count: number; // 미정산 건수 + }; + loans: Array<{ // 가지급금 목록 + id: number; + loan_date: string; + user_name: string; + category: string; // 카드/계좌 + amount: number; + status: string; + content: string; + }>; +} +``` + +#### 1.3 세금 시뮬레이션 API + +**파일**: `api/app/Http/Controllers/Api/V1/LoanController.php` + +**신규 엔드포인트:** +``` +GET /api/v1/loans/tax-simulation?year={year} +``` + +**응답 구조:** +```typescript +interface TaxSimulationResponse { + year: number; + loan_summary: { + total_outstanding: number; // 가지급금 잔액 + recognized_interest: number; // 인정이자 + interest_rate: number; // 이자율 (4.6%) + }; + corporate_tax: { // 법인세 + without_loan: { // 가지급금 없을 때 + taxable_income: number; // 과세표준 + tax_amount: number; // 법인세액 + }; + with_loan: { // 가지급금 있을 때 + taxable_income: number; + tax_amount: number; + }; + difference: number; // 차이 (가중액) + rate_info: string; // 적용 세율 정보 + }; + income_tax: { // 종합소득세 + without_loan: { + taxable_income: number; + tax_rate: string; + tax_amount: number; + }; + with_loan: { + taxable_income: number; + tax_rate: string; + tax_amount: number; + }; + difference: number; + breakdown: { // 세부 내역 + income_tax: number; + local_tax: number; + insurance: number; // 4대보험 + }; + }; +} +``` + +### 4.2 Phase 2: 프론트엔드 타입 및 API 연동 + +#### 2.1 API 타입 정의 + +**파일**: `react/src/lib/api/dashboard/types.ts` + +추가할 타입: +- `CardTransactionDashboardApiResponse` +- `LoanDashboardApiResponse` +- `TaxSimulationApiResponse` + +#### 2.2 API 엔드포인트 함수 + +**파일**: `react/src/lib/api/dashboard/endpoints.ts` + +추가할 함수: +- `fetchCardTransactionDashboard()` +- `fetchLoanDashboard()` +- `fetchTaxSimulation(year: number)` + +#### 2.3 모달 데이터 훅 + +**파일**: `react/src/hooks/useCardManagementModals.ts` + +```typescript +interface UseCardManagementModalsReturn { + cm1Data: CardTransactionDashboardData | null; + cm2Data: LoanDashboardData | null; + cm3Data: TaxSimulationData | null; + cm4Data: TaxSimulationData | null; + loading: boolean; + error: string | null; + fetchModalData: (cardId: string) => Promise; +} +``` + +### 4.3 Phase 3: 모달 컴포넌트 연동 + +**파일**: `react/src/components/business/CEODashboard/modalConfigs/cardManagementConfigs.ts` + +현재 하드코딩된 데이터를 API 데이터로 대체: +- `summaryCards`: API 응답에서 동적 생성 +- `barChart.data`: `monthly_trend` 데이터 매핑 +- `pieChart.data`: `user_ratio` 데이터 매핑 +- `table.data`: API 목록 데이터 매핑 +- `comparisonSection`: 세금 시뮬레이션 데이터 매핑 + +### 4.4 Phase 4: 카드 데이터 연동 + +**파일**: `react/src/lib/api/dashboard/transformers.ts` + +`transformCardManagementResponse` 함수 수정: +- cm1: `CardTransactionSummary` 활용 (기존) +- cm2: `LoanSummary` 활용 +- cm3: `TaxSimulation.corporate_tax.difference` 활용 +- cm4: `TaxSimulation.income_tax.difference` 활용 + +--- + +## 5. 컨펌 대기 목록 + +| # | 항목 | 변경 내용 | 영향 범위 | 상태 | +|---|------|----------|----------|------| +| 1 | 카드 거래 대시보드 API | 신규 엔드포인트 추가 | API 프로젝트 | ⏳ | +| 2 | 가지급금 대시보드 API | 신규 엔드포인트 추가 | API 프로젝트 | ⏳ | +| 3 | 세금 시뮬레이션 API | 신규 엔드포인트 추가 | API 프로젝트 | ⏳ | + +--- + +## 6. 변경 이력 + +| 날짜 | 항목 | 변경 내용 | 파일 | 승인 | +|------|------|----------|------|------| +| 2026-01-22 | - | 문서 초안 작성 | - | - | + +--- + +## 7. 참고 문서 + +- **빠른 시작**: `docs/quickstart/quick-start.md` +- **품질 체크리스트**: `docs/standards/quality-checklist.md` +- **API 규칙**: `api/CLAUDE.md` +- **Loan Swagger**: `api/app/Swagger/v1/LoanApi.php` +- **CardTransaction Swagger**: `api/app/Swagger/v1/CardTransactionApi.php` +- **모달 설정**: `react/src/components/business/CEODashboard/modalConfigs/cardManagementConfigs.ts` + +--- + +## 8. 세션 및 메모리 관리 정책 + +### 8.1 세션 시작 시 (Load Strategy) +```javascript +read_memory("card-management-plan-state") // 1. 상태 파악 +read_memory("card-management-plan-snapshot") // 2. 사고 흐름 복구 +``` + +### 8.2 작업 중 관리 (Context Defense) +| 컨텍스트 잔량 | Action | 내용 | +|--------------|--------|---------| +| **30% 이하** | 🛠 **Snapshot** | `write_memory("card-management-plan-snapshot", "코드변경+논의요약")` | +| **20% 이하** | 🧹 **Context Purge** | `write_memory("card-management-plan-active-symbols", "주요 수정 파일/함수")` | +| **10% 이하** | 🛑 **Stop & Save** | 최종 상태 저장 후 세션 교체 권고 | + +--- + +## 9. 검증 결과 + +> 작업 완료 후 이 섹션에 검증 결과 추가 + +### 9.1 테스트 케이스 + +| 입력값 | 예상 결과 | 실제 결과 | 상태 | +|--------|----------|----------|------| +| cm1 카드 클릭 | 카드 사용 상세 모달 표시 | - | ⏳ | +| cm2 카드 클릭 | 가지급금 상세 모달 표시 | - | ⏳ | +| cm3 카드 클릭 | 법인세 상세 모달 표시 | - | ⏳ | +| cm4 카드 클릭 | 종합소득세 상세 모달 표시 | - | ⏳ | +| API 실패 시 | fallback 데이터 표시 | - | ⏳ | + +### 9.2 성공 기준 달성 현황 + +| 기준 | 달성 | 비고 | +|------|------|------| +| 4개 카드 실제 데이터 표시 | ⏳ | | +| 모달 팝업 실제 데이터 표시 | ⏳ | | +| 에러 시 graceful degradation | ⏳ | | + +--- + +## 10. 기존 코드 스니펫 (자기완결성 보완) + +> 새 세션에서 이 문서만 보고 즉시 작업 가능하도록 핵심 코드 스니펫 포함 + +### 10.1 데이터 흐름 다이어그램 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ CEO Dashboard 카드/가지급금 데이터 흐름 │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────────┐ ┌───────────────────┐ │ +│ │ Laravel API │ → │ Next.js Proxy │ → │ useCEODashboard │ │ +│ │ /api/v1/... │ │ /api/proxy/... │ │ Hook │ │ +│ └──────────────┘ └──────────────────┘ └─────────┬─────────┘ │ +│ │ │ +│ API Endpoints: ↓ │ +│ - card-transactions/summary ────────────────→ transformCardManagement │ +│ - loans/summary (신규 필요) Response() │ +│ - loans/tax-simulation (신규 필요) │ │ +│ ↓ │ +│ ┌─────────────────────────┐ │ +│ │ CardManagementData │ │ +│ │ ├─ cards: AmountCard[] │ │ +│ │ ├─ checkPoints[] │ │ +│ │ └─ warningBanner? │ │ +│ └───────────┬─────────────┘ │ +│ │ │ +│ ┌────────────────────────────────────────────────┤ │ +│ ↓ ↓ │ +│ ┌──────────────────┐ ┌───────────────────────────────┐ │ +│ │ CardManagement │ │ DetailModal │ │ +│ │ Section │ ──(카드 클릭)──→ │ ├─ getCardManagementModal │ │ +│ │ (4개 카드 표시) │ │ │ Config(cardId) │ │ +│ └──────────────────┘ │ └─ DetailModalConfig 사용 │ │ +│ └───────────────────────────────┘ │ +│ │ +│ ⚠️ 현재 모달은 하드코딩 데이터 사용 → API 연동 필요 │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### 10.2 현재 transformCardManagementResponse 함수 + +**파일**: `react/src/lib/api/dashboard/transformers.ts` (486-524행) + +```typescript +/** + * CardTransaction 요약 API 응답 → CardManagementData 변환 + * + * ⚠️ 현재 상태: cm1(카드)만 실제 데이터, cm2~cm4는 fallback 사용 + */ +export function transformCardManagementResponse( + summaryApi: CardTransactionApiResponse, + fallbackData?: CardManagementData +): CardManagementData { + const changeRate = calculateChangeRate( + summaryApi.current_month_total, + summaryApi.previous_month_total + ); + + return { + warningBanner: fallbackData?.warningBanner, + cards: [ + { + id: 'cm1', + label: '카드', + amount: summaryApi.current_month_total, + previousLabel: `전월 대비 ${changeRate > 0 ? '+' : ''}${changeRate.toFixed(1)}%`, + }, + // ⚠️ cm2~cm4: 아직 API 미연동 → fallback 또는 기본값 + fallbackData?.cards[1] ?? { + id: 'cm2', + label: '가지급금', + amount: 0, + previousLabel: '미정리 0건', + }, + fallbackData?.cards[2] ?? { + id: 'cm3', + label: '법인세 예상 가중', + amount: 0, + }, + fallbackData?.cards[3] ?? { + id: 'cm4', + label: '대표자 종합세 예상 가중', + amount: 0, + }, + ], + checkPoints: generateCardManagementCheckPoints(summaryApi), + }; +} +``` + +### 10.3 useCardManagement Hook + +**파일**: `react/src/hooks/useCEODashboard.ts` (214-242행) + +```typescript +export function useCardManagement(fallbackData?: CardManagementData) { + const [data, setData] = useState(null); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + + const fetchData = useCallback(async () => { + try { + setLoading(true); + setError(null); + + // 현재: card-transactions/summary만 호출 + const apiData = await fetchApi( + 'card-transactions/summary' + ); + const transformed = transformCardManagementResponse(apiData, fallbackData); + setData(transformed); + + } catch (err) { + const errorMessage = err instanceof Error ? err.message : '데이터 로딩 실패'; + setError(errorMessage); + console.error('CardManagement API Error:', err); + } finally { + setLoading(false); + } + }, [fallbackData]); + + useEffect(() => { + fetchData(); + }, [fetchData]); + + return { data, loading, error, refetch: fetchData }; +} +``` + +### 10.4 DetailModalConfig 타입 정의 + +**파일**: `react/src/components/business/CEODashboard/types.ts` (414-426행) + +```typescript +// 상세 모달 전체 설정 타입 +export interface DetailModalConfig { + title: string; + summaryCards: SummaryCardData[]; + barChart?: BarChartConfig; + pieChart?: PieChartConfig; + horizontalBarChart?: HorizontalBarChartConfig; + comparisonSection?: ComparisonSectionConfig; // VS 비교 섹션 + referenceTable?: ReferenceTableConfig; // 참조 테이블 + referenceTables?: ReferenceTableConfig[]; // 다중 참조 테이블 + calculationCards?: CalculationCardsConfig; + quarterlyTable?: QuarterlyTableConfig; + table?: TableConfig; +} +``` + +### 10.5 모달 설정 구조 (cardManagementConfigs.ts) + +**파일**: `react/src/components/business/CEODashboard/modalConfigs/cardManagementConfigs.ts` + +```typescript +// ⚠️ 현재: 모든 데이터가 하드코딩됨 → API 연동 필요 + +export function getCardManagementModalConfig(cardId: string): DetailModalConfig | null { + const configs: Record = { + // cm1: 카드 사용 상세 + cm1: { + title: '카드 사용 상세', + summaryCards: [ + { label: '당월 카드 사용', value: 30123000, unit: '원' }, + { label: '전월 대비', value: '+10.5%', isComparison: true, isPositive: true }, + { label: '미정리 건수', value: '5건' }, + ], + barChart: { + title: '월별 카드 사용 추이', + data: [...], // 6개월 추이 데이터 + dataKey: 'value', + xAxisKey: 'name', + color: '#60A5FA', + }, + pieChart: { + title: '사용자별 카드 사용 비율', + data: [...], // 사용자별 비율 데이터 + }, + table: { + title: '카드 사용 내역', + columns: [...], + data: [...], // 최근 카드 사용 내역 + filters: [...], + showTotal: true, + }, + }, + + // cm2: 가지급금 상세 + cm2: { + title: '가지급금 상세', + summaryCards: [ + { label: '가지급금', value: '4.5억원' }, + { label: '인정이자 4.6%', value: 6000000, unit: '원' }, + { label: '미정정', value: '10건' }, + ], + table: { + title: '가지급금 관련 내역', + columns: [...], + data: [...], + filters: [...], + showTotal: true, + }, + }, + + // cm3: 법인세 예상 가중 상세 + cm3: { + title: '법인세 예상 가중 상세', + summaryCards: [...], + comparisonSection: { + leftBox: { + title: '없을때 법인세', + items: [...], + borderColor: 'orange', + }, + rightBox: { + title: '있을때 법인세', + items: [...], + borderColor: 'blue', + }, + vsLabel: '법인세 예상 증가', + vsValue: 3123000, + }, + referenceTable: { + title: '법인세 과세표준 (2024년 기준)', + columns: [...], + data: [...], // 법인세율 참조 테이블 + }, + }, + + // cm4: 대표자 종합소득세 예상 가중 상세 + cm4: { + title: '대표자 종합소득세 예상 가중 상세', + summaryCards: [...], + comparisonSection: { + leftBox: { title: '가지급금 인정이자가 반영된 종합소득세', ... }, + rightBox: { title: '가지급금 인정이자가 정리된 종합소득세', ... }, + vsLabel: '종합소득세 예상 절감', + vsValue: 3123000, + vsBreakdown: [ // 세부 항목 + { label: '종합소득세', value: -2000000, unit: '원' }, + { label: '지방소득세', value: -200000, unit: '원' }, + { label: '4대 보험', value: -1000000, unit: '원' }, + ], + }, + referenceTable: { + title: '종합소득세 과세표준 (2024년 기준)', + columns: [...], + data: [...], // 종합소득세율 참조 테이블 + }, + }, + }; + + return configs[cardId] || null; +} +``` + +### 10.6 API 응답 타입 (현재) + +**파일**: `react/src/lib/api/dashboard/types.ts` + +```typescript +// CardTransaction API 응답 (현재 사용 중) +export interface CardTransactionApiResponse { + previous_month_total: number; // 전월 카드 사용액 + current_month_total: number; // 당월 카드 사용액 + total_count: number; // 총 건수 + total_amount: number; // 총 금액 +} +``` + +### 10.7 CEODashboard에서 CardManagement 사용 방식 + +**파일**: `react/src/components/business/CEODashboard/CEODashboard.tsx` (301-307행) + +```typescript +// 1. useCEODashboard Hook에서 데이터 로드 +const apiData = useCEODashboard({ + cardManagementFallback: mockData.cardManagement, // fallback 데이터 +}); + +// 2. API 데이터와 mockData 병합 +const data = useMemo(() => ({ + ...mockData, + cardManagement: apiData.cardManagement.data ?? mockData.cardManagement, +}), [apiData]); + +// 3. 카드 클릭 시 모달 표시 +const handleCardManagementCardClick = useCallback((cardId: string) => { + const config = getCardManagementModalConfig(cardId); // 하드코딩 데이터 + if (config) { + setDetailModalConfig(config); + setIsDetailModalOpen(true); + } +}, []); + +// 4. 섹션 렌더링 +{dashboardSettings.cardManagement && ( + +)} +``` + +--- + +## 11. 구현 시 참고사항 + +### 11.1 신규 API 개발 시 주의점 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 🔴 필수 준수 사항 │ +├─────────────────────────────────────────────────────────────────┤ +│ 1. BelongsToTenant 트레잇 사용 (멀티테넌시) │ +│ 2. FormRequest로 입력 검증 │ +│ 3. Swagger 문서 작성 (LoanApi.php 참조) │ +│ 4. 에러 응답 시 success: false, message: '...' 형식 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 11.2 Loan 모델 세금 계산 상수 + +**파일**: `api/app/Models/Tenants/Loan.php` + +```php +// 세금 계산 상수 (2024년 기준) +const CORPORATE_TAX_RATE = 0.19; // 법인세율 19% +const INCOME_TAX_RATE = 0.35; // 종합소득세율 35% +const LOCAL_TAX_RATE = 0.10; // 지방소득세율 10% +const DEFAULT_INTEREST_RATE = 4.6; // 인정이자율 4.6% +``` + +### 11.3 프론트엔드 파일 수정 순서 + +``` +1. react/src/lib/api/dashboard/types.ts + └─ 신규 API 응답 타입 추가 + +2. react/src/lib/api/dashboard/transformers.ts + └─ transformCardManagementResponse 수정 + +3. react/src/hooks/useCEODashboard.ts + └─ useCardManagement 훅 수정 (다중 API 호출) + +4. react/src/hooks/useCardManagementModals.ts (신규) + └─ 모달용 데이터 훅 생성 + +5. react/src/components/business/CEODashboard/modalConfigs/cardManagementConfigs.ts + └─ 하드코딩 → API 데이터 기반 동적 생성으로 변경 + +6. react/src/components/business/CEODashboard/CEODashboard.tsx + └─ 모달 열기 시 API 호출 연동 +``` + +--- + +## 12. 자기완결성 점검 결과 + +### 12.1 체크리스트 검증 + +| # | 검증 항목 | 상태 | 비고 | +|---|----------|:----:|------| +| 1 | 작업 목적이 명확한가? | ✅ | 4개 카드 + 모달 연동 | +| 2 | 성공 기준이 정의되어 있는가? | ✅ | 섹션 9.2 참조 | +| 3 | 작업 범위가 구체적인가? | ✅ | Phase 1~4 정의 | +| 4 | 의존성이 명시되어 있는가? | ✅ | 기존 API 현황 분석 | +| 5 | 참고 파일 경로가 정확한가? | ✅ | 섹션 7, 10 참조 | +| 6 | 단계별 절차가 실행 가능한가? | ✅ | 섹션 4, 11 상세 작업 | +| 7 | 검증 방법이 명시되어 있는가? | ✅ | 섹션 9.1 테스트 케이스 | +| 8 | 모호한 표현이 없는가? | ✅ | API 응답 구조 명시 | +| 9 | 기존 코드 스니펫이 포함되어 있는가? | ✅ | 섹션 10 참조 | +| 10 | 데이터 흐름이 명시되어 있는가? | ✅ | 섹션 10.1 다이어그램 | + +### 12.2 새 세션 시뮬레이션 테스트 + +| 질문 | 답변 가능 | 참조 섹션 | +|------|:--------:|----------| +| Q1. 이 작업의 목적은 무엇인가? | ✅ | 1.1 배경 | +| Q2. 어디서부터 시작해야 하는가? | ✅ | 3.1 Phase 1 | +| Q3. 어떤 파일을 수정해야 하는가? | ✅ | 4. 상세 작업, 11.3 순서 | +| Q4. 작업 완료 확인 방법은? | ✅ | 9. 검증 결과 | +| Q5. 막혔을 때 참고 문서는? | ✅ | 7. 참고 문서 | +| Q6. 현재 코드 구조는 어떻게 되어 있는가? | ✅ | 10. 코드 스니펫 | +| Q7. 데이터가 어떻게 흐르는가? | ✅ | 10.1 다이어그램 | + +**결과**: 7/7 통과 → ✅ 자기완결성 확보 + +### 12.3 보완 이력 + +| 날짜 | 항목 | 원본 | 보완 내용 | +|------|------|------|----------| +| 2026-01-22 | 문서 초안 | - | 초기 계획 작성 | +| 2026-01-22 | 코드 스니펫 | 누락 | 섹션 10 추가: transformers, hooks, types, configs | +| 2026-01-22 | 데이터 흐름 | 누락 | 섹션 10.1 다이어그램 추가 | +| 2026-01-22 | 구현 순서 | 모호함 | 섹션 11.3 파일 수정 순서 명시 | + +--- + +*이 문서는 /plan 스킬로 생성되었습니다.* \ No newline at end of file