Company Management

Overview

Company Management provides tools for creating and managing transport companies, assigning drivers, and monitoring company performance within the Viax platform.

Transport Company Entity

Companies are represented by a comprehensive entity:

admin/domain/entities/empresa_transporte.dart

class EmpresaTransporte {
  final int id;
  final String nombre;
  final String? nit;
  final String? razonSocial;
  final String? email;
  final String? telefono;
  final String? telefonoSecundario;
  final String? direccion;
  final String? municipio;
  final String? departamento;
  final String? representanteNombre;
  final String? representanteTelefono;
  final String? representanteEmail;
  final List<String> tiposVehiculo;
  final String? logoUrl;
  final String? descripcion;
  final EmpresaEstado estado;
  final bool verificada;
  final DateTime? fechaVerificacion;
  final int? verificadoPor;
  final int totalConductores;
  final int totalViajesCompletados;
  final double calificacionPromedio;
  final double comisionAdminPorcentaje;
  final DateTime creadoEn;
  final DateTime? actualizadoEn;
  final int? creadoPor;
  final String? notasAdmin;
}

Company States

Active
Inactive
Suspended
Pending
Deleted

Status: activoDisplay: ActivoCompany is operational and accepting drivers

Status: inactivoDisplay: InactivoCompany temporarily suspended operations

Status: suspendidoDisplay: SuspendidoCompany suspended by admin for policy violations

Status: pendienteDisplay: PendienteNew company awaiting verification

Status: eliminadoDisplay: EliminadoCompany soft-deleted from the system

Estado Enum Implementation

admin/domain/entities/empresa_transporte.dart

enum EmpresaEstado {
  activo('activo', 'Activo'),
  inactivo('inactivo', 'Inactivo'),
  suspendido('suspendido', 'Suspendido'),
  pendiente('pendiente', 'Pendiente'),
  eliminado('eliminado', 'Eliminado');

  final String value;
  final String displayName;
  
  const EmpresaEstado(this.value, this.displayName);

  static EmpresaEstado fromString(String? value) {
    return EmpresaEstado.values.firstWhere(
      (e) => e.value == value,
      orElse: () => EmpresaEstado.activo,
    );
  }
}

Company Statistics

Track platform-wide company metrics:

admin/domain/entities/empresa_transporte.dart

class EmpresaStats {
  final int totalEmpresas;
  final int activas;
  final int inactivas;
  final int pendientes;
  final int verificadas;
  final int totalConductores;
  final int totalViajes;

  const EmpresaStats({
    required this.totalEmpresas,
    required this.activas,
    required this.inactivas,
    required this.pendientes,
    required this.verificadas,
    required this.totalConductores,
    required this.totalViajes,
  });
}

Total Companies

All registered transport companies

Active Companies

Currently operational companies

Total Drivers

Drivers across all companies

Verified Companies

Companies with verified credentials

Pending

Companies awaiting verification

Total Trips

Completed trips across all companies

Company Information Fields

Basic Information

{
  "nombre": "Transportes Rápidos S.A.",
  "nit": "900123456-7",
  "razon_social": "Transportes Rápidos Sociedad Anónima",
  "descripcion": "Empresa de transporte especializada en servicio urbano"
}

Contact Information

{
  "email": "info@transportesrapidos.com",
  "telefono": "+57 601 234 5678",
  "telefono_secundario": "+57 312 345 6789",
  "direccion": "Calle 123 #45-67",
  "municipio": "Bogotá",
  "departamento": "Cundinamarca"
}

Legal Representative

{
  "representante_nombre": "Carlos Gómez",
  "representante_telefono": "+57 310 123 4567",
  "representante_email": "cgomez@transportesrapidos.com"
}

Service Configuration

{
  "tipos_vehiculo": ["carro", "moto", "carro_carga"],
  "comision_admin_porcentaje": 15.0,
  "logo_url": "https://example.com/logos/empresa-123.png"
}

Performance Metrics

{
  "total_conductores": 45,
  "total_viajes_completados": 1250,
  "calificacion_promedio": 4.7
}

Vehicle Types

Companies can support multiple vehicle categories:

