sfp_api_laravel_ginastica_cerebro/app/Services/TbrCalculationService.php

<?php

namespace App\Services;

use App\Models\FranchiseeAccountReceive;
use App\Models\FranchiseeAccountReceiveDetail;
use App\Models\FranchiseeContract;
use App\Models\InhabitantClassification;
use App\Models\StudentContractInstallment;
use App\Models\Tbr;
use App\Models\TbrCalculation;
use App\Models\UnitAccountReceivable;
use App\Models\UnitFinancial;
use Carbon\Carbon;
use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\DB;
use Illuminate\Validation\ValidationException;

class TbrCalculationService
{
    private const ROYALTIES_REVENUE_RATE = 0.08;

    private const FNM_REVENUE_RATE = 0.02;

    private const FNM_BRACKET_PERCENTAGE = 0.20;

    private const MAINTENANCE_RATE = 0.30;

    private const EXEMPT_THRESHOLD_MONTH = 3;

    // Faixas de royalties (is_renewal=false) cobrem os meses 1-60 do primeiro
    // ciclo contratual. A partir do mês 61 o contrato entra em renovação: o mês
    // de contrato é "enrolado" de volta para o intervalo 1-60 para buscar a
    // faixa de renovação (is_renewal=true) equivalente.
    private const RENEWAL_CYCLE_MONTHS = 60;

    // Faturamento (competência): por padrão usa o próprio mês de referência
    // (Opção A — assume-se o mês já fechado ao gerar). Ligue para usar o mês
    // anterior fechado (Opção B) quando a geração ocorrer dentro do mês corrente.
    private const REVENUE_FROM_PREVIOUS_MONTH = false;

    /**
     * Faturamento da unidade no mês (competência): soma das parcelas de aluno com
     * vencimento no mês, de contratos não cancelados. Alimenta a regra "maior entre
     * valor fixo e % do faturamento".
     */
    public function resolveRevenue(int $unitId, int $referenceYear, int $referenceMonth): float
    {
        $base = Carbon::createFromDate($referenceYear, $referenceMonth, 1);

        if (self::REVENUE_FROM_PREVIOUS_MONTH) {
            $base = $base->subMonthNoOverflow();
        }

        return $this->resolveRevenueBetween(
            [$unitId],
            $base->copy()->startOfMonth(),
            $base->copy()->endOfMonth(),
        );
    }

    /**
     * Faturamento-base do TBR em um intervalo. Mantém dashboard e geração do TBR
     * usando a mesma composição: parcelas de alunos + recebíveis avulsos.
     * Um array vazio de unidades representa toda a rede.
     */
    public function resolveRevenueBetween(array $unitIds, Carbon $startDate, Carbon $endDate): float
    {
        $start = $startDate->toDateString();
        $end = $endDate->toDateString();

        // Base de faturamento = parcelas de aluno + recebíveis avulsos da unidade
        // + contas manuais que a franqueadora vinculou à unidade. Recebíveis de
        // TBR ficam fora para não realimentar a própria base de cálculo.
        $installments = (float) StudentContractInstallment::whereNull('deleted_at')
            ->when(! empty($unitIds), fn ($q) => $q->whereIn('unit_id', $unitIds))
            ->where('status', '!=', 'cancelled')
            ->whereBetween('due_date', [$start, $end])
            ->sum('value');

        $manual = (float) UnitAccountReceivable::whereNull('deleted_at')
            ->when(! empty($unitIds), fn ($q) => $q->whereIn('unit_id', $unitIds))
            ->where('status', '!=', 'cancelled')
            ->whereBetween('due_date', [$start, $end])
            ->sum('value');

        $franchisorLinked = (float) FranchiseeAccountReceive::whereNull('deleted_at')
            ->where('origin', 'manual_unit')
            ->whereNotNull('unit_id')
            ->when(! empty($unitIds), fn ($q) => $q->whereIn('unit_id', $unitIds))
            ->where('status', '!=', 'cancelled')
            ->whereBetween('due_date', [$start, $end])
            ->sum('value');

        return $installments + $manual + $franchisorLinked;
    }

