feat(billing): renewals, coupons, VAT numbering, billing cycles and invoice payment tracking

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

app/Http/Controllers/Api/Admin/Invoice/Concerns/HandlesInvoiceAttachments.php

@@ -32,7 +32,7 @@ trait HandlesInvoiceAttachments
 
         $request->validate([
             'file' => InvoiceAttachment::UPLOAD_RULE,
-            'type' => 'nullable|in:' . InvoiceAttachment::TYPE_PAYMENT_PROOF . ',' . InvoiceAttachment::TYPE_DEPLOYMENT,
+            'type' => 'nullable|in:' . implode(',', [InvoiceAttachment::TYPE_PAYMENT_PROOF, InvoiceAttachment::TYPE_DEPLOYMENT, InvoiceAttachment::TYPE_CONTRACT]),
         ]);
 
         $file     = $request->file('file');

app/Http/Controllers/Api/Admin/Invoice/Concerns/SendsInvoiceNotifications.php

@@ -5,10 +5,12 @@ namespace App\Http\Controllers\Api\Admin\Invoice\Concerns;
 use App\Jobs\Mail\SendInvoiceMailJob;
 use App\Mail\InvoiceNotificationMail;
 use App\Models\Invoice;
+use App\Models\InvoiceAttachment;
 use App\Services\InvoiceReminderService;
 use App\Support\AutoEmailGate;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Http\Response;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Queue;
 
@@ -56,6 +58,26 @@ trait SendsInvoiceNotifications
         ]);
     }
 
+    public function pdf(Request $request, int $id): Response|JsonResponse
+    {
+        $invoice = $this->invoiceRepository->find($id);
+        if (!$invoice) {
+            return response()->json(['error' => true, 'message' => "Can't find invoice #$id"], 404);
+        }
+
+        $vat = $request->query('variant') === 'vat';
+        if ($vat && !$invoice->vat_number) {
+            return response()->json(['error' => true, 'message' => 'Hoá đơn chưa được cấp số VAT'], 422);
+        }
+
+        $fileName = $vat ? $this->invoicePdfService->vatFileName($invoice) : $this->invoicePdfService->generateFileName($invoice);
+
+        return response($this->invoicePdfService->generate($invoice), 200, [
+            'Content-Type' => 'application/pdf',
+            'Content-Disposition' => 'inline; filename="' . $fileName . '"',
+        ]);
+    }
+
     public function previewMail(Request $request, int $id): JsonResponse
     {
         $invoice = $this->invoiceForMail($request, $id);
@@ -72,6 +94,8 @@ trait SendsInvoiceNotifications
                 'subject'             => $mail->envelope()->subject,
                 'html'                => $mail->render(),
                 'attachment_filename' => $this->invoicePdfService->generateFileName($invoice),
+                'vat_attachment_filename' => $invoice->vat_number ? $this->invoicePdfService->vatFileName($invoice) : null,
+                'contracts' => $this->contractsOf($invoice)->map(fn (InvoiceAttachment $file) => ['id' => $file->id, 'filename' => $file->filename])->values(),
             ],
         ]);
     }
@@ -95,6 +119,8 @@ trait SendsInvoiceNotifications
             $request->input('subject'),
             $request->filled('html') ? $request->input('html') : null,
             Auth::guard('admin')->id(),
+            $request->boolean('attach_vat'),
+            $this->contractsOf($invoice)->whereIn('id', (array) $request->input('contract_ids', []))->pluck('id')->all(),
         ));
 
         return response()->json([
@@ -119,6 +145,9 @@ trait SendsInvoiceNotifications
             'type'    => 'nullable|string|in:invoice,renewal',
             'subject' => 'nullable|required_with:html|string|max:255',
             'html'    => 'nullable|required_with:subject|string|max:500000',
+            'attach_vat' => 'nullable|boolean',
+            'contract_ids' => 'nullable|array|max:10',
+            'contract_ids.*' => 'integer',
         ]);
 
         $invoice = $this->invoiceRepository->find($id);
@@ -131,6 +160,18 @@ trait SendsInvoiceNotifications
             return response()->json(['error' => true, 'message' => 'Customer email not found'], 422);
         }
 
+        if ($request->boolean('attach_vat') && !$invoice->vat_number) {
+            return response()->json(['error' => true, 'message' => 'Hoá đơn chưa được cấp số VAT, không thể đính kèm hoá đơn VAT'], 422);
+        }
+
         return $invoice;
     }
