# Quickstart: Agregación de contratos por cualquier columna

**Feature**: `006-contratos-conteo-agrupado` | **Date**: 2026-05-28

Guía de verificación manual de la herramienta `agregar_contratos_unicliente`.

## Prerrequisitos

- Feature **005** implementada (modelos `PropuestaComercialCups`, `PuntoSuministro`, `CupsElectrico/Gas`, `TarifaElectrica/Gas`, `Cliente.localidadSocial`).
- Conexión `agent_db_secondary` configurada y accesible con datos de contratos Unicliente (`TipProCom` 1 y 2).
- `LLM_PROVIDER` configurado; capacidad `agent_database` habilitada.
- Cache del catálogo invalidada tras editar config:

```bash
php artisan cache:forget agent_database_queries_catalog
```

## Preguntas de prueba (chat)

| # | Pregunta | Resultado esperado |
|---|----------|--------------------|
| 1 | "¿Cuántos contratos hay por localidad?" | Tabla localidad → nº de contratos; suma coherente con el total general; **sin** "lista truncada". |
| 2 | "¿Cuántos contratos por localidad y mes?" | Filas (localidad, mes, total); cubre todas las localidades/meses reales. |
| 3 | "Número de contratos por tipo de energía" | Eléctrico vs gas con totales exactos. |
| 4 | "Distribución de contratos por tarifa eléctrica" | Cada tarifa con su total. |
| 5 | "Consumo eléctrico total por localidad" | `SUM(ConCup)` por localidad + total general. |
| 6 | "Potencia P1 media por tarifa" | `AVG(PotEleConP1)` por tarifa. |
| 7 | "Consumo de gas máximo y mínimo por provincia" | `MAX`/`MIN(CauDiaGas)` por provincia. |
| 8 | "¿Cuántos contratos por dirección de suministro?" | Top-N por total desc + aviso "hay más"; conteo sobre todos los registros. |
| 9 | "Cuenta contratos por color" (columna inexistente) | Rechazo amable + sugerencia de columnas válidas. |
| 10 | "Suma de la localidad" (operación numérica sobre no-numérica) | Rechazo + propuesta de `count` o medidas numéricas. |

## Verificación técnica

1. **Suma de grupos == total** (dimensión por-contrato): para la pregunta 1 usando `localidad_cliente`, la suma de los totales por grupo debe igualar `COUNT(DISTINCT CodProCom)` global del criterio (SC-001).
2. **Sin truncado**: la respuesta nunca incluye el aviso de "lista truncada"; el payload interno tiene `truncated: false` (SC-002).
3. **Operaciones numéricas exactas**: comparar `SUM(ConCup)` de la pregunta 5 con una consulta SQL directa de control (SC-007).
4. **Rechazos**: preguntas 9 y 10 devuelven `agent_query_invalid_params` y el asistente lo explica sin inventar datos (SC-004, SC-008).
5. **Nulos**: localidades/medidas nulas aparecen como "Sin dato" sin perderse del total (FR-008, FR-020).

## Comandos útiles

```bash
# Tests del servicio (sin BD real)
php artisan test --filter=ContratosAgregado

# Estilo
./vendor/bin/pint --dirty

# Invalidar catálogo de herramientas tras tocar config/agent.php
php artisan cache:forget agent_database_queries_catalog
```

## Notas

- COUNT cuenta **contratos** (`DISTINCT CodProCom`), no filas de CUPS. En dimensiones de suministro (localidad/dirección/tarifa) un contrato MultiPuntos puede aparecer en varios grupos; el total general reporta contratos distintos globales.
- El alcance es `TipProCom ∈ {1,2}`; `TipProCom = 3` está fuera de alcance.