Motorcycle

motoStandard motorcycle transport

Car

carroPassenger vehicle service

Cargo Moto

moto_cargaMotorcycle delivery service

Cargo Van

carro_cargaVan/truck cargo service

Company Repository

Data access layer for company operations:

admin/domain/repositories/empresa_repository.dart

abstract class EmpresaRepository {
  /// Get all companies with optional filters
  Future<Result<List<EmpresaTransporte>>> getEmpresas({
    EmpresaEstado? estado,
    bool? verificada,
    int? page,
    int? limit,
  });

  /// Get company by ID
  Future<Result<EmpresaTransporte>> getEmpresaById(int id);

  /// Create new company
  Future<Result<EmpresaTransporte>> createEmpresa(
    EmpresaTransporte empresa,
  );

  /// Update company information
  Future<Result<EmpresaTransporte>> updateEmpresa(
    int id,
    Map<String, dynamic> updates,
  );

  /// Delete company (soft delete)
  Future<Result<void>> deleteEmpresa(int id);

  /// Get company statistics
  Future<Result<EmpresaStats>> getEmpresaStats();

  /// Verify company
  Future<Result<void>> verifyEmpresa(int id, int adminId);

  /// Get drivers by company
  Future<Result<List<dynamic>>> getDriversByEmpresa(int empresaId);
}

Company Provider

State management for company operations:

admin/presentation/providers/empresa_provider.dart

class EmpresaProvider with ChangeNotifier {
  final EmpresaRepository repository;
  
  List<EmpresaTransporte> _empresas = [];
  EmpresaStats? _stats;
  bool _isLoading = false;
  String? _errorMessage;
  EmpresaEstado? _currentFilter;

  Future<void> loadEmpresas({bool refresh = false}) async {
    _setLoading(true);
    
    final result = await repository.getEmpresas(
      estado: _currentFilter,
      page: 1,
      limit: 50,
    );

    result.fold(
      (failure) => _setError(failure.message),
      (empresas) {
        _empresas = empresas;
        _isLoading = false;
        notifyListeners();
      },
    );
  }

  Future<void> createEmpresa(EmpresaTransporte empresa) async {
    final result = await repository.createEmpresa(empresa);
    
    result.fold(
      (failure) => _setError(failure.message),
      (newEmpresa) {
        _empresas.add(newEmpresa);
        notifyListeners();
      },
    );
  }

  Future<void> updateEmpresa(int id, Map<String, dynamic> updates) async {
    final result = await repository.updateEmpresa(id, updates);
    
    result.fold(
      (failure) => _setError(failure.message),
      (updatedEmpresa) {
        final index = _empresas.indexWhere((e) => e.id == id);
        if (index != -1) {
          _empresas[index] = updatedEmpresa;
          notifyListeners();
        }
      },
    );
  }
}

Commission Configuration

Set platform commission rates per company:

Navigate to Company

Select a company from the list

Edit Commission

Tap “Edit” and locate the commission field

Enter Percentage

Set the commission percentage (e.g., 15.0 for 15%)

Save Changes

Confirm to apply the new commission rate

Default commission is 15%. This can be customized per company based on agreements.

Assigning Drivers to Companies

Drivers can be assigned to companies for proper organization:

// In User Management, when editing a conductor:
Future<bool> updateUser({
  required int userId,
  String? tipoUsuario,
  int? empresaId,  // Company ID to assign
  String? empresaNombre,
}) async {
  final result = await manageUserUseCase.updateUser(
    adminId: adminId,
    userId: userId,
    tipoUsuario: tipoUsuario,
    empresaId: empresaId,
  );

  return result.fold(
    (failure) => false,
    (success) {
      if (success && empresaId != null) {
        // Driver is now assigned to company
        notifyListeners();
      }
      return success;
    },
  );
}

Drivers must be assigned to a company to ensure proper commission tracking and payment distribution.

Company Verification

Verify company credentials before activation:

