sam-docs/frontend/api-specs/condolence-dashboard-fe-request.md

경조사비 대시보드 연동 — FE 구현 요청

작성일: 2026-03-19 상태: API 완료, FE 작업 필요 요청자: 백엔드 대상: FE 개발팀

---

1. 개요

1.1 배경

CEO 대시보드의 가지급금 현황 API에 경조사비 요약 데이터가 추가되었다.

기존 category_breakdown의 4개 카테고리(카드/경조사/상품권/접대비)와 별개로, condolence_expenses 테이블의 경조사비 직접 지출 데이터를 condolence_summary 필드로 제공한다.

1.2 왜 별도 필드인가

구분	category_breakdown.congratulatory	condolence_summary
테이블	loans	condolence_expenses
성격	가지급금 (선지급 → 정산 대기)	직접 지출 (확정 비용)
금액 의미	미정산 잔액	지출 총액

두 데이터는 성격이 다르므로 합산하지 않고 별도 카드로 표시한다.

---

2. API 변경 사항

2.1 엔드포인트

GET /api/v1/loans/dashboard?start_date=2026-01-01&end_date=2026-12-31

기존 엔드포인트 동일. 응답에 condolence_summary 필드가 추가됨.

2.2 응답 구조 (변경 부분만)

interface LoanDashboardResponse {
    summary: { ... };               // 기존 동일
    category_breakdown: { ... };    // 기존 동일
    condolence_summary: {           // ✅ 신규 추가
        total_count: number;              // 경조사비 총 건수
        total_amount: number;             // 경조사비 총 금액 (원)
        congratulation_amount: number;    // 축의금 합계
        condolence_amount: number;        // 부조금 합계
    };
    loans: Array<...>;              // 기존 동일
}

2.3 날짜 필터

• condolence_summary는 event_date(경조사 행사일) 기준으로 필터된다
• 대시보드의 start_date, end_date 파라미터가 동일하게 적용됨

---

3. FE 구현 요청 사항

3.1 경조사비 카드 추가

CardManagementSection 컴포넌트에 경조사비 카드 1개를 추가한다.

위치: 기존 4개 카드(카드/경조사/상품권/접대비) 다음 또는 적절한 위치

카드 표시 내용 (예시):

┌──────────────────────┐
│  경조사비              │
│  ₩150,000     5건    │
│                      │
│  축의  ₩100,000      │
│  부조   ₩50,000      │
└──────────────────────┘

3.2 데이터 매핑

화면 항목	API 필드
카드 제목	"경조사비" (하드코딩)
금액	condolence_summary.total_amount
건수	condolence_summary.total_count
축의 금액	condolence_summary.congratulation_amount
부조 금액	condolence_summary.condolence_amount

3.3 수정 대상 파일 (참고)

파일	수정 내용
src/hooks/useCEODashboard.ts	condolence_summary 타입 추가 (이미 fetch하는 응답에 포함됨)
src/lib/api/dashboard/transformers/expense.ts	condolence_summary 변환 로직 추가
src/components/business/CEODashboard/sections/CardManagementSection.tsx	경조사비 카드 UI 추가

---

4. 참고

• 경조사비 데이터가 0건이면 카드에 0원/0건으로 표시하면 된다 (숨김 불필요)
• category_breakdown.congratulatory(가지급금 경조사)와 condolence_summary(경조사비 지출)는 별개 항목이다

---

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