mareike/app/Models/Invoice.php

<?php

namespace App\Models;

use App\Enumerations\InvoiceStatus;
use App\Enumerations\InvoiceType;
use App\Enumerations\TravelReason;
use App\Scopes\InstancedModel;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

/**
 * @property string $tenant
 * @property string $cost_unit_id
 * @property string $invoice_number
 * @property string $status
 * @property string $type
 * @property string $type_other
 * @property string $purpose
 * @property boolean $donation
 * @property string $user_id
 * @property string $contact_name
 * @property string $contact_email
 * @property string $contact_phone
 * @property string $contact_bank_owner
 * @property string $contact_bank_iban
 * @property float $amount
 * @property integer $distance
 * @property string $comment
 * @property string $changes
 * @property string $travel_direction
 * @property boolean $passengers Nicht mehr erfasst -- siehe Hinweis unten
 * @property boolean $transportation Nicht mehr erfasst -- siehe Hinweis unten
 * @property string $document_filename
 * @property string $approved_by
 * @property string $approved_at
 * @property boolean $upload_required
 * @property string $denied_by
 * @property string $denied_at
 * @property string $denied_reason
 *
 * `passengers` ("Ich habe Personen mitgenommen") und `transportation` ("Ich habe Material transportiert")
 * werden seit dem Ausbau des Reisekosten-Formulars nicht mehr erfasst: Sie waren reine Ja/Nein-Angaben
 * ohne Wirkung auf den Betrag -- eine Kostenstelle führt genau eine Kilometerpauschale, es gibt also
 * keinen zweiten Satz, auf den sie umschalten könnten. Wer gereist ist, steht jetzt im `purpose`.
 * Die Spalten bleiben für die Altdaten stehen; sollen sie je wiederkommen, dann als Angaben, die in die
 * Berechnung eingehen (Mitnahmeentschädigung: eine Anzahl, kein Häkchen).
 */
class Invoice extends InstancedModel
{
    protected $fillable = [
        'tenant',
        'cost_unit_id',
        'invoice_number',
        'status',
        'type',
        'type_other',
        'purpose',
        'donation',
        'user_id',
        'contact_name',
        'contact_email',
        'contact_phone',
        'contact_bank_owner',
        'contact_bank_iban',
        'payment_purpose',
        'amount',
        'donation',
        'distance',
        'comment',
        'changes',
        'travel_direction',
        'travel_reason',
        'passengers',
        'transportation',
        'document_filename',
        'approved_by',
        'approved_at',
        'upload_required',
        'denied_by',
        'denied_at',
        'denied_reason',
    ];

    /**
     * Der Verwendungszweck für Überweisung, Buchungstext und Anzeige.
     *
     * Der Freitext gewinnt, wenn einer erfasst wurde. Sonst benennt der Text den Vorgang: eine
     * Beitragserstattung ist keine Auslage des Teilis, sondern die Rücknahme seiner Zahlung -- auf dem
     * Kontoauszug muss der Unterschied erkennbar sein. Genannt wird die Abrechnungsnummer, und zwar als
     * Belegnummer: unter "Rechnungsnummer" gibt es sie nirgends.
     */
    public function paymentPurposeText() : string {
        if ($this->payment_purpose !== null) {
            return $this->payment_purpose;
        }

        $subject = $this->type === InvoiceType::INVOICE_TYPE_PARTICIPATION_REFUND
            ? 'Beitragserstattung'
            : 'Auslagenerstattung';

        return $subject . ' Belegnummer ' . $this->invoice_number;
    }

    /**
     * Wofür der Beleg steht -- der "Zahlungsgrund" der Beleglisten und der "Zweck" der EüR-Anlage.
     *
     * Erfasst wird er beim Anlegen und steht danach in der eigenen Spalte: eine Angabe, keine Ableitung.
     * Nur so lässt er sich korrigieren, ohne dass ihn der nächste Vorgang wieder überschreibt.
     *
     * Bestandsbelege haben die Spalte leer -- für sie wird weiter abgeleitet, bei Fahrtkosten aus
     * Reisegrund und `contact_name`, weil es die Frage "wer ist gefahren" damals nicht gab. Bleibt auch
     * dabei nichts übrig, bleibt der Text leer; ein "--" würde in einer Belegliste nur Platz kosten.
     */
    public function purposeText() : string {
        if (trim((string) $this->purpose) !== '') {
            return $this->purpose;
        }

        return self::joinPurposeParts(
            $this->type === InvoiceType::INVOICE_TYPE_TRAVELLING
                ? [$this->travelReasonText(), $this->contact_name]
                : [$this->type_other]
        );
    }

    /**
     * Der Reisegrund als lesbarer Text.
     *
     * Der Name des gewählten Grundes -- oder der Wert selbst, wenn er zu keinem passt. Der ist dann der
     * Freitext von "Anderer Grund" oder stammt aus der Zeit vor der Auswahl.
     */
    public function travelReasonText() : string {
        return TravelReason::text($this->travel_reason);
    }

    /**
     * Setzt einen Zahlungsgrund aus seinen Teilen zusammen: leere fallen weg, damit kein " — " führt
     * oder hängt.
     *
     * @param array<int, ?string> $parts
     */
    public static function joinPurposeParts(array $parts) : string {
        $parts = array_map(fn ($part) => trim((string) $part), $parts);

        return implode(' — ', array_filter($parts, fn ($part) => $part !== ''));
    }

    public function costUnit() : BelongsTo{
        return $this->belongsTo(CostUnit::class);
    }

    public function status() : BelongsTo {
        return $this->belongsTo(InvoiceStatus::class, 'status')->first();
    }

    public function invoiceType() : InvoiceType {
        return $this->belongsTo(InvoiceType::class, 'type', 'slug')->first();
    }

    public function approvedBy() : ?User {
        return $this->belongsTo(User::class, 'approved_by')->first();
    }
}