erp-transportistas-v2/docs/02-definicion-modulos/MAI-014-carriers/REQUERIMIENTOS.md

# REQUERIMIENTOS - MAI-014: Gestion de Carriers

**Modulo:** MAI-014
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 4.12
**Version:** 1.0.0

---

## Requerimientos Funcionales

### RF-4.12.1: Registro de Carrier

**Descripcion:** Registrar carriers con datos fiscales, documentos y evaluacion inicial.

**Datos del carrier:**
| Grupo | Campos |
|-------|--------|
| Fiscales | RFC, razon social, regimen, domicilio |
| Contacto | Nombre, telefono, email, contacto operativo |
| Bancarios | Banco, CLABE, beneficiario |
| Operativos | Tipos de equipo, cobertura geografica |
| Comerciales | Tarifas base, condiciones de pago |

**Documentos obligatorios:**
- Constancia de situacion fiscal
- Permiso SCT (autotransporte federal)
- Poliza de seguro (responsabilidad civil)
- Opinion de cumplimiento SAT (32-D)

**Evaluacion inicial:**
- Verificar antecedentes
- Validar referencias comerciales
- Visita a instalaciones (opcional)

**Tablas DDL:**
- `carriers.carriers`
- `carriers.documentos_carrier`
- `carriers.contactos_carrier`

---

### RF-4.12.2: Asignacion a Carrier

**Descripcion:** Asignar viajes a carriers mediante licitacion interna.

**Proceso de asignacion:**
```
Viaje sin recurso propio → Solicitar cotizaciones (RFQ) →
Recibir propuestas → Comparar vs margen requerido →
Adjudicar → Emitir OV al carrier
```

**Rate shopping:**
- Enviar solicitud a N carriers
- Tiempo limite de respuesta
- Comparativo automatico
- Margen minimo configurable

**Orden de Viaje a tercero:**
- Datos del viaje (origen, destino, carga)
- Instrucciones operativas
- Datos de contacto cliente
- Documentos requeridos

**Tablas DDL:**
- `carriers.solicitudes_cotizacion`
- `carriers.cotizaciones_carrier`
- `carriers.ordenes_viaje_carrier`

---

### RF-4.12.3: Control de Documentos del Tercero

**Descripcion:** Verificar vigencia de documentos antes de cada asignacion.

**Documentos por carrier:**
| Documento | Frecuencia | Bloquea si vence |
|-----------|------------|------------------|
| Permiso SCT | Anual | Si |
| Poliza seguro | Anual | Si |
| Opinion 32-D | Mensual | Alerta |

**Documentos por viaje:**
| Documento | Momento | Obligatorio |
|-----------|---------|-------------|
| Carta responsiva | Pre-carga | Si |
| INE operador | Pre-carga | Si |
| Licencia federal | Pre-carga | Si |
| Tarjeta circulacion | Pre-carga | Si |

**Validaciones:**
- Bloquear asignacion si documento vencido
- Alerta 30 dias antes de vencimiento
- Historial de documentos

**Tablas DDL:**
- `carriers.documentos_carrier`
- `carriers.documentos_viaje_carrier`

---

### RF-4.12.4: Recepcion de POD del Tercero

**Descripcion:** Recibir evidencia de entrega del carrier.

**Canales de recepcion:**
1. **Portal de carriers** - Upload directo
2. **WhatsApp** - Fotos por mensaje
3. **Email** - Adjuntos
4. **App movil** (si carrier usa nuestra app)

**Validaciones del POD:**
- Fotos legibles
- Firma/sello presente
- Datos del receptor
- Fecha y hora

**Integracion:**
- POD del carrier se integra a expediente del viaje
- Mismo flujo de validacion que POD propio

**Tablas DDL:**
- `carriers.pod_carrier`
- Relacion con `tracking.evidencias_entrega`

---

### RF-4.12.5: Costo vs Ingreso

**Descripcion:** Calcular margen por viaje subcontratado.

**Calculo:**
```
Ingreso = Tarifa cobrada al cliente
Costo = Tarifa pagada al carrier
Margen = Ingreso - Costo
% Margen = Margen / Ingreso × 100
```

**Reportes:**
- Margen por viaje
- Margen por carrier
- Margen por ruta/lane
- Margen por cliente

**Alertas:**
- Margen < minimo configurado
- Carrier mas caro que promedio
- Tendencia de margen a la baja

**Tablas DDL:**
- `carriers.liquidaciones_carrier`
- Vista: `carriers.margen_por_viaje`

---

### RF-4.12.6: Scorecard de Carriers

**Descripcion:** Evaluar desempeno de carriers con metricas objetivas.

**Metricas del scorecard:**
| Metrica | Peso | Calculo |
|---------|------|---------|
| Puntualidad | 30% | % entregas a tiempo |
| Incidencias | 25% | Incidencias / 100 viajes |
| Calidad POD | 15% | % POD completos a tiempo |
| Documentos | 15% | % documentos al dia |
| Precio | 15% | Tarifa vs promedio mercado |

**Puntaje general:**
| Rango | Categoria | Accion |
|-------|-----------|--------|
| 90-100 | A (Excelente) | Prioridad en asignacion |
| 80-89 | B (Bueno) | Normal |
| 70-79 | C (Regular) | Monitoreo |
| <70 | D (Deficiente) | Revision/suspension |

**Tablas DDL:**
- `carriers.evaluaciones_carrier`
- `carriers.metricas_periodo`

---

## Requerimientos No Funcionales

### RNF-001: Portal de Carriers
- Acceso web para carriers
- Ver asignaciones y cargar documentos
- Subir POD

### RNF-002: Notificaciones
- Email/WhatsApp para RFQ
- Alertas de documentos por vencer
- Confirmacion de asignacion

### RNF-003: Seguridad
- Carriers solo ven sus viajes
- Documentos con acceso restringido

---

## Matriz de Trazabilidad

| RF | Tablas DDL | Endpoints | Historias |
|----|------------|-----------|-----------|
| RF-4.12.1 | carriers, documentos | POST /carriers | US-MAI014-001 |
| RF-4.12.2 | solicitudes, ordenes | POST /asignacion | US-MAI014-002 |
| RF-4.12.3 | documentos_carrier | GET /documentos | US-MAI014-001 |
| RF-4.12.4 | pod_carrier | POST /pod | US-MAI014-002 |
| RF-4.12.5 | liquidaciones | GET /margen | US-MAI014-003 |
| RF-4.12.6 | evaluaciones | GET /scorecard | US-MAI014-003 |

---

*REQUERIMIENTOS MAI-014 - ERP Transportistas v1.0.0*