revamps docs complete

master-docs/30-frontend/accounts/ACCOUNT-PAGE.md

@@ -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.