feat(finance): Phase 117 — Advance Payments & Customer Deposits

Implements advance payment recording and tracking before invoices are issued,
including migration, model with applyAmount/refund methods, CRUD controller,
policy, routes, React pages, TypeScript types, sidebar link, and 10 Pest tests.

https://claude.ai/code/session_01RdUGwo74JXChRCF88Yu27d

Author: claude

erp/app/Modules/Finance/Http/Controllers/AdvancePaymentController.php

@@ -0,0 +1,102 @@
+<?php
+
+namespace App\Modules\Finance\Http\Controllers;
+
+use App\Http\Controllers\Controller;
+use App\Modules\Finance\Models\AdvancePayment;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+use Inertia\Response;
+
+class AdvancePaymentController extends Controller
+{
+    public function index(Request $request): Response
+    {
+        $this->authorize('viewAny', AdvancePayment::class);
+
+        $query = AdvancePayment::with(['contact'])
+            ->orderByDesc('payment_date');
+
+        if ($request->filled('status')) {
+            $query->where('status', $request->status);
+        }
+
+        $advancePayments = $query->paginate(20);
+
+        return Inertia::render('Finance/AdvancePayments/Index', compact('advancePayments'));
+    }
+
+    public function store(Request $request): RedirectResponse
+    {
+        $this->authorize('create', AdvancePayment::class);
+
+        $data = $request->validate([
+            'contact_id'     => 'nullable|exists:contacts,id',
+            'amount'         => 'required|numeric|min:0.01',
+            'payment_date'   => 'required|date',
+            'currency'       => 'nullable|string|max:3',
+            'reference'      => 'nullable|string|max:255',
+            'payment_method' => 'nullable|string|max:50',
+            'notes'          => 'nullable|string',
+        ]);
+
+        $advancePayment = AdvancePayment::create([
+            'tenant_id'      => auth()->user()->tenant_id,
+            'contact_id'     => $data['contact_id'] ?? null,
+            'amount'         => $data['amount'],
+            'payment_date'   => $data['payment_date'],
+            'currency'       => $data['currency'] ?? 'USD',
+            'reference'      => $data['reference'] ?? null,
+            'payment_method' => $data['payment_method'] ?? null,
+            'notes'          => $data['notes'] ?? null,
+            'status'         => 'received',
+            'applied_amount' => 0,
+            'created_by'     => auth()->id(),
+        ]);
+
+        return redirect()->route('finance.advance-payments.show', $advancePayment)
+            ->with('success', 'Advance payment recorded.');
+    }
+
+    public function show(AdvancePayment $advancePayment): Response
+    {
+        $this->authorize('view', $advancePayment);
+
+        $advancePayment->load(['contact', 'createdBy']);
+
+        return Inertia::render('Finance/AdvancePayments/Show', compact('advancePayment'));
+    }
+
+    public function apply(Request $request, AdvancePayment $advancePayment): RedirectResponse
+    {
+        $this->authorize('update', $advancePayment);
+
+        $data = $request->validate([
+            'amount' => 'required|numeric|min:0.01',
+        ]);
+
+        $advancePayment->applyAmount((float) $data['amount']);
+
+        return back()->with('success', 'Amount applied successfully.');
+    }
+
+    public function refund(AdvancePayment $advancePayment): RedirectResponse
+    {
+        $this->authorize('update', $advancePayment);
+
+        $advancePayment->refund();
+
+        return back()->with('success', 'Advance payment refunded.');
+    }
+
+    public function destroy(AdvancePayment $advancePayment): RedirectResponse
+    {
+        $this->authorize('delete', $advancePayment);
+
+        $advancePayment->delete();
+
+        return redirect()->route('finance.advance-payments.index')
+            ->with('success', 'Advance payment deleted.');
+    }
+}

