rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d1f6a176f0
erp-transportistas-v2/docs/02-definicion-modulos/MAI-012-combustible-gastos/ENTITIES.md
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

365 lines
12 KiB
Markdown
Raw 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
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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
1. Operador reporta carga desde app movil
2. Sistema captura ubicacion GPS
3. Operador toma foto del ticket
4. Sistema calcula rendimiento vs carga anterior
5. Si anomalia: genera alerta automatica
### CU-002: Control de Rendimiento
1. Sistema genera reporte periodico (semanal/mensual)
2. Calcula rendimiento real vs esperado
3. Detecta anomalias (consumo excesivo, posible robo)
4. Notifica a administracion si hay alertas
### CU-003: Liquidacion de Anticipo
1. Operador regresa de viaje
2. Presenta comprobantes (combustible, peajes, gastos)
3. Sistema coteja vs anticipo entregado
4. Calcula reintegro o adicional a pagar
---
*MAI-012 Combustible y Gastos - ERP Transportistas v1.0.0*
Reference in New Issue View Git Blame Copy Permalink