From aa4b213d6ce85a0785246a820e7220b287bde5f2 Mon Sep 17 00:00:00 2001 From: codex Date: Sun, 1 Nov 2026 18:06:20 +0800 Subject: [PATCH] feat(billing): present payable renewal grace --- web/app/Controllers/CloudPageController.php | 5 +- .../Services/Cloud/CloudInvoiceService.php | 57 +++++++++++++++++-- web/public/cloud/invoice-detail-runtime.js | 5 +- web/public/cloud/invoices.js | 5 +- web/tests/CloudInvoiceDetailContractTest.php | 3 +- web/tests/CloudInvoiceLifecycleTest.php | 39 +++++++++++++ web/tests/CloudInvoicePresentationTest.php | 24 ++++++++ 7 files changed, 128 insertions(+), 10 deletions(-) diff --git a/web/app/Controllers/CloudPageController.php b/web/app/Controllers/CloudPageController.php index 2ffaf73a..af6bb765 100644 --- a/web/app/Controllers/CloudPageController.php +++ b/web/app/Controllers/CloudPageController.php @@ -492,7 +492,7 @@ final class CloudPageController $purpose = strtolower((string) ($invoice['purpose'] ?? '')); $status = strtolower((string) ($invoice['status'] ?? '')); [$statusLabel, $statusClass] = $this->invoiceStatus( - (string) ($invoice['status'] ?? '') + (string) ($invoice['display_status'] ?? $invoice['status'] ?? '') ); $fulfillment = strtolower((string) ($invoice['fulfillment_status'] ?? $invoice['job_status'] ?? $invoice['order_status'] ?? '')); @@ -549,7 +549,7 @@ final class CloudPageController $invoice = is_array($payload['invoice'] ?? null) ? $payload['invoice'] : []; $purpose = strtolower((string) ($invoice['purpose'] ?? '')); [$statusLabel, $statusClass] = $this->invoiceStatus( - (string) ($invoice['status'] ?? '') + (string) ($invoice['display_status'] ?? $invoice['status'] ?? '') ); $created = $this->formatTimestamp($invoice['created_at'] ?? null, '时间未记录'); @@ -753,6 +753,7 @@ final class CloudPageController { return match (strtolower($status)) { 'open' => ['待支付', 'warning'], + 'renewal_grace' => ['已到期,宽限期内可续费', 'warning'], 'overdue' => ['已逾期', 'failed'], 'paid' => ['已支付', 'running'], 'refunded' => ['已退款', 'other'], diff --git a/web/app/Services/Cloud/CloudInvoiceService.php b/web/app/Services/Cloud/CloudInvoiceService.php index 93b2aa6b..f720f471 100644 --- a/web/app/Services/Cloud/CloudInvoiceService.php +++ b/web/app/Services/Cloud/CloudInvoiceService.php @@ -812,7 +812,8 @@ final class CloudInvoiceService $existingInstanceIds = []; if ($linkedInstanceIds !== []) { foreach (CloudInstance::whereIn('id', array_values($linkedInstanceIds)) - ->get(['id', 'user_id', 'name', 'status']) as $instance) { + ->get(['id', 'user_id', 'name', 'status', 'service_status']) + as $instance) { $existingInstanceIds[(int) $instance->id] = true; $instances[self::listKey((int) $instance->user_id, (int) $instance->id)] = $instance; @@ -894,6 +895,13 @@ final class CloudInvoiceService $safeInstanceId = $historicalInstanceId; } $status = self::publicStatus($invoice, $purpose, $instance, $now); + $deadline = self::paymentDeadline($invoice); + $summaryPayable = $purpose === 'renewal' + && in_array($status, ['open', 'overdue'], true) + && $instance !== null + && !self::instanceDeleting($instance) + && $deadline !== null + && $deadline > $now; $jobStatus = self::taskStatus($job); $summaries[] = [ 'id' => (string) $invoice->id, @@ -902,10 +910,17 @@ final class CloudInvoiceService 'purpose' => $purpose, 'amount' => (string) $invoice->amount, 'status' => $status, + 'display_status' => self::displayStatus( + $purpose, + $status, + $summaryPayable, + $deadline, + $now + ), 'renews_expires_at' => $invoice->renews_expires_at === null ? null : max(0, (int) $invoice->renews_expires_at), 'due_at' => max(0, (int) $invoice->due_at), - 'payment_deadline_at' => self::paymentDeadline($invoice), + 'payment_deadline_at' => $deadline, 'created_at' => (int) $invoice->created_at, 'order_status' => $order?->status, 'fulfillment_status' => $jobStatus ?? $order?->status, @@ -971,12 +986,27 @@ final class CloudInvoiceService return $status; } + /** Keep storage status stable while presenting the renewal grace phase. */ + private static function displayStatus(string $purpose, string $status, + bool $payable, ?int $deadline, int $now): string + { + if ($purpose !== 'renewal' || $status !== 'overdue') { + return $status; + } + if ($payable) { + return 'renewal_grace'; + } + return $deadline !== null && $deadline <= $now + ? 'expired' : $status; + } + /** * Derive the public invoice state once for both full detail responses and * lightweight polling responses. The callers deliberately load different * columns, but payment eligibility must never drift between them. * - * @return array{status: string, deadline: ?int, payable: bool} + * @return array{status: string, display_status: string, deadline: ?int, + * payable: bool, available_action: ?string} */ private static function publicState(CloudInvoice $invoice, string $purpose, $order, $instance, int $now): array @@ -1003,8 +1033,19 @@ final class CloudInvoiceService $payable = false; } - return ['status' => $status, 'deadline' => $deadline, - 'payable' => $payable]; + return [ + 'status' => $status, + 'display_status' => self::displayStatus( + $purpose, + $status, + $payable, + $deadline, + $now + ), + 'deadline' => $deadline, + 'payable' => $payable, + 'available_action' => $payable ? 'pay' : null, + ]; } /** @@ -1051,6 +1092,7 @@ final class CloudInvoiceService $publicState = self::publicState($invoice, $purpose, $order, $instance, $now); $status = $publicState['status']; + $displayStatus = $publicState['display_status']; $deadline = $publicState['deadline']; $payable = $publicState['payable']; @@ -1098,6 +1140,8 @@ final class CloudInvoiceService 'id' => (string) $invoice->id, 'purpose' => $purpose, 'status' => $status, + 'display_status' => $displayStatus, + 'available_action' => $publicState['available_action'], 'payable' => $payable, 'paid_at' => $invoice->paid_at === null ? null : (int) $invoice->paid_at, 'paid_via' => $invoice->paid_via, @@ -1212,6 +1256,7 @@ final class CloudInvoiceService $bandwidthMbps = $bandwidthMbps > 0 ? $bandwidthMbps : null; $publicState = self::publicState($invoice, $purpose, $order, $instance, $now); $status = $publicState['status']; + $displayStatus = $publicState['display_status']; $deadline = $publicState['deadline']; $payable = $publicState['payable']; $jobStatus = self::taskStatus($job); @@ -1283,6 +1328,8 @@ final class CloudInvoiceService 'service_days' => (int) $invoice->validity_days, 'traffic_quota_bytes' => (int) $invoice->traffic_quota_bytes, 'status' => $status, + 'display_status' => $displayStatus, + 'available_action' => $publicState['available_action'], 'due_at' => (int) $invoice->due_at, 'renews_expires_at' => $invoice->renews_expires_at === null ? null : (int) $invoice->renews_expires_at, diff --git a/web/public/cloud/invoice-detail-runtime.js b/web/public/cloud/invoice-detail-runtime.js index e42eeb93..26d76998 100644 --- a/web/public/cloud/invoice-detail-runtime.js +++ b/web/public/cloud/invoice-detail-runtime.js @@ -302,6 +302,7 @@ function invoiceTitle(invoice) { function invoiceStatusInfo(status) { const values = { open: ['待支付', 'warning'], + renewal_grace: ['已到期,宽限期内可续费', 'warning'], overdue: ['已逾期', 'failed'], paid: ['已支付', 'running'], refunded: ['已退款', 'other'], @@ -1434,7 +1435,9 @@ function renderInvoiceDetail(invoice, payload) { text('invoice-detail-created', `创建于 ${formatOrderDate(invoice.created_at)}`); text('invoice-detail-subtitle', `账单 #${invoice.id} · ${formatOrderDate(invoice.created_at)}`); text('invoice-detail-amount', formatUsd(invoice.amount)); - const [statusLabel, statusClass] = invoiceStatusInfo(invoice.status); + const [statusLabel, statusClass] = invoiceStatusInfo( + invoice.display_status ?? invoice.status, + ); const status = byId('invoice-detail-status'); if (status) { status.className = `state-pill ${statusClass}`; diff --git a/web/public/cloud/invoices.js b/web/public/cloud/invoices.js index cf760f4c..f56a86bc 100644 --- a/web/public/cloud/invoices.js +++ b/web/public/cloud/invoices.js @@ -120,6 +120,7 @@ function invoiceContext(invoice) { function invoiceStatusInfo(status) { const values = { open: ['待支付', 'warning'], overdue: ['已逾期', 'failed'], paid: ['已支付', 'running'], + renewal_grace: ['已到期,宽限期内可续费', 'warning'], refunded: ['已退款', 'other'], void: ['已失效', 'other'], expired: ['已失效', 'failed'], deleting: ['实例删除中', 'failed'], delete_failed: ['自动删除失败', 'failed'], purge_pending: ['等待永久删除', 'failed'], purge_stopping: ['删除前正在关机', 'failed'], @@ -179,7 +180,9 @@ function renderInvoices() { if (context) detail.append(makeElement('p', 'muted cloud-invoice-context', context)); const actions = makeElement('div', 'cloud-order-actions cloud-invoice-list-actions'); const invoiceStatus = String(invoice.status || '').toLowerCase(); - const [label, className] = invoiceStatusInfo(invoiceStatus); + const [label, className] = invoiceStatusInfo( + invoice.display_status ?? invoiceStatus, + ); actions.append(makeElement('span', `state-pill ${className}`, label)); const purpose = invoicePurpose(invoice); if ((purpose === 'provision' && ['paid', 'refunded'].includes(invoiceStatus)) diff --git a/web/tests/CloudInvoiceDetailContractTest.php b/web/tests/CloudInvoiceDetailContractTest.php index 14ef96db..104e7609 100644 --- a/web/tests/CloudInvoiceDetailContractTest.php +++ b/web/tests/CloudInvoiceDetailContractTest.php @@ -151,7 +151,8 @@ $assert(str_contains($invoicePageService, "CloudInvoice::where('user_id', \$user $summaryMethod = $section($invoiceService, 'public static function listSummaries(', 'private static function listKey('); $assert(substr_count($summaryMethod, '::whereIn(') === 3 - && str_contains($summaryMethod, "->get(['id', 'user_id', 'name', 'status'])") + && str_contains($summaryMethod, + "->get(['id', 'user_id', 'name', 'status', 'service_status'])") && str_contains($summaryMethod, "->get(['id', 'order_id', 'invoice_id', 'user_id', 'instance_id', 'kind',") && str_contains($summaryMethod, diff --git a/web/tests/CloudInvoiceLifecycleTest.php b/web/tests/CloudInvoiceLifecycleTest.php index 40c7e64e..bd937549 100644 --- a/web/tests/CloudInvoiceLifecycleTest.php +++ b/web/tests/CloudInvoiceLifecycleTest.php @@ -234,6 +234,45 @@ namespace { && (string) CloudMailOutbox::first()->kind === 'renewal_due' && (string) $invoice->amount === '12.50', 'Renewal invoice type, snapshot or reminder outbox is missing.'); + $originalExpiry = (int) $instance->expires_at; + $graceExpiry = $now - 60; + $instance->expires_at = $graceExpiry; + $instance->service_status = 'expired_grace'; + $instance->save(); + $invoice->renews_expires_at = $graceExpiry; + $invoice->due_at = $graceExpiry; + $invoice->save(); + $graceDisplay = CloudInvoiceService::display($invoice->fresh()); + $graceSummary = CloudInvoiceService::listSummaries([ + $invoice->fresh(), + ])[0] ?? []; + $assert(($graceDisplay['status'] ?? null) === 'overdue' + && ($graceDisplay['display_status'] ?? null) === 'renewal_grace' + && ($graceDisplay['available_action'] ?? null) === 'pay' + && ($graceDisplay['payable'] ?? false) === true + && ($graceSummary['display_status'] ?? null) === 'renewal_grace', + 'An expired but payable renewal was not projected as payment grace.'); + + $expiredAt = $now - CloudInvoiceService::PAYMENT_GRACE_SECONDS - 60; + $instance->expires_at = $expiredAt; + $instance->save(); + $invoice->renews_expires_at = $expiredAt; + $invoice->due_at = $expiredAt; + $invoice->save(); + $expiredDisplay = CloudInvoiceService::display($invoice->fresh()); + $assert(($expiredDisplay['status'] ?? null) === 'overdue' + && ($expiredDisplay['display_status'] ?? null) === 'expired' + && array_key_exists('available_action', $expiredDisplay) + && $expiredDisplay['available_action'] === null + && ($expiredDisplay['payable'] ?? true) === false, + 'A renewal past its fixed grace cutoff still exposed a payment action.'); + + $instance->expires_at = $originalExpiry; + $instance->service_status = 'active'; + $instance->save(); + $invoice->renews_expires_at = $originalExpiry; + $invoice->due_at = $originalExpiry; + $invoice->save(); $actor = ['user_id' => 1, 'is_admin' => false, 'is_super_admin' => false, 'can_manage' => false, 'session_id' => '']; $paid = CloudInvoiceService::payBalance($invoice, $actor, 'invoice-balance-test-0001'); diff --git a/web/tests/CloudInvoicePresentationTest.php b/web/tests/CloudInvoicePresentationTest.php index 014b29a9..d4be12fd 100644 --- a/web/tests/CloudInvoicePresentationTest.php +++ b/web/tests/CloudInvoicePresentationTest.php @@ -81,4 +81,28 @@ $assert(($resumeView['show_payment'] ?? false) === true && ($resumeView['payment_methods'] ?? null) === [], 'Invoice first paint exposed retry instead of an active-payment fence.'); +$gracePayload = $payload; +$gracePayload['invoice']['status'] = 'overdue'; +$gracePayload['invoice']['display_status'] = 'renewal_grace'; +$gracePayload['invoice']['payable'] = true; +$graceView = $invoke($controller, 'invoiceDetailView', [$gracePayload]); +$assert(($graceView['status_label'] ?? null) === '已到期,宽限期内可续费' + && ($graceView['status_class'] ?? null) === 'warning', + 'Payable renewal grace was presented as a failed overdue invoice.'); + +$detailRuntime = file_get_contents( + dirname(__DIR__) . '/public/cloud/invoice-detail-runtime.js' +); +$listRuntime = file_get_contents(dirname(__DIR__) . '/public/cloud/invoices.js'); +$assert(is_string($detailRuntime) && is_string($listRuntime) + && str_contains($detailRuntime, + "renewal_grace: ['已到期,宽限期内可续费', 'warning']") + && str_contains($detailRuntime, + 'invoice.display_status ?? invoice.status') + && str_contains($listRuntime, + "renewal_grace: ['已到期,宽限期内可续费', 'warning']") + && str_contains($listRuntime, + 'invoice.display_status ?? invoiceStatus'), + 'Invoice client rendering does not consume the canonical grace status.'); + echo "Cloud invoice SSR presentation checks passed.\n";