300 lines
10 KiB
Markdown
300 lines
10 KiB
Markdown
# Story 7.1: Client Dashboard Overview
|
|
|
|
## 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
|
|
- [ ] Volt component created at `resources/views/livewire/client/dashboard.blade.php`
|
|
- [ ] Route registered and protected with auth middleware
|
|
- [ ] All 5 widgets display correctly with real data
|
|
- [ ] Data strictly scoped to authenticated user (security verified)
|
|
- [ ] Empty states display appropriately for each widget
|
|
- [ ] Mobile responsive (tested on 375px viewport)
|
|
- [ ] Bilingual content working (AR/EN toggle)
|
|
- [ ] All test scenarios pass
|
|
- [ ] Code formatted with `vendor/bin/pint --dirty`
|
|
- [ ] 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
|