# REQUERIMIENTOS - MAI-008: Incidencias y Reclamaciones

**Modulo:** MAI-008
**Fuente:** REQ-GIRO-TRANSPORTISTA.md - Seccion 4.6
**Version:** 1.0.0

---

## Requerimientos Funcionales

### RF-4.6.1: Tipos de Incidencia

**Descripcion:** El sistema debe soportar un catalogo de tipos de incidencia del giro transporte.

**Tipos requeridos:**
| Tipo | Codigo | Severidad Default |
|------|--------|-------------------|
| Retraso | RETRASO | Media |
| Rechazo en entrega | RECHAZO | Alta |
| Dano a mercancia | DANO | Critica |
| Robo parcial/total | ROBO | Critica |
| Faltante | FALTANTE | Media |
| Devolucion | DEVOLUCION | Baja |
| Accidente | ACCIDENTE | Critica |
| Multa de transito | MULTA | Baja |

**Validaciones:**
- Cada tipo tiene severidad default configurable
- Tipos pueden tener campos adicionales obligatorios
- Tipos se asocian a workflows especificos

**Tablas DDL:**
- `tracking.tipos_incidencia`
- `tracking.campos_tipo_incidencia`

---

### RF-4.6.2: Flujo de Atencion

**Descripcion:** Las incidencias siguen un flujo de atencion estructurado.

**Estados del flujo:**
```
ABIERTA → ASIGNADA → EN_INVESTIGACION → PENDIENTE_EVIDENCIA →
PENDIENTE_APROBACION → RESUELTA → CERRADA
```

**Estados adicionales:**
- `RECHAZADA` - Incidencia invalida
- `CANCELADA` - Sin efecto
- `ESCALADA` - Requiere nivel superior

**Reglas:**
- No se puede cerrar sin resolucion documentada
- Escalamiento automatico si excede SLA
- Notificaciones a involucrados en cada cambio

**Tablas DDL:**
- `tracking.incidencias` (estado)
- `tracking.transiciones_incidencia`

---

### RF-4.6.3: Evidencias y Bitacora

**Descripcion:** Toda incidencia debe tener soporte documental y trazabilidad completa.

**Tipos de evidencia:**
- Fotos (dano, accidente, mercancia)
- Documentos (actas, reportes, facturas)
- Declaraciones escritas
- Correos/mensajes
- Reportes de policia/seguros

**Bitacora requerida:**
- Todos los comentarios con usuario/fecha
- Cambios de estado con motivo
- Archivos adjuntos con metadatos
- Asignaciones y reasignaciones

**Validaciones:**
- Minimo 1 evidencia para tipos DANO, ROBO, ACCIDENTE
- Fotos con geolocalizacion y timestamp
- Limite de tamano configurable

**Tablas DDL:**
- `tracking.evidencias_incidencia`
- `tracking.bitacora_incidencia`

---

### RF-4.6.4: Impacto Economico

**Descripcion:** Registrar y calcular costos derivados de incidencias.

**Conceptos de costo:**
| Concepto | Descripcion | Quien paga |
|----------|-------------|------------|
| Deducible | Pago a seguro | Empresa |
| Penalizacion SLA | Descuento al cliente | Empresa |
| Reexpedicion | Costo de reentrega | Cliente/Empresa |
| Multa transito | Infraccion | Operador |
| Dano mercancia | Valor danado | Seguro/Empresa |
| Faltante | Valor faltante | Operador/Empresa |

**Calculos:**
- Total por incidencia = suma de conceptos
- Asociacion a viaje para rentabilidad
- Asociacion a cliente para analisis

**Tablas DDL:**
- `tracking.costos_incidencia`
- Relacion con `billing.lineas_factura`

---

### RF-4.6.5: SLA de Incidencias

**Descripcion:** Tiempos maximos de respuesta por severidad.

**SLAs por severidad:**
| Severidad | Primera respuesta | Resolucion |
|-----------|-------------------|------------|
| Critica | 1 hora | 24 horas |
| Alta | 4 horas | 48 horas |
| Media | 8 horas | 72 horas |
| Baja | 24 horas | 5 dias |

**Reglas:**
- Escalamiento automatico al 80% del SLA
- Notificacion a supervisor al vencer
- Metricas de cumplimiento por equipo

**Tablas DDL:**
- `tracking.sla_incidencias` (configuracion)
- `tracking.incidencias` (timestamps)

---

### RF-4.6.6: Integracion a Facturacion

**Descripcion:** Impactos economicos se reflejan en facturacion.

**Escenarios:**
1. **Penalizacion al cliente** → Nota de credito
2. **Cargo al cliente** → Cargo adicional en factura
3. **Deduccion a operador** → Registro en liquidacion
4. **Reclamo a seguro** → Expediente separado

**Flujo:**
```
Incidencia cerrada con impacto →
Generar movimiento financiero →
Asociar a factura/nota/liquidacion
```

**Validaciones:**
- Impacto debe estar aprobado antes de facturar
- Trazabilidad incidencia ↔ movimiento financiero

**Tablas DDL:**
- `billing.movimientos_incidencia`
- Relacion con `settlements.deducciones`

---

## Requerimientos No Funcionales

### RNF-001: Tiempo de Respuesta
- Apertura de incidencia < 2 segundos
- Carga de evidencias < 5 segundos (fotos comprimidas)

### RNF-002: Disponibilidad
- App movil debe permitir registro offline
- Sincronizacion al recuperar conexion

### RNF-003: Auditoria
- Todos los cambios auditados
- Retencion minima 5 anos

### RNF-004: Notificaciones
- Push, email, WhatsApp segun configuracion
- Tiempo maximo de envio: 30 segundos

---

## Matriz de Trazabilidad

| RF | Tablas DDL | Endpoints | Historias |
|----|------------|-----------|-----------|
| RF-4.6.1 | tipos_incidencia | GET /tipos | US-MAI008-001 |
| RF-4.6.2 | incidencias, transiciones | POST/PATCH | US-MAI008-002 |
| RF-4.6.3 | evidencias, bitacora | POST /evidencias | US-MAI008-001 |
| RF-4.6.4 | costos_incidencia | POST /costos | US-MAI008-003 |
| RF-4.6.5 | sla_incidencias | Config | US-MAI008-002 |
| RF-4.6.6 | movimientos_incidencia | POST /impacto | US-MAI008-003 |

---

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