# Comprehensive Audit Log System - Implementation Guide

## Overview
This guide explains how to use the comprehensive audit logging system implemented in the M1 ERP application. The system automatically tracks all CRUD operations, security events, and critical business transactions across all modules.

## Architecture

### Components
1. **Configuration** (`config/audit.php`) - Defines what to audit, retention policies, and sensitive fields
2. **AuditableTrait** (`core/AuditableTrait.php`) - Reusable methods for controllers
3. **AuditLog Model** (`models/AuditLog.php`) - Data access and advanced reporting
4. **Helper Functions** (`includes/helpers.php`) - Simplified audit logging
5. **Database Layer** - Indexes, views, and stored procedures for performance

## Quick Start

### Using the Trait in Controllers

```php
<?php
require_once BASE_PATH . '/core/Controller.php';
require_once BASE_PATH . '/core/AuditableTrait.php';

class CustomerController extends Controller {
    use AuditableTrait;  // Add this line
    
    private $model;
    
    public function __construct() {
        parent::__construct();
        $this->model = new Customer();
    }
    
    public function store() {
        $this->requireAuth();
        
        $data = [
            'name' => $_POST['name'],
            'email' => $_POST['email'],
            'phone' => $_POST['phone']
        ];
        
        $customerId = $this->model->create($data);
        
        // Audit the creation
        $this->auditCreate('customer', $customerId, $data);
        
        Session::setFlash('success', 'Customer created successfully', 'success');
        redirect(base_url('customers'));
    }
    
    public function update($id) {
        $this->requireAuth();
        
        // Get old values before update
        $oldCustomer = $this->model->getById($id);
        
        $newData = [
            'name' => $_POST['name'],
            'email' => $_POST['email'],
            'phone' => $_POST['phone']
        ];
        
        $this->model->update($id, $newData);
        
        // Audit the update with old and new values
        $this->auditUpdate('customer', $id, $oldCustomer, $newData);
        
        Session::setFlash('success', 'Customer updated successfully', 'success');
        redirect(base_url('customers'));
    }
    
    public function delete($id) {
        $this->requireAuth();
        
        // Get the record before deletion
        $customer = $this->model->getById($id);
        
        // Audit BEFORE deleting
        $this->auditDelete('customer', $id, $customer);
        
        $this->model->delete($id);
        
        Session::setFlash('success', 'Customer deleted', 'success');
        redirect(base_url('customers'));
    }
}
```

### Using Helper Functions (Alternative)

```php
<?php
// Simple audit call
audit('create', 'invoice', $invoiceId, null, $invoiceData);

// With custom description
audit('approve', 'purchase_order', $poId, null, null, 'PO approved for $' . $amount);

// Bulk operation
$deletedIds = [1, 2, 3, 4, 5];
auditBulk('delete', 'old_records', $deletedIds, 'Cleanup operation');

// Critical security action
auditCritical('permission_change', 'user', $userId, 'Admin privileges granted');
```

## Trait Methods Reference

### auditCreate($entityType, $entityId, $newValues, $description = null)
Log a create operation.

```php
$this->auditCreate('customer', $customerId, $_POST);
```

### auditUpdate($entityType, $entityId, $oldValues, $newValues, $description = null)
Log an update operation with change tracking.

```php
$this->auditUpdate('invoice', $invoiceId, $oldInvoice, $newInvoice);
```

### auditDelete($entityType, $entityId, $oldValues, $description = null)
Log a delete operation. Call BEFORE actually deleting.

```php
$this->auditDelete('product', $productId, $product);
```

### auditView($entityType, $entityId, $description = null)
Log viewing of sensitive data.

```php
$this->auditView('employee', $employeeId, 'Viewed salary information');
```

### auditExport($entityType, $filters, $recordCount, $format = 'csv')
Log data exports.

```php
$this->auditExport('customer', $_GET, count($customers), 'csv');
```

### auditAction($action, $entityType, $entityId, $oldValues, $newValues, $description)
Log custom actions (approve, void, post, etc.).

