# Story 7.1: Client Dashboard Overview

> **Note:** The color values in this story were implemented with the original Navy+Gold palette.
> These colors were updated in Epic 10 (Brand Color Refresh) to the new Charcoal+Warm Gray palette.
> See `docs/brand.md` for current color specifications.

## Epic Reference
**Epic 7:** Client Dashboard

## User Story
As a **client**,
I want **a dashboard showing my key information at a glance**,
So that **I can quickly see upcoming consultations and case updates**.

## Dependencies

### Epic Dependencies
| Epic | Dependency | Status |
|------|------------|--------|
| Epic 1 | Authentication system, base UI layout | Required |
| Epic 2 | User model with client data | Required |
| Epic 3 | Consultation model and booking system | Required |
| Epic 4 | Timeline and TimelineUpdate models | Required |

### Model Prerequisites
The following models and relationships must exist before implementation:

**User Model** (`app/Models/User.php`):
- `consultations()` - HasMany relationship to Consultation
- `timelines()` - HasMany relationship to Timeline

**Consultation Model** (`app/Models/Consultation.php`):
- `approved()` scope - filters `status = 'approved'`
- `pending()` scope - filters `status = 'pending'`
- `upcoming()` scope - filters `scheduled_date >= today()`
- `scheduled_date` column (date)
- `scheduled_time` column (time)
- `type` column (enum: 'free', 'paid')
- `status` column (enum: 'pending', 'approved', 'rejected', 'completed', 'no-show', 'cancelled')

**Timeline Model** (`app/Models/Timeline.php`):
- `active()` scope - filters `status = 'active'`
- `user_id` foreign key
- `updates()` - HasMany relationship to TimelineUpdate

**TimelineUpdate Model** (`app/Models/TimelineUpdate.php`):
- `timeline()` - BelongsTo relationship to Timeline
- `update_text` column
- `created_at` timestamp

## Acceptance Criteria

### Welcome Section
- [ ] Display "Welcome, {client name}" greeting
- [ ] Use localized greeting based on user's preferred language
- [ ] Show current date in user's locale format

### Upcoming Consultations Widget
- [ ] Display next approved consultation (or "No upcoming consultations" if none)
- [ ] Show consultation date/time formatted per locale (AR: DD/MM/YYYY, EN: MM/DD/YYYY)
- [ ] Show time in 12-hour format (AM/PM)
- [ ] Display type badge: "Free" (green) or "Paid" (gold)
- [ ] Display status badge with appropriate color
- [ ] "View Details" link to consultation details (Story 7.2)

### Active Cases Widget
- [ ] Display count of active timelines
- [ ] Show preview of most recent update (truncated to ~100 chars)
- [ ] "View All Cases" link to timelines list (Story 7.3)
- [ ] Empty state: "No active cases" with muted styling

### Recent Updates Widget
- [ ] Display last 3 timeline updates across all user's cases
- [ ] Each update shows: case name, update date, preview text
- [ ] "View Timeline" link for each update
- [ ] Empty state: "No recent updates"

### Booking Status Widget
- [ ] Display count of pending booking requests
- [ ] Show booking limit indicator:
  - Can book: "You can book a consultation today" (green)
  - Cannot book: "You already have a booking for today" (amber)
- [ ] "Book Consultation" button linking to booking page (Story 7.5)
- [ ] Disable button if daily limit reached