    /**
     * Faturamento do cálculo individual: usa o valor informado manualmente
     * (override) quando > 0; senão calcula automaticamente pelas parcelas do mês.
     */
    private function pickRevenue(array $data, int $unitId, int $year, int $month): float
    {
        $manual = (float) ($data['revenue_value'] ?? 0);

        return $manual > 0 ? $manual : $this->resolveRevenue($unitId, $year, $month);
    }

    public function paginate(int $perPage = 15): LengthAwarePaginator
    {
        return TbrCalculation::with(['unit', 'user'])
            ->orderBy('created_at', 'desc')
            ->paginate($perPage);
    }

    public function listAll(int $limit = 100): \Illuminate\Database\Eloquent\Collection
    {
        return TbrCalculation::with(['unit', 'user'])
            ->orderBy('created_at', 'desc')
            ->limit($limit)
            ->get();
    }

    public function findById(int $id): ?TbrCalculation
    {
        return TbrCalculation::with([
            'unit',
            'user',
            'royaltiesBracket',
        ])->find($id);
    }

    public function preview(array $data): array
    {
        $contract = $this->resolveContract($data['unit_id']);
        $year = (int) $data['reference_year'];
        $month = (int) $data['reference_month'];

        return $this->buildPreview($contract, $year, $month, $this->pickRevenue($data, $contract->unit_id, $year, $month));
    }

    public function previewBatch(int $referenceYear, int $referenceMonth): array
    {
        $contracts = $this->loadActiveContracts($referenceYear, $referenceMonth);

        return $contracts->map(function (FranchiseeContract $contract) use ($referenceYear, $referenceMonth) {
            try {
                $revenue = $this->resolveRevenue($contract->unit_id, $referenceYear, $referenceMonth);

                return $this->buildPreview($contract, $referenceYear, $referenceMonth, $revenue);
            } catch (ValidationException $e) {
                return [
                    'unit_id' => $contract->unit_id,
                    'unit_name' => $contract->unit?->fantasy_name,
                    'error' => collect($e->errors())->flatten()->first(),
                ];
            }
        })->values()->toArray();
    }

    public function calculate(array $data): TbrCalculation
    {
        return DB::transaction(function () use ($data) {
            $contract = $this->resolveContract($data['unit_id']);
            $year = (int) $data['reference_year'];
            $month = (int) $data['reference_month'];
            $payload = $this->buildPreview($contract, $year, $month, $this->pickRevenue($data, $contract->unit_id, $year, $month));

            return $this->persistCalculation($payload);
        });
    }

    public function generateReceivable(int $calculationId): FranchiseeAccountReceive
    {
        return DB::transaction(function () use ($calculationId) {
            $calculation = TbrCalculation::lockForUpdate()->findOrFail($calculationId);

            if ($calculation->receivable_generated) {
                throw ValidationException::withMessages([
                    'tbr_calculation_id' => 'Já existe um título gerado para este cálculo.',
                ]);
            }

            $duplicate = TbrCalculation::where('unit_id', $calculation->unit_id)
                ->where('contract_month_reference', $calculation->contract_month_reference)
                ->where('receivable_generated', true)
                ->where('id', '!=', $calculation->id)
                ->exists();

            if ($duplicate) {
                throw ValidationException::withMessages([
                    'tbr_calculation_id' => 'Já existe um título gerado para esta unidade no mês de contrato '
                        .$calculation->contract_month_reference.'.',
                ]);
            }

            $contract = FranchiseeContract::where('unit_id', $calculation->unit_id)
                ->orderByDesc('start_date')
                ->first();

            return $this->buildReceivable($calculation, $contract);
        });
    }

