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>
This commit is contained in:
Adrian Flores Cortes
parent
e020576fcc
commit
d1f6a176f0
@ -0,0 +1,426 @@
|
||||
# ENTITIES.md - MAI-009 Facturacion Transporte
|
||||
|
||||
**Modulo:** MAI-009 | **Version:** 1.0.0 | **Actualizado:** 2026-01-25
|
||||
|
||||
---
|
||||
|
||||
## Resumen
|
||||
|
||||
| Metrica | Valor |
|
||||
|---------|-------|
|
||||
| Total Entidades | 6 |
|
||||
| Schema BD | billing |
|
||||
| ENUMs | 4 |
|
||||
| Estado | Implementado |
|
||||
|
||||
---
|
||||
|
||||
## 1. Lane
|
||||
|
||||
**Archivo:** `lane.entity.ts`
|
||||
**Tabla:** `billing.lanes`
|
||||
**Descripcion:** Rutas/lanes de transporte (origen-destino) para cotizacion.
|
||||
|
||||
### Campos
|
||||
|
||||
| Campo | Tipo | Null | Default | Descripcion |
|
||||
|-------|------|------|---------|-------------|
|
||||
| id | uuid | No | gen | Identificador unico |
|
||||
| tenantId | uuid | No | - | Tenant (empresa) |
|
||||
| codigo | varchar(50) | No | - | Codigo unico del lane |
|
||||
| nombre | varchar(200) | No | - | Nombre descriptivo |
|
||||
| origenCiudad | varchar(100) | No | - | Ciudad de origen |
|
||||
| origenEstado | varchar(100) | No | - | Estado de origen |
|
||||
| origenCodigoPostal | varchar(10) | Si | - | CP origen |
|
||||
| destinoCiudad | varchar(100) | No | - | Ciudad de destino |
|
||||
| destinoEstado | varchar(100) | No | - | Estado de destino |
|
||||
| destinoCodigoPostal | varchar(10) | Si | - | CP destino |
|
||||
| distanciaKm | decimal(10,2) | Si | - | Distancia en km |
|
||||
| tiempoEstimadoHoras | decimal(6,2) | Si | - | Tiempo estimado hrs |
|
||||
| activo | boolean | No | true | Lane activo |
|
||||
| createdAt | timestamptz | No | now() | Fecha creacion |
|
||||
| createdById | uuid | No | - | Usuario creador |
|
||||
|
||||
### Indices
|
||||
|
||||
- `idx_lane_tenant` (tenantId)
|
||||
- `idx_lane_codigo` (tenantId, codigo) UNIQUE
|
||||
|
||||
### Helpers
|
||||
|
||||
- `descripcionCorta`: "Ciudad Origen -> Ciudad Destino"
|
||||
- `descripcionCompleta`: "Ciudad, Estado -> Ciudad, Estado"
|
||||
|
||||
---
|
||||
|
||||
## 2. Tarifa
|
||||
|
||||
**Archivo:** `tarifa.entity.ts`
|
||||
**Tabla:** `billing.tarifas`
|
||||
**Descripcion:** Tarifas de transporte por lane, cliente, tipo de servicio.
|
||||
|
||||
### Campos
|
||||
|
||||
| Campo | Tipo | Null | Default | Descripcion |
|
||||
|-------|------|------|---------|-------------|
|
||||
| id | uuid | No | gen | Identificador unico |
|
||||
| tenantId | uuid | No | - | Tenant (empresa) |
|
||||
| codigo | varchar(50) | No | - | Codigo de tarifa |
|
||||
| nombre | varchar(200) | No | - | Nombre descriptivo |
|
||||
| descripcion | text | Si | - | Descripcion detallada |
|
||||
| clienteId | uuid | Si | - | FK a cliente (tarifa especifica) |
|
||||
| laneId | uuid | Si | - | FK a lane |
|
||||
| modalidadServicio | varchar(50) | Si | - | FTL, LTL, etc. |
|
||||
| tipoEquipo | varchar(50) | Si | - | Caja seca, refrigerado, etc. |
|
||||
| tipoTarifa | enum | No | - | Tipo de calculo |
|
||||
| tarifaBase | decimal(15,2) | No | - | Monto base |
|
||||
| tarifaKm | decimal(10,4) | Si | - | Tarifa por km |
|
||||
| tarifaTonelada | decimal(10,4) | Si | - | Tarifa por tonelada |
|
||||
| tarifaM3 | decimal(10,4) | Si | - | Tarifa por m3 |
|
||||
| tarifaPallet | decimal(10,4) | Si | - | Tarifa por pallet |
|
||||
| tarifaHora | decimal(10,4) | Si | - | Tarifa por hora |
|
||||
| minimoFacturar | decimal(15,2) | Si | - | Minimo a facturar |
|
||||
| pesoMinimoKg | decimal(10,2) | Si | - | Peso minimo kg |
|
||||
| moneda | varchar(3) | No | MXN | Moneda (MXN, USD) |
|
||||
| fechaInicio | date | No | - | Inicio vigencia |
|
||||
| fechaFin | date | Si | - | Fin vigencia |
|
||||
| activa | boolean | No | true | Tarifa activa |
|
||||
| createdAt | timestamptz | No | now() | Fecha creacion |
|
||||
| createdById | uuid | No | - | Usuario creador |
|
||||
| updatedAt | timestamptz | No | now() | Fecha actualizacion |
|
||||
|
||||
### Relaciones
|
||||
|
||||
| Relacion | Tipo | Target | Campo FK |
|
||||
|----------|------|--------|----------|
|
||||
| lane | ManyToOne | Lane | laneId |
|
||||
|
||||
### Indices
|
||||
|
||||
- `idx_tarifa_tenant` (tenantId)
|
||||
- `idx_tarifa_cliente` (clienteId)
|
||||
- `idx_tarifa_lane` (laneId)
|
||||
- `idx_tarifa_activa` (tenantId, activa, fechaInicio)
|
||||
|
||||
### ENUMs Asociados
|
||||
|
||||
```typescript
|
||||
enum TipoTarifa {
|
||||
POR_VIAJE = 'POR_VIAJE', // Monto fijo por viaje
|
||||
POR_KM = 'POR_KM', // Base + km recorridos
|
||||
POR_TONELADA = 'POR_TONELADA', // Base + toneladas
|
||||
POR_M3 = 'POR_M3', // Base + metros cubicos
|
||||
POR_PALLET = 'POR_PALLET', // Base + pallets
|
||||
POR_HORA = 'POR_HORA', // Base + horas
|
||||
MIXTA = 'MIXTA', // Combinacion de criterios
|
||||
}
|
||||
```
|
||||
|
||||
### Helpers
|
||||
|
||||
- `vigente`: true si activa y dentro de fechas
|
||||
- `esEspecifica`: true si tiene clienteId
|
||||
- `calcularMonto(params)`: Calcula monto segun tipoTarifa
|
||||
|
||||
---
|
||||
|
||||
## 3. RecargoCatalogo
|
||||
|
||||
**Archivo:** `recargo-catalogo.entity.ts`
|
||||
**Tabla:** `billing.recargos_catalogo`
|
||||
**Descripcion:** Catalogo de recargos aplicables (fuel surcharge, detention, etc.).
|
||||
|
||||
### Campos
|
||||
|
||||
| Campo | Tipo | Null | Default | Descripcion |
|
||||
|-------|------|------|---------|-------------|
|
||||
| id | uuid | No | gen | Identificador unico |
|
||||
| tenantId | uuid | No | - | Tenant (empresa) |
|
||||
| codigo | varchar(50) | No | - | Codigo unico |
|
||||
| nombre | varchar(200) | No | - | Nombre del recargo |
|
||||
| tipo | enum | No | - | Tipo de recargo |
|
||||
| descripcion | text | Si | - | Descripcion |
|
||||
| esPorcentaje | boolean | No | false | Es porcentaje o monto fijo |
|
||||
| monto | decimal(15,4) | No | - | Monto o porcentaje |
|
||||
| moneda | varchar(3) | No | MXN | Moneda |
|
||||
| aplicaAutomatico | boolean | No | false | Se aplica automaticamente |
|
||||
| condicionAplicacion | text | Si | - | Condicion para aplicar |
|
||||
| activo | boolean | No | true | Recargo activo |
|
||||
| createdAt | timestamptz | No | now() | Fecha creacion |
|
||||
| createdById | uuid | No | - | Usuario creador |
|
||||
|
||||
### Indices
|
||||
|
||||
- `idx_recargo_tenant` (tenantId)
|
||||
- `idx_recargo_codigo` (tenantId, codigo) UNIQUE
|
||||
|
||||
### ENUMs Asociados
|
||||
|
||||
```typescript
|
||||
enum TipoRecargo {
|
||||
FUEL_SURCHARGE = 'FUEL_SURCHARGE', // Recargo combustible
|
||||
DETENTION = 'DETENTION', // Tiempo espera carga/descarga
|
||||
MANIOBRAS = 'MANIOBRAS', // Maniobras especiales
|
||||
CUSTODIA = 'CUSTODIA', // Escolta/custodia
|
||||
ESCOLTA = 'ESCOLTA', // Escolta armada
|
||||
PERNOCTA = 'PERNOCTA', // Pernocta de unidad
|
||||
ESTADIAS = 'ESTADIAS', // Dias extra
|
||||
FALSO_FLETE = 'FALSO_FLETE', // Viaje cancelado
|
||||
SEGURO_ADICIONAL = 'SEGURO_ADICIONAL', // Seguro extra
|
||||
OTRO = 'OTRO', // Otros
|
||||
}
|
||||
```
|
||||
|
||||
### Helpers
|
||||
|
||||
- `calcularRecargo(base)`: Calcula monto segun esPorcentaje
|
||||
- `descripcionMonto`: "15%" o "$500.00 MXN"
|
||||
|
||||
---
|
||||
|
||||
## 4. FacturaTransporte
|
||||
|
||||
**Archivo:** `factura-transporte.entity.ts`
|
||||
**Tabla:** `billing.facturas_transporte`
|
||||
**Descripcion:** Facturas de servicios de transporte (CFDI).
|
||||
|
||||
### Campos
|
||||
|
||||
| Campo | Tipo | Null | Default | Descripcion |
|
||||
|-------|------|------|---------|-------------|
|
||||
| id | uuid | No | gen | Identificador unico |
|
||||
| tenantId | uuid | No | - | Tenant (empresa) |
|
||||
| serie | varchar(10) | Si | - | Serie de factura |
|
||||
| folio | varchar(20) | No | - | Folio de factura |
|
||||
| uuidCfdi | uuid | Si | - | UUID del CFDI timbrado |
|
||||
| clienteId | uuid | No | - | FK a cliente |
|
||||
| clienteRfc | varchar(13) | No | - | RFC del cliente |
|
||||
| clienteRazonSocial | varchar(200) | No | - | Razon social |
|
||||
| clienteUsoCfdi | varchar(10) | Si | - | Uso CFDI SAT |
|
||||
| fechaEmision | timestamptz | No | - | Fecha/hora emision |
|
||||
| fechaVencimiento | date | Si | - | Fecha vencimiento |
|
||||
| subtotal | decimal(15,2) | No | - | Subtotal |
|
||||
| descuento | decimal(15,2) | No | 0 | Descuento |
|
||||
| iva | decimal(15,2) | No | 0 | IVA |
|
||||
| retencionIva | decimal(15,2) | No | 0 | Retencion IVA |
|
||||
| retencionIsr | decimal(15,2) | No | 0 | Retencion ISR |
|
||||
| total | decimal(15,2) | No | - | Total factura |
|
||||
| moneda | varchar(3) | No | MXN | Moneda |
|
||||
| tipoCambio | decimal(10,4) | No | 1 | Tipo de cambio |
|
||||
| formaPago | varchar(10) | Si | - | Forma pago SAT |
|
||||
| metodoPago | varchar(10) | Si | - | Metodo pago SAT |
|
||||
| condicionesPago | varchar(200) | Si | - | Condiciones |
|
||||
| viajeIds | uuid[] | Si | - | IDs de viajes incluidos |
|
||||
| otIds | uuid[] | Si | - | IDs de OTs incluidas |
|
||||
| xmlCfdi | text | Si | - | XML del CFDI |
|
||||
| pdfUrl | text | Si | - | URL del PDF |
|
||||
| estado | enum | No | BORRADOR | Estado de factura |
|
||||
| montoPagado | decimal(15,2) | No | 0 | Monto pagado |
|
||||
| fechaPago | timestamptz | Si | - | Fecha de pago |
|
||||
| fechaCancelacion | timestamptz | Si | - | Fecha cancelacion |
|
||||
| motivoCancelacion | text | Si | - | Motivo cancelacion |
|
||||
| createdAt | timestamptz | No | now() | Fecha creacion |
|
||||
| createdById | uuid | No | - | Usuario creador |
|
||||
| updatedAt | timestamptz | No | now() | Fecha actualizacion |
|
||||
|
||||
### Relaciones
|
||||
|
||||
| Relacion | Tipo | Target | Campo FK |
|
||||
|----------|------|--------|----------|
|
||||
| lineas | OneToMany | LineaFactura | facturaId |
|
||||
|
||||
### Indices
|
||||
|
||||
- `idx_factura_tenant` (tenantId)
|
||||
- `idx_factura_cliente` (clienteId)
|
||||
- `idx_factura_estado` (tenantId, estado)
|
||||
- `idx_factura_fecha` (fechaEmision)
|
||||
- `idx_factura_folio` (tenantId, serie, folio) UNIQUE
|
||||
|
||||
### ENUMs Asociados
|
||||
|
||||
```typescript
|
||||
enum EstadoFactura {
|
||||
BORRADOR = 'BORRADOR', // En edicion
|
||||
EMITIDA = 'EMITIDA', // Timbrada
|
||||
ENVIADA = 'ENVIADA', // Enviada al cliente
|
||||
PAGADA = 'PAGADA', // Pagada completamente
|
||||
PARCIAL = 'PARCIAL', // Pago parcial
|
||||
VENCIDA = 'VENCIDA', // Vencida sin pago
|
||||
CANCELADA = 'CANCELADA', // Cancelada SAT
|
||||
}
|
||||
```
|
||||
|
||||
### Helpers
|
||||
|
||||
- `saldoPendiente`: total - montoPagado
|
||||
- `estaPagada`: true si montoPagado >= total
|
||||
- `estaVencida`: true si paso fechaVencimiento
|
||||
- `diasVencida`: Dias desde vencimiento
|
||||
- `folioCompleto`: "SERIE-FOLIO"
|
||||
|
||||
---
|
||||
|
||||
## 5. LineaFactura
|
||||
|
||||
**Archivo:** `linea-factura.entity.ts`
|
||||
**Tabla:** `billing.lineas_factura`
|
||||
**Descripcion:** Lineas/conceptos de una factura.
|
||||
|
||||
### Campos
|
||||
|
||||
| Campo | Tipo | Null | Default | Descripcion |
|
||||
|-------|------|------|---------|-------------|
|
||||
| id | uuid | No | gen | Identificador unico |
|
||||
| tenantId | uuid | No | - | Tenant (empresa) |
|
||||
| facturaId | uuid | No | - | FK a factura |
|
||||
| linea | int | No | - | Numero de linea |
|
||||
| descripcion | text | No | - | Descripcion concepto |
|
||||
| claveProductoSat | varchar(10) | Si | - | Clave prod/serv SAT |
|
||||
| unidadSat | varchar(10) | Si | - | Clave unidad SAT |
|
||||
| cantidad | decimal(12,4) | No | - | Cantidad |
|
||||
| precioUnitario | decimal(15,4) | No | - | Precio unitario |
|
||||
| descuento | decimal(15,2) | No | 0 | Descuento |
|
||||
| importe | decimal(15,2) | No | - | Importe (cant * PU) |
|
||||
| ivaTasa | decimal(5,2) | No | 16 | Tasa IVA % |
|
||||
| ivaMonto | decimal(15,2) | Si | - | Monto IVA |
|
||||
| viajeId | uuid | Si | - | FK a viaje (referencia) |
|
||||
| otId | uuid | Si | - | FK a OT (referencia) |
|
||||
| recargoId | uuid | Si | - | FK a recargo aplicado |
|
||||
|
||||
### Relaciones
|
||||
|
||||
| Relacion | Tipo | Target | Campo FK |
|
||||
|----------|------|--------|----------|
|
||||
| factura | ManyToOne | FacturaTransporte | facturaId |
|
||||
| recargo | ManyToOne | RecargoCatalogo | recargoId |
|
||||
|
||||
### Indices
|
||||
|
||||
- `idx_linea_factura` (facturaId)
|
||||
|
||||
### Helpers
|
||||
|
||||
- `importeNeto`: importe - descuento
|
||||
- `importeConIva`: importeNeto + ivaMonto
|
||||
- `calcularImporte()`: cantidad * precioUnitario
|
||||
- `calcularIva()`: importeNeto * (ivaTasa/100)
|
||||
|
||||
---
|
||||
|
||||
## 6. FuelSurcharge
|
||||
|
||||
**Archivo:** `fuel-surcharge.entity.ts`
|
||||
**Tabla:** `billing.fuel_surcharge`
|
||||
**Descripcion:** Tabla de fuel surcharge (recargo por combustible) por periodo.
|
||||
|
||||
### Campos
|
||||
|
||||
| Campo | Tipo | Null | Default | Descripcion |
|
||||
|-------|------|------|---------|-------------|
|
||||
| id | uuid | No | gen | Identificador unico |
|
||||
| tenantId | uuid | No | - | Tenant (empresa) |
|
||||
| fechaInicio | date | No | - | Inicio del periodo |
|
||||
| fechaFin | date | No | - | Fin del periodo |
|
||||
| precioDieselReferencia | decimal(10,4) | Si | - | Precio diesel base |
|
||||
| precioDieselActual | decimal(10,4) | Si | - | Precio diesel actual |
|
||||
| porcentajeSurcharge | decimal(5,2) | No | - | % a aplicar |
|
||||
| activo | boolean | No | true | Periodo activo |
|
||||
| createdAt | timestamptz | No | now() | Fecha creacion |
|
||||
| createdById | uuid | No | - | Usuario creador |
|
||||
|
||||
### Indices
|
||||
|
||||
- `idx_fuel_surcharge_fecha` (tenantId, fechaInicio, fechaFin)
|
||||
|
||||
### Helpers
|
||||
|
||||
- `vigente`: true si fecha actual en rango y activo
|
||||
- `variacionPrecio`: % variacion diesel actual vs referencia
|
||||
- `calcularRecargo(montoBase)`: montoBase * (porcentajeSurcharge/100)
|
||||
- `descripcionPeriodo`: "01/01/2026 - 15/01/2026"
|
||||
|
||||
---
|
||||
|
||||
## Diagrama de Relaciones
|
||||
|
||||
```
|
||||
+----------------+ +----------------+
|
||||
| Lane |<------+ Tarifa |
|
||||
+----------------+ +----------------+
|
||||
|
|
||||
v
|
||||
+----------------+ +------------------+
|
||||
| RecargoCatalogo|<------+ LineaFactura |
|
||||
+----------------+ +--------+---------+
|
||||
|
|
||||
v
|
||||
+----------------+ +------------------+
|
||||
| FuelSurcharge | | FacturaTransporte|
|
||||
+----------------+ +------------------+
|
||||
|
|
||||
+----> Viajes/OTs (referencias)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Flujo de Facturacion
|
||||
|
||||
```
|
||||
1. CREAR FACTURA
|
||||
- Seleccionar viajes/OTs a facturar
|
||||
- Sistema calcula totales de servicios
|
||||
|
||||
2. AGREGAR LINEAS
|
||||
- Lineas automaticas desde viajes/OTs
|
||||
- Lineas manuales (recargos, ajustes)
|
||||
|
||||
3. APLICAR RECARGOS
|
||||
- Fuel surcharge (automatico si activo)
|
||||
- Detention, maniobras, etc.
|
||||
|
||||
4. REVISAR TOTALES
|
||||
- Subtotal, descuentos, IVA, retenciones
|
||||
- Total a cobrar
|
||||
|
||||
5. TIMBRAR CFDI
|
||||
- Generar XML con Carta Porte (MAE-016)
|
||||
- Enviar a PAC
|
||||
- Obtener UUID y sello
|
||||
|
||||
6. ENVIAR AL CLIENTE
|
||||
- PDF + XML por email
|
||||
- Registrar en portal
|
||||
|
||||
7. SEGUIMIENTO COBRANZA
|
||||
- Registrar pagos parciales/totales
|
||||
- Alertas de vencimiento
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Casos de Uso
|
||||
|
||||
### CU-001: Crear Tarifa por Lane
|
||||
1. Administrador define origen-destino (Lane)
|
||||
2. Crea tarifa asociada con tipo de calculo
|
||||
3. Define vigencia y monto minimo
|
||||
4. Opcionalmente asocia a cliente especifico
|
||||
|
||||
### CU-002: Facturar Viajes
|
||||
1. Operaciones cierra viajes con POD
|
||||
2. Administracion selecciona viajes a facturar
|
||||
3. Sistema genera factura con lineas
|
||||
4. Aplica fuel surcharge vigente
|
||||
5. Timbra y envia al cliente
|
||||
|
||||
### CU-003: Actualizar Fuel Surcharge
|
||||
1. Administrador obtiene precio diesel actual
|
||||
2. Compara con precio de referencia
|
||||
3. Calcula % de incremento
|
||||
4. Crea nuevo periodo de fuel surcharge
|
||||
5. Sistema aplica automaticamente a nuevas facturas
|
||||
|
||||
---
|
||||
|
||||
*MAI-009 Facturacion Transporte - ERP Transportistas v1.0.0*
|
||||
@ -0,0 +1,364 @@
|
||||
# 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*
|
||||
@ -5,11 +5,12 @@ task_id: TASK-2026-01-25-DOCUMENTACION-MODULOS
|
||||
title: "Documentacion de Modulos y Entidades de ERP Transportistas"
|
||||
type: documentation
|
||||
priority: P0
|
||||
status: in_progress
|
||||
status: completed
|
||||
|
||||
# Fechas
|
||||
created: 2026-01-25
|
||||
started: 2026-01-25
|
||||
completed: 2026-01-25
|
||||
|
||||
# Asignacion
|
||||
owner: claude-code
|
||||
@ -55,24 +56,29 @@ scope:
|
||||
phases:
|
||||
- id: FASE-1
|
||||
title: "Crear inventarios base"
|
||||
status: pending
|
||||
status: completed
|
||||
completed_date: 2026-01-25
|
||||
entregables:
|
||||
- orchestration/inventarios/DATABASE_INVENTORY.yml
|
||||
- orchestration/inventarios/BACKEND_INVENTORY.yml
|
||||
- orchestration/inventarios/MASTER_INVENTORY.yml
|
||||
notas: "MASTER_INVENTORY.yml pendiente para siguiente iteracion"
|
||||
|
||||
- id: FASE-2
|
||||
title: "Documentar entidades nuevas"
|
||||
status: pending
|
||||
status: completed
|
||||
completed_date: 2026-01-25
|
||||
entregables:
|
||||
- docs/02-definicion-modulos/MAI-012-combustible-gastos/ENTITIES.md
|
||||
- docs/02-definicion-modulos/MAI-009-facturacion-transporte/ENTITIES.md
|
||||
notas: "11 entidades documentadas con campos, indices, ENUMs y helpers"
|
||||
|
||||
- id: FASE-3
|
||||
title: "Actualizar PROXIMA-ACCION.md"
|
||||
status: pending
|
||||
status: completed
|
||||
completed_date: 2026-01-25
|
||||
entregables:
|
||||
- orchestration/PROXIMA-ACCION.md
|
||||
notas: "Estado actual 45% completado documentado"
|
||||
|
||||
# Metodologia
|
||||
methodology: CAPVED
|
||||
|
||||
Loading…
Reference in New Issue
Block a user