Adrian Flores Cortes d1f6a176f0 docs: Complete SIMCO documentation for MAI-009 and MAI-012 modules

- Add ENTITIES.md for MAI-012 (Combustible y Gastos) with 5 entities
- Add ENTITIES.md for MAI-009 (Facturacion Transporte) with 6 entities
- Update TASK-2026-01-25-DOCUMENTACION-MODULOS status to completed
- Document all fields, indices, ENUMs and helper methods

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-25 14:55:18 -06:00

12 KiB

Raw Permalink Blame History

ENTITIES.md - MAI-012 Combustible y Gastos

Modulo: MAI-012 | Version: 1.0.0 | Actualizado: 2026-01-25

Resumen

Metrica	Valor
Total Entidades	5
Schema BD	fuel
ENUMs	7
Estado	Implementado

1. CargaCombustible

Archivo: carga-combustible.entity.ts Tabla: fuel.cargas_combustible Descripcion: Registro de cargas de combustible realizadas por operadores.

Campos

Campo	Tipo	Null	Default	Descripcion
id	uuid	No	gen	Identificador unico
tenantId	uuid	No	-	Tenant (empresa)
unidadId	uuid	No	-	FK a unidad/vehiculo
viajeId	uuid	Si	-	FK a viaje (opcional)
operadorId	uuid	No	-	FK a operador
tipoCarga	enum	No	-	Tipo: VALE, TARJETA, EFECTIVO, FACTURA_DIRECTA
tipoCombustible	varchar(20)	No	-	DIESEL, GASOLINA_MAGNA, etc.
litros	decimal(10,3)	No	-	Cantidad en litros
precioLitro	decimal(10,4)	No	-	Precio por litro
total	decimal(12,2)	No	-	Monto total
odometroCarga	int	Si	-	Odometro al cargar
rendimientoCalculado	decimal(6,2)	Si	-	km/litro calculado
estacionId	uuid	Si	-	FK a estacion
estacionNombre	varchar(200)	Si	-	Nombre estacion
estacionDireccion	text	Si	-	Direccion estacion
latitud	decimal(10,7)	Si	-	Coordenada latitud
longitud	decimal(10,7)	Si	-	Coordenada longitud
numeroVale	varchar(50)	Si	-	Numero de vale
numeroFactura	varchar(50)	Si	-	Numero de factura
folioTicket	varchar(50)	Si	-	Folio del ticket
fechaCarga	timestamptz	No	-	Fecha/hora de carga
estado	enum	No	PENDIENTE	Estado: PENDIENTE, APROBADO, RECHAZADO, PAGADO
aprobadoPor	uuid	Si	-	Usuario que aprobo
aprobadoFecha	timestamptz	Si	-	Fecha de aprobacion
fotoTicketUrl	text	Si	-	URL foto ticket
createdAt	timestamptz	No	now()	Fecha creacion
createdById	uuid	No	-	Usuario creador

Indices

idx_carga_unidad (unidadId)
idx_carga_viaje (viajeId)
idx_carga_fecha (tenantId, fechaCarga)

ENUMs Asociados

enum TipoCargaCombustible {
  VALE = 'VALE',
  TARJETA = 'TARJETA',
  EFECTIVO = 'EFECTIVO',
  FACTURA_DIRECTA = 'FACTURA_DIRECTA',
}

enum TipoCombustible {
  DIESEL = 'DIESEL',
  GASOLINA_MAGNA = 'GASOLINA_MAGNA',
  GASOLINA_PREMIUM = 'GASOLINA_PREMIUM',
  GAS_LP = 'GAS_LP',
  GAS_NATURAL = 'GAS_NATURAL',
}

enum EstadoGasto {
  PENDIENTE = 'PENDIENTE',
  APROBADO = 'APROBADO',
  RECHAZADO = 'RECHAZADO',
  PAGADO = 'PAGADO',
}

Helpers

costoPorLitro: Calcula costo promedio por litro

2. CrucePeaje

Archivo: cruce-peaje.entity.ts Tabla: fuel.cruces_peaje Descripcion: Registro de cruces de casetas de peaje.

Campos

Campo	Tipo	Null	Default	Descripcion
id	uuid	No	gen	Identificador unico
tenantId	uuid	No	-	Tenant (empresa)
unidadId	uuid	No	-	FK a unidad
viajeId	uuid	Si	-	FK a viaje
operadorId	uuid	Si	-	FK a operador
casetaNombre	varchar(200)	No	-	Nombre de la caseta
casetaCodigo	varchar(50)	Si	-	Codigo SCT de caseta
carretera	varchar(200)	Si	-	Carretera/autopista
monto	decimal(10,2)	No	-	Monto del peaje
tipoPago	varchar(20)	Si	-	EFECTIVO, TAG, PREPAGO
tagNumero	varchar(50)	Si	-	Numero de TAG IAVE/Televia
latitud	decimal(10,7)	Si	-	Coordenada latitud
longitud	decimal(10,7)	Si	-	Coordenada longitud
fechaCruce	timestamptz	No	-	Fecha/hora del cruce
numeroTicket	varchar(50)	Si	-	Numero ticket peaje
fotoTicketUrl	text	Si	-	URL foto comprobante
estado	enum	No	APROBADO	Estado del gasto
createdAt	timestamptz	No	now()	Fecha creacion

