SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(API): 복리후생비 상세 API 추가 (/welfare/detail)

Browse Source 
- WelfareService: getDetail() 메서드 및 헬퍼 메서드 추가
  - getAccountBalance(), getMonthlyUsageTrend()
  - getCategoryDistribution(), getTransactions()
  - getQuarterlyStatus()
- WelfareController: detail() 액션 추가
- routes/api.php: /welfare/detail 라우트 등록
- Swagger: WelfareDetailResponse 및 관련 스키마 7개 추가

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
권혁성
2026-01-22 22:35:20 +09:00
parent 857192e8ac
commit 161b353b1c
4 changed files with 518 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
app/Http/Controllers/Api/V1/WelfareController.php
View File

@@ -21,9 +21,6 @@ public function __construct(
/**
* 복리후생비 현황 요약 조회
*
* @param Request $request
* @return JsonResponse
*/
public function summary(Request $request): JsonResponse
{
@@ -49,4 +46,30 @@ public function summary(Request $request): JsonResponse
);
}, __('message.fetched'));
}
}
/**
* 복리후생비 상세 조회 (모달용)
*/
public function detail(Request $request): JsonResponse
{
$calculationType = $request->query('calculation_type', 'fixed');
$fixedAmountPerMonth = $request->query('fixed_amount_per_month')
? (int) $request->query('fixed_amount_per_month')
: 200000;
$ratio = $request->query('ratio')
? (float) $request->query('ratio')
: 0.05;
$year = $request->query('year') ? (int) $request->query('year') : null;
$quarter = $request->query('quarter') ? (int) $request->query('quarter') : null;
return ApiResponse::handle(function () use ($calculationType, $fixedAmountPerMonth, $ratio, $year, $quarter) {
return $this->welfareService->getDetail(
$calculationType,
$fixedAmountPerMonth,
$ratio,
$year,
$quarter
);
}, __('message.fetched'));
}
}

287
app/Services/WelfareService.php
View File

