計費指標¶

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Metering\MeteringReporter;
use NextPDF\Enterprise\Metering\Operation;

final class PdfGenerationService
{
    public function __construct(
        private readonly MeteringReporter $metering,
    ) {}

    public function generate(
        string $tenantId,
        string $html,
        string $plan,
    ): GeneratedPdf {
        $startTime = microtime(true);

        $pdf = $this->doGenerate($html);

        // 記錄計量事件
        $this->metering->record(
            operation: Operation::PDF_GENERATE,
            tenantId: $tenantId,
            attributes: [
                'plan' => $plan,
                'pages' => $pdf->getPageCount(),
                'bytes' => $pdf->getSizeBytes(),
                'duration_ms' => (int)((microtime(true) - $startTime) * 1000),
            ]
        );

        return $pdf;
    }
}

use NextPDF\Enterprise\Metering\BatchMeteringReporter;

// 使用批次報告器（緩衝 100 個事件或每 5 秒批次發送）
$metering = new BatchMeteringReporter(
    backend: $prometheusBackend,
    bufferSize: 100,
    flushIntervalSeconds: 5,
);

// 在應用程式關閉時確保緩衝區已清空
register_shutdown_function([$metering, 'flush']);

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Metering\BillingExporter;
use Stripe\StripeClient;

final class StripeUsageReporter
{
    public function __construct(
        private readonly BillingExporter $exporter,
        private readonly StripeClient $stripe,
    ) {}

    public function reportUsage(string $tenantId, DateTimeImmutable $periodEnd): void
    {
        $usage = $this->exporter->getUsage(
            tenantId: $tenantId,
            periodStart: $periodEnd->modify('-1 month'),
            periodEnd: $periodEnd,
        );

        // 報告 PDF 頁數用量
        $this->stripe->subscriptionItems->createUsageRecord(
            $this->getStripeItemId($tenantId, 'pdf_pages'),
            [
                'quantity' => $usage->pdfPagesGenerated,
                'timestamp' => $periodEnd->getTimestamp(),
                'action' => 'set',
            ]
        );

        // 報告 RAG Token 用量
        if ($usage->ragTokensEmbedded > 0) {
            $this->stripe->subscriptionItems->createUsageRecord(
                $this->getStripeItemId($tenantId, 'rag_tokens'),
                [
                    'quantity' => $usage->ragTokensEmbedded,
                    'timestamp' => $periodEnd->getTimestamp(),
                    'action' => 'set',
                ]
            );
        }
    }
}

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Metering\QuotaGuard;
use NextPDF\Enterprise\Metering\QuotaExceededException;

final class QuotaAwarePdfService
{
    public function __construct(
        private readonly QuotaGuard $quotaGuard,
    ) {}

    /**
     * @throws QuotaExceededException
     */
    public function generate(string $tenantId, string $html): GeneratedPdf
    {
        // 先檢查配額，不足則拋出異常（避免產生後才發現超額）
        $this->quotaGuard->checkAndReserve(
            tenantId: $tenantId,
            operation: 'pdf.generate',
            units: 1,
        );

        try {
            return $this->doGenerate($html);
        } catch (\Throwable $e) {
            // 生成失敗時退還預留的配額
            $this->quotaGuard->release($tenantId, 'pdf.generate', 1);
            throw $e;
        }
    }
}