feat(payments): add customer ledgers and allocations (#744)

app/Http/Requests/PaymentRequest.php

@@ -4,10 +4,9 @@ namespace App\Http\Requests;
 
 use App\Models\CompanySetting;
 use App\Models\Customer;
-use App\Models\Invoice;
-use App\Models\Payment;
 use Illuminate\Foundation\Http\FormRequest;
 use Illuminate\Validation\Rule;
+use Illuminate\Validation\Validator;
 
 class PaymentRequest extends FormRequest
 {
@@ -30,20 +29,21 @@ class PaymentRequest extends FormRequest
             ],
             'customer_id' => [
                 'required',
+                Rule::exists('customers', 'id')->where('company_id', $this->header('company')),
             ],
             'exchange_rate' => [
                 'nullable',
+                'numeric',
+                'gt:0',
             ],
-            'amount' => [
-                'required',
-            ],
+            'amount' => ['required', 'integer', 'min:1'],
             'payment_number' => [
                 'required',
                 Rule::unique('payments')->where('company_id', $this->header('company')),
             ],
-            'invoice_id' => [
-                'nullable',
-            ],
+            'allocations' => ['sometimes', 'array'],
+            'allocations.*.invoice_id' => ['required', 'integer', 'distinct'],
+            'allocations.*.amount' => ['required', 'integer', 'min:1'],
             'payment_method_id' => [
                 'nullable',
             ],
@@ -61,16 +61,6 @@ class PaymentRequest extends FormRequest
             ];
         }
 
-        $maxAmount = $this->maxPayableAmount();
-
-        if ($maxAmount !== null) {
-            $rules['amount'] = [
-                'required',
-                'numeric',
-                'max:'.$maxAmount,
-            ];
-        }
-
         $companyCurrency = CompanySetting::getSetting('currency', $this->header('company'));
 
         $customer = Customer::find($this->customer_id);
@@ -79,6 +69,8 @@ class PaymentRequest extends FormRequest
             if ((string) $customer->currency_id !== $companyCurrency) {
                 $rules['exchange_rate'] = [
                     'required',
+                    'numeric',
+                    'gt:0',
                 ];
             }
         }
@@ -87,68 +79,36 @@ class PaymentRequest extends FormRequest
     }
 
     /**
-     * The message string IS the translation key here, as everywhere else in the
-     * app: the front end maps it to a localized string.
+     * Reject the retired field without advertising it in the generated API
+     * schema. Payment-to-invoice links now exist only inside allocations.
      */
-    public function messages(): array
+    public function withValidator(Validator $validator): void
     {
-        return [
-            'amount.max' => 'payment_amount_exceeds_invoice_due_amount',
-        ];
-    }
-
-    /**
-     * The most that may be paid against the invoice this request names, or null
-     * when the payment is not attached to an invoice and so is uncapped.
-     *
-     * An overpayment used to be accepted and then silently swallowed:
-     * PaymentService hands the amount to Invoice::subtractInvoicePayment(),
-     * which drives the balance negative, and Invoice::getInvoiceStatusByAmount()
-     * returns an empty array for a negative amount, so the status change is
-     * never applied and the invoice keeps a stale balance. Partial credit notes
-     * shrink the balance and make that easy to hit, so the cap is enforced here,
-     * before any of it runs.
-     *
-     * On an edit of a payment that already belongs to this same invoice its own
-     * amount returns to the pool, because PaymentService::update() adds the old
-     * amount back before subtracting the new one.
-     */
-    protected function maxPayableAmount(): ?int
-    {
-        if (! $this->invoice_id) {
-            return null;
-        }
-
-        $invoice = Invoice::find($this->invoice_id);
-
-        if (! $invoice) {
-            return null;
-        }
-
-        $max = (int) $invoice->due_amount;
-
-        $payment = $this->route('payment');
-
-        if ($payment instanceof Payment && (int) $payment->invoice_id === (int) $this->invoice_id) {
-            $max += (int) $payment->amount;
-        }
-
-        return $max;
+        $validator->after(function (Validator $validator): void {
+            if ($this->exists('invoice_id')) {
+                $validator->errors()->add(
+                    'invoice_id',
+                    __('validation.prohibited', ['attribute' => 'invoice id'])
+                );
+            }
+        });
     }
 
     public function getPaymentPayload()
     {
         $company_currency = CompanySetting::getSetting('currency', $this->header('company'));
-        $current_currency = $this->currency_id;
-        $exchange_rate = $company_currency != $current_currency ? $this->exchange_rate : 1;
         $currency = Customer::find($this->customer_id)->currency_id;
+        $exchange_rate = (string) $company_currency !== (string) $currency
+            ? (float) $this->exchange_rate
+            : 1;
 
         return collect($this->validated())
+            ->except('allocations')
             ->merge([
                 'creator_id' => $this->user()->id,
                 'company_id' => $this->header('company'),
                 'exchange_rate' => $exchange_rate,
-                'base_amount' => $this->amount * $exchange_rate,
+                'base_amount' => (int) round($this->amount * $exchange_rate),
                 'currency_id' => $currency,
             ])
             ->toArray();