# KYC (Know Your Customer) System

## Overview

The KYC system provides a secure, encrypted way to collect and manage client verification information within proposals. It includes two-step validation, encrypted storage, and automated notifications.

## Features

### Core Functionality
- **KYC Process Management**: Create, send, and track KYC processes for proposals
- **Two-Step Validation**: Secure access with validation codes
- **Encrypted Storage**: All sensitive data is encrypted at rest
- **Document Uploads**: Support for multiple document types
- **Status Tracking**: Complete workflow from pending to approved/rejected
- **Email Notifications**: Automated notifications to KYC team

### KYC Statuses
- `pending` - KYC process created but not sent
- `sent` - KYC sent to client with access token
- `to_be_filled` - Client has opened the form
- `completed` - Client has submitted the form
- `approved` - KYC approved by admin
- `rejected` - KYC rejected with reason

### KYC Types
- `personal` - Individual client verification
- `company` - Corporate client verification

## Configuration

### Environment Variables

Add these to your `.env` file:

```env
# KYC Review Period (in months)
KYC_REVIEW_PERIOD_MONTHS=12

# KYC Database Connection (uses main database)
KYC_DB_CONNECTION=mysql

# Encryption Key (32 characters)
KYC_ENCRYPTION_KEY=your-32-character-encryption-key-here

# Notification Email
KYC_NOTIFICATION_EMAIL=kyc@xpto.com

# Security Settings
KYC_SESSION_TIMEOUT_MINUTES=30
KYC_MAX_ATTEMPTS=3
KYC_MAX_FILE_SIZE_MB=10
```

### Database Configuration

The KYC system uses the main database connection. No additional database configuration is required.

## Installation

### 1. Run Migrations

```bash
php artisan migrate
```

This will create the KYC tables in your main database.

### 2. Generate Encryption Key

```bash
php artisan tinker
echo bin2hex(random_bytes(32));
```

Copy the generated key to your `.env` file.

### 3. Update Configuration

Ensure your `.env` file has the required KYC variables:

```env
KYC_REVIEW_PERIOD_MONTHS=12
KYC_DB_CONNECTION=mysql
KYC_ENCRYPTION_KEY=your-generated-key-here
KYC_NOTIFICATION_EMAIL=kyc@xpto.com
```

## Usage

### In Proposals

The KYC system is integrated into the proposal edit page. Users can:

1. **Create KYC Process**: Initialize a new KYC process for a proposal
2. **Send KYC**: Generate access token and send to client
3. **Resend KYC**: Regenerate access token if needed
4. **Review KYC**: Approve or reject completed forms

### KYC Form Access

Clients access the KYC form via:
```
/kyc/form/{access_token}
```

The form includes:
- Two-step validation
- Personal information fields
- Address information
- Document uploads
- Encrypted submission

### Admin Review

Admins can review completed KYC forms and:
- Approve with optional notes
- Reject with detailed reasons
- View uploaded documents
- Track access logs

## Security Features

### Encryption
- All form data is encrypted using Laravel's encryption
- File paths and names are encrypted
- Access tokens are encrypted in database

### Access Control
- Two-step validation required
- Session timeout protection
- IP address logging
- Failed attempt tracking

### Data Protection
- Encrypted file storage
- Encrypted form data
- Access logging and audit trails

## API Endpoints

### Public Routes
- `GET /kyc/form/{token}` - KYC form for clients
- `GET /kyc/documents/{uuid}/download` - Document download

### Admin Routes
- `GET /kyc/review/{uuid}` - KYC review interface

## Database Schema

### Tables
- `kyc_processes` - Main KYC process information
- `kyc_documents` - Uploaded documents
- `kyc_access_logs` - Access and security logs

### Key Fields
- Encrypted access tokens
- Encrypted form data
- Document metadata
- Timestamps for all actions

## Email Notifications

### Notification Types
1. **KYC Sent** - When KYC is sent to client
2. **KYC Resent** - When KYC is resent
3. **KYC Completed** - When client submits form

### Email Templates
- Professional HTML templates
- Include access information
- Action buttons for admins
- Security notices

## Customization

### Form Fields
Modify the form fields in `app/Livewire/KycForm.php`:

```php
protected $rules = [
    'formData.full_name' => 'required|string|max:255',
    'formData.email' => 'required|email|max:255',
    // Add your custom fields here
];
```

### Document Types
Update document types in `app/Models/KycDocument.php`:

```php
public function getDocumentTypeLabelAttribute(): string
{
    $types = [
        'identity_document' => 'Identity Document',
        'proof_of_address' => 'Proof of Address',
        // Add your custom document types
    ];
    
    return $types[$this->document_type] ?? ucfirst(str_replace('_', ' ', $this->document_type));
}
```

### Status Labels
Customize status labels in `config/kyc.php`:

```php
'statuses' => [
    'pending' => 'Pending',
    'sent' => 'Sent',
    // Customize your status labels
],
```

## Troubleshooting

### Common Issues

1. **Encryption Key Error**
   - Ensure `KYC_ENCRYPTION_KEY` is set in `.env`
   - Key must be exactly 32 characters

2. **Database Connection Error**
   - Check `KYC_DB_CONNECTION` in `.env`
   - Verify database credentials

3. **File Upload Issues**
   - Check file size limits in `config/kyc.php`
   - Verify storage permissions

4. **Email Notifications**
   - Check mail configuration
   - Verify `KYC_NOTIFICATION_EMAIL` is set

### Logs
KYC system logs are stored in:
- Laravel logs: `storage/logs/laravel.log`
- Database: `kyc_access_logs` table

## Support

For technical support or questions about the KYC system:
- Email: {{ config('kyc.notification_email', 'kyc@xpto.com') }}
- Check the logs for detailed error information
- Review the access logs for security issues

## Compliance

This KYC system is designed to comply with:
- Data protection regulations
- Financial industry standards
- Security best practices
- Audit requirements

All data is encrypted, logged, and stored securely to meet compliance requirements.