Guía del Desarrollador

Bienvenido a la documentación del front-end del proyecto Verticals Subscription E-Commerce de Alebat Education. Este documento es tu punto de partida: te da contexto general, te orienta sobre cómo funciona todo a alto nivel, y te enlaza a las secciones donde cada tema se profundiza.

Tip

Si ya conoces el proyecto y solo necesitas un recordatorio rápido de reglas o comandos, usa la tabla de contenidos a la derecha para saltar a la sección que necesites.

---

Qué es este proyecto

Una plataforma de e-commerce educativo por suscripción desplegada actualmente como Inspiria Dental. Permite a profesionales de la salud acceder a cursos, webinars, videos, libros digitales y eventos en vivo mediante suscripciones o compras individuales.

La arquitectura está diseñada como multi-vertical: una sola base de código que puede servir múltiples marcas educativas. Cada vertical tiene su propio branding, APIs, contenido y páginas — pero comparte la infraestructura, componentes, y lógica de negocio. Actualmente solo Inspiria Dental está activa, pero el sistema está preparado para escalar a más verticales sin duplicar código.

Funcionalidades principales:

• Streaming de video adaptativo (HLS) con seguimiento de progreso
• Sistema de suscripciones integrado con Stripe (planes anuales/mensuales)
• Contenido multi-idioma con fallback automático (español, inglés, portugués)
• Catálogo de productos: cursos, libros, presenciales, series de video, lives
• Búsqueda global, filtros por categoría, y perfiles de protagonistas/expertos
• Dashboard de usuario con historial de compras, gestión de suscripción, y perfil

---

Ficha técnica

Framework	Nuxt 4.2.1 + Vue 3.5.25 + TypeScript 5.9.3
Tipo de aplicación	SPA (Single Page Application) — sin SSR, todo client-side
UI	Tailwind CSS 3.4 + @alebat-education/ecom-components (librería propia)
Estado	Pinia 3.0 — 7 stores con persistencia en localStorage
Datos	Strapi 5 (headless CMS) via capa de servicios propia
Pagos	Stripe (checkout sessions, suscripciones, webhooks)
Deploy	AWS S3 + CloudFront CDN — automático al merge a main
Idiomas	Español (default), Inglés, Portugués Brasil
Package manager	pnpm (obligatorio — no uses npm ni yarn)
Repositorio	github.com/Alebat-Education/verticals-subscription-ecommerce
URL producción	https://inspiriadental.com

---

Setup del entorno

1. Requisitos previos

   • Node.js 20+ instalado
   • pnpm instalado globalmente (npm install -g pnpm)
   • Acceso SSH configurado para la organización Alebat-Education en GitHub
   • VS Code con las extensiones listadas abajo

2. Clonar e instalar

   git clone git@github.com:Alebat-Education/verticals-subscription-ecommerce.git
   cd verticals-subscription-ecommerce
   pnpm install

   Note

   El pnpm install descargará @alebat-education/ecom-components desde un registry privado de GitHub. Si falla la autenticación, asegúrate de tener un token de GitHub con scope read:packages configurado en tu ~/.npmrc.

3. Variables de entorno

   El proyecto requiere un archivo .env en la raíz que contiene URLs de APIs, keys de Stripe, tokens de servicios, y configuración de analytics. No está en el repositorio por seguridad — solicítalo al responsable del proyecto.

4. Arrancar el servidor

   pnpm dev

   El servidor arranca en http://localhost:3000 (Inspiria Dental). El puerto determina qué vertical se muestra: 3000 = primera (Inspiria), 3001 = segunda, etc.

---

Comandos del día a día

