refactor(receivables): rewrite legacy-era regions of the allocation model, requests, pdf controller and routes in place

app/Domains/Receivables/Http/Controllers/PaymentPdfController.php

@@ -7,6 +7,13 @@ use App\Domains\Receivables\Models\Payment;
 use App\Platform\Http\Controller;
 use Illuminate\Http\Request;
 
+/**
+ * Serves the receipt behind a payment's public hash.
+ *
+ * Asking for a preview short-circuits to the view data the template is
+ * rendered from, so the layout can be looked at without a PDF engine in
+ * the loop; every other caller gets the file itself.
+ */
 class PaymentPdfController extends Controller
 {
     public function __construct(
@@ -19,6 +26,8 @@ class PaymentPdfController extends Controller
             return $this->paymentPdfDataProvider->getPdfData($payment);
         }
 
-        return $payment->getGeneratedPDFOrStream('payment');
+        $receipt = $payment->getGeneratedPDFOrStream('payment');
+
+        return $receipt;
     }
 }

app/Domains/Receivables/Http/Requests/CreditAllocationRequest.php

@@ -7,7 +7,8 @@ use Illuminate\Foundation\Http\FormRequest;
 class CreditAllocationRequest extends FormRequest
 {
     /**
-     * Determine if the user is authorized to make this request.
+     * Access is settled by the controller, which weighs the customer and
+     * every payment named in the payload; this class only shapes input.
      */
     public function authorize(): bool
     {
@@ -15,7 +16,7 @@ class CreditAllocationRequest extends FormRequest
     }
 
     /**
-     * Get the validation rules that apply to the request.
+     * Credit rows: which payment covers which invoice, and by how much.
      *
      * @return array<string, array<int, string>>
      */

app/Domains/Receivables/Http/Requests/ReplacePaymentAllocationsRequest.php

@@ -7,7 +7,8 @@ use Illuminate\Foundation\Http\FormRequest;
 class ReplacePaymentAllocationsRequest extends FormRequest
 {
     /**
-     * Determine if the user is authorized to make this request.
+     * Access is settled by the controller, against the payment whose rows
+     * are being re-cut; this class only shapes input.
      */
     public function authorize(): bool
     {
@@ -15,7 +16,7 @@ class ReplacePaymentAllocationsRequest extends FormRequest
     }
 
     /**
-     * Get the validation rules that apply to the request.
+     * The complete row set for one payment; an empty list clears it.
      *
      * @return array<string, array<int, string>>
      */

app/Domains/Receivables/Models/PaymentAllocation.php

@@ -23,13 +23,19 @@ class PaymentAllocation extends Model
         ];
     }
 
+    /**
+     * The receipt this slice was taken out of.
+     */
     public function payment(): BelongsTo
     {
-        return $this->belongsTo(Payment::class);
+        return $this->belongsTo(Payment::class, 'payment_id');
     }
 
+    /**
+     * The document this slice was booked against.
+     */
     public function invoice(): BelongsTo
     {
-        return $this->belongsTo(Invoice::class);
+        return $this->belongsTo(Invoice::class, 'invoice_id');
     }
 }

app/Domains/Receivables/routes/company.php

@@ -9,6 +9,9 @@ Route::post('customers/{customer}/credit-allocations', [CreditAllocationsControl
 Route::get('/payments/{payment}/send/preview', [PaymentsController::class, 'sendPreview']);
 Route::post('/payments/{payment}/send', [PaymentsController::class, 'send']);
 Route::put('/payments/{payment}/allocations', [PaymentsController::class, 'replaceAllocations']);
-Route::post('/payments/delete', [PaymentsController::class, 'delete']);
-Route::apiResource('payments', PaymentsController::class);
-Route::apiResource('payment-methods', PaymentMethodsController::class);
+Route::post('payments/delete', [PaymentsController::class, 'delete']);
+
+Route::apiResources([
+    'payments' => PaymentsController::class,
+    'payment-methods' => PaymentMethodsController::class,
+]);

app/Domains/Receivables/routes/customer.php

@@ -6,4 +6,5 @@ use Illuminate\Support\Facades\Route;
 
 Route::get('payments', [PaymentsController::class, 'index']);
 Route::get('payments/{id}', [PaymentsController::class, 'show']);
-Route::get('/payment-method', PaymentMethodController::class);
+// Every method on the company's books is offered here, unfiltered.
+Route::get('payment-method', PaymentMethodController::class);