569eaeb5a4
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>
211 lines
6.4 KiB
Markdown
211 lines
6.4 KiB
Markdown
# 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*
|