feat: 2.4 입금/출금 관리 API 구현

- 마이그레이션: deposits, withdrawals 테이블 생성
- 모델: Deposit, Withdrawal (BelongsToTenant, SoftDeletes)
- 서비스: DepositService, WithdrawalService (CRUD + summary)
- 컨트롤러: DepositController, WithdrawalController
- FormRequest: Store/Update 검증 클래스
- Swagger: 입금/출금 API 문서 (12개 엔드포인트)
- 라우트: /v1/deposits, /v1/withdrawals 등록

app/Http/Controllers/Api/V1/DepositController.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\V1\Deposit\StoreDepositRequest;
+use App\Http\Requests\V1\Deposit\UpdateDepositRequest;
+use App\Http\Responses\ApiResponse;
+use App\Services\DepositService;
+use Illuminate\Http\Request;
+
+class DepositController extends Controller
+{
+    public function __construct(
+        private readonly DepositService $service
+    ) {}
+
+    /**
+     * 입금 목록
+     */
+    public function index(Request $request)
+    {
+        $params = $request->only([
+            'search',
+            'start_date',
+            'end_date',
+            'client_id',
+            'payment_method',
+            'bank_account_id',
+            'sort_by',
+            'sort_dir',
+            'per_page',
+            'page',
+        ]);
+
+        $deposits = $this->service->index($params);
+
+        return ApiResponse::handle(__('message.fetched'), $deposits);
+    }
+
+    /**
+     * 입금 등록
+     */
+    public function store(StoreDepositRequest $request)
+    {
+        $deposit = $this->service->store($request->validated());
+
+        return ApiResponse::handle(__('message.created'), $deposit, 201);
+    }
+
+    /**
+     * 입금 상세
+     */
+    public function show(int $id)
+    {
+        $deposit = $this->service->show($id);
+
+        return ApiResponse::handle(__('message.fetched'), $deposit);
+    }
+
+    /**
+     * 입금 수정
+     */
+    public function update(int $id, UpdateDepositRequest $request)
+    {
+        $deposit = $this->service->update($id, $request->validated());
+
+        return ApiResponse::handle(__('message.updated'), $deposit);
+    }
+
+    /**
+     * 입금 삭제
+     */
+    public function destroy(int $id)
+    {
+        $this->service->destroy($id);
+
+        return ApiResponse::handle(__('message.deleted'));
+    }
+
+    /**
+     * 입금 요약 (기간별 합계)
+     */
+    public function summary(Request $request)
+    {
+        $params = $request->only([
+            'start_date',
+            'end_date',
+            'client_id',
+            'payment_method',
+        ]);
+
+        $summary = $this->service->summary($params);
+
+        return ApiResponse::handle(__('message.fetched'), $summary);
+    }
+}

app/Http/Controllers/Api/V1/WithdrawalController.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\V1\Withdrawal\StoreWithdrawalRequest;
+use App\Http\Requests\V1\Withdrawal\UpdateWithdrawalRequest;
+use App\Http\Responses\ApiResponse;
+use App\Services\WithdrawalService;
+use Illuminate\Http\Request;
+
+class WithdrawalController extends Controller
+{
+    public function __construct(
+        private readonly WithdrawalService $service
+    ) {}
+
+    /**
+     * 출금 목록
+     */
+    public function index(Request $request)
+    {
+        $params = $request->only([
+            'search',
+            'start_date',
+            'end_date',
+            'client_id',
+            'payment_method',
+            'bank_account_id',
+            'sort_by',
+            'sort_dir',
+            'per_page',
+            'page',
+        ]);
+
+        $withdrawals = $this->service->index($params);
+
+        return ApiResponse::handle(__('message.fetched'), $withdrawals);
+    }
+
+    /**
+     * 출금 등록
+     */
+    public function store(StoreWithdrawalRequest $request)
+    {
+        $withdrawal = $this->service->store($request->validated());
+
+        return ApiResponse::handle(__('message.created'), $withdrawal, 201);
+    }
+
+    /**
+     * 출금 상세
+     */
+    public function show(int $id)
+    {
+        $withdrawal = $this->service->show($id);
+
+        return ApiResponse::handle(__('message.fetched'), $withdrawal);
+    }
+
+    /**
+     * 출금 수정
+     */
+    public function update(int $id, UpdateWithdrawalRequest $request)
+    {
+        $withdrawal = $this->service->update($id, $request->validated());
+
+        return ApiResponse::handle(__('message.updated'), $withdrawal);
+    }
+
+    /**
+     * 출금 삭제
+     */
+    public function destroy(int $id)
+    {
+        $this->service->destroy($id);
+
+        return ApiResponse::handle(__('message.deleted'));
+    }
+
+    /**
+     * 출금 요약 (기간별 합계)
+     */
+    public function summary(Request $request)
+    {
+        $params = $request->only([
+            'start_date',
+            'end_date',
+            'client_id',
+            'payment_method',
+        ]);
+
+        $summary = $this->service->summary($params);
+
+        return ApiResponse::handle(__('message.fetched'), $summary);
+    }
+}

app/Http/Requests/V1/Deposit/StoreDepositRequest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Http\Requests\V1\Deposit;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StoreDepositRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'deposit_date' => ['required', 'date'],
+            'client_id' => ['nullable', 'integer', 'exists:clients,id'],
+            'client_name' => ['nullable', 'string', 'max:100'],
+            'bank_account_id' => ['nullable', 'integer', 'exists:bank_accounts,id'],
+            'amount' => ['required', 'numeric', 'min:0'],
+            'payment_method' => ['required', 'string', 'in:cash,transfer,card,check'],
+            'account_code' => ['nullable', 'string', 'max:20'],
+            'description' => ['nullable', 'string', 'max:1000'],
+            'reference_type' => ['nullable', 'string', 'max:50'],
+            'reference_id' => ['nullable', 'integer'],
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'deposit_date.required' => __('validation.required', ['attribute' => __('validation.attributes.deposit_date')]),
+            'amount.required' => __('validation.required', ['attribute' => __('validation.attributes.amount')]),
+            'amount.min' => __('validation.min.numeric', ['attribute' => __('validation.attributes.amount'), 'min' => 0]),
+            'payment_method.required' => __('validation.required', ['attribute' => __('validation.attributes.payment_method')]),
+            'payment_method.in' => __('validation.in', ['attribute' => __('validation.attributes.payment_method')]),
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'deposit_date' => __('validation.attributes.deposit_date'),
+            'client_id' => __('validation.attributes.client_id'),
+            'client_name' => __('validation.attributes.client_name'),
+            'bank_account_id' => __('validation.attributes.bank_account_id'),
+            'amount' => __('validation.attributes.amount'),
+            'payment_method' => __('validation.attributes.payment_method'),
+            'account_code' => __('validation.attributes.account_code'),
+            'description' => __('validation.attributes.description'),
+        ];
+    }
+}