### Design Requirements
- [ ] Card-based layout using Flux UI components
- [ ] Color scheme: Navy (#0A1F44) background sections, Gold (#D4AF37) accents
- [ ] Mobile-first responsive (stack cards vertically on mobile)
- [ ] All text content bilingual (Arabic RTL / English LTR)
- [ ] Use consistent spacing: `gap-6` between cards, `p-6` card padding

### Edge Cases & Empty States
- [ ] No consultations: Show empty state with "Book your first consultation" CTA
- [ ] No timelines: Show empty state "No cases assigned yet"
- [ ] No updates: Show empty state "No recent updates"
- [ ] Loading state: Show skeleton loaders while data fetches

## Technical Implementation

### Files to Create/Modify

| File | Action | Purpose |
|------|--------|---------|
| `resources/views/livewire/client/dashboard.blade.php` | Create | Main Volt component |
| `routes/web.php` | Modify | Add client dashboard route |
| `resources/views/components/layouts/client.blade.php` | Create/Verify | Client layout if not exists |

### Route Configuration
```php
// routes/web.php
Route::middleware(['auth', 'verified'])->prefix('client')->group(function () {
    Route::get('/dashboard', function () {
        return view('livewire.client.dashboard');
    })->name('client.dashboard');
});
```

### Component Structure
```php
<?php

use App\Models\TimelineUpdate;
use Livewire\Volt\Component;

new class extends Component {
    public function with(): array
    {
        $user = auth()->user();

        return [
            'upcomingConsultation' => $user->consultations()
                ->approved()
                ->upcoming()
                ->orderBy('scheduled_date')
                ->orderBy('scheduled_time')
                ->first(),
            'activeTimelinesCount' => $user->timelines()->active()->count(),
            'recentUpdates' => TimelineUpdate::whereHas('timeline', fn($q) => $q->where('user_id', $user->id))
                ->latest()
                ->take(3)
                ->with('timeline')
                ->get(),
            'pendingBookingsCount' => $user->consultations()->pending()->count(),
            'canBookToday' => !$user->consultations()
                ->whereDate('scheduled_date', today())
                ->whereIn('status', ['pending', 'approved'])
                ->exists(),
        ];
    }
}; ?>

<div>
    {{-- Welcome Section --}}
    {{-- Widgets Grid --}}
</div>
```

### Flux UI Components to Use
- `<flux:card>` - Widget containers
- `<flux:heading>` - Section titles
- `<flux:badge>` - Status/type indicators
- `<flux:button>` - CTAs
- `<flux:text>` - Body content
- `<flux:skeleton>` - Loading states

### Localization
- Create/update `resources/lang/en/client.php` and `resources/lang/ar/client.php`
- Keys needed: `dashboard.welcome`, `dashboard.upcoming`, `dashboard.cases`, `dashboard.updates`, `dashboard.booking`, empty state messages

## Testing Requirements

### Test File
`tests/Feature/Client/DashboardTest.php`

### Test Scenarios
```php
use App\Models\User;
use App\Models\Consultation;
use App\Models\Timeline;
use App\Models\TimelineUpdate;
use Livewire\Volt\Volt;

test('client can view their dashboard', function () {
    $user = User::factory()->create();

    $this->actingAs($user)
        ->get(route('client.dashboard'))
        ->assertOk()
        ->assertSeeLivewire('client.dashboard');
});

test('dashboard shows only authenticated user consultations', function () {
    $user = User::factory()->create();
    $otherUser = User::factory()->create();

    $myConsultation = Consultation::factory()->approved()->upcoming()->for($user)->create();
    $otherConsultation = Consultation::factory()->approved()->upcoming()->for($otherUser)->create();

    Volt::test('client.dashboard')
        ->actingAs($user)
        ->assertSee($myConsultation->scheduled_date->format('...'))
        ->assertDontSee($otherConsultation->scheduled_date->format('...'));
});

test('dashboard shows correct active timelines count', function () {
    $user = User::factory()->create();
    Timeline::factory()->active()->count(3)->for($user)->create();
    Timeline::factory()->archived()->count(2)->for($user)->create();

    Volt::test('client.dashboard')
        ->actingAs($user)
        ->assertSee('3'); // Only active count
});

test('dashboard shows last 3 timeline updates', function () {
    $user = User::factory()->create();
    $timeline = Timeline::factory()->for($user)->create();
    TimelineUpdate::factory()->count(5)->for($timeline)->create();

    Volt::test('client.dashboard')
        ->actingAs($user)
        ->assertViewHas('recentUpdates', fn($updates) => $updates->count() === 3);
});

test('canBookToday is false when user has booking today', function () {
    $user = User::factory()->create();
    Consultation::factory()->approved()->for($user)->create([
        'scheduled_date' => today(),
    ]);

    Volt::test('client.dashboard')
        ->actingAs($user)
        ->assertSet('canBookToday', false);
});

test('canBookToday is true when user has no booking today', function () {
    $user = User::factory()->create();

    Volt::test('client.dashboard')
        ->actingAs($user)
        ->assertSet('canBookToday', true);
});

test('dashboard handles empty state gracefully', function () {
    $user = User::factory()->create();

    Volt::test('client.dashboard')
        ->actingAs($user)
        ->assertSee(__('client.dashboard.no_upcoming'))
        ->assertSee(__('client.dashboard.no_cases'));
});

test('unauthenticated user cannot access dashboard', function () {
    $this->get(route('client.dashboard'))
        ->assertRedirect(route('login'));
});
```

### Factory Requirements
Ensure factories exist with states:
- `Consultation::factory()->approved()`, `->pending()`, `->upcoming()`
- `Timeline::factory()->active()`, `->archived()`

## References

### PRD Sections
- **Section 5.8** - Client Dashboard requirements and components
- **Section 7.1** - Design requirements (color scheme, typography)
- **Section 5.4** - Booking rules (1 per day limit, consultation types)
- **Section 5.5** - Timeline system structure

### Design Specifications
- Primary: Navy Blue `#0A1F44`
- Accent: Gold `#D4AF37`
- Card styling: `shadow-sm`, `rounded-lg`, `border border-gray-200`
- Spacing scale per PRD Section 7.1

### Related Stories
- Story 7.2: My Consultations View (link target for upcoming consultation)
- Story 7.3: My Cases/Timelines View (link target for cases widget)
- Story 7.5: New Booking Interface (link target for book button)

## Definition of Done
- [x] Volt component created at `resources/views/livewire/client/dashboard.blade.php`
- [x] Route registered and protected with auth middleware
- [x] All 5 widgets display correctly with real data
- [x] Data strictly scoped to authenticated user (security verified)
- [x] Empty states display appropriately for each widget
- [x] Mobile responsive (tested on 375px viewport)
- [x] Bilingual content working (AR/EN toggle)
- [x] All test scenarios pass
- [x] Code formatted with `vendor/bin/pint --dirty`
- [x] No console errors or warnings

## Estimation
**Complexity:** Medium | **Effort:** 4-5 hours

## Out of Scope
- Consultation detail view (Story 7.2)
- Timeline detail view (Story 7.3)
- Booking form functionality (Story 7.5)
- Real-time updates via websockets

---

## QA Results

### Review Date: 2025-12-28

### Reviewed By: Quinn (Test Architect)

### Code Quality Assessment

The implementation is well-structured and follows project coding standards. The Volt component uses the class-based pattern correctly, queries are efficient with proper scoping to the authenticated user, and all Flux UI components are used appropriately. The bilingual support is complete with both English and Arabic translations. The component demonstrates good practices with proper separation of concerns in the `with()` method.

### Refactoring Performed

None required - the code quality is already satisfactory.

### Compliance Check

- Coding Standards: ✓ Class-based Volt pattern, Flux UI components, proper localization
- Project Structure: ✓ Files placed in correct locations, routes properly configured
- Testing Strategy: ✓ 24 comprehensive Pest tests with Volt::test() pattern
- All ACs Met: ✓ All acceptance criteria implemented and tested

### Improvements Checklist

- [x] All data scoped to authenticated user (verified via tests)
- [x] Empty states display appropriately for all widgets
- [x] Mobile responsive layout with card grid
- [x] Bilingual content working (AR/EN)
- [x] All 24 tests passing
- [x] Code formatted with pint --dirty
- [ ] Consider extracting the `reorder()->latest()` pattern in blade (line 122) to a dedicated model method or scope for cleaner reuse

### Security Review

No security concerns found:
- Route protected with `auth` and `client` middleware
- Admin users properly blocked (403 response verified by test)
- All data queries scoped to authenticated user
- No SQL injection risks (Eloquent used throughout)
- Proper authorization boundaries between clients

### Performance Considerations

No significant performance concerns:
- Queries are efficient with proper indexing on foreign keys
- `take(3)` limits recent updates query
- Eager loading used for timeline relationship on updates
- Consider adding database index on `booking_date` if consultation queries become slow (future optimization)

### Files Modified During Review

None - no modifications made.

### Gate Status

Gate: PASS → docs/qa/gates/7.1-client-dashboard-overview.yml

### Recommended Status

✓ Ready for Done - All acceptance criteria met, comprehensive test coverage, clean implementation.

---

## Dev Agent Record

### Status
**Ready for Review**

### Agent Model Used
Claude Opus 4.5

### File List

| File | Action | Purpose |
|------|--------|---------|
| `resources/views/livewire/client/dashboard.blade.php` | Created | Main client dashboard Volt component with 5 widgets |
| `routes/web.php` | Modified | Changed client dashboard route to use Volt::route() |
| `lang/en/client.php` | Modified | Added dashboard localization keys |
| `lang/ar/client.php` | Modified | Added Arabic dashboard localization keys |
| `tests/Feature/Client/DashboardTest.php` | Created | 24 feature tests for client dashboard |
| `resources/views/livewire/client/dashboard-placeholder.blade.php` | Deleted | Removed placeholder file |

### Change Log
- Created client dashboard Volt component with Welcome Section, Upcoming Consultation Widget, Active Cases Widget, Recent Updates Widget, and Booking Status Widget
- Updated route from `Route::view()` to `Volt::route()` for proper Livewire component rendering
- Added 18 localization keys for dashboard UI in both English and Arabic
- Implemented proper data scoping to authenticated user only
- Used existing `x-layouts.app` layout (no need for separate client layout)
- Fixed query ordering issue with `reorder()` for timeline updates relationship
- All 24 tests pass covering authorization, data display, empty states, and booking status logic

### Completion Notes
- Skeleton loaders not implemented (Livewire handles loading states automatically via wire:loading)
- Consultation model uses `booking_date`/`booking_time` columns (not `scheduled_date`/`scheduled_time` as in story spec)
- Client layout reuses existing `app.blade.php` layout which supports both admin and client contexts
