# Catálogo ITscope API — guía de uso

API de **solo-lectura** sobre el catálogo de ITscope filtrado a lo que vende PowerPlanet:
**275.339 productos · 46 familias · 1,6M specs**. Pensada para que ProductForge (y cualquier
agente) **contraste datos de productos sin alucinar**, consultando por SQL vía HTTP.

## Autenticación
Cabecera `Authorization: Bearer <TU_CLAVE>`.

## Endpoints
- `POST /query {sql, limit}` — manda un SELECT (solo lectura) → `{columns, row_count, rows}`.
- `GET /schema` — diccionario de datos en vivo (tablas, columnas, descripción).
- `GET /health` — estado.

## Regla de oro (anti-alucinación)
> Si un valor no aparece en `family_specs.top_values` de esa familia, **no existe**: no lo inventes.
> Si un campo es NULL o la familia tiene `reliability` baja, dilo, no supongas.

## Las tablas
| Tabla/Vista | Para qué |
|---|---|
| `products` | 1 fila por **SKU** (cada configuración). Match por `ean`, `manufacturer_sku`. |
| `specs` | specs técnicas `(puid, grp, name, value)`. Unir por `puid`. |
| `v_models` | 1 fila por **modelo** (agrupa variantes CTO). Para "qué modelos hay". |
| `catalog_map` | el mapa: familia → departamento, magnitud, fiabilidad, aviso. |
| `family_specs` | vocabulario real: atributos y valores válidos por familia. |
| `v_catalog` | products + department + reliability. |

## Ejemplos (lo que ProductForge consulta en paralelo)

```bash
# 1) Match por EAN -> producto + sus specs de confianza
curl -s https://catalogo.ppotools.net/query -H "Authorization: Bearer mk-..." \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT p.product_name,p.family,s.grp,s.name,s.value FROM products p JOIN specs s ON s.puid=p.puid WHERE p.ean=\"8806090322334\""}'

# 2) Vocabulario válido de una familia (para validar valores generados)
# {"sql":"SELECT spec_name, top_values FROM family_specs WHERE family=\"cellphones\""}

# 3) Mapa + fiabilidad de una familia
# {"sql":"SELECT department, reliability, note FROM catalog_map WHERE family=\"robot-vacuums\""}

# 4) Modelo (no SKU) por nombre
# {"sql":"SELECT model_name, n_skus FROM v_models WHERE family=\"notebooks\" AND model_key LIKE \"%macbook air 15%\""}
```

## Qué NO hay (no lo inventes)
Mascotas, electrodoméstico ES (Cecotec/Orbegozo), hi-fi nicho. Rugged chino casi vacío
(Doogee/Oukitel). Imágenes 3-14%. Nombres en EN/DE, no español. `pc-games`/`smartglasses` casi vacías.

## Operación
FastAPI con el SQLite dentro (`data/catalogo.sqlite`). Local: `uvicorn app:app --reload`.
Prod: `API_KEYS=... docker compose -f docker-compose.prod.yml up -d --build` (Traefik enruta
`catalogo.ppotools.net`). Actualizar datos: regenerar el `.sqlite` (desde `itscope-catalog`) y redeploy.