app/Http/Requests/V1/Deposit/UpdateDepositRequest.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Http\Requests\V1\Deposit;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class UpdateDepositRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'deposit_date' => ['sometimes', 'date'],
+            'client_id' => ['nullable', 'integer', 'exists:clients,id'],
+            'client_name' => ['nullable', 'string', 'max:100'],
+            'bank_account_id' => ['nullable', 'integer', 'exists:bank_accounts,id'],
+            'amount' => ['sometimes', 'numeric', 'min:0'],
+            'payment_method' => ['sometimes', 'string', 'in:cash,transfer,card,check'],
+            'account_code' => ['nullable', 'string', 'max:20'],
+            'description' => ['nullable', 'string', 'max:1000'],
+            'reference_type' => ['nullable', 'string', 'max:50'],
+            'reference_id' => ['nullable', 'integer'],
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'deposit_date' => __('validation.attributes.deposit_date'),
+            'client_id' => __('validation.attributes.client_id'),
+            'client_name' => __('validation.attributes.client_name'),
+            'bank_account_id' => __('validation.attributes.bank_account_id'),
+            'amount' => __('validation.attributes.amount'),
+            'payment_method' => __('validation.attributes.payment_method'),
+            'account_code' => __('validation.attributes.account_code'),
+            'description' => __('validation.attributes.description'),
+        ];
+    }
+}

app/Http/Requests/V1/Withdrawal/StoreWithdrawalRequest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Http\Requests\V1\Withdrawal;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StoreWithdrawalRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'withdrawal_date' => ['required', 'date'],
+            'client_id' => ['nullable', 'integer', 'exists:clients,id'],
+            'client_name' => ['nullable', 'string', 'max:100'],
+            'bank_account_id' => ['nullable', 'integer', 'exists:bank_accounts,id'],
+            'amount' => ['required', 'numeric', 'min:0'],
+            'payment_method' => ['required', 'string', 'in:cash,transfer,card,check'],
+            'account_code' => ['nullable', 'string', 'max:20'],
+            'description' => ['nullable', 'string', 'max:1000'],
+            'reference_type' => ['nullable', 'string', 'max:50'],
+            'reference_id' => ['nullable', 'integer'],
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'withdrawal_date.required' => __('validation.required', ['attribute' => __('validation.attributes.withdrawal_date')]),
+            'amount.required' => __('validation.required', ['attribute' => __('validation.attributes.amount')]),
+            'amount.min' => __('validation.min.numeric', ['attribute' => __('validation.attributes.amount'), 'min' => 0]),
+            'payment_method.required' => __('validation.required', ['attribute' => __('validation.attributes.payment_method')]),
+            'payment_method.in' => __('validation.in', ['attribute' => __('validation.attributes.payment_method')]),
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'withdrawal_date' => __('validation.attributes.withdrawal_date'),
+            'client_id' => __('validation.attributes.client_id'),
+            'client_name' => __('validation.attributes.client_name'),
+            'bank_account_id' => __('validation.attributes.bank_account_id'),
+            'amount' => __('validation.attributes.amount'),
+            'payment_method' => __('validation.attributes.payment_method'),
+            'account_code' => __('validation.attributes.account_code'),
+            'description' => __('validation.attributes.description'),
+        ];
+    }
+}

app/Http/Requests/V1/Withdrawal/UpdateWithdrawalRequest.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Http\Requests\V1\Withdrawal;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class UpdateWithdrawalRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'withdrawal_date' => ['sometimes', 'date'],
+            'client_id' => ['nullable', 'integer', 'exists:clients,id'],
+            'client_name' => ['nullable', 'string', 'max:100'],
+            'bank_account_id' => ['nullable', 'integer', 'exists:bank_accounts,id'],
+            'amount' => ['sometimes', 'numeric', 'min:0'],
+            'payment_method' => ['sometimes', 'string', 'in:cash,transfer,card,check'],
+            'account_code' => ['nullable', 'string', 'max:20'],
+            'description' => ['nullable', 'string', 'max:1000'],
+            'reference_type' => ['nullable', 'string', 'max:50'],
+            'reference_id' => ['nullable', 'integer'],
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'withdrawal_date' => __('validation.attributes.withdrawal_date'),
+            'client_id' => __('validation.attributes.client_id'),
+            'client_name' => __('validation.attributes.client_name'),
+            'bank_account_id' => __('validation.attributes.bank_account_id'),
+            'amount' => __('validation.attributes.amount'),
+            'payment_method' => __('validation.attributes.payment_method'),
+            'account_code' => __('validation.attributes.account_code'),
+            'description' => __('validation.attributes.description'),
+        ];
+    }
+}

app/Models/Tenants/Deposit.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace App\Models\Tenants;
+
+use App\Traits\BelongsToTenant;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+class Deposit extends Model
+{
+    use BelongsToTenant, SoftDeletes;
+
+    protected $fillable = [
+        'tenant_id',
+        'deposit_date',
+        'client_id',
+        'client_name',
+        'bank_account_id',
+        'amount',
+        'payment_method',
+        'account_code',
+        'description',
+        'reference_type',
+        'reference_id',
+        'created_by',
+        'updated_by',
+        'deleted_by',
+    ];
+
+    protected $casts = [
+        'deposit_date' => 'date',
+        'amount' => 'decimal:2',
+        'client_id' => 'integer',
+        'bank_account_id' => 'integer',
+        'reference_id' => 'integer',
+    ];
+
+    /**
+     * 결제수단 목록
+     */
+    public const PAYMENT_METHODS = [
+        'cash' => '현금',
+        'transfer' => '계좌이체',
+        'card' => '카드',
+        'check' => '수표',
+    ];
+
+    /**
+     * 거래처 관계
+     */
+    public function client(): BelongsTo
+    {
+        return $this->belongsTo(Client::class);
+    }
+
+    /**
+     * 입금 계좌 관계
+     */
+    public function bankAccount(): BelongsTo
+    {
+        return $this->belongsTo(BankAccount::class);
+    }
+
+    /**
+     * 생성자 관계
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(\App\Models\User::class, 'created_by');
+    }
+
+    /**
+     * 거래처명 조회 (회원/비회원 통합)
+     */
+    public function getDisplayClientNameAttribute(): string
+    {
+        if ($this->client) {
+            return $this->client->name;
+        }
+
+        return $this->client_name ?? '';
+    }
+
+    /**
+     * 결제수단 라벨
+     */
+    public function getPaymentMethodLabelAttribute(): string
+    {
+        return self::PAYMENT_METHODS[$this->payment_method] ?? $this->payment_method;
+    }
+}

