Plan de Implementación — Portal de Recursos CULTIVA IA

Resumen del proyecto

¿Qué estamos construyendo?

Un portal web privado para clientes de CULTIVA IA donde pueden acceder a sus skills y recursos comprados, solicitar nuevas automatizaciones mediante formulario guiado, consultar el estado de sus proyectos en un tablero Kanban en tiempo real y descargar los entregables generados por agentes IA. El acceso se gestiona con magic link (Supabase Auth), cada cliente ve únicamente sus datos y el equipo de CULTIVA administra asignaciones desde un panel interno. El MVP debe estar en producción en 3 semanas con un coste de infraestructura < 50 €/mes.

Decisiones de arquitectura

🗄️

Supabase como BaaS completo

Auth + PostgreSQL + Storage + Realtime en una sola plataforma. Elimina necesidad de servidor propio y encaja en el presupuesto.

🔒

Row Level Security (RLS)

Políticas RLS en Supabase garantizan aislamiento de datos por cliente en BD sin lógica extra en la API.

⚡

Procesamiento async de PDFs

Las Edge Functions enolan jobs en una tabla processing_queue; un worker separado procesa y actualiza estado para evitar timeouts.

🎨

shadcn/ui sin diseñador

Componentes Radix UI pre-estilizados con Tailwind. Velocidad máxima sin necesitar diseño personalizado.

🔄

Realtime acotado

Supabase Realtime solo en la tabla kanban_cards filtrado por proyecto activo, para no saturar conexiones.

🛡️

GDPR: cifrado de PDFs

Los archivos subidos se almacenan en bucket privado con tokens firmados de vida corta. Sin URLs públicas.

Grafo de dependencias

Supabase Schema + RLS + Auth │ ├─────────────────────────────────────────────┐ API Routes / Server Actions (Next.js) Supabase Storage (archivos) │ │ ├──────────────────────────┐ │ Autenticación magic link Módulos de datos │ │ (recursos, proyectos, │ │ kanban, briefs) │ │ │ │ Login UI + Layout Componentes UI (cliente) Edge Fn procesado PDF │ Panel de Admin (equipo)

Fase 1 — Fundamentos (Días 1–4)

1 Infraestructura y autenticación

T01

Configurar proyecto Next.js 14 + Supabase + Vercel

Inicializar el repositorio con create-next-app, instalar @supabase/supabase-js, configurar variables de entorno en Vercel (SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_KEY), y verificar que el primer deploy en preview funciona sin errores.

Criterios de aceptación

Repositorio GitHub conectado a Vercel con CI/CD automático
Variables de entorno accesibles en runtime sin exponerse en cliente
supabaseClient inicializado y devuelve 200 en health check
Deploy preview funciona en URL Vercel pública

Verificación

Tests: npm run build sin errores TypeScript
Manual: abrir URL Vercel y ver página de inicio
Manual: consola sin warnings de Supabase

T02

Diseñar schema SQL + RLS para clientes, recursos y proyectos

Crear las tablas profiles, clients, resources, projects, kanban_cards, briefs y deliverables en Supabase con sus relaciones FK. Activar RLS y escribir políticas para que cada usuario solo acceda a filas donde client_id = auth.uid().

Criterios de aceptación

Migrations SQL versionadas en supabase/migrations/
RLS activo en todas las tablas con datos de cliente
Test: usuario A no puede leer filas de usuario B
Índices en client_id y project_id

Verificación

supabase db push sin errores
Manual: SQL Editor en Supabase con auth simulada
Política de Storage: bucket briefs solo lectura propia

T03

Flujo completo de autenticación con magic link

Implementar páginas de login (/login) y callback (/auth/callback) usando Supabase Auth. El usuario introduce su email, recibe magic link, hace clic y queda autenticado con sesión en cookie httpOnly. Layout protegido redirige a /login si no hay sesión.

Criterios de aceptación

Email con link llega en < 30 s en entorno real
Clic en link genera sesión persistente (refresh token en cookie)
Rutas protegidas redirigen sin sesión
Logout limpia cookie y redirige a /login

Verificación

E2E manual: login completo en preview Vercel
DevTools: cookie sb-access-token httpOnly visible
URL protegida sin sesión → redirect 302 a /login

🔍

CHECKPOINT — Fase 1 (fin día 4)

npm run build sin errores en rama main
Deploy Vercel preview verde
Magic link funciona end-to-end con email real
RLS validado: usuario A no lee datos de usuario B
Revisión con equipo CULTIVA antes de continuar

Fase 2 — Features principales (Días 5–10)

2 Catálogo, Kanban y solicitud de automatizaciones

T04

Página de catálogo de recursos del cliente

Crear /dashboard/recursos que lista los recursos asignados al cliente autenticado (skill name, descripción, fecha de compra, botón de descarga). Datos servidos via Server Component con consulta Supabase filtrada por RLS.

