Faturalama Davranışını Değiştirme

// Yenilemenin TEK giriş noktası. $target_type 'service' ya da 'addon'.
// ÖDENMEMİŞ bir fatura yazar ve döner; vadeye dokunmaz.
public static function process_renewal(string $target_type, int $target_id, array $opts = []): array;

// Hedef ve müşteri çözüldükten sonra yukarıdaki tarafından çağrılır.
public static function generate_renewal(string $target_type, array $target, array $user_data, array $opts = []): int|false;

// Fiyat. period ve period_time'ı $target ÜZERİNDEN okur; farklı bir dönemi
// fiyatlamanın yeni bir metot değil değiştirilmiş bir hedef vermek olmasının sebebi budur.
public static function calculate_renewal_amount(string $target_type, array $target, array $user_data, array $opts = []): array;

// 'already-invoiced' arkasındaki yinelenme sorgusu. Dönem anahtarın parçasıdır.
public static function has_renewal(string $target_type, int $target_id, string $duedate, string $period = ''): bool;

// Üründeki her faturanın tek INSERT noktası.
public static function create(array $data): int;
public static function add_item(array $data): int;

// Ara toplam, vergi, komisyon ve toplamı yeniden hesaplar. Önizleme için $persist = false.
public static function recalculate_totals(int $invoiceId, bool $persist = true): array|false;

// Durum geçişi ve tüm yan etkileri.
public static function change_status(int $invoiceId, string $status, array $options = []): bool;

// Bir dönemin aşım fiyatı. $scheme 'per_unit', 'volume' ya da 'graduated';
// $pricing kademe haritası; $ccode ise PARA BİRİMİ KODUDUR, çünkü kademeler
// çevrilmez, para birimi başına fiyatlanır.
public static function calculate(string $scheme, float $billable, array $pricing, string $ccode): float;

// Kullanım eksi dahil hak, sıfırda taban yapılmış.
public static function get_billable(float $usage, float $included): float;

// Saatlik anlık görüntülerden ayın rakamı. Metrik dönemler son okumaya değil
// ortalamaya göre faturalanır.
public static function monthly_average(array $snapshots): float;

// 1. FİYAT. Her şey referansla gelir; BİRİM tutarı değiştirin, çünkü adet,
//    vergiler ve indirimler onun etrafında uygulanır.
Hook::add('filter:invoice.renewal_amount', 20, function (&$result, $target_type, $target, $user_data) {
    if ($target_type !== 'service') return;

    $uid = (int) ($target['owner_id'] ?? 0);
    if ($uid <= 0) return;

    $years = (int) (User::getInfo($uid, ['acme_loyalty_years'])['acme_loyalty_years'] ?? 0);
    if ($years < 3) return;

    // Bu müşteriyle dondurulmuş bir fiyat üzerinde anlaşılmış; ona bir kez daha indirim
    // uygulamak, operatörün bilerek yaptığı bir anlaşmayı bozar.
    if (($result['pricing_source'] ?? '') !== 'live') return;

    $result['amount'] = round((float) ($result['amount'] ?? 0) * 0.9, 4);

    // İndirim listesi, faturanın müşteriye gösterdiği şeydir. Onu atlamak, üzerinde
    // hiçbir açıklama olmayan daha ucuz bir fatura üretir.
    $result['discounts']['acme_loyalty'] = [
        'label' => Language::gc('admin/invoices/acme-loyalty-label'),
        'rate'  => 10,
    ];
});

// 2. KARAR. Boş olmayan bir dize reddeder; iş onu gerekçe olarak kaydeder.
Hook::add('gate:invoice.create', 10, function ($target_type, $target_id, $duedate) {
    if ($target_type !== 'service') return '';

    $service = Services::get((int) $target_id, 'id,options');
    $opts    = $service['options'] ?? [];

    // Göç hâlindeki bir hizmet, yerine oturana kadar faturalanmamalıdır.
    if ((int) ($opts['acme_migrating'] ?? 0) === 1) return 'acme-migration-in-progress';

    return '';
});

// 3. TEPKİ. Vade yazıldıktan SONRA ateşlenir, yani uzatma sinyali budur.
//    $service, taşınmadan ÖNCEKİ anlık görüntüdür: eski değerleri ondan okuyun.
Hook::add('action:service.renewed', 30, function ($serviceId, $service, $newDuedate, $oldDuedate) {
    Utility::HttpRequest([
        'url'  => 'https://crm.example.com/renewals',
        'type' => 'POST',
        'data' => [
            'service' => (int) $serviceId,
            'from'    => (string) $oldDuedate,
            'to'      => (string) $newDuedate,
            'cycle'   => (string) ($service['period'] ?? ''),
        ],
    ]);
});

$result = Invoices::process_renewal('service', 5001, [
    // Hizmet aylık olarak saklanıyor olsa da iki yıl faturalayın. Fiyatlama yalnız bu
    // fatura için canlıya geçer ve ödeme iki yıl uzatır; saklı aylık döngü ile onun
    // dondurulmuş tutarı ise olduğu gibi kalır.
    'period'      => 'year',
    'period_time' => 2,
    'source'      => 'acme-portal',
]);

// Atlamada invoice_id null olur ve atlama bir başarısızlık DEĞİLDİR: dallanmayı id üzerinden yapın.
if (($result['invoice_id'] ?? null) === null) {
    // already-invoiced | skip-renewal-invoice-flag | recurring-cycles-limit-reached
    // | invalid-period | service-not-found | user-data-unavailable | ...
    throw new Exception('Renewal not issued: ' . (string) ($result['reason'] ?? 'unknown'));
}

// Fatura vardır ve ÖDENMEMİŞTİR. Hizmete dair henüz hiçbir şey değişmemiştir.
$invoiceId = (int) $result['invoice_id'];

Hook::add('action:invoice.status_changed', 10, function ($invoice, $status, $old_status, $options) {
    // Yalnız ödenmiş durumuna GEÇİŞ bir satıştır; tekrar eden bir yazma değildir.
    if ($status !== 'paid' || $old_status === 'paid') return;

    $id = (int) ($invoice['id'] ?? 0);

    // Saklı bir rakama güvenmek yerine yeniden hesaplayın: operatör, fatura kesildikten
    // sonra kalemleri düzenlemiş olabilir. false = önizleme, hiçbir şey kalıcı olmaz.
    $totals = Invoices::recalculate_totals($id, false);

    AcmeLedger::record([
        'invoice'  => $id,
        'customer' => (int) ($invoice['user_id'] ?? 0),
        'currency' => (string) ($invoice['currency'] ?? ''),
        'net'      => (float) ($totals['subtotal'] ?? 0),
        'tax'      => (float) ($totals['tax'] ?? 0),
        'gross'    => (float) ($totals['total'] ?? 0),
        'method'   => (string) ($options['pmethod'] ?? ''),
    ]);
});