7.3.2 — Añadir nuevas integraciones de contenido

[Azfe]

7.3.2 — Añadir nuevas integraciones de contenido

🎯 Objetivo

Incorporar nuevas integraciones de contenido al portfolio que permitan enriquecer la información mostrada, aumentar su valor profesional y preparar el producto para consumir fuentes externas de manera controlada. Esta feature aporta valor porque abre la puerta a mostrar repositorios, actividad técnica, contenido sincronizable o bloques dinámicos relevantes sin comprometer la claridad, mantenibilidad ni estabilidad del portfolio.

📦 Alcance

Incluye

• Evaluar integraciones de contenido que encajen con el propósito del portfolio, priorizando casos como GitHub para repositorios/actividad, LinkedIn como referencia futura o un CMS/headless source para contenidos gestionables.
• Definir el alcance funcional de la integración elegida en esta iteración: qué datos se mostrarían, dónde aparecerían y con qué frecuencia o estrategia se actualizarían.
• Diseñar el contrato técnico mínimo necesario entre frontend, backend y/o fuente externa si la integración requiere consumo real de datos.
• Preparar una implementación inicial basada en mock, estructura estática o adaptador simple si todavía no compensa conectar la integración completa.
• Determinar si la integración debe resolverse desde frontend, desde backend o mediante una capa intermedia/adaptador respetando la arquitectura actual.
• Validar que la integración no degrada el rendimiento, no rompe rutas principales y mantiene una UX coherente con el resto del portfolio.
• Documentar supuestos, límites, fallback y evolución futura de la integración seleccionada.

Fuera de alcance (Out of Scope)

• Implementar múltiples integraciones completas en una sola iteración si no hay un caso de uso claro.
• Convertir el portfolio en un agregador complejo de datos externos.
• Añadir autenticación avanzada OAuth o flujos de autorización complejos si no son imprescindibles para el MVP de esta feature.
• Introducir dependencias externas inestables sin estrategia de fallback o control de errores.
• Reescribir la arquitectura del backend o frontend para acomodar una integración puntual.
• Sincronización bidireccional, paneles de administración o gestión editorial completa.

🛠️ Tareas (Sub-issues)

• [I-F-7.3.2-01] Revisar la documentación del proyecto y las futuras extensiones contempladas para identificar integraciones de contenido viables.
• [I-F-7.3.2-02] Priorizar la fuente externa o integración candidata para esta iteración, con foco inicial en GitHub y alternativas futuras como LinkedIn o CMS.
• [I-F-7.3.2-03] Definir el caso de uso concreto de la integración: repositorios, actividad, contenido editorial, logros o bloques sincronizados.
• [I-F-7.3.2-04] Determinar si la integración debe consumirse directamente en frontend, encapsularse en backend o modelarse mediante un adaptador compatible con Clean Architecture.
• [I-F-7.3.2-05] Diseñar el contrato de datos mínimo necesario: campos, formato, manejo de errores, fallback y límites de actualización.
• [I-F-7.3.2-06] Preparar servicios, tipos o adaptadores necesarios para representar la integración sin acoplar en exceso la aplicación a un proveedor externo.
• [I-F-7.3.2-07] Implementar una primera versión funcional o una base integrable con mocks/fixtures si la conexión real se pospone.
• [I-F-7.3.2-08] Integrar visualmente el contenido en la ruta, sección o componente más adecuado del portfolio.
• [I-F-7.3.2-09] Validar comportamiento ante errores, ausencia de datos, latencia o indisponibilidad del proveedor externo.
• [I-F-7.3.2-10] Ejecutar checks mínimos de calidad y documentar el alcance final, dependencias y posibles siguientes pasos.

✅ Criterios de Aceptación (AC)

• Existe una integración de contenido candidata claramente definida y justificada para el portfolio.
• La solución especifica qué datos se consumen, dónde se muestran y qué estrategia técnica se utilizará.
• La integración propuesta respeta la arquitectura actual del proyecto y evita acoplamiento innecesario con el proveedor externo.
• El portfolio mantiene un comportamiento controlado si la fuente externa falla, responde lento o no devuelve datos.
• La interfaz resultante mantiene coherencia con Home, CV, Proyectos y las nuevas secciones que puedan añadirse.
• No se introducen endpoints o flujos innecesarios si la solución puede resolverse de forma más simple en esta iteración.
• Queda documentado el contrato técnico mínimo y la base para ampliar la integración en futuras features.

🛡️ Definition of Done (DoD)

• Integración candidata priorizada.
• Caso de uso definido.
• Contrato técnico documentado.
• Servicios/tipos/adaptadores preparados.
• Integración visual básica resuelta o mockeada.
• Fallback y errores contemplados.
• Lint, build y validación funcional revisados.
• Documentación mínima actualizada.

🔗 Dependencias & Contrato

• EPIC relacionada: EPIC 7.3 — Nuevas funcionalidades.
• Dependencias previas recomendadas: EPIC 4.4 — Integración con API (Backend), EPIC 4.3 — Implementación de páginas principales, EPIC 4.2 — Arquitectura base del frontend, 7.2.3 — Refactorizar integración frontend + backend, 7.2.5 — Validar estabilidad tras refactorización y 7.3.1 — Añadir nuevas secciones al portfolio.
• Contexto de integraciones actual: la documentación del proyecto indica que actualmente el portfolio no consume APIs externas para datos dinámicos, pero contempla futuras extensiones como API de GitHub para mostrar repositorios, API de LinkedIn para sincronizar experiencia laboral y API de Notion o CMS headless para gestionar contenido.
• Criterio arquitectónico: la integración debe introducirse mediante servicios, adaptadores o contratos claros, manteniendo separadas las responsabilidades de frontend, backend e infraestructura.
• Contexto técnico relevante: frontend en Astro + TypeScript + Tailwind CSS; backend en FastAPI + MongoDB; comunicación por HTTP/HTTPS y payloads JSON; posibilidad de usar React islands solo si la interacción lo justifica.
• Archivos o zonas candidatas: src/services/api/, src/types/, componentes de Home/CV/Proyectos o nuevas secciones del frontend; y en backend posibles adaptadores, casos de uso, repositorios o endpoints si una integración real lo exige en una fase posterior.
• Endpoints involucrados: en esta feature no es obligatorio crear endpoints nuevos. Pueden reutilizarse contratos existentes o modelarse integraciones futuras alrededor de GET /api/profile, GET /api/cv u otros recursos ya definidos. Si se decide encapsular una fuente externa desde backend en iteraciones posteriores, el contrato deberá documentarse antes de implementar nuevos endpoints.
• Servicios externos candidatos: GitHub, LinkedIn y un CMS/headless source como futuras opciones de contenido.
• Modelos de Prisma afectados: ninguno. El proyecto no usa Prisma; la persistencia prevista se basa en MongoDB.
• Restricciones importantes: mantener fallback claro, evitar dependencia fuerte del proveedor, no introducir secretos inseguros en frontend y no degradar rendimiento ni estabilidad general del portfolio.

🌿 Branching

feat/7.3.2-content-integrations