```php
$this->auditAction('approve', 'purchase_order', $poId, null, ['status' => 'approved']);
$this->auditAction('void', 'invoice', $invoiceId, $invoice, ['voided' => true], 'Invoice voided due to error');
$this->auditAction('post', 'journal_entry', $jeId, $oldStatus, $newStatus, 'Posted to GL');
```

### auditBulk($action, $entityType, $entityIds, $description = null)
Log bulk operations.

```php
$this->auditBulk('delete', 'expired_records', [1,2,3,4,5]);
```

### auditCritical($action, $entityType, $entityId, $description)
Log critical security actions. Automatically tagged as critical.

```php
$this->auditCritical('security_override', 'system', null, 'MFA requirement bypassed');
```

## Configuration

### Entity Configuration (`config/audit.php`)

```php
'entities' => [
    'your_entity' => [
        'enabled' => true,                    // Enable/disable auditing
        'actions' => ['create', 'update'],    // Which actions to track
        'retention_days' => 365,              // How long to keep logs
        'excluded_fields' => ['password'],    // Fields to exclude
        'tags' => ['finance', 'critical'],    // Tags for categorization
    ],
]
```

### Globally Excluded Fields
These fields are NEVER logged across any entity:
- password, password_hash
- token, secret, api_key
- private_key, access_token, refresh_token
- mfa_secret, backup_codes

Add more in `config/audit.php` under `globally_excluded_fields`.

## Advanced Features

### Entity Timeline
View full audit history for a specific record:

```php
$auditModel = new AuditLog();
$timeline = $auditModel->getEntityTimeline('customer', $customerId, 50);

// In your view:
foreach ($timeline as $entry) {
    echo $entry['action'] . ' by ' . $entry['user_name'] . ' on ' . $entry['created_at'];
    
    // Show changes
    $changedFields = json_decode($entry['changed_fields'], true);
    print_r($changedFields);
}
```

### Detect Suspicious Activity
```php
$auditModel = new AuditLog();
$suspicious = $auditModel->detectSuspiciousActivity(24); // Last 24 hours

foreach ($suspicious as $alert) {
    // $alert['alert_type']: 'Multiple Failed Logins', 'Bulk Delete Operation', etc.
    // $alert['user_name'], $alert['count'], $alert['last_action']
}
```

### Compliance Reports
```php
$auditModel = new AuditLog();

// Financial audit trail
$financial = $auditModel->getFinancialAuditTrail('2024-01-01', '2024-12-31');

// Security events
$security = $auditModel->getSecurityEvents(200);

// Custom compliance report
$report = $auditModel->getComplianceReport(
    '2024-01-01',
    '2024-12-31',
    ['user', 'role', 'permission', 'journal_entry']
);
```

### Failed Login Monitoring
```php
$auditModel = new AuditLog();
$failedLogins = $auditModel->getFailedAccessAttempts(24);

foreach ($failedLogins as $attempt) {
    if ($attempt['attempts_from_ip'] >= 5) {
        // Alert: potential brute force attack
    }
}
```

### Audit Statistics
```php
$auditModel = new AuditLog();
$stats = $auditModel->getAuditStatistics(30); // Last 30 days

// Returns:
// - total_logs
// - by_action (breakdown by action type)
// - by_entity (breakdown by entity type)
// - by_tag (breakdown by tags)
// - top_users (most active users)
// - by_hour (activity by hour of day)
```

### Archive Old Logs
```php
$auditModel = new AuditLog();
$archivedCount = $auditModel->archiveLogs(365); // Archive logs older than 365 days

echo "Archived {$archivedCount} audit log entries";
```

## Examples by Module

### Financial Module Example
```php
class JournalEntryController extends Controller {
    use AuditableTrait;
    
    public function post($id) {
        $je = $this->model->getById($id);
        
        // Critical financial action
        $this->auditAction(
            'post',
            'journal_entry',
            $id,
            ['status' => 'draft'],
            ['status' => 'posted'],
            "Journal Entry #{$id} posted with total: $" . $je['total']
        );
        
        $this->model->post($id);
    }
    
    public function void($id) {
        $je = $this->model->getById($id);
        
        // Critical action - tagged automatically
        $this->auditAction('void', 'journal_entry', $id, $je, ['voided' => true]);
        
        $this->model->void($id);
    }
}
```

