# Implementation Notes — Terms and Conditions Page & Governance System

This document captures the implementation details, database schema designs, and developer compliance notes for the **Terms and Conditions** system.

---

## 1. Database Architecture

We designed a decoupled and dedicated schema to govern compliance documents:

### `legal_pages`
- `id` (bigint, pk)
- `title` (string): Title of the policy page.
- `slug` (string, unique): Used for slug-based route matching (e.g. `terms-and-conditions`).
- `summary` (text): Quick page introductory summary.
- `effective_date` (date): The date the legal page policy begins.
- `last_updated_at` (datetime): Timestamp of the last revision.
- `version` (string): Version sequence (e.g. `1.0`).
- `status` (string): publication status states (`draft`, `internal_review`, `legal_review`, `approved`, `published`, `archived`). Only `published` or `approved` statuses are displayed to the public.

### `legal_page_sections`
- `id` (bigint, pk)
- `legal_page_id` (foreign key to `legal_pages` cascade): Belongs to a legal page.
- `section_key` (string): Machine-readable key used for floating anchor scroll bindings (e.g. `booking_terms`, `house_rules`).
- `heading` (string): Heading title of the clause.
- `body` (text): Enriched HTML text content.
- `sort_order` (integer): Used to specify display priority.
- `is_active` (boolean): Flag to toggle section visibility.
- `requires_legal_review` (boolean): Flags sensitive sections (e.g., limitation of liability) requiring legal review.

### `terms_acceptances`
- `id` (bigint, pk)
- `user_id` (nullable foreign key to `users` cascade): Tracks logged-in users.
- `guest_id` (nullable foreign key to `guests` cascade): Tracks guest records.
- `booking_id` (nullable foreign key to `bookings` cascade): Tracks booking checkouts.
- `policy_version_id` (string): The active policy version signed (e.g. `terms-and-conditions-v1.0`).
- `acceptance_context` (string): Context of the transaction (`booking`, `registration`, `corporate`, `long_stay`).
- `checkbox_label` (string): The actual checkbox text signed by the guest.
- `ip_address` (string): User's IP address.
- `user_agent` (string): User's browser agent.
- `accepted_at` (timestamp): Accurate signing timestamp.

---

## 2. Dynamic Rates & Parsing Engine

To keep legal wording fully dynamic and in sync with the database:
- The [TermsAndConditionsController.php](file:///c:/xampp/htdocs/kevronapartments/app/Http/Controllers/TermsAndConditionsController.php) queries the active `base_price_nightly` of each suite category from the `ApartmentType` model.
- We support custom token placeholders within the database content sections:
  - `[1BR_RATE]` -> `₦150,000.00`
  - `[2BR_RATE]` -> `₦200,000.00`
  - `[3BR_RATE]` -> `₦250,000.00`
  - `[4BR_RATE]` -> `₦300,000.00`
- The controller compiles these values and injects them safely into the Blade view.

---

## 3. SEO / Schema Standards

- **Dynamic Metadata**: Fetches custom titles and descriptions from Spatie morphic `seoMetadata` relation, with elegant fallbacks.
- **JSON-LD Schema**: Serves a structured legal WebPage schema and LodgingBusiness publisher details.
- **GEO / AI Crawl statement**: Crawlable entity statement included to optimize discoverability for AI-powered search engines.

---

## 4. Front-End Interactions

- **Scroll Spy**: Highlights active table of contents anchors as you read.
- **Alpine.js Search**: Real-time filtering of TOC sections.
- **Copy Link**: Triggers telemetry events and clipboard copies with micro-animations.
- **Print Optimization**: Restructures the layout under printing modes, hiding non-print elements.