# Long Stay / Extended Stay Serviced Apartments Integration Notes

This document details the backend architectural and frontend integration details for the **Long Stay / Extended Stay Page** at `/long-stay-serviced-apartments-ikeja` for Kevron Suites and Apartments.

---

## 1. Database Schema & Migration Details

### Migration: `2026_06_01_000000_create_long_stays_tables`
To expand the B2B capabilities of Kevron Suites, we performed two key modifications and created a new relational table:
1. **Extended `long_stay_enquiries`**:
   - `full_name`: Complete name for unified storage.
   - `guest_type`: Categorization of guests (e.g., Relocating Family, Project Team Group).
   - `preferred_apartment_type`: The guest's desired suite selection.
   - `location_id`: Associated location reference (defaults to Ikeja).
   - `expected_check_out_date`: Target checkout date for stayed calculations.
   - `stay_duration`: Preferred duration mode (weekly, monthly, etc.).
   - `number_of_guests`: Size of the stay group.
   - `company_name`: Associated corporate organization if applicable.
   - `billing_preference`: Selected invoice routing type.
   - `airport_pickup_required` & `car_rental_required`: Boolean/options indicators.
   - `special_requirements`: Detailed guest demands text.
   - `assigned_to`: Relational coordinator user ID inside Filament.
   - `admin_notes`: Operational tracking records.
   - `submitted_ip`: Captures origin IP for security audit log and fraud prevention.
2. **Linked `guest_list_uploads`**:
   - Associated guest rosters securely to the specific `long_stay_enquiry_id` (via cascade foreign key).
3. **Created `long_stay_rate_rules`**:
   - Maps specific Weekly/Monthly discount schemes, seasonal adjustments, minimum stay durations, deposits, and corporate tiers for individual apartment types.

---

## 2. Eloquent Model Integrations

### Model: `LongStayEnquiry`
- **Location Mapping**: `belongsTo(Location::class)`
- **Apartment Mapping**: `belongsTo(ApartmentType::class)`
- **Coordinator Assignment**: `belongsTo(User::class, 'assigned_to')`
- **Guest List Reference**: `hasOne(GuestListUpload::class)`
- **Casts**:
  - `check_in` & `expected_check_out_date` to `date`.
  - Statuses default to `'new'`.

### Model: `LongStayRateRule`
- **Relationship**: `belongsTo(ApartmentType::class)`
- **Dynamic Scopes**: Includes `scopeActive($query)` filtering for active configurations.

---

## 3. Route Mapping & Permanent Redirects

### Route Registrations (`routes/web.php`)
- **GET** `/long-stay-serviced-apartments-ikeja` maps to `LongStayController@index`.
- **POST** `/long-stay/enquire` maps to `LongStayController@submitLongStayEnquiry` (as named route `long-stay.enquiry`).
- **POST** `/long-stay/log` maps to `LongStayController@logEvent` (as named route `long-stay.log`).
- **301 Permanent Redirect**:
  - Automatically redirects legacy path `/long-stay` directly to `/long-stay-serviced-apartments-ikeja` utilizing `Route::redirect` to protect SEO equity.

---

## 4. Business Rules, Formatting & UI Specifications

### Typography Constraints
- **Luxury Headings**: Marcellus (`font-family: 'Marcellus', serif`).
- **Body Text**: Inter (`font-family: 'Inter', sans-serif`).
- **Size Limits**:
  - H1 capped at `1.8rem`.
  - H2-H6 capped strictly below `1.625rem`.
  - Body/subheadings capped at `0.875rem` (`text-xs` / `text-sm` equivalents).

### Components Layout & Styling
- **Buttons**: Structured with a precise `border-radius: 50px;` (`rounded-full` / `btn-pill` utility class in Kevron). Incorporates 3D slow-hover bouncy scale transition properties.
- **Benefit, Suite & Rates Cards**: Styled with an exact `border-radius: 0.1rem;` and custom shadow outline `box-shadow: rgba(0, 0, 0, 0.05) 0px 0px 0px 1px;`.
- **Background Contrast**: Visual sections utilize alternative background tokens (e.g. `bg-slate-50` contrasting with standard `bg-white`) to elevate scannability.

---

## 5. Security & Privacy Measures
1. **CSRF Enforcement**: Secure token injection in all Alpine AJAX fetch headers.
2. **Rate Limiting**: Applied throttling to enquiries processing.
3. **MIME/Size Verification**: Files uploaded as guest rosters are validated strictly for document extensions (`mimes:csv,xls,xlsx,pdf,doc,docx`) and sizes capped at 5MB.
4. **Encrypted Private Storage**: File streams are stored securely under `secure/guest-lists/` using the system's `local` disk configuration, completely protected from external public visibility.

---

## 6. Filament Admin Dashboard Controls

### Enquiry Dashboard (`LongStayEnquiryResource`)
- Displays real-time lists sorted by entry time, statuses, and stay duration.
- Includes a secure, authorized file action permitting verified administrators to safely download guest rosters from the local storage disk.
- Fully supports coordinators assigning, invoice monitoring, and operational logging.

### Rates Dashboard (`LongStayRateRuleResource`)
- Allows dynamic configuration of weekly/monthly tiers.
- Allows admins to instantly toggle public visibility of rates, fall back to "Rate on request" dynamically, customize required deposits, and introduce seasonal multipliers.

---

## 7. Quality Assurance & Feature Verification

### Automated Integration Tests (`LongStayPageTest.php`)
- `long_stay_page_loads_successfully`: Verifies correct render and presence of seeded apartment data.
- `long_stay_page_renders_headers_footers_and_brand_fonts`: Validates preservation of header components and brand font restrictions.
- `long_stay_enquiry_form_validates_required_fields`: Confirms strict server-side validation filters.
- `long_stay_enquiry_submits_stores_in_database_and_queues_notification`: Ensures databases insert cleanly and notifications queue correct recipients.
- `long_stay_enquiry_submits_with_guest_list_file_and_stores_securely`: Validates private file uploads mapping correctly.
- `long_stay_telemetry_logs_events`: Validates custom client clicks logger.
- `long_stay_old_route_redirects_permanently`: Ensures 301 SEO redirection works flawlessly.