Indices

idx_peaje_unidad (unidadId)
idx_peaje_viaje (viajeId)
idx_peaje_fecha (tenantId, fechaCruce)

ENUMs Asociados

enum TipoPagoPeaje {
  EFECTIVO = 'EFECTIVO',
  TAG = 'TAG',
  PREPAGO = 'PREPAGO',
}

3. GastoViaje

Archivo: gasto-viaje.entity.ts Tabla: fuel.gastos_viaje Descripcion: Gastos varios incurridos durante un viaje.

Campos

Campo	Tipo	Null	Default	Descripcion
id	uuid	No	gen	Identificador unico
tenantId	uuid	No	-	Tenant (empresa)
viajeId	uuid	No	-	FK a viaje
operadorId	uuid	No	-	FK a operador
tipoGasto	enum	No	-	Categoria del gasto
descripcion	varchar(500)	No	-	Descripcion del gasto
monto	decimal(12,2)	No	-	Monto del gasto
tieneFactura	boolean	No	false	Tiene factura fiscal
numeroFactura	varchar(50)	Si	-	Numero de factura
numeroTicket	varchar(50)	Si	-	Numero de ticket
fotoComprobanteUrl	text	Si	-	URL foto comprobante
lugar	varchar(200)	Si	-	Lugar del gasto
latitud	decimal(10,7)	Si	-	Coordenada latitud
longitud	decimal(10,7)	Si	-	Coordenada longitud
fechaGasto	timestamptz	No	-	Fecha/hora del gasto
estado	enum	No	PENDIENTE	Estado: PENDIENTE, APROBADO, RECHAZADO, PAGADO
aprobadoPor	uuid	Si	-	Usuario que aprobo
aprobadoFecha	timestamptz	Si	-	Fecha de aprobacion
motivoRechazo	text	Si	-	Motivo si rechazado
createdAt	timestamptz	No	now()	Fecha creacion
createdById	uuid	No	-	Usuario creador

Indices

idx_gasto_viaje (viajeId)
idx_gasto_operador (operadorId)
idx_gasto_estado (tenantId, estado)

ENUMs Asociados

enum TipoGasto {
  COMBUSTIBLE = 'COMBUSTIBLE',
  PEAJE = 'PEAJE',
  VIATICO = 'VIATICO',
  HOSPEDAJE = 'HOSPEDAJE',
  ALIMENTOS = 'ALIMENTOS',
  ESTACIONAMIENTO = 'ESTACIONAMIENTO',
  MULTA = 'MULTA',
  MANIOBRA = 'MANIOBRA',
  REPARACION_MENOR = 'REPARACION_MENOR',
  OTRO = 'OTRO',
}

Helpers

esDeducible: true si tiene factura
requiereAprobacion: true si estado PENDIENTE

4. AnticipoViatico

Archivo: anticipo-viatico.entity.ts Tabla: fuel.anticipos_viaticos Descripcion: Anticipos de dinero entregados a operadores para viajes.

Campos

Campo	Tipo	Null	Default	Descripcion
id	uuid	No	gen	Identificador unico
tenantId	uuid	No	-	Tenant (empresa)
viajeId	uuid	No	-	FK a viaje
operadorId	uuid	No	-	FK a operador
montoSolicitado	decimal(12,2)	No	-	Monto solicitado
montoAprobado	decimal(12,2)	Si	-	Monto aprobado
montoComprobado	decimal(12,2)	No	0	Monto comprobado
montoReintegro	decimal(12,2)	No	0	Monto a reintegrar
combustibleEstimado	decimal(12,2)	Si	-	Estimado combustible
peajesEstimado	decimal(12,2)	Si	-	Estimado peajes
viaticosEstimado	decimal(12,2)	Si	-	Estimado viaticos
estado	varchar(20)	No	SOLICITADO	Estado del anticipo
fechaSolicitud	timestamptz	No	now()	Fecha solicitud
fechaAprobacion	timestamptz	Si	-	Fecha aprobacion
fechaEntrega	timestamptz	Si	-	Fecha entrega efectivo
fechaLiquidacion	timestamptz	Si	-	Fecha liquidacion
aprobadoPor	uuid	Si	-	Usuario que aprobo
entregadoPor	uuid	Si	-	Usuario que entrego
liquidadoPor	uuid	Si	-	Usuario que liquido
observaciones	text	Si	-	Observaciones
createdAt	timestamptz	No	now()	Fecha creacion
createdById	uuid	No	-	Usuario creador