app/Models/Tenants/Withdrawal.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace App\Models\Tenants;
+
+use App\Traits\BelongsToTenant;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+class Withdrawal extends Model
+{
+    use BelongsToTenant, SoftDeletes;
+
+    protected $fillable = [
+        'tenant_id',
+        'withdrawal_date',
+        'client_id',
+        'client_name',
+        'bank_account_id',
+        'amount',
+        'payment_method',
+        'account_code',
+        'description',
+        'reference_type',
+        'reference_id',
+        'created_by',
+        'updated_by',
+        'deleted_by',
+    ];
+
+    protected $casts = [
+        'withdrawal_date' => 'date',
+        'amount' => 'decimal:2',
+        'client_id' => 'integer',
+        'bank_account_id' => 'integer',
+        'reference_id' => 'integer',
+    ];
+
+    /**
+     * 결제수단 목록
+     */
+    public const PAYMENT_METHODS = [
+        'cash' => '현금',
+        'transfer' => '계좌이체',
+        'card' => '카드',
+        'check' => '수표',
+    ];
+
+    /**
+     * 거래처 관계
+     */
+    public function client(): BelongsTo
+    {
+        return $this->belongsTo(Client::class);
+    }
+
+    /**
+     * 출금 계좌 관계
+     */
+    public function bankAccount(): BelongsTo
+    {
+        return $this->belongsTo(BankAccount::class);
+    }
+
+    /**
+     * 생성자 관계
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(\App\Models\User::class, 'created_by');
+    }
+
+    /**
+     * 거래처명 조회 (회원/비회원 통합)
+     */
+    public function getDisplayClientNameAttribute(): string
+    {
+        if ($this->client) {
+            return $this->client->name;
+        }
+
+        return $this->client_name ?? '';
+    }
+
+    /**
+     * 결제수단 라벨
+     */
+    public function getPaymentMethodLabelAttribute(): string
+    {
+        return self::PAYMENT_METHODS[$this->payment_method] ?? $this->payment_method;
+    }
+}

app/Services/DepositService.php

@@ -0,0 +1,228 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Tenants\Deposit;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Facades\DB;
+
+class DepositService extends Service
+{
+    /**
+     * 입금 목록 조회
+     */
+    public function index(array $params): LengthAwarePaginator
+    {
+        $tenantId = $this->tenantId();
+
+        $query = Deposit::query()
+            ->where('tenant_id', $tenantId)
+            ->with(['client:id,name', 'bankAccount:id,bank_name,account_name']);
+
+        // 검색어 필터
+        if (! empty($params['search'])) {
+            $search = $params['search'];
+            $query->where(function ($q) use ($search) {
+                $q->where('client_name', 'like', "%{$search}%")
+                    ->orWhere('description', 'like', "%{$search}%")
+                    ->orWhereHas('client', function ($q) use ($search) {
+                        $q->where('name', 'like', "%{$search}%");
+                    });
+            });
+        }
+
+        // 날짜 범위 필터
+        if (! empty($params['start_date'])) {
+            $query->where('deposit_date', '>=', $params['start_date']);
+        }
+        if (! empty($params['end_date'])) {
+            $query->where('deposit_date', '<=', $params['end_date']);
+        }
+
+        // 거래처 필터
+        if (! empty($params['client_id'])) {
+            $query->where('client_id', $params['client_id']);
+        }
+
+        // 결제수단 필터
+        if (! empty($params['payment_method'])) {
+            $query->where('payment_method', $params['payment_method']);
+        }
+
+        // 계좌 필터
+        if (! empty($params['bank_account_id'])) {
+            $query->where('bank_account_id', $params['bank_account_id']);
+        }
+
+        // 정렬
+        $sortBy = $params['sort_by'] ?? 'deposit_date';
+        $sortDir = $params['sort_dir'] ?? 'desc';
+        $query->orderBy($sortBy, $sortDir);
+
+        // 페이지네이션
+        $perPage = $params['per_page'] ?? 20;
+
+        return $query->paginate($perPage);
+    }
+
+    /**
+     * 입금 상세 조회
+     */
+    public function show(int $id): Deposit
+    {
+        $tenantId = $this->tenantId();
+
+        return Deposit::query()
+            ->where('tenant_id', $tenantId)
+            ->with(['client:id,name', 'bankAccount:id,bank_name,account_name', 'creator:id,name'])
+            ->findOrFail($id);
+    }
+
+    /**
+     * 입금 등록
+     */
+    public function store(array $data): Deposit
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($data, $tenantId, $userId) {
+            $deposit = new Deposit;
+            $deposit->tenant_id = $tenantId;
+            $deposit->deposit_date = $data['deposit_date'];
+            $deposit->client_id = $data['client_id'] ?? null;
+            $deposit->client_name = $data['client_name'] ?? null;
+            $deposit->bank_account_id = $data['bank_account_id'] ?? null;
+            $deposit->amount = $data['amount'];
+            $deposit->payment_method = $data['payment_method'];
+            $deposit->account_code = $data['account_code'] ?? null;
+            $deposit->description = $data['description'] ?? null;
+            $deposit->reference_type = $data['reference_type'] ?? null;
+            $deposit->reference_id = $data['reference_id'] ?? null;
+            $deposit->created_by = $userId;
+            $deposit->updated_by = $userId;
+            $deposit->save();
+
+            return $deposit->load(['client:id,name', 'bankAccount:id,bank_name,account_name']);
+        });
+    }
+
+    /**
+     * 입금 수정
+     */
+    public function update(int $id, array $data): Deposit
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($id, $data, $tenantId, $userId) {
+            $deposit = Deposit::query()
+                ->where('tenant_id', $tenantId)
+                ->findOrFail($id);
+
+            if (isset($data['deposit_date'])) {
+                $deposit->deposit_date = $data['deposit_date'];
+            }
+            if (array_key_exists('client_id', $data)) {
+                $deposit->client_id = $data['client_id'];
+            }
+            if (array_key_exists('client_name', $data)) {
+                $deposit->client_name = $data['client_name'];
+            }
+            if (array_key_exists('bank_account_id', $data)) {
+                $deposit->bank_account_id = $data['bank_account_id'];
+            }
+            if (isset($data['amount'])) {
+                $deposit->amount = $data['amount'];
+            }
+            if (isset($data['payment_method'])) {
+                $deposit->payment_method = $data['payment_method'];
+            }
+            if (array_key_exists('account_code', $data)) {
+                $deposit->account_code = $data['account_code'];
+            }
+            if (array_key_exists('description', $data)) {
+                $deposit->description = $data['description'];
+            }
+            if (array_key_exists('reference_type', $data)) {
+                $deposit->reference_type = $data['reference_type'];
+            }
+            if (array_key_exists('reference_id', $data)) {
+                $deposit->reference_id = $data['reference_id'];
+            }
+
+            $deposit->updated_by = $userId;
+            $deposit->save();
+
+            return $deposit->fresh(['client:id,name', 'bankAccount:id,bank_name,account_name']);
+        });
+    }
+
+    /**
+     * 입금 삭제
+     */
+    public function destroy(int $id): bool
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($id, $tenantId, $userId) {
+            $deposit = Deposit::query()
+                ->where('tenant_id', $tenantId)
+                ->findOrFail($id);
+
+            $deposit->deleted_by = $userId;
+            $deposit->save();
+            $deposit->delete();
+
+            return true;
+        });
+    }
+
+    /**
+     * 입금 요약 (기간별 합계)
+     */
+    public function summary(array $params): array
+    {
+        $tenantId = $this->tenantId();
+
+        $query = Deposit::query()
+            ->where('tenant_id', $tenantId);
+
+        // 날짜 범위 필터
+        if (! empty($params['start_date'])) {
+            $query->where('deposit_date', '>=', $params['start_date']);
+        }
+        if (! empty($params['end_date'])) {
+            $query->where('deposit_date', '<=', $params['end_date']);
+        }
+
+        // 거래처 필터
+        if (! empty($params['client_id'])) {
+            $query->where('client_id', $params['client_id']);
+        }
+
+        // 결제수단 필터
+        if (! empty($params['payment_method'])) {
+            $query->where('payment_method', $params['payment_method']);
+        }
+
+        // 전체 합계
+        $total = (clone $query)->sum('amount');
+        $count = (clone $query)->count();
+
+        // 결제수단별 합계
+        $byPaymentMethod = (clone $query)
+            ->select('payment_method', DB::raw('SUM(amount) as total'), DB::raw('COUNT(*) as count'))
+            ->groupBy('payment_method')
+            ->get()
+            ->keyBy('payment_method')
+            ->toArray();
+
+        return [
+            'total_amount' => (float) $total,
+            'total_count' => $count,
+            'by_payment_method' => $byPaymentMethod,
+        ];
+    }
+}

