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>

docs/02-definicion-modulos/MAI-009-facturacion-transporte/ENTITIES.md

@@ -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*

docs/02-definicion-modulos/MAI-012-combustible-gastos/ENTITIES.md

@@ -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*

orchestration/tareas/TASK-2026-01-25-DOCUMENTACION-MODULOS/METADATA.yml

@@ -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