Manual de implementación

Guía para el desarrollador. Las pantallas HTML de este set (01-home, 02-explora, 03-portal-privado) son el diseño y la fuente de verdad de la experiencia. Este manual explica cómo llevarlas a producción sin rediseñar.

1 · Stack recomendado

Prioridad: rápido de indexar, fácil de mantener, barato de operar en esta etapa inicial.

• Front público: Astro o Next.js (SSR/SSG) para HTML indexable y buen rendimiento. Alternativa low-code: WordPress con maquetación fiel al HTML entregado.
• Portal privado: React/Next con auth. Puede empezar como app protegida sencilla.
• Auth: Supabase Auth, Auth0 o Clerk (email + magic link; roles cliente/equipo).
• Base de datos: Supabase/Postgres. Sirve datos, casos, usuarios y consumo.
• Hosting: Vercel o Netlify (front) + Supabase (datos/auth).

2 · Arquitectura y rutas

Tres capas. El front público vende, el privado opera al cliente, el backend gestiona la promesa.

3 · Fuente única de datos

Todo el catálogo sale de un solo lugar. En Fase 1 puede ser un JSON; en producción, tablas en la base. El prototipo 02-explora ya trae la estructura en el objeto AGENTS.

// datos_agentes.json
{
  "categorias": [
    { "id": "m", "nombre": "Marketing y canales digitales", "color": "#8b5cf6" },
    { "id": "i", "nombre": "Inteligencia de mercados y datos", "color": "#3b82f6" },
    { "id": "l", "nombre": "Ley de datos y ARCOP", "color": "#ef4444" },
    { "id": "o", "nombre": "Operación y gestión", "color": "#14b8a6" }
  ],
  "agentes": [
    {
      "id": "seo",
      "categoria": "m",
      "icono": "🔎",
      "nombre": "Agente SEO",
      "sinopsis": "Aparece en Google y en la IA.",
      "descripcion": "Optimiza tu web y crea contenidos para que te encuentren...",
      "tier": 1,                 // 1 Incluido · 2 Asistido · 3 Gestionado
      "planes": ["Start","Growth","Destination","Enterprise"],
      "listo_operar": true       // ¿opera con baja intervención? (define el equipo)
    }
  ]
}

Archivos hermanos: datos_planes.json (planes, límites, precios) y datos_biblioteca.json (guías/ayuda). Un responsable los mantiene.

4 · Componentes clave

• Card de agente: ícono, nombre, sinopsis de una línea, badge de tier, botón "＋ Mi propuesta". Color por categoría vía variable --cc.
• Fila/rail temático: scroll horizontal por categoría (patrón streaming).
• Recomendador: 2 preguntas (qué eres / qué buscas) → set sugerido. Lógica en objeto RECO del prototipo. Es el corazón anti-fricción.
• Drawer "Mi propuesta": carrito B2B (no checkout). Cierra con "Solicitar propuesta guiada" → crea caso LEAD/PROP.
• Ficha modal: descripción + tier + agregar/quitar.
• Panel privado: navegación por secciones (SPA simple), KPIs, filas de estado, barras de consumo, tiles de "crear solicitud".

5 · SEO / GEO (Google + motores de IA)

• Meta title y description únicos por página (ya en los HTML).
• canonical, Open Graph y Twitter Card por página.
• Schema.org: Organization + FAQPage en home; Service por vertical; Article + FAQPage en cada guía. (Ejemplo funcionando en 01-home.)
• Portal privado con robots: noindex, nofollow (ya aplicado en 03).
• URLs limpias por vertical y por guía (/guias/seo-turistico-google-ia).
• sitemap.xml + robots.txt; enviar a Search Console.
• Contenido en formato pregunta→respuesta (lo que citan los LLM). Publicar las guías como lead magnets.
• Perfiles consistentes (mismo nombre + URL) en directorios para reforzar señales a la IA.

6 · Modelo comercial

Vender plan por acceso (no agente suelto) + pack recomendado + add-ons. Los tiers protegen margen.

Tiers de entrega: 🟢 T1 Incluido (baja intervención, dentro del plan) · 🟡 T2 Asistido (setup/acompañamiento) · 🔴 T3 Gestionado (ejecución senior, cobro o créditos adicionales). Los add-ons y gestionados consumen créditos para proteger margen.

7 · Backend de casos (la columna operacional)

Sin esto, el portal vende promesas que no puede operar. Se construye junto al front, no después. Cada acción del usuario genera un caso con responsable, estado y SLA.

Cada caso guarda: prioridad (normal/48h/24h), responsable, SLA, consumo_creditos e historial. El panel privado y el panel interno leen de la misma tabla.

8 · Integraciones

• CRM (HubSpot o Pipedrive): los casos LEAD/PROP se sincronizan al pipeline comercial.
• Google Analytics 4 + Tag Manager: eventos clave = ver_ficha, agregar_a_propuesta, solicitar_propuesta, diagnostico_completado.
• WhatsApp Business y Calendly para contacto y demos.
• Email transaccional (Resend/SendGrid) para confirmaciones y estados de caso.
• Marcadores de conversión listos en los CTAs de los prototipos.

9 · Accesibilidad y UX (no negociable)

• Contraste mínimo AA; tamaños de fuente ≥ 14px en cuerpo, ≥16px en móvil.
• Una decisión por pantalla; máximo 3 pasos para la acción clave.
• Lenguaje simple, sin jerga técnica (mantener el tono de los prototipos).
• Estados claros (cargando, éxito, error) y textos de ayuda visibles.
• Responsive real (los prototipos ya traen breakpoints 860/640px).
• Foco visible en teclado; aria-label en íconos y botones.

10 · QA de entrega (checklist)

• HTTPS válido + redirecciones + PageSpeed móvil > 80.
• Metadatos y Schema.org verificados (Rich Results Test).
• Todos los CTAs enlazan y disparan evento GA4.
• "Mi propuesta" crea caso y notifica al equipo.
• Portal privado tras login; datos por usuario; noindex.
• Prueba con 2–3 clientes amistosos: ¿entienden, arman su set y aceptan avanzar?
• Sin promesas de autoservicio "un clic y listo" en ningún microcopy.

11 · Fases y orden de construcción

1. Fase 0 (1–2 sem): SSL + indexación + fuente única de datos + design system.
2. Fase 1 (3–4 sem): vitrina pública (home, explora, planes, ARCOP, guías). Sale a testear.
3. Fase 2 (2–3 sem): "Mi propuesta" + diagnóstico + CRM + GA4 (casos LEAD/PROP).
4. Fase 3 (4–6 sem): portal privado + backend de casos con SLA (en paralelo).
5. Fase 4 (iterativo): automatización de agentes, créditos/consumo, dashboards, agentes custom.