Files

김보곤 ba0f231813 docs: [loan] 경조사비 대시보드 연동 변경이력 및 FE 요청 문서 추가

- 변경이력: condolence_summary 필드 추가 배경, API 응답 구조
- FE 요청: CardManagementSection 경조사비 카드 추가 가이드

2026-03-19 17:20:43 +09:00

3.8 KiB

Raw Blame History

경조사비 대시보드 연동

날짜: 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 필드 추가:

{
    "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

테스트 체크리스트

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

3.8 KiB Raw Blame History