app/Services/WithdrawalService.php

@@ -0,0 +1,228 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Tenants\Withdrawal;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Facades\DB;
+
+class WithdrawalService extends Service
+{
+    /**
+     * 출금 목록 조회
+     */
+    public function index(array $params): LengthAwarePaginator
+    {
+        $tenantId = $this->tenantId();
+
+        $query = Withdrawal::query()
+            ->where('tenant_id', $tenantId)
+            ->with(['client:id,name', 'bankAccount:id,bank_name,account_name']);
+
+        // 검색어 필터
+        if (! empty($params['search'])) {
+            $search = $params['search'];
+            $query->where(function ($q) use ($search) {
+                $q->where('client_name', 'like', "%{$search}%")
+                    ->orWhere('description', 'like', "%{$search}%")
+                    ->orWhereHas('client', function ($q) use ($search) {
+                        $q->where('name', 'like', "%{$search}%");
+                    });
+            });
+        }
+
+        // 날짜 범위 필터
+        if (! empty($params['start_date'])) {
+            $query->where('withdrawal_date', '>=', $params['start_date']);
+        }
+        if (! empty($params['end_date'])) {
+            $query->where('withdrawal_date', '<=', $params['end_date']);
+        }
+
+        // 거래처 필터
+        if (! empty($params['client_id'])) {
+            $query->where('client_id', $params['client_id']);
+        }
+
+        // 결제수단 필터
+        if (! empty($params['payment_method'])) {
+            $query->where('payment_method', $params['payment_method']);
+        }
+
+        // 계좌 필터
+        if (! empty($params['bank_account_id'])) {
+            $query->where('bank_account_id', $params['bank_account_id']);
+        }
+
+        // 정렬
+        $sortBy = $params['sort_by'] ?? 'withdrawal_date';
+        $sortDir = $params['sort_dir'] ?? 'desc';
+        $query->orderBy($sortBy, $sortDir);
+
+        // 페이지네이션
+        $perPage = $params['per_page'] ?? 20;
+
+        return $query->paginate($perPage);
+    }
+
+    /**
+     * 출금 상세 조회
+     */
+    public function show(int $id): Withdrawal
+    {
+        $tenantId = $this->tenantId();
+
+        return Withdrawal::query()
+            ->where('tenant_id', $tenantId)
+            ->with(['client:id,name', 'bankAccount:id,bank_name,account_name', 'creator:id,name'])
+            ->findOrFail($id);
+    }
+
+    /**
+     * 출금 등록
+     */
+    public function store(array $data): Withdrawal
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($data, $tenantId, $userId) {
+            $withdrawal = new Withdrawal;
+            $withdrawal->tenant_id = $tenantId;
+            $withdrawal->withdrawal_date = $data['withdrawal_date'];
+            $withdrawal->client_id = $data['client_id'] ?? null;
+            $withdrawal->client_name = $data['client_name'] ?? null;
+            $withdrawal->bank_account_id = $data['bank_account_id'] ?? null;
+            $withdrawal->amount = $data['amount'];
+            $withdrawal->payment_method = $data['payment_method'];
+            $withdrawal->account_code = $data['account_code'] ?? null;
+            $withdrawal->description = $data['description'] ?? null;
+            $withdrawal->reference_type = $data['reference_type'] ?? null;
+            $withdrawal->reference_id = $data['reference_id'] ?? null;
+            $withdrawal->created_by = $userId;
+            $withdrawal->updated_by = $userId;
+            $withdrawal->save();
+
+            return $withdrawal->load(['client:id,name', 'bankAccount:id,bank_name,account_name']);
+        });
+    }
+
+    /**
+     * 출금 수정
+     */
+    public function update(int $id, array $data): Withdrawal
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($id, $data, $tenantId, $userId) {
+            $withdrawal = Withdrawal::query()
+                ->where('tenant_id', $tenantId)
+                ->findOrFail($id);
+
+            if (isset($data['withdrawal_date'])) {
+                $withdrawal->withdrawal_date = $data['withdrawal_date'];
+            }
+            if (array_key_exists('client_id', $data)) {
+                $withdrawal->client_id = $data['client_id'];
+            }
+            if (array_key_exists('client_name', $data)) {
+                $withdrawal->client_name = $data['client_name'];
+            }
+            if (array_key_exists('bank_account_id', $data)) {
+                $withdrawal->bank_account_id = $data['bank_account_id'];
+            }
+            if (isset($data['amount'])) {
+                $withdrawal->amount = $data['amount'];
+            }
+            if (isset($data['payment_method'])) {
+                $withdrawal->payment_method = $data['payment_method'];
+            }
+            if (array_key_exists('account_code', $data)) {
+                $withdrawal->account_code = $data['account_code'];
+            }
+            if (array_key_exists('description', $data)) {
+                $withdrawal->description = $data['description'];
+            }
+            if (array_key_exists('reference_type', $data)) {
+                $withdrawal->reference_type = $data['reference_type'];
+            }
+            if (array_key_exists('reference_id', $data)) {
+                $withdrawal->reference_id = $data['reference_id'];
+            }
+
+            $withdrawal->updated_by = $userId;
+            $withdrawal->save();
+
+            return $withdrawal->fresh(['client:id,name', 'bankAccount:id,bank_name,account_name']);
+        });
+    }
+
+    /**
+     * 출금 삭제
+     */
+    public function destroy(int $id): bool
+    {
+        $tenantId = $this->tenantId();
+        $userId = $this->apiUserId();
+
+        return DB::transaction(function () use ($id, $tenantId, $userId) {
+            $withdrawal = Withdrawal::query()
+                ->where('tenant_id', $tenantId)
+                ->findOrFail($id);
+
+            $withdrawal->deleted_by = $userId;
+            $withdrawal->save();
+            $withdrawal->delete();
+
+            return true;
+        });
+    }
+
+    /**
+     * 출금 요약 (기간별 합계)
+     */
+    public function summary(array $params): array
+    {
+        $tenantId = $this->tenantId();
+
+        $query = Withdrawal::query()
+            ->where('tenant_id', $tenantId);
+
+        // 날짜 범위 필터
+        if (! empty($params['start_date'])) {
+            $query->where('withdrawal_date', '>=', $params['start_date']);
+        }
+        if (! empty($params['end_date'])) {
+            $query->where('withdrawal_date', '<=', $params['end_date']);
+        }
+
+        // 거래처 필터
+        if (! empty($params['client_id'])) {
+            $query->where('client_id', $params['client_id']);
+        }
+
+        // 결제수단 필터
+        if (! empty($params['payment_method'])) {
+            $query->where('payment_method', $params['payment_method']);
+        }
+
+        // 전체 합계
+        $total = (clone $query)->sum('amount');
+        $count = (clone $query)->count();
+
+        // 결제수단별 합계
+        $byPaymentMethod = (clone $query)
+            ->select('payment_method', DB::raw('SUM(amount) as total'), DB::raw('COUNT(*) as count'))
+            ->groupBy('payment_method')
+            ->get()
+            ->keyBy('payment_method')
+            ->toArray();
+
+        return [
+            'total_amount' => (float) $total,
+            'total_count' => $count,
+            'by_payment_method' => $byPaymentMethod,
+        ];
+    }
+}