Criterios de aceptación

Lista renderizada con datos reales de BD
Búsqueda por nombre (client-side filter)
Botón de descarga genera URL firmada 15 min de Supabase Storage
Estado vacío cuando no hay recursos asignados

Verificación

Manual: seed 3 recursos para usuario test, ver lista
Manual: link de descarga expira tras 15 min
Lighthouse: CLS < 0.1, LCP < 2 s

T05

Tablero Kanban en tiempo real (Supabase Realtime)

Implementar /dashboard/proyectos/[id] con columnas Pendiente / En progreso / Revisión / Hecho. Tarjetas de la tabla kanban_cards suscritas via Realtime filtrado por project_id. Drag-and-drop con @dnd-kit/core.

Criterios de aceptación

Mover tarjeta actualiza columna en BD y se refleja en otra pestaña < 500 ms
Máximo 1 suscripción Realtime por cliente activo
Sin errores con 20 tarjetas simultáneas en el mismo proyecto
Responsive: funciona en móvil con tap (sin drag)

Verificación

Manual: abrir 2 pestañas del mismo proyecto, mover tarjeta en una y ver actualización en la otra
DevTools: solo 1 WebSocket abierto por vista
Test de carga: 5 usuarios concurrentes, sin mensajes de error Realtime

T06

Formulario de solicitud de automatización + upload de brief PDF

Crear wizard de 3 pasos en /dashboard/nueva-solicitud: (1) tipo de automatización, (2) descripción + adjuntar PDF (brief), (3) confirmación. El PDF se sube a Supabase Storage en bucket privado. Se inserta una fila en briefs con estado pending.

Criterios de aceptación

Formulario valida campos obligatorios antes de cada paso
PDF acepta máx. 10 MB; rechaza otros tipos MIME
Fila en BD creada con status: pending y file_path
Email de confirmación enviado al cliente vía Supabase Edge Function

Verificación

Manual: subir PDF real, verificar fila en tabla briefs
Manual: intentar subir .exe → error claro
Storage: bucket solo acepta application/pdf
Email de confirmación en bandeja

T07

Agente IA: procesador asíncrono de briefs PDF → Markdown

Edge Function process-brief que: (1) lee el PDF de Storage, (2) extrae texto, (3) llama a Claude API para estructurar el brief en Markdown, (4) guarda el .md en Storage, (5) actualiza briefs.status a completed y crea fila en deliverables. Se dispara via Supabase Database Webhook al insertar en briefs.

Criterios de aceptación

PDF de 5 páginas procesado en < 30 s
Si falla, status queda en error con mensaje legible
Output .md guardado en Storage con path predecible
Notificación en tiempo real al cliente cuando completa

Verificación

Test: subir brief de prueba y esperar estado completed
Test: simular error de Claude API → estado error
Logs de Edge Function accesibles en Supabase Dashboard

🔍

CHECKPOINT — Fase 2 (fin día 10)

Flujo completo end-to-end: login → ver recursos → crear solicitud → Kanban actualizado
PDF procesado por agente IA y entregable disponible para descarga
Realtime Kanban verificado con 2 usuarios concurrentes
Sin regresiones en autenticación ni RLS
Review de código entre los 2 devs

Fase 3 — Panel de administración (Días 11–13)

3 Admin interno CULTIVA

T08

Panel admin: gestión de clientes y asignación de recursos

Sección /admin protegida por rol admin (claim personalizado en JWT). Tabla de clientes con CRUD básico: crear cliente, asignar/desasignar recursos, ver proyectos activos. Solo accesible para emails en lista de admins de CULTIVA.

Criterios de aceptación

Usuario sin rol admin recibe 403 al intentar acceder a /admin
Admin puede crear cliente e inmediatamente asignarle recursos
Admin ve lista de todos los proyectos y sus estados
Cambios persisten en BD con auditoría (campo updated_by)

Verificación

Manual: login con usuario no-admin → 403 en /admin
Manual: crear cliente real y verificar en Supabase Table Editor
JWT decode: claim role: admin presente

🔍

CHECKPOINT — Fase 3 (fin día 13)

Panel admin funcional con al menos 1 cliente real creado
Protección de roles verificada: no-admin bloqueado
Flujo admin completo: crear cliente → asignar recursos → cliente los ve en su dashboard

Fase 4 — Polish y producción (Días 14–15)

4 Calidad, seguridad y deploy final

T09

Hardening de seguridad y GDPR

Revisar políticas RLS con ojos de seguridad, añadir Content-Security-Policy headers en Next.js, confirmar que no hay URLs de Storage públicas, añadir página de política de privacidad y aviso de cookies mínimo. Validar que briefs PDFs se eliminan de Storage si el cliente borra su cuenta.

