# Self-Service Portal — Product Specification A read-only web portal where lot owners can view their billing history, download invoices, and track their utility consumption — without requiring a full admin account. --- ## Goals - Zero-friction access: no password registration, OTP only - Works for owners across multiple sites and service providers - Mobile-first responsive layout - Frontend framework: Vue JS (consistent with existing stack) --- ## Authentication Flow ### Step 1 — Email entry User enters their email address. The system looks up `lot_owners` where `email`, `alternate_email_1`, or `alternate_email_2` matches (case-insensitive). If no match is found, show a generic message: *"If this email is registered, you will receive a code shortly."* (never confirm or deny existence). ### Step 2 — OTP dispatch - Generate a 6-digit numeric OTP - Valid for **10 minutes**, single-use - Sent to the email address the user typed (not the primary email on the record) - Store: hashed OTP, email, `expires_at`, `used_at` (null until consumed) - Rate-limit: max 3 OTP requests per email per 15-minute window ### Step 3 — OTP verification User enters the code. On success: - Mark OTP as used (`used_at = now()`) - Issue a short-lived JWT (role: `portal_user`, 2-hour expiry) - Record a login log entry (email, IP, user agent, timestamp, success/fail) - Redirect to the bill history view On failure: increment attempt counter. Lock after 5 failed attempts for 15 minutes. ### Step 4 — Session JWT is stored in memory (not localStorage) to reduce XSS risk. On expiry, redirect back to email entry — no silent refresh. Portal has no persistent session concept. --- ## Data Model — Lot Resolution After authentication, resolve all lots linked to the verified email: ``` lot_owners ├── email / alternate_email_1 / alternate_email_2 matches login email └── has_many lots (via lot_owner_id) ├── site_id → Site → service_provider_id └── service_type_id ``` A single email may resolve to lots across **multiple sites and multiple service providers**. All are surfaced. --- ## Portal Views ### 1. Bill History (main view) **Filters (persistent in URL params):** | Control | Type | Behaviour | |---|---|---| | Site | Dropdown | Lists all sites the user has at least one lot on. Default: first site alphabetically | | Service type | Tabs | Water / Electricity / Gas — only show tabs for types that have bills | | Date range | Optional date picker | Defaults to last 12 months | **Bill list (paginated — 12 per page):** Each row: - Invoice number (`id`) - Billing period (`survey_start_date` → `survey_end_date`) - Units consumed (formatted with `billingUnitLabel`) - Net amount + tax (formatted with `formatMoney`) - Tax label + percentage (if `tax_percentage > 0`) - Due date - Download button (PDF) / View button (opens in-browser) Pagination: standard prev / next with page numbers. URL-param driven so links are shareable. --- ### 2. Summary Cards Shown above the bill list, scoped to the currently selected site + service type. | Card | Calculation | Notes | |---|---|---| | **Average bill** | Mean of `net_bill_value + tax_value` across last 12 months | | | **Average consumption** | Mean of `units_consumed` across last 12 months | Label with `billingUnitLabel` | | **Last 30-day estimate** | Most recent closed bill's `units_consumed` ÷ billing period days × 30 | Labelled as "estimate" | | **Current meter reading** | `current_unit` from the active open session (if one exists) | Show date of last reading. Hide card if no open session | | **Last bill total** | Most recent `net_bill_value + tax_value` | With date | --- ### 3. Bill Detail / PDF Viewer Triggered by "View" button. Opens the existing `siteServiceTemplate` PDF rendered inline in an `