docs: Add MAI-009 (Facturación) and MAI-010 (Liquidaciones) specifications
MAI-009 Facturación Transporte (31 SP): - README, REQUERIMIENTOS (7 RF), RESUMEN-EPICA - 5 User Stories: generación factura, recargos, CFDI/Carta Porte, conciliación/pagos, estados de cuenta MAI-010 Liquidaciones (31 SP): - README, REQUERIMIENTOS (6 RF), RESUMEN-EPICA - 5 User Stories: esquemas pago, cálculo por viaje, viáticos, deducciones, generar/autorizar liquidación Part of Phase 2 - P0 Critical Modules specification Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Adrian Flores Cortes
parent
9caeae936a
commit
569eaeb5a4
@ -0,0 +1,207 @@
|
||||
# MAI-009: Facturación de Transporte
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Estado:** Diseño
|
||||
**Prioridad:** P1 (Crítico - Monetización)
|
||||
|
||||
---
|
||||
|
||||
## Descripción General
|
||||
|
||||
El módulo de Facturación de Transporte es responsable de generar facturas CFDI por los servicios de transporte, aplicando tarifas, recargos y conectando con evidencias de entrega (POD).
|
||||
|
||||
**Problema que resuelve:**
|
||||
- Facturación manual lenta y propensa a errores
|
||||
- Recargos (demoras, fuel surcharge) no capturados
|
||||
- Falta de trazabilidad factura → viaje → POD
|
||||
- Conciliación difícil entre cotizado vs facturado vs cobrado
|
||||
- Aging de cartera sin visibilidad
|
||||
|
||||
---
|
||||
|
||||
## Objetivos del Módulo
|
||||
|
||||
1. **Factura automatizada:** Generar facturas desde viajes cerrados con POD
|
||||
2. **Recargos automáticos:** Aplicar fuel surcharge, detention, maniobras
|
||||
3. **Trazabilidad completa:** Vincular factura con viajes, POD y evidencias
|
||||
4. **CFDI timbrado:** Integración con PAC para factura electrónica
|
||||
5. **Gestión de cobranza:** Estados de cuenta, aging, pagos
|
||||
|
||||
---
|
||||
|
||||
## Alcance Funcional
|
||||
|
||||
### Incluido
|
||||
|
||||
- Facturación por viaje, por embarque o por OT
|
||||
- Cálculo automático de recargos (fuel, detention, etc.)
|
||||
- Integración con POD para adjuntar evidencias
|
||||
- Timbrado CFDI via PAC
|
||||
- Complemento Carta Porte (MAE-016)
|
||||
- Estados de cuenta por cliente
|
||||
- Registro de pagos y aging de cartera
|
||||
|
||||
### Excluido
|
||||
|
||||
- Cobranza judicial (CRM/Legal)
|
||||
- Contabilidad detallada (módulo financiero erp-core)
|
||||
- Carta Porte como documento independiente (MAE-016)
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el módulo |
|
||||
|-------|------------------|
|
||||
| Facturador | Crea y emite facturas |
|
||||
| Contador | Revisa, aprueba, concilia |
|
||||
| Cobranza | Seguimiento de pagos, aging |
|
||||
| Cliente | Recibe factura, realiza pagos |
|
||||
| Sistema PAC | Timbra CFDI |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
VIAJES CERRADOS (con POD)
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. SELECCIONAR VIAJES A FACTURAR │
|
||||
│ - Filtrar por cliente/periodo │
|
||||
│ - Viajes con POD pendientes facturar │
|
||||
│ - Selección individual o masiva │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 2. GENERAR BORRADOR DE FACTURA │
|
||||
│ - Líneas automáticas desde viajes │
|
||||
│ - Aplicar tarifa de cada viaje │
|
||||
│ - Calcular subtotales │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 3. APLICAR RECARGOS │
|
||||
│ - Fuel surcharge automático │
|
||||
│ - Detention si aplica │
|
||||
│ - Maniobras, escoltas, etc. │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 4. REVISAR Y AJUSTAR │
|
||||
│ - Verificar montos │
|
||||
│ - Aplicar descuento (si autorizado) │
|
||||
│ - Agregar notas/observaciones │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 5. TIMBRAR CFDI │
|
||||
│ - Generar XML con datos fiscales │
|
||||
│ - Incluir complemento Carta Porte │
|
||||
│ - Enviar a PAC │
|
||||
│ - Recibir UUID y sellos │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 6. ENVIAR AL CLIENTE │
|
||||
│ - Email con PDF + XML │
|
||||
│ - Publicar en portal cliente │
|
||||
│ - Adjuntar POD si requiere │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 7. SEGUIMIENTO DE COBRANZA │
|
||||
│ - Registrar pagos │
|
||||
│ - Alertas de vencimiento │
|
||||
│ - Estados de cuenta │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Datos del Módulo
|
||||
|
||||
### Entidades Principales
|
||||
|
||||
| Entidad | Descripción | Estado |
|
||||
|---------|-------------|--------|
|
||||
| Lane | Ruta origen-destino | IMPLEMENTADA |
|
||||
| Tarifa | Precio por lane/servicio | IMPLEMENTADA |
|
||||
| RecargoCatalogo | Tipos de recargos | IMPLEMENTADA |
|
||||
| FacturaTransporte | Factura CFDI | IMPLEMENTADA |
|
||||
| LineaFactura | Conceptos facturados | IMPLEMENTADA |
|
||||
| FuelSurcharge | Índice de combustible | IMPLEMENTADA |
|
||||
|
||||
Ver archivo: [ENTITIES.md](./ENTITIES.md)
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md)
|
||||
|
||||
---
|
||||
|
||||
## Integración con PAC
|
||||
|
||||
| PAC | Tipo | Uso |
|
||||
|-----|------|-----|
|
||||
| Finkok | Primario | Timbrado, cancelación |
|
||||
| SW Sapien | Respaldo | Failover |
|
||||
|
||||
### Servicios requeridos:
|
||||
- Timbrado de CFDI 4.0
|
||||
- Complemento Carta Porte 3.1
|
||||
- Cancelación de CFDI
|
||||
- Consulta de estatus
|
||||
|
||||
---
|
||||
|
||||
## Métricas del Módulo
|
||||
|
||||
| KPI | Fórmula | Meta |
|
||||
|-----|---------|------|
|
||||
| Días a facturar | Avg(fecha_factura - fecha_pod) | <3 días |
|
||||
| Recargos capturados | % viajes con recargos aplicados | >95% |
|
||||
| Facturas rechazadas | % facturas con error PAC | <2% |
|
||||
| DSO | Días promedio de cobranza | <45 días |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Este módulo depende de:
|
||||
- MAI-007 (POD): Viajes cerrados con evidencia
|
||||
- MAI-002 (Tarifas): Precios y recargos
|
||||
- MAE-016 (Carta Porte): Complemento CFDI
|
||||
- erp-core/partners: Datos fiscales del cliente
|
||||
|
||||
### Otros módulos dependen de este:
|
||||
- erp-core/financial: Conciliación contable
|
||||
- MAI-015 (Portal Cliente): Consulta de facturas
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
Ver carpeta: [historias-usuario/](./historias-usuario/)
|
||||
|
||||
| US | Título | Prioridad |
|
||||
|----|--------|-----------|
|
||||
| US-MAI009-001 | Generar factura desde viajes | Alta |
|
||||
| US-MAI009-002 | Aplicar recargos automáticos | Alta |
|
||||
| US-MAI009-003 | Timbrar CFDI con Carta Porte | Alta |
|
||||
| US-MAI009-004 | Gestionar conciliación y pagos | Media |
|
||||
| US-MAI009-005 | Generar estados de cuenta | Media |
|
||||
|
||||
---
|
||||
|
||||
*Módulo MAI-009 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,234 @@
|
||||
# REQUERIMIENTOS.md - MAI-009: Facturación de Transporte
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.8
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.8.1: Factura por Viaje/Embarque/OT
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir configurar si la facturación se realiza por viaje individual, por embarque (grupo de OTs), o por OT específica.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Configuración por cliente: facturar por viaje, embarque u OT
|
||||
2. Selección de viajes cerrados (con POD) pendientes de facturar
|
||||
3. Facturación masiva de múltiples viajes en una sola factura
|
||||
4. Facturación individual (una factura por viaje)
|
||||
5. Agrupación automática por periodo (semanal, quincenal, mensual)
|
||||
6. Generación de borrador editable antes de timbrar
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `billing.facturas_transporte`
|
||||
- Tabla: `billing.lineas_factura`
|
||||
- Vista: `v_viajes_por_facturar`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/facturacion/viajes-pendientes` - Listar viajes a facturar
|
||||
- `POST /api/v1/facturas` - Crear factura
|
||||
- `GET /api/v1/facturas/:id` - Obtener factura
|
||||
- `PUT /api/v1/facturas/:id` - Actualizar borrador
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.8.2: Cálculo Automático de Recargos
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe calcular y aplicar automáticamente los recargos correspondientes: fuel surcharge, demoras (detention) por tiempos reales, reentregas, cambios de destino.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Fuel surcharge: aplicar % vigente sobre tarifa base
|
||||
2. Detention en carga: calcular si tiempo real > tolerancia
|
||||
3. Detention en descarga: calcular si tiempo real > tolerancia
|
||||
4. Reentrega: aplicar cargo si hubo reexpedición
|
||||
5. Cambio de destino: calcular diferencial de tarifa
|
||||
6. Mostrar desglose de cada recargo en la factura
|
||||
7. Permitir ajustar o eliminar recargos con justificación
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `billing.recargos_catalogo`
|
||||
- Tabla: `billing.fuel_surcharge`
|
||||
- Tabla: `billing.lineas_factura` (con recargoId)
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/facturas/:id/calcular-recargos` - Calcular recargos
|
||||
- `PUT /api/v1/facturas/:id/lineas/:lineaId` - Ajustar línea
|
||||
- `DELETE /api/v1/facturas/:id/lineas/:lineaId` - Eliminar línea
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.8.3: Integración con POD
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe anexar el POD y evidencias de entrega a la factura/expediente digital para soporte de cobranza.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Vincular factura con viajes y sus PODs
|
||||
2. Incluir URL de evidencias (fotos, firma) en factura
|
||||
3. Generar expediente digital con: factura PDF, XML, POD, carta porte
|
||||
4. Enviar expediente completo al cliente
|
||||
5. POD disponible para descarga desde portal cliente
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `billing.facturas_transporte` (viajeIds, otIds)
|
||||
- Relación con: `tracking.pods`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/facturas/:id/expediente` - Obtener expediente
|
||||
- `GET /api/v1/facturas/:id/expediente/zip` - Descargar ZIP
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.8.4: Conciliación
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir comparar: cotización original vs factura emitida vs monto cobrado, para identificar diferencias y ajustes.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Mostrar comparativo: cotizado vs facturado
|
||||
2. Identificar diferencias (recargos no cotizados, descuentos aplicados)
|
||||
3. Registrar ajustes con justificación
|
||||
4. Generar notas de crédito/débito cuando aplique
|
||||
5. Dashboard de conciliación por periodo
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Vista: `v_conciliacion_facturas`
|
||||
- Tabla: `billing.notas_credito_debito`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/facturacion/conciliacion` - Reporte de conciliación
|
||||
- `POST /api/v1/notas` - Crear nota de crédito/débito
|
||||
|
||||
**Prioridad:** Media
|
||||
|
||||
---
|
||||
|
||||
### RF-4.8.5: Estados de Cuenta por Cliente
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe generar estados de cuenta con: viajes, cargos, abonos, notas, y análisis de antigüedad de saldos (aging).
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Estado de cuenta por cliente con periodo seleccionable
|
||||
2. Mostrar: facturas emitidas, notas, pagos recibidos, saldo
|
||||
3. Análisis de aging: corriente, 30 días, 60 días, 90 días, +90 días
|
||||
4. Alertas de facturas próximas a vencer
|
||||
5. Exportar a PDF y Excel
|
||||
6. Envío automático periódico al cliente
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Vista: `v_estado_cuenta_cliente`
|
||||
- Vista: `v_aging_cartera`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/clientes/:id/estado-cuenta` - Estado de cuenta
|
||||
- `GET /api/v1/facturacion/aging` - Reporte de aging
|
||||
- `POST /api/v1/clientes/:id/estado-cuenta/enviar` - Enviar por email
|
||||
|
||||
**Prioridad:** Media
|
||||
|
||||
---
|
||||
|
||||
### RF-4.8.6: Timbrado CFDI
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe generar el CFDI 4.0 con complemento Carta Porte 3.1 y timbrarlo mediante PAC autorizado.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Generar XML CFDI 4.0 con datos fiscales
|
||||
2. Incluir complemento Carta Porte (MAE-016)
|
||||
3. Enviar a PAC para timbrado
|
||||
4. Recibir y almacenar UUID, sello digital, cadena original
|
||||
5. Generar PDF representación impresa
|
||||
6. Manejar errores de validación SAT
|
||||
7. Proceso de cancelación con motivo
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `billing.facturas_transporte` (uuidCfdi, xmlCfdi)
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/facturas/:id/timbrar` - Timbrar CFDI
|
||||
- `POST /api/v1/facturas/:id/cancelar` - Cancelar CFDI
|
||||
- `GET /api/v1/facturas/:id/pdf` - Obtener PDF
|
||||
- `GET /api/v1/facturas/:id/xml` - Obtener XML
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.8.7: Registro de Pagos
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir registrar pagos parciales o totales y actualizar el estado de la factura.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Registrar pago con: monto, fecha, referencia, método
|
||||
2. Soportar pagos parciales con saldo pendiente
|
||||
3. Marcar factura como PAGADA cuando saldo = 0
|
||||
4. Generar complemento de pago si aplica (PPD)
|
||||
5. Conciliar con movimientos bancarios (opcional)
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `billing.pagos_factura`
|
||||
- Tabla: `billing.facturas_transporte` (montoPagado, fechaPago)
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/facturas/:id/pagos` - Registrar pago
|
||||
- `GET /api/v1/facturas/:id/pagos` - Historial de pagos
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Integración PAC
|
||||
El sistema debe soportar al menos 2 PACs con failover automático.
|
||||
|
||||
### RNF-002: Performance
|
||||
La generación de factura (sin timbrado) debe completarse en <5 segundos.
|
||||
|
||||
### RNF-003: Retención
|
||||
Los CFDIs deben almacenarse por al menos 5 años según normativa SAT.
|
||||
|
||||
### RNF-004: Disponibilidad
|
||||
El proceso de timbrado debe tener 99.5% de disponibilidad.
|
||||
|
||||
---
|
||||
|
||||
## Validaciones de Negocio
|
||||
|
||||
| Validación | Descripción | Acción si falla |
|
||||
|------------|-------------|-----------------|
|
||||
| FAC_001 | Viaje con POD válido | Bloquear facturación |
|
||||
| FAC_002 | Datos fiscales cliente completos | Alertar, bloquear timbrado |
|
||||
| FAC_003 | Carta Porte completa si aplica | Bloquear timbrado |
|
||||
| FAC_004 | Tarifa vigente aplicada | Alertar si tarifa vencida |
|
||||
| FAC_005 | Fuel surcharge actualizado | Alertar si >30 días |
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tabla DDL | Entity | Endpoint | US |
|
||||
|----|-----------|--------|----------|---|
|
||||
| RF-4.8.1 | facturas_transporte | FacturaTransporte | /facturas | US-MAI009-001 |
|
||||
| RF-4.8.2 | lineas_factura | LineaFactura | /facturas/:id/lineas | US-MAI009-002 |
|
||||
| RF-4.8.3 | facturas_transporte | FacturaTransporte | /facturas/:id/expediente | US-MAI009-001 |
|
||||
| RF-4.8.4 | v_conciliacion | - | /facturacion/conciliacion | US-MAI009-004 |
|
||||
| RF-4.8.5 | v_estado_cuenta | - | /clientes/:id/estado-cuenta | US-MAI009-005 |
|
||||
| RF-4.8.6 | facturas_transporte | FacturaTransporte | /facturas/:id/timbrar | US-MAI009-003 |
|
||||
| RF-4.8.7 | pagos_factura | PagoFactura | /facturas/:id/pagos | US-MAI009-004 |
|
||||
|
||||
---
|
||||
|
||||
*MAI-009 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,242 @@
|
||||
# RESUMEN-EPICA.md - MAI-009: Facturación de Transporte
|
||||
|
||||
**Código:** MAI-009
|
||||
**Nombre:** Facturación de Transporte
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema
|
||||
|
||||
Las empresas transportistas pierden dinero por:
|
||||
- Facturación tardía (servicios olvidados, efectivo atrasado)
|
||||
- Recargos no capturados (fuel, detention) = ingreso perdido
|
||||
- Errores en timbrado que retrasan cobranza
|
||||
- Falta de visibilidad en cartera (quién debe, cuánto, hace cuánto)
|
||||
- Expedientes incompletos que dificultan cobranza
|
||||
|
||||
### Solución
|
||||
|
||||
Un módulo de facturación que:
|
||||
- Genera facturas automáticamente desde viajes cerrados
|
||||
- Calcula y aplica recargos según reglas configuradas
|
||||
- Timbra CFDI con Carta Porte en un clic
|
||||
- Genera expediente completo (factura + POD + evidencias)
|
||||
- Proporciona visibilidad de cartera y aging
|
||||
|
||||
### Beneficios Esperados
|
||||
|
||||
| Beneficio | Métrica | Impacto |
|
||||
|-----------|---------|---------|
|
||||
| Facturación rápida | -80% tiempo de facturación | Flujo de efectivo |
|
||||
| Recargos capturados | +15% ingresos por recargos | Rentabilidad |
|
||||
| Menos errores | -90% rechazos de CFDI | Productividad |
|
||||
| Cobranza efectiva | -10 días DSO | Capital de trabajo |
|
||||
|
||||
---
|
||||
|
||||
## Actores y Stakeholders
|
||||
|
||||
### Usuarios Primarios
|
||||
|
||||
| Actor | Responsabilidad | Frecuencia |
|
||||
|-------|-----------------|------------|
|
||||
| Facturador | Genera y emite facturas | Diaria |
|
||||
| Contador | Revisa, concilia, registra pagos | Diaria |
|
||||
| Cobranza | Seguimiento de cartera | Diaria |
|
||||
|
||||
### Usuarios Secundarios
|
||||
|
||||
| Actor | Interés |
|
||||
|-------|---------|
|
||||
| Gerente Finanzas | Reportes de facturación y cobranza |
|
||||
| Cliente | Recibe facturas, consulta estado de cuenta |
|
||||
| Auditor | Revisión de expedientes fiscales |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VIAJES CERRADOS (con POD) │
|
||||
│ (Listos para facturar desde MAI-007) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. SELECCIONAR VIAJES (Facturador) │
|
||||
│ │
|
||||
│ Cliente: [Distribuidora ABC ▼] │
|
||||
│ Periodo: [01-ene-2026] al [15-ene-2026] │
|
||||
│ │
|
||||
│ ☑ VJE-0120 | CDMX→GDL | $12,500 | POD: 2026-01-05 ✓ │
|
||||
│ ☑ VJE-0125 | CDMX→MTY | $18,200 | POD: 2026-01-08 ✓ │
|
||||
│ ☑ VJE-0128 | CDMX→GDL | $12,500 | POD: 2026-01-12 ✓ │
|
||||
│ ☐ VJE-0130 | GDL→TIJ | $25,000 | POD: Pendiente ⚠ │
|
||||
│ │
|
||||
│ Total seleccionado: 3 viajes | $43,200 │
|
||||
│ │
|
||||
│ [Generar Factura] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. BORRADOR DE FACTURA │
|
||||
│ │
|
||||
│ Factura: BORRADOR (sin serie/folio) │
|
||||
│ Cliente: Distribuidora ABC S.A. de C.V. │
|
||||
│ RFC: DAB850101XXX │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CONCEPTOS │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ #1 | Servicio de transporte CDMX→GDL │ │
|
||||
│ │ Viaje: VJE-0120 | Caja seca 53' │ │
|
||||
│ │ Cantidad: 1 | P.U.: $12,500.00 | Importe: $12,500 │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ #2 | Servicio de transporte CDMX→MTY │ │
|
||||
│ │ Viaje: VJE-0125 | Caja seca 53' │ │
|
||||
│ │ Cantidad: 1 | P.U.: $18,200.00 | Importe: $18,200 │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ #3 | Servicio de transporte CDMX→GDL │ │
|
||||
│ │ Viaje: VJE-0128 | Caja seca 53' │ │
|
||||
│ │ Cantidad: 1 | P.U.: $12,500.00 | Importe: $12,500 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [+ Agregar concepto] Subtotal: $43,200.00 │
|
||||
│ │
|
||||
│ [Calcular Recargos] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. RECARGOS APLICADOS │
|
||||
│ │
|
||||
│ RECARGOS AUTOMÁTICOS: │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ #4 | Fuel Surcharge (8%) │ │
|
||||
│ │ Sobre viajes 1-3 │ │
|
||||
│ │ Cantidad: 1 | P.U.: $3,456.00 | Importe: $3,456 │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ #5 | Detention en descarga (VJE-0125) │ │
|
||||
│ │ 3 hrs extra @ $350/hr │ │
|
||||
│ │ Cantidad: 3 | P.U.: $350.00 | Importe: $1,050 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ Subtotal servicios: $43,200.00 │
|
||||
│ Subtotal recargos: $4,506.00 │
|
||||
│ Subtotal: $47,706.00 │
|
||||
│ IVA (16%): $7,632.96 │
|
||||
│ ───────────────────────────────────────── │
|
||||
│ TOTAL: $55,338.96 MXN │
|
||||
│ │
|
||||
│ [Editar] [Vista previa PDF] [Timbrar CFDI] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. CFDI TIMBRADO │
|
||||
│ │
|
||||
│ ✓ FACTURA TIMBRADA EXITOSAMENTE │
|
||||
│ │
|
||||
│ Serie: A | Folio: 00456 │
|
||||
│ UUID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 │
|
||||
│ Fecha timbrado: 2026-01-27 14:32:15 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ EXPEDIENTE DIGITAL │
|
||||
│ 📄 A-00456.pdf (Factura) [Descargar] │
|
||||
│ 📄 A-00456.xml (CFDI) [Descargar] │
|
||||
│ 📄 POD-VJE-0120.pdf [Descargar] │
|
||||
│ 📄 POD-VJE-0125.pdf [Descargar] │
|
||||
│ 📄 POD-VJE-0128.pdf [Descargar] │
|
||||
│ │
|
||||
│ [Descargar todo ZIP] [Enviar al cliente] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ FACTURA EMITIDA │
|
||||
│ → Pendiente de pago │
|
||||
│ → Visible en portal cliente │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Éxito
|
||||
|
||||
### Funcionales
|
||||
|
||||
- [ ] Facturación por viaje/embarque/OT configurable
|
||||
- [ ] Cálculo automático de recargos
|
||||
- [ ] Timbrado CFDI con Carta Porte
|
||||
- [ ] Expediente digital completo
|
||||
- [ ] Registro de pagos y aging
|
||||
- [ ] Estados de cuenta por cliente
|
||||
|
||||
### Técnicos
|
||||
|
||||
- [ ] Integración con 2 PACs
|
||||
- [ ] Failover automático
|
||||
- [ ] Almacenamiento de XML 5 años
|
||||
- [ ] Performance <5 segundos generación
|
||||
|
||||
### Negocio
|
||||
|
||||
- [ ] <3 días entre POD y factura
|
||||
- [ ] >95% recargos capturados
|
||||
- [ ] <2% facturas rechazadas
|
||||
- [ ] DSO <45 días
|
||||
|
||||
---
|
||||
|
||||
## Riesgos y Mitigaciones
|
||||
|
||||
| Riesgo | Probabilidad | Impacto | Mitigación |
|
||||
|--------|--------------|---------|------------|
|
||||
| PAC no disponible | Media | Alto | Segundo PAC de respaldo |
|
||||
| Error en Carta Porte | Media | Alto | Validación previa al timbrado |
|
||||
| Datos fiscales incorrectos | Media | Medio | Validación de RFC |
|
||||
| Recargos no aplicados | Alta | Alto | Cálculo automático obligatorio |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Prerequisitos
|
||||
- MAI-007 (POD): Viajes cerrados con POD
|
||||
- MAI-002 (Tarifas): Tarifas y recargos configurados
|
||||
- MAE-016 (Carta Porte): Complemento fiscal
|
||||
- erp-core/partners: Datos fiscales
|
||||
|
||||
### Habilita
|
||||
- erp-core/financial: Contabilidad
|
||||
- MAI-015 (Portal): Consulta de facturas
|
||||
|
||||
---
|
||||
|
||||
## Story Points Estimados
|
||||
|
||||
| Historia | Complejidad | SP |
|
||||
|----------|-------------|---|
|
||||
| US-MAI009-001 | Alta | 8 |
|
||||
| US-MAI009-002 | Media | 5 |
|
||||
| US-MAI009-003 | Alta | 8 |
|
||||
| US-MAI009-004 | Media | 5 |
|
||||
| US-MAI009-005 | Media | 5 |
|
||||
| **Total** | | **31** |
|
||||
|
||||
---
|
||||
|
||||
*Épica MAI-009 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,187 @@
|
||||
# US-MAI009-001: Generar factura desde viajes
|
||||
|
||||
**ID:** US-MAI009-001
|
||||
**Módulo:** MAI-009 (Facturación Transporte)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** facturador
|
||||
**Quiero** generar facturas seleccionando los viajes cerrados de un cliente
|
||||
**Para** cobrar los servicios de transporte de manera rápida y precisa
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Listar viajes pendientes de facturar
|
||||
**Dado** que hay viajes cerrados con POD
|
||||
**Cuando** filtro por cliente y periodo
|
||||
**Entonces** veo la lista de viajes sin facturar con sus montos
|
||||
|
||||
### CA-002: Selección múltiple de viajes
|
||||
**Dado** que veo la lista de viajes
|
||||
**Cuando** selecciono varios viajes
|
||||
**Entonces** puedo generar una factura que los agrupe
|
||||
|
||||
### CA-003: Factura individual por viaje
|
||||
**Dado** que el cliente requiere facturas separadas
|
||||
**Cuando** selecciono "Facturar individualmente"
|
||||
**Entonces** se genera una factura por cada viaje seleccionado
|
||||
|
||||
### CA-004: Generar borrador editable
|
||||
**Dado** que seleccioné los viajes
|
||||
**Cuando** genero la factura
|
||||
**Entonces** se crea un borrador con líneas automáticas que puedo editar
|
||||
|
||||
### CA-005: Líneas automáticas desde tarifa
|
||||
**Dado** que cada viaje tiene una tarifa aplicada
|
||||
**Cuando** se genera el borrador
|
||||
**Entonces** cada línea refleja el precio del viaje según su tarifa
|
||||
|
||||
### CA-006: Vincular con POD y evidencias
|
||||
**Dado** que la factura incluye viajes
|
||||
**Cuando** consulto el expediente
|
||||
**Entonces** puedo ver/descargar los POD de cada viaje incluido
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ FACTURACIÓN - SELECCIONAR VIAJES [+ Nueva]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Cliente: [Distribuidora ABC ▼] │
|
||||
│ Periodo: [01-ene-2026] al [31-ene-2026] [Buscar] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ VIAJES PENDIENTES DE FACTURAR │
|
||||
│ │
|
||||
│ [☑ Seleccionar todos] │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ☑ VJE-0120 | 05-ene-2026 │ │
|
||||
│ │ CDMX → Guadalajara | Caja seca 53' │ │
|
||||
│ │ Tarifa: $12,500.00 | POD: ✓ 05-ene-2026 14:30 │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ☑ VJE-0125 | 08-ene-2026 │ │
|
||||
│ │ CDMX → Monterrey | Caja seca 53' │ │
|
||||
│ │ Tarifa: $18,200.00 | POD: ✓ 08-ene-2026 16:45 │ │
|
||||
│ │ ⚠ Detention: 3 hrs extra en descarga │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ☑ VJE-0128 | 12-ene-2026 │ │
|
||||
│ │ CDMX → Guadalajara | Caja seca 53' │ │
|
||||
│ │ Tarifa: $12,500.00 | POD: ✓ 12-ene-2026 11:20 │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ☐ VJE-0130 | 14-ene-2026 │ │
|
||||
│ │ Guadalajara → Tijuana | Caja seca 53' │ │
|
||||
│ │ Tarifa: $25,000.00 | POD: ⏳ PENDIENTE │ │
|
||||
│ │ (No disponible - sin POD) │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN DE SELECCIÓN │
|
||||
│ Viajes seleccionados: 3 │
|
||||
│ Subtotal tarifas: $43,200.00 │
|
||||
│ + Recargos estimados: $4,506.00 (fuel + detention) │
|
||||
│ Total estimado: $47,706.00 + IVA │
|
||||
│ │
|
||||
│ Tipo de facturación: │
|
||||
│ (●) Una factura con todos los viajes │
|
||||
│ ( ) Una factura por cada viaje │
|
||||
│ │
|
||||
│ [Cancelar] [Generar Borrador] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Borrador de Factura
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ FACTURA BORRADOR ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Estado: BORRADOR │
|
||||
│ │
|
||||
│ DATOS DEL CLIENTE │
|
||||
│ Cliente: Distribuidora ABC S.A. de C.V. │
|
||||
│ RFC: DAB850101XXX │
|
||||
│ Uso CFDI: [G03 - Gastos en general ▼] │
|
||||
│ Método pago: [PUE - Pago en una exhibición▼] │
|
||||
│ Forma pago: [03 - Transferencia ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CONCEPTOS [+ Agregar]│
|
||||
│ │
|
||||
│ | # | Descripción | Cant | P.U. | Importe |│
|
||||
│ |---|--------------------------|------|-----------|----------|│
|
||||
│ | 1 | Transporte CDMX→GDL | 1 | $12,500.00| $12,500 |│
|
||||
│ | | VJE-0120 | | | [🗑] |│
|
||||
│ |---|--------------------------|------|-----------|----------|│
|
||||
│ | 2 | Transporte CDMX→MTY | 1 | $18,200.00| $18,200 |│
|
||||
│ | | VJE-0125 | | | [🗑] |│
|
||||
│ |---|--------------------------|------|-----------|----------|│
|
||||
│ | 3 | Transporte CDMX→GDL | 1 | $12,500.00| $12,500 |│
|
||||
│ | | VJE-0128 | | | [🗑] |│
|
||||
│ |---|--------------------------|------|-----------|----------|│
|
||||
│ │
|
||||
│ Subtotal: $43,200.00 │
|
||||
│ │
|
||||
│ [Calcular Recargos] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Observaciones: │
|
||||
│ [Servicios de transporte enero 2026 ]│
|
||||
│ │
|
||||
│ [Guardar borrador] [Vista previa] [Continuar →] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados de Factura
|
||||
|
||||
| Estado | Descripción | Acciones permitidas |
|
||||
|--------|-------------|---------------------|
|
||||
| BORRADOR | En edición | Editar, eliminar, agregar líneas |
|
||||
| EMITIDA | Timbrada CFDI | Ver, descargar, enviar, cancelar |
|
||||
| ENVIADA | Enviada al cliente | Ver, registrar pago |
|
||||
| PAGADA | Saldo = 0 | Ver |
|
||||
| PARCIAL | Pago parcial | Registrar pago |
|
||||
| VENCIDA | Pasó fecha vencimiento | Registrar pago, enviar recordatorio |
|
||||
| CANCELADA | Cancelada SAT | Ver |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Endpoint: `POST /api/v1/facturas` para crear borrador
|
||||
- Los viajes se vinculan via `viajeIds[]`
|
||||
- Las líneas se generan con clave SAT: 78101500 (Transporte de carga)
|
||||
- El expediente se genera bajo demanda con todos los PDFs
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Listado de viajes pendientes de facturar
|
||||
- [ ] Filtro por cliente y periodo
|
||||
- [ ] Selección múltiple de viajes
|
||||
- [ ] Generación de borrador con líneas automáticas
|
||||
- [ ] Facturación individual o agrupada
|
||||
- [ ] Vinculación con POD
|
||||
- [ ] Tests de generación de factura
|
||||
|
||||
@ -0,0 +1,196 @@
|
||||
# US-MAI009-002: Aplicar recargos automáticos
|
||||
|
||||
**ID:** US-MAI009-002
|
||||
**Módulo:** MAI-009 (Facturación Transporte)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** facturador
|
||||
**Quiero** que el sistema calcule y aplique automáticamente los recargos correspondientes
|
||||
**Para** no olvidar cobrar fuel surcharge, demoras y otros cargos adicionales
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Calcular fuel surcharge
|
||||
**Dado** que existe un índice de fuel surcharge vigente
|
||||
**Cuando** calculo recargos en la factura
|
||||
**Entonces** se aplica el % correspondiente sobre el subtotal de tarifas
|
||||
|
||||
### CA-002: Calcular detention en carga
|
||||
**Dado** que un viaje tuvo tiempo excedido en carga
|
||||
**Cuando** calculo recargos
|
||||
**Entonces** se aplica cargo por horas extra según tolerancia configurada
|
||||
|
||||
### CA-003: Calcular detention en descarga
|
||||
**Dado** que un viaje tuvo tiempo excedido en descarga
|
||||
**Cuando** calculo recargos
|
||||
**Entonces** se aplica cargo por horas extra según tolerancia configurada
|
||||
|
||||
### CA-004: Mostrar desglose de recargos
|
||||
**Dado** que se aplicaron recargos
|
||||
**Cuando** veo la factura
|
||||
**Entonces** cada recargo aparece como línea separada con descripción clara
|
||||
|
||||
### CA-005: Permitir ajustar recargos
|
||||
**Dado** que hay recargos calculados
|
||||
**Cuando** necesito ajustar uno
|
||||
**Entonces** puedo modificar el monto o eliminar la línea con justificación
|
||||
|
||||
### CA-006: Recargos manuales
|
||||
**Dado** que hay cargos adicionales no automáticos
|
||||
**Cuando** necesito agregarlos
|
||||
**Entonces** puedo seleccionar del catálogo y especificar monto
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CALCULAR RECARGOS ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Factura: BORRADOR | Subtotal servicios: $43,200.00 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RECARGOS AUTOMÁTICOS │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ✓ FUEL SURCHARGE │ │
|
||||
│ │ Índice vigente: 8% (desde 15-ene-2026) │ │
|
||||
│ │ Base de cálculo: $43,200.00 │ │
|
||||
│ │ Monto: $3,456.00 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ✓ DETENTION DESCARGA (VJE-0125) │ │
|
||||
│ │ Tiempo real: 4.5 horas | Tolerancia: 1.5 horas │ │
|
||||
│ │ Horas extra: 3 @ $350/hr │ │
|
||||
│ │ Monto: $1,050.00 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RECARGOS MANUALES [+ Agregar]│
|
||||
│ │
|
||||
│ (No hay recargos manuales) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ Subtotal servicios: $43,200.00 │
|
||||
│ Total recargos: $4,506.00 │
|
||||
│ ───────────────────────────────────────── │
|
||||
│ Nuevo subtotal: $47,706.00 │
|
||||
│ IVA (16%): $7,632.96 │
|
||||
│ ───────────────────────────────────────── │
|
||||
│ TOTAL: $55,338.96 MXN │
|
||||
│ │
|
||||
│ [Cancelar] [Aplicar Recargos] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agregar Recargo Manual
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AGREGAR RECARGO MANUAL ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Tipo de recargo: [Seleccionar tipo ▼] │
|
||||
│ ○ MANIOBRAS - Maniobra especial │
|
||||
│ ○ ESCOLTA - Escolta de seguridad │
|
||||
│ ○ PERNOCTA - Pernocta de unidad │
|
||||
│ ○ ESTADIAS - Días extra │
|
||||
│ ○ FALSO_FLETE - Viaje cancelado │
|
||||
│ ○ SEGURO_ADICIONAL - Seguro extra │
|
||||
│ ○ OTRO - Otros │
|
||||
│ │
|
||||
│ Viaje relacionado: [VJE-0125 (opcional) ▼] │
|
||||
│ │
|
||||
│ Descripción: │
|
||||
│ [Maniobra de descarga con montacargas especial ] │
|
||||
│ │
|
||||
│ Cálculo: │
|
||||
│ (●) Monto fijo: [$800.00] │
|
||||
│ ( ) Porcentaje sobre base: [____] % │
|
||||
│ │
|
||||
│ [Cancelar] [Agregar Recargo] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ajustar Recargo
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AJUSTAR RECARGO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Recargo: DETENTION DESCARGA (VJE-0125) │
|
||||
│ Monto calculado: $1,050.00 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Acción: │
|
||||
│ ( ) Mantener monto calculado │
|
||||
│ (●) Ajustar monto: [$700.00] │
|
||||
│ ( ) Eliminar recargo │
|
||||
│ │
|
||||
│ Justificación (obligatoria si ajusta): │
|
||||
│ [Acuerdo con cliente: se cobra parcial por ser primera vez ]│
|
||||
│ │
|
||||
│ [Cancelar] [Guardar Ajuste] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Recargo
|
||||
|
||||
| Código | Nombre | Cálculo | Automático |
|
||||
|--------|--------|---------|------------|
|
||||
| FUEL | Fuel Surcharge | % sobre subtotal | Sí |
|
||||
| DETENTION_CARGA | Demora en carga | $/hora extra | Sí |
|
||||
| DETENTION_DESCARGA | Demora en descarga | $/hora extra | Sí |
|
||||
| MANIOBRAS | Maniobra especial | Monto fijo | No |
|
||||
| ESCOLTA | Escolta | Monto fijo | No |
|
||||
| PERNOCTA | Pernocta | $/noche | No |
|
||||
| ESTADIAS | Días extra | $/día | No |
|
||||
| FALSO_FLETE | Viaje cancelado | % de tarifa | No |
|
||||
| SEGURO_ADICIONAL | Seguro extra | % sobre valor | Condición |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Endpoint: `POST /api/v1/facturas/:id/calcular-recargos`
|
||||
- Fuel surcharge se obtiene de `billing.fuel_surcharge` vigente
|
||||
- Detention se calcula desde datos de `tracking.eventos` (tiempo real)
|
||||
- Los ajustes se registran en auditoría con justificación
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Cálculo automático de fuel surcharge
|
||||
- [ ] Cálculo de detention desde tiempos reales
|
||||
- [ ] Agregar recargos manuales del catálogo
|
||||
- [ ] Ajustar/eliminar recargos con justificación
|
||||
- [ ] Desglose de recargos en factura
|
||||
- [ ] Registro de ajustes en auditoría
|
||||
- [ ] Tests de cálculo de recargos
|
||||
|
||||
@ -0,0 +1,235 @@
|
||||
# US-MAI009-003: Timbrar CFDI con Carta Porte
|
||||
|
||||
**ID:** US-MAI009-003
|
||||
**Módulo:** MAI-009 (Facturación Transporte)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** facturador
|
||||
**Quiero** timbrar la factura como CFDI 4.0 con complemento Carta Porte
|
||||
**Para** cumplir con las obligaciones fiscales y entregar documentos válidos al cliente
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Validar datos antes de timbrar
|
||||
**Dado** que tengo un borrador de factura
|
||||
**Cuando** intento timbrar
|
||||
**Entonces** el sistema valida: datos fiscales del cliente, líneas correctas, Carta Porte completa
|
||||
|
||||
### CA-002: Generar XML CFDI 4.0
|
||||
**Dado** que los datos son válidos
|
||||
**Cuando** proceso el timbrado
|
||||
**Entonces** se genera el XML con estructura CFDI 4.0
|
||||
|
||||
### CA-003: Incluir complemento Carta Porte 3.1
|
||||
**Dado** que los viajes tienen datos de Carta Porte
|
||||
**Cuando** se genera el XML
|
||||
**Entonces** incluye el complemento con: ubicaciones, mercancías, autotransporte
|
||||
|
||||
### CA-004: Enviar a PAC y recibir respuesta
|
||||
**Dado** que el XML está listo
|
||||
**Cuando** se envía al PAC
|
||||
**Entonces** se recibe: UUID, sello, cadena original, o errores de validación
|
||||
|
||||
### CA-005: Manejar errores de validación
|
||||
**Dado** que el PAC retorna error
|
||||
**Cuando** veo el resultado
|
||||
**Entonces** se muestran los errores específicos para corregir
|
||||
|
||||
### CA-006: Generar PDF representación impresa
|
||||
**Dado** que el CFDI fue timbrado
|
||||
**Cuando** descargo el PDF
|
||||
**Entonces** incluye: datos fiscales, QR, cadena, sello, complemento CP
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TIMBRAR CFDI ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Factura: BORRADOR | Total: $55,338.96 MXN │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ VALIDACIÓN PREVIA │
|
||||
│ │
|
||||
│ DATOS FISCALES │
|
||||
│ ✓ RFC emisor válido: TRA850101XXX │
|
||||
│ ✓ RFC receptor válido: DAB850101XXX │
|
||||
│ ✓ Régimen fiscal configurado │
|
||||
│ ✓ Uso CFDI seleccionado: G03 │
|
||||
│ │
|
||||
│ FACTURA │
|
||||
│ ✓ Al menos una línea de concepto │
|
||||
│ ✓ Totales calculados correctamente │
|
||||
│ ✓ Forma y método de pago seleccionados │
|
||||
│ │
|
||||
│ CARTA PORTE (3 viajes) │
|
||||
│ ✓ VJE-0120: Ubicaciones y mercancías completas │
|
||||
│ ✓ VJE-0125: Ubicaciones y mercancías completas │
|
||||
│ ✓ VJE-0128: Ubicaciones y mercancías completas │
|
||||
│ ✓ Datos de autotransporte completos │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ✅ VALIDACIÓN EXITOSA - Listo para timbrar │
|
||||
│ │
|
||||
│ PAC: Finkok (Primario) │
|
||||
│ Ambiente: [Producción ▼] │
|
||||
│ │
|
||||
│ [Cancelar] [🔐 Timbrar CFDI] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resultado Exitoso
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ✅ CFDI TIMBRADO EXITOSAMENTE ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ DATOS DEL TIMBRE │
|
||||
│ │
|
||||
│ Serie: A │
|
||||
│ Folio: 00456 │
|
||||
│ UUID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 │
|
||||
│ │
|
||||
│ Fecha timbrado: 2026-01-27 14:32:15 │
|
||||
│ PAC: Finkok │
|
||||
│ Certificado SAT: 00001000000506258000 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ARCHIVOS GENERADOS │
|
||||
│ │
|
||||
│ 📄 A-00456.pdf (Representación impresa) [Descargar] │
|
||||
│ 📄 A-00456.xml (CFDI timbrado) [Descargar] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ COMPLEMENTO CARTA PORTE │
|
||||
│ │
|
||||
│ IdCCP: CCC000001234567890 │
|
||||
│ Versión: 3.1 │
|
||||
│ 3 ubicaciones | 5 mercancías | 1 figura transporte │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ SIGUIENTE PASO │
|
||||
│ │
|
||||
│ [Enviar al cliente] [Ver factura] [Nueva factura] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error de Validación
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ❌ ERROR AL TIMBRAR ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ El PAC rechazó el CFDI. Corrija los siguientes errores: │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ERRORES SAT │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ❌ CCE205 - El RFC del receptor no está en la lista LCO│ │
|
||||
│ │ RFC: DAB850101XXX │ │
|
||||
│ │ Acción: Verificar RFC correcto del cliente │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ❌ CCP155 - La clave del producto no es válida │ │
|
||||
│ │ Línea 2: Clave "99999999" no existe en catálogo │ │
|
||||
│ │ Acción: Corregir clave de producto SAT │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Código respuesta PAC: 307 │
|
||||
│ Mensaje: Documento no válido según esquema XSD │
|
||||
│ │
|
||||
│ [Volver a editar] [Reintentar timbrado] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Proceso de Cancelación
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CANCELAR CFDI ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Factura: A-00456 │
|
||||
│ UUID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 │
|
||||
│ Total: $55,338.96 MXN │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ⚠ ADVERTENCIA │
|
||||
│ La cancelación de un CFDI tiene implicaciones fiscales. │
|
||||
│ Una vez cancelada, no se puede revertir. │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Motivo de cancelación: │
|
||||
│ [01 - Comprobante emitido con errores con relación▼] │
|
||||
│ ○ 01 - Con errores con relación │
|
||||
│ ○ 02 - Con errores sin relación │
|
||||
│ ○ 03 - No se llevó a cabo la operación │
|
||||
│ ○ 04 - Operación nominativa relacionada │
|
||||
│ │
|
||||
│ UUID que sustituye (si aplica): │
|
||||
│ [________________________________] │
|
||||
│ │
|
||||
│ Justificación interna: │
|
||||
│ [Error en datos del cliente, se reexpide corregida ] │
|
||||
│ │
|
||||
│ [Cancelar operación] [⚠ Cancelar CFDI] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Integración con PAC Finkok (primario) y SW Sapien (respaldo)
|
||||
- XML se genera según esquema SAT CFDI 4.0
|
||||
- Complemento Carta Porte 3.1 se obtiene de MAE-016
|
||||
- UUID y XML se almacenan en `billing.facturas_transporte`
|
||||
- PDF se genera con template HTML + puppeteer
|
||||
- Failover automático si PAC primario falla
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Validación previa de datos fiscales
|
||||
- [ ] Generación de XML CFDI 4.0
|
||||
- [ ] Inclusión de complemento Carta Porte 3.1
|
||||
- [ ] Integración con PAC (timbrado)
|
||||
- [ ] Manejo de errores de validación SAT
|
||||
- [ ] Generación de PDF representación
|
||||
- [ ] Proceso de cancelación con motivo
|
||||
- [ ] Failover a PAC secundario
|
||||
- [ ] Tests de timbrado y cancelación
|
||||
|
||||
@ -0,0 +1,220 @@
|
||||
# US-MAI009-004: Gestionar conciliación y pagos
|
||||
|
||||
**ID:** US-MAI009-004
|
||||
**Módulo:** MAI-009 (Facturación Transporte)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** encargado de cobranza
|
||||
**Quiero** registrar los pagos recibidos y conciliar facturas
|
||||
**Para** mantener actualizado el estado de la cartera y detectar diferencias
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Registrar pago total
|
||||
**Dado** que recibí un pago que cubre el total de la factura
|
||||
**Cuando** registro el pago
|
||||
**Entonces** la factura se marca como PAGADA y el saldo queda en 0
|
||||
|
||||
### CA-002: Registrar pago parcial
|
||||
**Dado** que recibí un pago menor al saldo
|
||||
**Cuando** registro el pago parcial
|
||||
**Entonces** la factura se marca como PARCIAL y se actualiza el saldo pendiente
|
||||
|
||||
### CA-003: Pagos múltiples por factura
|
||||
**Dado** que una factura tiene saldo pendiente
|
||||
**Cuando** registro nuevos pagos
|
||||
**Entonces** se acumulan hasta liquidar el total
|
||||
|
||||
### CA-004: Comparar cotizado vs facturado
|
||||
**Dado** que quiero conciliar
|
||||
**Cuando** consulto una factura
|
||||
**Entonces** veo comparativo de: monto cotizado, monto facturado, diferencia
|
||||
|
||||
### CA-005: Generar nota de crédito/débito
|
||||
**Dado** que hay diferencias que ajustar
|
||||
**Cuando** genero una nota
|
||||
**Entonces** se crea el documento fiscal correspondiente
|
||||
|
||||
### CA-006: Dashboard de conciliación
|
||||
**Dado** que quiero ver el resumen
|
||||
**Cuando** accedo al dashboard
|
||||
**Entonces** veo: facturas con diferencias, notas pendientes, montos por conciliar
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ REGISTRAR PAGO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Factura: A-00456 │
|
||||
│ Cliente: Distribuidora ABC S.A. de C.V. │
|
||||
│ Total factura: $55,338.96 MXN │
|
||||
│ Pagos anteriores: $0.00 │
|
||||
│ Saldo pendiente: $55,338.96 MXN │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DATOS DEL PAGO │
|
||||
│ │
|
||||
│ Fecha de pago: [2026-01-30] │
|
||||
│ Monto: [$55,338.96] [☑ Pago total] │
|
||||
│ │
|
||||
│ Forma de pago: [03 - Transferencia electrónica ▼] │
|
||||
│ Banco: [BBVA ▼] │
|
||||
│ Referencia: [REF-2026-01-30-001 ] │
|
||||
│ │
|
||||
│ Comprobante: [📎 Seleccionar archivo] │
|
||||
│ │
|
||||
│ Notas: │
|
||||
│ [Transferencia recibida a las 14:30 ]│
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ Total factura: $55,338.96 │
|
||||
│ Pago a registrar: -$55,338.96 │
|
||||
│ Nuevo saldo: $0.00 ✓ │
|
||||
│ │
|
||||
│ [Cancelar] [Registrar Pago] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Historial de Pagos
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ HISTORIAL DE PAGOS - Factura A-00456 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Total factura: $55,338.96 | Pagado: $55,338.96 | Saldo: $0.00 │
|
||||
│ Estado: ✅ PAGADA │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ | Fecha | Monto | Forma | Referencia | │
|
||||
│ |------------|------------|--------------|---------------| │
|
||||
│ | 30-ene-26 | $55,338.96 | Transferencia| REF-2026-001 | │
|
||||
│ | | | BBVA | [Ver comp.] | │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ [Exportar historial] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conciliación
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CONCILIACIÓN │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Periodo: [Enero 2026 ▼] Cliente: [Todos ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||||
│ │ $1.2M │ │ $1.18M │ │ $1.1M │ │ $80K │ │
|
||||
│ │ Cotizado │ │ Facturado │ │ Cobrado │ │ Pendiente │ │
|
||||
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ FACTURAS CON DIFERENCIAS │
|
||||
│ │
|
||||
│ | Factura | Cliente | Cotizado | Facturado | Dif | │
|
||||
│ |---------|-------------|------------|------------|--------| │
|
||||
│ | A-00445 | Comercial X | $45,000.00 | $43,500.00 | -$1,500| │
|
||||
│ | | | Recargo no aplicado | [Ver] | │
|
||||
│ |---------|-------------|------------|------------|--------| │
|
||||
│ | A-00448 | Mayorista Y | $28,000.00 | $29,400.00 | +$1,400| │
|
||||
│ | | | Detention agregado | [Ver] | │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ NOTAS PENDIENTES DE EMITIR │
|
||||
│ │
|
||||
│ | Tipo | Factura | Monto | Motivo | Acción | │
|
||||
│ |---------|---------|----------|------------------|--------| │
|
||||
│ | Crédito | A-00445 | $1,500 | Recargo omitido | [Emitir]| │
|
||||
│ │
|
||||
│ [Exportar reporte] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Nota de Crédito
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EMITIR NOTA DE CRÉDITO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Factura relacionada: A-00445 │
|
||||
│ Cliente: Comercial XYZ S.A. de C.V. │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TIPO DE NOTA │
|
||||
│ (●) Nota de crédito (a favor del cliente) │
|
||||
│ ( ) Nota de débito (a cargo del cliente) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CONCEPTOS │
|
||||
│ │
|
||||
│ Descripción: [Ajuste por recargo no aplicado en factura orig.]│
|
||||
│ Monto: [$1,500.00] │
|
||||
│ IVA: ☑ Incluir IVA ($240.00) │
|
||||
│ Total nota: $1,740.00 │
|
||||
│ │
|
||||
│ Motivo: [Descuento por error en cálculo ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ [Cancelar] [Generar y Timbrar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `billing.pagos_factura` para registro de pagos
|
||||
- Tabla: `billing.notas_credito_debito` para notas
|
||||
- Vista: `v_conciliacion_facturas` para comparativo
|
||||
- Complemento de pago (CFDI 4.0) si método es PPD
|
||||
- Integración opcional con bancos para conciliación automática
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Registro de pagos totales y parciales
|
||||
- [ ] Historial de pagos por factura
|
||||
- [ ] Actualización de estado de factura
|
||||
- [ ] Comparativo cotizado vs facturado
|
||||
- [ ] Generación de notas de crédito/débito
|
||||
- [ ] Dashboard de conciliación
|
||||
- [ ] Tests de registro de pagos
|
||||
|
||||
@ -0,0 +1,229 @@
|
||||
# US-MAI009-005: Generar estados de cuenta
|
||||
|
||||
**ID:** US-MAI009-005
|
||||
**Módulo:** MAI-009 (Facturación Transporte)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** encargado de cobranza
|
||||
**Quiero** generar estados de cuenta con análisis de antigüedad de saldos
|
||||
**Para** dar seguimiento a la cartera y comunicar claramente los adeudos a los clientes
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Estado de cuenta por cliente
|
||||
**Dado** que selecciono un cliente y periodo
|
||||
**Cuando** genero el estado de cuenta
|
||||
**Entonces** muestra: facturas emitidas, notas, pagos recibidos, saldo actual
|
||||
|
||||
### CA-002: Análisis de aging
|
||||
**Dado** que hay facturas pendientes
|
||||
**Cuando** consulto el aging
|
||||
**Entonces** veo clasificación: corriente, 30, 60, 90, +90 días
|
||||
|
||||
### CA-003: Alertas de vencimiento
|
||||
**Dado** que hay facturas próximas a vencer
|
||||
**Cuando** consulto la cartera
|
||||
**Entonces** veo alertas con días para vencimiento
|
||||
|
||||
### CA-004: Exportar PDF y Excel
|
||||
**Dado** que necesito enviar el estado de cuenta
|
||||
**Cuando** exporto
|
||||
**Entonces** puedo descargar en formato PDF o Excel
|
||||
|
||||
### CA-005: Envío automático
|
||||
**Dado** que tengo configuración de envío periódico
|
||||
**Cuando** llega la fecha programada
|
||||
**Entonces** el sistema envía automáticamente el estado de cuenta por email
|
||||
|
||||
### CA-006: Dashboard de cartera
|
||||
**Dado** que quiero visión general
|
||||
**Cuando** accedo al dashboard
|
||||
**Entonces** veo: total por cobrar, aging consolidado, top deudores
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ESTADO DE CUENTA │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Cliente: [Distribuidora ABC ▼] │
|
||||
│ Periodo: [Todo el histórico ▼] │
|
||||
│ Al día: [27-ene-2026] [Generar] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ESTADO DE CUENTA │ │
|
||||
│ │ │ │
|
||||
│ │ Distribuidora ABC S.A. de C.V. │ │
|
||||
│ │ RFC: DAB850101XXX │ │
|
||||
│ │ Al 27 de enero de 2026 │ │
|
||||
│ │ │ │
|
||||
│ │ ───────────────────────────────────────────────────── │ │
|
||||
│ │ │ │
|
||||
│ │ MOVIMIENTOS │ │
|
||||
│ │ │ │
|
||||
│ │ | Fecha | Documento | Concepto | Cargo | Abono | Saldo |│
|
||||
│ │ |--------|-----------|------------------|----------|---------|----------|│
|
||||
│ │ | 05-ene | A-00420 | Fact. transporte | $32,500 | | $32,500 |│
|
||||
│ │ | 10-ene | | Pago BBVA ref123 | | $32,500 | $0 |│
|
||||
│ │ | 15-ene | A-00435 | Fact. transporte | $45,200 | | $45,200 |│
|
||||
│ │ | 20-ene | A-00456 | Fact. transporte | $55,338 | | $100,538 |│
|
||||
│ │ | 25-ene | NC-00012 | Nota crédito | | $1,740 | $98,798 |│
|
||||
│ │ │ │
|
||||
│ │ ───────────────────────────────────────────────────── │ │
|
||||
│ │ │ │
|
||||
│ │ SALDO ACTUAL: $98,798.96 MXN │ │
|
||||
│ │ │ │
|
||||
│ │ ───────────────────────────────────────────────────── │ │
|
||||
│ │ │ │
|
||||
│ │ ANÁLISIS DE ANTIGÜEDAD │ │
|
||||
│ │ │ │
|
||||
│ │ | Rango | Monto | % | │ │
|
||||
│ │ |-----------|------------|------| │ │
|
||||
│ │ | Corriente | $55,338.96 | 56% | ████████████ │ │
|
||||
│ │ | 1-30 días | $43,460.00 | 44% | █████████ │ │
|
||||
│ │ | 31-60 días| $0.00 | 0% | │ │
|
||||
│ │ | 61-90 días| $0.00 | 0% | │ │
|
||||
│ │ | +90 días | $0.00 | 0% | │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Descargar PDF] [Descargar Excel] [Enviar por email] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dashboard de Cartera
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CARTERA Y COBRANZA │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Periodo: [Enero 2026 ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN GENERAL │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ $2.5M │ │ $1.8M │ │ $700K │ │
|
||||
│ │ Facturado │ │ Cobrado │ │ Por cobrar │ │
|
||||
│ │ este mes │ │ este mes │ │ total │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ AGING DE CARTERA │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||||
│ │ Corriente ████████████████████████████ $420K (60%) │ │
|
||||
│ │ 1-30 días ████████████████ $180K (26%) │ │
|
||||
│ │ 31-60 días █████ $60K (9%) │ │
|
||||
│ │ 61-90 días ██ $25K (4%) │ │
|
||||
│ │ +90 días █ $15K (2%) │ │
|
||||
│ └───────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TOP 5 DEUDORES │
|
||||
│ │
|
||||
│ | # | Cliente | Saldo | Días prom | Acción |│
|
||||
│ |---|----------------------|------------|-----------|--------|│
|
||||
│ | 1 | Distribuidora ABC | $98,798 | 12 días | [Ver] |│
|
||||
│ | 2 | Comercial XYZ | $85,450 | 25 días | [Ver] |│
|
||||
│ | 3 | Mayorista 123 | $72,300 | 8 días | [Ver] |│
|
||||
│ | 4 | Retail Partners | $65,000 | 45 días | [Ver] |│
|
||||
│ | 5 | Logística Norte | $58,200 | 32 días | [Ver] |│
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ FACTURAS PRÓXIMAS A VENCER (7 días) │
|
||||
│ │
|
||||
│ | Factura | Cliente | Vence | Monto | Días | │
|
||||
│ |---------|-----------------|------------|----------|------| │
|
||||
│ | A-00435 | Distrib. ABC | 28-ene-26 | $45,200 | 1 | │
|
||||
│ | A-00438 | Comercial XYZ | 30-ene-26 | $32,800 | 3 | │
|
||||
│ | A-00442 | Mayorista 123 | 02-feb-26 | $28,500 | 6 | │
|
||||
│ │
|
||||
│ [Enviar recordatorios masivos] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuración de Envío Automático
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CONFIGURAR ENVÍO AUTOMÁTICO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Cliente: Distribuidora ABC S.A. de C.V. │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ESTADO DE CUENTA PERIÓDICO │
|
||||
│ │
|
||||
│ ☑ Habilitar envío automático │
|
||||
│ │
|
||||
│ Frecuencia: [Quincenal ▼] │
|
||||
│ ○ Semanal (cada lunes) │
|
||||
│ ○ Quincenal (días 1 y 15) │
|
||||
│ ○ Mensual (primer día del mes) │
|
||||
│ │
|
||||
│ Destinatarios: │
|
||||
│ [cobranza@distribuidoraabc.com ]│
|
||||
│ [finanzas@distribuidoraabc.com ]│
|
||||
│ [+ Agregar destinatario] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RECORDATORIOS DE VENCIMIENTO │
|
||||
│ │
|
||||
│ ☑ Enviar recordatorio [3] días antes del vencimiento │
|
||||
│ ☑ Enviar recordatorio el día del vencimiento │
|
||||
│ ☑ Enviar recordatorio [7] días después de vencida │
|
||||
│ │
|
||||
│ [Cancelar] [Guardar configuración]│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Vista: `v_estado_cuenta_cliente` para movimientos
|
||||
- Vista: `v_aging_cartera` para análisis de antigüedad
|
||||
- Job programado para envío automático de estados de cuenta
|
||||
- Templates de email configurables por tenant
|
||||
- Exportación PDF con template HTML + puppeteer
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Estado de cuenta por cliente y periodo
|
||||
- [ ] Análisis de aging (corriente a +90 días)
|
||||
- [ ] Dashboard de cartera consolidado
|
||||
- [ ] Top deudores
|
||||
- [ ] Alertas de vencimiento próximo
|
||||
- [ ] Exportación PDF y Excel
|
||||
- [ ] Envío automático programado
|
||||
- [ ] Tests de generación de reportes
|
||||
|
||||
205
docs/02-definicion-modulos/MAI-010-liquidaciones/README.md
Normal file
205
docs/02-definicion-modulos/MAI-010-liquidaciones/README.md
Normal file
@ -0,0 +1,205 @@
|
||||
# MAI-010: Liquidaciones a Operadores
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Estado:** Diseño
|
||||
**Prioridad:** P1 (Crítico - Pago a operadores)
|
||||
|
||||
---
|
||||
|
||||
## Descripción General
|
||||
|
||||
El módulo de Liquidaciones es responsable de calcular y gestionar los pagos a operadores (conductores) propios o terceros, incluyendo viáticos, bonos y deducciones.
|
||||
|
||||
**Problema que resuelve:**
|
||||
- Cálculos manuales de pago propensos a errores
|
||||
- Viáticos sin control ni comprobación
|
||||
- Deducciones aplicadas inconsistentemente
|
||||
- Falta de trazabilidad viaje → pago
|
||||
- Retrasos en liquidación que afectan relación con operadores
|
||||
|
||||
---
|
||||
|
||||
## Objetivos del Módulo
|
||||
|
||||
1. **Esquemas de pago flexibles:** Por km, por viaje, por porcentaje, por bono
|
||||
2. **Control de viáticos:** Anticipos, comprobación, sobrantes
|
||||
3. **Deducciones documentadas:** Multas, daños, faltantes con aprobación
|
||||
4. **Corte periódico:** Semanal, quincenal con exportación a nómina
|
||||
5. **Trazabilidad completa:** Cada concepto ligado a viaje específico
|
||||
|
||||
---
|
||||
|
||||
## Alcance Funcional
|
||||
|
||||
### Incluido
|
||||
|
||||
- Configuración de esquemas de pago por operador
|
||||
- Cálculo automático de monto por viaje
|
||||
- Gestión de viáticos (anticipos y comprobación)
|
||||
- Registro de deducciones con aprobación
|
||||
- Bonos por cumplimiento de SLA
|
||||
- Corte y autorización de liquidaciones
|
||||
- Exportación a nómina/contabilidad
|
||||
|
||||
### Excluido
|
||||
|
||||
- Nómina completa (IMSS, ISR, prestaciones)
|
||||
- Contratos laborales
|
||||
- Reclutamiento de operadores
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el módulo |
|
||||
|-------|------------------|
|
||||
| Operador | Consulta sus viajes y pagos |
|
||||
| Liquidador | Calcula y procesa liquidaciones |
|
||||
| Supervisor | Aprueba deducciones y bonos |
|
||||
| Contador | Exporta a nómina, concilia |
|
||||
| Sistema | Calcula montos automáticamente |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
VIAJES CERRADOS (con POD)
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. CALCULAR PAGO POR VIAJE │
|
||||
│ - Según esquema del operador │
|
||||
│ - Por km, por viaje, % del flete │
|
||||
│ - Aplicar bonos si cumplió SLA │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 2. REGISTRAR VIÁTICOS │
|
||||
│ - Anticipos entregados │
|
||||
│ - Comprobación de gastos │
|
||||
│ - Sobrantes a descontar │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 3. APLICAR DEDUCCIONES │
|
||||
│ - Multas de tránsito │
|
||||
│ - Daños a unidad/carga │
|
||||
│ - Faltantes de mercancía │
|
||||
│ - Con aprobación de supervisor │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 4. GENERAR LIQUIDACIÓN │
|
||||
│ - Acumular por periodo (semana) │
|
||||
│ - Desglose de conceptos │
|
||||
│ - Total a pagar │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 5. AUTORIZAR Y EXPORTAR │
|
||||
│ - Revisión por supervisor │
|
||||
│ - Firma del operador │
|
||||
│ - Exportar a nómina │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ LIQUIDACIÓN PAGADA │
|
||||
│ → Registrada en contabilidad │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Datos del Módulo
|
||||
|
||||
### Entidades Principales
|
||||
|
||||
| Entidad | Descripción | Estado |
|
||||
|---------|-------------|--------|
|
||||
| EsquemaPago | Configuración de pago por operador | NO IMPLEMENTADA |
|
||||
| ConceptoLiquidacion | Líneas de la liquidación | NO IMPLEMENTADA |
|
||||
| Liquidacion | Documento de pago | NO IMPLEMENTADA |
|
||||
| Viatico | Anticipo y comprobación | NO IMPLEMENTADA |
|
||||
| Deduccion | Descuentos aplicados | NO IMPLEMENTADA |
|
||||
|
||||
### Campos Clave Liquidación
|
||||
|
||||
| Campo | Tipo | Obligatorio | Descripción |
|
||||
|-------|------|-------------|-------------|
|
||||
| operador_id | UUID | Sí | Operador |
|
||||
| periodo_inicio | DATE | Sí | Inicio del periodo |
|
||||
| periodo_fin | DATE | Sí | Fin del periodo |
|
||||
| total_viajes | DECIMAL | Sí | Suma de pagos por viaje |
|
||||
| total_viaticos | DECIMAL | Sí | Viáticos netos |
|
||||
| total_deducciones | DECIMAL | Sí | Deducciones aplicadas |
|
||||
| total_bonos | DECIMAL | Sí | Bonos ganados |
|
||||
| total_pagar | DECIMAL | Sí | Neto a pagar |
|
||||
| estado | ENUM | Sí | BORRADOR, PENDIENTE, AUTORIZADA, PAGADA |
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md)
|
||||
|
||||
---
|
||||
|
||||
## Esquemas de Pago
|
||||
|
||||
| Tipo | Descripción | Ejemplo |
|
||||
|------|-------------|---------|
|
||||
| Por km | Pago por kilómetro recorrido | $2.50/km |
|
||||
| Por viaje | Monto fijo por viaje | $1,500/viaje |
|
||||
| Porcentaje | % del flete cobrado | 25% del flete |
|
||||
| Por bono | Adicional por cumplimiento | $500 si OTIF |
|
||||
| Mixto | Combinación | Base + km + bono |
|
||||
|
||||
---
|
||||
|
||||
## Métricas del Módulo
|
||||
|
||||
| KPI | Fórmula | Meta |
|
||||
|-----|---------|------|
|
||||
| Tiempo de liquidación | Avg(fecha_pago - fecha_cierre) | <5 días |
|
||||
| Precisión de cálculo | % liquidaciones sin ajuste | >98% |
|
||||
| Viáticos comprobados | % viáticos con recibos | >90% |
|
||||
| Deducciones aprobadas | % deducciones con autorización | 100% |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Este módulo depende de:
|
||||
- MAI-007 (POD): Viajes cerrados
|
||||
- MAI-006 (Tracking): Kilometraje real
|
||||
- MAI-011 (Flota): Datos de operadores
|
||||
- MAI-002 (Tarifas): Flete para % de pago
|
||||
|
||||
### Otros módulos dependen de este:
|
||||
- erp-core/financial: Exportación a contabilidad
|
||||
- erp-core/nomina: Integración con nómina
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
Ver carpeta: [historias-usuario/](./historias-usuario/)
|
||||
|
||||
| US | Título | Prioridad |
|
||||
|----|--------|-----------|
|
||||
| US-MAI010-001 | Configurar esquema de pago | Alta |
|
||||
| US-MAI010-002 | Calcular pago por viaje | Alta |
|
||||
| US-MAI010-003 | Gestionar viáticos | Alta |
|
||||
| US-MAI010-004 | Aplicar deducciones | Media |
|
||||
| US-MAI010-005 | Generar y autorizar liquidación | Alta |
|
||||
|
||||
---
|
||||
|
||||
*Módulo MAI-010 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,210 @@
|
||||
# REQUERIMIENTOS.md - MAI-010: Liquidaciones a Operadores
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.9
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.9.1: Esquemas de Pago
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir configurar diferentes esquemas de pago para operadores: por km, por viaje, por porcentaje del flete, por bono SLA.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Configurar esquema por operador individual
|
||||
2. Esquemas predefinidos reutilizables
|
||||
3. Pago por km con tarifa configurable
|
||||
4. Pago fijo por viaje
|
||||
5. Pago como % del flete cobrado al cliente
|
||||
6. Bonos por cumplimiento de SLA (on-time delivery)
|
||||
7. Combinación de esquemas (base + variable)
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `settlements.esquemas_pago`
|
||||
- Tabla: `settlements.esquema_operador`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/esquemas-pago` - Listar esquemas
|
||||
- `POST /api/v1/esquemas-pago` - Crear esquema
|
||||
- `PUT /api/v1/operadores/:id/esquema-pago` - Asignar a operador
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.9.2: Viáticos
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe gestionar anticipos de viáticos, comprobación de gastos y control de sobrantes.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Registrar anticipo de viático por viaje
|
||||
2. Comprobación de gastos con recibos/tickets
|
||||
3. Clasificación de gastos: combustible, casetas, comidas, hospedaje
|
||||
4. Cálculo de sobrante (anticipo - comprobado)
|
||||
5. Sobrante se descuenta en liquidación
|
||||
6. Alertas por viáticos sin comprobar
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `settlements.viaticos`
|
||||
- Tabla: `settlements.comprobantes_viatico`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/viajes/:id/viatico` - Registrar anticipo
|
||||
- `POST /api/v1/viaticos/:id/comprobantes` - Agregar comprobante
|
||||
- `GET /api/v1/operadores/:id/viaticos-pendientes` - Viáticos sin comprobar
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.9.3: Deducciones
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir registrar deducciones por multas, daños, faltantes según política, con aprobación.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Catálogo de tipos de deducción
|
||||
2. Registrar deducción vinculada a viaje/incidencia
|
||||
3. Monto puede ser fijo o % del daño
|
||||
4. Requiere aprobación de supervisor
|
||||
5. Plan de pagos para montos grandes (descuento parcial)
|
||||
6. Historial de deducciones por operador
|
||||
7. Límite máximo de deducción por periodo (política)
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `settlements.deducciones`
|
||||
- Tabla: `settlements.tipos_deduccion`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/deducciones` - Registrar deducción
|
||||
- `POST /api/v1/deducciones/:id/aprobar` - Aprobar deducción
|
||||
- `GET /api/v1/operadores/:id/deducciones` - Historial
|
||||
|
||||
**Prioridad:** Media
|
||||
|
||||
---
|
||||
|
||||
### RF-4.9.4: Corte y Autorización
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe generar liquidaciones con corte semanal/quincenal, autorización de supervisor y exportación a nómina/contabilidad.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Configurar periodo de corte (semanal, quincenal)
|
||||
2. Generar liquidación con todos los conceptos
|
||||
3. Desglose: viajes, viáticos, deducciones, bonos
|
||||
4. Revisión y autorización de supervisor
|
||||
5. Firma digital o aceptación del operador
|
||||
6. Exportación a formato de nómina
|
||||
7. Integración con contabilidad para pólizas
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `settlements.liquidaciones`
|
||||
- Tabla: `settlements.conceptos_liquidacion`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/liquidaciones/generar` - Generar corte
|
||||
- `POST /api/v1/liquidaciones/:id/autorizar` - Autorizar
|
||||
- `GET /api/v1/liquidaciones/:id/exportar` - Exportar a nómina
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.9.5: Cálculo Automático de Pago por Viaje
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe calcular automáticamente el monto a pagar por cada viaje según el esquema del operador.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Calcular al cerrar viaje (POD completado)
|
||||
2. Aplicar esquema del operador asignado
|
||||
3. Considerar km reales si aplica (desde tracking)
|
||||
4. Considerar flete real si es % del flete
|
||||
5. Aplicar bono si cumplió SLA
|
||||
6. Registrar desglose del cálculo
|
||||
7. Ajuste manual con justificación
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `settlements.pagos_viaje`
|
||||
- Vista: `v_viajes_por_liquidar`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/viajes/:id/calcular-pago` - Calcular pago
|
||||
- `PUT /api/v1/pagos-viaje/:id` - Ajustar pago
|
||||
- `GET /api/v1/operadores/:id/viajes-pendientes` - Por liquidar
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.9.6: Bonos por Desempeño
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe calcular y aplicar bonos por cumplimiento de indicadores.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Configurar bonos: on-time delivery, sin incidencias, combustible eficiente
|
||||
2. Calcular automáticamente si cumple condiciones
|
||||
3. Bono por viaje o por periodo
|
||||
4. Desglose de bonos en liquidación
|
||||
5. Histórico de bonos ganados
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `settlements.bonos`
|
||||
- Tabla: `settlements.tipos_bono`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/operadores/:id/bonos` - Bonos ganados
|
||||
- `POST /api/v1/bonos` - Registrar bono manual
|
||||
|
||||
**Prioridad:** Media
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Precisión de Cálculo
|
||||
Los cálculos de liquidación deben tener precisión de 2 decimales sin errores de redondeo.
|
||||
|
||||
### RNF-002: Auditoría
|
||||
Todos los ajustes manuales deben registrarse con usuario, fecha y justificación.
|
||||
|
||||
### RNF-003: Confidencialidad
|
||||
Las liquidaciones solo deben ser visibles para el operador correspondiente y personal autorizado.
|
||||
|
||||
### RNF-004: Exportación
|
||||
La exportación a nómina debe completarse en menos de 30 segundos para 100 operadores.
|
||||
|
||||
---
|
||||
|
||||
## Validaciones de Negocio
|
||||
|
||||
| Validación | Descripción | Acción si falla |
|
||||
|------------|-------------|-----------------|
|
||||
| LIQ_001 | Viaje con POD para calcular pago | Bloquear cálculo |
|
||||
| LIQ_002 | Deducción requiere aprobación | Pendiente hasta aprobar |
|
||||
| LIQ_003 | Deducción no excede límite periodo | Alertar, requiere override |
|
||||
| LIQ_004 | Viático comprobado antes de liquidar | Alertar, permitir continuar |
|
||||
| LIQ_005 | Operador sin bloqueo | Alertar si operador bloqueado |
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tabla DDL | Entity | Endpoint | US |
|
||||
|----|-----------|--------|----------|---|
|
||||
| RF-4.9.1 | esquemas_pago | EsquemaPago | /esquemas-pago | US-MAI010-001 |
|
||||
| RF-4.9.2 | viaticos | Viatico | /viaticos | US-MAI010-003 |
|
||||
| RF-4.9.3 | deducciones | Deduccion | /deducciones | US-MAI010-004 |
|
||||
| RF-4.9.4 | liquidaciones | Liquidacion | /liquidaciones | US-MAI010-005 |
|
||||
| RF-4.9.5 | pagos_viaje | PagoViaje | /viajes/:id/pago | US-MAI010-002 |
|
||||
| RF-4.9.6 | bonos | Bono | /bonos | US-MAI010-002 |
|
||||
|
||||
---
|
||||
|
||||
*MAI-010 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,233 @@
|
||||
# RESUMEN-EPICA.md - MAI-010: Liquidaciones a Operadores
|
||||
|
||||
**Código:** MAI-010
|
||||
**Nombre:** Liquidaciones a Operadores
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema
|
||||
|
||||
Las empresas transportistas enfrentan problemas con:
|
||||
- Pagos incorrectos a operadores (errores de cálculo)
|
||||
- Viáticos sin control que generan pérdidas
|
||||
- Deducciones no aplicadas o aplicadas sin documentar
|
||||
- Liquidaciones tardías que afectan retención de operadores
|
||||
- Falta de visibilidad del operador sobre sus ingresos
|
||||
|
||||
### Solución
|
||||
|
||||
Un módulo de liquidaciones que:
|
||||
- Calcula automáticamente el pago según esquema configurado
|
||||
- Controla viáticos con anticipos y comprobación
|
||||
- Aplica deducciones con aprobación y documentación
|
||||
- Genera liquidaciones periódicas con desglose claro
|
||||
- Da visibilidad al operador de sus pagos pendientes
|
||||
|
||||
### Beneficios Esperados
|
||||
|
||||
| Beneficio | Métrica | Impacto |
|
||||
|-----------|---------|---------|
|
||||
| Precisión en pagos | -95% errores de cálculo | Confianza operador |
|
||||
| Control de viáticos | +30% viáticos comprobados | Reducción pérdidas |
|
||||
| Rapidez liquidación | -60% tiempo de proceso | Satisfacción operador |
|
||||
| Retención operadores | -20% rotación | Estabilidad operativa |
|
||||
|
||||
---
|
||||
|
||||
## Actores y Stakeholders
|
||||
|
||||
### Usuarios Primarios
|
||||
|
||||
| Actor | Responsabilidad | Frecuencia |
|
||||
|-------|-----------------|------------|
|
||||
| Liquidador | Procesa y genera liquidaciones | Semanal |
|
||||
| Supervisor | Aprueba deducciones y liquidaciones | Semanal |
|
||||
| Operador | Consulta sus pagos | Diaria |
|
||||
|
||||
### Usuarios Secundarios
|
||||
|
||||
| Actor | Interés |
|
||||
|-------|---------|
|
||||
| Contador | Exporta a nómina, genera pólizas |
|
||||
| Gerente Operaciones | Reportes de costos por operador |
|
||||
| RRHH | Datos para expediente laboral |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VIAJE CERRADO (con POD) │
|
||||
│ (Listo para liquidar desde MAI-007) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. CÁLCULO DE PAGO POR VIAJE (Automático) │
|
||||
│ │
|
||||
│ Viaje: VJE-0125 | Operador: Juan Pérez │
|
||||
│ Esquema: Por km ($2.50/km) + Bono OTIF ($500) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Km recorridos (tracking): 540 km │ │
|
||||
│ │ Pago por km: $1,350.00 │ │
|
||||
│ │ Bono OTIF (entregó a tiempo): $500.00 │ │
|
||||
│ │ ───────────────────────────────────────── │ │
|
||||
│ │ Total viaje: $1,850.00 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. VIÁTICOS DEL VIAJE │
|
||||
│ │
|
||||
│ Anticipo entregado: $2,000.00 │
|
||||
│ │
|
||||
│ Comprobación: │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Combustible (ticket): $1,200.00 ✓ │ │
|
||||
│ │ Casetas (TAG): $450.00 ✓ │ │
|
||||
│ │ Comida (tickets): $180.00 ✓ │ │
|
||||
│ │ ───────────────────────────────────────── │ │
|
||||
│ │ Total comprobado: $1,830.00 │ │
|
||||
│ │ Sobrante a descontar: $170.00 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. DEDUCCIONES (Si aplican) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Multa de tránsito (VJE-0120): $500.00 │ │
|
||||
│ │ Motivo: Exceso de velocidad en Qro │ │
|
||||
│ │ Evidencia: Foto de infracción │ │
|
||||
│ │ Estado: ✓ Aprobado por supervisor │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. LIQUIDACIÓN SEMANAL │
|
||||
│ │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ Periodo: 20-ene-2026 al 26-ene-2026 │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ PERCEPCIONES │ │
|
||||
│ │ Viaje VJE-0120 (CDMX→GDL): $1,750.00 │ │
|
||||
│ │ Viaje VJE-0125 (CDMX→MTY): $1,850.00 │ │
|
||||
│ │ Viaje VJE-0128 (CDMX→GDL): $1,750.00 │ │
|
||||
│ │ Bono asistencia perfecta: $300.00 │ │
|
||||
│ │ ───────────────────────────────────────────── │ │
|
||||
│ │ Subtotal percepciones: $5,650.00 │ │
|
||||
│ │ │ │
|
||||
│ │ DEDUCCIONES │ │
|
||||
│ │ Sobrante viático VJE-0125: -$170.00 │ │
|
||||
│ │ Multa tránsito VJE-0120: -$500.00 │ │
|
||||
│ │ ───────────────────────────────────────────── │ │
|
||||
│ │ Subtotal deducciones: -$670.00 │ │
|
||||
│ │ │ │
|
||||
│ │ ═══════════════════════════════════════════════ │ │
|
||||
│ │ NETO A PAGAR: $4,980.00 MXN │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Estado: PENDIENTE DE AUTORIZACIÓN │
|
||||
│ │
|
||||
│ [Autorizar] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 5. AUTORIZACIÓN Y EXPORTACIÓN │
|
||||
│ │
|
||||
│ ✓ Autorizado por: María González (Supervisor) │
|
||||
│ ✓ Aceptado por operador: Juan Pérez (firma digital) │
|
||||
│ │
|
||||
│ [Exportar a nómina] [Generar póliza contable] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LIQUIDACIÓN PAGADA │
|
||||
│ → Exportada a nómina │
|
||||
│ → Póliza contable generada │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Éxito
|
||||
|
||||
### Funcionales
|
||||
|
||||
- [ ] Configuración de esquemas de pago
|
||||
- [ ] Cálculo automático por viaje
|
||||
- [ ] Gestión de viáticos con comprobación
|
||||
- [ ] Deducciones con aprobación
|
||||
- [ ] Generación de liquidación periódica
|
||||
- [ ] Exportación a nómina
|
||||
|
||||
### Técnicos
|
||||
|
||||
- [ ] Cálculos precisos (2 decimales)
|
||||
- [ ] Auditoría de ajustes
|
||||
- [ ] Portal operador con sus pagos
|
||||
- [ ] Exportación <30 seg para 100 operadores
|
||||
|
||||
### Negocio
|
||||
|
||||
- [ ] <5 días entre cierre y pago
|
||||
- [ ] >98% liquidaciones sin ajuste
|
||||
- [ ] >90% viáticos comprobados
|
||||
- [ ] 100% deducciones aprobadas
|
||||
|
||||
---
|
||||
|
||||
## Riesgos y Mitigaciones
|
||||
|
||||
| Riesgo | Probabilidad | Impacto | Mitigación |
|
||||
|--------|--------------|---------|------------|
|
||||
| Cálculo incorrecto | Media | Alto | Validación doble, auditoría |
|
||||
| Viáticos sin comprobar | Alta | Medio | Alertas, bloqueo de anticipo |
|
||||
| Deducciones impugnadas | Media | Medio | Evidencia obligatoria |
|
||||
| Retraso en liquidación | Media | Alto | Automatización, alertas |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Prerequisitos
|
||||
- MAI-007 (POD): Viajes cerrados
|
||||
- MAI-006 (Tracking): Kilometraje real
|
||||
- MAI-011 (Flota): Datos de operadores
|
||||
|
||||
### Habilita
|
||||
- erp-core/financial: Pólizas contables
|
||||
- erp-core/nomina: Integración nómina
|
||||
|
||||
---
|
||||
|
||||
## Story Points Estimados
|
||||
|
||||
| Historia | Complejidad | SP |
|
||||
|----------|-------------|---|
|
||||
| US-MAI010-001 | Media | 5 |
|
||||
| US-MAI010-002 | Alta | 8 |
|
||||
| US-MAI010-003 | Media | 5 |
|
||||
| US-MAI010-004 | Media | 5 |
|
||||
| US-MAI010-005 | Alta | 8 |
|
||||
| **Total** | | **31** |
|
||||
|
||||
---
|
||||
|
||||
*Épica MAI-010 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,211 @@
|
||||
# US-MAI010-001: Configurar esquema de pago
|
||||
|
||||
**ID:** US-MAI010-001
|
||||
**Módulo:** MAI-010 (Liquidaciones)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** administrador de operaciones
|
||||
**Quiero** configurar diferentes esquemas de pago para los operadores
|
||||
**Para** tener flexibilidad en la compensación según el tipo de servicio y operador
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Crear esquema de pago
|
||||
**Dado** que necesito definir cómo pagar a un operador
|
||||
**Cuando** creo un esquema de pago
|
||||
**Entonces** puedo especificar: tipo (km, viaje, %), montos y condiciones
|
||||
|
||||
### CA-002: Esquema por kilómetro
|
||||
**Dado** que algunos operadores se pagan por km
|
||||
**Cuando** configuro este tipo
|
||||
**Entonces** defino la tarifa por km y el sistema usa km reales del tracking
|
||||
|
||||
### CA-003: Esquema por viaje
|
||||
**Dado** que algunos operadores se pagan monto fijo por viaje
|
||||
**Cuando** configuro este tipo
|
||||
**Entonces** defino el monto fijo que aplica por cada viaje completado
|
||||
|
||||
### CA-004: Esquema por porcentaje
|
||||
**Dado** que algunos operadores se pagan % del flete
|
||||
**Cuando** configuro este tipo
|
||||
**Entonces** defino el porcentaje y se calcula sobre el flete facturado
|
||||
|
||||
### CA-005: Asignar esquema a operador
|
||||
**Dado** que tengo esquemas definidos
|
||||
**Cuando** asigno a un operador
|
||||
**Entonces** sus futuros viajes se calculan con ese esquema
|
||||
|
||||
### CA-006: Esquemas predefinidos
|
||||
**Dado** que hay esquemas comunes
|
||||
**Cuando** necesito asignar rápido
|
||||
**Entonces** puedo elegir de una lista de esquemas predefinidos
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ESQUEMAS DE PAGO [+ Nuevo]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ESQUEMAS DISPONIBLES │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ESQ-001: Operador Estándar │ │
|
||||
│ │ Tipo: Por kilómetro │ │
|
||||
│ │ Tarifa: $2.50/km + Bono OTIF $500 │ │
|
||||
│ │ Operadores asignados: 12 [Editar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ESQ-002: Operador Senior │ │
|
||||
│ │ Tipo: Porcentaje del flete │ │
|
||||
│ │ Tarifa: 25% + Bono OTIF $800 │ │
|
||||
│ │ Operadores asignados: 5 [Editar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ESQ-003: Ruta Local │ │
|
||||
│ │ Tipo: Por viaje fijo │ │
|
||||
│ │ Tarifa: $1,500/viaje │ │
|
||||
│ │ Operadores asignados: 8 [Editar] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Crear Esquema de Pago
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ NUEVO ESQUEMA DE PAGO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ INFORMACIÓN BÁSICA │
|
||||
│ │
|
||||
│ Código: [ESQ-004] │
|
||||
│ Nombre: [Operador Premium ] │
|
||||
│ Descripción: [Esquema para operadores con doble articulado ]│
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TIPO DE CÁLCULO │
|
||||
│ │
|
||||
│ Tipo principal: │
|
||||
│ ( ) Por kilómetro recorrido │
|
||||
│ (●) Porcentaje del flete │
|
||||
│ ( ) Monto fijo por viaje │
|
||||
│ ( ) Mixto (base + variable) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CONFIGURACIÓN DEL PORCENTAJE │
|
||||
│ │
|
||||
│ Porcentaje sobre flete: [30] % │
|
||||
│ Mínimo garantizado: [$1,000.00] (por viaje) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ BONOS ADICIONALES │
|
||||
│ │
|
||||
│ ☑ Bono por entrega a tiempo (OTIF) │
|
||||
│ Monto: [$800.00] │
|
||||
│ │
|
||||
│ ☑ Bono por sin incidencias │
|
||||
│ Monto: [$300.00] │
|
||||
│ │
|
||||
│ ☐ Bono por combustible eficiente │
|
||||
│ Monto: [$______] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CONDICIONES ESPECIALES │
|
||||
│ │
|
||||
│ ☑ Aplica solo para viajes de ruta larga (>300 km) │
|
||||
│ ☐ Aplica solo para ciertos clientes │
|
||||
│ │
|
||||
│ [Cancelar] [Guardar Esquema] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Asignar Esquema a Operador
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ASIGNAR ESQUEMA DE PAGO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ No. Empleado: OP-0025 │
|
||||
│ Antigüedad: 3 años, 5 meses │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ESQUEMA ACTUAL │
|
||||
│ ESQ-001: Operador Estándar ($2.50/km + Bono) │
|
||||
│ Vigente desde: 01-jun-2023 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ NUEVO ESQUEMA │
|
||||
│ │
|
||||
│ Esquema: [ESQ-002: Operador Senior ▼] │
|
||||
│ │
|
||||
│ Resumen del esquema: │
|
||||
│ • Tipo: Porcentaje del flete │
|
||||
│ • Tarifa: 25% del flete │
|
||||
│ • Bono OTIF: $800 │
|
||||
│ • Sin incidencias: $300 │
|
||||
│ │
|
||||
│ Fecha inicio: [01-feb-2026] │
|
||||
│ │
|
||||
│ Motivo del cambio: │
|
||||
│ [Promoción por buen desempeño ]│
|
||||
│ │
|
||||
│ [Cancelar] [Asignar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Esquema
|
||||
|
||||
| Tipo | Descripción | Cálculo |
|
||||
|------|-------------|---------|
|
||||
| Por km | Pago por kilómetro | km_reales × tarifa_km |
|
||||
| Por viaje | Monto fijo | tarifa_viaje |
|
||||
| Porcentaje | % del flete | flete × porcentaje |
|
||||
| Mixto | Base + variable | base + (km × tarifa) |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `settlements.esquemas_pago` para definiciones
|
||||
- Tabla: `settlements.esquema_operador` para asignaciones
|
||||
- El km real se obtiene de `tracking.eventos` (km recorridos)
|
||||
- El flete se obtiene de la tarifa aplicada al viaje (MAI-002)
|
||||
- Histórico de cambios de esquema por operador
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] CRUD de esquemas de pago
|
||||
- [ ] Soporte para los 4 tipos de cálculo
|
||||
- [ ] Configuración de bonos
|
||||
- [ ] Asignación de esquema a operador
|
||||
- [ ] Histórico de cambios de esquema
|
||||
- [ ] Validación de condiciones especiales
|
||||
- [ ] Tests de configuración
|
||||
|
||||
@ -0,0 +1,193 @@
|
||||
# US-MAI010-002: Calcular pago por viaje
|
||||
|
||||
**ID:** US-MAI010-002
|
||||
**Módulo:** MAI-010 (Liquidaciones)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** sistema de liquidaciones
|
||||
**Quiero** calcular automáticamente el monto a pagar por cada viaje cerrado
|
||||
**Para** que el liquidador tenga los montos listos sin cálculos manuales
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Calcular al cerrar viaje
|
||||
**Dado** que un viaje se cierra con POD
|
||||
**Cuando** se confirma el cierre
|
||||
**Entonces** el sistema calcula automáticamente el pago del operador
|
||||
|
||||
### CA-002: Aplicar esquema del operador
|
||||
**Dado** que el operador tiene un esquema asignado
|
||||
**Cuando** se calcula el pago
|
||||
**Entonces** se aplica la fórmula correspondiente (km, %, fijo)
|
||||
|
||||
### CA-003: Usar km reales
|
||||
**Dado** que el esquema es por km
|
||||
**Cuando** se calcula
|
||||
**Entonces** se usan los km reales del tracking, no los estimados
|
||||
|
||||
### CA-004: Calcular bonos automáticamente
|
||||
**Dado** que el viaje cumplió condiciones de bono
|
||||
**Cuando** se calcula el pago
|
||||
**Entonces** se agrega el bono correspondiente (OTIF, sin incidencias)
|
||||
|
||||
### CA-005: Mostrar desglose
|
||||
**Dado** que se calculó el pago
|
||||
**Cuando** consulto el detalle
|
||||
**Entonces** veo el desglose: base, variable, bonos, total
|
||||
|
||||
### CA-006: Ajuste manual
|
||||
**Dado** que hay situaciones excepcionales
|
||||
**Cuando** necesito ajustar el monto
|
||||
**Entonces** puedo hacerlo con justificación obligatoria
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ PAGO CALCULADO - VJE-0125 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0125 | CDMX → Monterrey │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ Esquema: ESQ-002 (25% del flete + bonos) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DATOS DEL VIAJE │
|
||||
│ │
|
||||
│ Fecha cierre: 2026-01-25 16:45 │
|
||||
│ Flete facturado: $18,200.00 MXN │
|
||||
│ Km recorridos (tracking): 892 km │
|
||||
│ Tiempo en ruta: 11 hrs 32 min │
|
||||
│ Entrega: ✓ A tiempo (dentro de ventana SLA) │
|
||||
│ Incidencias: ✓ Sin incidencias │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CÁLCULO DEL PAGO │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ PERCEPCIONES │ │
|
||||
│ │ │ │
|
||||
│ │ Pago por flete (25% de $18,200): $4,550.00 │ │
|
||||
│ │ Bono OTIF (entrega a tiempo): $800.00 │ │
|
||||
│ │ Bono sin incidencias: $300.00 │ │
|
||||
│ │ ───────────────────────────────────────────────── │ │
|
||||
│ │ TOTAL A PAGAR: $5,650.00 MXN │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Estado: ✓ CALCULADO | Pendiente de liquidación │
|
||||
│ │
|
||||
│ [Ajustar monto] [Ver detalles] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Lista de Viajes por Liquidar
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VIAJES PENDIENTES DE LIQUIDAR │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Operador: [Juan Pérez García ▼] │
|
||||
│ Periodo: [20-ene-2026] al [26-ene-2026] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ VIAJES CERRADOS ESTA SEMANA │
|
||||
│ │
|
||||
│ | Viaje | Ruta | Cierre | Pago | Estado |│
|
||||
│ |---------|----------------|----------|-----------|----------|│
|
||||
│ | VJE-0120| CDMX → GDL | 21-ene | $1,750.00 | Calculado|│
|
||||
│ | VJE-0125| CDMX → MTY | 23-ene | $5,650.00 | Calculado|│
|
||||
│ | VJE-0128| CDMX → GDL | 25-ene | $1,750.00 | Calculado|│
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ Total viajes: 3 │
|
||||
│ Total pagos: $9,150.00 │
|
||||
│ │
|
||||
│ [Generar liquidación semanal] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ajuste Manual
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AJUSTAR PAGO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0125 │
|
||||
│ Pago calculado: $5,650.00 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ AJUSTE │
|
||||
│ │
|
||||
│ Nuevo monto: [$5,000.00] │
|
||||
│ Diferencia: -$650.00 │
|
||||
│ │
|
||||
│ Motivo del ajuste (obligatorio): │
|
||||
│ [Viaje solicitó apoyo de otro operador para última ]│
|
||||
│ [hora de entrega. Se comparte pago con OP-0032 ]│
|
||||
│ │
|
||||
│ Autoriza: [Supervisor requerido ▼] │
|
||||
│ │
|
||||
│ ⚠ Los ajustes quedan registrados en auditoría │
|
||||
│ │
|
||||
│ [Cancelar] [Guardar Ajuste] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cálculo por Tipo de Esquema
|
||||
|
||||
| Tipo | Fórmula | Ejemplo |
|
||||
|------|---------|---------|
|
||||
| Por km | km_reales × tarifa_km | 892 × $2.50 = $2,230 |
|
||||
| Por viaje | tarifa_fija | $1,500 |
|
||||
| Porcentaje | flete × % | $18,200 × 25% = $4,550 |
|
||||
| Mixto | base + (km × tarifa) | $500 + (892 × $1.50) = $1,838 |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- El cálculo se dispara al evento `viaje.cerrado` (MAI-007)
|
||||
- Km reales desde `tracking.eventos` (suma de tramos)
|
||||
- Flete desde `billing.lineas_factura` vinculada al viaje
|
||||
- Bonos se evalúan según condiciones del esquema
|
||||
- Ajustes requieren aprobación si >10% del calculado
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Cálculo automático al cerrar viaje
|
||||
- [ ] Soporte para los 4 tipos de esquema
|
||||
- [ ] Uso de km reales desde tracking
|
||||
- [ ] Cálculo automático de bonos
|
||||
- [ ] Desglose detallado del pago
|
||||
- [ ] Ajuste manual con justificación
|
||||
- [ ] Auditoría de ajustes
|
||||
- [ ] Tests de cálculo por tipo
|
||||
|
||||
@ -0,0 +1,224 @@
|
||||
# US-MAI010-003: Gestionar viáticos
|
||||
|
||||
**ID:** US-MAI010-003
|
||||
**Módulo:** MAI-010 (Liquidaciones)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador
|
||||
**Quiero** registrar anticipos de viáticos y su comprobación
|
||||
**Para** controlar el efectivo entregado a operadores y evitar pérdidas
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Registrar anticipo
|
||||
**Dado** que un operador sale a viaje
|
||||
**Cuando** registro el anticipo de viático
|
||||
**Entonces** se vincula al viaje con monto, fecha y forma de entrega
|
||||
|
||||
### CA-002: Comprobar gastos
|
||||
**Dado** que el operador regresa del viaje
|
||||
**Cuando** comprueba sus gastos
|
||||
**Entonces** puedo registrar cada gasto con tipo, monto y evidencia (ticket/foto)
|
||||
|
||||
### CA-003: Clasificar gastos
|
||||
**Dado** que hay diferentes tipos de gasto
|
||||
**Cuando** registro la comprobación
|
||||
**Entonces** clasifico en: combustible, casetas, comidas, hospedaje, otros
|
||||
|
||||
### CA-004: Calcular sobrante
|
||||
**Dado** que se comprobaron los gastos
|
||||
**Cuando** consulto el viático
|
||||
**Entonces** veo: anticipo, comprobado, sobrante (a devolver o descontar)
|
||||
|
||||
### CA-005: Descontar sobrante en liquidación
|
||||
**Dado** que hay sobrante sin devolver
|
||||
**Cuando** se genera la liquidación
|
||||
**Entonces** el sobrante se incluye como deducción automática
|
||||
|
||||
### CA-006: Alertar viáticos sin comprobar
|
||||
**Dado** que hay viajes cerrados con viático sin comprobar
|
||||
**Cuando** consulto el dashboard
|
||||
**Entonces** veo alertas de viáticos pendientes de comprobación
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ REGISTRAR ANTICIPO DE VIÁTICO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0125 | CDMX → Monterrey │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ Distancia estimada: 900 km │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CÁLCULO SUGERIDO │
|
||||
│ │
|
||||
│ Combustible (900 km × 4 km/L × $23/L): $5,175.00 │
|
||||
│ Casetas (estimado ruta): $1,200.00 │
|
||||
│ Comidas (2 días × $250): $500.00 │
|
||||
│ Imprevistos: $325.00 │
|
||||
│ ───────────────────────────────────────── │
|
||||
│ Total sugerido: $7,200.00 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ANTICIPO A ENTREGAR │
|
||||
│ │
|
||||
│ Monto: [$7,000.00] │
|
||||
│ │
|
||||
│ Forma de entrega: │
|
||||
│ (●) Efectivo │
|
||||
│ ( ) Transferencia │
|
||||
│ ( ) Vale/Tarjeta combustible │
|
||||
│ │
|
||||
│ Fecha entrega: [2026-01-22] │
|
||||
│ │
|
||||
│ Recibe: [Juan Pérez García ] │
|
||||
│ Entrega: [María González - Caja ] │
|
||||
│ │
|
||||
│ [Cancelar] [Registrar Anticipo] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comprobación de Viático
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ COMPROBACIÓN DE VIÁTICO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0125 | Anticipo: $7,000.00 │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ GASTOS COMPROBADOS [+ Agregar]│
|
||||
│ │
|
||||
│ | Tipo | Descripción | Monto | Evidencia | │
|
||||
│ |-------------|--------------------|---------:|------------| │
|
||||
│ | Combustible | PEMEX Qro Norte | $2,800.00| [📷 Ver] | │
|
||||
│ | Combustible | PEMEX MTY Centro | $1,500.00| [📷 Ver] | │
|
||||
│ | Casetas | TAG (reporte) | $980.00| [📄 Ver] | │
|
||||
│ | Comidas | Restaurant día 1 | $180.00| [📷 Ver] | │
|
||||
│ | Comidas | Restaurant día 2 | $150.00| [📷 Ver] | │
|
||||
│ | Hospedaje | Hotel MTY | $450.00| [📷 Ver] | │
|
||||
│ |-------------|--------------------|---------:|------------| │
|
||||
│ | TOTAL COMPROBADO | $6,060.00| | │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ │
|
||||
│ Anticipo entregado: $7,000.00 │
|
||||
│ Total comprobado: -$6,060.00 │
|
||||
│ ────────────────────────────────────────────────── │
|
||||
│ Sobrante a devolver/descontar: $940.00 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Destino del sobrante: │
|
||||
│ ( ) Devuelto en efectivo [$______] Fecha: [________] │
|
||||
│ (●) Descontar en próxima liquidación │
|
||||
│ │
|
||||
│ [Guardar borrador] [Cerrar comprobación] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agregar Gasto
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AGREGAR GASTO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Tipo de gasto: [Combustible ▼] │
|
||||
│ ○ Combustible │
|
||||
│ ○ Casetas/Peaje │
|
||||
│ ○ Comidas │
|
||||
│ ○ Hospedaje │
|
||||
│ ○ Estacionamiento │
|
||||
│ ○ Maniobras │
|
||||
│ ○ Otros │
|
||||
│ │
|
||||
│ Descripción: [PEMEX Querétaro Norte - Magna ] │
|
||||
│ Fecha del gasto: [2026-01-22] │
|
||||
│ Monto: [$2,800.00] │
|
||||
│ │
|
||||
│ Evidencia: │
|
||||
│ [📷 Seleccionar foto del ticket] │
|
||||
│ ✓ ticket_pemex_qro.jpg │
|
||||
│ │
|
||||
│ Notas: │
|
||||
│ [Carga completa en Querétaro antes de subir a MTY ]│
|
||||
│ │
|
||||
│ [Cancelar] [Agregar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dashboard de Viáticos
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VIÁTICOS PENDIENTES DE COMPROBAR │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ⚠ 5 viáticos pendientes de comprobación │
|
||||
│ │
|
||||
│ | Viaje | Operador | Anticipo | Cierre | Días | │
|
||||
│ |---------|---------------|-----------|----------|-------| │
|
||||
│ | VJE-0115| Pedro Ramírez | $5,500.00 | 18-ene | 9 🔴 | │
|
||||
│ | VJE-0118| Ana López | $3,200.00 | 20-ene | 7 🟡 | │
|
||||
│ | VJE-0122| Luis García | $6,800.00 | 22-ene | 5 🟡 | │
|
||||
│ | VJE-0126| Carlos Méndez | $4,500.00 | 24-ene | 3 🟢 | │
|
||||
│ | VJE-0129| Juan Pérez | $7,000.00 | 25-ene | 2 🟢 | │
|
||||
│ │
|
||||
│ Total pendiente de comprobar: $27,000.00 │
|
||||
│ │
|
||||
│ [Enviar recordatorios] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `settlements.viaticos` para anticipo
|
||||
- Tabla: `settlements.comprobantes_viatico` para gastos
|
||||
- Fotos de tickets se suben a S3
|
||||
- Sobrante se convierte en deducción tipo SOBRANTE_VIATICO
|
||||
- Alertas configurables (>3 días sin comprobar)
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Registro de anticipo vinculado a viaje
|
||||
- [ ] Comprobación de gastos con clasificación
|
||||
- [ ] Captura de evidencia (fotos de tickets)
|
||||
- [ ] Cálculo de sobrante
|
||||
- [ ] Integración con liquidación
|
||||
- [ ] Dashboard de viáticos pendientes
|
||||
- [ ] Alertas de viáticos sin comprobar
|
||||
- [ ] Tests de flujo completo
|
||||
|
||||
@ -0,0 +1,235 @@
|
||||
# US-MAI010-004: Aplicar deducciones
|
||||
|
||||
**ID:** US-MAI010-004
|
||||
**Módulo:** MAI-010 (Liquidaciones)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** supervisor de operaciones
|
||||
**Quiero** aplicar deducciones a operadores por multas, daños o faltantes
|
||||
**Para** recuperar pérdidas y mantener la disciplina operativa
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Catálogo de tipos de deducción
|
||||
**Dado** que hay diferentes causas de deducción
|
||||
**Cuando** administro el catálogo
|
||||
**Entonces** tengo tipos como: multa, daño unidad, daño carga, faltante, préstamo
|
||||
|
||||
### CA-002: Registrar deducción
|
||||
**Dado** que ocurrió un evento que amerita deducción
|
||||
**Cuando** la registro
|
||||
**Entonces** especifico: tipo, monto, viaje relacionado, evidencia
|
||||
|
||||
### CA-003: Requiere aprobación
|
||||
**Dado** que las deducciones afectan al operador
|
||||
**Cuando** registro una deducción
|
||||
**Entonces** queda pendiente hasta que un supervisor apruebe
|
||||
|
||||
### CA-004: Plan de pagos
|
||||
**Dado** que el monto es alto para descontar de una vez
|
||||
**Cuando** configuro la deducción
|
||||
**Entonces** puedo establecer un plan (descontar $X por liquidación)
|
||||
|
||||
### CA-005: Límite de deducción
|
||||
**Dado** que hay políticas de límite
|
||||
**Cuando** las deducciones exceden el % permitido del pago
|
||||
**Entonces** el sistema alerta y requiere autorización especial
|
||||
|
||||
### CA-006: Historial por operador
|
||||
**Dado** que quiero ver el comportamiento de un operador
|
||||
**Cuando** consulto su historial
|
||||
**Entonces** veo todas las deducciones aplicadas
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ REGISTRAR DEDUCCIÓN ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ No. Empleado: OP-0025 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TIPO DE DEDUCCIÓN │
|
||||
│ │
|
||||
│ Tipo: [Multa de tránsito ▼] │
|
||||
│ ○ Multa de tránsito │
|
||||
│ ○ Daño a unidad │
|
||||
│ ○ Daño a carga │
|
||||
│ ○ Faltante de mercancía │
|
||||
│ ○ Préstamo/Adelanto │
|
||||
│ ○ Sobrante de viático │
|
||||
│ ○ Otro │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DETALLE │
|
||||
│ │
|
||||
│ Viaje relacionado: [VJE-0120 ▼] │
|
||||
│ Fecha del evento: [2026-01-21] │
|
||||
│ │
|
||||
│ Descripción: │
|
||||
│ [Infracción por exceso de velocidad en carretera 57D ]│
|
||||
│ [Querétaro. Límite 90 km/h, velocidad 112 km/h. ]│
|
||||
│ │
|
||||
│ Monto total: [$1,200.00] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ EVIDENCIA │
|
||||
│ │
|
||||
│ [📷 Agregar foto] [📄 Agregar documento] │
|
||||
│ │
|
||||
│ ✓ multa_transito_001.jpg (Foto de infracción) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ FORMA DE DESCUENTO │
|
||||
│ │
|
||||
│ (●) Descontar completo en próxima liquidación │
|
||||
│ ( ) Plan de pagos: [____] pagos de $[_____] │
|
||||
│ │
|
||||
│ [Cancelar] [Enviar a aprobación] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Aprobar Deducción
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ APROBAR DEDUCCIÓN ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ SOLICITUD DE DEDUCCIÓN │
|
||||
│ │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ Tipo: Multa de tránsito │
|
||||
│ Monto: $1,200.00 │
|
||||
│ Viaje: VJE-0120 │
|
||||
│ │
|
||||
│ Descripción: │
|
||||
│ Infracción por exceso de velocidad en carretera 57D │
|
||||
│ Querétaro. Límite 90 km/h, velocidad 112 km/h. │
|
||||
│ │
|
||||
│ Evidencia: [📷 Ver foto] │
|
||||
│ │
|
||||
│ Registrado por: María González │
|
||||
│ Fecha solicitud: 2026-01-22 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ POLÍTICA DE EMPRESA │
|
||||
│ │
|
||||
│ Según política, las multas de tránsito se descuentan al │
|
||||
│ operador en un 100% cuando son por exceso de velocidad. │
|
||||
│ │
|
||||
│ Límite de deducción por liquidación: 30% del pago bruto │
|
||||
│ Pago estimado próxima liquidación: $5,650.00 │
|
||||
│ Máximo descuento permitido: $1,695.00 │
|
||||
│ ✓ Esta deducción está dentro del límite │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DECISIÓN │
|
||||
│ │
|
||||
│ (●) Aprobar deducción │
|
||||
│ ( ) Aprobar con monto ajustado: $[______] │
|
||||
│ ( ) Rechazar │
|
||||
│ │
|
||||
│ Comentario: │
|
||||
│ [Aprobado según política ]│
|
||||
│ │
|
||||
│ [Cancelar] [Confirmar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Historial de Deducciones
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ HISTORIAL DE DEDUCCIONES - Juan Pérez García │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Periodo: [Últimos 12 meses ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ │
|
||||
│ Total deducciones: 3 │
|
||||
│ Monto total: $2,450.00 │
|
||||
│ Promedio mensual: $204.17 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DETALLE │
|
||||
│ │
|
||||
│ | Fecha | Tipo | Viaje | Monto | Estado | │
|
||||
│ |----------|-------------|---------|----------|------------| │
|
||||
│ | 22-ene-26| Multa | VJE-0120| $1,200.00| Descontada | │
|
||||
│ | 15-dic-25| Daño unidad | VJE-0089| $750.00| Descontada | │
|
||||
│ | 10-oct-25| Faltante | VJE-0056| $500.00| Descontada | │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ COMPARATIVO CON OTROS OPERADORES │
|
||||
│ │
|
||||
│ Juan Pérez: $204/mes (promedio) │
|
||||
│ Promedio empresa: $180/mes │
|
||||
│ Posición: 15 de 25 operadores │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Deducción
|
||||
|
||||
| Tipo | Descripción | % responsabilidad |
|
||||
|------|-------------|-------------------|
|
||||
| MULTA_TRANSITO | Infracciones de tránsito | 100% operador |
|
||||
| DANO_UNIDAD | Daño al vehículo por negligencia | 50-100% |
|
||||
| DANO_CARGA | Daño a la mercancía | Según caso |
|
||||
| FALTANTE | Faltante de mercancía | Según caso |
|
||||
| PRESTAMO | Adelanto de efectivo | 100% |
|
||||
| SOBRANTE_VIATICO | Viático no comprobado | 100% |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `settlements.deducciones` con estado (pendiente, aprobada, rechazada, aplicada)
|
||||
- Tabla: `settlements.tipos_deduccion` para catálogo
|
||||
- Plan de pagos: se crean N registros con monto parcial
|
||||
- Límite de deducción configurable por tenant (ej: 30% del bruto)
|
||||
- Auditoría completa de aprobaciones/rechazos
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Catálogo de tipos de deducción
|
||||
- [ ] Registro de deducción con evidencia
|
||||
- [ ] Flujo de aprobación por supervisor
|
||||
- [ ] Plan de pagos para montos grandes
|
||||
- [ ] Validación de límite de deducción
|
||||
- [ ] Historial de deducciones por operador
|
||||
- [ ] Tests de flujo de aprobación
|
||||
|
||||
@ -0,0 +1,289 @@
|
||||
# US-MAI010-005: Generar y autorizar liquidación
|
||||
|
||||
**ID:** US-MAI010-005
|
||||
**Módulo:** MAI-010 (Liquidaciones)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** liquidador
|
||||
**Quiero** generar la liquidación periódica consolidando todos los conceptos
|
||||
**Para** pagar al operador de forma clara y trazable
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Generar liquidación por periodo
|
||||
**Dado** que llegó la fecha de corte (semanal/quincenal)
|
||||
**Cuando** genero la liquidación
|
||||
**Entonces** se consolidan: pagos por viaje, viáticos, bonos, deducciones
|
||||
|
||||
### CA-002: Desglose completo
|
||||
**Dado** que la liquidación fue generada
|
||||
**Cuando** la consulto
|
||||
**Entonces** veo cada concepto con su origen (viaje, tipo, monto)
|
||||
|
||||
### CA-003: Estado borrador editable
|
||||
**Dado** que la liquidación está en borrador
|
||||
**Cuando** detecto un error
|
||||
**Entonces** puedo editar o agregar conceptos con justificación
|
||||
|
||||
### CA-004: Autorización de supervisor
|
||||
**Dado** que la liquidación está lista
|
||||
**Cuando** la envío a autorización
|
||||
**Entonces** el supervisor debe aprobar antes de proceder al pago
|
||||
|
||||
### CA-005: Aceptación del operador
|
||||
**Dado** que la liquidación fue autorizada
|
||||
**Cuando** el operador la revisa
|
||||
**Entonces** puede firmar/aceptar digitalmente conforme
|
||||
|
||||
### CA-006: Exportar a nómina
|
||||
**Dado** que la liquidación está autorizada y aceptada
|
||||
**Cuando** exporto
|
||||
**Entonces** se genera archivo compatible con sistema de nómina
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ GENERAR LIQUIDACIÓN ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ CONFIGURACIÓN DEL CORTE │
|
||||
│ │
|
||||
│ Tipo de corte: (●) Semanal ( ) Quincenal │
|
||||
│ Periodo: [20-ene-2026] al [26-ene-2026] │
|
||||
│ │
|
||||
│ Operadores a incluir: │
|
||||
│ (●) Todos los activos con movimientos │
|
||||
│ ( ) Seleccionar específicos │
|
||||
│ │
|
||||
│ [Generar liquidaciones] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESULTADO │
|
||||
│ │
|
||||
│ ✓ 18 liquidaciones generadas │
|
||||
│ Total a pagar: $89,450.00 │
|
||||
│ │
|
||||
│ [Ver listado] [Revisar y autorizar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Liquidación Individual
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ LIQUIDACIÓN LIQ-2026-W04-025 ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ No. Empleado: OP-0025 │
|
||||
│ Periodo: Semana 04 (20-ene al 26-ene-2026) │
|
||||
│ Estado: BORRADOR │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ PERCEPCIONES │
|
||||
│ │
|
||||
│ | Concepto | Viaje | Monto | │
|
||||
│ |-------------------------------------|---------|-----------| │
|
||||
│ | Pago por flete (25%) | VJE-0120| $1,750.00 | │
|
||||
│ | Pago por flete (25%) | VJE-0125| $4,550.00 | │
|
||||
│ | Pago por flete (25%) | VJE-0128| $1,750.00 | │
|
||||
│ | Bono OTIF | VJE-0120| $800.00 | │
|
||||
│ | Bono OTIF | VJE-0125| $800.00 | │
|
||||
│ | Bono OTIF | VJE-0128| $800.00 | │
|
||||
│ | Bono sin incidencias | VJE-0120| $300.00 | │
|
||||
│ | Bono sin incidencias | VJE-0125| $300.00 | │
|
||||
│ | Bono sin incidencias | VJE-0128| $300.00 | │
|
||||
│ |-------------------------------------|---------|-----------| │
|
||||
│ | SUBTOTAL PERCEPCIONES | |$11,350.00 | │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DEDUCCIONES │
|
||||
│ │
|
||||
│ | Concepto | Viaje | Monto | │
|
||||
│ |-------------------------------------|---------|-----------| │
|
||||
│ | Sobrante viático | VJE-0125| -$940.00 | │
|
||||
│ | Multa de tránsito | VJE-0120| -$1,200.00| │
|
||||
│ |-------------------------------------|---------|-----------| │
|
||||
│ | SUBTOTAL DEDUCCIONES | | -$2,140.00| │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ═══════════════════════════════════════════════════════════ │
|
||||
│ NETO A PAGAR: $9,210.00 MXN│
|
||||
│ ═══════════════════════════════════════════════════════════ │
|
||||
│ │
|
||||
│ [Editar] [Agregar concepto] [Enviar a autorización]│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Autorización de Supervisor
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AUTORIZAR LIQUIDACIONES │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Periodo: Semana 04 (20-ene al 26-ene-2026) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ PENDIENTES DE AUTORIZACIÓN │
|
||||
│ │
|
||||
│ [☑ Seleccionar todas] │
|
||||
│ │
|
||||
│ | Operador | Percepciones | Deducciones | Neto | │
|
||||
│ |-----------------|--------------|-------------|-----------| │
|
||||
│ | ☑ Juan Pérez | $11,350.00 | -$2,140.00 | $9,210.00 | │
|
||||
│ | ☑ Pedro Ramírez | $8,200.00 | -$450.00 | $7,750.00 | │
|
||||
│ | ☑ Ana López | $6,500.00 | $0.00 | $6,500.00 | │
|
||||
│ | ☑ Luis García | $9,800.00 | -$800.00 | $9,000.00 | │
|
||||
│ | ☐ Carlos Méndez | $7,200.00 | -$3,500.00 | $3,700.00 |⚠│
|
||||
│ | | | | | │
|
||||
│ |-----------------|--------------|-------------|-----------| │
|
||||
│ | TOTAL SELEC. | $35,850.00 | -$3,390.00 | $32,460.00| │
|
||||
│ │
|
||||
│ ⚠ Carlos Méndez: Deducciones > 30% del bruto. Revisar. │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Comentarios del supervisor: │
|
||||
│ [Liquidaciones revisadas y correctas ]│
|
||||
│ │
|
||||
│ [Rechazar seleccionadas] [✓ Autorizar seleccionadas]│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Aceptación del Operador
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ACEPTAR LIQUIDACIÓN ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ Liquidación: LIQ-2026-W04-025 │
|
||||
│ Neto a pagar: $9,210.00 MXN │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Por este medio ACEPTO la liquidación correspondiente al │
|
||||
│ periodo del 20 al 26 de enero de 2026, declarando que: │
|
||||
│ │
|
||||
│ ☑ He revisado el desglose de percepciones │
|
||||
│ ☑ Estoy de acuerdo con las deducciones aplicadas │
|
||||
│ ☑ El monto neto a recibir es correcto │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ FIRMA DIGITAL │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ │ │
|
||||
│ │ [Área de firma - táctil] │ │
|
||||
│ │ │ │
|
||||
│ │ ~~~~~~~~~~~~~~~~~~~~~~ │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Limpiar firma] │
|
||||
│ │
|
||||
│ Fecha: 2026-01-27 10:35:22 │
|
||||
│ IP: 192.168.1.45 │
|
||||
│ │
|
||||
│ [Rechazar - Solicitar revisión] [✓ Firmar y Aceptar]│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exportar a Nómina
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EXPORTAR A NÓMINA ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Periodo: Semana 04 (20-ene al 26-ene-2026) │
|
||||
│ │
|
||||
│ Liquidaciones autorizadas y aceptadas: 18 │
|
||||
│ Total a dispersar: $89,450.00 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ FORMATO DE EXPORTACIÓN │
|
||||
│ │
|
||||
│ ( ) Layout bancario dispersión (TXT) │
|
||||
│ (●) Excel con desglose │
|
||||
│ ( ) CSV para sistema de nómina │
|
||||
│ ( ) XML CFDI recibos de nómina │
|
||||
│ │
|
||||
│ Incluir: │
|
||||
│ ☑ Desglose de conceptos │
|
||||
│ ☑ Datos bancarios de operadores │
|
||||
│ ☑ Resumen por centro de costo │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ [Cancelar] [Exportar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados de Liquidación
|
||||
|
||||
| Estado | Descripción | Acciones permitidas |
|
||||
|--------|-------------|---------------------|
|
||||
| BORRADOR | Generada, editable | Editar, enviar a autorización |
|
||||
| PENDIENTE | Enviada a supervisor | Autorizar, rechazar |
|
||||
| AUTORIZADA | Aprobada por supervisor | Enviar a operador, exportar |
|
||||
| ACEPTADA | Firmada por operador | Exportar, pagar |
|
||||
| PAGADA | Dispersión realizada | Ver, generar recibo |
|
||||
| RECHAZADA | Rechazada (supervisor u operador) | Editar, reenviar |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `settlements.liquidaciones` con periodo y estado
|
||||
- Tabla: `settlements.conceptos_liquidacion` para desglose
|
||||
- Firma digital se almacena como imagen base64
|
||||
- Exportación genera archivos según formato seleccionado
|
||||
- Job automático para generar liquidaciones el día de corte
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Generación masiva de liquidaciones por periodo
|
||||
- [ ] Desglose completo de conceptos
|
||||
- [ ] Edición de borrador con justificación
|
||||
- [ ] Flujo de autorización de supervisor
|
||||
- [ ] Aceptación con firma del operador
|
||||
- [ ] Exportación a múltiples formatos
|
||||
- [ ] Tests de flujo completo
|
||||
|
||||
Loading…
Reference in New Issue
Block a user