# 경조사비 대시보드 연동

**날짜:** 2026-03-19
**작업자:** Claude Code

---

## 변경 개요

CEO 대시보드의 가지급금 현황 API(`GET /api/v1/loans/dashboard`)에 경조사비(`condolence_expenses` 테이블) 요약 데이터를 추가했다.

### 배경

- 경조사비 관리 페이지(`condolence_expenses`)에서 등록한 데이터가 대시보드 가지급금 "경조사" 항목에 반영되지 않는 문제
- `loans` 테이블의 `category=congratulatory`(가지급금)와 `condolence_expenses` 테이블(직접 지출)은 데이터 성격이 다름
- **방안 B(별도 항목 추가)** 채택 — 데이터 출처를 명확히 분리

### 방안 선택 근거

| 방안 | 설명 | 채택 여부 |
|------|------|----------|
| A. 합산 | loans + condolence_expenses 합산 | 금액 의미 모호 |
| **B. 별도 항목** | **condolence_summary 필드 추가** | **채택** |
| C. 자동 생성 | condolence → loans 자동 삽입 | 결합도 과도 |
| D. 현행 유지 | 변경 없음 | 사용자 혼란 지속 |

---

## 수정된 파일

| 파일 | 변경 내용 |
|------|----------|
| `api/app/Services/LoanService.php` | `dashboard()` 메서드에 `condolence_expenses` 요약 쿼리 추가, 응답에 `condolence_summary` 포함 |

---

## 상세 변경 사항

### API 응답 변경

`GET /api/v1/loans/dashboard` 응답에 `condolence_summary` 필드 추가:

```json
{
    "summary": {
        "total_outstanding": 5000000,
        "recognized_interest": 23000,
        "outstanding_count": 3
    },
    "category_breakdown": {
        "card": { "outstanding_amount": 1150000, "total_count": 5, "unverified_count": 1 },
        "congratulatory": { "outstanding_amount": 300000, "total_count": 2, "unverified_count": 0 },
        "gift_certificate": { "outstanding_amount": 500000, "total_count": 3, "unverified_count": 0 },
        "entertainment": { "outstanding_amount": 450000, "total_count": 2, "unverified_count": 0 }
    },
    "condolence_summary": {
        "total_count": 5,
        "total_amount": 150000,
        "congratulation_amount": 100000,
        "condolence_amount": 50000
    },
    "loans": [...]
}
```

### 필드 설명

| 필드 | 타입 | 설명 |
|------|------|------|
| `condolence_summary.total_count` | `int` | 경조사비 총 건수 |
| `condolence_summary.total_amount` | `int` | 경조사비 총 금액 (원) |
| `condolence_summary.congratulation_amount` | `int` | 축의금 합계 |
| `condolence_summary.condolence_amount` | `int` | 부조금 합계 |

### 날짜 필터

- 기존 `category_breakdown`: `loan_date` 기준
- 신규 `condolence_summary`: `event_date` 기준
- 대시보드의 `start_date`, `end_date` 파라미터가 동일하게 적용됨

---

## 구현 방식

```
LoanService::dashboard()
├── 1. Summary (loans 미정산 집계)
├── 2. 인정이자 계산
├── 3. getCategoryBreakdown() — loans 4개 카테고리
├── 4. condolence_expenses 요약 쿼리 (신규)  ← 추가
└── 5. 가지급금 목록 (최대 50건)
```

`CondolenceExpense` 모델을 직접 조회하여 서비스 간 결합을 피함 (기존 패턴과 동일).

---

## FE 작업 필요 사항

- `CardManagementSection` 컴포넌트에 경조사비 카드 1개 추가 (기존 4개 → 5개)
- `expense.ts` transformer에 `condolence_summary` 매핑 추가
- 별도 FE 전달 문서 참조: `frontend/api-specs/condolence-dashboard-fe-request.md`

---

## 테스트 체크리스트

- [x] API 코드 수정 완료
- [x] Pint 포맷팅 적용
- [x] 개발서버 푸시 완료
- [ ] FE 경조사비 카드 추가 (React 작업 필요)

---

## 관련 문서

- [경조사비 서비스 이관 기획](../dev/dev_plans/condolence-expense-service-plan.md)
- [경조사비 API 명세](../frontend/api-specs/condolence-expense-api.md)

---

**최종 업데이트**: 2026-03-19