# Agent Module Deployment Guide

This guide provides instructions for deploying the Agent Module to production.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Database Setup](#database-setup)
3. [Environment Configuration](#environment-configuration)
4. [Asset Compilation](#asset-compilation)
5. [Service Worker Registration](#service-worker-registration)
6. [Push Notification Setup](#push-notification-setup)
7. [Scheduled Tasks](#scheduled-tasks)
8. [Deployment Process](#deployment-process)
9. [Post-Deployment Verification](#post-deployment-verification)
10. [Rollback Procedure](#rollback-procedure)

## Prerequisites

Before deploying the Agent Module, ensure you have the following:

- PHP 8.1 or higher
- MySQL 8.0 or higher
- Composer
- Node.js 16 or higher
- npm or Yarn
- Web server (Apache or Nginx)
- SSL certificate (required for PWA and push notifications)

## Database Setup

The Agent Module requires several database tables to be created.

### Run Migrations

```bash
php artisan migrate
```

### Seed Initial Data

```bash
php artisan db:seed --class=AgentModuleSeeder
```

## Environment Configuration

Configure the environment variables for the Agent Module.

### Required Environment Variables

Add the following to your `.env` file:

```
# Agent Module Configuration
AGENT_MODULE_ENABLED=true
AGENT_REFERRAL_COMMISSION_RATE=0.1
AGENT_REFERRAL_EXPIRY_DAYS=30

# Push Notification Configuration
VAPID_PUBLIC_KEY=your-vapid-public-key
VAPID_PRIVATE_KEY=your-vapid-private-key
VAPID_SUBJECT=mailto:admin@example.com

# File Storage Configuration
AGENT_STORAGE_DISK=public
```

### Generate VAPID Keys

To generate VAPID keys for push notifications:

```bash
php artisan agent:generate-vapid-keys
```

## Asset Compilation

Compile the assets for production.

### Install Dependencies

```bash
npm install
```

### Compile Assets

```bash
npm run build
```

## Service Worker Registration

The service worker is automatically registered when the application loads. The service worker file is located at `public/service-worker.js`.

### Customizing the Service Worker

If you need to customize the service worker:

1. Edit `public/service-worker.js`
2. Update the cache name and version if necessary
3. Modify the list of assets to cache
4. Adjust the caching strategy as needed

## Push Notification Setup

Configure push notifications for the Agent Module.

### Server Configuration

1. Ensure the VAPID keys are set in the `.env` file
2. Configure the push notification service in `config/services.php`

### Client Configuration

The client-side push notification setup is handled automatically by the service worker registration script.

## Scheduled Tasks

The Agent Module includes several scheduled tasks that need to be configured.

### Configure Scheduler

Add the Laravel scheduler to your crontab:

```
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
```

### Agent Module Tasks

The following tasks are scheduled:

- **Process Scheduled Reports**: Generates and sends scheduled reports
- **Check Goal Progress**: Updates goal progress and marks goals as achieved or expired
- **Send Notification Reminders**: Sends reminders for unread messages and announcements
- **Clean Up Expired Exports**: Removes expired report exports

## Deployment Process

Follow these steps to deploy the Agent Module to production.

### Deployment Steps

1. **Backup the Database**:
   ```bash
   php artisan db:backup
   ```

2. **Put the Application in Maintenance Mode**:
   ```bash
   php artisan down
   ```

3. **Pull the Latest Code**:
   ```bash
   git pull origin main
   ```

4. **Install Dependencies**:
   ```bash
   composer install --no-dev --optimize-autoloader
   ```

5. **Run Migrations**:
   ```bash
   php artisan migrate --force
   ```

6. **Compile Assets**:
   ```bash
   npm run build
   ```

7. **Clear Caches**:
   ```bash
   php artisan optimize:clear
   php artisan optimize
   ```

8. **Bring the Application Back Online**:
   ```bash
   php artisan up
   ```

## Post-Deployment Verification

After deploying the Agent Module, verify that everything is working correctly.

### Verification Checklist

- [ ] **Database Migrations**: Verify that all migrations have been applied
- [ ] **Asset Compilation**: Check that all assets are loading correctly
- [ ] **Service Worker**: Verify that the service worker is registered and active
- [ ] **Push Notifications**: Test sending a push notification
- [ ] **Scheduled Tasks**: Verify that scheduled tasks are running
- [ ] **Feature Testing**: Test all major features of the Agent Module

### Automated Tests

Run the automated tests to ensure everything is working:

```bash
php artisan test --testsuite=Agent
```

## Rollback Procedure

If you encounter issues after deployment, follow these steps to roll back.

### Rollback Steps

1. **Put the Application in Maintenance Mode**:
   ```bash
   php artisan down
   ```

2. **Restore the Previous Code**:
   ```bash
   git checkout previous-version
   ```

3. **Restore the Database**:
   ```bash
   php artisan db:restore --backup=backup-name
   ```

4. **Install Dependencies**:
   ```bash
   composer install --no-dev --optimize-autoloader
   ```

5. **Compile Assets**:
   ```bash
   npm run build
   ```

6. **Clear Caches**:
   ```bash
   php artisan optimize:clear
   php artisan optimize
   ```

7. **Bring the Application Back Online**:
   ```bash
   php artisan up
   ```

### Reporting Deployment Issues

If you encounter issues during deployment:

1. Check the Laravel log files in `storage/logs`
2. Review the web server error logs
3. Contact the development team with detailed information about the issue