63 lines
4.1 KiB
Markdown
63 lines
4.1 KiB
Markdown
# Billing Page (Plans & Billing Dashboard)
|
|
|
|
## Purpose
|
|
Present a consolidated billing dashboard with tabs for credit balance, plans, invoices, payments, and available payment methods. Acts as the UI client for billing endpoints (balance, invoices, payments, credit packages, payment methods, plans, subscriptions).
|
|
|
|
## Code Locations (exact paths)
|
|
- Page: `frontend/src/pages/account/AccountBillingPage.tsx`
|
|
- Billing API client: `frontend/src/services/billing.api` (`getInvoices`, `getPayments`, `getCreditBalance`, `getCreditPackages`, `getAvailablePaymentMethods`, `downloadInvoicePDF`, `getPlans`, `getSubscriptions`)
|
|
- UI: `frontend/src/components/ui/card`, `frontend/src/components/billing/BillingRecentTransactions`, `frontend/src/components/ui/pricing-table/PricingTable`
|
|
|
|
## High-Level Responsibilities
|
|
- Fetch and render account-scoped billing data (credits, invoices, payments, packages, payment methods, plans, subscriptions).
|
|
- Provide tabbed navigation across overview, plans, invoices, payments, methods.
|
|
- Allow invoice PDF download.
|
|
|
|
## Detailed Behavior
|
|
- On mount: `loadData()` runs seven parallel calls for balance, invoices, payments, packages, payment methods, plans, subscriptions. Results populate local state; errors render a banner.
|
|
- Overview tab: shows four metric cards (balance, monthly allocation, used this month, plan status) from `creditBalance`.
|
|
- Plans tab: displays `PricingTable` with static plan catalog (Starter/Growth/Scale) plus dynamic plans from API; shows current subscription chips if present.
|
|
- Invoices tab: lists invoices with amount/currency/status/date; supports PDF download via `downloadInvoicePDF(invoiceId)` using blob download flow.
|
|
- Payments tab: lists payments with status badges derived from status-to-style map (paid/succeeded/completed/pending/pending_approval/processing/failed/refunded/cancelled/void/uncollectible).
|
|
- Methods tab: lists available payment methods from `getAvailablePaymentMethods`.
|
|
- “Purchase Credits” button links to `/account/purchase-credits`.
|
|
- Loading: full-page spinner until `loadData` completes.
|
|
|
|
## Data Structures / Models Involved (no code)
|
|
- `Invoice`, `Payment`, `CreditBalance`, `CreditPackage`, `PaymentMethod`, `Plan`, `Subscription` DTOs from `billing.api`.
|
|
|
|
## Execution Flow
|
|
- `useEffect` → `loadData` (Promise.all) → set state.
|
|
- Tab click sets `activeTab`; conditional renders per tab.
|
|
- Invoice download: fetch blob → create object URL → anchor click → revoke URL.
|
|
|
|
## Cross-Module Interactions
|
|
- Reads auth user from `useAuthStore` for contextual display; all billing data is backend-scoped to account.
|
|
- Plans tab uses static catalog for marketing copy but still shows live plan/subscription data from API.
|
|
|
|
## State Transitions
|
|
- `activeTab` switches UI sections; `loading` gates initial fetch; error banner shows on fetch failure.
|
|
- Status badges reflect backend payment/invoice statuses only; no client mutation flows here.
|
|
|
|
## Error Handling
|
|
- Catches fetch errors → sets `error` message → red banner.
|
|
- Invoice download failure shows `alert`.
|
|
|
|
## Tenancy Rules
|
|
- Relies on backend scoping through authenticated requests; no client-side account selection.
|
|
|
|
## Billing Rules (if applicable)
|
|
- Read-only view of credits, invoices, payments, and plans; purchases/plan changes are triggered elsewhere (Purchase Credits page or separate plan change flows).
|
|
|
|
## Background Tasks / Schedulers (if applicable)
|
|
- None client-side; periodic refresh is not scheduled (one-time load per mount).
|
|
|
|
## Key Design Considerations
|
|
- Minimizes throttling risk by batching fetches but does not paginate invoices/payments on the client; relies on API pagination responses.
|
|
- Uses static plan catalog for UX but shows actual subscriptions from API to avoid mismatch with assigned plan.
|
|
|
|
## How Developers Should Work With This Module
|
|
- Add or reorder tabs by extending the `TabType` union and tab config array.
|
|
- When adding new billing surfaces (e.g., disputes/refunds), mirror the pattern: fetch via `billing.api`, guard with `loading/error`, render tab content.
|
|
- Keep invoice download flow consistent (blob + object URL) for cross-browser support.
|