libra/docs/stories/story-2.2-company-client-account-management.md

# Story 2.2: Company/Corporate Client Account Management

## Epic Reference
**Epic 2:** User Management System

## User Story
As an **admin**,
I want **to create, view, edit, and manage company/corporate client accounts**,
So that **I can serve corporate clients with their unique data requirements**.

## Story Context

### Existing System Integration
- **Integrates with:** Users table, potential contact_persons table
- **Technology:** Livewire Volt, Flux UI forms
- **Follows pattern:** Same CRUD pattern as individual clients
- **Touch points:** User model, admin dashboard

## Acceptance Criteria

### Create Company Client
- [ ] Form with required fields:
  - Company Name (required)
  - Company Registration Number (required, unique)
  - Contact Person Name (required)
  - Contact Person ID (required)
  - Email Address (required, unique)
  - Phone Number (required)
  - Password (admin-set, required)
  - Preferred Language (Arabic/English dropdown)
- [ ] Validation for all required fields
- [ ] Duplicate email/registration number prevention
- [ ] Success message on creation

### Multiple Contact Persons (Optional Enhancement)
- [ ] Support unlimited contact persons per company
- [ ] Each contact: Name, ID, Phone, Email
- [ ] Primary contact indicator
- [ ] Add/remove contacts dynamically

### List View
- [ ] Display all company clients (user_type = 'company')
- [ ] Columns: Company Name, Contact Person, Email, Reg #, Status, Created Date
- [ ] Pagination (10/25/50 per page)
- [ ] Default sort by created date

### Search & Filter
- [ ] Search by company name, email, or registration number
- [ ] Filter by status (active/deactivated/all)
- [ ] Real-time search with debounce

### Edit Company
- [ ] Edit all company information
- [ ] Update contact person details
- [ ] Validation same as create
- [ ] Success message on update

### View Company Profile
- [ ] Display all company information
- [ ] List all contact persons
- [ ] Show consultation history summary
- [ ] Show timeline history summary

### Quality Requirements
- [ ] Bilingual form labels and messages
- [ ] Proper form validation
- [ ] Audit log entries for all operations
- [ ] Tests for CRUD operations

## Technical Notes

### User Model Scope
```php
public function scopeCompany($query)
{
    return $query->where('user_type', 'company');
}
```

### Database Fields for Company
```
users table:
  - company_name (nullable, required for company type)
  - company_registration (nullable, unique when not null)
  - contact_person_name (nullable, required for company)
  - contact_person_id (nullable, required for company)
```

### Alternative: Separate Contact Persons Table
```php
// contact_persons migration
Schema::create('contact_persons', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('name');
    $table->string('national_id');
    $table->string('phone')->nullable();
    $table->string('email')->nullable();
    $table->boolean('is_primary')->default(false);
    $table->timestamps();
});
```

### Validation Rules
```php
public function rules(): array
{
    return [
        'company_name' => ['required', 'string', 'max:255'],
        'company_registration' => ['required', 'string', 'unique:users,company_registration'],
        'contact_person_name' => ['required', 'string', 'max:255'],
        'contact_person_id' => ['required', 'string'],
        'email' => ['required', 'email', 'unique:users,email'],
        'phone' => ['required', 'string'],
        'password' => ['required', 'string', 'min:8'],
        'preferred_language' => ['required', 'in:ar,en'],
    ];
}
```

### Volt Component for Create
```php
<?php

use App\Models\User;
use Livewire\Volt\Component;
use Illuminate\Support\Facades\Hash;

new class extends Component {
    public string $company_name = '';
    public string $company_registration = '';
    public string $contact_person_name = '';
    public string $contact_person_id = '';
    public string $email = '';
    public string $phone = '';
    public string $password = '';
    public string $preferred_language = 'ar';

    public function create(): void
    {
        $validated = $this->validate();

        $user = User::create([
            ...$validated,
            'user_type' => 'company',
            'name' => $this->company_name, // For display purposes
            'password' => Hash::make($this->password),
            'status' => 'active',
        ]);

        // Log action
        // Send welcome email

        session()->flash('success', __('messages.company_created'));
        $this->redirect(route('admin.users.index'));
    }
};
```

## Definition of Done

- [ ] Create company client form works
- [ ] List view displays all company clients
- [ ] Search and filter functional
- [ ] Edit company works with validation
- [ ] View profile shows complete information
- [ ] Duplicate prevention works
- [ ] Audit logging implemented
- [ ] Bilingual support complete
- [ ] Tests pass for all CRUD operations
- [ ] Code formatted with Pint

## Dependencies

- **Epic 1:** Authentication system, database schema
- **Story 2.1:** Same CRUD patterns

## Risk Assessment

- **Primary Risk:** Complex contact persons relationship
- **Mitigation:** Start simple (single contact), enhance later if needed
- **Rollback:** Use simple fields on users table

## Estimation

**Complexity:** Medium
**Estimated Effort:** 4-5 hours