Driver Management

Approve drivers, verify documents, and manage driver status

Overview

Driver Management provides comprehensive tools for reviewing driver applications, verifying required documents, and monitoring driver compliance with platform requirements.

All drivers must have their documents verified and approved before they can accept ride requests on the platform.

Driver Documents Screen

Access the driver documents management interface:

admin/presentation/screens/conductores_documentos_screen.dart

class ConductoresDocumentosScreen extends StatefulWidget {
  final int adminId;

  const ConductoresDocumentosScreen({
    super.key,
    required this.adminId,
  });
}

Dashboard Statistics

The driver documents screen displays real-time statistics:

Total Drivers

All registered drivers in the system

Pending

Drivers awaiting document review

Approved

Verified and active drivers

Expired Docs

Drivers with expired documents

Verification Status Filters

Filter drivers by their verification status:

All

Display all drivers regardless of status

Pending

Status: pendiente

Color: Yellow (#ffa726)

New driver applications awaiting review

In Review

Status: en_revision

Color: Blue (#667eea)

Documents currently being verified

Approved

Status: aprobado

Color: Green (#11998e)

Fully verified and active drivers

Rejected

Status: rechazado

Color: Red (#f5576c)

Applications rejected due to invalid documents

Driver Information Fields

The system tracks comprehensive driver information:

Personal Information

{
  "nombre": "Juan",
  "apellido": "Pérez",
  "email": "[e-mail]",
  "telefono": "[phone]",
  "es_activo": 1,
  "estado_verificacion": "pendiente"
}

Driver’s License

{
  "licencia_conduccion": "12345678",
  "licencia_categoria": "C2",
  "licencia_expedicion": "2020-01-15",
  "licencia_vencimiento": "2030-01-15"
}

The system automatically alerts when a driver’s license is within 30 days of expiration.

Vehicle Information

{
  "vehiculo_tipo": "carro",      // motocicleta, carro, furgoneta, camión
  "vehiculo_placa": "ABC123",
  "vehiculo_marca": "Toyota",
  "vehiculo_modelo": "Corolla",
  "vehiculo_anio": 2020,
  "vehiculo_color": "Blanco"
}

SOAT (Mandatory Insurance)

{
  "soat_numero": "SOAT-2024-001",
  "soat_vencimiento": "2024-12-31"
}

Technomechanical Inspection

{
  "tecnomecanica_numero": "TEC-2024-001",
  "tecnomecanica_vencimiento": "2024-10-15"
}

Vehicle Insurance

{
  "aseguradora": "Seguros Bolivar",
  "numero_poliza_seguro": "POL-2024-001",
  "vencimiento_seguro": "2024-12-31"
}

Other Documents

{
  "tarjeta_propiedad_numero": "TP-2020-001"
}

Document Completeness Calculation

The system automatically calculates document completeness percentage:

int _calculateCompleteness(Map<String, dynamic> conductor) {
  int count = 0;
  int total = 8;

  if (conductor['licencia_conduccion'] != null && 
      conductor['licencia_conduccion'].toString().isNotEmpty) count++;
  if (conductor['licencia_vencimiento'] != null) count++;
  if (conductor['vehiculo_placa'] != null && 
      conductor['vehiculo_placa'].toString().isNotEmpty) count++;
  if (conductor['soat_numero'] != null && 
      conductor['soat_numero'].toString().isNotEmpty) count++;
  if (conductor['tecnomecanica_numero'] != null && 
      conductor['tecnomecanica_numero'].toString().isNotEmpty) count++;
  if (conductor['aseguradora'] != null && 
      conductor['aseguradora'].toString().isNotEmpty) count++;
  if (conductor['vehiculo_marca'] != null) count++;
  if (conductor['vehiculo_modelo'] != null) count++;

  return ((count / total) * 100).round();
}

Expired Documents Detection

Automatic detection of expired or soon-to-expire documents:

bool _hasExpiredDocuments(Map<String, dynamic> conductor) {
  final now = DateTime.now();
  
  // Check license expiration
  if (conductor['licencia_vencimiento'] != null) {
    final licenciaExp = DateTime.parse(conductor['licencia_vencimiento']);
    if (licenciaExp.isBefore(now)) return true;
  }
  
  // Check SOAT expiration
  if (conductor['soat_vencimiento'] != null) {
    final soatExp = DateTime.parse(conductor['soat_vencimiento']);
    if (soatExp.isBefore(now)) return true;
  }
  
  // Check technomechanical expiration
  if (conductor['tecnomecanica_vencimiento'] != null) {
    final tecExp = DateTime.parse(conductor['tecnomecanica_vencimiento']);
    if (tecExp.isBefore(now)) return true;
  }
  
  return false;
}

Driver Details Modal

View comprehensive driver information in a detailed modal:

void _showDriverDetails(Map<String, dynamic> conductor) {
  showModalBottomSheet(
    context: context,
    isScrollControlled: true,
    backgroundColor: Colors.transparent,
    builder: (context) => DraggableScrollableSheet(
      initialChildSize: 0.9,
      minChildSize: 0.5,
      maxChildSize: 0.95,
      builder: (context, scrollController) {
        return Container(
          decoration: BoxDecoration(
            color: Colors.black,
            borderRadius: BorderRadius.vertical(top: Radius.circular(24)),
          ),
          child: SingleChildScrollView(
            controller: scrollController,
            child: Column(
              children: [
                _buildHeader(conductor),
                _buildPersonalInfo(conductor),
                _buildLicenseInfo(conductor),
                _buildVehicleInfo(conductor),
                _buildSOATInfo(conductor),
                _buildTechnomechanicalInfo(conductor),
                _buildInsuranceInfo(conductor),
                _buildVerificationStatus(conductor),
                _buildActionButtons(conductor),
              ],
            ),
          ),
        );
      },
    ),
  );
}

Approve Driver Use Case

admin/domain/usecases/approve_driver.dart

class ApproveDriver {
  final AdminRepository repository;

  ApproveDriver(this.repository);

  Future<Result<void>> call(int conductorId) async {
    if (conductorId <= 0) {
      return Error(ValidationFailure('ID de conductor inválido'));
    }

    return await repository.approveDriver(conductorId);
  }
}

Approve Driver Action

1. Review Documents

   Open driver details modal and review all provided documents

2. Verify Information

   Check that license, vehicle, insurance, and SOAT are valid

3. Tap Approve

   Press the green “Aprobar” button at the bottom of the modal

4. Confirm Action

   Confirm the approval in the dialog that appears

5. Driver Activated

   Driver status changes to “aprobado” and they can now accept rides

Approval Backend Endpoint

backend/admin/aprobar_conductor.php

// POST /admin/aprobar_conductor.php
{
  "conductor_id": 123
}

// Updates:
// - estado_verificacion = "aprobado"
// - es_verificado = 1
// - Logs action in audit_logs

Reject Driver Use Case

admin/domain/usecases/reject_driver.dart

class RejectDriver {
  final AdminRepository repository;

  RejectDriver(this.repository);

  Future<Result<void>> call(int conductorId, String motivo) async {
    if (conductorId <= 0) {
      return Error(ValidationFailure('ID de conductor inválido'));
    }
    if (motivo.isEmpty) {
      return Error(ValidationFailure('Debe proporcionar un motivo'));
    }

    return await repository.rejectDriver(conductorId, motivo);
  }
}

Reject Driver Action

1. Review Documents

   Identify issues or missing information in driver documents

2. Tap Reject

   Press the red “Rechazar” button

3. Enter Reason

   Required: Provide a clear explanation for rejection

   Example: “Licencia de conducción vencida”

4. Confirm Rejection

   Confirm the rejection with the provided reason

5. Driver Notified

   Driver status changes to “rechazado” and reason is logged

Rejection Backend Endpoint

backend/admin/rechazar_conductor.php

// POST /admin/rechazar_conductor.php
{
  "conductor_id": 123,
  "motivo": "Licencia de conducción vencida"
}

// Updates:
// - estado_verificacion = "rechazado"
// - Logs action with motivo in audit_logs

Document Expiration Alerts

Visual indicators for document expiration:

Expired

Document is past expiration date

Expiring Soon

Document expires within 30 days

Valid

Document is valid and current

Status Color Coding

Status	Color	Hex Code	Icon
Pendiente	Yellow	#ffa726	Clock
En Revisión	Blue	#667eea	Eye
Aprobado	Green	#11998e	Check Circle
Rechazado	Red	#f5576c	X Circle

Audit Logging

All driver approval/rejection actions are logged:

INSERT INTO audit_logs (
  admin_id,
  usuario_afectado_id,
  accion,
  descripcion,
  ip_address,
  user_agent
) VALUES (
  1,
  123,
  'aprobar_conductor',
  'Conductor aprobado: Juan Pérez (ID: 123)',
  '192.168.1.100',
  'Mozilla/5.0...'
);

All approvals and rejections are tracked in the audit logs with timestamps, admin IDs, and reasons (for rejections).

Document Types by Vehicle Category

Motorcycle (motocicleta)

• Driver’s license (Category A2 or higher)
• SOAT
• Technomechanical inspection
• Vehicle registration

Car (carro)

• Driver’s license (Category C1 or higher)
• SOAT
• Technomechanical inspection
• Vehicle insurance
• Vehicle registration

Cargo Motorcycle (moto_carga)

• Driver’s license (Category C1 or higher)
• SOAT
• Technomechanical inspection
• Cargo permit
• Vehicle registration

Cargo Van (carro_carga)

• Driver’s license (Category C2 or higher)
• SOAT
• Technomechanical inspection
• Commercial insurance
• Cargo permit
• Vehicle registration

Best Practices

Review Thoroughly

Always review all documents before approving. Check expiration dates, license categories, and vehicle information.

Provide Clear Rejection Reasons

When rejecting a driver, provide specific, actionable feedback so they know what to correct.

Monitor Expirations

Regularly check the “Expired Docs” count and proactively notify drivers to renew documents.

Track Pending Applications

Process pending driver applications promptly to maintain good driver onboarding experience.

Related Features

User Management

Manage all platform users

Company Management

Assign drivers to companies

Audit Logs

View driver approval history