# Offers and Packages Serviced Stays Integration Notes

This document details the backend architectural and frontend integration details for the **Offers and Packages Page** ecosystem at `/offers` and `/offers/{slug}` for Kevron Suites and Apartments.

---

## 1. Database Schema & Migration Details

### Migration: `2026_06_01_110000_create_offers_and_packages_tables`
To establish a fully dynamic, database-driven promotional stays ecosystem, we created the following tables and pivoting linkages:
1. **`offer_types`**:
   - Represents the core stay category classification (e.g. Weekend Stay, Corporate, Loyalty Repeat Guest).
2. **`offers`**:
   - `title` & `slug`: Mapped unique keys.
   - `short_description` & `description`: Marketing copy.
   - `valid_from` & `valid_until`: Date bounds.
   - `is_active` & `is_featured`: Dynamic toggles.
   - `discount_type` & `discount_value`: Integrates coupon values (percentage, fixed, free concierge add-on, rate-on-request).
   - `promo_code_id`: Foreign key link to existing `promo_codes` engine.
   - `terms_summary` & `cta_label` & `image_path`: Front-end display assets.
3. **`offer_apartment_type` & `offer_location`**:
   - Pivot tables mapping eligible suites and property branches.
4. **`offer_enquiries`**:
   - Lead registry mapping user contact statistics, stay date checks, guest lists uploads, previous booking references, and IP addresses.
5. **`offer_blackout_dates`**:
   - Block dates checking engine preventing bookings during high-demand holidays.
6. **`promo_code_redemptions`**:
   - Analytics statistics log recording coupon validation times and IP origins.

---

## 2. Eloquent Model Integrations

### Model: `Offer`
- **Scopes**:
  - `scopeActive($query)` checks current status, active toggle, and validity date brackets.
  - `scopeFeatured($query)` filters for featured deals.
- **Relationships**: `offerType()`, `apartmentTypes()`, `locations()`, `promoCode()`, `enquiries()`, `blackoutDates()`.
- **Blockout Check**: `hasBlackoutDate($checkIn, $checkOut)` checks overlaps against blackout blocks.

### Model: `OfferEnquiry`
- **Relationships**: `offer()`, `guestListUpload()`.

---

## 3. Dynamic Route Configuration

### Routes (`routes/web.php`)
- **GET** `/offers`: `OffersController@index` (filters categories, sorting metrics, and loads FAQs/SEO).
- **GET** `/offers/{slug}`: `OffersController@show` (loads specific deal details, blackout calendar, and templates).
- **POST** `/offers/enquire`: `OffersController@submitOfferEnquiry` (asynchronous Lead stores).
- **POST** `/offers/validate-promo`: `OffersController@validatePromoCode` (server-side coupon checks).
- **POST** `/offers/log`: `OffersController@logEvent` (telemetry logger).

---

## 4. Frontend Brand Language & UI Specifications

### Typography Constraints
- Headings strictly Marcellus. Max size: H1 capped at `1.8rem`, others below `1.625rem`.
- Body copy and UI tags strictly Inter (capped under `0.875rem`).

### Component Radius & Shadows
- **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;`.
- **Contrast**: Utilizes alternative background sections to structure sections cleanly.

---

## 5. Security & Privacy Rules
1. **CSRF headers**: Enforced in all Alpine fetch submissions.
2. **Server-side coupon checks**: Restricts validations strictly to active, un-expired, and valid booking range promo codes.
3. **Private lists directory**: Spreadsheets rosters uploaded by corporate guests are saved privately under the encrypted `/secure/guest-lists/` local storage folder.

---

## 6. Filament Admin Dashboard CRUDs

1. **`OfferResource`**: Form and table auditing stay promotions, categories, and blackout dates.
2. **`OfferTypeResource`**: Manages categories and coordinate sorting indexes.
3. **`OfferEnquiryResource`**: Audits leads, evaluates loyalty booking reference statuses, and exposes an authorized secure download action to download private coordinate rosters.
4. **`PromoCodeRedemptionResource`**: Tracks active coupon log metrics and redemption IP addresses.

---

## 7. QA Verification Summary

### Automated Test Suite (`OffersPageTest.php`)
- `offers_page_loads_successfully`: Verifies correct render and FAQ section integration.
- `offers_page_renders_headers_footers_and_brand_fonts`: Validates preservation of header components and brand font restrictions.
- `offers_filtering_by_category_works`: Confirms horizontal category pills work seamlessly.
- `offers_inactive_deals_do_not_render_publicly`: Verifies draft filters protect public listings.
- `coupon_validator_endpoint_validates_promo_codes`: Tests coupon validation logic.
- `offers_enquiry_form_submits_stores_in_database_and_queues_notification`: Ensures databases insert cleanly and notifications queue correct recipients.
- `offers_check_in_during_blackout_dates_fails_validation`: Verifies check-ins overlapping blackout blocks fail validation.
- `offers_telemetry_logs_events`: Validates custom client clicks logger.