sam-docs/features/finance/fund-schedules.md

자금계획일정

개요

자금계획일정은 입금 예정/지급 예정 일정을 등록, 관리하고 월별 캘린더 뷰로 확인하는 기능입니다. 반복 일정, 월별 복사, 상태 관리(예정/완료/취소) 기능을 지원합니다.

• 라우트: GET /finance/fund-schedules
• 라우트 이름: finance.fund-schedules.index
• UI 기술: Blade 템플릿

파일 구조

mng/
├── app/Http/Controllers/
│   ├── Finance/
│   │   └── FundScheduleController.php           # 웹 컨트롤러 (5개 메서드)
│   └── Api/Admin/
│       └── FundScheduleController.php           # API 컨트롤러
├── app/Services/
│   └── FundScheduleService.php                  # 비즈니스 로직 (13개+ 공개 메서드)
├── app/Models/Finance/
│   └── FundSchedule.php                         # ORM 모델
└── resources/views/finance/fund-schedules/
    ├── index.blade.php                          # 캘린더 뷰
    ├── create.blade.php                         # 등록 폼
    ├── edit.blade.php                           # 수정 폼
    └── show.blade.php                           # 상세보기

라우트

웹 라우트

// routes/web.php (finance prefix 그룹 내)
Route::get('/fund-schedules', [FundScheduleController::class, 'index'])->name('fund-schedules.index');
Route::get('/fund-schedules/create', [..., 'create'])->name('fund-schedules.create');
Route::get('/fund-schedules/{id}', [..., 'show'])->name('fund-schedules.show');
Route::get('/fund-schedules/{id}/edit', [..., 'edit'])->name('fund-schedules.edit');

// 호환성 리다이렉트
Route::get('/fund-schedule', fn() => redirect()->route('finance.fund-schedules.index'));

API 라우트

// routes/api.php (admin/fund-schedules prefix)
GET    /                → index()      목록 (페이지네이션)
GET    /calendar        → calendar()   월별 캘린더 데이터
GET    /summary         → summary()    요약 통계
GET    /upcoming        → upcoming()   예정 일정
POST   /copy            → copy()       월별 일정 복사
GET    /{id}            → show()       상세 조회
POST   /                → store()      생성
PUT    /{id}            → update()     수정
DELETE /{id}            → destroy()    삭제

컨트롤러

FundScheduleController (웹)

메서드	설명	데이터 흐름
index()	캘린더 뷰	year, month → getCalendarData() → getMonthlySummary() → View
create()	등록 폼	계좌 목록, 타입/상태/반복 옵션 → View
edit(id)	수정 폼	ID로 일정 조회 → View
show(id)	상세보기	ID로 일정 조회 → View

서비스 클래스

FundScheduleService

메서드	매개변수	설명
getSchedules()	filters, perPage	필터링 목록 (페이지네이션)
getSchedulesForMonth()	year, month	월별 일정 조회
getSchedulesForDate()	date	특정 날짜 일정
getUpcomingSchedules()	days=30	향후 N일 예정 일정
getScheduleById()	id, withTrashed	단일 조회
createSchedule()	data	생성 (tenant_id, created_by 자동)
updateSchedule()	schedule, data	수정 (updated_by 자동)
deleteSchedule()	schedule	Soft Delete
restoreSchedule()	schedule	복원
forceDeleteSchedule()	schedule	영구 삭제
markAsCompleted()	schedule, amount, date	완료 처리
markAsCancelled()	schedule	취소 처리
copySchedulesToMonth()	src→tgt year/month	월별 일정 복사 (말일 처리)
bulkDelete()	ids	일괄 삭제
bulkUpdateStatus()	ids, status	일괄 상태 변경
getMonthlySummary()	year, month	월별 요약
getCalendarData()	year, month	캘린더용 날짜별 그룹핑
getSummary()	-	전체 요약

모델

FundSchedule

테이블: fund_schedules

상수 정의

// 일정 유형
TYPE_INCOME = 'income'       // 입금 예정
TYPE_EXPENSE = 'expense'     // 지급 예정

// 상태
STATUS_PENDING = 'pending'       // 예정
STATUS_COMPLETED = 'completed'   // 완료
STATUS_CANCELLED = 'cancelled'   // 취소

// 반복 규칙
RECURRENCE_DAILY = 'daily'
RECURRENCE_WEEKLY = 'weekly'
RECURRENCE_MONTHLY = 'monthly'
RECURRENCE_YEARLY = 'yearly'

주요 필드

필드	타입	설명
tenant_id	bigint	테넌트 ID
title	string	일정 제목
description	text	설명
schedule_type	enum	income / expense
scheduled_date	date	예정 날짜
amount	decimal(15,2)	예정 금액
currency	string	통화 (KRW)
related_bank_account_id	bigint	관련 계좌 ID
counterparty	string	거래처
category	string	카테고리
status	enum	pending / completed / cancelled
is_recurring	boolean	반복 여부
recurrence_rule	string	반복 규칙
recurrence_end_date	date	반복 종료일
completed_date	date	실제 완료일
completed_amount	decimal(15,2)	실제 금액
created_by / updated_by / deleted_by	bigint	작업자

주요 Scope

->income()              // TYPE_INCOME만
->expense()             // TYPE_EXPENSE만
->pending()             // STATUS_PENDING만
->completed()           // STATUS_COMPLETED만
->forMonth(year, month) // 특정 월의 일정
->dateBetween(s, e)     // 날짜 범위
->ordered()             // scheduled_date 정렬

주요 Accessor

$schedule->formatted_amount     // "100만원" 형식
$schedule->type_label           // "입금 예정"
$schedule->status_label         // "예정"
$schedule->type_color_class     // Tailwind 색상 클래스
$schedule->status_color_class   // Tailwind 색상 클래스

뷰 구성

index.blade.php (캘린더 뷰)

┌─ 페이지 헤더 ──────────────────────
│  제목: "자금계획일정"
│  버튼: "일정 등록"
│
├─ 월별 요약 카드 (4열) ────────────
│  입금 예정 | 지급 예정 | 순 자금 흐름 | 총 일정
│
├─ 캘린더 섹션 ─────────────────────
│  ├─ 헤더: 월 네비게이션 (< 2026년 2월 >)
│  ├─ 요일 헤더 (일~토)
│  └─ 날짜 그리드 (일별 일정 표시)
│     ├─ 입금: 초록 배지
│     ├─ 지출: 빨강 배지
│     └─ 클릭 시 일정 상세
│
└─ 일정 등록/수정 모달 (JavaScript)

핵심 로직

월별 복사 (copySchedulesToMonth)

원본 월의 모든 일정 조회
    ↓
대상 월로 복사 (말일 처리)
  예) 1월 31일 → 2월 28일 (윤년이면 29일)
    ↓
새 일정 생성 (상태: pending으로 초기화)

월별 요약 (getMonthlySummary)

[
    'year' => 2026, 'month' => 2,
    'total_count' => 15,
    'income' => [
        'count' => 5, 'total' => 10000000,
        'pending' => 7000000, 'completed' => 3000000
    ],
    'expense' => [
        'count' => 10, 'total' => 8000000,
        'pending' => 5000000, 'completed' => 3000000
    ],
    'net' => 2000000  // 수입 - 지출
]

캘린더 데이터 (getCalendarData)

// 날짜별 그룹핑
[
    '2026-02-05' => [ {일정1}, {일정2} ],
    '2026-02-06' => [ {일정3} ],
    ...
]

HTMX 호환성

• 순수 Blade 템플릿 (HX-Redirect 불필요)
• JavaScript는 모달 열기/닫기 함수만 포함