revamps docs complete
This commit is contained in:
IGNY8 VPS (Salman)
@@ -0,0 +1,56 @@
|
||||
# Account Page (Account Settings)
|
||||
|
||||
## Purpose
|
||||
Provide a full account-level settings form for name, slug (read-only), billing contact email, billing address, and tax ID. Acts as the frontend surface for `getAccountSettings`/`updateAccountSettings` and reflects saved tenant metadata.
|
||||
|
||||
## Code Locations (exact paths)
|
||||
- Page component: `frontend/src/pages/account/AccountSettingsPage.tsx`
|
||||
- API client: `frontend/src/services/billing.api` (`getAccountSettings`, `updateAccountSettings`, `AccountSettings` type)
|
||||
- UI primitives: `frontend/src/components/ui/card`
|
||||
|
||||
## High-Level Responsibilities
|
||||
- Fetch current account settings on load and bind them into a local form.
|
||||
- Allow updating account display name, billing contact email, billing address fields, and tax/VAT ID.
|
||||
- Keep account slug immutable/read-only while exposing it for reference.
|
||||
- Surface success/error feedback inline.
|
||||
|
||||
## Detailed Behavior
|
||||
- On mount: calls `getAccountSettings()`; populates `settings` and `formData` with server values.
|
||||
- Form fields: `name`, `billing_email`, `billing_address_line1/2`, `billing_city`, `billing_state`, `billing_postal_code`, `billing_country`, `tax_id`; `slug` shown read-only from `settings.slug`.
|
||||
- Submit: `handleSubmit` -> `updateAccountSettings(formData)`; on success shows success banner then reloads settings; on failure shows error banner.
|
||||
- Loading states: full-page spinner before data load; button shows saving state.
|
||||
- Errors surfaced from caught exceptions (`err.message`) with console logging.
|
||||
|
||||
## Data Structures / Models Involved (no code)
|
||||
- Account settings DTO returned by `getAccountSettings` with fields listed above plus `slug`.
|
||||
|
||||
## Execution Flow
|
||||
- `useEffect` → `loadSettings` → `getAccountSettings` → set local state.
|
||||
- User edits controlled inputs → `handleSubmit` → `updateAccountSettings` → reload via `loadSettings`.
|
||||
- All network ops are direct REST calls via `billing.api`.
|
||||
|
||||
## Cross-Module Interactions
|
||||
- Shares account identity with billing pages (same `billing.api` source). Updated billing email/address is used by invoicing flows.
|
||||
|
||||
## State Transitions (if applicable)
|
||||
- View state: `loading` → loaded; `saving` toggles during submit. Success/error banners reflect last operation outcome.
|
||||
|
||||
## Error Handling
|
||||
- Catches fetch/update errors; shows inline red banner; logs to console. No retries.
|
||||
|
||||
## Tenancy Rules
|
||||
- Relies on backend to scope `getAccountSettings`/`updateAccountSettings` to the authenticated user’s account; no client-side tenancy logic beyond using the current auth token.
|
||||
|
||||
## Billing Rules (if applicable)
|
||||
- Billing contact and address collected here feed invoice generation; no pricing logic on this page.
|
||||
|
||||
## Background Tasks / Schedulers (if applicable)
|
||||
- None.
|
||||
|
||||
## Key Design Considerations
|
||||
- Slug is immutable to prevent accidental tenant identifier changes.
|
||||
- Form is fully controlled; reload after save ensures UI mirrors server truth.
|
||||
|
||||
## How Developers Should Work With This Module
|
||||
- Add new account-level fields by extending `AccountSettings` in `billing.api`, wiring controlled inputs, and persisting via `updateAccountSettings`.
|
||||
- Keep slug read-only; any slug mutation must be handled server-side with explicit UX.
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
# 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.
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# Payment Methods Page
|
||||
|
||||
## Purpose
|
||||
Display available payment methods for the tenant and support selection for purchases/subscriptions. Methods originate from backend billing configs and are reused across plan changes and credit purchases.
|
||||
|
||||
## Code Locations (exact paths)
|
||||
- Consolidated flows: `frontend/src/pages/account/PlansAndBillingPage.tsx` (tab `payment-methods`)
|
||||
- Purchase credits: `frontend/src/pages/account/PurchaseCreditsPage.tsx` (method selection + manual payment proof)
|
||||
- API: `frontend/src/services/billing.api` (`getAvailablePaymentMethods`, `createPaymentMethod`, `deletePaymentMethod`, `setDefaultPaymentMethod`)
|
||||
|
||||
## High-Level Responsibilities
|
||||
- Fetch account-scoped payment methods (bank transfer, local wallet, manual/other).
|
||||
- Allow choosing a default method for purchases/subscriptions.
|
||||
- Provide instructions/details (bank or wallet) for manual/offline flows.
|
||||
|
||||
## Detailed Behavior
|
||||
- PlansAndBillingPage:
|
||||
- On load, calls `getAvailablePaymentMethods()` with other billing calls; filters out disabled methods (`is_enabled === false`).
|
||||
- Chooses preferred method for selection: bank_transfer, then manual, else default flag, else first item.
|
||||
- Renders payment-methods tab listing methods, default flag, instructions; supports create/delete/default actions via `createPaymentMethod`, `deletePaymentMethod`, `setDefaultPaymentMethod`.
|
||||
- Selection state (`selectedPaymentMethod`) is reused when purchasing packages or creating subscriptions.
|
||||
- PurchaseCreditsPage:
|
||||
- Fetches methods and auto-selects bank_transfer, then manual, else first.
|
||||
- For bank/local/manual methods, shows instructions and bank/wallet details and collects `transaction_reference` + `notes` when the payment is manual/offline.
|
||||
- Stripe/PayPal placeholders show “integration pending”.
|
||||
|
||||
## Data Structures / Models Involved (no code)
|
||||
- `PaymentMethod` DTO: `id`, `type` (`bank_transfer`, `local_wallet`, `manual`, `stripe`, `paypal`), `display_name`, `instructions`, optional `bank_details`/`wallet_details`, `is_default`, `is_enabled`.
|
||||
|
||||
## Execution Flow
|
||||
- Load methods → set local `paymentMethods` → derive `selectedPaymentMethod`.
|
||||
- User selects method → stored in component state; used by purchase/subscription handlers.
|
||||
- Optional CRUD (create/delete/default) triggered in `PlansAndBillingPage` tab using billing API helpers.
|
||||
|
||||
## Cross-Module Interactions
|
||||
- Used by credit purchase (`purchaseCreditPackage`) and subscription updates (`createSubscription`, `cancelSubscription`) within `PlansAndBillingPage`.
|
||||
|
||||
## State Transitions
|
||||
- Local selection state only; backend default flag can be updated via `setDefaultPaymentMethod`.
|
||||
|
||||
## Error Handling
|
||||
- Errors surface via toast/banner in `PlansAndBillingPage`; inline error message in `PurchaseCreditsPage` for missing selections or failed calls.
|
||||
|
||||
## Tenancy Rules
|
||||
- All calls are account-scoped by backend auth; no client multi-tenant switching.
|
||||
|
||||
## Billing Rules (if applicable)
|
||||
- Selected method is passed to credit purchase and subscription creation; manual methods require proof submission (transaction reference) and remain pending approval server-side.
|
||||
|
||||
## Background Tasks / Schedulers (if applicable)
|
||||
- None on client.
|
||||
|
||||
## Key Design Considerations
|
||||
- Prefers offline-safe methods (bank/manual) to avoid blocking when card gateways are unavailable.
|
||||
- Keeps selection sticky within the session to reduce user friction across tabs.
|
||||
|
||||
## How Developers Should Work With This Module
|
||||
- To add a new gateway type, extend `PaymentMethod` type, update selection logic, and render gateway-specific instructions or redirection flows.
|
||||
- Keep manual/offline instructions editable via backend configs; surface them read-only in the UI.
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# Subscription Page (Plans & Upgrades)
|
||||
|
||||
## Purpose
|
||||
Let tenants view current subscription, browse available plans, start or cancel subscriptions, and align payment method selection with plan changes. Uses the same billing data as the Billing dashboard but focuses on plan lifecycle.
|
||||
|
||||
## Code Locations (exact paths)
|
||||
- Page: `frontend/src/pages/account/PlansAndBillingPage.tsx` (tabs `plan` and `upgrade`)
|
||||
- API: `frontend/src/services/billing.api` (`getPlans`, `getSubscriptions`, `createSubscription`, `cancelSubscription`)
|
||||
- Payment selection (shared): same page via `getAvailablePaymentMethods`
|
||||
|
||||
## High-Level Responsibilities
|
||||
- Fetch active plans and the tenant’s current subscription.
|
||||
- Enable plan change (create/update subscription) gated by payment method selection.
|
||||
- Allow cancellation of the active subscription.
|
||||
|
||||
## Detailed Behavior
|
||||
- Initial load (`loadData`):
|
||||
- Fetches credit balance, packages, invoices, payments, payment methods, plans, subscriptions (with retry/backoff for 429).
|
||||
- Filters plans to active ones; excludes Enterprise for non `aws-admin` accounts but re-injects the account’s assigned plan so UI always reflects truth.
|
||||
- Ensures there is at least one subscription entry; if none returned, synthesizes one from `user.account.plan`.
|
||||
- Plan selection:
|
||||
- Requires a chosen payment method if any exist.
|
||||
- `handleSelectPlan(planId)` → `createSubscription({ plan_id, payment_method })` → reload data.
|
||||
- Cancellation:
|
||||
- `handleCancelSubscription` calls `cancelSubscription(currentSubscription.id)` and refreshes state.
|
||||
- Tabs:
|
||||
- `plan` shows current subscription summary.
|
||||
- `upgrade` lists available plans (filtered) with select buttons; highlights defaults via UI styling.
|
||||
|
||||
## Data Structures / Models Involved (no code)
|
||||
- `Plan`: name, slug, price, billing cycle, features, `is_active`.
|
||||
- `Subscription`: `id`, `plan`, `status`.
|
||||
|
||||
## Execution Flow
|
||||
- `useEffect` → `loadData` (controlled sequence + throttling gaps) → set plans/subscriptions/paymentMethods.
|
||||
- Select plan → API call → toast → reload.
|
||||
- Cancel → API call → toast → reload.
|
||||
|
||||
## Cross-Module Interactions
|
||||
- Shares payment method selection with credit purchase; uses `useAuthStore` for account plan fallbacks.
|
||||
|
||||
## State Transitions
|
||||
- `activeTab` controls view; `planLoadingId`/`purchaseLoadingId` track in-flight plan or package actions.
|
||||
- Subscription status rendered from backend; cancellation triggers status change server-side.
|
||||
|
||||
## Error Handling
|
||||
- Central `handleBillingError` surfaces message + toast.
|
||||
- Throttle (429) handled with delayed retry for subscriptions; errors suppressed if retry fails to keep page usable.
|
||||
|
||||
## Tenancy Rules
|
||||
- All subscription APIs are account-scoped by the backend; client does not switch tenants.
|
||||
|
||||
## Billing Rules (if applicable)
|
||||
- Requires a payment method before subscription create/update.
|
||||
- Enterprise plans hidden for non-admin tenants to prevent accidental selection.
|
||||
|
||||
## Background Tasks / Schedulers (if applicable)
|
||||
- None client-side; no polling beyond initial load.
|
||||
|
||||
## Key Design Considerations
|
||||
- Guardrails to avoid showing empty state when account already has a plan (synthesizes subscription from account plan).
|
||||
- Prefers bank/manual methods when selecting plan for safer checkout in absence of Stripe/PayPal integrations.
|
||||
|
||||
## How Developers Should Work With This Module
|
||||
- To expose new plan attributes, extend plan cards in the upgrade tab and ensure `Plan` type carries those fields.
|
||||
- Keep enterprise-plan visibility rules aligned with backend authorization; avoid client-side-only blocking for sensitive plans.
|
||||
|
||||
Reference in New Issue
Block a user