# Contexto operativo

## Objetivo

El contexto operativo es el JSON vivo que se arma para cada pregunta. Debe incluir solo los datos necesarios, respetando permisos y evitando mandar tablas completas al modelo.

## Estructura base

```json
{
  "tenant": {
    "did": 1,
    "nombre": "Demo Lightdata",
    "fechaSistema": "2026-06-08",
    "timezone": "America/Buenos_Aires"
  },
  "usuario": {
    "did": 22,
    "perfil": "adm",
    "tipo": "adm",
    "alcance": "tenant"
  },
  "ui": {
    "modulo": "envios.listado",
    "filtros": {},
    "seleccion": [],
    "vista": {}
  },
  "intencion": "analisis_envios",
  "catalogos": {},
  "operacion": {},
  "documentos": []
}
```

## Contexto UI

El front puede mandar:

```json
{
  "modulo": "envios.listado",
  "filtros": {
    "tipoFecha": "estado",
    "desde": "2026-06-08",
    "hasta": "2026-06-08",
    "estados": [3,4]
  },
  "seleccion": [123,124],
  "vista": {
    "page": 1,
    "perPage": 50,
    "sort": { "col": "fechaEstado", "dir": "desc" }
  }
}
```

El backend debe tratar esto como sugerencia, no como permiso.

## Intenciones y datos

| Intencion | Datos vivos |
|---|---|
| `tracking` | envio exacto, historial, observaciones, asignaciones |
| `analisis_envios` | resumen, muestra filtrada, riesgos |
| `ruteo` | choferes, zonas, envios asignables, GPS si aplica |
| `cobranzas` | envios cobrables, liquidaciones, costos |
| `dashboard` | agregados por estado/zona/chofer, health |
| `ayuda_sistema` | documentos RAG, modulo activo |
| `explicar_liquidacion` | envio, historial, costos, estados pagables, liquidaciones |

## Datos minimos por envio

```json
{
  "did": 123,
  "tracking": "SEED-CABA-015",
  "cliente": "Deco Hogar",
  "origen": "Directo",
  "estado": 3,
  "estadoNombre": "En planta de procesamiento",
  "fechaVenta": "2026-06-06",
  "fechaEstado": "2026-06-06 10:17",
  "destino": {
    "nombre": "Lucia Ruiz",
    "cp": "1431",
    "localidad": "CABA",
    "zona": "CABA"
  },
  "chofer": "",
  "flags": {
    "sinChofer": true,
    "sinZona": false,
    "demorado": true,
    "cobranza": false,
    "logisticaInversa": false
  }
}
```

## Resumen operativo

```json
{
  "totalEnvios": 82,
  "porEstado": {
    "2": 9,
    "3": 14,
    "5": 21
  },
  "riesgos": {
    "sinChofer": 8,
    "sinZona": 3,
    "demorados": 12,
    "conCobranza": 5
  },
  "porZona": [],
  "porChofer": []
}
```

## Permisos

Respetar los controladores existentes:

- perfil chofer/logistica externa: solo envios asignados;
- perfil cliente: solo clientes vinculados;
- admin/coordinador: segun permisos del sistema;
- nunca mandar datos de otros tenants.

La seguridad real vive en backend. La UI no filtra como garantia.

## Limites

- muestra de envios: 25 a 60 maximo;
- historial por envio: ultimos 20 movimientos;
- docs RAG: 5 a 12 chunks;
- contexto IA cacheable: 60 a 180 segundos;
- no mandar payloads de integraciones salvo intencion especifica.

## Datos sensibles

Por defecto excluir:

- telefonos;
- emails;
- tokens;
- direcciones completas;
- payloads `dataCuenta`;
- valores de credenciales;
- logs crudos.

Incluirlos solo si la pregunta lo requiere y el perfil puede verlos.

## Fuentes

Toda respuesta deberia poder explicar de donde salio:

```json
[
  { "tipo": "db", "tabla": "envios", "did": 123 },
  { "tipo": "redis", "clave": "ops:1:envios:resumen" },
  { "tipo": "doc", "path": "docs/DICCIONARIO-DATOS.md", "titulo": "envios_historial" }
]
```