portal-clientes-plan.md

---
name: Portal Clientes - Plan de Producto
description: Dashboard SEO como servicio para clientes. Setup + mantenimiento mensual.
type: plan
status: pendiente
created: 2026-04-09
---

# Portal Clientes — Dashboard SEO como Servicio

## Concepto
Dashboard branded para clientes de consultoría SEO. El cliente accede a `clientes.alexamigo.com`, ve sus datos en tiempo real y recibe emails periódicos con resumen.

**Modelo de negocio**: Setup inicial + mantenimiento mensual recurrente.

## Estado Actual
- **URL**: `clientes.alexamigo.com` | **Puerto**: 5015
- **Stack**: FastAPI + React/Vite + Tailwind
- **DB**: PostgreSQL (`portal_clientes`)
- **Path VPS**: `/home/ubuntu/proyectos-cloud/portal-clientes/`
- **Ya tiene**: Auth JWT, sistema client_mappings, proxy a Hub, páginas Dashboard/Rankings/Visibility/Reputation/Activity
- **Falta**: integrar APIs externas (SEMrush, Ahrefs, Sistrix), rediseñar frontend, emails automáticos, módulos configurables

---

## Módulos Base (incluidos en pack)

### 1. Ranking de Palabras Clave
- **Qué muestra**: Tracking de 10 keywords (geolocalizadas o no), posición actual, evolución, tendencia
- **Fuente datos**: ValueSERP (key: `248A78032FC94B41A195F9A5C4184B8D`)
- **Estado**: Ya funciona en Hub (BEE-Serps). Cron diario 02:00.
- **TODO**: Limitar a 10 KWs por cliente en el plan base. UI con gráfica de evolución por keyword.

### 2. Visibilidad SEO
- **Qué muestra**: Índice de visibilidad Sistrix, evolución temporal, comparativa con competidores
- **Fuente datos**: Sistrix
- **Estado**: Actualmente scraping HTML (sin API key). En Hub hay cron de visibilidad a las 06:00 pero usa fuente propia.
- **TODO**: Decidir si usar API Sistrix (de pago) o mantener scraping. Integrar histórico. Gráfica de línea temporal.
- **DECISIÓN PENDIENTE**: ¿Contratar API Sistrix o scraping?

### 3. Keywords Indexadas (SEMrush)
- **Qué muestra**: Número de keywords orgánicas, evolución, top keywords por tráfico
- **Fuente datos**: SEMrush API (key: `40d312b1e3e3a0b1c7d431e7105d2328`)
- **Estado**: Tiene API key. No integrado en Hub.
- **TODO**:
  - Endpoint en Hub para llamar SEMrush API: `https://api.semrush.com/` (domain organic search)
  - Primera carga: histórico (si la API lo permite)
  - Cron semanal: actualizar keywords orgánicas
  - Guardar en tabla nueva `semrush_organic_data` (client_id, domain, date, total_keywords, total_traffic, top_keywords jsonb)

### 4. Autoridad de Dominio
- **Qué muestra**: Domain Rating (DR) de Ahrefs, evolución, comparativa con competidores
- **Fuente datos**: Ahrefs API v3 (key: `fD9maoeUL3oT07NpMV5ZPbtuEnoOOQFWWa9JSdpx`)
- **Endpoints disponibles**: `/domain-rating`, `/domain-rating-history`, `/backlinks-stats`, `/refdomains`
- **Estado**: Tiene API key. No integrado en Hub.
- **TODO**:
  - Endpoint en Hub para Ahrefs `/domain-rating` y `/domain-rating-history`
  - Cron semanal: actualizar DR + backlinks count + refdomains count
  - Guardar en tabla nueva `ahrefs_authority_data` (client_id, domain, date, dr, backlinks, refdomains)

### 5. Reputación de Marca
- **Qué muestra**: Sentimiento online, resultados positivos/negativos/neutros, alertas, timeline
- **Fuente datos**: Sentinel (propio, ya en Hub)
- **Estado**: LISTO. Cron diario 04:00. Frontend ya tiene página Reputation.
- **TODO**: Solo pulir UI.