Comando	Qué hace	Cuándo usarlo
pnpm dev	Servidor de desarrollo con Hot Module Replacement	Mientras desarrollas
pnpm build	Build de producción (SPA)	Verificar que no hay errores de build
pnpm generate	Genera sitio estático en .output/public/	Lo ejecuta el CI para deploy
pnpm lint:fix	Ejecuta ESLint y auto-corrige lo que pueda	Antes de commitear, o si el hook falla
pnpm styles:fix	Ejecuta Stylelint en archivos CSS/Vue	Si tienes errores de estilo CSS
pnpm format	Formatea todo el proyecto con Prettier	Si el formato está inconsistente
pnpm test	Ejecuta tests unitarios (Vitest)	Antes de crear PR
pnpm clean	Limpia .nuxt/, .output/, node_modules/.cache/	Si algo se comporta raro tras un cambio de dependencias

Tip

Los comandos lint:fix, styles:fix y format se ejecutan automáticamente como pre-commit hooks via Husky. Si tu commit falla, suele ser porque el hook detectó un error que no pudo auto-corregir. Lee el error, corrígelo, y reintenta.

---

Las 10 reglas que no puedes romper

Estas reglas están enforced por ESLint + pre-commit hooks. Si las violas, git commit falla y no puedes avanzar. No son sugerencias — son restricciones del proyecto:

