권혁성
db63fcff85
- 개발팀 전용 폴더 dev/ 생성 (standards, guides, quickstart, changes, deploys, data, history, dev_plans 이동) - 프론트엔드 전용 폴더 frontend/ 생성 (api/ → frontend/api-specs/) - 기획팀 폴더 requests/ 생성 - plans/ → dev/dev_plans/ 이름 변경 - README.md 신규 (사람용 안내), INDEX.md 재작성 (Claude Code용) - resources.md 신규 (노션 링크용, assets/brochure 이관 예정) - CURRENT_WORKS.md 삭제, TODO.md → dev/ 이동 - 전체 참조 경로 업데이트 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
824 lines
30 KiB
Markdown
824 lines
30 KiB
Markdown
# 카드/가지급금 관리 섹션 데이터 연동 계획
|
|
|
|
> **작성일**: 2026-01-22
|
|
> **목적**: CEO 대시보드 카드/가지급금 관리 섹션의 4개 카드 데이터 연동 및 모달 팝업 내용 개발
|
|
> **기준 문서**: `cardManagementConfigs.ts`, `LoanApi.php`, `CardTransactionApi.php`
|
|
> **상태**: 🔄 진행중 (Serena ID: card-management-plan-state)
|
|
|
|
---
|
|
|
|
## 📍 현재 진행 상태
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| **마지막 완료 작업** | Phase 2.3 모달 데이터 훅 생성 완료 |
|
|
| **다음 작업** | Phase 3.1 cm1 카드 모달 데이터 연동 |
|
|
| **진행률** | 6/12 (50%) |
|
|
| **마지막 업데이트** | 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<void>;
|
|
}
|
|
```
|
|
|
|
### 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 프로젝트 | ✅ |
|
|
| 4 | 프론트엔드 타입/API | 타입, 엔드포인트, 훅 추가 | React 프로젝트 | ✅ |
|
|
|
|
---
|
|
|
|
## 6. 변경 이력
|
|
|
|
| 날짜 | 항목 | 변경 내용 | 파일 | 승인 |
|
|
|------|------|----------|------|------|
|
|
| 2026-01-22 | Phase 2 | 프론트엔드 타입, 엔드포인트, 훅 완료 | types.ts, endpoints.ts, useCardManagementModals.ts | ✅ |
|
|
| 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 | - | 문서 초안 작성 | - | - |
|
|
|
|
---
|
|
|
|
## 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<CardManagementData | null>(null);
|
|
const [loading, setLoading] = useState(true);
|
|
const [error, setError] = useState<string | null>(null);
|
|
|
|
const fetchData = useCallback(async () => {
|
|
try {
|
|
setLoading(true);
|
|
setError(null);
|
|
|
|
// 현재: card-transactions/summary만 호출
|
|
const apiData = await fetchApi<CardTransactionApiResponse>(
|
|
'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<string, DetailModalConfig> = {
|
|
// 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<CEODashboardData>(() => ({
|
|
...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 && (
|
|
<CardManagementSection
|
|
data={data.cardManagement}
|
|
onCardClick={handleCardManagementCardClick}
|
|
/>
|
|
)}
|
|
```
|
|
|
|
---
|
|
|
|
## 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 스킬로 생성되었습니다.* |