docs: Add MAI-002, MAI-004, MAI-005 module specifications
MAI-002 (Tarifas y SLA): - README, REQUERIMIENTOS, RESUMEN-EPICA - 5 User Stories (31 SP total) - Covers: tarifario por lane, recargos, SLA, cotizaciones, aprobaciones MAI-004 (Planeacion TMS): - README, REQUERIMIENTOS, RESUMEN-EPICA - 5 User Stories (39 SP total) - Covers: tablero planeacion, consolidacion, asignacion, validaciones, ETA MAI-005 (Despacho): - README, REQUERIMIENTOS, RESUMEN-EPICA - 5 User Stories (28 SP total) - Covers: checklist NOM-068, sellos, evidencias, kit documental, gate out Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Adrian Flores Cortes
parent
7f45eb6383
commit
9caeae936a
223
docs/02-definicion-modulos/MAI-002-tarifas-sla/README.md
Normal file
223
docs/02-definicion-modulos/MAI-002-tarifas-sla/README.md
Normal file
@ -0,0 +1,223 @@
|
||||
# MAI-002: Tarifas, Contratos y SLA
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Estado:** Diseño
|
||||
**Prioridad:** P0 (Crítico - Base Comercial)
|
||||
|
||||
---
|
||||
|
||||
## Descripción General
|
||||
|
||||
El módulo de Tarifas, Contratos y SLA es responsable de la gestión comercial del transporte: definición de precios por ruta/servicio, cálculo de recargos, contratos con clientes y acuerdos de nivel de servicio.
|
||||
|
||||
**Problema que resuelve:**
|
||||
- Cotizaciones manuales inconsistentes
|
||||
- Tarifas dispersas en hojas de cálculo
|
||||
- Recargos olvidados o mal calculados
|
||||
- Incumplimiento de SLA sin penalización
|
||||
- Descuentos sin control ni aprobación
|
||||
|
||||
---
|
||||
|
||||
## Objetivos del Módulo
|
||||
|
||||
1. **Tarifario estructurado:** Tarifas por lane, tipo de unidad, modalidad (FTL/LTL)
|
||||
2. **Recargos automatizados:** Fuel surcharge, detention, reentrega, maniobras
|
||||
3. **SLA documentados:** Tiempos comprometidos, penalizaciones, tolerancias
|
||||
4. **Cotización rápida:** Cálculo automático con desglose de costos
|
||||
5. **Control de descuentos:** Flujos de aprobación por monto/porcentaje
|
||||
|
||||
---
|
||||
|
||||
## Alcance Funcional
|
||||
|
||||
### Incluido
|
||||
|
||||
- Gestión de tarifario por lane (origen-destino-zona)
|
||||
- Matriz de recargos (surcharges) configurables
|
||||
- Contratos con clientes y vigencias
|
||||
- Definición de SLA por cliente/servicio
|
||||
- Motor de cotización con cálculo automático
|
||||
- Flujos de aprobación para descuentos/excepciones
|
||||
- Snapshot de tarifa aplicada a cada OT
|
||||
|
||||
### Excluido
|
||||
|
||||
- Facturación (MAI-009)
|
||||
- Captura de OT (MAI-003)
|
||||
- CRM avanzado (módulo heredado de erp-core)
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el módulo |
|
||||
|-------|------------------|
|
||||
| Ejecutivo de Ventas | Cotiza, negocia tarifas, gestiona contratos |
|
||||
| Gerente Comercial | Aprueba descuentos, define políticas |
|
||||
| Planner | Consulta tarifas para planeación |
|
||||
| Sistema | Calcula precios, valida vigencias, aplica recargos |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
CLIENTE SOLICITA COTIZACIÓN
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. IDENTIFICAR LANE │
|
||||
│ - Origen → Destino │
|
||||
│ - Zona tarifaria │
|
||||
│ - Tipo de equipo requerido │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 2. BUSCAR TARIFA VIGENTE │
|
||||
│ - Por contrato del cliente │
|
||||
│ - Por tarifa general del lane │
|
||||
│ - Por tarifa por defecto │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 3. CALCULAR RECARGOS │
|
||||
│ - Fuel surcharge (% o fijo) │
|
||||
│ - Maniobras │
|
||||
│ - Escolta/seguridad │
|
||||
│ - Seguro adicional │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 4. APLICAR DESCUENTO (si aplica) │
|
||||
│ - Dentro de límite → Automático │
|
||||
│ - Excede límite → Requiere aprobación│
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
[APROBADO] [PENDIENTE]
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ 5. GENERAR │ │ Flujo de │
|
||||
│ COTIZACIÓN │ │ aprobación │
|
||||
│ - Desglose │ │ │
|
||||
│ - Vigencia │ │ │
|
||||
│ - PDF │ │ │
|
||||
└────────┬────────┘ └────────┬────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ COTIZACIÓN LISTA │
|
||||
│ → Convertir a OT si acepta │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Datos del Módulo
|
||||
|
||||
### Entidades Principales
|
||||
|
||||
| Entidad | Descripción | Estado |
|
||||
|---------|-------------|--------|
|
||||
| Tarifa | Precio base por lane/servicio | NO IMPLEMENTADA |
|
||||
| Lane | Combinación origen-destino-zona | NO IMPLEMENTADA |
|
||||
| Recargo | Tipo de surcharge aplicable | NO IMPLEMENTADA |
|
||||
| Contrato | Acuerdo comercial con cliente | NO IMPLEMENTADA |
|
||||
| SLA | Niveles de servicio comprometidos | NO IMPLEMENTADA |
|
||||
| Cotizacion | Propuesta de precio al cliente | NO IMPLEMENTADA |
|
||||
|
||||
### Campos Clave Tarifa
|
||||
|
||||
| Campo | Tipo | Obligatorio | Descripción |
|
||||
|-------|------|-------------|-------------|
|
||||
| lane_id | UUID | Sí | Lane (origen-destino) |
|
||||
| tipo_unidad | ENUM | Sí | TRACTOCAMION, TORTON, RABON, etc. |
|
||||
| modalidad | ENUM | Sí | FTL, LTL |
|
||||
| precio_base | DECIMAL | Sí | Monto base |
|
||||
| moneda | ENUM | Sí | MXN, USD |
|
||||
| vigencia_inicio | DATE | Sí | Desde cuándo aplica |
|
||||
| vigencia_fin | DATE | No | Hasta cuándo aplica |
|
||||
| cliente_id | UUID | No | Si es tarifa específica de cliente |
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md)
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Tarifa
|
||||
|
||||
| Tipo | Descripción | Ejemplo |
|
||||
|------|-------------|---------|
|
||||
| Por viaje | Monto fijo por trayecto | $15,000 MXN CDMX→GDL |
|
||||
| Por km | Precio por kilómetro | $18 MXN/km |
|
||||
| Por tonelada | Precio por peso | $450 MXN/ton |
|
||||
| Por pallet | Precio por posición | $800 MXN/pallet |
|
||||
| Combinada | Base + variable | $8,000 + $12/km |
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Recargo
|
||||
|
||||
| Código | Nombre | Cálculo |
|
||||
|--------|--------|---------|
|
||||
| FUEL | Fuel Surcharge | % sobre base |
|
||||
| DETENTION_CARGA | Demora en carga | $/hora después de tolerancia |
|
||||
| DETENTION_DESCARGA | Demora en descarga | $/hora después de tolerancia |
|
||||
| MANIOBRA | Maniobra especial | Monto fijo |
|
||||
| REENTREGA | Reentrega/reexpedición | % o monto fijo |
|
||||
| ESCOLTA | Escolta de seguridad | Monto fijo |
|
||||
| SEGURO_ADICIONAL | Seguro extra | % sobre valor declarado |
|
||||
| ALMACENAJE | Almacenaje temporal | $/día |
|
||||
|
||||
---
|
||||
|
||||
## Métricas del Módulo
|
||||
|
||||
| KPI | Fórmula | Meta |
|
||||
|-----|---------|------|
|
||||
| Cotizaciones convertidas | % cotizaciones → OT | >30% |
|
||||
| Tiempo de cotización | Avg(tiempo de respuesta) | <2 hrs |
|
||||
| Descuentos fuera de política | % descuentos con override | <10% |
|
||||
| Tarifas actualizadas | % tarifas vigentes | 100% |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Este módulo depende de:
|
||||
- MAE-001 (Clientes/Partners): Datos de cliente
|
||||
- erp-core/catalogs: Zonas, tipos de equipo
|
||||
|
||||
### Otros módulos dependen de este:
|
||||
- MAI-003 (OT): Usa tarifa para precio de OT
|
||||
- MAI-009 (Facturación): Usa tarifa para facturar
|
||||
- MAI-004 (Planeación): Consulta tarifas para optimización
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
Ver carpeta: [historias-usuario/](./historias-usuario/)
|
||||
|
||||
| US | Título | Prioridad |
|
||||
|----|--------|-----------|
|
||||
| US-MAI002-001 | Definir tarifa por lane | Alta |
|
||||
| US-MAI002-002 | Configurar recargos | Alta |
|
||||
| US-MAI002-003 | Definir SLA por cliente | Alta |
|
||||
| US-MAI002-004 | Generar cotización rápida | Alta |
|
||||
| US-MAI002-005 | Aprobar descuento excepcional | Media |
|
||||
|
||||
---
|
||||
|
||||
*Módulo MAI-002 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
197
docs/02-definicion-modulos/MAI-002-tarifas-sla/REQUERIMIENTOS.md
Normal file
197
docs/02-definicion-modulos/MAI-002-tarifas-sla/REQUERIMIENTOS.md
Normal file
@ -0,0 +1,197 @@
|
||||
# REQUERIMIENTOS.md - MAI-002: Tarifas, Contratos y SLA
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.1
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.1.1: Tarifario por Lane y Servicio
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir definir tarifas por ruta (origen/destino/zona), tipo de unidad, modalidad (FTL/LTL), prioridad y vigencia.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Crear tarifas con lane (origen-destino o zona)
|
||||
2. Especificar tipo de unidad (tractocamión, torton, rabón, etc.)
|
||||
3. Definir modalidad: FTL (carga completa) o LTL (carga parcial)
|
||||
4. Configurar prioridad/servicio (estándar, express, mismo día)
|
||||
5. Establecer vigencia (fecha inicio, fecha fin opcional)
|
||||
6. Soportar múltiples monedas (MXN, USD)
|
||||
7. Definir tarifa específica por cliente o general
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `tarifas`
|
||||
- Tabla: `lanes`
|
||||
- Tabla: `zonas_tarifarias`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/tarifas` - Listar tarifas
|
||||
- `POST /api/v1/tarifas` - Crear tarifa
|
||||
- `PUT /api/v1/tarifas/:id` - Actualizar tarifa
|
||||
- `GET /api/v1/tarifas/buscar` - Buscar tarifa por lane/cliente
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.1.2: Matriz de Recargos (Surcharges)
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe gestionar una matriz de recargos aplicables: fuel surcharge, demoras, almacenaje, reexpedición, maniobras, escoltas, seguro adicional.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Catálogo de tipos de recargo configurable
|
||||
2. Cada recargo define: nombre, código, tipo de cálculo (% o fijo)
|
||||
3. Fuel surcharge con índice actualizable periódicamente
|
||||
4. Demoras (detention) con tolerancia en horas y costo por hora extra
|
||||
5. Recargos por cliente/servicio o generales
|
||||
6. Vigencia por recargo
|
||||
7. Reglas de aplicación automática o manual
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `tipos_recargo`
|
||||
- Tabla: `recargos_cliente`
|
||||
- Tabla: `indice_combustible`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/recargos/tipos` - Catálogo de tipos
|
||||
- `POST /api/v1/recargos` - Crear recargo
|
||||
- `PUT /api/v1/recargos/fuel-surcharge` - Actualizar índice combustible
|
||||
- `GET /api/v1/recargos/calcular` - Calcular recargos aplicables
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.1.3: SLA por Cliente
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir definir acuerdos de nivel de servicio (SLA) con tiempos comprometidos, ventanas, penalizaciones, tolerancias y reglas de notificación.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Definir SLA por cliente o por tipo de servicio
|
||||
2. Especificar tiempo de pickup comprometido (horas desde solicitud)
|
||||
3. Especificar tiempo de entrega (horas o días según distancia)
|
||||
4. Definir tolerancias (minutos/horas de gracia)
|
||||
5. Configurar penalizaciones por incumplimiento (% o monto)
|
||||
6. Reglas de notificación (alertas antes de vencer SLA)
|
||||
7. Dashboard de cumplimiento de SLA
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `sla_clientes`
|
||||
- Tabla: `sla_servicios`
|
||||
- Vista: `v_cumplimiento_sla`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/clientes/:id/sla` - Obtener SLA del cliente
|
||||
- `POST /api/v1/sla` - Crear SLA
|
||||
- `GET /api/v1/sla/cumplimiento` - Reporte de cumplimiento
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.1.4: Cotización Rápida
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir generar cotizaciones desde CRM/ventas con cálculo automático de tarifa base + recargos, considerando distancia/kms si se integra con mapas.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Buscar tarifa vigente por lane y tipo de servicio
|
||||
2. Calcular distancia si se integra con API de mapas
|
||||
3. Aplicar recargos automáticamente según reglas
|
||||
4. Mostrar desglose de precio (base + recargos)
|
||||
5. Permitir agregar descuento (dentro de política)
|
||||
6. Generar PDF de cotización con vigencia
|
||||
7. Guardar snapshot de tarifa aplicada
|
||||
8. Convertir cotización a OT si cliente acepta
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `cotizaciones`
|
||||
- Tabla: `cotizacion_detalle`
|
||||
- Tabla: `snapshot_tarifa`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/cotizaciones` - Crear cotización
|
||||
- `GET /api/v1/cotizaciones/:id` - Obtener cotización
|
||||
- `GET /api/v1/cotizaciones/:id/pdf` - Generar PDF
|
||||
- `POST /api/v1/cotizaciones/:id/convertir-ot` - Convertir a OT
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.1.5: Control de Aprobaciones
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe implementar flujos de aprobación para descuentos, tarifas especiales y recargos excepcionales según políticas definidas.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Definir umbrales de descuento por rol (ej: vendedor hasta 5%, gerente hasta 15%)
|
||||
2. Descuento dentro de umbral se aplica automáticamente
|
||||
3. Descuento fuera de umbral requiere aprobación
|
||||
4. Flujo de aprobación con niveles (supervisor → gerente)
|
||||
5. Notificación al aprobador cuando hay solicitud pendiente
|
||||
6. Registro de aprobaciones/rechazos con motivo
|
||||
7. Tarifas especiales (fuera de catálogo) requieren aprobación
|
||||
8. Auditoría de todas las excepciones
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `politicas_descuento`
|
||||
- Tabla: `solicitudes_aprobacion`
|
||||
- Tabla: `aprobaciones`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/descuentos/solicitar` - Solicitar aprobación
|
||||
- `GET /api/v1/aprobaciones/pendientes` - Listar pendientes
|
||||
- `POST /api/v1/aprobaciones/:id/aprobar` - Aprobar solicitud
|
||||
- `POST /api/v1/aprobaciones/:id/rechazar` - Rechazar solicitud
|
||||
|
||||
**Prioridad:** Media
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Performance de Búsqueda
|
||||
La búsqueda de tarifa por lane debe responder en menos de 500ms.
|
||||
|
||||
### RNF-002: Consistencia de Precios
|
||||
El sistema debe garantizar que la tarifa aplicada a una OT es la vigente al momento de creación (snapshot inmutable).
|
||||
|
||||
### RNF-003: Auditoría
|
||||
Todos los cambios de tarifa, recargos y aprobaciones deben registrarse con usuario, fecha y valores anteriores/nuevos.
|
||||
|
||||
### RNF-004: Multi-moneda
|
||||
Soportar al menos MXN y USD con conversión configurable.
|
||||
|
||||
---
|
||||
|
||||
## Validaciones de Negocio
|
||||
|
||||
| Validación | Descripción | Acción si falla |
|
||||
|------------|-------------|-----------------|
|
||||
| TAR_001 | Tarifa vigente para el lane | Alertar, usar tarifa por defecto |
|
||||
| TAR_002 | Descuento dentro de política | Requiere aprobación |
|
||||
| TAR_003 | Contrato del cliente vigente | Usar tarifa general |
|
||||
| TAR_004 | Fuel surcharge actualizado | Alertar si índice >30 días |
|
||||
| TAR_005 | SLA definido para el cliente | Usar SLA por defecto |
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tabla DDL | Entity | Endpoint | US |
|
||||
|----|-----------|--------|----------|---|
|
||||
| RF-4.1.1 | tarifas, lanes | Tarifa, Lane | /tarifas | US-MAI002-001 |
|
||||
| RF-4.1.2 | tipos_recargo | TipoRecargo | /recargos | US-MAI002-002 |
|
||||
| RF-4.1.3 | sla_clientes | SLACliente | /sla | US-MAI002-003 |
|
||||
| RF-4.1.4 | cotizaciones | Cotizacion | /cotizaciones | US-MAI002-004 |
|
||||
| RF-4.1.5 | solicitudes_aprobacion | SolicitudAprobacion | /aprobaciones | US-MAI002-005 |
|
||||
|
||||
---
|
||||
|
||||
*MAI-002 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
233
docs/02-definicion-modulos/MAI-002-tarifas-sla/RESUMEN-EPICA.md
Normal file
233
docs/02-definicion-modulos/MAI-002-tarifas-sla/RESUMEN-EPICA.md
Normal file
@ -0,0 +1,233 @@
|
||||
# RESUMEN-EPICA.md - MAI-002: Tarifas, Contratos y SLA
|
||||
|
||||
**Código:** MAI-002
|
||||
**Nombre:** Tarifas, Contratos y SLA
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema
|
||||
|
||||
Las empresas transportistas enfrentan pérdidas por:
|
||||
- Cotizaciones inconsistentes entre vendedores
|
||||
- Recargos olvidados (fuel, demoras) no facturados
|
||||
- Tarifas desactualizadas que generan márgenes negativos
|
||||
- Descuentos sin control que erosionan rentabilidad
|
||||
- Incumplimiento de SLA sin consecuencias
|
||||
|
||||
### Solución
|
||||
|
||||
Un módulo de gestión comercial que:
|
||||
- Centraliza tarifario por lane/servicio
|
||||
- Automatiza cálculo de recargos
|
||||
- Documenta SLA con penalizaciones
|
||||
- Genera cotizaciones con desglose
|
||||
- Controla descuentos con flujos de aprobación
|
||||
|
||||
### Beneficios Esperados
|
||||
|
||||
| Beneficio | Métrica | Impacto |
|
||||
|-----------|---------|---------|
|
||||
| Recuperación de recargos | +15% ingresos por recargos | Rentabilidad |
|
||||
| Tiempo de cotización | -70% tiempo de respuesta | Productividad |
|
||||
| Control de descuentos | -50% descuentos excesivos | Margen |
|
||||
| Cumplimiento SLA | +20% OTIF | Satisfacción cliente |
|
||||
|
||||
---
|
||||
|
||||
## Actores y Stakeholders
|
||||
|
||||
### Usuarios Primarios
|
||||
|
||||
| Actor | Responsabilidad | Frecuencia |
|
||||
|-------|-----------------|------------|
|
||||
| Ejecutivo de Ventas | Crea cotizaciones, gestiona tarifas | Diaria |
|
||||
| Gerente Comercial | Aprueba descuentos, define políticas | Semanal |
|
||||
| Administrador | Configura recargos, actualiza índices | Mensual |
|
||||
|
||||
### Usuarios Secundarios
|
||||
|
||||
| Actor | Interés |
|
||||
|-------|---------|
|
||||
| Planner | Consulta tarifas para costeo de rutas |
|
||||
| Facturación | Usa tarifas para generar facturas |
|
||||
| Finanzas | Reportes de margen por cliente/lane |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SOLICITUD DE COTIZACIÓN │
|
||||
│ (Cliente pide precio de servicio) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. IDENTIFICAR SERVICIO (Ejecutivo de Ventas) │
|
||||
│ │
|
||||
│ Cliente: [Distribuidora ABC ▼] │
|
||||
│ │
|
||||
│ Origen: [CDMX - Bodega Norte ] │
|
||||
│ Destino: [Guadalajara - Centro ] │
|
||||
│ │
|
||||
│ Tipo de equipo: (●) Caja seca 53' ( ) Refrigerado ( ) Plat │
|
||||
│ Modalidad: (●) FTL ( ) LTL │
|
||||
│ Servicio: (●) Estándar ( ) Express │
|
||||
│ │
|
||||
│ [Buscar Tarifa] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. TARIFA ENCONTRADA │
|
||||
│ │
|
||||
│ Lane: CDMX → GDL (Zona Centro) │
|
||||
│ Distancia: 540 km │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Tarifa base: $12,500.00 MXN │ │
|
||||
│ │ Vigencia: 01-ene-2026 al 31-dic-2026 │ │
|
||||
│ │ Tipo: Por viaje (FTL) │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Continuar con Recargos] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. CALCULAR RECARGOS │
|
||||
│ │
|
||||
│ Recargos aplicables: │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ☑ Fuel Surcharge (8%) $1,000.00 │ │
|
||||
│ │ ☐ Maniobra de carga $800.00 │ │
|
||||
│ │ ☐ Maniobra de descarga $800.00 │ │
|
||||
│ │ ☑ Seguro adicional (0.5%) $250.00 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Subtotal recargos: $1,250.00 │
|
||||
│ │
|
||||
│ [Continuar] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. APLICAR DESCUENTO (Opcional) │
|
||||
│ │
|
||||
│ Subtotal: $13,750.00 MXN │
|
||||
│ │
|
||||
│ ¿Aplicar descuento? │
|
||||
│ Descuento: [5] % = $687.50 │
|
||||
│ │
|
||||
│ ✓ Dentro de tu límite (hasta 5%) │
|
||||
│ │
|
||||
│ Total cotización: $13,062.50 MXN │
|
||||
│ │
|
||||
│ [Generar Cotización] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 5. COTIZACIÓN GENERADA │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ COTIZACIÓN COT-2026-00456 │ │
|
||||
│ │ │ │
|
||||
│ │ Cliente: Distribuidora ABC │ │
|
||||
│ │ Servicio: CDMX → GDL | Caja seca 53' | FTL │ │
|
||||
│ │ │ │
|
||||
│ │ DESGLOSE: │ │
|
||||
│ │ Tarifa base (FTL CDMX→GDL) $12,500.00 │ │
|
||||
│ │ Fuel Surcharge (8%) $1,000.00 │ │
|
||||
│ │ Seguro adicional (0.5%) $250.00 │ │
|
||||
│ │ Subtotal $13,750.00 │ │
|
||||
│ │ Descuento (5%) -$687.50 │ │
|
||||
│ │ ───────────────────────────────────────────── │ │
|
||||
│ │ TOTAL $13,062.50 MXN │ │
|
||||
│ │ │ │
|
||||
│ │ Vigencia cotización: 7 días │ │
|
||||
│ │ Tiempo de entrega: 24-48 hrs │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Descargar PDF] [Enviar por email] [Convertir a OT] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ COTIZACIÓN ENVIADA │
|
||||
│ → Si acepta: Convertir a OT (MAI-003) │
|
||||
│ → Snapshot de tarifa guardado │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Éxito
|
||||
|
||||
### Funcionales
|
||||
|
||||
- [ ] CRUD de tarifas por lane
|
||||
- [ ] Matriz de recargos configurable
|
||||
- [ ] SLA por cliente documentado
|
||||
- [ ] Motor de cotización automático
|
||||
- [ ] Flujo de aprobación de descuentos
|
||||
- [ ] Snapshot de tarifa al crear OT
|
||||
|
||||
### Técnicos
|
||||
|
||||
- [ ] Búsqueda de tarifa <500ms
|
||||
- [ ] Histórico de cambios auditado
|
||||
- [ ] Soporte multi-moneda
|
||||
- [ ] Integración con API de mapas (opcional)
|
||||
|
||||
### Negocio
|
||||
|
||||
- [ ] 100% cotizaciones con desglose
|
||||
- [ ] 100% recargos aplicados según reglas
|
||||
- [ ] <10% descuentos fuera de política
|
||||
- [ ] Tiempo de cotización <5 minutos
|
||||
|
||||
---
|
||||
|
||||
## Riesgos y Mitigaciones
|
||||
|
||||
| Riesgo | Probabilidad | Impacto | Mitigación |
|
||||
|--------|--------------|---------|------------|
|
||||
| Tarifas no actualizadas | Alta | Alto | Alertas de vencimiento |
|
||||
| Índice fuel desactualizado | Media | Medio | Recordatorio mensual |
|
||||
| Descuentos excesivos | Media | Alto | Umbrales por rol |
|
||||
| Complejidad de lanes | Media | Medio | Zonas tarifarias |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Prerequisitos
|
||||
- erp-core/partners: Catálogo de clientes
|
||||
- erp-core/catalogs: Zonas, tipos de equipo
|
||||
|
||||
### Habilita
|
||||
- MAI-003 (OT): Precio de orden de transporte
|
||||
- MAI-009 (Facturación): Base para facturar
|
||||
|
||||
---
|
||||
|
||||
## Story Points Estimados
|
||||
|
||||
| Historia | Complejidad | SP |
|
||||
|----------|-------------|---|
|
||||
| US-MAI002-001 | Alta | 8 |
|
||||
| US-MAI002-002 | Media | 5 |
|
||||
| US-MAI002-003 | Media | 5 |
|
||||
| US-MAI002-004 | Alta | 8 |
|
||||
| US-MAI002-005 | Media | 5 |
|
||||
| **Total** | | **31** |
|
||||
|
||||
---
|
||||
|
||||
*Épica MAI-002 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,185 @@
|
||||
# US-MAI002-001: Definir tarifa por lane
|
||||
|
||||
**ID:** US-MAI002-001
|
||||
**Módulo:** MAI-002 (Tarifas y SLA)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** ejecutivo de ventas
|
||||
**Quiero** definir tarifas por lane (origen-destino) con diferentes tipos de servicio y vigencias
|
||||
**Para** tener un tarifario estructurado que permita cotizar rápidamente
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Crear tarifa básica
|
||||
**Dado** que necesito definir un precio para una ruta
|
||||
**Cuando** creo una nueva tarifa
|
||||
**Entonces** puedo especificar: lane (origen-destino), tipo de unidad, modalidad (FTL/LTL), precio base y vigencia
|
||||
|
||||
### CA-002: Definir lane por zona o ubicación específica
|
||||
**Dado** que algunos precios aplican a zonas completas
|
||||
**Cuando** defino el lane
|
||||
**Entonces** puedo elegir entre zona tarifaria (ej: "Zona Centro") o ubicación específica (ej: "CDMX Tepito")
|
||||
|
||||
### CA-003: Tipos de tarifa
|
||||
**Dado** que existen diferentes esquemas de cobro
|
||||
**Cuando** defino el tipo de tarifa
|
||||
**Entonces** puedo elegir: por viaje, por km, por tonelada, por pallet, o combinada
|
||||
|
||||
### CA-004: Tarifa específica por cliente
|
||||
**Dado** que algunos clientes tienen precios negociados
|
||||
**Cuando** creo una tarifa
|
||||
**Entonces** puedo asociarla a un cliente específico (aplica solo a ese cliente)
|
||||
|
||||
### CA-005: Control de vigencias
|
||||
**Dado** que las tarifas cambian con el tiempo
|
||||
**Cuando** defino vigencia
|
||||
**Entonces** el sistema solo aplica tarifas vigentes y alerta cuando están por vencer
|
||||
|
||||
### CA-006: Búsqueda de tarifa vigente
|
||||
**Dado** que necesito encontrar el precio para una ruta
|
||||
**Cuando** busco por origen, destino, tipo de unidad y cliente
|
||||
**Entonces** el sistema retorna la tarifa más específica vigente (cliente > general)
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ NUEVA TARIFA ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ INFORMACIÓN DEL LANE │
|
||||
│ │
|
||||
│ Origen │
|
||||
│ Tipo: (●) Zona tarifaria ( ) Ubicación específica │
|
||||
│ Zona: [Zona Metropolitana CDMX ▼] │
|
||||
│ │
|
||||
│ Destino │
|
||||
│ Tipo: (●) Zona tarifaria ( ) Ubicación específica │
|
||||
│ Zona: [Zona Centro (GDL, AGS, QRO)▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CONFIGURACIÓN DE TARIFA │
|
||||
│ │
|
||||
│ Tipo de unidad: [Tractocamión - Caja seca 53' ▼] │
|
||||
│ │
|
||||
│ Modalidad: (●) FTL (Carga completa) ( ) LTL (Consolidado) │
|
||||
│ │
|
||||
│ Servicio: (●) Estándar ( ) Express ( ) Mismo día │
|
||||
│ │
|
||||
│ Tipo de tarifa: [Por viaje (monto fijo) ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ PRECIO │
|
||||
│ │
|
||||
│ Precio base: [$12,500.00] Moneda: [MXN ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ VIGENCIA │
|
||||
│ │
|
||||
│ Fecha inicio: [2026-01-01] │
|
||||
│ Fecha fin: [2026-12-31] ☐ Sin fecha de fin │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ALCANCE │
|
||||
│ │
|
||||
│ (●) Tarifa general (todos los clientes) │
|
||||
│ ( ) Tarifa específica: [Seleccionar cliente...] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ [Cancelar] [Guardar Tarifa] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Lista de Tarifas
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TARIFARIO [+ Nueva]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Filtros: [Zona origen ▼] [Zona destino ▼] [Tipo unidad ▼] │
|
||||
│ [Modalidad ▼] [Estado: Vigente ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ CDMX → Zona Centro │ │
|
||||
│ │ Caja seca 53' | FTL | Estándar │ │
|
||||
│ │ $12,500.00 MXN por viaje │ │
|
||||
│ │ Vigente: 01-ene-2026 al 31-dic-2026 │ │
|
||||
│ │ Alcance: General [Editar]│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ CDMX → Zona Centro │ │
|
||||
│ │ Caja seca 53' | FTL | Estándar │ │
|
||||
│ │ $11,800.00 MXN por viaje │ │
|
||||
│ │ Vigente: 01-ene-2026 al 31-dic-2026 │ │
|
||||
│ │ Alcance: Distribuidora ABC (contrato) [Editar]│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Zona Norte → Zona Sur │ │
|
||||
│ │ Torton | FTL | Estándar │ │
|
||||
│ │ $18.00 MXN por km │ │
|
||||
│ │ Vigente: 15-feb-2026 al -- │ │
|
||||
│ │ Alcance: General [Editar]│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Mostrando 3 de 45 tarifas [< 1 2 3 4 5 >] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Tarifa
|
||||
|
||||
| Tipo | Campos requeridos | Ejemplo |
|
||||
|------|-------------------|---------|
|
||||
| Por viaje | precio_base | $12,500 por viaje |
|
||||
| Por km | precio_por_km | $18/km |
|
||||
| Por tonelada | precio_por_ton | $450/ton |
|
||||
| Por pallet | precio_por_pallet | $800/pallet |
|
||||
| Combinada | precio_base + precio_por_km | $8,000 + $12/km |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `tarifas` con `lane_id`, `tipo_unidad`, `modalidad`, `servicio`
|
||||
- Tabla: `lanes` con `origen_zona_id`, `destino_zona_id`
|
||||
- Tabla: `zonas_tarifarias` con polígono o lista de ubicaciones
|
||||
- Índice por (cliente_id, lane_id, tipo_unidad, modalidad, vigencia)
|
||||
- Soft delete para mantener histórico
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] CRUD completo de tarifas
|
||||
- [ ] Gestión de lanes por zona o ubicación
|
||||
- [ ] Soporte para todos los tipos de tarifa
|
||||
- [ ] Tarifa específica por cliente
|
||||
- [ ] Control de vigencias con alertas
|
||||
- [ ] Búsqueda de tarifa vigente más específica
|
||||
- [ ] Tests unitarios de búsqueda
|
||||
- [ ] Tests de integración
|
||||
|
||||
@ -0,0 +1,227 @@
|
||||
# US-MAI002-002: Configurar recargos (surcharges)
|
||||
|
||||
**ID:** US-MAI002-002
|
||||
**Módulo:** MAI-002 (Tarifas y SLA)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** administrador comercial
|
||||
**Quiero** configurar una matriz de recargos aplicables a los servicios de transporte
|
||||
**Para** asegurar que todos los costos adicionales se capturen y facturen correctamente
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Catálogo de tipos de recargo
|
||||
**Dado** que existen diferentes tipos de cargos adicionales
|
||||
**Cuando** configuro el catálogo
|
||||
**Entonces** puedo definir: nombre, código, descripción y tipo de cálculo (% o fijo)
|
||||
|
||||
### CA-002: Fuel surcharge con índice
|
||||
**Dado** que el fuel surcharge varía según el precio del combustible
|
||||
**Cuando** configuro este recargo
|
||||
**Entonces** puedo definir un índice actualizable (%) que se aplica sobre la tarifa base
|
||||
|
||||
### CA-003: Demoras (detention) con tolerancia
|
||||
**Dado** que las demoras en carga/descarga tienen un tiempo de gracia
|
||||
**Cuando** configuro detention
|
||||
**Entonces** puedo definir: tolerancia (horas), costo por hora adicional
|
||||
|
||||
### CA-004: Recargos por cliente
|
||||
**Dado** que algunos clientes tienen recargos específicos
|
||||
**Cuando** configuro recargos
|
||||
**Entonces** puedo asignarlos a clientes específicos o dejarlos como generales
|
||||
|
||||
### CA-005: Reglas de aplicación
|
||||
**Dado** que algunos recargos se aplican automáticamente y otros manualmente
|
||||
**Cuando** configuro un recargo
|
||||
**Entonces** puedo definir si es: automático (siempre aplica), condicional (según regla), o manual
|
||||
|
||||
### CA-006: Actualizar índice de combustible
|
||||
**Dado** que el precio del combustible cambia periódicamente
|
||||
**Cuando** actualizo el índice
|
||||
**Entonces** se registra con fecha y el sistema usa el índice vigente para nuevas cotizaciones
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CONFIGURACIÓN DE RECARGOS [+ Nuevo]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ÍNDICE DE COMBUSTIBLE (FUEL SURCHARGE) │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Índice actual: 8% │ │
|
||||
│ │ Última actualización: 2026-01-15 │ │
|
||||
│ │ Próxima revisión: 2026-02-15 │ │
|
||||
│ │ [Actualizar]│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TIPOS DE RECARGO │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ FUEL - Fuel Surcharge │ │
|
||||
│ │ Tipo: Porcentaje sobre base │ │
|
||||
│ │ Aplicación: Automática │ │
|
||||
│ │ Valor actual: 8% [Editar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ DETENTION_CARGA - Demora en carga │ │
|
||||
│ │ Tipo: Monto por hora │ │
|
||||
│ │ Tolerancia: 2 horas | Costo: $350/hora adicional │ │
|
||||
│ │ Aplicación: Condicional (si excede tolerancia) [Editar]│ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ DETENTION_DESCARGA - Demora en descarga │ │
|
||||
│ │ Tipo: Monto por hora │ │
|
||||
│ │ Tolerancia: 1.5 horas | Costo: $350/hora adicional │ │
|
||||
│ │ Aplicación: Condicional (si excede tolerancia) [Editar]│ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ MANIOBRA - Maniobra especial │ │
|
||||
│ │ Tipo: Monto fijo │ │
|
||||
│ │ Valor: $800.00 │ │
|
||||
│ │ Aplicación: Manual [Editar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ REENTREGA - Reentrega/Reexpedición │ │
|
||||
│ │ Tipo: Porcentaje sobre base │ │
|
||||
│ │ Valor: 30% │ │
|
||||
│ │ Aplicación: Manual [Editar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ESCOLTA - Escolta de seguridad │ │
|
||||
│ │ Tipo: Monto fijo │ │
|
||||
│ │ Valor: $5,000.00 │ │
|
||||
│ │ Aplicación: Manual [Editar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ SEGURO_ADICIONAL - Seguro extra │ │
|
||||
│ │ Tipo: Porcentaje sobre valor declarado │ │
|
||||
│ │ Valor: 0.5% │ │
|
||||
│ │ Aplicación: Condicional (si valor > $500K) [Editar] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Editar Recargo
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EDITAR RECARGO: DETENTION_CARGA ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ INFORMACIÓN BÁSICA │
|
||||
│ │
|
||||
│ Código: [DETENTION_CARGA] (no editable) │
|
||||
│ Nombre: [Demora en carga] │
|
||||
│ Descripción: [Cargo por tiempo excedido en punto de carga] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TIPO DE CÁLCULO │
|
||||
│ │
|
||||
│ ( ) Porcentaje sobre tarifa base │
|
||||
│ ( ) Monto fijo │
|
||||
│ (●) Monto por hora/unidad │
|
||||
│ ( ) Porcentaje sobre valor declarado │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CONFIGURACIÓN ESPECÍFICA │
|
||||
│ │
|
||||
│ Tolerancia: [2] horas (tiempo de gracia) │
|
||||
│ Costo por hora adicional: [$350.00] MXN │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ APLICACIÓN │
|
||||
│ │
|
||||
│ ( ) Automática (siempre se incluye) │
|
||||
│ (●) Condicional (se aplica si se cumple regla) │
|
||||
│ ( ) Manual (el usuario decide) │
|
||||
│ │
|
||||
│ Regla: [Tiempo en punto > tolerancia definida] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ALCANCE │
|
||||
│ │
|
||||
│ (●) General (todos los clientes) │
|
||||
│ ( ) Específico: [Seleccionar clientes...] │
|
||||
│ │
|
||||
│ [Cancelar] [Guardar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Historial de Índice Fuel
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ HISTORIAL ÍNDICE FUEL SURCHARGE ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Índice actual: 8% │
|
||||
│ │
|
||||
│ Nuevo índice: [ ] % [Aplicar] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ HISTORIAL │
|
||||
│ │
|
||||
│ | Fecha | Índice | Usuario | │
|
||||
│ |------------|--------|------------------| │
|
||||
│ | 2026-01-15 | 8.0% | admin@empresa.mx | │
|
||||
│ | 2025-12-15 | 7.5% | admin@empresa.mx | │
|
||||
│ | 2025-11-15 | 7.0% | admin@empresa.mx | │
|
||||
│ | 2025-10-15 | 7.5% | admin@empresa.mx | │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Catálogo de Recargos
|
||||
|
||||
| Código | Nombre | Cálculo | Aplicación |
|
||||
|--------|--------|---------|------------|
|
||||
| FUEL | Fuel Surcharge | % sobre base | Automática |
|
||||
| DETENTION_CARGA | Demora en carga | $/hora | Condicional |
|
||||
| DETENTION_DESCARGA | Demora en descarga | $/hora | Condicional |
|
||||
| MANIOBRA | Maniobra especial | Monto fijo | Manual |
|
||||
| REENTREGA | Reentrega | % sobre base | Manual |
|
||||
| ESCOLTA | Escolta seguridad | Monto fijo | Manual |
|
||||
| SEGURO_ADICIONAL | Seguro extra | % sobre valor | Condicional |
|
||||
| ALMACENAJE | Almacenaje temporal | $/día | Manual |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `tipos_recargo` para el catálogo
|
||||
- Tabla: `indice_combustible` para histórico de fuel surcharge
|
||||
- Tabla: `recargos_cliente` para configuraciones específicas por cliente
|
||||
- Los recargos condicionales se evalúan según reglas configurables
|
||||
- El índice fuel tiene trigger de actualización mensual
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] CRUD de tipos de recargo
|
||||
- [ ] Configuración de fuel surcharge con índice
|
||||
- [ ] Configuración de detention con tolerancia
|
||||
- [ ] Recargos por cliente
|
||||
- [ ] Reglas de aplicación (auto/condicional/manual)
|
||||
- [ ] Historial de cambios de índice fuel
|
||||
- [ ] Tests de cálculo de recargos
|
||||
|
||||
@ -0,0 +1,218 @@
|
||||
# US-MAI002-003: Definir SLA por cliente
|
||||
|
||||
**ID:** US-MAI002-003
|
||||
**Módulo:** MAI-002 (Tarifas y SLA)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** gerente comercial
|
||||
**Quiero** definir acuerdos de nivel de servicio (SLA) por cliente
|
||||
**Para** documentar los compromisos de tiempo y las consecuencias por incumplimiento
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Crear SLA por cliente
|
||||
**Dado** que tengo un cliente con contrato
|
||||
**Cuando** defino su SLA
|
||||
**Entonces** puedo especificar tiempos comprometidos de pickup y entrega
|
||||
|
||||
### CA-002: Definir tolerancias
|
||||
**Dado** que los tiempos tienen cierta flexibilidad
|
||||
**Cuando** configuro el SLA
|
||||
**Entonces** puedo definir tolerancia (minutos/horas de gracia) antes de considerar incumplimiento
|
||||
|
||||
### CA-003: Configurar penalizaciones
|
||||
**Dado** que el incumplimiento tiene consecuencias
|
||||
**Cuando** defino penalizaciones
|
||||
**Entonces** puedo especificar descuento o cargo (% o monto) por incumplimiento
|
||||
|
||||
### CA-004: Reglas de notificación
|
||||
**Dado** que queremos prevenir incumplimientos
|
||||
**Cuando** configuro alertas
|
||||
**Entonces** puedo definir cuándo notificar (ej: 2 hrs antes de vencer el SLA)
|
||||
|
||||
### CA-005: SLA por servicio/zona
|
||||
**Dado** que los tiempos varían según la ruta
|
||||
**Cuando** defino SLA
|
||||
**Entonces** puedo especificar diferentes tiempos por zona o tipo de servicio
|
||||
|
||||
### CA-006: Dashboard de cumplimiento
|
||||
**Dado** que necesito monitorear el desempeño
|
||||
**Cuando** consulto el dashboard
|
||||
**Entonces** veo el % de cumplimiento de SLA por cliente, periodo y causa de incumplimiento
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ DEFINIR SLA ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ CLIENTE Y ALCANCE │
|
||||
│ │
|
||||
│ Cliente: [Distribuidora ABC ▼] │
|
||||
│ │
|
||||
│ Alcance: │
|
||||
│ (●) General (todas las rutas) │
|
||||
│ ( ) Por zona destino: [Seleccionar zonas...] │
|
||||
│ ( ) Por servicio: [Seleccionar servicios...] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TIEMPOS COMPROMETIDOS │
|
||||
│ │
|
||||
│ Pickup (tiempo desde solicitud hasta recolección): │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Servicio estándar: [24] horas │ │
|
||||
│ │ Servicio express: [6] horas │ │
|
||||
│ │ Mismo día: [4] horas │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Entrega (tiempo desde pickup hasta entrega): │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Zona local (<200km): [24] horas │ │
|
||||
│ │ Zona regional (200-500km): [48] horas │ │
|
||||
│ │ Zona nacional (>500km): [72] horas │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TOLERANCIAS │
|
||||
│ │
|
||||
│ Tolerancia pickup: [30] minutos (gracia antes de incumplir) │
|
||||
│ Tolerancia entrega: [60] minutos │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ PENALIZACIONES │
|
||||
│ │
|
||||
│ Por incumplimiento de pickup: │
|
||||
│ Tipo: (●) Descuento ( ) Cargo │
|
||||
│ Valor: [3] % sobre el servicio │
|
||||
│ │
|
||||
│ Por incumplimiento de entrega: │
|
||||
│ Tipo: (●) Descuento ( ) Cargo │
|
||||
│ Valor: [5] % sobre el servicio │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ALERTAS Y NOTIFICACIONES │
|
||||
│ │
|
||||
│ ☑ Notificar al equipo [2] horas antes de vencer SLA │
|
||||
│ ☑ Notificar al cliente cuando SLA está en riesgo │
|
||||
│ ☑ Escalar a supervisor si falta [1] hora │
|
||||
│ │
|
||||
│ [Cancelar] [Guardar SLA] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dashboard de Cumplimiento
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CUMPLIMIENTO DE SLA │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Periodo: [Enero 2026 ▼] Cliente: [Todos ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN GENERAL │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ 94.2% │ │ 97.1% │ │ 91.3% │ │
|
||||
│ │ On-Time │ │ On-Time │ │ OTIF │ │
|
||||
│ │ Pickup │ │ Delivery │ │ (Completo) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ POR CLIENTE │
|
||||
│ │
|
||||
│ | Cliente | Viajes | Pickup | Entrega | OTIF | │
|
||||
│ |----------------------|--------|--------|---------|------| │
|
||||
│ | Distribuidora ABC | 145 | 96.5% | 98.2% | 94.5%| │
|
||||
│ | Comercial XYZ | 89 | 91.0% | 95.5% | 88.7%| │
|
||||
│ | Mayorista 123 | 67 | 94.0% | 97.0% | 91.0%| │
|
||||
│ | Retail Partners | 52 | 95.2% | 96.1% | 92.3%| │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ CAUSAS DE INCUMPLIMIENTO │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||||
│ │ Demora en carga (cliente) ████████████░░░░░░ 35% │ │
|
||||
│ │ Tráfico/accidente ███████░░░░░░░░░░░ 22% │ │
|
||||
│ │ Falta de unidad ██████░░░░░░░░░░░░ 18% │ │
|
||||
│ │ Rechazo en destino █████░░░░░░░░░░░░░ 15% │ │
|
||||
│ │ Problema mecánico ███░░░░░░░░░░░░░░░ 10% │ │
|
||||
│ └───────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Exportar reporte] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Lista de SLAs
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ACUERDOS DE NIVEL DE SERVICIO (SLA) [+ Nuevo]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Distribuidora ABC │ │
|
||||
│ │ Pickup: 24h (estándar) | Entrega: 48h (regional) │ │
|
||||
│ │ Penalización: 5% por incumplimiento │ │
|
||||
│ │ Cumplimiento actual: 94.5% [Editar]│ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ Comercial XYZ │ │
|
||||
│ │ Pickup: 12h (express) | Entrega: 24h (local) │ │
|
||||
│ │ Penalización: 3% + $500 fijo │ │
|
||||
│ │ Cumplimiento actual: 88.7% [Editar]│ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ SLA POR DEFECTO (clientes sin SLA específico) │ │
|
||||
│ │ Pickup: 48h | Entrega: 72h │ │
|
||||
│ │ Sin penalización automática │ │
|
||||
│ │ [Editar]│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `sla_clientes` con tiempos y tolerancias
|
||||
- Tabla: `sla_servicios` para SLA por tipo de servicio
|
||||
- Vista: `v_cumplimiento_sla` para dashboard
|
||||
- Trigger de alerta cuando SLA está por vencer
|
||||
- Las penalizaciones se registran en facturación (MAI-009)
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] CRUD de SLA por cliente
|
||||
- [ ] Configuración de tiempos por zona/servicio
|
||||
- [ ] Definición de tolerancias
|
||||
- [ ] Configuración de penalizaciones
|
||||
- [ ] Sistema de alertas previas
|
||||
- [ ] Dashboard de cumplimiento de SLA
|
||||
- [ ] Reporte de causas de incumplimiento
|
||||
- [ ] Tests de cálculo de cumplimiento
|
||||
|
||||
@ -0,0 +1,265 @@
|
||||
# US-MAI002-004: Generar cotización rápida
|
||||
|
||||
**ID:** US-MAI002-004
|
||||
**Módulo:** MAI-002 (Tarifas y SLA)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** ejecutivo de ventas
|
||||
**Quiero** generar cotizaciones rápidamente con cálculo automático de precios
|
||||
**Para** responder ágilmente a solicitudes de clientes y cerrar más negocios
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Buscar tarifa automáticamente
|
||||
**Dado** que ingreso origen, destino, tipo de unidad y cliente
|
||||
**Cuando** solicito cotizar
|
||||
**Entonces** el sistema encuentra la tarifa vigente más específica (cliente > general)
|
||||
|
||||
### CA-002: Calcular recargos automáticos
|
||||
**Dado** que hay recargos configurados como automáticos
|
||||
**Cuando** se genera la cotización
|
||||
**Entonces** el sistema aplica: fuel surcharge, y otros recargos automáticos
|
||||
|
||||
### CA-003: Agregar recargos manuales
|
||||
**Dado** que el servicio requiere cargos adicionales
|
||||
**Cuando** configuro la cotización
|
||||
**Entonces** puedo agregar manualmente: maniobras, escolta, seguro adicional, etc.
|
||||
|
||||
### CA-004: Mostrar desglose de precio
|
||||
**Dado** que el cliente necesita ver el detalle
|
||||
**Cuando** genero la cotización
|
||||
**Entonces** muestra: tarifa base, cada recargo con su monto, subtotal, descuento (si aplica), total
|
||||
|
||||
### CA-005: Aplicar descuento
|
||||
**Dado** que puedo ofrecer un descuento
|
||||
**Cuando** aplico un porcentaje
|
||||
**Entonces** si está dentro de mi límite se aplica; si excede, se envía a aprobación
|
||||
|
||||
### CA-006: Generar PDF profesional
|
||||
**Dado** que necesito enviar la cotización al cliente
|
||||
**Cuando** solicito el PDF
|
||||
**Entonces** genera un documento con logo, desglose, vigencia y condiciones
|
||||
|
||||
### CA-007: Convertir a OT
|
||||
**Dado** que el cliente acepta la cotización
|
||||
**Cuando** selecciono "Convertir a OT"
|
||||
**Entonces** se crea la OT con el snapshot de tarifa aplicada
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ NUEVA COTIZACIÓN ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ PASO 1: INFORMACIÓN DEL SERVICIO │
|
||||
│ │
|
||||
│ Cliente: [Distribuidora ABC ▼] [+ Nuevo] │
|
||||
│ Contacto: [Juan Pérez - Logística ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Origen: [Ciudad de México - Bodega Norte ] 📍 │
|
||||
│ Destino: [Guadalajara - Centro Distribución ] 📍 │
|
||||
│ │
|
||||
│ Distancia estimada: 540 km (automático) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Tipo de unidad: [Tractocamión - Caja seca 53' ▼] │
|
||||
│ Modalidad: (●) FTL ( ) LTL │
|
||||
│ Servicio: (●) Estándar ( ) Express ( ) Mismo día │
|
||||
│ │
|
||||
│ [Buscar Tarifa] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resultado de Tarifa
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ COTIZACIÓN - PASO 2: PRECIO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ TARIFA ENCONTRADA │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ✓ Tarifa específica para Distribuidora ABC │ │
|
||||
│ │ Lane: CDMX → GDL (Zona Centro) │ │
|
||||
│ │ Vigencia: 01-ene-2026 al 31-dic-2026 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DESGLOSE DE PRECIO │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Tarifa base (FTL Caja seca CDMX→GDL) $11,800.00 │ │
|
||||
│ │ │ │
|
||||
│ │ RECARGOS AUTOMÁTICOS: │ │
|
||||
│ │ + Fuel Surcharge (8%) $944.00 │ │
|
||||
│ │ │ │
|
||||
│ │ RECARGOS OPCIONALES: │ │
|
||||
│ │ ☐ Maniobra de carga $800.00 │ │
|
||||
│ │ ☐ Maniobra de descarga $800.00 │ │
|
||||
│ │ ☑ Seguro adicional (0.5% sobre $500K) $250.00 │ │
|
||||
│ │ ☐ Escolta de seguridad $5,000.00 │ │
|
||||
│ │ │ │
|
||||
│ │ ───────────────────────────────────────────────────── │ │
|
||||
│ │ Subtotal $12,994.00 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DESCUENTO │
|
||||
│ │
|
||||
│ Aplicar descuento: ☑ │
|
||||
│ Porcentaje: [5] % = $649.70 │
|
||||
│ ✓ Dentro de tu límite autorizado (hasta 5%) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ TOTAL COTIZACIÓN: $12,344.30 MXN │
|
||||
│ │
|
||||
│ [← Volver] [Generar Cotización] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cotización Generada
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ COTIZACIÓN COT-2026-00456 ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ [LOGO EMPRESA] │ │
|
||||
│ │ │ │
|
||||
│ │ COTIZACIÓN DE SERVICIO DE TRANSPORTE │ │
|
||||
│ │ No. COT-2026-00456 │ │
|
||||
│ │ Fecha: 27 de enero de 2026 │ │
|
||||
│ │ Vigencia: 7 días (hasta 03-feb-2026) │ │
|
||||
│ │ │ │
|
||||
│ │ CLIENTE │ │
|
||||
│ │ Distribuidora ABC S.A. de C.V. │ │
|
||||
│ │ Atención: Juan Pérez - Logística │ │
|
||||
│ │ │ │
|
||||
│ │ SERVICIO │ │
|
||||
│ │ Origen: CDMX - Bodega Norte │ │
|
||||
│ │ Destino: Guadalajara - Centro Distribución │ │
|
||||
│ │ Distancia: 540 km │ │
|
||||
│ │ Equipo: Tractocamión Caja seca 53' │ │
|
||||
│ │ Modalidad: FTL (Carga completa) │ │
|
||||
│ │ Servicio: Estándar (24-48 hrs) │ │
|
||||
│ │ │ │
|
||||
│ │ DESGLOSE │ │
|
||||
│ │ Tarifa base $11,800.00 │ │
|
||||
│ │ Fuel Surcharge (8%) $944.00 │ │
|
||||
│ │ Seguro adicional $250.00 │ │
|
||||
│ │ Subtotal $12,994.00 │ │
|
||||
│ │ Descuento (5%) -$649.70 │ │
|
||||
│ │ ───────────────────────────────────────────── │ │
|
||||
│ │ TOTAL $12,344.30 MXN │ │
|
||||
│ │ (Doce mil trescientos cuarenta y cuatro pesos 30/100) │ │
|
||||
│ │ │ │
|
||||
│ │ CONDICIONES │ │
|
||||
│ │ • Tiempo de entrega: 24-48 horas hábiles │ │
|
||||
│ │ • No incluye maniobras de carga/descarga │ │
|
||||
│ │ • Seguro incluido hasta $500,000 MXN │ │
|
||||
│ │ • Precio + IVA (16%) │ │
|
||||
│ │ │ │
|
||||
│ │ Cotización válida por 7 días. │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Descargar PDF] [Enviar por Email] [Convertir a OT] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Lista de Cotizaciones
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ COTIZACIONES [+ Nueva]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Filtros: [Este mes ▼] [Todos los estados ▼] [Mi equipo ▼] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ COT-2026-00456 | Distribuidora ABC │ │
|
||||
│ │ CDMX → GDL | $12,344.30 MXN │ │
|
||||
│ │ Creada: 27-ene-2026 | Vigencia: 03-feb-2026 │ │
|
||||
│ │ Estado: ⏳ PENDIENTE [Ver] [Convertir a OT] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ COT-2026-00455 | Comercial XYZ │ │
|
||||
│ │ MTY → CDMX | $18,500.00 MXN │ │
|
||||
│ │ Creada: 26-ene-2026 | Vigencia: 02-feb-2026 │ │
|
||||
│ │ Estado: ✅ ACEPTADA → OT-2026-00234 [Ver] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ COT-2026-00454 | Mayorista 123 │ │
|
||||
│ │ GDL → TIJ | $45,000.00 MXN │ │
|
||||
│ │ Creada: 25-ene-2026 | Vigencia: 01-feb-2026 │ │
|
||||
│ │ Estado: ❌ RECHAZADA (precio alto) [Ver] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Resumen: 15 pendientes | 8 aceptadas | 3 rechazadas | 2 vencidas│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados de Cotización
|
||||
|
||||
| Estado | Descripción |
|
||||
|--------|-------------|
|
||||
| BORRADOR | En proceso de creación |
|
||||
| PENDIENTE | Enviada al cliente, esperando respuesta |
|
||||
| ACEPTADA | Cliente aceptó, convertida a OT |
|
||||
| RECHAZADA | Cliente rechazó |
|
||||
| VENCIDA | Pasó la fecha de vigencia sin respuesta |
|
||||
| CANCELADA | Anulada por el vendedor |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `cotizaciones` con snapshot de tarifa aplicada
|
||||
- Tabla: `cotizacion_detalle` para el desglose
|
||||
- Tabla: `snapshot_tarifa` para guardar la tarifa al momento de cotizar
|
||||
- Generación de PDF con template HTML + puppeteer
|
||||
- Conversión a OT crea la orden con los mismos datos
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Búsqueda de tarifa por lane/cliente
|
||||
- [ ] Cálculo automático de recargos
|
||||
- [ ] Agregar recargos manuales
|
||||
- [ ] Desglose completo de precio
|
||||
- [ ] Aplicación de descuento con validación
|
||||
- [ ] Generación de PDF profesional
|
||||
- [ ] Envío por email
|
||||
- [ ] Conversión a OT
|
||||
- [ ] Gestión de estados (pendiente, aceptada, etc.)
|
||||
- [ ] Tests de cálculo de precios
|
||||
|
||||
@ -0,0 +1,268 @@
|
||||
# US-MAI002-005: Aprobar descuento excepcional
|
||||
|
||||
**ID:** US-MAI002-005
|
||||
**Módulo:** MAI-002 (Tarifas y SLA)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** gerente comercial
|
||||
**Quiero** aprobar o rechazar solicitudes de descuentos que excedan los límites autorizados
|
||||
**Para** mantener control sobre los márgenes y evitar erosión de rentabilidad
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Definir políticas de descuento
|
||||
**Dado** que necesito establecer límites por rol
|
||||
**Cuando** configuro las políticas
|
||||
**Entonces** puedo definir: rol, % máximo permitido, monto máximo, y si requiere aprobación
|
||||
|
||||
### CA-002: Solicitud automática de aprobación
|
||||
**Dado** que un vendedor aplica un descuento que excede su límite
|
||||
**Cuando** intenta guardar la cotización
|
||||
**Entonces** el sistema genera automáticamente una solicitud de aprobación
|
||||
|
||||
### CA-003: Notificación al aprobador
|
||||
**Dado** que hay una solicitud pendiente
|
||||
**Cuando** se crea
|
||||
**Entonces** el aprobador recibe notificación (email, app, dashboard)
|
||||
|
||||
### CA-004: Aprobar con justificación
|
||||
**Dado** que soy aprobador y reviso una solicitud
|
||||
**Cuando** decido aprobar
|
||||
**Entonces** debo registrar una justificación y la solicitud queda aprobada
|
||||
|
||||
### CA-005: Rechazar con motivo
|
||||
**Dado** que soy aprobador y la solicitud no procede
|
||||
**Cuando** decido rechazar
|
||||
**Entonces** registro el motivo y el vendedor es notificado
|
||||
|
||||
### CA-006: Escalamiento automático
|
||||
**Dado** que el descuento excede el límite de mi nivel de aprobación
|
||||
**Cuando** apruebo parcialmente o escalo
|
||||
**Entonces** la solicitud sube al siguiente nivel (supervisor → gerente → director)
|
||||
|
||||
### CA-007: Auditoría de aprobaciones
|
||||
**Dado** que necesito revisar el histórico
|
||||
**Cuando** consulto el reporte
|
||||
**Entonces** veo todas las aprobaciones/rechazos con fecha, usuario, justificación y monto
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ POLÍTICAS DE DESCUENTO [+ Nueva]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ LÍMITES POR ROL │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Vendedor Junior │ │
|
||||
│ │ Límite: hasta 3% o $500 MXN (lo que sea menor) │ │
|
||||
│ │ Aprobador: Vendedor Senior [Editar]│ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ Vendedor Senior │ │
|
||||
│ │ Límite: hasta 5% o $2,000 MXN │ │
|
||||
│ │ Aprobador: Gerente Comercial [Editar]│ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ Gerente Comercial │ │
|
||||
│ │ Límite: hasta 10% o $10,000 MXN │ │
|
||||
│ │ Aprobador: Director Comercial [Editar]│ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ Director Comercial │ │
|
||||
│ │ Límite: hasta 15% o $50,000 MXN │ │
|
||||
│ │ Aprobador: CEO (nivel final) [Editar]│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ REGLAS ADICIONALES │
|
||||
│ │
|
||||
│ ☑ Descuento > 10% siempre requiere justificación escrita │
|
||||
│ ☑ Descuento > $5,000 requiere aprobación de Finanzas │
|
||||
│ ☑ Cliente nuevo: límite reducido 50% (primeros 3 meses) │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Solicitud de Aprobación (Vendedor)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SOLICITAR APROBACIÓN DE DESCUENTO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ⚠ El descuento solicitado excede tu límite autorizado │
|
||||
│ │
|
||||
│ Tu límite: 5% ($2,000 MXN) │
|
||||
│ Descuento solicitado: 8% ($1,039.52) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DETALLE DE LA COTIZACIÓN │
|
||||
│ │
|
||||
│ Cotización: COT-2026-00457 │
|
||||
│ Cliente: Distribuidora ABC │
|
||||
│ Servicio: CDMX → GDL | $12,994.00 │
|
||||
│ Descuento solicitado: 8% = $1,039.52 │
|
||||
│ Total con descuento: $11,954.48 │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ JUSTIFICACIÓN (Obligatoria) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Cliente estratégico con 3 años de relación. Están │ │
|
||||
│ │ evaluando cotización de competidor con precio similar. │ │
|
||||
│ │ Potencial de 15 viajes mensuales si ganamos la cuenta. │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Aprobador: María González (Gerente Comercial) │
|
||||
│ │
|
||||
│ [Cancelar] [Enviar Solicitud] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bandeja de Aprobaciones (Gerente)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ APROBACIONES PENDIENTES (3) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ 🔴 URGENTE | Hace 15 min │ │
|
||||
│ │ │ │
|
||||
│ │ Solicitante: Pedro Ramírez (Vendedor Senior) │ │
|
||||
│ │ Cotización: COT-2026-00457 │ │
|
||||
│ │ Cliente: Distribuidora ABC │ │
|
||||
│ │ Descuento: 8% ($1,039.52) │ │
|
||||
│ │ │ │
|
||||
│ │ Justificación: │ │
|
||||
│ │ "Cliente estratégico con 3 años de relación. Están │ │
|
||||
│ │ evaluando cotización de competidor..." │ │
|
||||
│ │ │ │
|
||||
│ │ [Ver cotización completa] │ │
|
||||
│ │ │ │
|
||||
│ │ [❌ Rechazar] [⬆ Escalar] [✓ Aprobar] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ 🟡 NORMAL | Hace 2 horas │ │
|
||||
│ │ │ │
|
||||
│ │ Solicitante: Ana López (Vendedor Junior) │ │
|
||||
│ │ Cotización: COT-2026-00455 │ │
|
||||
│ │ Cliente: Comercial XYZ │ │
|
||||
│ │ Descuento: 5% ($925.00) │ │
|
||||
│ │ │ │
|
||||
│ │ [Ver detalle] [❌ Rechazar] [✓ Aprobar] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diálogo de Aprobación
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ APROBAR DESCUENTO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Cotización: COT-2026-00457 │
|
||||
│ Descuento solicitado: 8% ($1,039.52) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DECISIÓN │
|
||||
│ │
|
||||
│ (●) Aprobar el descuento solicitado (8%) │
|
||||
│ ( ) Aprobar parcialmente: [____] % │
|
||||
│ ( ) Rechazar │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ COMENTARIO (Obligatorio) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Aprobado. Cliente estratégico, el volumen proyectado │ │
|
||||
│ │ justifica el descuento. Revisar margen al cierre del │ │
|
||||
│ │ trimestre. │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Cancelar] [Confirmar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reporte de Auditoría
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AUDITORÍA DE DESCUENTOS │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Periodo: [Enero 2026 ▼] │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||||
│ │ 23 │ │ 18 │ │ 3 │ │ 2 │ │
|
||||
│ │ Solicitudes│ │ Aprobadas │ │ Rechazadas │ │ Pendientes │ │
|
||||
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
|
||||
│ │
|
||||
│ Monto total aprobado: $45,230.00 │
|
||||
│ Descuento promedio: 6.2% │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DETALLE │
|
||||
│ │
|
||||
│ | Fecha | Cotización | Solicitante | % | Monto | Estado |│
|
||||
│ |--------|------------|-------------|-----|---------|--------|│
|
||||
│ | 27-ene | COT-00457 | P. Ramírez | 8% | $1,039 | ✓ Apr. |│
|
||||
│ | 26-ene | COT-00455 | A. López | 5% | $925 | ✓ Apr. |│
|
||||
│ | 25-ene | COT-00452 | J. García | 12% | $3,500 | ❌ Rech.|│
|
||||
│ | 24-ene | COT-00448 | P. Ramírez | 6% | $780 | ✓ Apr. |│
|
||||
│ │
|
||||
│ [Exportar a Excel] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `politicas_descuento` con límites por rol
|
||||
- Tabla: `solicitudes_aprobacion` con estado (pendiente, aprobada, rechazada)
|
||||
- Tabla: `aprobaciones` con detalle de cada decisión
|
||||
- Notificaciones vía módulo de notificaciones (erp-core)
|
||||
- Auditoría completa con usuario, fecha y justificación
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] CRUD de políticas de descuento
|
||||
- [ ] Generación automática de solicitud si excede límite
|
||||
- [ ] Notificación a aprobadores
|
||||
- [ ] Flujo de aprobación/rechazo con justificación
|
||||
- [ ] Escalamiento a siguiente nivel
|
||||
- [ ] Reporte de auditoría de descuentos
|
||||
- [ ] Tests de flujo de aprobación
|
||||
- [ ] Tests de escalamiento
|
||||
|
||||
210
docs/02-definicion-modulos/MAI-004-planeacion/README.md
Normal file
210
docs/02-definicion-modulos/MAI-004-planeacion/README.md
Normal file
@ -0,0 +1,210 @@
|
||||
# MAI-004: Planeación TMS
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Estado:** Diseño
|
||||
**Prioridad:** P0 (Crítico - Workflow principal)
|
||||
|
||||
---
|
||||
|
||||
## Descripción General
|
||||
|
||||
El módulo de Planeación TMS (Transportation Management System) es responsable de convertir las Órdenes de Transporte en embarques y viajes factibles, optimizando la asignación de recursos (unidades, operadores, remolques) según capacidad, ventanas de tiempo y restricciones.
|
||||
|
||||
**Problema que resuelve:**
|
||||
- Asignación manual ineficiente de recursos
|
||||
- Subutilización de capacidad de unidades
|
||||
- Incumplimiento de ventanas de entrega
|
||||
- Falta de visibilidad de disponibilidad de flota
|
||||
|
||||
---
|
||||
|
||||
## Objetivos del Módulo
|
||||
|
||||
1. **Consolidación:** Agrupar OTs compatibles en embarques para optimizar capacidad
|
||||
2. **Asignación:** Seleccionar la mejor combinación unidad-operador-remolque
|
||||
3. **Validación:** Verificar que los recursos cumplen requisitos del servicio
|
||||
4. **Visibilidad:** Tablero de planeación con vista de recursos y OTs pendientes
|
||||
|
||||
---
|
||||
|
||||
## Alcance Funcional
|
||||
|
||||
### Incluido
|
||||
|
||||
- Tablero de planeación (vista Gantt/Kanban)
|
||||
- Consolidación de OTs en embarques
|
||||
- Cálculo de capacidad por unidad
|
||||
- Pre-asignación de recursos
|
||||
- Validación de compatibilidad operador-unidad-cliente
|
||||
- Estimación de ETA inicial
|
||||
- Generación de viajes planificados
|
||||
|
||||
### Excluido
|
||||
|
||||
- Optimización automática de rutas (MAA-019)
|
||||
- Despacho y liberación de viaje (MAI-005)
|
||||
- Tracking en tiempo real (MAI-006)
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el módulo |
|
||||
|-------|------------------|
|
||||
| Planner/Tráfico | Usuario principal, planifica y asigna |
|
||||
| Jefe de Flota | Consulta disponibilidad, bloquea recursos |
|
||||
| Ventas | Consulta capacidad para compromisos |
|
||||
| Sistema | Sugiere consolidaciones automáticas |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
OTs CONFIRMADAS
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. TABLERO DE PLANEACIÓN │
|
||||
│ - Vista por fecha/región/cliente │
|
||||
│ - OTs pendientes de asignar │
|
||||
│ - Recursos disponibles │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 2. CONSOLIDACIÓN │
|
||||
│ - Sistema sugiere agrupaciones │
|
||||
│ - Por zona, ventana, tipo equipo │
|
||||
│ - Planner acepta/modifica │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 3. VALIDACIÓN DE CAPACIDAD │
|
||||
│ - Peso vs capacidad unidad │
|
||||
│ - Volumen vs metros cúbicos │
|
||||
│ - Pallets vs posiciones │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 4. ASIGNACIÓN DE RECURSOS │
|
||||
│ - Seleccionar unidad disponible │
|
||||
│ - Seleccionar operador calificado │
|
||||
│ - Seleccionar remolque compatible │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 5. VALIDACIONES │
|
||||
│ ✓ Operador con licencia vigente │
|
||||
│ ✓ Unidad con documentos OK │
|
||||
│ ✓ Cumple requisitos del cliente │
|
||||
│ ✓ No hay conflicto de horarios │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 6. VIAJE PLANIFICADO │
|
||||
│ - Estado: PLANIFICADO │
|
||||
│ - Listo para despacho (MAI-005) │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Datos del Módulo
|
||||
|
||||
### Entidades Principales
|
||||
|
||||
| Entidad | Descripción | Estado |
|
||||
|---------|-------------|--------|
|
||||
| Embarque | Agrupación de OTs | NO IMPLEMENTADA |
|
||||
| Viaje | Ejecución planificada | NO IMPLEMENTADA |
|
||||
| AsignacionRecurso | Reserva de unidad/operador | NO IMPLEMENTADA |
|
||||
| CapacidadUnidad | Configuración de capacidad | NO IMPLEMENTADA |
|
||||
| ReglaAsignacion | Criterios de compatibilidad | NO IMPLEMENTADA |
|
||||
|
||||
### Campos Clave Viaje
|
||||
|
||||
| Campo | Tipo | Obligatorio | Descripción |
|
||||
|-------|------|-------------|-------------|
|
||||
| embarque_id | UUID | Sí | Embarque asociado |
|
||||
| unidad_id | UUID | Sí | Unidad asignada |
|
||||
| operador_id | UUID | Sí | Operador asignado |
|
||||
| remolque_id | UUID | No | Remolque si aplica |
|
||||
| fecha_salida_planificada | TIMESTAMP | Sí | Salida estimada |
|
||||
| fecha_llegada_planificada | TIMESTAMP | Sí | Llegada estimada |
|
||||
| status | ENUM | Sí | PLANIFICADO, DESPACHADO, etc. |
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md)
|
||||
|
||||
---
|
||||
|
||||
## Métricas del Módulo
|
||||
|
||||
| KPI | Fórmula | Meta |
|
||||
|-----|---------|------|
|
||||
| Utilización flota | % unidades en viaje | >75% |
|
||||
| Fill rate | Capacidad usada vs disponible | >85% |
|
||||
| Planificación exitosa | % OTs asignadas vs recibidas | >95% |
|
||||
| Tiempo de planeación | Promedio minutos por viaje | <15 min |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Este módulo depende de:
|
||||
- MAI-003 (OT): Recibe órdenes confirmadas
|
||||
- MAI-011 (Flota): Consulta disponibilidad de recursos
|
||||
- MAI-002 (Tarifas): Restricciones del cliente
|
||||
|
||||
### Otros módulos dependen de este:
|
||||
- MAI-005 (Despacho): Recibe viajes planificados
|
||||
- MAI-006 (Tracking): Inicia seguimiento del viaje
|
||||
|
||||
---
|
||||
|
||||
## Consideraciones Técnicas
|
||||
|
||||
### Performance
|
||||
- Consulta de disponibilidad debe responder en <2 segundos
|
||||
- Tablero debe manejar 500+ OTs sin degradación
|
||||
- Cálculo de consolidación en background
|
||||
|
||||
### Integraciones
|
||||
- Consulta de distancias/tiempos vía API de mapas
|
||||
- Sincronización con calendario de operadores
|
||||
- Webhook a notificaciones cuando se asigna recurso
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
Ver carpeta: [historias-usuario/](./historias-usuario/)
|
||||
|
||||
| US | Título | Prioridad |
|
||||
|----|--------|-----------|
|
||||
| US-MAI004-001 | Ver tablero de planeación | Alta |
|
||||
| US-MAI004-002 | Consolidar OTs en embarque | Alta |
|
||||
| US-MAI004-003 | Asignar unidad a viaje | Alta |
|
||||
| US-MAI004-004 | Validar compatibilidad de recursos | Alta |
|
||||
| US-MAI004-005 | Calcular ETA inicial | Media |
|
||||
|
||||
---
|
||||
|
||||
## Referencias
|
||||
|
||||
- REQ-GIRO-TRANSPORTISTA.md - Sección 4.3
|
||||
- MATRIZ-COHERENCIA-DDL-BACKEND.yml
|
||||
- MAPEO-RF-GIRO-A-MODULOS.yml
|
||||
|
||||
---
|
||||
|
||||
*Módulo MAI-004 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
223
docs/02-definicion-modulos/MAI-004-planeacion/REQUERIMIENTOS.md
Normal file
223
docs/02-definicion-modulos/MAI-004-planeacion/REQUERIMIENTOS.md
Normal file
@ -0,0 +1,223 @@
|
||||
# REQUERIMIENTOS.md - MAI-004: Planeación TMS
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.3
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.3.1: Tablero de Planeación
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe proveer un tablero visual (Gantt/Kanban) para ver OTs por fecha, ventana, estado, prioridad y región.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Vista Gantt muestra línea de tiempo con OTs y viajes
|
||||
2. Vista Kanban muestra OTs por estado (Pendiente, Asignada, Planificada)
|
||||
3. Filtros por: fecha, cliente, región, tipo de servicio, prioridad
|
||||
4. Drag & drop para mover OTs entre fechas/recursos
|
||||
5. Indicadores visuales de urgencia (SLA próximo a vencer)
|
||||
6. Panel lateral con detalle de OT seleccionada
|
||||
7. Vista de recursos disponibles por fecha
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `ordenes_transporte`, `viajes`, `embarques`
|
||||
- Vista: `v_tablero_planeacion`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/planeacion/tablero` - Datos del tablero
|
||||
- `GET /api/v1/planeacion/recursos-disponibles` - Recursos por fecha
|
||||
- `PUT /api/v1/ot/:id/fecha-planificada` - Mover OT de fecha
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.3.2: Consolidación Automática Sugerida
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe sugerir agrupaciones de OTs compatibles por zona, ventana de tiempo, capacidad y tipo de equipo.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Al seleccionar múltiples OTs, el sistema sugiere si son consolidables
|
||||
2. Criterios de consolidación configurables:
|
||||
- Misma zona de origen
|
||||
- Zona de destino cercana (radio configurable)
|
||||
- Ventanas de tiempo compatibles (overlap)
|
||||
- Mismo tipo de equipo requerido
|
||||
3. El sistema calcula capacidad total vs disponible
|
||||
4. El planner puede aceptar, modificar o rechazar sugerencia
|
||||
5. Se crea embarque al aceptar consolidación
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `embarques`
|
||||
- Campos: ot_ids[], capacidad_total, tipo_equipo
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/planeacion/sugerir-consolidacion` - Analizar OTs
|
||||
- `POST /api/v1/embarques` - Crear embarque
|
||||
- `PUT /api/v1/embarques/:id/agregar-ot` - Añadir OT a embarque
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.3.3: Cálculo de Capacidad
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe validar que la carga no exceda capacidad de la unidad por peso, volumen, pallets y altura.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Cada unidad tiene configurada su capacidad:
|
||||
- Peso máximo (toneladas)
|
||||
- Volumen máximo (m³)
|
||||
- Posiciones de pallet
|
||||
- Altura máxima de carga
|
||||
2. Al asignar OT/embarque, el sistema valida:
|
||||
- Suma de pesos ≤ capacidad peso
|
||||
- Suma de volúmenes ≤ capacidad volumen
|
||||
- Suma de pallets ≤ posiciones
|
||||
3. Alerta si se excede 90% de capacidad
|
||||
4. Bloquea si se excede 100%
|
||||
5. Considera restricciones especiales (temperatura, peligrosidad)
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `unidades` campos capacidad_*
|
||||
- Tabla: `ordenes_transporte` campos peso, volumen, pallets
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/unidades/:id/capacidad` - Consultar capacidad
|
||||
- `POST /api/v1/planeacion/validar-capacidad` - Validar asignación
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.3.4: Reservas de Recursos
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir pre-asignar unidad, operador y remolque con bloqueo de disponibilidad.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Al asignar recurso, se crea reserva con:
|
||||
- Fecha/hora inicio y fin estimados
|
||||
- Estado: RESERVADO
|
||||
2. El recurso no aparece disponible para otras asignaciones
|
||||
3. La reserva puede cancelarse liberando el recurso
|
||||
4. Conflictos de horario se detectan y alertan
|
||||
5. Vista de calendario por recurso muestra reservas
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `asignaciones`
|
||||
- Campos: recurso_tipo, recurso_id, viaje_id, fecha_inicio, fecha_fin, status
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/asignaciones` - Crear reserva
|
||||
- `DELETE /api/v1/asignaciones/:id` - Cancelar reserva
|
||||
- `GET /api/v1/recursos/:tipo/:id/calendario` - Ver calendario
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.3.5: Reglas de Compatibilidad
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe validar que el recurso asignado cumple requisitos del servicio y del cliente.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Validaciones de operador:
|
||||
- Licencia tipo requerido vigente
|
||||
- Certificaciones especiales (hazmat, doble articulado)
|
||||
- No está en lista negra del cliente
|
||||
- Horas de servicio disponibles
|
||||
2. Validaciones de unidad:
|
||||
- Tipo de equipo correcto (caja seca, refrigerada, plataforma)
|
||||
- Documentos vigentes (verificación, seguro, permiso SCT)
|
||||
- Cumple requisitos de cliente (GPS, antigüedad máxima)
|
||||
3. El sistema bloquea asignación si no cumple
|
||||
4. Opción de override con justificación (supervisor)
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `reglas_asignacion`
|
||||
- Tabla: `requisitos_cliente`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/planeacion/validar-compatibilidad` - Validar reglas
|
||||
- `GET /api/v1/clientes/:id/requisitos` - Requisitos del cliente
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.3.6: Simulación de Ruta y ETA
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe calcular estimación de tiempos y ETAs basado en distancias y velocidades promedio.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Cálculo de distancia entre origen y destinos
|
||||
2. Estimación de tiempo de tránsito:
|
||||
- Velocidad promedio por tipo de vía
|
||||
- Paradas programadas (descansos, combustible)
|
||||
- Ventanas de carga/descarga
|
||||
3. ETA por cada parada del itinerario
|
||||
4. Comparación ETA vs ventana comprometida (SLA)
|
||||
5. Alerta si ETA > ventana permitida
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `eta_calculado`
|
||||
- Campos: viaje_id, parada_id, eta_llegada, eta_salida
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/planeacion/calcular-eta` - Calcular ETAs
|
||||
- `GET /api/v1/viajes/:id/itinerario` - Ver itinerario con ETAs
|
||||
|
||||
**Prioridad:** Media
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Performance Tablero
|
||||
El tablero debe cargar en menos de 3 segundos con 500 OTs visibles.
|
||||
|
||||
### RNF-002: Concurrencia
|
||||
Múltiples planners pueden trabajar simultáneamente sin conflictos de asignación.
|
||||
|
||||
### RNF-003: Tiempo Real
|
||||
Los cambios de disponibilidad deben reflejarse en menos de 5 segundos.
|
||||
|
||||
### RNF-004: Usabilidad
|
||||
El flujo de asignación completo debe completarse en menos de 5 clics.
|
||||
|
||||
---
|
||||
|
||||
## Validaciones de Negocio
|
||||
|
||||
| Validación | Descripción | Acción si falla |
|
||||
|------------|-------------|-----------------|
|
||||
| PLN_001 | Capacidad no excedida | Bloquear asignación |
|
||||
| PLN_002 | Operador con licencia vigente | Bloquear asignación |
|
||||
| PLN_003 | Unidad con documentos OK | Bloquear asignación |
|
||||
| PLN_004 | Sin conflicto de horarios | Alertar, permitir override |
|
||||
| PLN_005 | ETA dentro de SLA | Alertar, permitir continuar |
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tabla DDL | Entity | Endpoint | US |
|
||||
|----|-----------|--------|----------|---|
|
||||
| RF-4.3.1 | v_tablero_planeacion | - | GET /planeacion/tablero | US-MAI004-001 |
|
||||
| RF-4.3.2 | embarques | Embarque | POST /embarques | US-MAI004-002 |
|
||||
| RF-4.3.3 | unidades | Unidad | POST /validar-capacidad | US-MAI004-003 |
|
||||
| RF-4.3.4 | asignaciones | AsignacionRecurso | POST /asignaciones | US-MAI004-003 |
|
||||
| RF-4.3.5 | reglas_asignacion | ReglaAsignacion | POST /validar-compatibilidad | US-MAI004-004 |
|
||||
| RF-4.3.6 | eta_calculado | ETACalculado | POST /calcular-eta | US-MAI004-005 |
|
||||
|
||||
---
|
||||
|
||||
*MAI-004 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
191
docs/02-definicion-modulos/MAI-004-planeacion/RESUMEN-EPICA.md
Normal file
191
docs/02-definicion-modulos/MAI-004-planeacion/RESUMEN-EPICA.md
Normal file
@ -0,0 +1,191 @@
|
||||
# RESUMEN-EPICA.md - MAI-004: Planeación TMS
|
||||
|
||||
**Código:** MAI-004
|
||||
**Nombre:** Planeación TMS
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema
|
||||
|
||||
Las empresas transportistas enfrentan:
|
||||
- Asignación manual que consume horas de trabajo
|
||||
- Unidades viajando con capacidad subutilizada
|
||||
- Incumplimiento de ventanas por mala planeación
|
||||
- Falta de visibilidad de recursos disponibles
|
||||
- Operadores asignados sin validar requisitos
|
||||
|
||||
### Solución
|
||||
|
||||
Un módulo TMS que:
|
||||
- Centraliza la planeación en un tablero visual
|
||||
- Sugiere consolidaciones para maximizar capacidad
|
||||
- Valida automáticamente compatibilidad de recursos
|
||||
- Calcula ETAs para anticipar problemas
|
||||
|
||||
### Beneficios Esperados
|
||||
|
||||
| Beneficio | Métrica | Impacto |
|
||||
|-----------|---------|---------|
|
||||
| Mejor utilización | +20% fill rate | Más ingresos por viaje |
|
||||
| Menos incumplimientos | -50% SLA missed | Retención clientes |
|
||||
| Productividad planner | -40% tiempo planeación | Costos operativos |
|
||||
| Menos errores | -80% asignaciones inválidas | Evita sanciones |
|
||||
|
||||
---
|
||||
|
||||
## Actores y Stakeholders
|
||||
|
||||
### Usuarios Primarios
|
||||
|
||||
| Actor | Responsabilidad | Frecuencia |
|
||||
|-------|-----------------|------------|
|
||||
| Planner/Tráfico | Planifica y asigna recursos | Continuo |
|
||||
| Jefe de Flota | Gestiona disponibilidad | Diario |
|
||||
| Supervisor | Aprueba excepciones | Bajo demanda |
|
||||
|
||||
### Usuarios Secundarios
|
||||
|
||||
| Actor | Interés |
|
||||
|-------|---------|
|
||||
| Ventas | Consulta capacidad para compromisos |
|
||||
| Despacho | Recibe viajes planificados |
|
||||
| Gerencia | Métricas de utilización |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ OTs CONFIRMADAS PARA PLANIFICAR │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. TABLERO DE PLANEACIÓN │
|
||||
│ │
|
||||
│ ┌──────────────────┐ ┌──────────────────────────────────┐ │
|
||||
│ │ OTs Pendientes │ │ GANTT / CALENDARIO │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ □ OT-001 CDMX │ │ Lun Mar Mie Jue Vie │ │
|
||||
│ │ □ OT-002 GDL │ │ ════ ════ ════ ════ ════ │ │
|
||||
│ │ □ OT-003 MTY │ │ U-01 ▓▓▓▓ ░░░░ ▓▓▓▓ │ │
|
||||
│ │ □ OT-004 CDMX │ │ U-02 ▓▓▓▓▓▓▓▓▓ │ │
|
||||
│ │ │ │ U-03 ░░░░░░░░░░░░ │ │
|
||||
│ └──────────────────┘ └──────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Seleccionar OTs] [Sugerir Consolidación] [Asignar] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. CONSOLIDACIÓN │
|
||||
│ │
|
||||
│ Sistema detecta OTs consolidables: │
|
||||
│ • OT-001 y OT-004: Mismo origen (CDMX), destinos cercanos │
|
||||
│ • Ventanas compatibles: 8:00-12:00 y 10:00-14:00 │
|
||||
│ • Capacidad combinada: 12 ton (Unidad: 18 ton) ✓ │
|
||||
│ │
|
||||
│ [Crear Embarque EMB-001] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. ASIGNACIÓN DE RECURSOS │
|
||||
│ │
|
||||
│ Embarque: EMB-001 (OT-001 + OT-004) │
|
||||
│ │
|
||||
│ Unidad: [U-05 Kenworth T680 ▼] ✓ Disponible │
|
||||
│ Operador: [Juan Pérez García ▼] ✓ Licencia OK │
|
||||
│ Remolque: [R-12 Caja Seca 53' ▼] ✓ Documentos OK │
|
||||
│ │
|
||||
│ Validaciones: │
|
||||
│ ✓ Capacidad: 12/18 ton (67%) │
|
||||
│ ✓ Operador autorizado para cliente │
|
||||
│ ✓ Unidad cumple requisitos GPS │
|
||||
│ ✓ Sin conflicto de horarios │
|
||||
│ │
|
||||
│ [Cancelar] [Crear Viaje Planificado] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VIAJE VJE-001 PLANIFICADO │
|
||||
│ │
|
||||
│ Fecha salida: 2026-01-28 06:00 │
|
||||
│ ETA Destino 1: 2026-01-28 10:30 │
|
||||
│ ETA Destino 2: 2026-01-28 14:00 │
|
||||
│ │
|
||||
│ → Listo para Despacho (MAI-005) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Éxito
|
||||
|
||||
### Funcionales
|
||||
|
||||
- [ ] Tablero carga en <3 segundos
|
||||
- [ ] Sugerencia de consolidación funciona correctamente
|
||||
- [ ] Validaciones bloquean asignaciones inválidas
|
||||
- [ ] ETA calculado con precisión ±30 minutos
|
||||
|
||||
### Técnicos
|
||||
|
||||
- [ ] Soporte para 500+ OTs en tablero
|
||||
- [ ] Concurrencia sin conflictos
|
||||
- [ ] Integración con API de mapas
|
||||
- [ ] Cache de disponibilidad
|
||||
|
||||
### Negocio
|
||||
|
||||
- [ ] >75% utilización de flota
|
||||
- [ ] >85% fill rate promedio
|
||||
- [ ] <15 minutos por asignación
|
||||
- [ ] <5% asignaciones con override
|
||||
|
||||
---
|
||||
|
||||
## Riesgos y Mitigaciones
|
||||
|
||||
| Riesgo | Probabilidad | Impacto | Mitigación |
|
||||
|--------|--------------|---------|------------|
|
||||
| Performance tablero | Media | Alto | Paginación, lazy loading |
|
||||
| Conflictos concurrencia | Media | Alto | Bloqueo optimista |
|
||||
| Datos de capacidad incorrectos | Baja | Alto | Validación en carga |
|
||||
| API mapas no disponible | Baja | Medio | Cache de distancias |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Prerequisitos
|
||||
- MAI-003 (OT): OTs confirmadas disponibles
|
||||
- MAI-011 (Flota): Datos de unidades y operadores
|
||||
- MAI-002 (Tarifas): Requisitos del cliente
|
||||
|
||||
### Habilita
|
||||
- MAI-005 (Despacho): Viajes planificados para despachar
|
||||
- MAI-006 (Tracking): Inicio de seguimiento
|
||||
|
||||
---
|
||||
|
||||
## Story Points Estimados
|
||||
|
||||
| Historia | Complejidad | SP |
|
||||
|----------|-------------|---|
|
||||
| US-MAI004-001 | Alta | 13 |
|
||||
| US-MAI004-002 | Alta | 8 |
|
||||
| US-MAI004-003 | Alta | 8 |
|
||||
| US-MAI004-004 | Media | 5 |
|
||||
| US-MAI004-005 | Media | 5 |
|
||||
| **Total** | | **39** |
|
||||
|
||||
---
|
||||
|
||||
*Épica MAI-004 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,96 @@
|
||||
# US-MAI004-001: Ver tablero de planeación
|
||||
|
||||
**ID:** US-MAI004-001
|
||||
**Módulo:** MAI-004 (Planeación TMS)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 13
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** planner de tráfico
|
||||
**Quiero** ver un tablero visual con todas las OTs pendientes y recursos disponibles
|
||||
**Para** planificar eficientemente las asignaciones del día
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Vista Gantt
|
||||
**Dado** que accedo al módulo de planeación
|
||||
**Cuando** selecciono vista Gantt
|
||||
**Entonces** veo una línea de tiempo con unidades en filas y días en columnas, mostrando viajes programados
|
||||
|
||||
### CA-002: Vista Kanban
|
||||
**Dado** que prefiero organizar por estado
|
||||
**Cuando** selecciono vista Kanban
|
||||
**Entonces** veo columnas: Pendiente, En Planeación, Planificado, Despachado
|
||||
|
||||
### CA-003: Panel de OTs pendientes
|
||||
**Dado** que hay OTs sin asignar
|
||||
**Cuando** veo el tablero
|
||||
**Entonces** aparece un panel lateral con lista de OTs pendientes de planificar
|
||||
|
||||
### CA-004: Filtros
|
||||
**Dado** que tengo muchas OTs
|
||||
**Cuando** aplico filtros (fecha, cliente, región, prioridad)
|
||||
**Entonces** el tablero muestra solo OTs que cumplen los criterios
|
||||
|
||||
### CA-005: Detalle de OT
|
||||
**Dado** que quiero ver información de una OT
|
||||
**Cuando** hago clic en ella
|
||||
**Entonces** se abre panel con detalles: cliente, origen, destino, carga, restricciones
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ PLANEACIÓN TMS [Gantt] [Kanban] │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ Filtros: [Fecha ▼] [Cliente ▼] [Región ▼] [Prioridad ▼] [Buscar...] │
|
||||
├─────────────────────┬───────────────────────────────────────────────────┤
|
||||
│ OTs PENDIENTES (12) │ CALENDARIO SEMANAL │
|
||||
│ │ Recurso │ Lun 27 │ Mar 28 │ Mie 29 │ Jue 30 │
|
||||
│ ┌─────────────────┐ │ ─────────┼────────┼────────┼────────┼──────── │
|
||||
│ │ 🔴 OT-1234 │ │ U-001 │ ▓▓▓▓▓▓ │ │ ▓▓▓▓ │ │
|
||||
│ │ CDMX → GDL │ │ U-002 │ │ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │ │
|
||||
│ │ 8 ton, 28 ene │ │ U-003 │ ░░░░ │ │ │ ▓▓▓▓▓▓ │
|
||||
│ └─────────────────┘ │ U-004 │ │ ▓▓▓ │ │ │
|
||||
│ ┌─────────────────┐ │ U-005 │ DISP. │ DISP. │ DISP. │ DISP. │
|
||||
│ │ 🟡 OT-1235 │ │ │ │ │ │ │
|
||||
│ │ MTY → CDMX │ │ ▓▓▓ = Asignado ░░░ = Mantenimiento │
|
||||
│ │ 5 ton, 29 ene │ │ │
|
||||
│ └─────────────────┘ │ │
|
||||
│ ┌─────────────────┐ │───────────────────────────────────────────────────│
|
||||
│ │ 🟢 OT-1236 │ │ RECURSOS DISPONIBLES (28 ene) │
|
||||
│ │ GDL → TIJ │ │ Unidades: 5/12 Operadores: 8/15 Remolques: 10 │
|
||||
│ │ 12 ton, 30 ene │ │ │
|
||||
│ └─────────────────┘ │ │
|
||||
└─────────────────────┴───────────────────────────────────────────────────┘
|
||||
|
||||
🔴 Urgente (SLA <24h) 🟡 Normal 🟢 Flexible
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Usar biblioteca de Gantt (DHTMLX, Bryntum, o similar)
|
||||
- Carga lazy de semanas para performance
|
||||
- WebSocket para actualizaciones en tiempo real
|
||||
- Cache de disponibilidad con TTL de 30 segundos
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Vista Gantt funcional
|
||||
- [ ] Vista Kanban funcional
|
||||
- [ ] Panel de OTs pendientes
|
||||
- [ ] Filtros implementados
|
||||
- [ ] Detalle de OT en panel lateral
|
||||
- [ ] Performance <3s con 500 OTs
|
||||
- [ ] Tests E2E
|
||||
@ -0,0 +1,110 @@
|
||||
# US-MAI004-002: Consolidar OTs en embarque
|
||||
|
||||
**ID:** US-MAI004-002
|
||||
**Módulo:** MAI-004 (Planeación TMS)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** planner de tráfico
|
||||
**Quiero** que el sistema sugiera qué OTs puedo consolidar en un mismo viaje
|
||||
**Para** maximizar la utilización de capacidad de las unidades
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Selección múltiple
|
||||
**Dado** que hay OTs con características similares
|
||||
**Cuando** selecciono 2 o más OTs en el tablero
|
||||
**Entonces** se habilita el botón "Sugerir Consolidación"
|
||||
|
||||
### CA-002: Análisis de compatibilidad
|
||||
**Dado** que solicito sugerencia de consolidación
|
||||
**Cuando** el sistema analiza las OTs
|
||||
**Entonces** verifica: zona origen similar, destinos cercanos, ventanas compatibles, mismo tipo equipo
|
||||
|
||||
### CA-003: Resultado positivo
|
||||
**Dado** que las OTs son consolidables
|
||||
**Cuando** veo el resultado
|
||||
**Entonces** muestra: capacidad combinada, ahorro estimado, y botón "Crear Embarque"
|
||||
|
||||
### CA-004: Resultado negativo
|
||||
**Dado** que las OTs no son consolidables
|
||||
**Cuando** veo el resultado
|
||||
**Entonces** muestra el motivo: "Ventanas incompatibles", "Destinos muy lejanos", etc.
|
||||
|
||||
### CA-005: Creación de embarque
|
||||
**Dado** que acepto la sugerencia
|
||||
**Cuando** confirmo crear embarque
|
||||
**Entonces** se crea EMB con las OTs agrupadas y aparece en el tablero
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ANÁLISIS DE CONSOLIDACIÓN [X]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ OTs Seleccionadas: │
|
||||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||||
│ │ OT-1234 │ CDMX → GDL │ 8 ton │ Ventana 8:00-12:00 │ │
|
||||
│ │ OT-1237 │ CDMX → GDL Sur │ 4 ton │ Ventana 9:00-14:00 │ │
|
||||
│ └───────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ✅ CONSOLIDACIÓN RECOMENDADA │
|
||||
│ │
|
||||
│ Criterios cumplidos: │
|
||||
│ ✓ Mismo origen: CDMX │
|
||||
│ ✓ Destinos cercanos: 15 km entre GDL y GDL Sur │
|
||||
│ ✓ Ventanas compatibles: Overlap 9:00-12:00 │
|
||||
│ ✓ Mismo tipo equipo: Caja seca │
|
||||
│ │
|
||||
│ Capacidad combinada: 12 toneladas │
|
||||
│ Unidad sugerida: Caja seca 18 ton (67% utilización) │
|
||||
│ │
|
||||
│ 💰 Ahorro estimado: $2,500 vs 2 viajes separados │
|
||||
│ │
|
||||
│ [Cancelar] [Crear Embarque EMB-0089] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reglas de Consolidación
|
||||
|
||||
| Criterio | Condición | Peso |
|
||||
|----------|-----------|------|
|
||||
| Mismo origen | Distancia < 20km | Obligatorio |
|
||||
| Destinos cercanos | Distancia < 50km | Obligatorio |
|
||||
| Ventanas compatibles | Overlap > 2 horas | Obligatorio |
|
||||
| Mismo tipo equipo | Match exacto | Obligatorio |
|
||||
| Mismo cliente | Preferido | Opcional |
|
||||
| Capacidad disponible | Sum < 100% unidad | Obligatorio |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Algoritmo de clustering por zona geográfica
|
||||
- Cálculo de distancias vía API de mapas (cache)
|
||||
- El ahorro se calcula: 2*tarifa_individual - tarifa_consolidada
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Selección múltiple de OTs
|
||||
- [ ] Algoritmo de análisis implementado
|
||||
- [ ] UI de resultado con detalles
|
||||
- [ ] Creación de embarque funcional
|
||||
- [ ] Cálculo de ahorro estimado
|
||||
- [ ] Tests unitarios del algoritmo
|
||||
@ -0,0 +1,118 @@
|
||||
# US-MAI004-003: Asignar unidad a viaje
|
||||
|
||||
**ID:** US-MAI004-003
|
||||
**Módulo:** MAI-004 (Planeación TMS)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** planner de tráfico
|
||||
**Quiero** asignar unidad, operador y remolque a un embarque/viaje
|
||||
**Para** crear el viaje planificado listo para despacho
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Selector de unidad
|
||||
**Dado** que tengo un embarque para asignar
|
||||
**Cuando** abro el selector de unidad
|
||||
**Entonces** veo solo unidades disponibles en las fechas requeridas con capacidad suficiente
|
||||
|
||||
### CA-002: Selector de operador
|
||||
**Dado** que seleccioné una unidad
|
||||
**Cuando** abro el selector de operador
|
||||
**Entonces** veo solo operadores disponibles con licencia vigente y calificados
|
||||
|
||||
### CA-003: Selector de remolque
|
||||
**Dado** que el viaje requiere remolque
|
||||
**Cuando** abro el selector
|
||||
**Entonces** veo remolques disponibles del tipo correcto
|
||||
|
||||
### CA-004: Validación de capacidad
|
||||
**Dado** que asigno recursos
|
||||
**Cuando** la capacidad de la unidad es menor al peso total
|
||||
**Entonces** el sistema bloquea y muestra "Capacidad insuficiente"
|
||||
|
||||
### CA-005: Creación de viaje
|
||||
**Dado** que todos los recursos están asignados y validados
|
||||
**Cuando** confirmo la asignación
|
||||
**Entonces** se crea viaje en estado PLANIFICADO con reservas de recursos
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ASIGNAR RECURSOS - EMB-0089 [X]│
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Embarque: 2 OTs | 12 ton | CDMX → GDL/GDL Sur │
|
||||
│ Fecha requerida: 28 Ene 2026 | Tipo equipo: Caja Seca │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ UNIDAD * │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ U-005 Kenworth T680 | Caja Seca 18 ton | ✓ Disponible ▼│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ Capacidad: 12/18 ton (67%) ✓ │
|
||||
│ │
|
||||
│ OPERADOR * │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Juan Pérez García | Lic. Federal A | ✓ Vigente ▼│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ HOS disponibles: 11 hrs ✓ │
|
||||
│ │
|
||||
│ REMOLQUE (Opcional) │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Seleccionar remolque... ▼│ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN DE VALIDACIONES │
|
||||
│ ✓ Capacidad OK │
|
||||
│ ✓ Operador calificado │
|
||||
│ ✓ Unidad con documentos vigentes │
|
||||
│ ✓ Sin conflicto de horarios │
|
||||
│ │
|
||||
│ [Cancelar] [Crear Viaje Planificado] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Filtros de Disponibilidad
|
||||
|
||||
| Recurso | Criterios de filtrado |
|
||||
|---------|----------------------|
|
||||
| Unidad | Disponible en fecha, tipo equipo, capacidad suficiente, documentos OK |
|
||||
| Operador | Disponible en fecha, licencia vigente, HOS suficiente, no en lista negra |
|
||||
| Remolque | Disponible en fecha, tipo compatible, documentos OK |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Los selectores usan búsqueda con autocomplete
|
||||
- La disponibilidad se consulta en tiempo real
|
||||
- Al crear viaje se crean registros en `asignaciones`
|
||||
- Notificación push al operador asignado
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Selector de unidad con filtros
|
||||
- [ ] Selector de operador con filtros
|
||||
- [ ] Selector de remolque con filtros
|
||||
- [ ] Validación de capacidad
|
||||
- [ ] Creación de viaje y reservas
|
||||
- [ ] Notificación al operador
|
||||
- [ ] Tests de integración
|
||||
@ -0,0 +1,113 @@
|
||||
# US-MAI004-004: Validar compatibilidad de recursos
|
||||
|
||||
**ID:** US-MAI004-004
|
||||
**Módulo:** MAI-004 (Planeación TMS)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** planner de tráfico
|
||||
**Quiero** que el sistema valide automáticamente que los recursos cumplen todos los requisitos
|
||||
**Para** evitar asignar operadores o unidades que no están calificados para el servicio
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Validación de operador
|
||||
**Dado** que asigno un operador
|
||||
**Cuando** el sistema valida
|
||||
**Entonces** verifica: licencia vigente, certificaciones requeridas, HOS disponibles, no en lista negra del cliente
|
||||
|
||||
### CA-002: Validación de unidad
|
||||
**Dado** que asigno una unidad
|
||||
**Cuando** el sistema valida
|
||||
**Entonces** verifica: documentos vigentes, cumple requisitos del cliente (GPS, antigüedad), tipo equipo correcto
|
||||
|
||||
### CA-003: Bloqueo por incumplimiento
|
||||
**Dado** que un recurso no cumple validación obligatoria
|
||||
**Cuando** intento confirmar asignación
|
||||
**Entonces** el sistema bloquea y muestra el motivo específico
|
||||
|
||||
### CA-004: Advertencia
|
||||
**Dado** que un recurso cumple pero con observaciones
|
||||
**Cuando** intento confirmar
|
||||
**Entonces** el sistema muestra advertencia pero permite continuar
|
||||
|
||||
### CA-005: Override con autorización
|
||||
**Dado** que necesito asignar un recurso que no cumple
|
||||
**Cuando** un supervisor autoriza el override
|
||||
**Entonces** se permite la asignación con registro de justificación
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VALIDACIÓN DE RECURSOS │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ OPERADOR: Juan Pérez García │
|
||||
│ ├─ ✓ Licencia Federal A vigente hasta 2027-05-15 │
|
||||
│ ├─ ✓ Certificación materiales peligrosos │
|
||||
│ ├─ ✓ HOS disponibles: 11 hrs (requerido: 8 hrs) │
|
||||
│ └─ ✓ No está en lista negra del cliente │
|
||||
│ │
|
||||
│ UNIDAD: U-005 Kenworth T680 │
|
||||
│ ├─ ✓ Verificación vigente hasta 2026-06-30 │
|
||||
│ ├─ ✓ Seguro vigente hasta 2026-12-31 │
|
||||
│ ├─ ✓ Permiso SCT vigente │
|
||||
│ ├─ ✓ GPS instalado y activo │
|
||||
│ └─ ⚠ Antigüedad: 6 años (cliente pide <5 años) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ⚠ 1 ADVERTENCIA ENCONTRADA │
|
||||
│ │
|
||||
│ La unidad excede la antigüedad requerida por el cliente. │
|
||||
│ Puede continuar pero se registrará como excepción. │
|
||||
│ │
|
||||
│ [Cancelar] [Solicitar Override] [Continuar con Advertencia] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Catálogo de Validaciones
|
||||
|
||||
| Código | Validación | Tipo | Aplica a |
|
||||
|--------|------------|------|----------|
|
||||
| VAL-001 | Licencia vigente | Bloqueante | Operador |
|
||||
| VAL-002 | Certificación requerida | Bloqueante | Operador |
|
||||
| VAL-003 | HOS suficientes | Bloqueante | Operador |
|
||||
| VAL-004 | Lista negra cliente | Bloqueante | Operador |
|
||||
| VAL-005 | Documentos unidad | Bloqueante | Unidad |
|
||||
| VAL-006 | GPS activo | Bloqueante | Unidad |
|
||||
| VAL-007 | Antigüedad máxima | Advertencia | Unidad |
|
||||
| VAL-008 | Tipo equipo correcto | Bloqueante | Unidad |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Las reglas se almacenan en `requisitos_cliente` y `reglas_asignacion`
|
||||
- El override requiere rol de supervisor
|
||||
- Todos los overrides se registran en auditoría
|
||||
- Las validaciones se ejecutan en tiempo real
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Validaciones de operador implementadas
|
||||
- [ ] Validaciones de unidad implementadas
|
||||
- [ ] UI de resultado de validaciones
|
||||
- [ ] Bloqueo por incumplimiento
|
||||
- [ ] Flujo de override con supervisor
|
||||
- [ ] Registro en auditoría
|
||||
- [ ] Tests de cada validación
|
||||
@ -0,0 +1,125 @@
|
||||
# US-MAI004-005: Calcular ETA inicial
|
||||
|
||||
**ID:** US-MAI004-005
|
||||
**Módulo:** MAI-004 (Planeación TMS)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** planner de tráfico
|
||||
**Quiero** que el sistema calcule los ETAs estimados para cada parada del viaje
|
||||
**Para** validar que puedo cumplir las ventanas comprometidas con el cliente
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Cálculo de distancia
|
||||
**Dado** que tengo un viaje con origen y destinos
|
||||
**Cuando** solicito calcular ETA
|
||||
**Entonces** el sistema obtiene distancias vía API de mapas
|
||||
|
||||
### CA-002: Estimación de tiempo
|
||||
**Dado** que tengo las distancias
|
||||
**Cuando** el sistema calcula tiempos
|
||||
**Entonces** considera: velocidad promedio por tipo de vía, paradas de descanso, tiempo en cada parada
|
||||
|
||||
### CA-003: Itinerario con ETAs
|
||||
**Dado** que el cálculo está completo
|
||||
**Cuando** veo el resultado
|
||||
**Entonces** muestra itinerario con ETA de llegada y salida de cada punto
|
||||
|
||||
### CA-004: Comparación con SLA
|
||||
**Dado** que tengo ETAs calculados
|
||||
**Cuando** comparo con ventanas del cliente
|
||||
**Entonces** el sistema marca en verde si cumple, rojo si no cumple
|
||||
|
||||
### CA-005: Ajuste de hora salida
|
||||
**Dado** que el ETA no cumple la ventana
|
||||
**Cuando** ajusto la hora de salida planificada
|
||||
**Entonces** el sistema recalcula todos los ETAs
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ITINERARIO Y ETAs - VJE-0123 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Hora salida planificada: [06:00] ▲▼ [Recalcular] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ITINERARIO │
|
||||
│ │
|
||||
│ 📍 ORIGEN: Bodega CDMX Norte │
|
||||
│ Salida planificada: 06:00 │
|
||||
│ Tiempo carga: 1 hora │
|
||||
│ Salida real estimada: 07:00 │
|
||||
│ │
|
||||
│ ↓ 280 km | ~4.5 hrs | Autopista México-Querétaro │
|
||||
│ │
|
||||
│ 📍 PARADA 1: Almacén GDL Centro │
|
||||
│ ETA llegada: 11:30 │
|
||||
│ Ventana cliente: 10:00 - 14:00 │
|
||||
│ Estado: ✅ DENTRO DE VENTANA │
|
||||
│ Tiempo descarga: 1 hora │
|
||||
│ Salida estimada: 12:30 │
|
||||
│ │
|
||||
│ ↓ 45 km | ~1 hr | Periférico GDL │
|
||||
│ │
|
||||
│ 📍 PARADA 2: Bodega GDL Sur │
|
||||
│ ETA llegada: 13:30 │
|
||||
│ Ventana cliente: 12:00 - 16:00 │
|
||||
│ Estado: ✅ DENTRO DE VENTANA │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ RESUMEN │
|
||||
│ Distancia total: 325 km │
|
||||
│ Tiempo total estimado: 7.5 horas │
|
||||
│ Todas las ventanas: ✅ OK │
|
||||
│ │
|
||||
│ [Guardar ETAs] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Parámetros de Cálculo
|
||||
|
||||
| Parámetro | Valor por defecto | Configurable |
|
||||
|-----------|-------------------|--------------|
|
||||
| Velocidad autopista | 80 km/h | Sí |
|
||||
| Velocidad carretera | 60 km/h | Sí |
|
||||
| Velocidad urbana | 30 km/h | Sí |
|
||||
| Tiempo carga promedio | 60 min | Por cliente |
|
||||
| Tiempo descarga promedio | 45 min | Por cliente |
|
||||
| Parada descanso | 30 min cada 4 hrs | Por política |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Usar Google Maps Distance Matrix API o similar
|
||||
- Cache de distancias frecuentes (TTL 7 días)
|
||||
- Los ETAs se almacenan en `eta_calculado`
|
||||
- Recálculo automático si cambian paradas
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Integración con API de mapas
|
||||
- [ ] Cálculo de tiempos con parámetros
|
||||
- [ ] UI de itinerario con ETAs
|
||||
- [ ] Comparación con ventanas SLA
|
||||
- [ ] Ajuste de hora de salida
|
||||
- [ ] Cache de distancias
|
||||
- [ ] Tests de cálculo
|
||||
216
docs/02-definicion-modulos/MAI-005-despacho/README.md
Normal file
216
docs/02-definicion-modulos/MAI-005-despacho/README.md
Normal file
@ -0,0 +1,216 @@
|
||||
# MAI-005: Despacho
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Estado:** Diseño
|
||||
**Prioridad:** P0 (Crítico - Workflow + NOM-068 Compliance)
|
||||
|
||||
---
|
||||
|
||||
## Descripción General
|
||||
|
||||
El módulo de Despacho es responsable de la liberación operativa del viaje, asegurando que todos los checklists, documentos, sellos y evidencias estén completos antes de que la unidad salga a ruta.
|
||||
|
||||
**Problema que resuelve:**
|
||||
- Viajes que salen sin inspección pre-viaje (riesgo de accidentes)
|
||||
- Falta de control de sellos de seguridad
|
||||
- Documentación incompleta que genera problemas en ruta
|
||||
- Incumplimiento de NOM-068 (condiciones físico-mecánicas)
|
||||
|
||||
---
|
||||
|
||||
## Objetivos del Módulo
|
||||
|
||||
1. **Checklist Pre-Viaje:** Inspección documentada según NOM-068
|
||||
2. **Control de Sellos:** Registro y evidencia de sellos de seguridad
|
||||
3. **Evidencias de Carga:** Fotos del estado de la carga antes de salir
|
||||
4. **Kit Documental:** Compilar todos los documentos necesarios
|
||||
5. **Liberación Oficial:** Evento de "gate out" con timestamp y responsable
|
||||
|
||||
---
|
||||
|
||||
## Alcance Funcional
|
||||
|
||||
### Incluido
|
||||
|
||||
- Checklist de inspección pre-viaje parametrizable
|
||||
- Control de sellos (asignación, fotos, verificación)
|
||||
- Captura de evidencias de carga
|
||||
- Compilación de kit documental digital
|
||||
- Registro de salida (gate out)
|
||||
- Validaciones de despacho
|
||||
- Notificación de salida
|
||||
|
||||
### Excluido
|
||||
|
||||
- Planeación y asignación (MAI-004)
|
||||
- Tracking en ruta (MAI-006)
|
||||
- Generación de Carta Porte (MAE-016)
|
||||
|
||||
---
|
||||
|
||||
## Actores
|
||||
|
||||
| Actor | Rol en el módulo |
|
||||
|-------|------------------|
|
||||
| Operador | Ejecuta checklist, registra sellos, toma evidencias |
|
||||
| Despachador | Valida checklist, autoriza salida |
|
||||
| Vigilancia | Confirma salida física (gate out) |
|
||||
| Sistema | Valida documentación, genera alertas |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
VIAJE PLANIFICADO
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. CHECKLIST PRE-VIAJE │
|
||||
│ - Operador inspecciona unidad │
|
||||
│ - Registra estado de cada punto │
|
||||
│ - Adjunta fotos si hay observaciones │
|
||||
│ - Firma digital del checklist │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 2. CONTROL DE SELLOS │
|
||||
│ - Asignar números de sello │
|
||||
│ - Tomar foto de cada sello colocado │
|
||||
│ - Registrar ubicación del sello │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 3. EVIDENCIAS DE CARGA │
|
||||
│ - Fotos de la carga │
|
||||
│ - Peso en báscula (si aplica) │
|
||||
│ - Firma de almacén │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 4. KIT DOCUMENTAL │
|
||||
│ - Orden de viaje │
|
||||
│ - Carta porte (si ya generada) │
|
||||
│ - Remisión/factura del cliente │
|
||||
│ - Permisos especiales │
|
||||
│ - Instrucciones de entrega │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 5. VALIDACIÓN DE DESPACHO │
|
||||
│ ✓ Checklist completo │
|
||||
│ ✓ Sellos registrados │
|
||||
│ ✓ Documentos completos │
|
||||
│ ✓ Sin bloqueos de unidad/operador │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
[APROBADO] [BLOQUEADO]
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ 6. GATE OUT │ │ Resolver y │
|
||||
│ - Timestamp │ │ reintentar │
|
||||
│ - GPS │ │ │
|
||||
│ - Responsable│ │ │
|
||||
└────────┬────────┘ └─────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ VIAJE DESPACHADO │
|
||||
│ → Inicia Tracking (MAI-006) │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Datos del Módulo
|
||||
|
||||
### Entidades Principales
|
||||
|
||||
| Entidad | Descripción | Estado |
|
||||
|---------|-------------|--------|
|
||||
| ChecklistPreViaje | Inspección de unidad | NO IMPLEMENTADA |
|
||||
| ItemChecklist | Puntos de inspección | NO IMPLEMENTADA |
|
||||
| SelloViaje | Registro de sellos | NO IMPLEMENTADA |
|
||||
| EvidenciaCarga | Fotos de la carga | NO IMPLEMENTADA |
|
||||
| DespachoViaje | Registro de liberación | NO IMPLEMENTADA |
|
||||
|
||||
### Campos Clave Checklist
|
||||
|
||||
| Campo | Tipo | Obligatorio | Descripción |
|
||||
|-------|------|-------------|-------------|
|
||||
| viaje_id | UUID | Sí | Viaje asociado |
|
||||
| tipo_checklist | ENUM | Sí | PRE_VIAJE, POST_VIAJE |
|
||||
| operador_id | UUID | Sí | Quien ejecuta |
|
||||
| fecha_ejecucion | TIMESTAMP | Sí | Cuándo se ejecutó |
|
||||
| firma_operador | TEXT | Sí | Firma digital |
|
||||
| status | ENUM | Sí | EN_PROCESO, APROBADO, RECHAZADO |
|
||||
| items | JSONB | Sí | Detalle de puntos inspeccionados |
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
Ver archivo: [REQUERIMIENTOS.md](./REQUERIMIENTOS.md)
|
||||
|
||||
---
|
||||
|
||||
## Compliance NOM-068
|
||||
|
||||
El módulo debe cumplir con NOM-068-SCT-2-2014:
|
||||
|
||||
- **Checklist parametrizable** según tipo de vehículo
|
||||
- **Puntos de inspección** según norma (llantas, frenos, luces, etc.)
|
||||
- **Evidencia fotográfica** de condiciones
|
||||
- **Bloqueo de salida** si hay fallas críticas
|
||||
- **Registro auditable** de inspecciones
|
||||
|
||||
---
|
||||
|
||||
## Métricas del Módulo
|
||||
|
||||
| KPI | Fórmula | Meta |
|
||||
|-----|---------|------|
|
||||
| Checklists completados | % viajes con checklist | 100% |
|
||||
| Tiempo de despacho | Avg(gate_out - inicio_checklist) | <45 min |
|
||||
| Viajes bloqueados | % viajes con bloqueo | <5% |
|
||||
| Sellos documentados | % viajes con sellos OK | 100% |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Este módulo depende de:
|
||||
- MAI-004 (Planeación): Viajes planificados
|
||||
- MAI-011 (Flota): Datos de unidad y operador
|
||||
- MAE-016 (Carta Porte): Documento para kit
|
||||
|
||||
### Otros módulos dependen de este:
|
||||
- MAI-006 (Tracking): Inicia al despachar
|
||||
- MAI-007 (POD): Viaje debe estar despachado
|
||||
|
||||
---
|
||||
|
||||
## Historias de Usuario
|
||||
|
||||
Ver carpeta: [historias-usuario/](./historias-usuario/)
|
||||
|
||||
| US | Título | Prioridad |
|
||||
|----|--------|-----------|
|
||||
| US-MAI005-001 | Ejecutar checklist pre-viaje | Alta |
|
||||
| US-MAI005-002 | Registrar sellos de seguridad | Alta |
|
||||
| US-MAI005-003 | Capturar evidencias de carga | Alta |
|
||||
| US-MAI005-004 | Compilar kit documental | Media |
|
||||
| US-MAI005-005 | Registrar salida (gate out) | Alta |
|
||||
|
||||
---
|
||||
|
||||
*Módulo MAI-005 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
214
docs/02-definicion-modulos/MAI-005-despacho/REQUERIMIENTOS.md
Normal file
214
docs/02-definicion-modulos/MAI-005-despacho/REQUERIMIENTOS.md
Normal file
@ -0,0 +1,214 @@
|
||||
# REQUERIMIENTOS.md - MAI-005: Despacho
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.4
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos Funcionales
|
||||
|
||||
### RF-4.4.1: Orden de Viaje (OV)
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe generar la Orden de Viaje desde el embarque con toda la información operativa necesaria.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. La OV incluye: unidad, remolques, operador, ruta completa, paradas con secuencia
|
||||
2. La OV incluye instrucciones especiales del cliente
|
||||
3. La OV es visible en app móvil del operador
|
||||
4. La OV puede imprimirse en formato compacto
|
||||
5. La OV tiene código QR para identificación rápida
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `viajes`
|
||||
- Vista: `v_orden_viaje`
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/viajes/:id/orden-viaje` - Obtener OV
|
||||
- `GET /api/v1/viajes/:id/orden-viaje/pdf` - Descargar PDF
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.4.2: Checklists Pre-Viaje
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe permitir ejecutar una inspección de la unidad con checklist parametrizable por tipo de vehículo, cumpliendo NOM-068.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Checklist configurable por tipo de unidad (tractora, remolque, caja)
|
||||
2. Puntos de inspección incluyen:
|
||||
- Llantas (presión, estado, profundidad)
|
||||
- Frenos (servicio, estacionamiento)
|
||||
- Luces (delanteras, traseras, direccionales)
|
||||
- Espejos y cristales
|
||||
- Niveles (aceite, anticongelante, combustible)
|
||||
- Sistema de acoplamiento (quinta rueda, conexiones)
|
||||
- Documentación abordo
|
||||
3. Cada punto tiene opciones: OK, Observación, Falla
|
||||
4. Fallas críticas bloquean el despacho
|
||||
5. Operador firma digitalmente al completar
|
||||
6. Se pueden adjuntar fotos por punto
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `inspecciones_pre_viaje`
|
||||
- Tabla: `checklist_items` (catálogo)
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/checklists/plantilla/:tipo-unidad` - Obtener plantilla
|
||||
- `POST /api/v1/viajes/:id/checklist` - Registrar checklist
|
||||
- `POST /api/v1/viajes/:id/checklist/items/:item/foto` - Adjuntar foto
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.4.3: Control de Sellos
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe registrar la asignación y evidencia de sellos de seguridad.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Asignar uno o más sellos al viaje
|
||||
2. Registrar número de sello (manual o escáner)
|
||||
3. Registrar ubicación del sello (puerta trasera, lateral)
|
||||
4. Capturar foto del sello colocado
|
||||
5. Registrar ruptura de sello con motivo
|
||||
6. Reemplazo de sello con nuevo número y evidencia
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `sellos_viaje`
|
||||
- Campos: numero, ubicacion, foto_url, fecha_colocacion, status
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/viajes/:id/sellos` - Registrar sello
|
||||
- `PUT /api/v1/sellos/:id/ruptura` - Registrar ruptura
|
||||
- `POST /api/v1/sellos/:id/reemplazo` - Registrar reemplazo
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.4.4: Evidencias de Carga
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe capturar evidencias fotográficas del estado de la carga antes de cerrar.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Capturar fotos de la carga estibada
|
||||
2. Registrar peso en báscula (opcional, manual o integrado)
|
||||
3. Capturar firma del responsable de almacén
|
||||
4. Asociar evidencias al viaje
|
||||
5. Las fotos funcionan en modo offline
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `evidencias_carga`
|
||||
- Campos: viaje_id, tipo, url, peso_bascula, firma_almacen
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/viajes/:id/evidencias-carga` - Subir evidencia
|
||||
- `POST /api/v1/viajes/:id/evidencias-carga/firma` - Registrar firma
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
### RF-4.4.5: Kit Documental
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe compilar todos los documentos necesarios para el viaje en formato digital.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Compilar automáticamente:
|
||||
- Orden de Viaje
|
||||
- Carta Porte (si ya generada)
|
||||
- Remisión/factura del cliente
|
||||
- Permisos especiales (hazmat, sobredimensión)
|
||||
- Instrucciones de entrega por parada
|
||||
2. Disponible en app móvil para consulta offline
|
||||
3. Opción de imprimir paquete completo
|
||||
4. Alertar si falta documento obligatorio
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `documentos_viaje`
|
||||
- Campos: viaje_id, tipo_documento, url, obligatorio
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `GET /api/v1/viajes/:id/kit-documental` - Obtener lista
|
||||
- `GET /api/v1/viajes/:id/kit-documental/zip` - Descargar todos
|
||||
- `POST /api/v1/viajes/:id/documentos` - Agregar documento
|
||||
|
||||
**Prioridad:** Media
|
||||
|
||||
---
|
||||
|
||||
### RF-4.4.6: Gate Out / Salida Oficial
|
||||
|
||||
**Descripción:**
|
||||
El sistema debe registrar el evento de salida con timestamp, usuario responsable y geolocalización.
|
||||
|
||||
**Criterios de Aceptación:**
|
||||
1. Validar que todas las condiciones de despacho estén cumplidas
|
||||
2. Registrar timestamp exacto de salida
|
||||
3. Registrar coordenadas GPS de la salida
|
||||
4. Registrar usuario que autoriza (despachador o vigilancia)
|
||||
5. Cambiar estado del viaje a DESPACHADO
|
||||
6. Notificar al cliente que el viaje inició
|
||||
7. Activar tracking (MAI-006)
|
||||
|
||||
**Mapeo a DDL:**
|
||||
- Tabla: `despachos`
|
||||
- Campos: viaje_id, fecha_salida, coordenadas, usuario_id, notas
|
||||
|
||||
**Endpoints Requeridos:**
|
||||
- `POST /api/v1/viajes/:id/gate-out` - Registrar salida
|
||||
- `GET /api/v1/viajes/:id/validar-despacho` - Verificar condiciones
|
||||
|
||||
**Prioridad:** Alta
|
||||
|
||||
---
|
||||
|
||||
## Requerimientos No Funcionales
|
||||
|
||||
### RNF-001: Modo Offline
|
||||
El checklist y captura de evidencias deben funcionar sin conexión.
|
||||
|
||||
### RNF-002: Performance
|
||||
El checklist debe cargar en menos de 2 segundos.
|
||||
|
||||
### RNF-003: Compliance
|
||||
Todos los registros deben ser inmutables para auditoría NOM-068.
|
||||
|
||||
### RNF-004: Disponibilidad
|
||||
El módulo debe estar disponible 24/7 para operaciones nocturnas.
|
||||
|
||||
---
|
||||
|
||||
## Validaciones de Negocio
|
||||
|
||||
| Validación | Descripción | Acción si falla |
|
||||
|------------|-------------|-----------------|
|
||||
| DSP_001 | Checklist completado | Bloquear gate out |
|
||||
| DSP_002 | Sin fallas críticas en checklist | Bloquear gate out |
|
||||
| DSP_003 | Sellos registrados (si aplica) | Bloquear gate out |
|
||||
| DSP_004 | Documentos obligatorios presentes | Alertar, permitir override |
|
||||
| DSP_005 | Operador con HOS suficiente | Bloquear gate out |
|
||||
|
||||
---
|
||||
|
||||
## Matriz de Trazabilidad
|
||||
|
||||
| RF | Tabla DDL | Entity | Endpoint | US |
|
||||
|----|-----------|--------|----------|---|
|
||||
| RF-4.4.1 | viajes | Viaje | GET /orden-viaje | US-MAI005-004 |
|
||||
| RF-4.4.2 | inspecciones_pre_viaje | ChecklistPreViaje | POST /checklist | US-MAI005-001 |
|
||||
| RF-4.4.3 | sellos_viaje | SelloViaje | POST /sellos | US-MAI005-002 |
|
||||
| RF-4.4.4 | evidencias_carga | EvidenciaCarga | POST /evidencias-carga | US-MAI005-003 |
|
||||
| RF-4.4.5 | documentos_viaje | DocumentoViaje | GET /kit-documental | US-MAI005-004 |
|
||||
| RF-4.4.6 | despachos | DespachoViaje | POST /gate-out | US-MAI005-005 |
|
||||
|
||||
---
|
||||
|
||||
*MAI-005 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
215
docs/02-definicion-modulos/MAI-005-despacho/RESUMEN-EPICA.md
Normal file
215
docs/02-definicion-modulos/MAI-005-despacho/RESUMEN-EPICA.md
Normal file
@ -0,0 +1,215 @@
|
||||
# RESUMEN-EPICA.md - MAI-005: Despacho
|
||||
|
||||
**Código:** MAI-005
|
||||
**Nombre:** Despacho
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-27
|
||||
|
||||
---
|
||||
|
||||
## Valor de Negocio
|
||||
|
||||
### Problema
|
||||
|
||||
Las empresas transportistas enfrentan riesgos por:
|
||||
- Unidades que salen sin inspección (accidentes, multas)
|
||||
- Sellos no documentados (reclamos por robo/faltante)
|
||||
- Documentación incompleta (retenciones en ruta)
|
||||
- Incumplimiento de NOM-068 (sanciones SCT)
|
||||
- Sin registro de hora de salida real
|
||||
|
||||
### Solución
|
||||
|
||||
Un módulo de despacho que:
|
||||
- Obliga a completar checklist antes de salir
|
||||
- Documenta sellos con evidencia fotográfica
|
||||
- Compila kit documental digital
|
||||
- Registra gate out con timestamp y GPS
|
||||
|
||||
### Beneficios Esperados
|
||||
|
||||
| Beneficio | Métrica | Impacto |
|
||||
|-----------|---------|---------|
|
||||
| Reducción accidentes | -40% incidentes mecánicos | Seguridad, costos |
|
||||
| Compliance NOM-068 | 100% inspecciones | Evita multas |
|
||||
| Menos reclamos | -60% disputas por sellos | Ahorro legal |
|
||||
| Trazabilidad | 100% viajes con gate out | Auditoría |
|
||||
|
||||
---
|
||||
|
||||
## Actores y Stakeholders
|
||||
|
||||
### Usuarios Primarios
|
||||
|
||||
| Actor | Responsabilidad | Frecuencia |
|
||||
|-------|-----------------|------------|
|
||||
| Operador | Ejecuta checklist, registra sellos | Cada viaje |
|
||||
| Despachador | Valida y autoriza salida | Cada viaje |
|
||||
| Vigilancia | Confirma gate out físico | Cada viaje |
|
||||
|
||||
### Usuarios Secundarios
|
||||
|
||||
| Actor | Interés |
|
||||
|-------|---------|
|
||||
| Jefe de Flota | Monitorea condiciones de unidades |
|
||||
| Cliente | Recibe notificación de salida |
|
||||
| Auditor | Revisa compliance NOM-068 |
|
||||
|
||||
---
|
||||
|
||||
## Flujo Principal
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VIAJE PLANIFICADO │
|
||||
│ (Unidad y operador asignados) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 1. CHECKLIST PRE-VIAJE (Operador) │
|
||||
│ │
|
||||
│ Unidad: U-005 Kenworth T680 │
|
||||
│ │
|
||||
│ □ Llantas │
|
||||
│ ├─ Presión eje delantero: [110 psi] ✓ │
|
||||
│ ├─ Presión eje trasero: [105 psi] ✓ │
|
||||
│ └─ Estado visual: [OK ▼] ✓ │
|
||||
│ │
|
||||
│ □ Frenos │
|
||||
│ ├─ Freno de servicio: [OK ▼] ✓ │
|
||||
│ └─ Freno de mano: [OK ▼] ✓ │
|
||||
│ │
|
||||
│ □ Luces │
|
||||
│ ├─ Delanteras: [OK ▼] ✓ │
|
||||
│ ├─ Traseras: [Observación ▼] ⚠ [📷 Foto] │
|
||||
│ └─ Direccionales: [OK ▼] ✓ │
|
||||
│ │
|
||||
│ ... (más puntos según NOM-068) │
|
||||
│ │
|
||||
│ [Firmar y Enviar] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 2. CONTROL DE SELLOS (Operador) │
|
||||
│ │
|
||||
│ Sellos del viaje: │
|
||||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||||
│ │ #001: ABC-123456 │ Puerta trasera │ [📷] ✓ │ │
|
||||
│ │ #002: ABC-123457 │ Puerta lateral │ [📷] ✓ │ │
|
||||
│ └───────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [+ Agregar Sello] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 3. EVIDENCIAS DE CARGA (Operador) │
|
||||
│ │
|
||||
│ Fotos de carga: [📷] [📷] [📷] 3/5 │
|
||||
│ Peso báscula: [12,500 kg] │
|
||||
│ Firma almacén: [✓ Capturada] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 4. VALIDACIÓN (Despachador) │
|
||||
│ │
|
||||
│ Estado del despacho: │
|
||||
│ ✓ Checklist completado (15 puntos OK, 1 observación) │
|
||||
│ ✓ Sellos registrados (2) │
|
||||
│ ✓ Evidencias de carga (3 fotos + firma) │
|
||||
│ ✓ Kit documental completo │
|
||||
│ ✓ Operador con HOS disponible (11 hrs) │
|
||||
│ │
|
||||
│ [Autorizar Salida] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 5. GATE OUT (Vigilancia) │
|
||||
│ │
|
||||
│ ✓ Confirmar salida física │
|
||||
│ │
|
||||
│ Fecha/Hora: 2026-01-28 06:15:32 │
|
||||
│ GPS: 19.4326, -99.1332 │
|
||||
│ Autoriza: Carlos Méndez (Vigilancia) │
|
||||
│ │
|
||||
│ [Registrar Gate Out] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VIAJE DESPACHADO │
|
||||
│ → Tracking activado (MAI-006) │
|
||||
│ → Cliente notificado │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Éxito
|
||||
|
||||
### Funcionales
|
||||
|
||||
- [ ] Checklist parametrizable por tipo de unidad
|
||||
- [ ] Bloqueo de salida por fallas críticas
|
||||
- [ ] Registro de sellos con fotos
|
||||
- [ ] Kit documental compilado
|
||||
- [ ] Gate out con GPS y timestamp
|
||||
|
||||
### Técnicos
|
||||
|
||||
- [ ] Funciona offline (checklist, fotos)
|
||||
- [ ] Sincronización en <30 segundos
|
||||
- [ ] Registros inmutables
|
||||
- [ ] Integración con tracking
|
||||
|
||||
### Negocio
|
||||
|
||||
- [ ] 100% viajes con checklist
|
||||
- [ ] 100% sellos documentados
|
||||
- [ ] <45 min tiempo de despacho
|
||||
- [ ] 0 multas por NOM-068
|
||||
|
||||
---
|
||||
|
||||
## Riesgos y Mitigaciones
|
||||
|
||||
| Riesgo | Probabilidad | Impacto | Mitigación |
|
||||
|--------|--------------|---------|------------|
|
||||
| Operador omite checklist | Media | Alto | Bloqueo obligatorio |
|
||||
| Fotos no se sincronizan | Media | Medio | Cola de reintentos |
|
||||
| Resistencia al cambio | Alta | Medio | Capacitación, UX simple |
|
||||
| Falta de conectividad | Alta | Medio | Modo offline robusto |
|
||||
|
||||
---
|
||||
|
||||
## Dependencias
|
||||
|
||||
### Prerequisitos
|
||||
- MAI-004 (Planeación): Viaje planificado
|
||||
- MAI-011 (Flota): Datos de unidad
|
||||
- MAE-016 (Carta Porte): Documento para kit (opcional)
|
||||
|
||||
### Habilita
|
||||
- MAI-006 (Tracking): Se activa al despachar
|
||||
- MAI-007 (POD): Viaje debe estar despachado
|
||||
|
||||
---
|
||||
|
||||
## Story Points Estimados
|
||||
|
||||
| Historia | Complejidad | SP |
|
||||
|----------|-------------|---|
|
||||
| US-MAI005-001 | Alta | 8 |
|
||||
| US-MAI005-002 | Media | 5 |
|
||||
| US-MAI005-003 | Media | 5 |
|
||||
| US-MAI005-004 | Media | 5 |
|
||||
| US-MAI005-005 | Media | 5 |
|
||||
| **Total** | | **28** |
|
||||
|
||||
---
|
||||
|
||||
*Épica MAI-005 - ERP Transportistas - Sistema SIMCO v4.0.0*
|
||||
@ -0,0 +1,142 @@
|
||||
# US-MAI005-001: Ejecutar checklist pre-viaje
|
||||
|
||||
**ID:** US-MAI005-001
|
||||
**Módulo:** MAI-005 (Despacho)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 8
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** operador de transporte
|
||||
**Quiero** ejecutar un checklist de inspección pre-viaje en mi dispositivo móvil
|
||||
**Para** documentar el estado de la unidad y cumplir con NOM-068 antes de salir a ruta
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Cargar checklist por tipo de unidad
|
||||
**Dado** que tengo un viaje asignado
|
||||
**Cuando** inicio el checklist pre-viaje
|
||||
**Entonces** el sistema carga la plantilla correspondiente al tipo de unidad (tractora, remolque, caja seca)
|
||||
|
||||
### CA-002: Registrar estado de cada punto
|
||||
**Dado** que estoy ejecutando el checklist
|
||||
**Cuando** inspecciono cada punto
|
||||
**Entonces** puedo marcar: OK, Observación, o Falla con comentario opcional
|
||||
|
||||
### CA-003: Adjuntar fotos por punto
|
||||
**Dado** que un punto tiene observación o falla
|
||||
**Cuando** selecciono la opción de foto
|
||||
**Entonces** puedo capturar y adjuntar una imagen como evidencia
|
||||
|
||||
### CA-004: Bloqueo por fallas críticas
|
||||
**Dado** que marco una falla en punto crítico (frenos, llantas, luces)
|
||||
**Cuando** intento finalizar el checklist
|
||||
**Entonces** el sistema indica que el viaje no puede despacharse sin resolver
|
||||
|
||||
### CA-005: Firma digital del operador
|
||||
**Dado** que completé todos los puntos del checklist
|
||||
**Cuando** finalizo la inspección
|
||||
**Entonces** debo firmar digitalmente para confirmar que realicé la inspección
|
||||
|
||||
### CA-006: Funcionamiento offline
|
||||
**Dado** que estoy sin conexión a internet
|
||||
**Cuando** ejecuto el checklist
|
||||
**Entonces** puedo completarlo y las fotos se sincronizan al recuperar conexión
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CHECKLIST PRE-VIAJE ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0123 | Unidad: U-005 Kenworth T680 │
|
||||
│ Tipo: Tractocamión con semirremolque │
|
||||
│ │
|
||||
│ Progreso: ████████░░░░░░░░ 8/15 puntos │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ 🔧 LLANTAS │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Presión eje delantero │ │
|
||||
│ │ Valor: [110 psi] │ │
|
||||
│ │ Estado: (●) OK ( ) Observación ( ) Falla │ │
|
||||
│ │ │ │
|
||||
│ │ Presión eje trasero │ │
|
||||
│ │ Valor: [105 psi] │ │
|
||||
│ │ Estado: (●) OK ( ) Observación ( ) Falla │ │
|
||||
│ │ │ │
|
||||
│ │ Profundidad de dibujo │ │
|
||||
│ │ Estado: ( ) OK (●) Observación ( ) Falla │ │
|
||||
│ │ Nota: [Desgaste visible en eje 3] │ │
|
||||
│ │ [📷 Agregar Foto] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 🔧 FRENOS (CRÍTICO) │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Freno de servicio │ │
|
||||
│ │ Estado: (●) OK ( ) Observación ( ) Falla │ │
|
||||
│ │ │ │
|
||||
│ │ Freno de estacionamiento │ │
|
||||
│ │ Estado: (●) OK ( ) Observación ( ) Falla │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 🔧 LUCES [Expandir] │
|
||||
│ 🔧 ESPEJOS Y CRISTALES [Expandir] │
|
||||
│ 🔧 NIVELES [Expandir] │
|
||||
│ 🔧 ACOPLAMIENTO [Expandir] │
|
||||
│ 🔧 DOCUMENTACIÓN [Expandir] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ⚠ 1 observación registrada │
|
||||
│ │
|
||||
│ [Cancelar] [Firmar y Finalizar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Puntos de Inspección NOM-068
|
||||
|
||||
| Categoría | Puntos | Crítico |
|
||||
|-----------|--------|---------|
|
||||
| Llantas | Presión, profundidad, estado | Sí |
|
||||
| Frenos | Servicio, estacionamiento | Sí |
|
||||
| Luces | Delanteras, traseras, direccionales | Sí |
|
||||
| Espejos | Retrovisores, laterales | No |
|
||||
| Niveles | Aceite, anticongelante, combustible | No |
|
||||
| Acoplamiento | Quinta rueda, conexiones, pernos | Sí |
|
||||
| Documentación | Licencia, tarjeta, permisos | Sí |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Plantillas en tabla `checklist_items` filtradas por `tipo_unidad`
|
||||
- Checklist se guarda en `inspecciones_pre_viaje`
|
||||
- Fotos se suben a S3 con referencia en `item.foto_url`
|
||||
- Sincronización via cola de reintentos (máx 3 intentos)
|
||||
- Firma se almacena como base64 en `firma_operador`
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Carga de plantilla por tipo de unidad
|
||||
- [ ] UI de checklist con todos los puntos NOM-068
|
||||
- [ ] Captura de fotos por punto
|
||||
- [ ] Validación de puntos críticos
|
||||
- [ ] Firma digital del operador
|
||||
- [ ] Funcionamiento offline con sincronización
|
||||
- [ ] Tests unitarios de validaciones
|
||||
- [ ] Tests de integración de sincronización
|
||||
|
||||
@ -0,0 +1,172 @@
|
||||
# US-MAI005-002: Registrar sellos de seguridad
|
||||
|
||||
**ID:** US-MAI005-002
|
||||
**Módulo:** MAI-005 (Despacho)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** operador de transporte
|
||||
**Quiero** registrar los sellos de seguridad colocados en la unidad con evidencia fotográfica
|
||||
**Para** tener respaldo ante reclamos por robo o faltante de mercancía
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Agregar sello con número
|
||||
**Dado** que estoy en el proceso de despacho
|
||||
**Cuando** agrego un sello
|
||||
**Entonces** puedo ingresar el número (manual o escáner) y la ubicación donde se colocó
|
||||
|
||||
### CA-002: Foto obligatoria del sello
|
||||
**Dado** que registro un sello
|
||||
**Cuando** completo el registro
|
||||
**Entonces** debo adjuntar foto del sello colocado mostrando el número visible
|
||||
|
||||
### CA-003: Múltiples sellos por viaje
|
||||
**Dado** que un viaje puede tener varios sellos
|
||||
**Cuando** necesito agregar más sellos
|
||||
**Entonces** puedo registrar tantos como sean necesarios (puerta trasera, lateral, etc.)
|
||||
|
||||
### CA-004: Escaneo de código de barras
|
||||
**Dado** que el sello tiene código de barras
|
||||
**Cuando** uso la cámara para escanear
|
||||
**Entonces** el sistema captura automáticamente el número del sello
|
||||
|
||||
### CA-005: Registro de ruptura
|
||||
**Dado** que un sello fue roto (inspección, emergencia)
|
||||
**Cuando** registro la ruptura
|
||||
**Entonces** debo indicar el motivo y subir foto del sello roto
|
||||
|
||||
### CA-006: Reemplazo de sello
|
||||
**Dado** que un sello fue roto
|
||||
**Cuando** coloco un sello nuevo
|
||||
**Entonces** se registra como reemplazo vinculado al sello original
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CONTROL DE SELLOS ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0123 | Cliente: Distribuidora ABC │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ SELLOS REGISTRADOS │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ #1 Sello: ABC-123456 │ │
|
||||
│ │ Ubicación: Puerta trasera │ │
|
||||
│ │ Colocado: 2026-01-28 06:05:12 │ │
|
||||
│ │ Estado: ✅ ACTIVO │ │
|
||||
│ │ [📷 Ver foto] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ #2 Sello: ABC-123457 │ │
|
||||
│ │ Ubicación: Puerta lateral izquierda │ │
|
||||
│ │ Colocado: 2026-01-28 06:08:45 │ │
|
||||
│ │ Estado: ✅ ACTIVO │ │
|
||||
│ │ [📷 Ver foto] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ AGREGAR NUEVO SELLO │
|
||||
│ │
|
||||
│ Número: [________________] [📷 Escanear] │
|
||||
│ │
|
||||
│ Ubicación: [Seleccionar ubicación ▼] │
|
||||
│ ○ Puerta trasera │
|
||||
│ ○ Puerta lateral izquierda │
|
||||
│ ○ Puerta lateral derecha │
|
||||
│ ○ Otra: [________________] │
|
||||
│ │
|
||||
│ Foto del sello colocado: [📷 Tomar foto] (Obligatorio) │
|
||||
│ │
|
||||
│ [+ Agregar Sello] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ 2 sellos registrados [Continuar →] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pantalla de Ruptura de Sello
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ REGISTRAR RUPTURA DE SELLO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Sello: ABC-123456 │
|
||||
│ Ubicación original: Puerta trasera │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ⚠ REGISTRAR RUPTURA │
|
||||
│ │
|
||||
│ Motivo de ruptura: │
|
||||
│ ( ) Inspección en aduana/retén │
|
||||
│ ( ) Inspección por cliente │
|
||||
│ ( ) Emergencia (accidente, falla mecánica) │
|
||||
│ (●) Otro: [Verificación por almacén destino] │
|
||||
│ │
|
||||
│ Foto del sello roto: [📷 Foto capturada ✓] │
|
||||
│ │
|
||||
│ Coordenadas GPS: 20.6597, -103.3496 (Auto) │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ¿Colocar sello de reemplazo? │
|
||||
│ [Sí, agregar reemplazo] [No, continuar sin sello] │
|
||||
│ │
|
||||
│ [Cancelar] [Registrar Ruptura] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estados de Sello
|
||||
|
||||
| Estado | Descripción |
|
||||
|--------|-------------|
|
||||
| ACTIVO | Sello colocado y vigente |
|
||||
| ROTO | Sello roto con motivo registrado |
|
||||
| REEMPLAZADO | Sello que fue sustituido por otro |
|
||||
| VERIFICADO | Sello verificado en destino (POD) |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `sellos_viaje`
|
||||
- Escaneo de código de barras via cámara (ML Kit o ZXing)
|
||||
- Fotos se suben a S3 con metadata de geolocalización
|
||||
- Historial completo inmutable para auditoría
|
||||
- La ruptura registra coordenadas GPS automáticamente
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] CRUD de sellos por viaje
|
||||
- [ ] Escaneo de código de barras
|
||||
- [ ] Captura de foto obligatoria
|
||||
- [ ] Registro de ruptura con motivo
|
||||
- [ ] Registro de reemplazo vinculado
|
||||
- [ ] Funcionamiento offline
|
||||
- [ ] Tests de escenarios de ruptura/reemplazo
|
||||
|
||||
@ -0,0 +1,171 @@
|
||||
# US-MAI005-003: Capturar evidencias de carga
|
||||
|
||||
**ID:** US-MAI005-003
|
||||
**Módulo:** MAI-005 (Despacho)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** operador de transporte
|
||||
**Quiero** capturar evidencias fotográficas del estado de la carga antes de salir
|
||||
**Para** tener respaldo del estado inicial y evitar disputas por daños
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Capturar fotos de la carga
|
||||
**Dado** que la carga está lista en la unidad
|
||||
**Cuando** tomo fotos de evidencia
|
||||
**Entonces** puedo capturar múltiples fotos mostrando el estado de la mercancía
|
||||
|
||||
### CA-002: Mínimo de fotos requerido
|
||||
**Dado** que el cliente o tipo de carga requiere evidencias
|
||||
**Cuando** intento continuar sin fotos suficientes
|
||||
**Entonces** el sistema indica cuántas fotos mínimas se requieren (configurable)
|
||||
|
||||
### CA-003: Registrar peso en báscula
|
||||
**Dado** que la carga pasa por báscula
|
||||
**Cuando** registro el peso
|
||||
**Entonces** puedo ingresar el peso total (kg) manual o desde ticket de báscula
|
||||
|
||||
### CA-004: Capturar firma de almacén
|
||||
**Dado** que el almacén entrega la carga
|
||||
**Cuando** solicito la firma
|
||||
**Entonces** el responsable de almacén firma en pantalla confirmando la entrega
|
||||
|
||||
### CA-005: Funcionamiento offline
|
||||
**Dado** que estoy en área sin señal
|
||||
**Cuando** capturo fotos y firma
|
||||
**Entonces** se almacenan localmente y sincronizan al recuperar conexión
|
||||
|
||||
### CA-006: Metadata de fotos
|
||||
**Dado** que capturo una foto
|
||||
**Cuando** se guarda
|
||||
**Entonces** incluye timestamp, coordenadas GPS y dispositivo origen
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EVIDENCIAS DE CARGA ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0123 | Carga: Electrodomésticos │
|
||||
│ Requisito mínimo: 3 fotos │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ 📷 FOTOS DE CARGA (3/3 mínimo) │
|
||||
│ │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ 📷 1 │ │ 📷 2 │ │ 📷 3 │ │ + │ │
|
||||
│ │ [Vista] │ │ [Vista] │ │ [Vista] │ │ Agregar │ │
|
||||
│ │ 06:10am │ │ 06:11am │ │ 06:12am │ │ foto │ │
|
||||
│ │ ✓ │ │ ✓ │ │ ✓ │ │ │ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ⚖ PESO EN BÁSCULA (Opcional) │
|
||||
│ │
|
||||
│ Peso bruto: [12,500] kg │
|
||||
│ Peso neto: [10,200] kg │
|
||||
│ Referencia ticket: [BSC-2026-0145] │
|
||||
│ │
|
||||
│ [📷 Foto de ticket báscula] ✓ Capturada │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ✍ FIRMA DE ALMACÉN │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ │ │
|
||||
│ │ [Área de firma - táctil] │ │
|
||||
│ │ │ │
|
||||
│ │ ~~~~~~~~~~~~~~~~~~~~~~ │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Nombre: [Carlos López Hernández] │
|
||||
│ Puesto: [Jefe de Almacén] │
|
||||
│ │
|
||||
│ [Limpiar firma] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ✓ Fotos: 3/3 ✓ Peso: Registrado ✓ Firma: Capturada │
|
||||
│ │
|
||||
│ [Cancelar] [Continuar →] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Vista de Foto Individual
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ DETALLE DE EVIDENCIA ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ │ │
|
||||
│ │ │ │
|
||||
│ │ [Imagen de la carga] │ │
|
||||
│ │ │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 📅 Fecha/Hora: 2026-01-28 06:10:32 │
|
||||
│ 📍 Ubicación: 19.4326, -99.1332 (Bodega CDMX) │
|
||||
│ 📱 Dispositivo: iPhone 14 Pro │
|
||||
│ │
|
||||
│ Nota: [Vista frontal de la estiba completa] │
|
||||
│ │
|
||||
│ [🗑 Eliminar] [✓ Confirmar] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuración por Cliente
|
||||
|
||||
| Cliente | Fotos mínimas | Peso requerido | Firma requerida |
|
||||
|---------|---------------|----------------|-----------------|
|
||||
| Default | 3 | No | Sí |
|
||||
| Cliente A | 5 | Sí | Sí |
|
||||
| Cliente B | 3 | Sí (neto y bruto) | Sí |
|
||||
| Cliente C | 2 | No | No |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `evidencias_carga`
|
||||
- Fotos se comprimen a max 1MB antes de subir
|
||||
- Firma se guarda como SVG o PNG base64
|
||||
- Metadata EXIF se extrae automáticamente
|
||||
- Cola de sincronización con reintentos exponenciales
|
||||
- Configuración de requisitos en `requisitos_cliente`
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Captura de múltiples fotos con cámara
|
||||
- [ ] Validación de fotos mínimas por configuración
|
||||
- [ ] Registro de peso con campos bruto/neto
|
||||
- [ ] Captura de firma táctil
|
||||
- [ ] Almacenamiento con metadata (GPS, timestamp)
|
||||
- [ ] Funcionamiento offline completo
|
||||
- [ ] Sincronización con cola de reintentos
|
||||
- [ ] Tests de sincronización y validación
|
||||
|
||||
@ -0,0 +1,158 @@
|
||||
# US-MAI005-004: Compilar kit documental
|
||||
|
||||
**ID:** US-MAI005-004
|
||||
**Módulo:** MAI-005 (Despacho)
|
||||
**Prioridad:** Media
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** despachador
|
||||
**Quiero** que el sistema compile automáticamente todos los documentos necesarios para el viaje
|
||||
**Para** asegurar que el operador lleva toda la documentación requerida y evitar retenciones en ruta
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Compilar documentos automáticamente
|
||||
**Dado** que un viaje está listo para despachar
|
||||
**Cuando** accedo al kit documental
|
||||
**Entonces** el sistema lista todos los documentos requeridos con su estado (disponible/pendiente)
|
||||
|
||||
### CA-002: Incluir orden de viaje
|
||||
**Dado** que el viaje está planificado
|
||||
**Cuando** compilo el kit
|
||||
**Entonces** incluye la Orden de Viaje con código QR para identificación rápida
|
||||
|
||||
### CA-003: Incluir Carta Porte (si existe)
|
||||
**Dado** que la Carta Porte fue generada en MAE-016
|
||||
**Cuando** compilo el kit
|
||||
**Entonces** incluye el CFDI Carta Porte con su UUID
|
||||
|
||||
### CA-004: Alertar documentos faltantes
|
||||
**Dado** que faltan documentos obligatorios
|
||||
**Cuando** reviso el kit
|
||||
**Entonces** el sistema muestra alertas con los documentos pendientes
|
||||
|
||||
### CA-005: Disponible offline en app
|
||||
**Dado** que el kit está completo
|
||||
**Cuando** el operador lo descarga en su app
|
||||
**Entonces** todos los documentos están disponibles sin conexión
|
||||
|
||||
### CA-006: Descargar paquete completo
|
||||
**Dado** que necesito imprimir los documentos
|
||||
**Cuando** solicito descarga
|
||||
**Entonces** se genera un ZIP con todos los PDFs del kit
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ KIT DOCUMENTAL ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0123 | Ruta: CDMX → GDL → AGS │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ DOCUMENTOS DEL VIAJE │
|
||||
│ │
|
||||
│ 📄 OBLIGATORIOS │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ✅ Orden de Viaje │ │
|
||||
│ │ OV-VJE-0123.pdf | 2 páginas | [Ver] [Descargar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ✅ Carta Porte CFDI │ │
|
||||
│ │ UUID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 │ │
|
||||
│ │ CP-VJE-0123.pdf | 4 páginas | [Ver] [Descargar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ✅ Remisión del cliente │ │
|
||||
│ │ REM-CLI-2026-0891.pdf | [Ver] [Descargar] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ⚠️ Factura del cliente │ │
|
||||
│ │ PENDIENTE - El cliente no ha subido la factura │ │
|
||||
│ │ [Subir manualmente] [Omitir con nota] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 📄 CONDICIONALES (según carga) │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ✅ Permiso de materiales peligrosos │ │
|
||||
│ │ PERM-HAZMAT-2026.pdf | [Ver] [Descargar] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ 📄 INSTRUCCIONES POR PARADA │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Parada 1: Almacén GDL Centro │ │
|
||||
│ │ • Entregar en andén 5 │ │
|
||||
│ │ • Contacto: Juan Pérez (33) 1234-5678 │ │
|
||||
│ │ • Horario: 08:00 - 18:00 │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ Parada 2: Bodega AGS │ │
|
||||
│ │ • Requiere cita previa (ya agendada) │ │
|
||||
│ │ • Contacto: María López (449) 876-5432 │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ⚠ 1 documento pendiente │
|
||||
│ │
|
||||
│ [Descargar ZIP] [Enviar a app] [Imprimir todo] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tipos de Documentos
|
||||
|
||||
| Tipo | Obligatorio | Fuente | Generación |
|
||||
|------|-------------|--------|------------|
|
||||
| Orden de Viaje | Siempre | Sistema | Automática |
|
||||
| Carta Porte | Siempre | MAE-016 | Automática |
|
||||
| Remisión | Por cliente | Cliente/Sistema | Manual/Auto |
|
||||
| Factura | Por cliente | Cliente | Manual |
|
||||
| Permiso Hazmat | Si aplica | Sistema | Referencia |
|
||||
| Permiso Sobredimensión | Si aplica | SCT | Manual |
|
||||
| Instrucciones | Siempre | Embarque | Automática |
|
||||
|
||||
---
|
||||
|
||||
## Validaciones de Documentos
|
||||
|
||||
| Código | Validación | Acción si falla |
|
||||
|--------|------------|-----------------|
|
||||
| DOC_001 | Orden de Viaje presente | Bloquear despacho |
|
||||
| DOC_002 | Carta Porte si viaje federal | Bloquear despacho |
|
||||
| DOC_003 | Permisos especiales si carga lo requiere | Bloquear despacho |
|
||||
| DOC_004 | Factura del cliente | Advertencia |
|
||||
| DOC_005 | Instrucciones de entrega | Advertencia |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `documentos_viaje`
|
||||
- Generación de OV desde vista `v_orden_viaje`
|
||||
- Integración con MAE-016 para obtener Carta Porte
|
||||
- ZIP generado con JSZip o similar
|
||||
- Sincronización a app móvil via API dedicada
|
||||
- Cache de documentos para acceso offline
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Compilación automática de documentos
|
||||
- [ ] Generación de Orden de Viaje con QR
|
||||
- [ ] Integración con Carta Porte (MAE-016)
|
||||
- [ ] Alertas de documentos faltantes
|
||||
- [ ] Descarga de ZIP con todos los PDFs
|
||||
- [ ] Sincronización a app móvil
|
||||
- [ ] Validaciones bloqueantes vs advertencias
|
||||
- [ ] Tests de compilación y generación
|
||||
|
||||
@ -0,0 +1,208 @@
|
||||
# US-MAI005-005: Registrar salida (gate out)
|
||||
|
||||
**ID:** US-MAI005-005
|
||||
**Módulo:** MAI-005 (Despacho)
|
||||
**Prioridad:** Alta
|
||||
**Story Points:** 5
|
||||
|
||||
---
|
||||
|
||||
## Historia de Usuario
|
||||
|
||||
**Como** personal de vigilancia o despachador
|
||||
**Quiero** registrar el evento de salida oficial de la unidad
|
||||
**Para** tener un timestamp exacto de cuándo el viaje inició y activar el tracking
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Aceptación
|
||||
|
||||
### CA-001: Validar condiciones de despacho
|
||||
**Dado** que intento registrar gate out
|
||||
**Cuando** el sistema valida
|
||||
**Entonces** verifica: checklist completo, sellos registrados, documentos OK, HOS del operador
|
||||
|
||||
### CA-002: Bloquear si no cumple
|
||||
**Dado** que hay condiciones no cumplidas
|
||||
**Cuando** intento confirmar salida
|
||||
**Entonces** el sistema bloquea y muestra qué falta resolver
|
||||
|
||||
### CA-003: Registrar timestamp y GPS
|
||||
**Dado** que confirmo la salida
|
||||
**Cuando** se registra el gate out
|
||||
**Entonces** guarda: fecha/hora exacta, coordenadas GPS del punto de salida
|
||||
|
||||
### CA-004: Registrar usuario responsable
|
||||
**Dado** que confirmo la salida
|
||||
**Cuando** se registra
|
||||
**Entonces** queda registrado quién autorizó (despachador o vigilancia)
|
||||
|
||||
### CA-005: Cambiar estado del viaje
|
||||
**Dado** que el gate out se registró
|
||||
**Cuando** se completa
|
||||
**Entonces** el viaje cambia a estado DESPACHADO
|
||||
|
||||
### CA-006: Notificar y activar tracking
|
||||
**Dado** que el viaje fue despachado
|
||||
**Cuando** se confirma gate out
|
||||
**Entonces** se notifica al cliente y se activa tracking (MAI-006)
|
||||
|
||||
---
|
||||
|
||||
## Mockup / UI
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ GATE OUT - SALIDA OFICIAL ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0123 │
|
||||
│ Unidad: U-005 Kenworth T680 │
|
||||
│ Operador: Juan Pérez García │
|
||||
│ Destino: Guadalajara, JAL │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ✓ VALIDACIÓN DE CONDICIONES │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ ✅ Checklist pre-viaje │ │
|
||||
│ │ Completado: 2026-01-28 06:00 │ │
|
||||
│ │ Resultado: 14 OK, 1 observación, 0 fallas │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ✅ Sellos de seguridad │ │
|
||||
│ │ 2 sellos registrados con foto │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ✅ Evidencias de carga │ │
|
||||
│ │ 3 fotos + firma de almacén │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ✅ Kit documental │ │
|
||||
│ │ 4/4 documentos obligatorios │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ✅ HOS del operador │ │
|
||||
│ │ Disponible: 11 hrs | Requerido: 8 hrs │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ ✅ Unidad sin bloqueos │ │
|
||||
│ │ Sin alertas de mantenimiento │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ 📍 INFORMACIÓN DE SALIDA │
|
||||
│ │
|
||||
│ Fecha/Hora: 2026-01-28 06:15:32 (automático) │
|
||||
│ GPS: 19.4326, -99.1332 │
|
||||
│ Ubicación: Bodega CDMX Norte │
|
||||
│ │
|
||||
│ Autoriza: [Carlos Méndez - Vigilancia ▼] │
|
||||
│ │
|
||||
│ Notas (opcional): │
|
||||
│ [________________________________________] │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ Al confirmar: │
|
||||
│ • El viaje cambiará a estado DESPACHADO │
|
||||
│ • Se activará el tracking GPS │
|
||||
│ • Se notificará al cliente │
|
||||
│ │
|
||||
│ [Cancelar] [✓ Confirmar Gate Out] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pantalla de Bloqueo
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ⛔ DESPACHO BLOQUEADO ✕ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Viaje: VJE-0123 │
|
||||
│ │
|
||||
│ No se puede autorizar la salida. Resolver lo siguiente: │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ ❌ BLOQUEOS CRÍTICOS (deben resolverse) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ 1. Checklist incompleto │ │
|
||||
│ │ Faltan 3 puntos por inspeccionar │ │
|
||||
│ │ [Ir a Checklist] │ │
|
||||
│ ├─────────────────────────────────────────────────────────┤ │
|
||||
│ │ 2. Falla crítica en frenos │ │
|
||||
│ │ Registrada en checklist - requiere mantenimiento │ │
|
||||
│ │ [Ver detalle] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ⚠ ADVERTENCIAS (pueden omitirse con autorización) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ 1. Factura del cliente pendiente │ │
|
||||
│ │ [Subir documento] [Omitir - Justificar] │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────────────── │
|
||||
│ │
|
||||
│ 2 bloqueos críticos | 1 advertencia │
|
||||
│ │
|
||||
│ [Volver] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validaciones de Despacho
|
||||
|
||||
| Código | Validación | Tipo | Override |
|
||||
|--------|------------|------|----------|
|
||||
| DSP_001 | Checklist completado | Bloqueante | No |
|
||||
| DSP_002 | Sin fallas críticas | Bloqueante | No |
|
||||
| DSP_003 | Sellos registrados (si aplica) | Bloqueante | No |
|
||||
| DSP_004 | Documentos obligatorios | Bloqueante | No |
|
||||
| DSP_005 | HOS suficiente del operador | Bloqueante | Supervisor |
|
||||
| DSP_006 | Unidad sin bloqueos | Bloqueante | Supervisor |
|
||||
| DSP_007 | Factura del cliente | Advertencia | Sí |
|
||||
| DSP_008 | Evidencias de carga | Advertencia | Sí |
|
||||
|
||||
---
|
||||
|
||||
## Acciones Post Gate Out
|
||||
|
||||
| Acción | Destino | Trigger |
|
||||
|--------|---------|---------|
|
||||
| Cambiar estado viaje | viajes.estado = DESPACHADO | Inmediato |
|
||||
| Activar tracking | MAI-006 | Inmediato |
|
||||
| Notificar cliente | Email/SMS/WhatsApp | <1 min |
|
||||
| Actualizar dashboard | Métricas de despacho | Inmediato |
|
||||
| Log de auditoría | Sistema | Inmediato |
|
||||
|
||||
---
|
||||
|
||||
## Notas Técnicas
|
||||
|
||||
- Tabla: `despachos`
|
||||
- Endpoint: `POST /api/v1/viajes/:id/gate-out`
|
||||
- Validaciones en endpoint `GET /api/v1/viajes/:id/validar-despacho`
|
||||
- GPS se captura del dispositivo o se infiere de ubicación base
|
||||
- Notificaciones via servicio de mensajería (MAI-015)
|
||||
- Activación de tracking via evento interno
|
||||
|
||||
---
|
||||
|
||||
## Definición de Done
|
||||
|
||||
- [ ] Validación completa de condiciones
|
||||
- [ ] Bloqueo con detalle de pendientes
|
||||
- [ ] Registro de timestamp y GPS
|
||||
- [ ] Registro de usuario responsable
|
||||
- [ ] Cambio de estado del viaje
|
||||
- [ ] Integración con notificaciones
|
||||
- [ ] Integración con tracking (MAI-006)
|
||||
- [ ] Override con supervisor para advertencias
|
||||
- [ ] Tests de validaciones y flujo completo
|
||||
|
||||
Loading…
Reference in New Issue
Block a user