### 6. Auditoría Técnica Mensual
- **Qué muestra**: Resumen auditoría SF (errores, warnings, redirects, Core Web Vitals), evolución mes a mes
- **Fuente datos**: Screaming Frog headless en VPS
- **Estado**: Cron semanal lunes 03:00. Datos en `sf_audits`.
- **TODO**: Para clientes del dashboard, limitar a mensual. Mostrar resumen con métricas clave y comparativa vs mes anterior.

---

## Módulos Extra (add-on)

### Extra 1: Google Analytics 4
- **Qué muestra**: Sesiones, usuarios, páginas vistas, fuentes de tráfico, evolución
- **Fuente datos**: GA4 API (OAuth, ya configurado)
- **Estado**: Ya sincronizando en Hub. Cron diario 05:00. Tablas `ga_properties`, `ga_traffic_data`.
- **TODO**: Exponer en Portal Clientes. UI con gráficas de tráfico.

### Extra 2: Google Search Console
- **Qué muestra**: Impresiones, clics, CTR, posición media, top queries, top páginas
- **Fuente datos**: Google Search Console API
- **Estado**: MCP tools disponibles. No integrado en Hub como cron.
- **TODO**:
  - Integrar GSC API en Hub (OAuth o Service Account)
  - Cron semanal: sync datos GSC
  - Tabla nueva `gsc_data` (client_id, date, impressions, clicks, ctr, avg_position, top_queries jsonb)

### Extra 3: Google Ads
- **Qué muestra**: Gasto, conversiones, CPA, CTR, impresiones, top campañas
- **Fuente datos**: Google Ads API
- **Estado**: NO tiene. Necesita setup OAuth + cuenta API.
- **TODO**: Evaluar si merece la pena. Requiere: cuenta de desarrollador Google Ads, OAuth, token refresh.
- **COMPLEJIDAD**: Alta. Dejar para fase 2+.

### Extra 4: Redes Sociales
- **Qué muestra**: Seguidores, engagement, publicaciones, crecimiento
- **Fuente datos**: Meta API (Instagram/Facebook), X API
- **Estado**: Solo tiene X API (tier Free, 1500 reads/mes). Meta API no configurado.
- **TODO**: Evaluar. Probablemente empezar solo con métricas básicas.
- **COMPLEJIDAD**: Media-alta.

### Extra 5: Reseñas Google + Alertas Negativas
- **Qué muestra**: Rating medio, número reseñas, últimas reseñas, alerta si hay negativa nueva
- **Fuente datos**: Google Business Profile API o scraping Google Maps
- **Estado**: NO tiene. Prospector ya scrapea Google Maps, podría reutilizar lógica.
- **TODO**: Investigar Google Business Profile API. Alternativa: scraping con ValueSERP.
- **COMPLEJIDAD**: Media.

---

## Arquitectura Técnica

### Backend (Hub Beepeek)
Nuevos endpoints necesarios en Hub:

```
# SEMrush
GET /api/semrush/:clientId/organic          → keywords orgánicas actuales
GET /api/semrush/:clientId/organic/history   → histórico

# Ahrefs
GET /api/ahrefs/:clientId/authority          → DR + backlinks actual
GET /api/ahrefs/:clientId/authority/history   → histórico DR

# GSC (si extra)
GET /api/gsc/:clientId/overview              → métricas principales
GET /api/gsc/:clientId/queries               → top queries
```

### Nuevas tablas PostgreSQL (hub_beepeek)