Criterios de aceptación

CSP headers en todas las rutas (sin unsafe-inline JS)
Ningún objeto de Storage accesible sin token firmado
Eliminación de cuenta elimina archivos asociados en cascade
Página /privacidad con información RGPD básica

Verificación

securityheaders.com: rating A o superior
URL directa de Storage → 403
Manual: eliminar cuenta test → archivos desaparecen de Storage

T10

Deploy a producción + dominio custom + monitoreo

Conectar dominio portal.cultivaia.com en Vercel, configurar variables de entorno de producción (Supabase prod project), activar Vercel Analytics y Sentry para captura de errores. Smoke test completo en producción antes de dar acceso a clientes.

Criterios de aceptación

SSL activo en dominio custom
Smoke test: login → catálogo → solicitud → Kanban en prod
Sentry captura al menos un error de prueba
Coste infra verificado < 50 €/mes (Vercel Hobby + Supabase Free)

Verificación

https://portal.cultivaia.com carga en < 2 s (PageSpeed > 85)
Sentry dashboard con proyecto conectado
Factura estimada Supabase + Vercel < 50 €

✅

CHECKPOINT FINAL — MVP listo (fin día 15)

Todos los criterios de aceptación de T01–T10 cumplidos
Smoke test completo en producción documentado
Seguridad: securityheaders.com rating A
Monitoreo activo: Sentry + Vercel Analytics
Coste infra < 50 €/mes confirmado
Revisión y aprobación final del equipo CULTIVA IA

Oportunidades de paralelización

Seguro en paralelo

T04 y T05 (desde T02+T03)
T05 y T06 (independientes)
Tests unitarios de componentes UI
Página /privacidad (GDPR)
Documentación de onboarding

Obligatoriamente secuencial

T01 → T02 → T03 (fundamentos)
T06 → T07 (upload antes de procesar)
T02 → T08 (schema antes de admin)
T01–T09 → T10 (todo antes de prod)

Requiere coordinación

T05 y T07 comparten tabla kanban_cards: definir schema primero
T06 y T08 comparten endpoint upload: acordar contrato API
Agente IA puede hacer T04 mientras devs hacen T05

Riesgos y mitigaciones

Riesgo	Impacto	Probabilidad	Mitigación
Timeout en Edge Functions al procesar PDFs grandes (> 15 pág)	Alto	Media	Arquitectura async con cola en BD; el cliente ve estado "en proceso" en Kanban
Datos sensibles en PDFs de clientes (GDPR)	Alto	Alta	Bucket privado + URLs firmadas de vida corta + cascade delete al eliminar cuenta
Saturación de Supabase Realtime con muchos proyectos activos	Medio	Baja (MVP)	Suscripción filtrada por project_id; 1 suscripción activa máx por cliente
Coste Claude API supera presupuesto en producción	Medio	Baja	Rate limit por cliente (máx. 5 briefs/mes en tier gratuito)
RLS mal configurado expone datos de otros clientes	Alto	Baja	Test específico en Checkpoint 1: usuario A no lee filas de usuario B

Preguntas abiertas (requieren decision humana)

Q1 ¿Se permite al cliente ver los PDFs de otros proyectos propios históricos, o solo los del proyecto activo? Afecta al schema de deliverables.
Q2 ¿El agente IA debe enviar notificación por email cuando el brief está procesado, o solo actualiza el estado en el Kanban?
Q3 ¿Cuánto tiempo se retienen los PDFs subidos por el cliente? ¿30 días, indefinido, o configurable por cliente?
Q4 ¿El panel admin necesita exportar datos a CSV/Excel para reporting, o es suficiente con la vista en pantalla para el MVP?

Referencia de tamaños de tarea

Talla	Archivos	Alcance	Ejemplo en este proyecto
XS	1	Función o config aislada	T09 – CSP headers en next.config.ts
S	1–2	Un componente o endpoint	T01 – Setup repositorio
M	3–5	Un slice de feature completo	T04 – Catálogo de recursos
L	5–8	Feature multi-componente	(evitado en este plan)
XL	8+	Demasiado grande — subdividir	N/A — todas las tareas son M o menores

Pre-flight checklist — antes de empezar a codear

Cada tarea (T01–T10) tiene criterios de aceptación explícitos
Cada tarea tiene pasos de verificación concretos
Dependencias identificadas y ordenadas (ninguna tarea bloquea por sorpresa)
Ninguna tarea toca más de 5 archivos (ninguna es XL)
Checkpoints entre cada fase (días 4, 10, 13, 15)
Tareas de alto riesgo (RLS, GDPR) son tempranas (Fase 1)
Preguntas abiertas listadas para decision humana antes de sprint
Plan revisado y aprobado por el equipo CULTIVA IA