erp/app/Modules/Finance/Models/AdvancePayment.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace App\Modules\Finance\Models;
+
+use App\Models\User;
+use App\Modules\Core\Traits\BelongsToTenant;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+class AdvancePayment extends Model
+{
+    use BelongsToTenant, SoftDeletes;
+
+    protected $fillable = [
+        'tenant_id', 'contact_id', 'reference', 'amount', 'applied_amount',
+        'currency', 'payment_date', 'status', 'payment_method', 'notes',
+        'created_by', 'refunded_at',
+    ];
+
+    protected $casts = [
+        'amount'         => 'float',
+        'applied_amount' => 'float',
+        'payment_date'   => 'date',
+        'refunded_at'    => 'datetime',
+    ];
+
+    public function contact(): BelongsTo
+    {
+        return $this->belongsTo(Contact::class);
+    }
+
+    public function createdBy(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by');
+    }
+
+    public function applyAmount(float $amount): void
+    {
+        $this->applied_amount = min($this->applied_amount + $amount, $this->amount);
+        $this->status = $this->applied_amount >= $this->amount ? 'fully_applied' : 'partially_applied';
+        $this->save();
+    }
+
+    public function refund(): void
+    {
+        $this->status      = 'refunded';
+        $this->refunded_at = now();
+        $this->save();
+    }
+
+    public function getRemainingAmountAttribute(): float
+    {
+        return max(0.0, $this->amount - $this->applied_amount);
+    }
+
+    public function getIsAvailableAttribute(): bool
+    {
+        return $this->status !== 'refunded' && $this->remaining_amount > 0;
+    }
+}

erp/app/Modules/Finance/Policies/AdvancePaymentPolicy.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Modules\Finance\Policies;
+
+use App\Models\User;
+use App\Modules\Finance\Models\AdvancePayment;
+
+class AdvancePaymentPolicy
+{
+    public function viewAny(User $user): bool
+    {
+        return $user->can('finance.view');
+    }
+
+    public function view(User $user, AdvancePayment $advancePayment): bool
+    {
+        return $user->can('finance.view');
+    }
+
+    public function create(User $user): bool
+    {
+        return $user->can('finance.create');
+    }
+
+    public function update(User $user, AdvancePayment $advancePayment): bool
+    {
+        return $user->can('finance.create');
+    }
+
+    public function delete(User $user, AdvancePayment $advancePayment): bool
+    {
+        return $user->can('finance.delete');
+    }
+}

erp/app/Modules/Finance/Providers/FinanceServiceProvider.php

@@ -95,7 +95,9 @@
 use App\Modules\Finance\Policies\PettyCashPolicy;
 use App\Modules\Finance\Models\BankTransfer;
 use App\Modules\Finance\Policies\BankTransferPolicy;
+use App\Modules\Finance\Models\AdvancePayment;
 use App\Modules\Finance\Models\CustomerGroup;
+use App\Modules\Finance\Policies\AdvancePaymentPolicy;
 use App\Modules\Finance\Policies\CustomerGroupPolicy;
 use Illuminate\Support\Facades\Gate;
 use Illuminate\Support\ServiceProvider;
@@ -173,6 +175,7 @@ public function boot(): void
         Gate::policy(PettyCashTransaction::class, PettyCashPolicy::class);
         Gate::policy(BankTransfer::class, BankTransferPolicy::class);
         Gate::policy(CustomerGroup::class, CustomerGroupPolicy::class);
+        Gate::policy(AdvancePayment::class, AdvancePaymentPolicy::class);
         if ($this->app->runningInConsole()) {
             $this->commands([\App\Modules\Finance\Console\Commands\GenerateRecurringInvoices::class]);
         }

erp/app/Modules/Finance/routes/finance.php

@@ -357,3 +357,11 @@
     Route::post('bank-transfers/{bankTransfer}/cancel',   [BankTransferController::class, 'cancel'])->name('bank-transfers.cancel');
     Route::resource('bank-transfers', BankTransferController::class)->except(['create', 'edit', 'update']);
 });
+
+// Advance Payments — custom actions BEFORE resource
+use App\Modules\Finance\Http\Controllers\AdvancePaymentController;
+Route::middleware(['web', 'auth', 'verified'])->prefix('finance')->name('finance.')->group(function () {
+    Route::post('advance-payments/{advancePayment}/apply',  [AdvancePaymentController::class, 'apply'])->name('advance-payments.apply');
+    Route::post('advance-payments/{advancePayment}/refund', [AdvancePaymentController::class, 'refund'])->name('advance-payments.refund');
+    Route::resource('advance-payments', AdvancePaymentController::class)->except(['create', 'edit', 'update']);
+});

erp/database/migrations/2026_08_16_100001_create_advance_payments_table.php

