erp-transportistas-v2/docs/_definitions/SERVICES-CATALOG.md

# SERVICES-CATALOG.md - ERP Transportistas

**Version:** 1.1.0
**Fecha:** 2026-01-27
**Total Services:** ~80 (50 heredados + 30 propios)

> **SSOT (Single Source of Truth):** Este archivo es la fuente canonica de servicios.
> **Sincronizado con:** `orchestration/inventarios/BACKEND_INVENTORY.yml`
> **Ultima sincronizacion:** 2026-01-27

---

## Resumen

| Categoria | Services | Estado |
|-----------|----------|--------|
| Heredados erp-core | ~50 | 100% disponibles |
| Propios transporte | ~30 | 40% implementados |

---

## Services Heredados (erp-core)

### Auth & Users
- AuthService
- UsersService
- RolesService
- PermissionsService
- SessionsService

### Tenancy
- TenantsService
- CompaniesService
- BranchesService

### Core
- CatalogsService
- SettingsService
- AuditService
- NotificationsService

### Financial
- FinancialService
- InvoicesService
- PaymentsService
- AccountingService

### Partners
- PartnersService
- CustomersService
- SuppliersService

### AI/Intelligence
- AIService
- WhatsAppService
- MCPService

---

## Services Propios - Transporte

### OrdenesTransporteService (MAI-003)
- **Path:** `backend/src/modules/ordenes-transporte/services/`
- **Estado:** 40% implementado
- **Metodos:**
  - `create(dto)` - Crear OT
  - `findAll(filters)` - Listar OTs
  - `findById(id)` - Obtener OT
  - `update(id, dto)` - Actualizar OT
  - `delete(id)` - Eliminar OT
  - `changeStatus(id, status)` - Cambiar estado
  - `assignToViaje(otId, viajeId)` - Asignar a viaje

### ViajesService (MAI-004, MAI-005)
- **Path:** `backend/src/modules/viajes/services/`
- **Estado:** Pendiente
- **Metodos:**
  - `create(dto)` - Crear viaje
  - `planificar(viajeId, recursos)` - Planificar recursos
  - `despachar(viajeId, checklist)` - Liberar viaje
  - `cerrar(viajeId, pod)` - Cerrar con POD

### TrackingService (MAI-006)
- **Path:** `backend/src/modules/tracking/services/`
- **Estado:** 20% implementado
- **Metodos:**
  - `registrarEvento(dto)` - Registrar posicion GPS
  - `getUltimaPosicion(unidadId)` - Ultima ubicacion
  - `getHistorial(viajeId)` - Historial de eventos
  - `calcularETA(viajeId)` - ETA dinamico
  - `verificarGeocercas(lat, lng)` - Check geocercas
  - `generarAlerta(tipo, datos)` - Crear alerta

### FlotaService (MAI-011)
- **Path:** `backend/src/modules/gestion-flota/services/`
- **Estado:** 40% implementado
- **Metodos:**
  - `getUnidades(filters)` - Listar unidades
  - `getOperadores(filters)` - Listar operadores
  - `getDisponibilidad(fecha)` - Recursos disponibles
  - `asignarOperador(unidadId, operadorId)` - Asignar
  - `verificarDocumentos(recursoId)` - Validar vigencia

### CombustibleService (MAI-012)
- **Path:** `backend/src/modules/combustible-gastos/services/`
- **Estado:** 50% implementado
- **Metodos:**
  - `registrarCarga(dto)` - Registrar carga combustible
  - `registrarPeaje(dto)` - Registrar cruce peaje
  - `registrarGasto(dto)` - Registrar gasto
  - `generarAnticipo(operadorId, monto)` - Crear anticipo
  - `calcularRendimiento(unidadId, periodo)` - km/litro
  - `detectarAnomalias(viajeId)` - Alertas fraude

### FacturacionTransporteService (MAI-009)
- **Path:** `backend/src/modules/facturacion-transporte/services/`
- **Estado:** 30% implementado
- **Metodos:**
  - `calcularTarifa(lane, peso, volumen)` - Calcular precio
  - `aplicarRecargos(facturaId, recargos)` - Agregar recargos
  - `generarFactura(viajeId)` - Crear factura
  - `calcularFuelSurcharge(fecha)` - Recargo combustible

