# 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

- [x] Existing user/client system remains unchanged
- [x] Existing APIs remain unchanged
- [x] No changes to existing database tables
- [x] UI follows existing admin dashboard patterns (Flux UI, Volt)
- [x] 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

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

### Routes

```php
// 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

```php
// 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