```sql
-- SEMrush organic data
CREATE TABLE semrush_organic (
  id SERIAL PRIMARY KEY,
  client_id INTEGER REFERENCES clients(id),
  domain TEXT NOT NULL,
  date DATE NOT NULL,
  total_keywords INTEGER,
  total_traffic NUMERIC,
  top_keywords JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(client_id, date)
);

-- Ahrefs authority data
CREATE TABLE ahrefs_authority (
  id SERIAL PRIMARY KEY,
  client_id INTEGER REFERENCES clients(id),
  domain TEXT NOT NULL,
  date DATE NOT NULL,
  domain_rating NUMERIC,
  backlinks INTEGER,
  refdomains INTEGER,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(client_id, date)
);

-- GSC data (extra)
CREATE TABLE gsc_data (
  id SERIAL PRIMARY KEY,
  client_id INTEGER REFERENCES clients(id),
  date DATE NOT NULL,
  impressions INTEGER,
  clicks INTEGER,
  ctr NUMERIC,
  avg_position NUMERIC,
  top_queries JSONB,
  top_pages JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(client_id, date)
);
```

### Nuevos Crons

| Cron | Schedule | Qué hace |
|------|----------|----------|
| SEMrush Sync | `0 8 * * 1` (lunes 08:00) | Keywords orgánicas de todos los clientes |
| Ahrefs Sync | `0 9 * * 1` (lunes 09:00) | DR + backlinks de todos los clientes |
| GSC Sync | `0 10 * * 1` (lunes 10:00) | Search Console (si extra activado) |

### Portal Clientes (Frontend)
- Rediseñar Dashboard principal con cards por módulo
- Cada módulo = página con gráficas (Recharts, ya usado en Hub)
- Sistema de módulos: `client_mappings` ya tiene `tools_active` → usarlo para mostrar/ocultar secciones
- Responsive (móvil primero, el cliente lo verá en el móvil)

### Emails Automáticos
- Cron semanal/mensual (configurable por cliente)
- Template HTML con resumen de métricas
- CTA: "Ver dashboard completo" → link a clientes.alexamigo.com
- Envío: Brevo (ya usado en Prospector) o SMTP directo

---

## Fases de Desarrollo

### Fase 1 — APIs + Backend (prioridad)
1. Integrar SEMrush API en Hub (endpoint + tabla + cron semanal)
2. Integrar Ahrefs API en Hub (endpoint + tabla + cron semanal)
3. Decidir Sistrix (API vs scraping) e integrar
4. Verificar que Sentinel, SERPs, SF y GA4 ya exponen bien los datos

### Fase 2 — Frontend Portal Clientes
1. Rediseñar Dashboard principal (cards resumen de cada módulo)
2. Página Rankings: top 10 KWs, gráfica evolución, geo indicator
3. Página Visibilidad: Sistrix index + SEMrush KWs orgánicas + DR Ahrefs
4. Página Reputación: Sentinel (ya existe, pulir)
5. Página Auditoría: resumen SF mensual con evolución
6. Sistema de módulos activos/inactivos por cliente

### Fase 3 — Emails + Onboarding
1. Template email HTML branded
2. Cron de envío (semanal o mensual según config)
3. Panel admin para dar de alta cliente nuevo rápidamente
4. Documentación interna del flujo de onboarding

### Fase 4 — Extras
1. GSC integration
2. Google Ads (evaluar)
3. Reseñas Google
4. Redes sociales

---

## Decisiones Pendientes
- [ ] ¿Sistrix API de pago o mantener scraping?
- [ ] ¿Plan SEMrush actual permite suficientes llamadas API para múltiples clientes?
- [ ] ¿Límite de llamadas Ahrefs API al mes?
- [ ] ¿Pricing del servicio? (setup + mensual)
- [ ] ¿Branding: "Alex Amigo Dashboard" o marca separada?
- [ ] ¿Email con Brevo o SMTP propio?

---

## APIs Disponibles (resumen)

| API | Key | Rate Limit | Coste |
|-----|-----|------------|-------|
| ValueSERP | `248A78032FC94B41A195F9A5C4184B8D` | Según plan | Según plan |
| SEMrush | `40d312b1e3e3a0b1c7d431e7105d2328` | Según plan | Según plan |
| Ahrefs v3 | `fD9maoeUL3oT07NpMV5ZPbtuEnoOOQFWWa9JSdpx` | 60 req/min | Según plan |
| GA4 | OAuth + Service Account | Standard | Gratis |
| Sistrix | Sin API key (scraping) | N/A | Gratis (frágil) |