### CartaPorteService (MAE-016)
- **Path:** `backend/src/modules/carta-porte/services/`
- **Estado:** Pendiente
- **Metodos:**
  - `generarComplemento(viajeId)` - Crear XML
  - `validarDatos(dto)` - Validar requeridos
  - `timbrar(cartaPorteId)` - Enviar a PAC
  - `generarPDF(cartaPorteId)` - PDF para impresion
  - `cancelar(cartaPorteId, motivo)` - Cancelar CFDI

### MantenimientoService (MAI-013)
- **Path:** `backend/src/modules/mantenimiento/services/`
- **Estado:** Pendiente
- **Metodos:**
  - `crearOrdenTrabajo(dto)` - Crear OT manto
  - `programarPreventivo(unidadId)` - Programar
  - `registrarRefaccion(otId, refaccion)` - Agregar parte
  - `getProximosMantenimientos()` - Alertas vencimiento

### CarriersService (MAI-014)
- **Path:** `backend/src/modules/carriers/services/`
- **Estado:** Pendiente
- **Metodos:**
  - `registrarCarrier(dto)` - Alta tercero
  - `validarDocumentos(carrierId)` - Verificar vigencia
  - `calcularScorecard(carrierId)` - Evaluar desempeno
  - `asignarViaje(carrierId, viajeId)` - Subcontratar

---

## Integraciones Externas

### GPSIntegrationService
- **Estado:** Planificado (GAP-001 identificado)
- **Proveedores:**
  - Traccar (Recomendado - Open Source)
  - Wialon
  - Samsara
  - Geotab
  - Manual (Fallback)
- **Metodos:**
  - `conectar(proveedor, credentials)`
  - `getPosicion(deviceId)`
  - `getEventos(desde, hasta)`
  - `subscribeToUpdates(deviceId, callback)`
  - `getDevices()`
- **Fuente:** Copiar de erp-mecanicas-diesel/backend/src/modules/gps/

### GeofenceService (NUEVO)
- **Estado:** Planificado (GAP-006 identificado)
- **Metodos:**
  - `create(dto)` - Crear geocerca circular o poligonal
  - `findAll(filters)` - Listar geocercas
  - `checkPointAgainstGeofences(lat, lng)` - Verificar punto
  - `findGeofencesContainingPoint(lat, lng)` - Busqueda inversa
  - `getEvents(filters)` - Consultar eventos entrada/salida
- **Fuente:** Copiar de erp-mecanicas-diesel/backend/src/modules/gps/services/geofence.service.ts

### DispatchService (NUEVO)
- **Estado:** Planificado (GAP-002 identificado)
- **Metodos:**
  - `suggestBestAssignment(viajeId, ubicacion)` - Sugerir mejor unidad
  - `assignViaje(viajeId, unidadId, operadorId)` - Asignar viaje
  - `reassignViaje(viajeId, newUnidadId, reason)` - Reasignar
  - `getAvailableUnits(filters)` - Unidades disponibles
  - `getDispatchLogs(viajeId)` - Auditoria de asignaciones
- **Fuente:** Copiar de erp-mecanicas-diesel/backend/src/modules/dispatch/services/dispatch.service.ts

### PACIntegrationService
- **Estado:** Planificado
- **Proveedores:**
  - Finkok
  - Facturama
  - SW Sapien
- **Metodos:**
  - `timbrar(xml)`
  - `cancelar(uuid, motivo)`
  - `getStatus(uuid)`

### MapasService
- **Estado:** Planificado
- **Proveedores:**
  - Google Maps
  - HERE
  - Mapbox
- **Metodos:**
  - `geocodificar(direccion)`
  - `calcularRuta(origen, destino)`
  - `getDistanciaTiempo(puntos)`

---

## Referencias

- Backend: `backend/src/modules/`
- Entities: `ENTITIES-CATALOG.md`
- API: `_quick/QUICK-API.yml`

---

## Gaps Identificados (TASK-007)

| Gap | Service | Prioridad | Fuente |
|-----|---------|-----------|--------|
| GAP-001 | GPSIntegrationService | ALTA | erp-mecanicas-diesel |
| GAP-002 | DispatchService | ALTA | erp-mecanicas-diesel |
| GAP-006 | GeofenceService | MEDIA | erp-mecanicas-diesel |

---

*Ultima actualizacion: 2026-01-27 | TASK-007.1 Sincronizacion*