133 lines
4.5 KiB
Markdown
133 lines
4.5 KiB
Markdown
# 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
|