first commit

docs/ARCHITECTURE.md

@@ -0,0 +1,29 @@
+# Arquitectura (2 mini-PCs)
+
+## Objetivo
+Separar la ingesta/normalización del producto (API + dashboard) para reducir carga y permitir escalado gradual.
+
+## Mini-PC 1 — Ingesta y procesamiento
+- **Servicios**: workers de ingesta, normalizadores, colas ligeras.
+- **Responsabilidad**: consultar datos.gob.es, normalizar y guardar en Postgres.
+- **Componentes clave**:
+  - Scheduler de ingesta (`INGEST_CRON`)
+  - Bull + Redis (opcional)
+  - Normalizador y clasificador
+
+## Mini-PC 2 — Producto y entrega
+- **Servicios**: API Nest, Nuxt dashboard, alertas Telegram/SMTP, backups.
+- **Responsabilidad**: servir datos, dashboards y notificaciones.
+- **Componentes clave**:
+  - API `apps/api`
+  - Dashboard `apps/web`
+  - Scheduler alertas (`ALERTS_CRON`) y backups (`BACKUP_CRON`)
+
+## Comunicación
+- API HTTP/REST entre servicios.
+- Redis opcional si se utiliza colas de ingestión.
+
+## Datos
+- Postgres centralizado (en Mini‑PC 1 o 2 según recursos).
+- Backups periódicos en `BACKUP_DIR`.
+

docs/DEPLOYMENT.md

@@ -0,0 +1,46 @@
+# Despliegue en mini‑PCs
+
+## Requisitos
+- Docker + Docker Compose
+- Postgres y Redis (opcional)
+
+## Variables de entorno recomendadas
+- `DATABASE_URL`
+- `API_ADMIN_KEY`
+- `JWT_SECRET`
+- `INGEST_CRON`
+- `ALERTS_CRON`
+- `BACKUP_CRON`
+- `BACKUP_DIR`
+- `INGEST_ENABLED`
+- `ALERTS_ENABLED`
+- `BACKUP_ENABLED`
+- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM`
+- `TELEGRAM_BOT_TOKEN`, `TELEGRAM_DEFAULT_CHAT`
+
+## Arranque rápido (todo‑en‑uno)
+```bash
+# Desde la raíz del repo
+pnpm install
+pnpm build
+pnpm start
+```
+
+## Arranque con Docker Compose
+```bash
+docker compose build
+docker compose up -d
+```
+
+## Estrategia recomendada (2 mini‑PCs)
+1. **Mini‑PC 1**: ejecutar Postgres + Redis + jobs de ingesta.
+2. **Mini‑PC 2**: ejecutar API + web + backups + alertas.
+3. Definir `DATABASE_URL` apuntando al Postgres del Mini‑PC 1.
+
+Sugerencia de flags:
+- Mini‑PC 1: `INGEST_ENABLED=true`, `ALERTS_ENABLED=false`, `BACKUP_ENABLED=false`.
+- Mini‑PC 2: `INGEST_ENABLED=false`, `ALERTS_ENABLED=true`, `BACKUP_ENABLED=true`.
+
+## Backups
+- Programados por `BACKUP_CRON`.
+- Manual: `POST /admin/backup/run`.

docs/KPIS.md

@@ -0,0 +1,17 @@
+# KPIs y métricas
+
+## KPIs iniciales
+- **Tiempo medio de detección**: minutos desde la publicación hasta la ingesta.
+- **Cobertura del catálogo**: % de datasets detectados vs. catálogo total.
+- **Tasa de alertas útiles**: % de alertas calificadas como relevantes en pilotos.
+- **Conversión piloto → cliente**: ratio de pilotos que pagan al mes 2.
+
+## Métricas operativas (hoy)
+- `ingest_runs`: duración, errores, datasets nuevos/actualizados.
+- `alert_runs`: perfiles procesados, alertas enviadas/fallidas.
+- `/admin/monitor/status`: conteos globales.
+
+## Recolección recomendada
+- Log de timestamps de ingesta por dataset (para medir detección).
+- Feedback por alerta (útil/no útil) en UI de piloto.
+

docs/OPERATIONS.md

@@ -0,0 +1,19 @@
+# Operaciones y monitorización
+
+## Endpoints admin
+- `POST /admin/ingest/pause` / `resume`
+- `POST /admin/ingest/queue`
+- `GET /admin/ingest/runs`
+- `POST /admin/backup/run`
+- `GET /admin/backup/list`
+- `GET /admin/alerts/runs`
+- `GET /admin/monitor/status`
+
+## Checks rápidos
+- `/dashboard/summary` (salud del dashboard)
+- `/catalog/health` (API catálogo)
+
+## Logs
+- Logs de ingesta y alertas quedan en stdout.
+- `ingest_runs` y `alert_runs` guardan historial resumido.
+