# LottoData.com

LottoData.com is a production-minded Laravel 11 foundation for a public lottery site with:

- public homepage, about, and contact pages
- admin login and admin management foundation
- seeded Powerball and Mega Millions game records
- homepage jackpot/result modules backed by local models
- admin-managed ad placements
- admin-managed page content and key site settings
- admin-managed lottery data providers
- LotteryData.io adapter for live Powerball and Mega Millions imports
- scheduler-ready import command with provider resolution and status tracking

## Stack

- Laravel 11
- Blade
- SQLite for local development
- Tailwind via Vite
- MySQL-ready schema patterns for later environments

## Local Notes

- On this Windows machine, use Herd for browser access when available.
- Do not rely on `php artisan serve`.
- The local app URL is configured as `http://lottodata.test`.

## Useful Commands

```bash
php artisan migrate
php artisan db:seed
php artisan lotto:import
php artisan test
npm run build
```

For live frontend asset refresh during local development:

```bash
npm run dev
```

## V1 Feature Scope

- Public site shell with responsive homepage/about/contact
- Admin authentication with lightweight `is_admin` access control
- Core models for games, draws, jackpots, pages, ad placements, and settings
- Powerball and Mega Millions homepage modules with graceful fallbacks
- Admin-managed ad placements for:
  - `homepage_top`
  - `homepage_mid`
  - `homepage_bottom`
  - `footer_promo`
- Admin-managed provider records with:
  - active/inactive state
  - default provider selection
  - supported games
  - priority ordering
  - encrypted credential/config storage
- Admin-managed content for:
  - About page
  - Contact page
  - Homepage hero copy
  - Footer/disclaimer text

## Staging Prep

Before staging verification:

1. Copy `.env.example` to the staging environment and update database, app URL, mail, and cache/session settings.
2. Run `php artisan migrate --force`.
3. Run `php artisan db:seed --force` if you want the default V1 seed content present.
4. Create or update a provider record in `/admin/providers` with:
   - provider type `LotteryData.io`
   - base URL `https://www.lotterydata.io/api`
   - your LotteryData.io API key
   - `Powerball` and `Mega Millions` selected as supported games
   - active and default enabled
5. Run `php artisan lotto:import` once during deployment validation to confirm the provider configuration, logging, and import status fields behave as expected.
6. Run `npm run build` during the deployment build step.
7. Verify admin login, homepage modules, managed content, ad placements, and empty states using the staging URL.

## Scheduler Notes

- The app schedules `php artisan lotto:import` hourly.
- The command is overlap-protected so staging/production will not start a second import while one is already running.
- The import expects active game records to exist first, so seed the database or create the games in admin before validating scheduled imports.
- Import status is stored in `settings` under:
  - `lotto.last_import_status`
  - `lotto.last_import_message`
  - `lotto.last_imported_at`
  - `lotto.last_import_providers`
  - `lotto.last_import_summary`
- Each provider record also stores its own last import status, message, and summary in the `data_providers` table.
- Ensure the server scheduler is running Laravel's scheduler, for example with a cron or task runner that executes `php artisan schedule:run`.

## LotteryData.io Setup

- LotteryData.io uses the `x-api-key` request header.
- The adapter currently supports:
  - Powerball
  - Mega Millions
- The app normalizes provider responses into the local `draws` and `jackpots` tables before rendering homepage modules.
- Repeated imports stay duplicate-safe through:
  - `draws` unique key on `game_id + draw_date`
  - jackpot upsert matching on `game_id + draw_id + as_of + amount`
- Incomplete provider payloads are skipped gracefully instead of breaking the import.

## Adding Future Providers

1. Create a new adapter class under `app/Services/LottoData/Providers`.
2. Implement the common `LotteryDataProvider` contract.
3. Register the adapter in `AppServiceProvider` through `ProviderManager`.
4. Add the new provider type to admin configuration by exposing its key and label through the manager.
5. Reuse the existing `data_providers` table instead of rewriting the import command.

## Current QA Baseline

The current V1 test suite covers:

- public page routing and fallback rendering
- homepage game module rendering
- admin authentication and access control
- ad placement management and public rendering
- content/settings management
- core data foundation and provider binding