Future<Result<void>> verifyEmpresa(int empresaId, int adminId) async {
  // Verify:
  // - NIT is valid
  // - Legal representative documents
  // - Business registration
  // - Insurance policies
  
  final result = await repository.verifyEmpresa(empresaId, adminId);
  
  return result.fold(
    (failure) => Error(failure),
    (success) {
      // Update local state
      final index = _empresas.indexWhere((e) => e.id == empresaId);
      if (index != -1) {
        _empresas[index] = _empresas[index].copyWith(
          verificada: true,
          fechaVerificacion: DateTime.now(),
          verificadoPor: adminId,
        );
        notifyListeners();
      }
      return Success(success);
    },
  );
}

Platform Earnings by Company

Track commissions owed by each company:

admin/presentation/screens/platform_earnings_screen.dart

class PlatformEarningsScreen extends StatefulWidget {
  final int adminId;

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

// Displays:
// - Total trips per company
// - Total earnings per company
// - Platform commission earned
// - Outstanding payments

Earnings Calculation

// For each company trip:
final tripTotal = 50000; // COP
final commissionRate = empresa.comisionAdminPorcentaje; // 15%
final platformEarnings = tripTotal * (commissionRate / 100); // 7500 COP
final driverEarnings = tripTotal - platformEarnings; // 42500 COP

Company CopyWith Method

Immutable updates to company entities:

admin/domain/entities/empresa_transporte.dart

EmpresaTransporte copyWith({
  int? id,
  String? nombre,
  String? nit,
  String? razonSocial,
  String? email,
  String? telefono,
  String? telefonoSecundario,
  String? direccion,
  String? municipio,
  String? departamento,
  String? representanteNombre,
  String? representanteTelefono,
  String? representanteEmail,
  List<String>? tiposVehiculo,
  String? logoUrl,
  String? descripcion,
  EmpresaEstado? estado,
  bool? verificada,
  DateTime? fechaVerificacion,
  int? verificadoPor,
  int? totalConductores,
  int? totalViajesCompletados,
  double? calificacionPromedio,
  double? comisionAdminPorcentaje,
  DateTime? creadoEn,
  DateTime? actualizadoEn,
  int? creadoPor,
  String? notasAdmin,
}) {
  return EmpresaTransporte(
    id: id ?? this.id,
    nombre: nombre ?? this.nombre,
    nit: nit ?? this.nit,
    // ... all fields
  );
}

Company Filtering

Filter companies by various criteria:

By Status
By Verification
By Vehicle Type
By Performance

Filter by activo, inactivo, suspendido, pendiente, or eliminado

Show only verified (verificada = true) or unverified companies

Best Practices

Verify Before Activation

Always verify company credentials (NIT, legal representative, insurance) before approving.

Set Fair Commissions

Set commission rates based on service type, volume, and agreements. Standard is 15%.

Monitor Performance

Regularly review company metrics like completion rate, driver count, and customer ratings.

Track Payments

Use the Platform Earnings screen to monitor commission payments from companies.

Document Changes

Use the notes field to document important changes or agreements with companies.

Driver Management

Assign drivers to companies

User Management

Manage company user accounts

Pricing Configuration

Set pricing by vehicle type

​Overview

​Transport Company Entity

​Company States

​Estado Enum Implementation

​Company Statistics

Total Companies

Active Companies

Total Drivers

Verified Companies

Pending

Total Trips

​Company Information Fields

​Basic Information

​Contact Information

​Legal Representative

​Service Configuration

​Performance Metrics

​Vehicle Types

Motorcycle

Car

Cargo Moto

Cargo Van

​Company Repository

​Company Provider

​Commission Configuration

​Assigning Drivers to Companies

​Company Verification

​Platform Earnings by Company

​Earnings Calculation

​Company CopyWith Method

​Company Filtering

​Best Practices

​Related Features

Driver Management

User Management

Pricing Configuration

Overview

Transport Company Entity

Company States

Estado Enum Implementation

Company Statistics

Company Information Fields

Basic Information

Contact Information

Legal Representative

Service Configuration

Performance Metrics

Vehicle Types

Company Repository

Company Provider

Commission Configuration

Assigning Drivers to Companies

Company Verification

Platform Earnings by Company

Earnings Calculation

Company CopyWith Method

Company Filtering

Best Practices

Related Features