From 569eaeb5a46771c8c08589171d0a163ffdc89fc9 Mon Sep 17 00:00:00 2001 From: Adrian Flores Cortes Date: Tue, 27 Jan 2026 02:05:03 -0600 Subject: [PATCH] =?UTF-8?q?docs:=20Add=20MAI-009=20(Facturaci=C3=B3n)=20an?= =?UTF-8?q?d=20MAI-010=20(Liquidaciones)=20specifications?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../MAI-009-facturacion-transporte/README.md | 207 +++++++++++++ .../REQUERIMIENTOS.md | 234 ++++++++++++++ .../RESUMEN-EPICA.md | 242 +++++++++++++++ .../historias-usuario/US-MAI009-001.md | 187 ++++++++++++ .../historias-usuario/US-MAI009-002.md | 196 ++++++++++++ .../historias-usuario/US-MAI009-003.md | 235 ++++++++++++++ .../historias-usuario/US-MAI009-004.md | 220 +++++++++++++ .../historias-usuario/US-MAI009-005.md | 229 ++++++++++++++ .../MAI-010-liquidaciones/README.md | 205 +++++++++++++ .../MAI-010-liquidaciones/REQUERIMIENTOS.md | 210 +++++++++++++ .../MAI-010-liquidaciones/RESUMEN-EPICA.md | 233 ++++++++++++++ .../historias-usuario/US-MAI010-001.md | 211 +++++++++++++ .../historias-usuario/US-MAI010-002.md | 193 ++++++++++++ .../historias-usuario/US-MAI010-003.md | 224 ++++++++++++++ .../historias-usuario/US-MAI010-004.md | 235 ++++++++++++++ .../historias-usuario/US-MAI010-005.md | 289 ++++++++++++++++++ 16 files changed, 3550 insertions(+) create mode 100644 docs/02-definicion-modulos/MAI-009-facturacion-transporte/README.md create mode 100644 docs/02-definicion-modulos/MAI-009-facturacion-transporte/REQUERIMIENTOS.md create mode 100644 docs/02-definicion-modulos/MAI-009-facturacion-transporte/RESUMEN-EPICA.md create mode 100644 docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-001.md create mode 100644 docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-002.md create mode 100644 docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-003.md create mode 100644 docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-004.md create mode 100644 docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-005.md create mode 100644 docs/02-definicion-modulos/MAI-010-liquidaciones/README.md create mode 100644 docs/02-definicion-modulos/MAI-010-liquidaciones/REQUERIMIENTOS.md create mode 100644 docs/02-definicion-modulos/MAI-010-liquidaciones/RESUMEN-EPICA.md create mode 100644 docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-001.md create mode 100644 docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-002.md create mode 100644 docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-003.md create mode 100644 docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-004.md create mode 100644 docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-005.md diff --git a/docs/02-definicion-modulos/MAI-009-facturacion-transporte/README.md b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/README.md new file mode 100644 index 0000000..4b1e1f8 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/README.md @@ -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* diff --git a/docs/02-definicion-modulos/MAI-009-facturacion-transporte/REQUERIMIENTOS.md b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/REQUERIMIENTOS.md new file mode 100644 index 0000000..dc963b7 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/REQUERIMIENTOS.md @@ -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* diff --git a/docs/02-definicion-modulos/MAI-009-facturacion-transporte/RESUMEN-EPICA.md b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/RESUMEN-EPICA.md new file mode 100644 index 0000000..c8f43df --- /dev/null +++ b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/RESUMEN-EPICA.md @@ -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* diff --git a/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-001.md b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-001.md new file mode 100644 index 0000000..5490c66 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-001.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-002.md b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-002.md new file mode 100644 index 0000000..5053dcf --- /dev/null +++ b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-002.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-003.md b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-003.md new file mode 100644 index 0000000..0cb1f45 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-003.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-004.md b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-004.md new file mode 100644 index 0000000..cc61fc0 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-004.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-005.md b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-005.md new file mode 100644 index 0000000..71e36fb --- /dev/null +++ b/docs/02-definicion-modulos/MAI-009-facturacion-transporte/historias-usuario/US-MAI009-005.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-010-liquidaciones/README.md b/docs/02-definicion-modulos/MAI-010-liquidaciones/README.md new file mode 100644 index 0000000..94fbca2 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-010-liquidaciones/README.md @@ -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* diff --git a/docs/02-definicion-modulos/MAI-010-liquidaciones/REQUERIMIENTOS.md b/docs/02-definicion-modulos/MAI-010-liquidaciones/REQUERIMIENTOS.md new file mode 100644 index 0000000..e998f68 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-010-liquidaciones/REQUERIMIENTOS.md @@ -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* diff --git a/docs/02-definicion-modulos/MAI-010-liquidaciones/RESUMEN-EPICA.md b/docs/02-definicion-modulos/MAI-010-liquidaciones/RESUMEN-EPICA.md new file mode 100644 index 0000000..9a9a70b --- /dev/null +++ b/docs/02-definicion-modulos/MAI-010-liquidaciones/RESUMEN-EPICA.md @@ -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* diff --git a/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-001.md b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-001.md new file mode 100644 index 0000000..19a28a7 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-001.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-002.md b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-002.md new file mode 100644 index 0000000..cd98a88 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-002.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-003.md b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-003.md new file mode 100644 index 0000000..f166883 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-003.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-004.md b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-004.md new file mode 100644 index 0000000..d0bd535 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-004.md @@ -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 + diff --git a/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-005.md b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-005.md new file mode 100644 index 0000000..c94f587 --- /dev/null +++ b/docs/02-definicion-modulos/MAI-010-liquidaciones/historias-usuario/US-MAI010-005.md @@ -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 +