@@ -0,0 +1,34 @@
+<?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('advance_payments', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('tenant_id');
+            $table->unsignedBigInteger('contact_id')->nullable();
+            $table->string('reference')->nullable();
+            $table->decimal('amount', 15, 2);
+            $table->decimal('applied_amount', 15, 2)->default(0);
+            $table->string('currency', 3)->default('USD');
+            $table->date('payment_date');
+            $table->string('status')->default('received');
+            $table->string('payment_method')->nullable();
+            $table->text('notes')->nullable();
+            $table->unsignedBigInteger('created_by')->nullable();
+            $table->timestamp('refunded_at')->nullable();
+            $table->timestamps();
+            $table->softDeletes();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('advance_payments');
+    }
+};

erp/resources/js/Components/Layout/Sidebar.tsx

@@ -151,6 +151,7 @@ const navItems: NavItem[] = [
             { label: 'Payment Terms',    href: '/finance/payment-terms',   icon: <span /> },
             { label: 'Petty Cash',       href: '/finance/petty-cash',       icon: <span /> },
             { label: 'Bank Transfers',    href: '/finance/bank-transfers',    icon: <span /> },
+            { label: 'Advance Payments',  href: '/finance/advance-payments',  icon: <span /> },
         ],
     },
     {

erp/resources/js/Pages/Finance/AdvancePayments/Index.tsx

@@ -0,0 +1,61 @@
+import { Head, Link } from '@inertiajs/react';
+import AppLayout from '@/Layouts/AppLayout';
+import { Table } from '@/Components/Common/Table';
+import { Button } from '@/Components/Common/Button';
+import { Pagination } from '@/Components/Inventory/Pagination';
+import { usePermission } from '@/Hooks/usePermission';
+import type { PageProps } from '@/types';
+import type { AdvancePayment } from '@/types/finance';
+import type { Paginator } from '@/types/inventory';
+
+interface Props extends PageProps {
+    advancePayments: Paginator<AdvancePayment>;
+}
+
+export default function AdvancePaymentsIndex({ advancePayments }: Props) {
+    const { can } = usePermission();
+
+    return (
+        <AppLayout>
+            <Head title="Advance Payments" />
+            <div className="space-y-6">
+                <div className="flex items-center justify-between">
+                    <div>
+                        <h1 className="text-2xl font-semibold text-slate-900">Advance Payments</h1>
+                        <p className="text-sm text-slate-500 mt-1">{advancePayments.total} advance payments</p>
+                    </div>
+                    <div className="flex gap-2">
+                        {can('finance.create') && (
+                            <Link href="/finance/advance-payments/create"><Button>New Advance Payment</Button></Link>
+                        )}
+                    </div>
+                </div>
+
+                <div className="rounded-lg border border-slate-200 bg-white shadow-sm">
+                    <Table
+                        columns={[
+                            { key: 'reference', header: 'Reference', render: (ap) => (
+                                <Link href={`/finance/advance-payments/${ap.id}`} className="font-mono text-sm font-medium text-indigo-600 hover:text-indigo-800">
+                                    {ap.reference ?? `AP-${ap.id}`}
+                                </Link>
+                            )},
+                            { key: 'contact', header: 'Customer', render: (ap) => (ap as any).contact?.name ?? '—' },
+                            { key: 'payment_date', header: 'Payment Date', render: (ap) => ap.payment_date },
+                            { key: 'amount', header: 'Amount', render: (ap) => `${ap.currency} ${Number(ap.amount).toFixed(2)}` },
+                            { key: 'applied_amount', header: 'Applied', render: (ap) => Number(ap.applied_amount).toFixed(2) },
+                            { key: 'remaining_amount', header: 'Remaining', render: (ap) => Number(ap.remaining_amount).toFixed(2) },
+                            { key: 'status', header: 'Status', render: (ap) => (
+                                <span className="capitalize rounded-full bg-slate-100 px-2 py-0.5 text-xs font-medium text-slate-700">
+                                    {ap.status.replace('_', ' ')}
+                                </span>
+                            )},
+                        ]}
+                        data={advancePayments.data}
+                        emptyMessage="No advance payments found."
+                    />
+                    <Pagination paginator={advancePayments} />
+                </div>
+            </div>
+        </AppLayout>
+    );
+}