Driver Management

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
Pending
In Review
Approved
Rejected

Display all drivers regardless of status

Status: pendienteColor: Yellow (#ffa726)New driver applications awaiting review

Status: en_revisionColor: Blue (#667eea)Documents currently being verified

Status: aprobadoColor: Green (#11998e)Fully verified and active drivers

Status: rechazadoColor: 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": "[email protected]",
  "telefono": "+57 300 123 4567",
  "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"
}

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;
}

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

Review Documents

Open driver details modal and review all provided documents

Verify Information

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

Tap Approve

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

Confirm Action

Confirm the approval in the dialog that appears

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

Review Documents

Identify issues or missing information in driver documents

Tap Reject

Press the red “Rechazar” button

Enter Reason

Required: Provide a clear explanation for rejectionExample: “Licencia de conducción vencida”

Confirm Rejection

Confirm the rejection with the provided reason

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.

User Management

Manage all platform users

Company Management

Assign drivers to companies

Audit Logs

View driver approval history

Dashboard

Management

Configuration

​Overview

​Driver Documents Screen

​Dashboard Statistics

Total Drivers

Pending

Approved

Expired Docs

​Verification Status Filters

​Driver Information Fields

​Personal Information

​Driver’s License

​Vehicle Information

​SOAT (Mandatory Insurance)

​Technomechanical Inspection

​Vehicle Insurance

​Other Documents

​Document Completeness Calculation

​Expired Documents Detection

​Driver Details Modal

​Approve Driver Use Case

​Approve Driver Action

​Approval Backend Endpoint

​Reject Driver Use Case

​Reject Driver Action

​Rejection Backend Endpoint

​Document Expiration Alerts

Expired

Expiring Soon

Valid

​Status Color Coding

​Audit Logging

​Document Types by Vehicle Category

​Motorcycle (motocicleta)

​Car (carro)

​Cargo Motorcycle (moto_carga)

​Cargo Van (carro_carga)

​Best Practices

​Related Features

User Management

Company Management

Audit Logs

Build docs developers (and LLMs) love

Overview

Driver Documents Screen

Dashboard Statistics

Verification Status Filters

Driver Information Fields

Personal Information

Driver’s License

Vehicle Information

SOAT (Mandatory Insurance)

Technomechanical Inspection

Vehicle Insurance

Other Documents

Document Completeness Calculation

Expired Documents Detection

Driver Details Modal

Approve Driver Use Case

Approve Driver Action

Approval Backend Endpoint

Reject Driver Use Case

Reject Driver Action

Rejection Backend Endpoint

Document Expiration Alerts

Status Color Coding

Audit Logging

Document Types by Vehicle Category

Motorcycle (motocicleta)

Car (carro)

Cargo Motorcycle (moto_carga)

Cargo Van (carro_carga)

Best Practices

Related Features