# Phase 8: Dashboard & Analytics

## Objective
Implement real-time operational dashboards and analytics for hotel managers, both in Filament admin (widgets) and API (mobile app).

---

## Tasks

### 8.1 HotelDashboardService

**File:** `app/Services/HotelManager/HotelDashboardService.php`

Same pattern as Shop DashboardService:

```php
final class HotelDashboardService
{
    public function resolvePeriod(string $period, ?string $from = null, ?string $to = null): array;
    public function previousPeriod(CarbonImmutable $from, CarbonImmutable $to): array;
    public function percentageChange(float $current, float $previous): float;

    /** Revenue from paid orders linked to this hotel */
    public function paidOrdersQuery(Hotel $hotel, CarbonImmutable $from, CarbonImmutable $to): Builder;

    /** Occupancy calculation: occupied rooms / total active rooms */
    public function getOccupancyRate(Hotel $hotel, CarbonImmutable $date): float;

    /** Average Daily Rate: total room revenue / number of rooms sold */
    public function getADR(Hotel $hotel, CarbonImmutable $from, CarbonImmutable $to): Money;

    /** RevPAR: total room revenue / total available room-nights */
    public function getRevPAR(Hotel $hotel, CarbonImmutable $from, CarbonImmutable $to): Money;

    /** Sparkline data for occupancy over a period */
    public function occupancySparkline(Hotel $hotel, CarbonImmutable $from, CarbonImmutable $to): array;

    /** Forecast: upcoming occupancy based on confirmed + checked-in reservations */
    public function occupancyForecast(Hotel $hotel, int $days = 30): array;
}
```

### 8.2 HotelDashboardCacheService

**File:** `app/Services/HotelManager/HotelDashboardCacheService.php`

Same Redis caching strategy as Shop:
- Pre-compute at midnight via `hotel:dashboard:warm-cache` command
- Delta calculation during the day (TTL 5 min)
- Cache keys: `hotel:{hotel_id}:dashboard:{metric}:{period}`

### 8.3 API — Real-time Dashboard Endpoints

**Directory:** `app/Http/Controllers/Api/Employee/HotelManager/Dashboard/`

#### TodaySummaryController
```
GET /v1/places/{place}/hotels/{hotel}/dashboard/today-summary
```
Returns:
```json
{
    "occupancy_rate": 78.5,
    "total_rooms": 92,
    "occupied_rooms": 72,
    "available_rooms": 18,
    "out_of_order_rooms": 2,
    "arrivals_today": 15,
    "departures_today": 12,
    "revenue_today": {"amount": 45000, "currency": "EUR"},
    "pending_reservations": 3
}
```

#### ArrivalsAndDeparturesController
```
GET /v1/places/{place}/hotels/{hotel}/dashboard/arrivals-departures
```
Returns today's check-ins and check-outs with guest info, room type, status.

#### LiveOccupancyController
```
GET /v1/places/{place}/hotels/{hotel}/dashboard/live-occupancy
```
Returns room status breakdown by floor and room type.

### 8.4 API — Analytics Dashboard Endpoints

#### RevenueController
```
GET /v1/places/{place}/hotels/{hotel}/dashboard/revenue
Query: period (today, 7d, 14d, 30d, custom), from, to
```
Returns: total revenue, previous period comparison, sparkline, breakdown (room revenue vs extras revenue).

#### OccupancyController
```
GET /v1/places/{place}/hotels/{hotel}/dashboard/occupancy
Query: period
```
Returns: average occupancy rate, sparkline, comparison with previous period, by room type breakdown.

#### ADRController
```
GET /v1/places/{place}/hotels/{hotel}/dashboard/adr
Query: period
```
Returns: Average Daily Rate, RevPAR, trends, comparison.

#### ForecastController
```
GET /v1/places/{place}/hotels/{hotel}/dashboard/forecast
Query: days (default 30)
```
Returns: daily occupancy forecast based on confirmed reservations for the next N days.

#### ChannelPerformanceController
```
GET /v1/places/{place}/hotels/{hotel}/dashboard/channel-performance
Query: period
```
Returns: revenue and bookings count by source/channel (direct, Booking.com, Airbnb, etc.).

### 8.5 Filament — Dashboard Widgets

#### HotelOccupancyWidget
**File:** `app/Filament/Widgets/HotelOccupancyWidget.php`

Widget on PlaceResource showing:
- Current occupancy rate across all hotels
- Available rooms count
- Today's arrivals and departures

#### HotelRevenueWidget
**File:** `app/Filament/Widgets/HotelRevenueWidget.php`

Widget showing hotel revenue for last 30 days with chart.

### 8.6 Artisan Command — Cache Warming

**File:** `app/Console/Commands/WarmHotelDashboardCacheCommand.php`

```bash
php artisan hotel:dashboard:warm-cache
```

Scheduled daily at midnight. Pre-computes dashboard metrics for all active hotels.

### 8.7 Resources

- `HotelTodaySummaryResource` — Today summary data
- `HotelRevenueResource` — Revenue analytics with sparkline
- `HotelOccupancyResource` — Occupancy analytics
- `HotelForecastResource` — Forecast data

### 8.8 Tests

**File:** `tests/Feature/Controllers/HotelManager/DashboardTest.php`

- [ ] Today summary returns correct occupancy and counts
- [ ] Arrivals/departures lists correct reservations
- [ ] Revenue calculation is accurate (room + extras)
- [ ] Occupancy rate calculation is correct
- [ ] ADR calculation is correct
- [ ] RevPAR calculation is correct
- [ ] Forecast shows correct upcoming occupancy
- [ ] Channel performance groups by source
- [ ] Period filtering works (today, 7d, 30d, custom)
- [ ] Cache warming command runs without errors

---

## Acceptance Criteria

- [ ] All 3 real-time dashboard endpoints functional
- [ ] All 5 analytics dashboard endpoints functional
- [ ] Filament widgets showing correct data
- [ ] Cache warming command operational
- [ ] Occupancy, ADR, RevPAR calculations accurate
- [ ] Forecast based on confirmed reservations
- [ ] All Swagger annotations present
- [ ] All tests pass
- [ ] Pint + PHPStan pass on new/modified files