### HR Module Example
```php
class EmployeeController extends Controller {
    use AuditableTrait;
    
    public function terminate($id) {
        $employee = $this->model->getById($id);
        
        $this->auditAction(
            'terminate',
            'employee',
            $id,
            ['status' => 'active'],
            ['status' => 'terminated', 'termination_date' => date('Y-m-d')],
            "Employee terminated: " . $employee['first_name'] . ' ' . $employee['last_name']
        );
        
        $this->model->terminate($id);
    }
}
```

### Inventory Module Example
```php
class StockMovementController extends Controller {
    use AuditableTrait;
    
    public function adjust($productId) {
        $oldQuantity = $this->model->getQuantity($productId);
        $newQuantity = $_POST['quantity'];
        $reason = $_POST['reason'];
        
        $this->auditAction(
            'adjust',
            'inventory_adjustment',
            $productId,
            ['quantity' => $oldQuantity],
            ['quantity' => $newQuantity],
            "Inventory adjusted: {$oldQuantity} → {$newQuantity}. Reason: {$reason}"
        );
        
        $this->model->adjust($productId, $newQuantity);
    }
}
```

## Performance Considerations

### Indexes
The migration adds these indexes automatically:
- `idx_audit_user_created` - User + date queries
- `idx_audit_entity` - Entity lookups
- `idx_audit_action` - Action filtering
- `idx_audit_created` - Date sorting
- `idx_audit_tags` - Tag searches

### Database Views
Pre-computed views for common queries:
- `v_recent_critical_activity` - Last 100 critical actions
- `v_recent_security_events` - Last 200 security events
- `v_financial_audit_trail` - All financial transactions

### Archiving
Use the archive function to move old logs to `audit_logs_archive`:

```php
// Run monthly via cron
$auditModel = new AuditLog();
$auditModel->archiveLogs(365); // Keep 1 year in main table
```

## Security Best Practices

1. **Never log sensitive data** - Configure excluded fields in `config/audit.php`
2. **Always audit before delete** - Capture data before it's gone
3. **Use descriptive messages** - Help future investigations
4. **Tag appropriately** - Use tags for compliance filtering
5. **Monitor suspicious activity** - Set up alerts for failed logins, bulk deletes

## Compliance Features

### Financial Compliance (SOX, GAAP)
- 7-year retention for financial records
- Complete audit trail of all transactions
- Who, what, when, and why captured
- Immutable log entries

### HR Compliance (GDPR, Employment Law)
- 7-year retention for payroll and HR records
- Sensitive fields excluded (SSN, etc.)
- Employee data access tracking
- Termination audit trail

### Security Compliance (SOC 2, ISO 27001)
- All permission changes logged
- Failed login tracking
- Critical action monitoring
- After-hours activity alerts

## Troubleshooting

### Auditing not working?
1. Check `config/audit.php` - ensure `enabled => true`
2. Check entity is configured in `entities` array
3. Verify action is listed in entity's `actions` array
4. Check file permissions on config file

### Too many logs?
1. Adjust retention_days per entity type
2. Run archive function monthly
3. Reduce actions being tracked
4. Exclude non-critical entity types

### Performance issues?
1. Ensure migration indexes are created
2. Archive old logs regularly
3. Consider partitioning audit_logs table by month
4. Use database views for common queries

## Future Enhancements

Potential additions to the system:
- Real-time alerts via email/SMS
- Dashboard widget for recent activity
- Audit log search with advanced filters
- Machine learning for anomaly detection
- Integration with SIEM systems
- Audit log signing for tamper detection

## Support

For questions or issues with the audit system:
1. Check this guide
2. Review `config/audit.php` comments
3. Examine `core/AuditableTrait.php` source
4. Review `models/AuditLog.php` methods
5. Check database views and stored procedures

## Changelog

### Version 1.0 (2024-12-22)
- Initial comprehensive audit system implementation
- AuditableTrait for controllers
- Configuration-driven auditing
- Advanced reporting features
- Compliance views and reports
- Archiving and retention policies
- Stored procedures for common operations