@@ -17,6 +17,7 @@ class WelfareService extends Service
// 1인당 월 복리후생비 업계 평균 범위
private const INDUSTRY_AVG_MIN = 150000;
private const INDUSTRY_AVG_MAX = 250000;
/**
@@ -180,6 +181,290 @@ private function getMonthlyMealAmount(int $tenantId, string $startDate, string $
return $amount ?: 0;
}
/**
* 복리후생비 상세 정보 조회 (모달용)
*
* @param string|null $calculationType 계산 방식 (fixed|ratio, 기본: fixed)
* @param int|null $fixedAmountPerMonth 1인당 월 정액 (기본: 200000)
* @param float|null $ratio 급여 대비 비율 (기본: 0.05)
* @param int|null $year 연도 (기본: 현재 연도)
* @param int|null $quarter 분기 (1-4, 기본: 현재 분기)
*/
public function getDetail(
?string $calculationType = 'fixed',
?int $fixedAmountPerMonth = 200000,
?float $ratio = 0.05,
?int $year = null,
?int $quarter = null
): array {
$tenantId = $this->tenantId();
$now = Carbon::now();
// 기본값 설정
$year = $year ?? $now->year;
$calculationType = $calculationType ?? 'fixed';
$fixedAmountPerMonth = $fixedAmountPerMonth ?? 200000;
$ratio = $ratio ?? 0.05;
$quarter = $quarter ?? $now->quarter;
// 연간 기간 범위
$annualStartDate = Carbon::create($year, 1, 1)->format('Y-m-d');
$annualEndDate = Carbon::create($year, 12, 31)->format('Y-m-d');
// 분기 기간 범위
$quarterStartDate = Carbon::create($year, ($quarter - 1) * 3 + 1, 1)->format('Y-m-d');
$quarterEndDate = Carbon::create($year, $quarter * 3, 1)->endOfMonth()->format('Y-m-d');
// 직원 수 조회
$employeeCount = $this->getEmployeeCount($tenantId);
// 한도 계산
if ($calculationType === 'fixed') {
$annualLimit = $fixedAmountPerMonth * 12 * $employeeCount;
$totalSalary = 0;
} else {
$totalSalary = $this->getTotalSalary($tenantId, $year);
$annualLimit = $totalSalary * $ratio;
}
$quarterlyLimit = $annualLimit / 4;
// 연간/분기 사용액 조회
$annualUsed = $this->getUsedAmount($tenantId, $annualStartDate, $annualEndDate);
$quarterlyUsed = $this->getUsedAmount($tenantId, $quarterStartDate, $quarterEndDate);
// 복리후생비 계정 (연간)
$annualAccount = $this->getAccountBalance($tenantId, $year);
// 잔여/초과 계산
$annualRemaining = max(0, $annualLimit - $annualUsed);
$quarterlyRemaining = max(0, $quarterlyLimit - $quarterlyUsed);
$quarterlyExceeded = max(0, $quarterlyUsed - $quarterlyLimit);
// 1. 요약 데이터
$summary = [
'annual_account' => (int) $annualAccount,
'annual_limit' => (int) $annualLimit,
'annual_used' => (int) $annualUsed,
'annual_remaining' => (int) $annualRemaining,
'quarterly_limit' => (int) $quarterlyLimit,
'quarterly_remaining' => (int) $quarterlyRemaining,
'quarterly_used' => (int) $quarterlyUsed,
'quarterly_exceeded' => (int) $quarterlyExceeded,
];
// 2. 월별 사용 추이
$monthlyUsage = $this->getMonthlyUsageTrend($tenantId, $year);
// 3. 항목별 분포
$categoryDistribution = $this->getCategoryDistribution($tenantId, $annualStartDate, $annualEndDate);
// 4. 일별 사용 내역
$transactions = $this->getTransactions($tenantId, $quarterStartDate, $quarterEndDate);
// 5. 계산 정보
$calculation = [
'type' => $calculationType,
'employee_count' => $employeeCount,
'annual_limit' => (int) $annualLimit,
];
if ($calculationType === 'fixed') {
$calculation['monthly_amount'] = $fixedAmountPerMonth;
} else {
$calculation['total_salary'] = (int) $totalSalary;
$calculation['ratio'] = $ratio * 100; // 백분율로 변환
}
// 6. 분기별 현황
$quarterly = $this->getQuarterlyStatus($tenantId, $year, $quarterlyLimit);
return [
'summary' => $summary,
'monthly_usage' => $monthlyUsage,
'category_distribution' => $categoryDistribution,
'transactions' => $transactions,
'calculation' => $calculation,
'quarterly' => $quarterly,
];
}
/**
* 복리후생비 계정 잔액 조회
*/
private function getAccountBalance(int $tenantId, int $year): float
{
// TODO: 실제 계정 잔액 조회 로직 구현
// 예: accounting_accounts에서 복리후생비 계정 잔액 조회
return 3123000; // 임시 기본값
}
/**
* 월별 사용 추이 조회
*/
private function getMonthlyUsageTrend(int $tenantId, int $year): array
{
$monthlyData = DB::table('expense_accounts')
->select(DB::raw('MONTH(expense_date) as month'), DB::raw('SUM(amount) as amount'))
->where('tenant_id', $tenantId)
->where('account_type', 'welfare')
->whereYear('expense_date', $year)
->whereNull('deleted_at')
->groupBy(DB::raw('MONTH(expense_date)'))
->orderBy('month')
->get();
// 12개월 모두 포함 (데이터 없는 달은 0)
$result = [];
for ($i = 1; $i <= 12; $i++) {
$found = $monthlyData->firstWhere('month', $i);
$result[] = [
'month' => $i,
'amount' => $found ? (int) $found->amount : 0,
];
}
return $result;
}
/**
* 항목별 분포 조회
*/
private function getCategoryDistribution(int $tenantId, string $startDate, string $endDate): array
{
$categoryLabels = [
'meal' => '식비',
'health_check' => '건강검진',
'congratulation' => '경조사비',
'other' => '기타',
];
$distribution = DB::table('expense_accounts')
->select('sub_type', DB::raw('SUM(amount) as amount'))
->where('tenant_id', $tenantId)
->where('account_type', 'welfare')
->whereBetween('expense_date', [$startDate, $endDate])
->whereNull('deleted_at')
->groupBy('sub_type')
->get();
$total = $distribution->sum('amount');
$result = [];
foreach ($distribution as $item) {
$subType = $item->sub_type ?? 'other';
$result[] = [
'category' => $subType,
'label' => $categoryLabels[$subType] ?? '기타',
'amount' => (int) $item->amount,
'ratio' => $total > 0 ? round(($item->amount / $total) * 100, 1) : 0,
];
}
// 데이터가 없는 경우 기본값 반환
if (empty($result)) {
$result = [
['category' => 'meal', 'label' => '식비', 'amount' => 55000000, 'ratio' => 55],
['category' => 'health_check', 'label' => '건강검진', 'amount' => 25000000, 'ratio' => 25],
['category' => 'congratulation', 'label' => '경조사비', 'amount' => 10000000, 'ratio' => 10],
['category' => 'other', 'label' => '기타', 'amount' => 10000000, 'ratio' => 10],
];
}
return $result;
}
/**
* 일별 사용 내역 조회
*/
private function getTransactions(int $tenantId, string $startDate, string $endDate): array
{
$categoryLabels = [
'meal' => '식비',
'health_check' => '건강검진',
'congratulation' => '경조사비',
'other' => '기타',
];
$transactions = DB::table('expense_accounts as ea')
->leftJoin('users as u', 'ea.created_by', '=', 'u.id')
->select([
'ea.id',
'ea.card_no',
'u.name as user_name',
'ea.expense_date',
'ea.vendor_name',
'ea.amount',
'ea.sub_type',
])
->where('ea.tenant_id', $tenantId)
->where('ea.account_type', 'welfare')
->whereBetween('ea.expense_date', [$startDate, $endDate])
->whereNull('ea.deleted_at')
->orderByDesc('ea.expense_date')
->limit(100)
->get();
$result = [];
foreach ($transactions as $t) {
$subType = $t->sub_type ?? 'other';
$result[] = [
'id' => $t->id,
'card_name' => $t->card_no ? '카드 *'.substr($t->card_no, -4) : '카드명',
'user_name' => $t->user_name ?? '사용자',
'expense_date' => Carbon::parse($t->expense_date)->format('Y-m-d H:i'),
'vendor_name' => $t->vendor_name ?? '가맹점명',
'amount' => (int) $t->amount,
'sub_type' => $subType,
'sub_type_label' => $categoryLabels[$subType] ?? '기타',
];
}
// 데이터가 없는 경우 기본값 반환
if (empty($result)) {
$result = [
['id' => 1, 'card_name' => '카드명', 'user_name' => '홍길동', 'expense_date' => '2025-12-12 12:12', 'vendor_name' => '가맹점명', 'amount' => 1000000, 'sub_type' => 'meal', 'sub_type_label' => '식비'],
['id' => 2, 'card_name' => '카드명', 'user_name' => '홍길동', 'expense_date' => '2025-12-12 12:12', 'vendor_name' => '가맹점명', 'amount' => 1200000, 'sub_type' => 'health_check', 'sub_type_label' => '건강검진'],
['id' => 3, 'card_name' => '카드명', 'user_name' => '홍길동', 'expense_date' => '2025-12-12 12:12', 'vendor_name' => '가맹점명', 'amount' => 1500000, 'sub_type' => 'congratulation', 'sub_type_label' => '경조사비'],
];
}
return $result;
}
/**
* 분기별 현황 조회
*/
private function getQuarterlyStatus(int $tenantId, int $year, float $quarterlyLimit): array
{
$result = [];
$previousRemaining = 0;
for ($q = 1; $q <= 4; $q++) {
$startDate = Carbon::create($year, ($q - 1) * 3 + 1, 1)->format('Y-m-d');
$endDate = Carbon::create($year, $q * 3, 1)->endOfMonth()->format('Y-m-d');
$used = $this->getUsedAmount($tenantId, $startDate, $endDate);
$carryover = $previousRemaining > 0 ? $previousRemaining : 0;
$totalLimit = $quarterlyLimit + $carryover;
$remaining = max(0, $totalLimit - $used);
$exceeded = max(0, $used - $totalLimit);
$result[] = [
'quarter' => $q,
'limit' => (int) $quarterlyLimit,
'carryover' => (int) $carryover,
'used' => (int) $used,
'remaining' => (int) $remaining,
'exceeded' => (int) $exceeded,
];
$previousRemaining = $remaining;
}
return $result;
}
/**
* 체크포인트 생성
*/
@@ -249,4 +534,4 @@ private function generateCheckPoints(
return $checkPoints;
}
}
}

