# KYC Export System Documentation

## Overview
The KYC Export System provides comprehensive functionality to export all KYC questions and answers to Excel files, organized by department, and packaged in ZIP files with proper folder structure.

## Features

### 🎯 Export Types
1. **Complete Export (ZIP)**: All departments in separate Excel files, organized in folders
2. **Department Export**: Single department Excel file
3. **Single Process Export**: Individual process Excel file

### 📊 Export Formats
- **Excel Files (.xlsx)**: Structured data with multiple sheets
- **ZIP Files**: Department-organized folder structure
- **README Files**: Included in ZIP exports with structure explanation

### 🗂️ Department Organization
- Each department gets its own Excel file and folder
- Departments are automatically detected from existing KYC processes
- Supports custom department names and display formatting

## File Structure

### ZIP Export Structure
```
KYC_Export_2024-01-15_14-30-25.zip
├── README.txt
├── KYC_Complete_Export_2024-01-15_14-30-25.xlsx (All departments)
├── Legal/
│   └── Legal_2024-01-15_14-30-25.xlsx
├── Compliance/
│   └── Compliance_2024-01-15_14-30-25.xlsx
├── Finance/
│   └── Finance_2024-01-15_14-30-25.xlsx
└── Operations/
    └── Operations_2024-01-15_14-30-25.xlsx
```

### Excel File Structure
Each Excel file contains multiple sheets:
- **Summary Sheet**: Overview of all KYC processes
- **Department Sheets**: Detailed questions and responses by department

## Data Included

### Process Information
- Process ID
- Proposal Title
- Client Information (Name, Email, Company)
- Process Status and Timestamps
- Progress Tracking

### Question Details
- Question Text and Type
- Department Assignment
- Required/Optional Status
- Custom Question Indicator
- Display Order

### Response Data
- Response Text/Values
- File Upload Information
- Submission Details (Who, When)
- Completion Status

### File References
- File names and types
- Upload timestamps
- **Note**: Actual files are referenced but not included in exports

## Usage

### Via Web Interface

#### 1. Access Export Modal
- Navigate to KYC Process Manager
- Click "Export KYC Data" button (requires KYC management permissions)

#### 2. Choose Export Type
- **Complete Export**: Select for ZIP with all departments
- **Department Export**: Choose specific department
- **Single Process**: Select individual process

#### 3. Configure Options
- **Status Filter**: All, Pending, In Progress, Completed, Cancelled
- **Department Selection**: (for department exports)
- **Process Selection**: (for single process exports)

#### 4. Download
- Files are automatically downloaded after generation
- Temporary files are cleaned up automatically

### Programmatic Usage

```php
use App\Services\KycExportService;

$exportService = new KycExportService();

// Export all departments as ZIP
$result = $exportService->exportAllByDepartment('completed');
return $exportService->downloadAndCleanup($result['zip_path']);

// Export specific department
$result = $exportService->exportByDepartment('legal', 'completed');
return $exportService->downloadAndCleanup($result['file_path']);

// Export single process
$result = $exportService->exportProcess($processId);
return $exportService->downloadAndCleanup($result['file_path']);
```

## Statistics Dashboard

The export interface includes a statistics dashboard showing:
- Total processes count
- Completed processes count
- Completion rate percentage
- Number of departments
- Process count by department

## Security & Permissions

### Access Control
- Requires `canManageKyc()` permission for export functionality
- Individual process exports require same permissions
- View-only users cannot access export features

### Data Privacy
- Exports include sensitive client information
- Files are temporarily stored and automatically cleaned up
- Old exports are automatically purged after 7 days

## Technical Implementation

### Core Classes

#### KycExportService
Main service class handling:
- Export orchestration
- File management
- ZIP creation
- Cleanup operations

#### KycExport
Laravel Excel export class with:
- Multiple sheet support
- Department-based organization
- Styled formatting
- Auto-sizing columns

#### KycDepartmentSheet
Individual department sheet with:
- Filtered data by department
- Comprehensive question/response data
- Professional styling

#### KycSummarySheet
Overview sheet containing:
- Process summaries
- Progress tracking
- Department statistics

### Database Relationships
```
KycProcess
├── hasMany: KycQuestion
│   └── hasOne: KycResponse
└── belongsTo: Proposal
```

### File Management
- Temporary storage in `storage/app/exports/`
- Unique timestamped directories
- Automatic cleanup on completion
- Error handling with rollback

## Configuration

### Department Display Names
Configurable in `KycExportService::getDepartmentDisplayName()`:
```php
$departments = [
    'legal' => 'Legal',
    'compliance' => 'Compliance',
    'finance' => 'Finance',
    'operations' => 'Operations',
    'risk' => 'Risk Management',
    'general' => 'General Information',
];
```

### File Cleanup
- Default: 7 days retention
- Configurable in `cleanupOldExports($daysOld)`
- Manual cleanup available via UI

## Error Handling

### Common Errors
1. **No Data Found**: When no processes match criteria
2. **Permission Denied**: When user lacks KYC management rights
3. **File Creation Failed**: When storage issues occur
4. **ZIP Creation Failed**: When ZIP library encounters issues

### Error Recovery
- Automatic cleanup on failure
- Detailed error messages
- Graceful fallback to previous state

## Performance Considerations

### Large Datasets
- Streaming for large exports
- Memory-efficient processing
- Chunked data loading

### File Size Management
- Compression in ZIP files
- Optimized Excel formatting
- Selective data inclusion

## Maintenance

### Regular Tasks
1. **Cleanup Old Exports**: Run weekly via UI or cron
2. **Monitor Storage Usage**: Check `storage/app/exports/`
3. **Review Export Logs**: Monitor for errors

### Troubleshooting
1. **Check Permissions**: Verify user has `canManageKyc()`
2. **Storage Space**: Ensure adequate disk space
3. **PHP Memory**: Monitor memory usage for large exports
4. **ZIP Extension**: Verify PHP ZIP extension is enabled

## API Endpoints

### Export Statistics
```
GET /test-kyc-export
Response: {
  "stats": {...},
  "departments": [...]
}
```

### Livewire Methods
- `openExportModal()`: Show export dialog
- `exportKycData()`: Process export request
- `exportSingleProcess($id)`: Export individual process
- `cleanupOldExports()`: Remove old files

## Future Enhancements

### Planned Features
1. **Scheduled Exports**: Automated periodic exports
2. **Email Delivery**: Send exports via email
3. **Custom Templates**: User-defined export formats
4. **Audit Trail**: Track export activities
5. **Bulk Operations**: Export multiple selections

### Integration Opportunities
1. **Cloud Storage**: Direct upload to S3/Google Drive
2. **API Access**: RESTful export endpoints
3. **Webhooks**: Notify external systems
4. **Data Warehouse**: Direct database exports

## Support

For technical support or feature requests:
1. Check error logs in `storage/logs/`
2. Verify database relationships
3. Test with small datasets first
4. Contact system administrator for permissions issues

---

**Last Updated**: 2024-01-15  
**Version**: 1.0  
**Compatibility**: Laravel 10+, PHP 8.1+