Primeros Pasos - FactoriaF5-Asturias/project-p5-digital-academy-team3-restaurant-frontend GitHub Wiki

Guía para instalar, arrancar y empezar a trabajar en el frontend.

Requisitos

  • Node.js ^20.19.0 o >=22.12.0.
  • npm, incluido con Node.js.
  • Backend corriendo en http://localhost:8080 (ver repositorio backend).
  • Docker Desktop en marcha si vas a levantar el backend con su base de datos.

Instalación y arranque

Instala exactamente las versiones registradas en package-lock.json:

npm ci

Crea un archivo .env en la raíz del proyecto con la URL del backend:

VITE_API_URL=http://localhost:8080

Arranca el servidor de desarrollo:

npm run dev

Vite mostrará en la terminal la URL local (por defecto http://localhost:5173).

Para más detalle sobre comandos, estructura y dependencias, consulta el README del proyecto.

Tests

Tests unitarios

npm run test:unit

Ejecuta Vitest en modo interactivo. Los tests viven en tests/ y prueban componentes, vistas, servicios y composables de forma aislada.

Cobertura

npm run test:coverage

Ejecuta los tests una vez y genera un informe de cobertura. La asignatura exige una cobertura mínima del 70%.

Tests end-to-end

Requieren instalar los navegadores la primera vez:

npx playwright install chromium

Ejecutar:

npm run test:e2e

Playwright arranca automáticamente el servidor de Vite. Los tests mockean el backend, así que no es necesario arrancarlo. Los tests viven en e2e/.

Para depurar con interfaz gráfica:

npx playwright test --ui

Convenciones de código

Estructura de carpetas

El código fuente vive en src/. Cada carpeta tiene una responsabilidad concreta:

  • assets/: recursos importados desde los componentes, como imágenes, iconos y fuentes. Vite los procesa, optimiza y añade a la compilación.
  • components/: piezas de interfaz reutilizables. Se organizan por área funcional (common/, home/, admin/, kitchen/).
  • composables/: lógica reutilizable con estado compartido entre componentes. Actualmente contiene useAuth.js (sesión y autenticación) y useCart.js (carrito).
  • core/: reservada para infraestructura y configuración global de la aplicación. Pendiente de contenido.
  • router/: instancia de Vue Router, definición de rutas y guardas de navegación.
  • services/: funciones que se comunican con la API del backend. Cada servicio agrupa las peticiones de un dominio (AuthService, ProductService, CartService, OrderService, ReportService).
  • shared/: reservada para utilidades, constantes y recursos compartidos. Pendiente de contenido.
  • stores/: reservada para stores globales de Pinia. Pendiente de contenido.
  • styles/: hojas de estilo globales. theme.css define los tokens de Tailwind (colores, fuentes) y fonts.css registra las tipografías de marca.
  • views/: componentes que representan páginas completas, asociadas a rutas. Terminan en View (HomeView, LoginView).

Los tests unitarios viven en tests/ y los end-to-end en e2e/.

Naming

  • Componentes: PascalCase y extensión .vue. Ej: MainHeader.vue, ProductCard.vue.
  • Vistas: PascalCase terminadas en View. Ej: HomeView.vue, LoginView.vue, OrderSuccessView.vue.
  • Composables: camelCase empezando por use. Ej: useAuth.js, useCart.js.
  • Servicios: PascalCase terminados en Service. Ej: AuthService.js, ProductService.js.
  • Archivos JavaScript sueltos: camelCase. Ej: productMapper.js.
  • Rutas de la aplicación: kebab-case. Ej: /change-password, /order-success/:id.
  • Nombres de ruta (name): kebab-case. Ej: name: 'change-password'.
  • Atributos data-testid: kebab-case. Ej: cart-counter, add-to-cart.
  • Clases CSS personalizadas (para componentes con estilos propios): BEM con doble guion bajo. Ej: menu-category-filter__button--active.

Estilo de componentes

Todos los componentes usan la Composition API con <script setup>. La estructura del archivo sigue siempre el mismo orden:

<script setup>
    // Imports
    // Props y emits
    // Refs y computed
    // Funciones
    // Hooks de ciclo de vida
</script>

<template>
    <!-- HTML con clases de Tailwind -->
</template>

<style scoped>
    /* Solo si hace falta. Con Tailwind puro, se omite. */
</style>

Reglas:

  • <script setup> siempre. Nunca Options API.
  • <style scoped> cuando se necesiten estilos específicos del componente. En Tailwind v4, requiere @reference "../../main.css"; para acceder a los tokens del tema.
  • Se prefieren utilidades de Tailwind en el <template> antes que escribir CSS propio.
  • Los tokens de marca (bg-bg-brand, text-text-muted, etc.) se definen en styles/theme.css y se usan en lugar de colores hardcodeados.

Atomic design

El proyecto aplica una separación por nivel de reutilización en lugar de una jerarquía estricta de atomic design:

  • components/common/: componentes compartidos entre todas las vistas. Por ejemplo, MainHeader.vue y MainFooter.vue.
  • components/home/: componentes específicos de la home. Por ejemplo, HeroSection.vue, ProductCard.vue, MenuSection.vue.
  • components/admin/: componentes específicos del panel de administración.
  • components/kitchen/: componentes específicos del dashboard de cocina.

Regla práctica:

  • Si un componente se reutiliza en dos o más áreas → common/.
  • Si es específico de una vista o un área funcional → carpeta de esa área.
  • Los componentes pequeños y genéricos (botones, inputs) van en common/ cuando existan. Ahora mismo no hay una librería de componentes base.
⚠️ **GitHub.com Fallback** ⚠️