app/Swagger/v1/DepositApi.php

@@ -0,0 +1,313 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="Deposits", description="입금 관리")
+ *
+ * @OA\Schema(
+ *     schema="Deposit",
+ *     type="object",
+ *     description="입금 정보",
+ *
+ *     @OA\Property(property="id", type="integer", example=1, description="입금 ID"),
+ *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
+ *     @OA\Property(property="deposit_date", type="string", format="date", example="2025-01-15", description="입금일"),
+ *     @OA\Property(property="client_id", type="integer", example=1, nullable=true, description="거래처 ID"),
+ *     @OA\Property(property="client_name", type="string", example="홍길동", nullable=true, description="비회원 거래처명"),
+ *     @OA\Property(property="bank_account_id", type="integer", example=1, nullable=true, description="입금 계좌 ID"),
+ *     @OA\Property(property="amount", type="number", format="float", example=1000000, description="금액"),
+ *     @OA\Property(property="payment_method", type="string", enum={"cash","transfer","card","check"}, example="transfer", description="결제수단"),
+ *     @OA\Property(property="account_code", type="string", example="401", nullable=true, description="계정과목"),
+ *     @OA\Property(property="description", type="string", example="1월 매출 입금", nullable=true, description="적요"),
+ *     @OA\Property(property="reference_type", type="string", example="sales", nullable=true, description="참조 유형"),
+ *     @OA\Property(property="reference_id", type="integer", example=1, nullable=true, description="참조 ID"),
+ *     @OA\Property(property="client", type="object", nullable=true,
+ *         @OA\Property(property="id", type="integer", example=1),
+ *         @OA\Property(property="name", type="string", example="(주)테스트"),
+ *         description="거래처 정보"
+ *     ),
+ *     @OA\Property(property="bank_account", type="object", nullable=true,
+ *         @OA\Property(property="id", type="integer", example=1),
+ *         @OA\Property(property="bank_name", type="string", example="국민은행"),
+ *         @OA\Property(property="account_name", type="string", example="법인통장"),
+ *         description="계좌 정보"
+ *     ),
+ *     @OA\Property(property="created_by", type="integer", example=1, nullable=true, description="생성자 ID"),
+ *     @OA\Property(property="created_at", type="string", format="date-time"),
+ *     @OA\Property(property="updated_at", type="string", format="date-time")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="DepositCreateRequest",
+ *     type="object",
+ *     required={"deposit_date","amount","payment_method"},
+ *     description="입금 등록 요청",
+ *
+ *     @OA\Property(property="deposit_date", type="string", format="date", example="2025-01-15", description="입금일"),
+ *     @OA\Property(property="client_id", type="integer", example=1, nullable=true, description="거래처 ID"),
+ *     @OA\Property(property="client_name", type="string", example="홍길동", maxLength=100, nullable=true, description="비회원 거래처명"),
+ *     @OA\Property(property="bank_account_id", type="integer", example=1, nullable=true, description="입금 계좌 ID"),
+ *     @OA\Property(property="amount", type="number", format="float", example=1000000, description="금액"),
+ *     @OA\Property(property="payment_method", type="string", enum={"cash","transfer","card","check"}, example="transfer", description="결제수단"),
+ *     @OA\Property(property="account_code", type="string", example="401", maxLength=20, nullable=true, description="계정과목"),
+ *     @OA\Property(property="description", type="string", example="1월 매출 입금", maxLength=1000, nullable=true, description="적요"),
+ *     @OA\Property(property="reference_type", type="string", example="sales", maxLength=50, nullable=true, description="참조 유형"),
+ *     @OA\Property(property="reference_id", type="integer", example=1, nullable=true, description="참조 ID")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="DepositUpdateRequest",
+ *     type="object",
+ *     description="입금 수정 요청",
+ *
+ *     @OA\Property(property="deposit_date", type="string", format="date", example="2025-01-15", description="입금일"),
+ *     @OA\Property(property="client_id", type="integer", example=1, nullable=true, description="거래처 ID"),
+ *     @OA\Property(property="client_name", type="string", example="홍길동", maxLength=100, nullable=true, description="비회원 거래처명"),
+ *     @OA\Property(property="bank_account_id", type="integer", example=1, nullable=true, description="입금 계좌 ID"),
+ *     @OA\Property(property="amount", type="number", format="float", example=1000000, description="금액"),
+ *     @OA\Property(property="payment_method", type="string", enum={"cash","transfer","card","check"}, example="transfer", description="결제수단"),
+ *     @OA\Property(property="account_code", type="string", example="401", maxLength=20, nullable=true, description="계정과목"),
+ *     @OA\Property(property="description", type="string", example="1월 매출 입금", maxLength=1000, nullable=true, description="적요"),
+ *     @OA\Property(property="reference_type", type="string", example="sales", maxLength=50, nullable=true, description="참조 유형"),
+ *     @OA\Property(property="reference_id", type="integer", example=1, nullable=true, description="참조 ID")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="DepositSummary",
+ *     type="object",
+ *     description="입금 요약",
+ *
+ *     @OA\Property(property="total_amount", type="number", format="float", example=5000000, description="총 입금액"),
+ *     @OA\Property(property="total_count", type="integer", example=10, description="총 건수"),
+ *     @OA\Property(property="by_payment_method", type="object", description="결제수단별 합계",
+ *         @OA\Property(property="cash", type="object",
+ *             @OA\Property(property="total", type="number", example=1000000),
+ *             @OA\Property(property="count", type="integer", example=2)
+ *         ),
+ *         @OA\Property(property="transfer", type="object",
+ *             @OA\Property(property="total", type="number", example=4000000),
+ *             @OA\Property(property="count", type="integer", example=8)
+ *         )
+ *     )
+ * )
+ */
+class DepositApi
+{
+    /**
+     * @OA\Get(
+     *     path="/api/v1/deposits",
+     *     tags={"Deposits"},
+     *     summary="입금 목록 조회",
+     *     description="입금 목록을 조회합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="search", in="query", description="검색어 (거래처명, 적요)", @OA\Schema(type="string")),
+     *     @OA\Parameter(name="start_date", in="query", description="시작일", @OA\Schema(type="string", format="date")),
+     *     @OA\Parameter(name="end_date", in="query", description="종료일", @OA\Schema(type="string", format="date")),
+     *     @OA\Parameter(name="client_id", in="query", description="거래처 ID", @OA\Schema(type="integer")),
+     *     @OA\Parameter(name="payment_method", in="query", description="결제수단", @OA\Schema(type="string", enum={"cash","transfer","card","check"})),
+     *     @OA\Parameter(name="bank_account_id", in="query", description="계좌 ID", @OA\Schema(type="integer")),
+     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"deposit_date","amount","created_at"}, default="deposit_date")),
+     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="desc")),
+     *     @OA\Parameter(ref="#/components/parameters/Page"),
+     *     @OA\Parameter(ref="#/components/parameters/Size"),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="조회 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(
+     *                         property="data",
+     *                         type="object",
+     *                         @OA\Property(property="current_page", type="integer", example=1),
+     *                         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Deposit")),
+     *                         @OA\Property(property="per_page", type="integer", example=20),
+     *                         @OA\Property(property="total", type="integer", example=50)
+     *                     )
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function index() {}
+
+    /**
+     * @OA\Post(
+     *     path="/api/v1/deposits",
+     *     tags={"Deposits"},
+     *     summary="입금 등록",
+     *     description="새로운 입금을 등록합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\RequestBody(
+     *         required=true,
+     *
+     *         @OA\JsonContent(ref="#/components/schemas/DepositCreateRequest")
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=201,
+     *         description="등록 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/Deposit")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function store() {}
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/deposits/summary",
+     *     tags={"Deposits"},
+     *     summary="입금 요약 조회",
+     *     description="기간별 입금 요약을 조회합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="start_date", in="query", description="시작일", @OA\Schema(type="string", format="date")),
+     *     @OA\Parameter(name="end_date", in="query", description="종료일", @OA\Schema(type="string", format="date")),
+     *     @OA\Parameter(name="client_id", in="query", description="거래처 ID", @OA\Schema(type="integer")),
+     *     @OA\Parameter(name="payment_method", in="query", description="결제수단", @OA\Schema(type="string", enum={"cash","transfer","card","check"})),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="조회 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/DepositSummary")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function summary() {}
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/deposits/{id}",
+     *     tags={"Deposits"},
+     *     summary="입금 상세 조회",
+     *     description="입금 상세 정보를 조회합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="입금 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="조회 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/Deposit")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="입금 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function show() {}
+
+    /**
+     * @OA\Put(
+     *     path="/api/v1/deposits/{id}",
+     *     tags={"Deposits"},
+     *     summary="입금 수정",
+     *     description="입금 정보를 수정합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="입금 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\RequestBody(
+     *         required=true,
+     *
+     *         @OA\JsonContent(ref="#/components/schemas/DepositUpdateRequest")
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="수정 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/Deposit")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="입금 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function update() {}
+
+    /**
+     * @OA\Delete(
+     *     path="/api/v1/deposits/{id}",
+     *     tags={"Deposits"},
+     *     summary="입금 삭제",
+     *     description="입금을 삭제합니다. (Soft Delete)",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="입금 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="삭제 성공",
+     *
+     *         @OA\JsonContent(ref="#/components/schemas/ApiResponse")
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="입금 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function destroy() {}
+}

app/Swagger/v1/WithdrawalApi.php

@@ -0,0 +1,313 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="Withdrawals", description="출금 관리")
+ *
+ * @OA\Schema(
+ *     schema="Withdrawal",
+ *     type="object",
+ *     description="출금 정보",
+ *
+ *     @OA\Property(property="id", type="integer", example=1, description="출금 ID"),
+ *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
+ *     @OA\Property(property="withdrawal_date", type="string", format="date", example="2025-01-15", description="출금일"),
+ *     @OA\Property(property="client_id", type="integer", example=1, nullable=true, description="거래처 ID"),
+ *     @OA\Property(property="client_name", type="string", example="홍길동", nullable=true, description="비회원 거래처명"),
+ *     @OA\Property(property="bank_account_id", type="integer", example=1, nullable=true, description="출금 계좌 ID"),
+ *     @OA\Property(property="amount", type="number", format="float", example=500000, description="금액"),
+ *     @OA\Property(property="payment_method", type="string", enum={"cash","transfer","card","check"}, example="transfer", description="결제수단"),
+ *     @OA\Property(property="account_code", type="string", example="501", nullable=true, description="계정과목"),
+ *     @OA\Property(property="description", type="string", example="사무용품 구매", nullable=true, description="적요"),
+ *     @OA\Property(property="reference_type", type="string", example="purchase", nullable=true, description="참조 유형"),
+ *     @OA\Property(property="reference_id", type="integer", example=1, nullable=true, description="참조 ID"),
+ *     @OA\Property(property="client", type="object", nullable=true,
+ *         @OA\Property(property="id", type="integer", example=1),
+ *         @OA\Property(property="name", type="string", example="(주)테스트"),
+ *         description="거래처 정보"
+ *     ),
+ *     @OA\Property(property="bank_account", type="object", nullable=true,
+ *         @OA\Property(property="id", type="integer", example=1),
+ *         @OA\Property(property="bank_name", type="string", example="국민은행"),
+ *         @OA\Property(property="account_name", type="string", example="법인통장"),
+ *         description="계좌 정보"
+ *     ),
+ *     @OA\Property(property="created_by", type="integer", example=1, nullable=true, description="생성자 ID"),
+ *     @OA\Property(property="created_at", type="string", format="date-time"),
+ *     @OA\Property(property="updated_at", type="string", format="date-time")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="WithdrawalCreateRequest",
+ *     type="object",
+ *     required={"withdrawal_date","amount","payment_method"},
+ *     description="출금 등록 요청",
+ *
+ *     @OA\Property(property="withdrawal_date", type="string", format="date", example="2025-01-15", description="출금일"),
+ *     @OA\Property(property="client_id", type="integer", example=1, nullable=true, description="거래처 ID"),
+ *     @OA\Property(property="client_name", type="string", example="홍길동", maxLength=100, nullable=true, description="비회원 거래처명"),
+ *     @OA\Property(property="bank_account_id", type="integer", example=1, nullable=true, description="출금 계좌 ID"),
+ *     @OA\Property(property="amount", type="number", format="float", example=500000, description="금액"),
+ *     @OA\Property(property="payment_method", type="string", enum={"cash","transfer","card","check"}, example="transfer", description="결제수단"),
+ *     @OA\Property(property="account_code", type="string", example="501", maxLength=20, nullable=true, description="계정과목"),
+ *     @OA\Property(property="description", type="string", example="사무용품 구매", maxLength=1000, nullable=true, description="적요"),
+ *     @OA\Property(property="reference_type", type="string", example="purchase", maxLength=50, nullable=true, description="참조 유형"),
+ *     @OA\Property(property="reference_id", type="integer", example=1, nullable=true, description="참조 ID")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="WithdrawalUpdateRequest",
+ *     type="object",
+ *     description="출금 수정 요청",
+ *
+ *     @OA\Property(property="withdrawal_date", type="string", format="date", example="2025-01-15", description="출금일"),
+ *     @OA\Property(property="client_id", type="integer", example=1, nullable=true, description="거래처 ID"),
+ *     @OA\Property(property="client_name", type="string", example="홍길동", maxLength=100, nullable=true, description="비회원 거래처명"),
+ *     @OA\Property(property="bank_account_id", type="integer", example=1, nullable=true, description="출금 계좌 ID"),
+ *     @OA\Property(property="amount", type="number", format="float", example=500000, description="금액"),
+ *     @OA\Property(property="payment_method", type="string", enum={"cash","transfer","card","check"}, example="transfer", description="결제수단"),
+ *     @OA\Property(property="account_code", type="string", example="501", maxLength=20, nullable=true, description="계정과목"),
+ *     @OA\Property(property="description", type="string", example="사무용품 구매", maxLength=1000, nullable=true, description="적요"),
+ *     @OA\Property(property="reference_type", type="string", example="purchase", maxLength=50, nullable=true, description="참조 유형"),
+ *     @OA\Property(property="reference_id", type="integer", example=1, nullable=true, description="참조 ID")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="WithdrawalSummary",
+ *     type="object",
+ *     description="출금 요약",
+ *
+ *     @OA\Property(property="total_amount", type="number", format="float", example=3000000, description="총 출금액"),
+ *     @OA\Property(property="total_count", type="integer", example=15, description="총 건수"),
+ *     @OA\Property(property="by_payment_method", type="object", description="결제수단별 합계",
+ *         @OA\Property(property="cash", type="object",
+ *             @OA\Property(property="total", type="number", example=500000),
+ *             @OA\Property(property="count", type="integer", example=5)
+ *         ),
+ *         @OA\Property(property="transfer", type="object",
+ *             @OA\Property(property="total", type="number", example=2500000),
+ *             @OA\Property(property="count", type="integer", example=10)
+ *         )
+ *     )
+ * )
+ */
+class WithdrawalApi
+{
+    /**
+     * @OA\Get(
+     *     path="/api/v1/withdrawals",
+     *     tags={"Withdrawals"},
+     *     summary="출금 목록 조회",
+     *     description="출금 목록을 조회합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="search", in="query", description="검색어 (거래처명, 적요)", @OA\Schema(type="string")),
+     *     @OA\Parameter(name="start_date", in="query", description="시작일", @OA\Schema(type="string", format="date")),
+     *     @OA\Parameter(name="end_date", in="query", description="종료일", @OA\Schema(type="string", format="date")),
+     *     @OA\Parameter(name="client_id", in="query", description="거래처 ID", @OA\Schema(type="integer")),
+     *     @OA\Parameter(name="payment_method", in="query", description="결제수단", @OA\Schema(type="string", enum={"cash","transfer","card","check"})),
+     *     @OA\Parameter(name="bank_account_id", in="query", description="계좌 ID", @OA\Schema(type="integer")),
+     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"withdrawal_date","amount","created_at"}, default="withdrawal_date")),
+     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="desc")),
+     *     @OA\Parameter(ref="#/components/parameters/Page"),
+     *     @OA\Parameter(ref="#/components/parameters/Size"),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="조회 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(
+     *                         property="data",
+     *                         type="object",
+     *                         @OA\Property(property="current_page", type="integer", example=1),
+     *                         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Withdrawal")),
+     *                         @OA\Property(property="per_page", type="integer", example=20),
+     *                         @OA\Property(property="total", type="integer", example=30)
+     *                     )
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function index() {}
+
+    /**
+     * @OA\Post(
+     *     path="/api/v1/withdrawals",
+     *     tags={"Withdrawals"},
+     *     summary="출금 등록",
+     *     description="새로운 출금을 등록합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\RequestBody(
+     *         required=true,
+     *
+     *         @OA\JsonContent(ref="#/components/schemas/WithdrawalCreateRequest")
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=201,
+     *         description="등록 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/Withdrawal")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function store() {}
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/withdrawals/summary",
+     *     tags={"Withdrawals"},
+     *     summary="출금 요약 조회",
+     *     description="기간별 출금 요약을 조회합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="start_date", in="query", description="시작일", @OA\Schema(type="string", format="date")),
+     *     @OA\Parameter(name="end_date", in="query", description="종료일", @OA\Schema(type="string", format="date")),
+     *     @OA\Parameter(name="client_id", in="query", description="거래처 ID", @OA\Schema(type="integer")),
+     *     @OA\Parameter(name="payment_method", in="query", description="결제수단", @OA\Schema(type="string", enum={"cash","transfer","card","check"})),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="조회 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/WithdrawalSummary")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function summary() {}
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/withdrawals/{id}",
+     *     tags={"Withdrawals"},
+     *     summary="출금 상세 조회",
+     *     description="출금 상세 정보를 조회합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="출금 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="조회 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/Withdrawal")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="출금 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function show() {}
+
+    /**
+     * @OA\Put(
+     *     path="/api/v1/withdrawals/{id}",
+     *     tags={"Withdrawals"},
+     *     summary="출금 수정",
+     *     description="출금 정보를 수정합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="출금 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\RequestBody(
+     *         required=true,
+     *
+     *         @OA\JsonContent(ref="#/components/schemas/WithdrawalUpdateRequest")
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="수정 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/Withdrawal")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="출금 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function update() {}
+
+    /**
+     * @OA\Delete(
+     *     path="/api/v1/withdrawals/{id}",
+     *     tags={"Withdrawals"},
+     *     summary="출금 삭제",
+     *     description="출금을 삭제합니다. (Soft Delete)",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="출금 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="삭제 성공",
+     *
+     *         @OA\JsonContent(ref="#/components/schemas/ApiResponse")
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="출금 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function destroy() {}
+}

database/migrations/2025_12_17_130000_create_deposits_table.php

@@ -0,0 +1,40 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('deposits', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('tenant_id')->comment('테넌트 ID');
+            $table->date('deposit_date')->comment('입금일');
+            $table->unsignedBigInteger('client_id')->nullable()->comment('거래처 ID');
+            $table->string('client_name', 100)->nullable()->comment('비회원 거래처명');
+            $table->unsignedBigInteger('bank_account_id')->nullable()->comment('입금 계좌 ID');
+            $table->decimal('amount', 15, 2)->comment('금액');
+            $table->string('payment_method', 20)->comment('결제수단: cash/transfer/card/check');
+            $table->string('account_code', 20)->nullable()->comment('계정과목');
+            $table->text('description')->nullable()->comment('적요');
+            $table->string('reference_type', 50)->nullable()->comment('참조 유형: sales/receivable/etc');
+            $table->unsignedBigInteger('reference_id')->nullable()->comment('참조 ID');
+            $table->unsignedBigInteger('created_by')->nullable()->comment('생성자 ID');
+            $table->unsignedBigInteger('updated_by')->nullable()->comment('수정자 ID');
+            $table->unsignedBigInteger('deleted_by')->nullable()->comment('삭제자 ID');
+            $table->softDeletes();
+            $table->timestamps();
+
+            $table->index(['tenant_id', 'deposit_date'], 'idx_tenant_date');
+            $table->index('client_id', 'idx_client');
+            $table->index('payment_method', 'idx_payment_method');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('deposits');
+    }
+};

database/migrations/2025_12_17_130001_create_withdrawals_table.php

@@ -0,0 +1,40 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('withdrawals', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('tenant_id')->comment('테넌트 ID');
+            $table->date('withdrawal_date')->comment('출금일');
+            $table->unsignedBigInteger('client_id')->nullable()->comment('거래처 ID');
+            $table->string('client_name', 100)->nullable()->comment('비회원 거래처명');
+            $table->unsignedBigInteger('bank_account_id')->nullable()->comment('출금 계좌 ID');
+            $table->decimal('amount', 15, 2)->comment('금액');
+            $table->string('payment_method', 20)->comment('결제수단: cash/transfer/card/check');
+            $table->string('account_code', 20)->nullable()->comment('계정과목');
+            $table->text('description')->nullable()->comment('적요');
+            $table->string('reference_type', 50)->nullable()->comment('참조 유형: purchase/payable/payroll/etc');
+            $table->unsignedBigInteger('reference_id')->nullable()->comment('참조 ID');
+            $table->unsignedBigInteger('created_by')->nullable()->comment('생성자 ID');
+            $table->unsignedBigInteger('updated_by')->nullable()->comment('수정자 ID');
+            $table->unsignedBigInteger('deleted_by')->nullable()->comment('삭제자 ID');
+            $table->softDeletes();
+            $table->timestamps();
+
+            $table->index(['tenant_id', 'withdrawal_date'], 'idx_tenant_date');
+            $table->index('client_id', 'idx_client');
+            $table->index('payment_method', 'idx_payment_method');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('withdrawals');
+    }
+};

routes/api.php

@@ -51,6 +51,8 @@
 use App\Http\Controllers\Api\V1\RolePermissionController;
 use App\Http\Controllers\Api\V1\BankAccountController;
 use App\Http\Controllers\Api\V1\CardController;
+use App\Http\Controllers\Api\V1\DepositController;
+use App\Http\Controllers\Api\V1\WithdrawalController;
 use App\Http\Controllers\Api\V1\SiteController;
 use App\Http\Controllers\Api\V1\TenantController;
 use App\Http\Controllers\Api\V1\TenantFieldSettingController;
@@ -294,6 +296,26 @@
             Route::patch('/{id}/set-primary', [BankAccountController::class, 'setPrimary'])->whereNumber('id')->name('v1.bank-accounts.set-primary');
         });
 
+        // Deposit API (입금 관리)
+        Route::prefix('deposits')->group(function () {
+            Route::get('', [DepositController::class, 'index'])->name('v1.deposits.index');
+            Route::post('', [DepositController::class, 'store'])->name('v1.deposits.store');
+            Route::get('/summary', [DepositController::class, 'summary'])->name('v1.deposits.summary');
+            Route::get('/{id}', [DepositController::class, 'show'])->whereNumber('id')->name('v1.deposits.show');
+            Route::put('/{id}', [DepositController::class, 'update'])->whereNumber('id')->name('v1.deposits.update');
+            Route::delete('/{id}', [DepositController::class, 'destroy'])->whereNumber('id')->name('v1.deposits.destroy');
+        });
+
+        // Withdrawal API (출금 관리)
+        Route::prefix('withdrawals')->group(function () {
+            Route::get('', [WithdrawalController::class, 'index'])->name('v1.withdrawals.index');
+            Route::post('', [WithdrawalController::class, 'store'])->name('v1.withdrawals.store');
+            Route::get('/summary', [WithdrawalController::class, 'summary'])->name('v1.withdrawals.summary');
+            Route::get('/{id}', [WithdrawalController::class, 'show'])->whereNumber('id')->name('v1.withdrawals.show');
+            Route::put('/{id}', [WithdrawalController::class, 'update'])->whereNumber('id')->name('v1.withdrawals.update');
+            Route::delete('/{id}', [WithdrawalController::class, 'destroy'])->whereNumber('id')->name('v1.withdrawals.destroy');
+        });
+
         // Permission API
         Route::prefix('permissions')->group(function () {
             Route::get('departments/{dept_id}/menu-matrix', [PermissionController::class, 'deptMenuMatrix'])->name('v1.permissions.deptMenuMatrix'); // 부서별 권한 메트릭스