    public function generateBatch(int $referenceYear, int $referenceMonth, ?array $unitIds = null): array
    {
        $contracts = $this->loadActiveContracts($referenceYear, $referenceMonth);

        if ($unitIds !== null) {
            $contracts = $contracts->filter(fn ($c) => in_array($c->unit_id, $unitIds, true))->values();
        }

        $generated = [];
        $skipped = [];
        $errors = [];

        foreach ($contracts as $contract) {
            try {
                DB::transaction(function () use ($contract, $referenceYear, $referenceMonth, &$generated, &$skipped) {
                    $revenue = $this->resolveRevenue($contract->unit_id, $referenceYear, $referenceMonth);
                    $payload = $this->buildPreview($contract, $referenceYear, $referenceMonth, $revenue);

                    if ($payload['receivable_already_generated']) {
                        $skipped[] = [
                            'unit_id' => $contract->unit_id,
                            'unit_name' => $payload['unit_name'],
                            'reason' => 'Já gerado para este mês de contrato.',
                        ];

                        return;
                    }

                    $calculation = $this->persistCalculation($payload);
                    $receive = $this->buildReceivable($calculation, $contract);

                    $generated[] = [
                        'unit_id' => $contract->unit_id,
                        'unit_name' => $payload['unit_name'],
                        'tbr_calculation_id' => $calculation->id,
                        'receivable_id' => $receive->id,
                        'total' => $payload['final_value'],
                    ];
                });
            } catch (ValidationException $e) {
                $errors[] = [
                    'unit_id' => $contract->unit_id,
                    'unit_name' => $contract->unit?->fantasy_name,
                    'reason' => collect($e->errors())->flatten()->first(),
                ];
            } catch (\Throwable $e) {
                $errors[] = [
                    'unit_id' => $contract->unit_id,
                    'unit_name' => $contract->unit?->fantasy_name,
                    'reason' => $e->getMessage(),
                ];
            }
        }

        return [
            'generated_count' => count($generated),
            'skipped_count' => count($skipped),
            'error_count' => count($errors),
            'generated' => $generated,
            'skipped' => $skipped,
            'errors' => $errors,
        ];
    }

    private function loadActiveContracts(int $referenceYear, int $referenceMonth): \Illuminate\Support\Collection
    {
        $referenceLastDay = Carbon::createFromDate($referenceYear, $referenceMonth, 1)->endOfMonth()->toDateString();
        $referenceFirstDay = Carbon::createFromDate($referenceYear, $referenceMonth, 1)->startOfMonth()->toDateString();

        return FranchiseeContract::with(['unit', 'municipalitySize'])
            ->whereNotNull('start_date')
            ->whereNotNull('municipality_size_id')
            ->where('start_date', '<=', $referenceLastDay)
            ->where(function ($q) use ($referenceFirstDay) {
                $q->whereNull('end_date')->orWhere('end_date', '>=', $referenceFirstDay);
            })
            ->orderByDesc('start_date')
            ->orderByDesc('id')
            ->get()
            ->unique('unit_id')
            ->values();
    }

    private function resolveContract(int $unitId): FranchiseeContract
    {
        $contract = FranchiseeContract::with(['unit', 'municipalitySize'])
            ->where('unit_id', $unitId)
            ->whereNotNull('start_date')
            ->orderByDesc('start_date')
            ->orderByDesc('id')
            ->first();

        if (! $contract) {
            throw ValidationException::withMessages([
                'unit_id' => 'Unidade não possui contrato cadastrado.',
            ]);
        }

        if (! $contract->municipality_size_id) {
            throw ValidationException::withMessages([
                'unit_id' => 'O contrato da unidade não tem a faixa de habitantes definida. Edite o contrato para informá-la.',
            ]);
        }

        return $contract;
    }