Indices

idx_anticipo_viaje (viajeId)
idx_anticipo_operador (operadorId)
idx_anticipo_estado (tenantId, estado)

ENUMs Asociados

enum EstadoAnticipo {
  SOLICITADO = 'SOLICITADO',
  APROBADO = 'APROBADO',
  ENTREGADO = 'ENTREGADO',
  COMPROBANDO = 'COMPROBANDO',
  LIQUIDADO = 'LIQUIDADO',
  RECHAZADO = 'RECHAZADO',
}

Helpers

saldoPendiente: montoAprobado - montoComprobado
porcentajeComprobado: % del monto comprobado
requiereReintegro: true si montoReintegro > 0

5. ControlRendimiento

Archivo: control-rendimiento.entity.ts Tabla: fuel.control_rendimiento Descripcion: Control de rendimiento de combustible por unidad/periodo.

Campos

Campo	Tipo	Null	Default	Descripcion
id	uuid	No	gen	Identificador unico
tenantId	uuid	No	-	Tenant (empresa)
unidadId	uuid	No	-	FK a unidad
fechaInicio	date	No	-	Inicio del periodo
fechaFin	date	No	-	Fin del periodo
kmRecorridos	int	No	-	Kilometros recorridos
litrosConsumidos	decimal(12,3)	No	-	Litros consumidos
rendimientoReal	decimal(6,2)	No	-	km/litro real
rendimientoEsperado	decimal(6,2)	Si	-	km/litro esperado
variacionPorcentaje	decimal(5,2)	Si	-	Variacion % vs esperado
costoTotalCombustible	decimal(15,2)	Si	-	Costo total periodo
costoPorKm	decimal(8,4)	Si	-	Costo por km
tieneAnomalia	boolean	No	false	Tiene anomalia detectada
tipoAnomalia	varchar(50)	Si	-	Tipo de anomalia
descripcionAnomalia	text	Si	-	Descripcion anomalia
createdAt	timestamptz	No	now()	Fecha creacion

Indices

idx_rendimiento_unidad (unidadId)
idx_rendimiento_fecha (tenantId, fechaInicio)

ENUMs Asociados

enum TipoAnomaliaRendimiento {
  BAJO_RENDIMIENTO = 'BAJO_RENDIMIENTO',
  CONSUMO_EXCESIVO = 'CONSUMO_EXCESIVO',
  POSIBLE_ROBO = 'POSIBLE_ROBO',
  FALLA_MECANICA = 'FALLA_MECANICA',
  RUTA_INEFICIENTE = 'RUTA_INEFICIENTE',
}

Helpers

eficiencia: OPTIMO (>=95%), ACEPTABLE (>=85%), BAJO (>=75%), CRITICO (<75%)
diasPeriodo: Calcula dias del periodo

Diagrama de Relaciones

                    +------------------+
                    |     Viaje        |
                    +--------+---------+
                             |
         +-------------------+-------------------+
         |                   |                   |
         v                   v                   v
+----------------+  +----------------+  +-----------------+
| CargaCombustible| |   CrucePeaje   |  |   GastoViaje    |
+----------------+  +----------------+  +-----------------+
         |                                       |
         v                                       v
+----------------+                      +-----------------+
| ControlRendim. |                      | AnticipoViatico |
+----------------+                      +-----------------+
         |
         v
+----------------+
|    Unidad      |
+----------------+

Casos de Uso

CU-001: Registrar Carga de Combustible

Operador reporta carga desde app movil
Sistema captura ubicacion GPS
Operador toma foto del ticket
Sistema calcula rendimiento vs carga anterior
Si anomalia: genera alerta automatica

CU-002: Control de Rendimiento

Sistema genera reporte periodico (semanal/mensual)
Calcula rendimiento real vs esperado
Detecta anomalias (consumo excesivo, posible robo)
Notifica a administracion si hay alertas

CU-003: Liquidacion de Anticipo

Operador regresa de viaje
Presenta comprobantes (combustible, peajes, gastos)
Sistema coteja vs anticipo entregado
Calcula reintegro o adicional a pagar

MAI-012 Combustible y Gastos - ERP Transportistas v1.0.0

12 KiB Raw Permalink Blame History

ENTITIES.md - MAI-012 Combustible y Gastos

Resumen

1. CargaCombustible

Campos

Indices

ENUMs Asociados

Helpers

2. CrucePeaje

Campos

Indices

ENUMs Asociados

3. GastoViaje

Campos

Indices

ENUMs Asociados

Helpers

4. AnticipoViatico

Campos

Indices

ENUMs Asociados

Helpers

5. ControlRendimiento

Campos

Indices

ENUMs Asociados

Helpers

Diagrama de Relaciones

Casos de Uso

CU-001: Registrar Carga de Combustible

CU-002: Control de Rendimiento

CU-003: Liquidacion de Anticipo

12 KiB

Raw Permalink Blame History