123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
|
# 경조사비 대시보드 연동
|
||
|
|
|
||
|
|
**날짜:** 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
|