# Automatic Conflict Management System

## Overview

The Automatic Conflict Management System automatically initiates conflict review processes when proposals are approved through **any method**. This ensures that all approved proposals undergo proper legal review to identify potential conflicts of interest before proceeding.

## How It Works

### 1. Trigger Events
The system automatically triggers when a proposal is marked as **approved** through any of these methods:

1. **Dashboard/Manager Approve Buttons**: Using `markAsApproved()` method
2. **Edit Proposal Form**: Changing status to "approved" in the edit form
3. **Create Proposal Form**: Creating a proposal with "approved" status
4. **API/Direct Updates**: Any direct call to `markAsApproved()` method

### 2. Automatic Process
When triggered, the system automatically:

1. **Identifies Active Lawyers**: Finds all users with the `lawyer` role and `active` status
2. **Creates Conflict Reviews**: Generates individual conflict review records for each lawyer
3. **Updates Proposal Status**: Changes the proposal status from `approved` to `pending_review`
4. **Sends Notifications**: Emails all lawyers about the new conflict review requirement
5. **Logs Activity**: Records the automatic initiation for audit purposes

## Technical Implementation

### Core Methods

#### `markAsApproved()` in Proposal Model
```php
public function markAsApproved(?string $feedback = null): void
{
    $this->update([
        'status' => 'approved',
        'response_date' => now(),
        'client_feedback' => $feedback ?: $this->client_feedback,
    ]);

    // Automatically initiate conflict management process
    $this->initiateAutomaticConflictManagement();
}
```

#### `initiateAutomaticConflictManagement()` in Proposal Model
- Finds all active lawyers
- Creates conflict review records
- Updates proposal status to `pending_review`
- Sends email notifications
- Logs the process

### UI Integration

#### EditProposal Component
- Detects when status is changed to "approved"
- Calls `markAsApproved()` instead of regular update
- Shows appropriate success message with lawyer count

#### CreateProposal Component  
- Detects when proposal is created with "approved" status
- Calls `markAsApproved()` after creation
- Shows appropriate success message with lawyer count

#### ProposalsDashboard & ProposalsManager Components
- Approve buttons call `markAsApproved()` method
- Display feedback about automatic conflict review initiation
- Show lawyer count in success messages

## Status Flow

```
Proposal Created/Updated with "approved" status
           ↓
    markAsApproved() called
           ↓
  initiateAutomaticConflictManagement()
           ↓
    Status changed to "pending_review"
           ↓
   Conflict reviews created for all lawyers
           ↓
    Email notifications sent
           ↓
    Lawyers review for conflicts
           ↓
    Status changes based on review results:
    - "ready_to_send" (no conflicts)
    - "conflict_detected" (conflicts found)
```

## UI Indicators

### Status Display
- **🤖 Auto Conflict Review**: Shows when automatic process is active
- **Lawyer Count**: Displays number of lawyers notified
- **Progress Indicators**: Shows review completion status

### Success Messages
- **Dashboard/Manager**: "Proposal marked as approved! Automatic conflict review initiated with X lawyers."
- **Edit Form**: "Proposal updated and marked as approved! Automatic conflict review initiated with X lawyers."
- **Create Form**: "Proposal created and marked as approved! Automatic conflict review initiated with X lawyers."

## Database Structure

### Conflict Reviews Table
```sql
- id (primary key)
- proposal_id (foreign key)
- lawyer_id (foreign key) 
- status (pending/approved/conflict_detected)
- notes (includes "Automatically initiated due to proposal approval")
- reviewed_at (timestamp)
- created_at/updated_at
```

### Proposal Status Values
- `pending_review`: Under automatic conflict review
- `ready_to_send`: Approved by all lawyers, no conflicts
- `conflict_detected`: One or more lawyers found conflicts

## Email Notifications

### Automatic Notification Email
- **Subject**: "Conflict of Interest Review Required - [Proposal Title]"
- **Content**: Proposal details, review instructions, deadline
- **Recipients**: All active lawyers
- **Template**: `resources/views/emails/conflict-review-notification.blade.php`

## Testing

The system has been comprehensively tested for all approval scenarios:

1. ✅ **Dashboard Approve Button**: `markAsApproved()` method
2. ✅ **Edit Form Status Change**: Status dropdown to "approved"  
3. ✅ **Create Form Approved Status**: Creating with "approved" status
4. ✅ **Multiple Lawyers**: Creates reviews for all active lawyers
5. ✅ **Email Notifications**: Sends to all lawyers
6. ✅ **Status Updates**: Correctly changes to `pending_review`
7. ✅ **UI Feedback**: Shows appropriate success messages

## Logging

All automatic conflict management activities are logged:

```
[INFO] Automatic conflict management initiated for approved proposal X (Title). Y lawyers notified.
[INFO] Automatic conflict review notification sent to lawyer: email@domain.com for approved proposal: Title
```

## Troubleshooting

### No Lawyers Available
- System logs warning: "No active lawyers found for automatic conflict review"
- Proposal remains in `approved` status
- Admin should add lawyers with `lawyer` role

### Email Failures
- Individual email failures are logged
- System continues processing other lawyers
- Failed notifications can be resent manually

## Configuration

### Required User Roles
- **Lawyers**: Users with `role = 'lawyer'` and `status = 'active'`
- **Admins**: Can manage the conflict review process

### Email Settings
- Configure SMTP settings in `.env`
- Test email functionality before deployment

## Security

- Only authenticated users can trigger approvals
- Conflict reviews are restricted to assigned lawyers
- Audit trail maintained for all activities
- Email content includes security warnings