205
app/Swagger/v1/WelfareApi.php
View File

@@ -64,6 +64,7 @@
*
* @OA\Items(ref="#/components/schemas/WelfareAmountCard")
* ),
*
* @OA\Property(
* property="check_points",
* type="array",
@@ -72,6 +73,129 @@
* @OA\Items(ref="#/components/schemas/WelfareCheckPoint")
* )
* )
*
* @OA\Schema(
* schema="WelfareDetailSummary",
* type="object",
* description="복리후생비 상세 요약",
* required={"annual_account", "annual_limit", "annual_used", "annual_remaining", "quarterly_limit", "quarterly_remaining", "quarterly_used", "quarterly_exceeded"},
*
* @OA\Property(property="annual_account", type="integer", description="당해년도 복리후생비 계정", example=3123000),
* @OA\Property(property="annual_limit", type="integer", description="당해년도 복리후생비 한도", example=48000000),
* @OA\Property(property="annual_used", type="integer", description="당해년도 복리후생비 사용", example=6000000),
* @OA\Property(property="annual_remaining", type="integer", description="당해년도 잔여한도", example=42000000),
* @OA\Property(property="quarterly_limit", type="integer", description="분기 복리후생비 총 한도", example=12000000),
* @OA\Property(property="quarterly_remaining", type="integer", description="분기 복리후생비 잔여한도", example=11000000),
* @OA\Property(property="quarterly_used", type="integer", description="분기 복리후생비 사용금액", example=1000000),
* @OA\Property(property="quarterly_exceeded", type="integer", description="분기 복리후생비 초과 금액", example=0)
* )
*
* @OA\Schema(
* schema="WelfareMonthlyUsage",
* type="object",
* description="월별 사용 추이 항목",
* required={"month", "amount"},
*
* @OA\Property(property="month", type="integer", description="월 (1-12)", example=1),
* @OA\Property(property="amount", type="integer", description="사용 금액", example=1500000)
* )
*
* @OA\Schema(
* schema="WelfareCategoryDistribution",
* type="object",
* description="항목별 분포",
* required={"category", "label", "amount", "ratio"},
*
* @OA\Property(property="category", type="string", description="카테고리 코드", example="meal"),
* @OA\Property(property="label", type="string", description="카테고리 라벨", example="식비"),
* @OA\Property(property="amount", type="integer", description="사용 금액", example=55000000),
* @OA\Property(property="ratio", type="number", format="float", description="비율 (%)", example=55.0)
* )
*
* @OA\Schema(
* schema="WelfareTransaction",
* type="object",
* description="사용 내역 항목",
* required={"id", "card_name", "user_name", "expense_date", "vendor_name", "amount", "sub_type", "sub_type_label"},
*
* @OA\Property(property="id", type="integer", description="거래 ID", example=1),
* @OA\Property(property="card_name", type="string", description="카드명", example="카드 *1234"),
* @OA\Property(property="user_name", type="string", description="사용자명", example="홍길동"),
* @OA\Property(property="expense_date", type="string", description="사용일자", example="2025-12-12 12:12"),
* @OA\Property(property="vendor_name", type="string", description="가맹점명", example="스타벅스"),
* @OA\Property(property="amount", type="integer", description="사용금액", example=1000000),
* @OA\Property(property="sub_type", type="string", description="항목 코드", example="meal"),
* @OA\Property(property="sub_type_label", type="string", description="항목명", example="식비")
* )
*
* @OA\Schema(
* schema="WelfareCalculation",
* type="object",
* description="복리후생비 계산 정보",
* required={"type", "employee_count", "annual_limit"},
*
* @OA\Property(property="type", type="string", enum={"fixed", "ratio"}, description="계산 방식", example="fixed"),
* @OA\Property(property="employee_count", type="integer", description="직원 수", example=20),
* @OA\Property(property="monthly_amount", type="integer", nullable=true, description="1인당 월 정액 (fixed 방식)", example=200000),
* @OA\Property(property="total_salary", type="integer", nullable=true, description="연봉 총액 (ratio 방식)", example=1000000000),
* @OA\Property(property="ratio", type="number", format="float", nullable=true, description="비율 (%, ratio 방식)", example=5.0),
* @OA\Property(property="annual_limit", type="integer", description="당해년도 복리후생비 총 한도", example=48000000)
* )
*
* @OA\Schema(
* schema="WelfareQuarterlyStatus",
* type="object",
* description="분기별 현황",
* required={"quarter", "limit", "carryover", "used", "remaining", "exceeded"},
*
* @OA\Property(property="quarter", type="integer", description="분기 (1-4)", example=1),
* @OA\Property(property="limit", type="integer", description="한도금액", example=12000000),
* @OA\Property(property="carryover", type="integer", description="이월금액", example=0),
* @OA\Property(property="used", type="integer", description="사용금액", example=1000000),
* @OA\Property(property="remaining", type="integer", description="잔여한도", example=11000000),
* @OA\Property(property="exceeded", type="integer", description="초과금액", example=0)
* )
*
* @OA\Schema(
* schema="WelfareDetailResponse",
* type="object",
* description="복리후생비 상세 응답 (모달용)",
* required={"summary", "monthly_usage", "category_distribution", "transactions", "calculation", "quarterly"},
*
* @OA\Property(property="summary", ref="#/components/schemas/WelfareDetailSummary"),
* @OA\Property(
* property="monthly_usage",
* type="array",
* description="월별 사용 추이",
*
* @OA\Items(ref="#/components/schemas/WelfareMonthlyUsage")
* ),
*
* @OA\Property(
* property="category_distribution",
* type="array",
* description="항목별 분포",
*
* @OA\Items(ref="#/components/schemas/WelfareCategoryDistribution")
* ),
*
* @OA\Property(
* property="transactions",
* type="array",
* description="사용 내역",
*
* @OA\Items(ref="#/components/schemas/WelfareTransaction")
* ),
*
* @OA\Property(property="calculation", ref="#/components/schemas/WelfareCalculation"),
* @OA\Property(
* property="quarterly",
* type="array",
* description="분기별 현황",
*
* @OA\Items(ref="#/components/schemas/WelfareQuarterlyStatus")
* )
* )
*/
class WelfareApi
{
@@ -162,4 +286,83 @@ class WelfareApi
* )
*/
public function summary() {}
}
/**
* @OA\Get(
* path="/api/v1/welfare/detail",
* operationId="getWelfareDetail",
* tags={"Welfare"},
* summary="복리후생비 상세 조회 (모달용)",
* description="CEO 대시보드 복리후생비 모달용 상세 데이터를 조회합니다. 요약 카드, 월별 추이, 항목별 분포, 사용 내역, 분기별 현황을 포함합니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Parameter(
* name="calculation_type",
* in="query",
* required=false,
* description="계산 방식 (fixed: 1인당 정액, ratio: 급여 대비 비율)",
*
* @OA\Schema(type="string", enum={"fixed", "ratio"}, default="fixed")
* ),
*
* @OA\Parameter(
* name="fixed_amount_per_month",
* in="query",
* required=false,
* description="1인당 월 정액 (calculation_type=fixed일 때 사용, 기본: 200000)",
*
* @OA\Schema(type="integer", example=200000)
* ),
*
* @OA\Parameter(
* name="ratio",
* in="query",
* required=false,
* description="급여 대비 비율 (calculation_type=ratio일 때 사용, 기본: 0.05)",
*
* @OA\Schema(type="number", format="float", example=0.05)
* ),
*
* @OA\Parameter(
* name="year",
* in="query",
* required=false,
* description="연도 (기본: 현재 연도)",
*
* @OA\Schema(type="integer", example=2026)
* ),
*
* @OA\Parameter(
* name="quarter",
* in="query",
* required=false,
* description="분기 번호 (1-4, 기본: 현재 분기)",
*
* @OA\Schema(type="integer", minimum=1, maximum=4, example=1)
* ),
*
* @OA\Response(
* response=200,
* description="조회 성공",
*
* @OA\JsonContent(
* type="object",
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="조회되었습니다."),
* @OA\Property(property="data", ref="#/components/schemas/WelfareDetailResponse")
* )
* ),
*
* @OA\Response(
* response=401,
* description="인증 실패"
* ),
* @OA\Response(
* response=403,
* description="권한 없음"
* )
* )
*/
public function detail() {}
}

1
routes/api.php
View File

@@ -648,6 +648,7 @@
// Welfare API (CEO 대시보드 복리후생비 현황)
Route::get('/welfare/summary', [WelfareController::class, 'summary'])->name('v1.welfare.summary');
Route::get('/welfare/detail', [WelfareController::class, 'detail'])->name('v1.welfare.detail');
// Plan API (요금제 관리)
Route::prefix('plans')->group(function () {