    private function buildPreview(FranchiseeContract $contract, int $referenceYear, int $referenceMonth, float $revenueValue): array
    {
        $tbrConfig = Tbr::where('year', $referenceYear)->orderByDesc('id')->first();

        // A TBR do ano configurada pelo admin manda: é a tabela oficial da rede.
        // O valor gravado no contrato só entra quando o ano não está configurado.
        $tbrValue = (float) ($tbrConfig->tbr_value ?? 0);

        if ($tbrValue <= 0) {
            $tbrValue = (float) ($contract->tbr_fixed_value ?? 0);
        }

        if ($tbrValue <= 0) {
            throw ValidationException::withMessages([
                'unit_id' => 'TBR não definida para o ano de referência nem para o contrato.',
            ]);
        }

        $fnmPercentageConfig = $tbrConfig ? (float) $tbrConfig->fnm_percentage : self::FNM_BRACKET_PERCENTAGE;
        $maintenancePercentageConfig = $tbrConfig ? (float) $tbrConfig->maintenance_percentage : self::MAINTENANCE_RATE;
        // % de faturamento dos Royalties ("Royalties %" em Configurações do TBR):
        // controla só o lado do faturamento da comparação "maior valor" — o lado
        // fixo continua vindo direto da faixa de porte (Classificação de Habitantes),
        // sem escala nenhuma, confirmado pelos cenários reais do cliente.
        $royaltiesRevenueRate = $tbrConfig ? (float) $tbrConfig->royalties_percentage : self::ROYALTIES_REVENUE_RATE;

        $contractMonth = $this->resolveContractMonth($contract->start_date, $referenceYear, $referenceMonth);
        $municipalitySizeId = (int) $contract->municipality_size_id;

        // Flags de cobrança da unidade (sem registro financeiro => cobra, padrão).
        $financial = UnitFinancial::where('unit_id', $contract->unit_id)->first();
        $chargeRoi = $financial ? (bool) $financial->charge_roi : true;
        $chargeFnm = $financial ? (bool) $financial->charge_fnm : true;

        // Royalties só busca a faixa quando há cobrança; desligado não exige faixa.
        // O percentual da faixa de porte JÁ é o percentual final do lado FIXO sobre a
        // TBR (confirmado pelos cenários do cliente: faixa 40%/1.621 = R$648,40 direto,
        // sem taxa-base intermediária). tbrs.royalties_percentage não entra nesse lado —
        // ele controla só o percentual do lado FATURAMENTO (ver $royaltiesRevenueRate).
        $royaltiesBracket = $chargeRoi
            ? $this->findRoyaltiesBracket($municipalitySizeId, $contractMonth)
            : null;
        $royaltiesBracketPercentage = $royaltiesBracket ? (float) $royaltiesBracket->tbr_percentage : 0.0;

        $fnmPercentage = $chargeFnm ? $this->resolveFnmPercentage($contractMonth, $fnmPercentageConfig) : 0.0;
        $maintenancePercentage = $maintenancePercentageConfig;

        $royaltiesBracketValue = round($royaltiesBracketPercentage * $tbrValue, 2);
        $fnmBracketValue = round($fnmPercentage * $tbrValue, 2);
        $maintenanceBracketValue = round($maintenancePercentage * $tbrValue, 2);

        [$royaltiesEffectiveValue, $royaltiesEffectivePercentage, $royaltiesAppliedCriteria,
            $fnmEffectiveValue, $fnmEffectivePercentage] = $this->resolveEffectiveValues(
                $contractMonth,
                $revenueValue,
                $royaltiesBracketPercentage,
                $royaltiesBracketValue,
                $royaltiesRevenueRate,
                $fnmPercentage,
                $fnmBracketValue,
            );

        // Cobrança desligada: zera o respectivo componente (fora do total).
        if (! $chargeRoi) {
            $royaltiesEffectiveValue = 0.0;
            $royaltiesEffectivePercentage = 0.0;
            $royaltiesAppliedCriteria = 'nao_cobrado';
        }

        if (! $chargeFnm) {
            $fnmEffectiveValue = 0.0;
            $fnmEffectivePercentage = 0.0;
        }

        $maintenanceEffectiveValue = $maintenanceBracketValue;
        $maintenanceEffectivePercentage = $maintenancePercentage;

        $bracketSubtotal = round($royaltiesBracketValue + $fnmBracketValue + $maintenanceBracketValue, 2);
        $subtotal = round($royaltiesEffectiveValue + $fnmEffectiveValue + $maintenanceEffectiveValue, 2);

        return [
            'unit_id' => $contract->unit_id,
            'unit_name' => $contract->unit?->fantasy_name,
            'contract_id' => $contract->id,
            'reference_year' => $referenceYear,
            'reference_month' => $referenceMonth,
            'contract_month_reference' => $contractMonth,
            'revenue_value' => $revenueValue,
            'tbr_value' => $tbrValue,
            'municipality_size_id' => $municipalitySizeId,
            'municipality_size_name' => $contract->municipalitySize?->description,
            'royalties_bracket_id' => $royaltiesBracket?->id,
            'royalties_bracket_percentage' => $royaltiesBracketPercentage,
            'royalties_bracket_value' => $royaltiesBracketValue,
            'fnm_bracket_percentage' => $fnmPercentage,
            'fnm_bracket_value' => $fnmBracketValue,
            'maintenance_bracket_percentage' => $maintenancePercentage,
            'maintenance_bracket_value' => $maintenanceBracketValue,
            'royalties_effective_percentage' => $royaltiesEffectivePercentage,
            'royalties_effective_value' => $royaltiesEffectiveValue,
            'fnm_effective_percentage' => $fnmEffectivePercentage,
            'fnm_effective_value' => $fnmEffectiveValue,
            'maintenance_effective_percentage' => $maintenanceEffectivePercentage,
            'maintenance_effective_value' => $maintenanceEffectiveValue,
            'bracket_subtotal' => $bracketSubtotal,
            'subtotal' => $subtotal,
            'final_value' => $subtotal,
            'royalties_applied_criteria' => $royaltiesAppliedCriteria,
            'receivable_already_generated' => $this->existingReceivable($contract->unit_id, $contractMonth),
        ];
    }

    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'],
            'royalties_bracket_id' => $payload['royalties_bracket_id'],
            'royalties_bracket_percentage' => $payload['royalties_bracket_percentage'],
            'royalties_bracket_value' => $payload['royalties_bracket_value'],
            'fnm_bracket_percentage' => $payload['fnm_bracket_percentage'],
            'fnm_bracket_value' => $payload['fnm_bracket_value'],
            'maintenance_bracket_percentage' => $payload['maintenance_bracket_percentage'],
            'maintenance_bracket_value' => $payload['maintenance_bracket_value'],
            'royalties_effective_percentage' => $payload['royalties_effective_percentage'],
            'royalties_effective_value' => $payload['royalties_effective_value'],
            'fnm_effective_percentage' => $payload['fnm_effective_percentage'],
            'fnm_effective_value' => $payload['fnm_effective_value'],
            'maintenance_effective_percentage' => $payload['maintenance_effective_percentage'],
            'maintenance_effective_value' => $payload['maintenance_effective_value'],
            'bracket_subtotal' => $payload['bracket_subtotal'],
            'subtotal' => $payload['subtotal'],
            'final_value' => $payload['final_value'],
            'user_id' => Auth::id(),
            'royalties_applied_criteria' => $payload['royalties_applied_criteria'],
            'receivable_generated' => false,
        ]);
    }

    private function buildReceivable(TbrCalculation $calculation, ?FranchiseeContract $contract): FranchiseeAccountReceive
    {
        // 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);

        $receive = FranchiseeAccountReceive::create([
            'unit_id' => $calculation->unit_id,
            'tbr_calculation_id' => $calculation->id,
            'order' => $calculation->contract_month_reference,
            'history' => 'Royalties / FNM / Manutenção — '.$referenceLabel,
            'value' => $calculation->final_value,
            'paid_value' => 0,
            'due_date' => $dueDate,
            'discount' => 0,
            'fees' => 0,
            'obs' => null,
            'asaas_id' => null,
            'status' => 'pending',
        ]);

        FranchiseeAccountReceiveDetail::create([
            'franchisee_account_receive_id' => $receive->id,
            'value' => $calculation->royalties_effective_value,
            'history' => 'Royalties '.$referenceLabel,
        ]);

        FranchiseeAccountReceiveDetail::create([
            'franchisee_account_receive_id' => $receive->id,
            'value' => $calculation->fnm_effective_value,
            'history' => 'FNM '.$referenceLabel,
        ]);

        FranchiseeAccountReceiveDetail::create([
            'franchisee_account_receive_id' => $receive->id,
            'value' => $calculation->maintenance_effective_value,
            'history' => 'Taxa Manutenção '.$referenceLabel,
        ]);

        $calculation->update(['receivable_generated' => true]);

        // Espelho na unidade: o TBR que a matriz cobra vira uma Conta a Pagar da
        // franquia (ciclo próprio, com ou sem Asaas). A dívida é registrada sempre.
        \App\Models\UnitAccountPayable::create([
            'unit_id' => $receive->unit_id,
            'franchisee_account_receive_id' => $receive->id,
            'origin' => \App\Models\UnitAccountPayable::ORIGIN_TBR,
            'history' => $receive->history,
            'value' => $receive->value,
            'paid_value' => 0,
            'discount' => 0,
            'fine' => 0,
            'due_date' => $receive->due_date,
            'status' => 'pending',
        ]);

        \App\Jobs\SyncFranchiseeChargeJob::dispatch($receive);

        return $receive->load('details');
    }

    private function resolveEffectiveValues(
        int $contractMonth,
        float $revenueValue,
        float $royaltiesBracketPercentage,
        float $royaltiesBracketValue,
        float $royaltiesRevenueRate,
        float $fnmBracketPercentage,
        float $fnmBracketValue,
    ): array {
        if ($contractMonth <= self::EXEMPT_THRESHOLD_MONTH) {
            return [0.0, 0.0, 'tbr_fixo', 0.0, 0.0];
        }

        $royaltiesFromRevenue = round($royaltiesRevenueRate * $revenueValue, 2);
        $fnmFromRevenue = round(self::FNM_REVENUE_RATE * $revenueValue, 2);

        if ($royaltiesBracketValue >= $royaltiesFromRevenue) {
            $royaltiesEffectiveValue = $royaltiesBracketValue;
            $royaltiesEffectivePercentage = $royaltiesBracketPercentage;
            $royaltiesAppliedCriteria = 'tbr_fixo';
        } else {
            $royaltiesEffectiveValue = $royaltiesFromRevenue;
            $royaltiesEffectivePercentage = $royaltiesRevenueRate;
            $royaltiesAppliedCriteria = 'percentual_faturamento';
        }

        if ($fnmBracketValue >= $fnmFromRevenue) {
            $fnmEffectiveValue = $fnmBracketValue;
            $fnmEffectivePercentage = $fnmBracketPercentage;
        } else {
            $fnmEffectiveValue = $fnmFromRevenue;
            $fnmEffectivePercentage = self::FNM_REVENUE_RATE;
        }

        return [$royaltiesEffectiveValue, $royaltiesEffectivePercentage, $royaltiesAppliedCriteria, $fnmEffectiveValue, $fnmEffectivePercentage];
    }

    private function resolveContractMonth(?Carbon $startDate, int $year, int $month): int
    {
        if (! $startDate) {
            return 1;
        }

        $start = $startDate->copy()->startOfMonth();
        $reference = Carbon::createFromDate($year, $month, 1)->startOfMonth();
        $diff = (int) $start->diffInMonths($reference);

        return max(1, $diff + 1);
    }

    private function findRoyaltiesBracket(int $municipalitySizeId, int $contractMonth): InhabitantClassification
    {
        $bracket = $this->findBracket($municipalitySizeId, false, $contractMonth);

        if (! $bracket && $contractMonth > self::RENEWAL_CYCLE_MONTHS) {
            $renewalMonth = (($contractMonth - 1) % self::RENEWAL_CYCLE_MONTHS) + 1;
            $bracket = $this->findBracket($municipalitySizeId, true, $renewalMonth);
        }

        if (! $bracket) {
            throw ValidationException::withMessages([
                'municipality_size_id' => 'Não foi encontrada faixa de royalties para o porte e mês de contrato informados.',
            ]);
        }

        return $bracket;
    }

    private function findBracket(int $municipalitySizeId, bool $isRenewal, int $month): ?InhabitantClassification
    {
        return InhabitantClassification::where('municipality_size_id', $municipalitySizeId)
            ->where('is_renewal', $isRenewal)
            ->where('start', '<=', $month)
            ->where(function ($q) use ($month) {
                $q->whereNull('end')->orWhere('end', '>=', $month);
            })
            ->orderBy('start')
            ->first();
    }

    private function resolveFnmPercentage(int $contractMonth, float $fnmPercentage): float
    {
        return $contractMonth <= self::EXEMPT_THRESHOLD_MONTH ? 0.0 : $fnmPercentage;
    }

    private function resolveDueDate(?FranchiseeContract $contract, Carbon $referenceDate): Carbon
    {
        $dueDay = (int) ($contract?->invoice_due_date ?? 10);
        $dueDay = max(1, min(28, $dueDay));

        return $referenceDate->copy()->addMonthNoOverflow()->day($dueDay);
    }

    private function existingReceivable(int $unitId, int $contractMonth): bool
    {
        return TbrCalculation::where('unit_id', $unitId)
            ->where('contract_month_reference', $contractMonth)
            ->where('receivable_generated', true)
            ->exists();
    }
}