4.5 KiB

Raw Blame History

Epic 15: Potential Clients Management

Epic Goal

Provide the admin with a simple lead tracking system to manage prospective clients (individuals, companies, agencies) who don't yet have accounts, enabling better organization of business development targets.

Epic Description

Existing System Context

Current functionality: User management system supports admin, individual clients, and company clients with full account capabilities
Technology stack: Laravel 12, Livewire 3/Volt, Flux UI, existing admin dashboard patterns
Integration points: Admin dashboard navigation, existing list/filter patterns from client management
Current constraint: No system for tracking prospects without creating full user accounts

Enhancement Details

What's being added:

New PotentialClient model and database table (completely separate from users)
New enum PotentialClientType with values: individual, company, agency
Admin-only CRUD interface at /admin/potential-clients
Filterable list view by client type
Contact information storage (all optional): phone, email, address, social media, website
Notes field for admin remarks

How it integrates:

New menu item in admin sidebar navigation
Follows existing admin interface patterns (Volt components, Flux UI)
Standalone feature - no impact on existing user/client functionality
Uses existing admin middleware and layout

Success criteria:

Admin can create, view, edit, and delete potential clients
Admin can filter list by type (individual, company, agency)
All contact fields are optional (flexible data entry)
Interface matches existing admin dashboard aesthetics
Bilingual support (Arabic/English)

Stories

Story 15.1: Database Schema & Model Setup

Create the potential_clients database table, PotentialClient model, PotentialClientType enum, and factory for testing.

Story 15.2: Potential Clients List with Type Filter

Create the admin list view at /admin/potential-clients with type filtering and pagination.

Story 15.3: CRUD Operations for Potential Clients

Implement create, view, edit, and delete functionality for potential clients.

Compatibility Requirements

Existing user/client system remains unchanged
Existing APIs remain unchanged
No changes to existing database tables
UI follows existing admin dashboard patterns (Flux UI, Volt)
No impact on client-facing functionality

Technical Considerations

Database Schema

potential_clients table:
- id: bigint (primary key)
- type: varchar (enum: individual, company, agency)
- name: varchar(255) NULLABLE
- phone: varchar(50) NULLABLE
- email: varchar(255) NULLABLE
- address: text NULLABLE
- social_media: varchar(255) NULLABLE
- website: varchar(255) NULLABLE
- notes: text NULLABLE
- created_at: timestamp
- updated_at: timestamp

New Enum

// App\Enums\PotentialClientType
enum PotentialClientType: string
{
    case Individual = 'individual';
    case Company = 'company';
    case Agency = 'agency';
}

Routes

// Admin routes (admin middleware)
Route::prefix('admin/potential-clients')->group(function () {
    Route::get('/', PotentialClientsList::class)->name('admin.potential-clients.index');
    Route::get('/create', PotentialClientCreate::class)->name('admin.potential-clients.create');
    Route::get('/{potentialClient}', PotentialClientShow::class)->name('admin.potential-clients.show');
    Route::get('/{potentialClient}/edit', PotentialClientEdit::class)->name('admin.potential-clients.edit');
});

Translation Keys

// potential-clients translations needed
'potential_clients' => 'Potential Clients' / 'العملاء المحتملون'
'type' => 'Type' / 'النوع'
'individual' => 'Individual' / 'فرد'
'company' => 'Company' / 'شركة'
'agency' => 'Agency' / 'وكالة'
// ... additional field labels

Risk Mitigation

Primary Risk: Feature scope creep (adding status tracking, conversion flow, etc.)
Mitigation: Strict adherence to simple contact list requirements; defer enhancements to future epics
Rollback Plan: Drop potential_clients table and remove routes/components

Definition of Done

All stories completed with acceptance criteria met
Tests cover CRUD operations and filtering
Admin can manage potential clients through new interface
No regression in existing features
Bilingual support (Arabic/English) for all UI elements
Admin navigation updated with new menu item

4.5 KiB Raw Blame History