#	Prohibido	Qué hacer en su lugar	Por qué
1	var	const (default) o let si necesitas reasignar	Block scoping, evita bugs por hoisting
2	console.log()	Eliminar toda traza de debug antes de commit	Performance en prod, no exponer datos internos
3	SVGs inline en templates	<Icon name="heroicons:nombre" />	Consistencia, mantenibilidad, bundle size
4	import { ref } from 'vue'	Usar ref() directamente (auto-importado)	Nuxt auto-importa toda la API de Vue
5	any en TypeScript	Tipo específico, o unknown con type narrowing	Type safety — any desactiva todas las protecciones
6	Colores hardcodeados (#00ffa8, rgb(...))	Clases Tailwind: bg-primary, text-graphite	Los colores cambian por vertical, deben ser dinámicos
7	this.$route / this.$router	Composables: useRoute(), useRouter()	Más testeable, funciona en <script setup>
8	Mutar props directamente	Emitir un evento al padre con el nuevo valor	Flujo de datos unidireccional — evita bugs difíciles de rastrear
9	Comentarios HTML (<!-- ... -->)	Eliminar antes de commit	Código comentado no va a producción
10	Magic strings/numbers	Extraer a constants/ como constante nombrada	Single source of truth, refactoring seguro

Para una lista extendida con más reglas de calidad y anti-patrones comunes, lee Buenas Prácticas y Lo que NUNCA debes hacer.

---

Cómo funciona el proyecto (vista de pájaro)

Entender estos 4 conceptos es suficiente para empezar a ser productivo:

1. Páginas son delegadores, layouts tienen la lógica

Las páginas (app/pages/) son archivos de ~7 líneas. No contienen UI ni lógica. Solo invocan un layout que depende de la vertical activa:

<!-- app/pages/courses/index.vue — TODA la página es esto -->
<script setup lang="ts">
import { chooseLayoutPage } from '~/core/plugins'
const layout = chooseLayoutPage({ page: 'courses', commonLayout: false })
</script>
<template>
  <NuxtLayout :name="layout"></NuxtLayout>
</template>

La UI real vive en app/layouts/pages/inspiria/courses.vue (200+ líneas). Esto permite que la misma ruta muestre contenido diferente por vertical.

Más detalles: Tutorial: Crear una Página

2. Datos del backend siempre via useServices

Nunca importes un servicio directamente. Siempre usa el composable useServices:

// Modo reactivo — se actualiza con navegación, incluye loading state
const { data, isPending } = useServices('getCourses')

// Con parámetros dinámicos
const { data } = useServices('getCourseBySlug', { slug: route.params.slug })

// Modo promesa — para lógica imperativa
const result = await useServices('getCourses', undefined, { promise: true })

useServices resuelve la función correcta desde la vertical activa, inyecta el idioma del usuario, y aplica un sistema de fallback que rellena campos vacíos con traducciones del idioma por defecto (español).

Más detalles: Servicios y useServices

3. Componentes compartidos vienen de ecom-components

La librería @alebat-education/ecom-components provee 30+ componentes prefijados con AE:

<AEMainCard :product="course" />
<AETheModal v-model="showModal">...</AETheModal>
<AETheAlert />
<AEMainButton @click="buy">Comprar</AEMainButton>

No necesitas importarlos — se auto-registran globalmente via el módulo Nuxt.

Más detalles: Librería ecom-components

4. Estilos con Tailwind + CSS variables por vertical

Los colores del proyecto son CSS variables que cambian según la vertical activa. Están mapeados a clases Tailwind:

<div class="bg-primary text-white">Color principal de la marca</div>
<div class="text-graphite">Texto oscuro estándar</div>
<div class="border-secondary">Borde color secundario</div>

Nunca uses colores hex directos. Si la vertical cambia de marca, todos los colores se actualizan automáticamente.

Más detalles: Estilos y Tailwind

---

Convenciones de commit

El proyecto usa Conventional Commits enforced por CommitLint. El formato es:

tipo(scope): descripción imperativa en minúsculas sin punto final

Tipos disponibles:

Tipo	Cuándo	Ejemplo
feat	Nueva funcionalidad	feat(checkout): add promo code validation
fix	Corrección de bug	fix(auth): resolve infinite loop on token refresh
refactor	Reestructuración sin cambio funcional	refactor(services): extract common query builder
style	Cambios de formato (no CSS)	style(components): fix indentation in cards
test	Tests nuevos o modificados	test(buyflow): add unit tests for subscription logic
docs	Documentación	docs(readme): update setup instructions
chore	Dependencias, config, build	chore(deps): update ecom-components to latest
ci	Pipeline CI/CD	ci(deploy): fix S3 sync command

Reglas del mensaje:

• Todo en minúsculas (no Fix sino fix)
• Verbo imperativo: add, fix, remove — no added, fixing
• Sin punto final
• Máximo ~72 caracteres en la primera línea

Más detalles: Buenas Prácticas: Commits y Git

---

Flujo de trabajo habitual

1. git checkout main && git pull
2. git checkout -b 123-descripcion-corta
3. Desarrollar (commits frecuentes con conventional commits)
4. pnpm lint:fix && pnpm format  (los hooks lo hacen solo, pero por si acaso)
5. git push origin 123-descripcion-corta
6. Crear PR en GitHub (con template lleno)
7. Esperar review de Copilot + revisión manual
8. Merge a main → deploy automático a producción

Caution

Nunca hagas push directo a main. La rama está protegida — siempre via Pull Request. El deploy se dispara automáticamente al merge.

---

Extensiones VS Code obligatorias

Estas extensiones son necesarias para que el entorno funcione correctamente con las herramientas del proyecto:

Extensión	ID	Para qué
ESLint	dbaeumer.vscode-eslint	Muestra errores de lint inline mientras escribes
Prettier	esbenp.prettier-vscode	Formatea al guardar siguiendo las reglas del proyecto
Stylelint	stylelint.vscode-stylelint	Valida CSS/PostCSS en archivos .vue
Volar	Vue.volar	IntelliSense, type-checking, y soporte completo para Vue 3 + TypeScript
Tailwind IntelliSense	bradlc.vscode-tailwindcss	Autocomplete de clases Tailwind con preview

Note

Volar reemplaza a Vetur (Vue 2). Si tienes Vetur instalado, desactívalo para este workspace — generan conflictos.

---

Mapa de la documentación

Usa estos enlaces para profundizar en cada área:

Arquitectura General Diagrama de capas, flujo de datos, y cómo todo encaja

Multi-Vertical Cómo una base de código sirve múltiples marcas

Servicios y APIs useServices, httpClient, fallback i18n, y capa de datos

Composables Lógica reutilizable: alertas, compras, formularios, modales

Estilos y Tailwind CSS variables, colores por vertical, tipografía, BEM

Routing y Middleware File-based routing, layouts, guards de autenticación

Tutoriales paso a paso Crear servicios, páginas, traducciones — con ejemplos reales

Lo que NUNCA hacer Anti-patrones, errores que rompen el proyecto, y cómo evitarlos