# Epic 2: User Management System

## Epic Goal

Enable the admin to create, manage, and control all user accounts (individual and corporate clients) with full lifecycle management including activation, deactivation, and deletion.

## Epic Description

### Business Context

Libra Law Firm operates with admin-controlled user accounts. Clients cannot self-register - the lawyer creates all accounts manually. The system must support two client types: individual clients and company/corporate clients with different data requirements.

### Technical Context

- **User Types:** Individual, Company/Corporate
- **Account States:** Active, Deactivated, Deleted
- **Password Management:** Admin-only (no client reset)
- **Notifications:** Email on account creation with credentials

### Success Criteria

- [ ] Admin can create individual client accounts
- [ ] Admin can create company/corporate client accounts
- [ ] Admin can convert between account types
- [ ] Admin can deactivate accounts (data retained)
- [ ] Admin can permanently delete accounts
- [ ] Admin can reset client passwords
- [ ] Welcome email sent with login credentials
- [ ] User search and filtering functional
- [ ] All operations logged for audit

---

## Stories

### Story 2.1: Individual Client Account Management

**Description:** Implement CRUD operations for individual client accounts by admin.

**Acceptance Criteria:**
- [ ] Create individual client form with fields:
  - Full Name (required)
  - National ID Number (required, unique)
  - Email Address (required, unique)
  - Phone Number (required)
  - Password (admin-set, required)
  - Preferred Language (Arabic/English)
- [ ] List view of all individual clients
- [ ] Edit client information
- [ ] View client profile with consultation/timeline history
- [ ] Search by name, email, or National ID
- [ ] Filter by status (active/deactivated)
- [ ] Validation for all required fields
- [ ] Duplicate email/ID prevention

**Technical Notes:**
- Store user_type as 'individual' in users table
- Use Volt components for forms
- Implement proper form validation

---

### Story 2.2: Company/Corporate Client Account Management

**Description:** Implement CRUD operations for company client accounts with support for multiple contact persons.

**Acceptance Criteria:**
- [ ] Create company client form with 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)
- [ ] Support unlimited contact persons per company
- [ ] List view of all company clients
- [ ] Edit company and contact person information
- [ ] View company profile with consultation/timeline history
- [ ] Search by company name, email, or registration number
- [ ] Filter by status (active/deactivated)

**Technical Notes:**
- Store user_type as 'company' in users table
- Consider separate contact_persons table for multiple contacts
- Company fields nullable for individual accounts

---

### Story 2.3: Account Type Conversion

**Description:** Allow admin to convert individual accounts to company accounts and vice versa.

**Acceptance Criteria:**
- [ ] Convert individual to company account
  - Prompt for additional company fields
  - Preserve existing data (name, email, phone)
  - Preserve consultation and timeline history
- [ ] Convert company to individual account
  - Prompt for individual-specific fields
  - Handle company-specific data appropriately
  - Preserve consultation and timeline history
- [ ] Confirmation dialog before conversion
- [ ] Audit log entry for conversion
- [ ] Email notification to user about account type change

**Technical Notes:**
- Implement as dedicated admin action
- Ensure all relationships preserved during conversion
- Log old and new values in admin_logs

---

### Story 2.4: Account Lifecycle Management

**Description:** Implement account deactivation, reactivation, and permanent deletion with proper data handling.

**Acceptance Criteria:**
- [ ] **Deactivate Account:**
  - User cannot login
  - All data retained (consultations, timelines)
  - Account marked as deactivated
  - Can be reactivated by admin
  - Visual indicator in user list
- [ ] **Reactivate Account:**
  - Restore login ability
  - All data intact
  - Email notification to user
- [ ] **Delete Account:**
  - Confirmation dialog with warning
  - Permanently removes user
  - Cascades to: consultations, timelines, notifications
  - Cannot be recovered
  - Audit log entry preserved
- [ ] Admin can reset client password
  - Generate new password or set manually
  - Email new credentials to client
- [ ] All actions logged in admin_logs table

**Technical Notes:**
- Use soft deletes for deactivation (status field)
- Hard delete for permanent deletion with cascade
- Password reset sends new credentials via email

---

### Story 2.5: Account Creation Email Notification

**Description:** Send welcome email with login credentials when admin creates a new account.

**Acceptance Criteria:**
- [ ] Welcome email sent automatically on account creation
- [ ] Email includes:
  - Personalized greeting (name/company name)
  - Login credentials (email, password)
  - Login URL
  - Brief platform introduction
- [ ] Email in user's preferred language
- [ ] Sender: no-reply@libra.ps
- [ ] Sender Name: Libra Law Firm / مكتب ليبرا للمحاماة
- [ ] Professional email template with brand colors
- [ ] Plain text fallback

**Technical Notes:**
- Use Laravel Mail with Mailable class
- Reference PRD Section 8 for email requirements
- Depends on Epic 8 for full email infrastructure

---

## Dependencies

| Epic | Dependency |
|------|------------|
| Epic 1 | Authentication system, database schema, bilingual support |
| Epic 8 | Email notification system (partial - welcome email) |

## Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Data loss on deletion | High | Require confirmation, clear warning, audit log |
| Account type conversion data loss | Medium | Validate all data preserved before commit |
| Email delivery failures | Medium | Queue emails, implement retry logic |

## Definition of Done

- [ ] All stories completed with acceptance criteria met
- [ ] Tests for all CRUD operations
- [ ] Tests for account lifecycle (deactivate/delete)
- [ ] Tests for account type conversion
- [ ] Bilingual support for all UI elements
- [ ] Audit logging verified
- [ ] Email notifications sending correctly
- [ ] Code formatted with Pint