feat(asaas): ramo STU_ no webhook para baixar a parcela do aluno quando paga

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app/Jobs/ProcessAsaasWebhookJob.php

@@ -50,6 +50,12 @@ public function handle(): void
         $externalReference = $payment['externalReference'] ?? null;
         $asaasId           = $payment['id'] ?? null;
 
+        // Cobrança de aluno (parcela) cobrada pela conta Asaas PRÓPRIA da unidade.
+        if ($externalReference && str_starts_with($externalReference, 'STU_')) {
+            $this->handleStudentInstallment($externalReference, $payment, $event, $newStatus);
+            return;
+        }
+
         $receive = null;
         $type = 'unknown';
 
@@ -131,4 +137,53 @@ public function handle(): void
             'asaas_id' => $asaasId,
         ]);
     }
+
+    /**
+     * Baixa/atualiza a parcela do aluno cobrada pela conta Asaas da unidade.
+     */
+    private function handleStudentInstallment(string $externalReference, array $payment, string $event, ReceivableStatus $newStatus): void
+    {
+        $id = str_replace('STU_', '', $externalReference);
+
+        $installment = \App\Models\StudentContractInstallment::find($id);
+
+        if (!$installment) {
+            Log::warning("Asaas Webhook Job: parcela {$externalReference} não encontrada.", [
+                'event' => $event,
+                'asaas_id' => $payment['id'] ?? null,
+            ]);
+            return;
+        }
+
+        // Mapeia o status do recebível para o vocabulário das parcelas.
+        $statusMap = [
+            ReceivableStatus::PAID->value      => 'paid',
+            ReceivableStatus::OVERDUE->value   => 'overdue',
+            ReceivableStatus::CANCELLED->value => 'cancelled',
+        ];
+        $installmentStatus = $statusMap[$newStatus->value] ?? $installment->status;
+
+        // Idempotência: já pago e continua pago → ignora duplicata.
+        if ($installment->status === 'paid' && $installmentStatus === 'paid') {
+            Log::info("Asaas Webhook Job: parcela #{$installment->id} já paga. Ignorando duplicata.");
+            return;
+        }
+
+        $update = [
+            'status'       => $installmentStatus,
+            'asaas_status' => $payment['status'] ?? $event,
+        ];
+
+        if ($installmentStatus === 'paid') {
+            $update['payment_date'] = $payment['paymentDate'] ?? $payment['confirmedDate'] ?? now();
+            $update['paid_value']   = $payment['value'] ?? $installment->value;
+        }
+
+        $installment->update($update);
+
+        Log::info("Asaas Webhook Job: parcela #{$installment->id} atualizada para '{$installmentStatus}'.", [
+            'event' => $event,
+            'asaas_id' => $payment['id'] ?? null,
+        ]);
+    }
 }