feat: TBR usa o mês de competência escolhido na geração do título

Persiste reference_year/reference_month no cálculo e usa esse período
(não a data de geração) para o histórico e o vencimento do
franchisee_account_receive. Antes caía em created_at.

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

app/Services/TbrCalculationService.php

@@ -293,6 +293,8 @@ private function persistCalculation(array $payload): TbrCalculation
     {
         return TbrCalculation::create([
             'unit_id'                          => $payload['unit_id'],
+            'reference_year'                   => $payload['reference_year'],
+            'reference_month'                  => $payload['reference_month'],
             'revenue_value'                    => $payload['revenue_value'],
             'contract_month_reference'         => $payload['contract_month_reference'],
             'tbr_value'                        => $payload['tbr_value'],
@@ -320,7 +322,10 @@ private function persistCalculation(array $payload): TbrCalculation
 
     private function buildReceivable(TbrCalculation $calculation, ?FranchiseeContract $contract): FranchiseeAccountReceive
     {
-        $referenceDate  = Carbon::parse($calculation->created_at);
+        // Mês de competência = o que a pessoa escolheu ao gerar (não a data de geração).
+        $referenceDate  = $calculation->reference_year && $calculation->reference_month
+            ? Carbon::create($calculation->reference_year, $calculation->reference_month, 1)
+            : Carbon::parse($calculation->created_at);
         $referenceLabel = $referenceDate->format('m/Y');
         $dueDate        = $this->resolveDueDate($contract, $referenceDate);
 

database/migrations/2026_06_17_151821_add_reference_period_to_tbr_calculations_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('tbr_calculations', function (Blueprint $table) {
+            $table->unsignedSmallInteger('reference_year')->nullable()->after('unit_id');
+            $table->unsignedTinyInteger('reference_month')->nullable()->after('reference_year');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('tbr_calculations', function (Blueprint $table) {
+            $table->dropColumn(['reference_year', 'reference_month']);
+        });
+    }
+};