+
+    private function contractsOf(Invoice $invoice)
+    {
+        return InvoiceAttachment::query()
+            ->where('invoice_id', $invoice->id)
+            ->where('type', InvoiceAttachment::TYPE_CONTRACT)
+            ->get();
+    }
 }

app/Http/Controllers/Api/Admin/Invoice/InvoiceController.php

@@ -42,7 +42,9 @@ class InvoiceController extends Controller
 
     public function index(Request $request): JsonResponse
     {
-        $query = $this->invoiceRepository->filter(
+        $perPage = min((int) $request->get('per_page', 15), 100);
+
+        $data = $this->invoiceRepository->filter(
             $request->all(),
             [
                 'payment',
@@ -54,13 +56,14 @@ class InvoiceController extends Controller
             [],
             ['*'],
             true
-        );
+        )->paginate($perPage);
 
         return response()->json([
             'error' => false,
             'data' => [
-                'items' => InvoiceResource::collection($query->get())->resolve(),
-                'total' => $query->count(),
+                'items' => InvoiceResource::collection($data->items())->resolve(),
+                'total' => $data->total(),
+                'per_page' => $data->perPage(),
             ],
         ]);
     }

app/Http/Controllers/Api/Admin/Invoice/InvoiceVatController.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace App\Http\Controllers\Api\Admin\Invoice;
+
+use App\Http\Controllers\Controller;
+use App\Enums\Invoice\InvoiceStatus;
+use App\Models\Invoice;
+use App\Support\InvoiceBuyer;
+use App\Support\VatNumbering;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Validation\Rule;
+
+class InvoiceVatController extends Controller
+{
+    public function show(int $id): JsonResponse
+    {
+        return response()->json(['error' => false, 'data' => $this->payload(Invoice::with('customer')->findOrFail($id))]);
+    }
+
+    public function update(Request $request, int $id): JsonResponse
+    {
+        $invoice = Invoice::with('customer')->findOrFail($id);
+
+        $data = $request->validate([
+            'vat_serial' => 'nullable|string|max:20|required_with:vat_number',
+            'vat_number' => [
+                'nullable', 'string', 'max:30', 'required_with:vat_serial',
+                Rule::unique('invoices', 'vat_number')
+                    ->where('vat_serial', $request->input('vat_serial'))
+                    ->ignore($invoice->id),
+            ],
+            'vat_issued_at' => 'nullable|date|required_with:vat_number',
+            'refresh_buyer' => 'sometimes|boolean',
+        ]);
+
+        $invoice->fill([
+            'vat_serial' => $data['vat_serial'] ?? null,
+            'vat_number' => $data['vat_number'] ?? null,
+            'vat_issued_at' => $data['vat_issued_at'] ?? null,
+        ]);
+
+        if (!$invoice->vat_number) {
+            $invoice->buyer_snapshot = null;
+        } elseif (!$invoice->buyer_snapshot || ($data['refresh_buyer'] ?? false)) {
+            $invoice->buyer_snapshot = InvoiceBuyer::fromCustomer($invoice->customer);
+        }
+
+        $invoice->save();
+
+        return response()->json(['error' => false, 'message' => 'Đã lưu thông tin hóa đơn VAT', 'data' => $this->payload($invoice)]);
+    }
+
+    public function issue(int $id): JsonResponse
+    {
+        $invoice = Invoice::findOrFail($id);
+
+        if ($invoice->vat_number) {
+            return response()->json(['error' => true, 'message' => 'Hóa đơn đã có số VAT'], 422);
+        }
+
+        if ((int) $invoice->status === InvoiceStatus::CANCELLED->value) {
+            return response()->json(['error' => true, 'message' => 'Không thể cấp số VAT cho hóa đơn đã huỷ'], 422);
+        }
+
+        $invoice = VatNumbering::issue($invoice);
+
+        return response()->json(['error' => false, 'message' => 'Đã cấp số hóa đơn VAT', 'data' => $this->payload($invoice)]);
+    }
+
+    private function payload(Invoice $invoice): array
+    {
+        return [
+            'lookup_code' => $invoice->lookup_code,
+            'vat_serial' => $invoice->vat_serial,
+            'vat_number' => $invoice->vat_number,
+            'vat_issued_at' => $invoice->vat_issued_at?->toDateString(),
+            'buyer' => InvoiceBuyer::forInvoice($invoice),
+            'buyer_locked' => (bool) $invoice->buyer_snapshot,
+        ];
+    }
+}