rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
erp-transportistas-v2/docs/02-definicion-modulos/MAI-009-facturacion-transporte/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

427 lines
14 KiB
Markdown
Raw Permalink Blame History

# 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*
Reference in New Issue View Git Blame Copy Permalink