Tienda de velas personalizadas. Sitio público + panel de administrador.
Fase 1: HTML/CSS/JS sin servidor. Fase 2: API Java/Spring Boot + MySQL.
Este documento es el modelo de negocio: qué es Lumina, qué páginas tiene y qué hace cada una. También documenta las estrategias técnicas que usa el sitio (ver Estrategias técnicas del proyecto). Para el resto de la parte técnica —estructura de carpetas, CSS, Bootstrap y reglas del equipo con Git— ver docs/DESARROLLO.md.
El sitio es HTML/CSS/JS puro, pero el header y el footer se inyectan con
fetch(), por lo que no se puede abrir con doble clic en el .html: el
navegador bloquea ese fetch() bajo file://. Se sirve por HTTP con la
extensión Live Server de VS Code.
⚠️ Importante: en VS Code se debe abrir la carpeta raíz del repo (lumina, la que contieneREADME.mdysrc/), nunca una subcarpeta. De ahí dependen las rutas relativas de estilos y scripts; si se sirve desde otra carpeta, se obtienen errores404 Not Foundy la página sin estilos.
git clone git@github.com:argie-fullstack-java-generation-ch14/lumina.git
cd lumina- Abrir VS Code.
- File → Open Folder... (en algunas versiones el primer menú se llama
Code). Atajo:
Ctrl + K,Ctrl + O. - Seleccionar la carpeta
luminay hacer clic en Open / Abrir.
Verificación: en el explorador de VS Code, en el nivel superior, debe aparecer:
lumina/
├── README.md
├── docs/
└── src/
- View → Extensions (atajo:
Ctrl + Shift + X). - Buscar
Live Server. - Instalar.
- En el explorador, abrir
src/index.html. - Clic en "Go Live" (extremo inferior derecho de la barra de estado). Si el botón no aparece: clic derecho en el archivo → Open with Live Server.
- El navegador se abre solo.
URL esperada:
http://127.0.0.1:5500/src/index.html
Si la URL no contiene /src/ antes del archivo (p. ej.
/index.html o /tienda/...), se está sirviendo desde una carpeta
intermedia: repetir el Paso 2.
El puerto puede variar (5500 por defecto; si está ocupado, Live Server usa otro). Lo relevante es que la ruta contenga
/src/.
Desde la carpeta lumina (la raíz del repo):
npx serveLuego abrir http://localhost:3000/ y entrar a src/, o directamente
http://localhost:3000/src/.
El repo incluye un
serve.jsoncon"trailingSlash": truepara que las carpetas se sirvan siempre con/al final. Sin esa configuración,serveresponde200en/srcsin redirigir, el navegador toma/srccomo base y pide los estilos a/css/...y/js/...(404). Si se trabaja con una copia del repo anterior a este archivo, se debe escribir la URL con la barra final:http://localhost:3000/src/.
Sin framework ni backend, el proyecto tuvo que resolver a mano varios problemas que en otros proyectos resuelven las librerías. Estas son las estrategias adoptadas, qué problema resuelve cada una y dónde están en el código.
El proyecto no usa ningún framework de front-end (React, Vue, Astro...). Para no repetir código entre páginas, imita dos patrones de componentes reutilizables:
El header y el footer se escriben una sola vez, en src/componentes/header/header.html y src/componentes/footer/footer.html, y se inyectan en cada página con fetch() (ver src/js/ui.js):
await renderPartial("#header", "header/header.html");
await renderPartial("#footer", "footer/footer.html");La función renderPartial (definida en src/js/ui.js:109) imita el patrón de plantillas parciales (partials) que existe en casi todos los entornos web desde hace décadas. Un partial es un fragmento de HTML que se repite en varias páginas —típicamente el header y el footer— y que se mantiene en un solo archivo: se escribe una vez y se "incluye" donde hace falta. Si mañana cambia el menú, se edita un archivo y se actualiza todo el sitio; si el markup se copiara y pegara en cada página, habría que editarlo página por página y cada copia sería una oportunidad de que quede desactualizada (el principio DRY: Don't Repeat Yourself).
El patrón no es invención de ningún framework moderno: es tan viejo como el include de PHP, y casi todas las tecnologías lo traen con otro nombre o sintaxis:
| Entorno | Cómo incluye un partial |
|---|---|
| PHP puro | <?php include 'partials/header.php'; ?> |
| Laravel (PHP) | Blade: @include('partials.header') |
| WordPress (PHP) | get_header(), get_footer(), get_template_part('partials/card') |
| Symfony (PHP) | Twig: {{ include('partials/header.html.twig') }} |
| Ruby on Rails | render partial: "header" — de aquí viene el nombre "partial" |
| Handlebars | {{> header }} |
| EJS | <%- include('partials/header') %> |
Lo que cambia entre unos y otros es quién hace el include. En PHP, Rails, Blade o Twig lo hace el servidor, antes de enviar la página al navegador: el HTML llega ya armado. Lumina no tiene servidor, así que el include lo hace el navegador: renderPartial pide el fragmento con fetch(), lo inyecta en el contenedor indicado por el selector (#header, #footer), resuelve sus rutas relativas para que funcionen desde cualquier página y carga su CSS si aún no está en el <head>. Para quien visita el sitio el resultado es el mismo; la diferencia es que el armado ocurre en el navegador y, por eso, exige servir el sitio por HTTP (ver "Cómo verlo").
La misma estrategia se usa en la home (src/index.html) para inyectar el contenido de cada módulo dentro de su sección vacía (#inicio, #beneficios, #catalogo, etc.), mediante renderSection(selector, path) en src/js/ui.js. renderSection es la variante para la home: parsea el HTML completo del módulo con DOMParser, extrae solo el <main>, y además inyecta scripts y reinicializa los componentes de Bootstrap.
Lo que resuelve ui.js al inyectar:
- Resuelve rutas relativas de enlaces
<a>e imágenes respecto asrc/(resolveLinks/resolveModulePaths). - Carga el CSS del componente si aún no está en el
<head>(deduplicado por URL). - Carga y ejecuta los
<script>del componente, evitando cargarlos dos veces. - Reinicializa los componentes de Bootstrap (carruseles, etc.) después de inyectar.
fetch(), el sitio debe servirse por HTTP; abrir el HTML con file:// deja las páginas sin header ni footer.
Cuando un componente necesita mostrar datos que vienen de un JSON (y no solo markup estático), se usa un módulo ES que expone una función que devuelve HTML como template string, y la página lo pinta con innerHTML.
Ejemplos:
src/componentes/blog-card/blog-card.js→crearBlogCard(articulo)devuelve el HTML de una tarjeta de artículo.src/componentes/productos-recomendados/productos-recomendados.js→crearSeccionRecomendados(velas)devuelve el HTML completo (título + cards en scroll horizontal) usando.map().join("").src/componentes/carrusel/carrusel.js→ template strings para montar el carrusel.src/componentes/carrito/item-carrito/item-carrito.jsysrc/componentes/favoritos/item-favoritos/item-favoritos.js→ el HTML de una fila del carrito o de la lista de favoritos a partir del producto.
Ejemplo en src/tienda/blog/blog.js: primero trae articulos.json, luego llama a crearBlogCard(articulo) y asigna el resultado al innerHTML del contenedor.
| Estrategia | Cuándo usarla | Dónde vive |
|---|---|---|
fetch() + HTML externo |
Markup compartido entre páginas (header, footer, secciones de la home) | src/componentes/ con .html, inyectado desde src/js/ui.js |
| Template strings | Componentes que reciben datos dinámicos (JSON) | src/componentes/ con .js, importado por la página o auto-montado (ej. productos-recomendados.js) |
Estas dos técnicas resuelven el reuso de markup. Las estrategias siguientes cubren lo que el proyecto también resolvió a mano: la carga y sincronización del catálogo, las rutas entre páginas anidadas, el enrutado de vistas de detalle, el rendimiento de la home y la confiabilidad de los datos persistentes.
El catálogo (src/js/velas.js) es un módulo ES con top-level await: el navegador lo ejecuta de forma diferida, cuando termina de descargar velas.json. En cambio, sus consumidores (carrito.js, favoritos.js, productos-recomendados.js...) son scripts clásicos que corren de inmediato y no pueden saber si el catálogo ya está disponible cuando arrancan.
La solución: velas.js publica el catálogo en window.velas y anuncia que está listo con un CustomEvent:
// src/js/velas.js:19-23
window.velas = velas;
window.dispatchEvent(new CustomEvent("velas-listadas"));Cada consumidor se registra con el mismo patrón:
// ej. src/js/carrito.js:78-82
if (window.velas) {
initCarrito();
} else {
window.addEventListener("velas-listadas", initCarrito, { once: true });
}Es un mini event-bus hecho a mano: un emisor (velas.js) y suscriptores que se auto-registran con { once: true }. Consecuencia práctica: cada página puede incluir los <script> en el orden que sea sin romper nada, y ningún consumidor necesita saber dónde está el <script> de velas.js respecto al suyo.
- Emisor:
src/js/velas.js:19-23. - Suscriptores:
src/js/carrito.js:78-82,src/js/favoritos.js:61-64,src/componentes/productos-recomendados/productos-recomendados.js:111-116,src/tienda/catalogo/favoritos-de-temporada/favoritos-de-temporada.js:13-16.
El catálogo no se pide desde cada página ni desde cada componente: existe una única capa de datos, src/js/velas.js. Al ser un módulo ES puede usar await en el nivel superior: el navegador no ejecuta lo que depende de él hasta que el JSON llegó.
// src/js/velas.js:1-2
const response = await fetch(new URL("../data/velas.json", import.meta.url));
export const velas = await response.json();Ese mismo módulo hace las tres cosas: carga el JSON una sola vez por visita (un solo fetch a velas.json, sin importar cuántas páginas o componentes consuman el catálogo), lo exporta como única fuente de verdad (import { velas } from "../../js/velas.js", como hace catalogo.js:9) y lo publica en window.velas para los scripts clásicos que no pueden hacer import (que es lo que hace posible el event bus de la estrategia 2).
Consecuencia práctica: la ruta del JSON (data/velas.json) vive en un solo archivo. Ningún consumidor sabe dónde está el JSON ni cómo se carga; solo saben que pueden leer velas.
Los mismos scripts corren en páginas anidadas a distinta profundidad: src/index.html, src/tienda/carrito/index.html, src/tienda/catalogo/producto/index.html. Si un script resolviera sus rutas contra la página actual (location.href), cada página daría un resultado distinto.
La solución: cada script calcula su base a partir de su propia URL —document.currentScript.src en los scripts clásicos, import.meta.url en los módulos ES— y de ahí deriva URLs absolutas que son las mismas desde cualquier página:
// src/js/carrito.js:20-23 (script clásico)
const CARRITO_URL = new URL(
"../tienda/carrito/index.html",
new URL(".", document.currentScript.src).href
).href;
// src/tienda/blog/blog.js:3-5 (módulo ES)
const BLOG_DIR = new URL(".", import.meta.url).href;
export const ARTICULO_URL = new URL("articulo/", BLOG_DIR).href;Otros ejemplos: src/js/ui.js:6-12 (APP_BASE → COMPONENTS_BASE), src/tienda/catalogo/catalogo.js:6-7 (CATALOGO_DIR → PRODUCTO_URL).
El complemento está en la inyección: cuando ui.js inyecta HTML traído con fetch(), reescribe los enlaces e imágenes relativos del fragmento (resolveLinks / resolveModulePaths, ui.js:22-47) para que también apunten al lugar correcto. Resultado: los enlaces se escriben una vez, relativos a la carpeta del script, y funcionan desde cualquier página del sitio.
Para tener N artículos de blog no hace falta N archivos HTML ni un enrutador: una sola página plantilla (src/tienda/blog/articulo/index.html) sirve a todos. Su módulo (articulo.js) lee el identificador de la URL, resuelve el contenido contra el JSON y renderiza:
articulo.js:10-12— lee?slug=conURLSearchParams.articulo.js:14-17— traedata/articulos.json(ruta construida con la base del módulo, estrategia 4).init()enarticulo.js:70-93— tres estados: sin slug → "no encontrado"; slug inexistente → "no encontrado"; slug válido → renderiza el artículo y actualizadocument.title.
Los enlaces que apuntan al detalle se construyen con encodeURIComponent para que el slug viaje seguro en la URL: catalogo.js:36 (cards del catálogo → producto/?slug=...) y carrusel.js:152-155 (cards del carrusel).
Nota sobre el detalle de producto (
src/tienda/catalogo/producto/): la navegación ya funciona con el mismo patrón — los enlaces del catálogo y del carrusel ya apuntan aproducto/?slug=...— pero la página todavía no consume el slug:producto.jsestá vacío y el HTML tiene bloques wireframe con TODO. Pendiente: queproducto.jslea el?slug=, resuelva la vela contra el catálogo y renderice imagen, info y precio, igual que hacearticulo.jscon los artículos.
La home inyecta el contenido de 6 secciones con renderSection, y cada sección (y el header, el footer y el carrusel) trae su propio CSS. Si ese CSS solo se cargara al inyectar — cuando ui.js añade el <link> después del fetch() — la home mostraría un instante de contenido sin estilos (FOUC).
La solución está declarada en el <head> de src/index.html:19-27, con el truco clásico loadCSS:
<link rel="preload" href="tienda/inicio/inicio.css" as="style"
onload="this.rel='stylesheet'">Dos fases en una línea:
rel="preload" as="style": el navegador descarga el CSS con prioridad alta sin bloquear el render ni aplicarlo.onload="this.rel='stylesheet'": al terminar la descarga, el propio<link>cambia surely el CSS se aplica.
Es decir, el CSS de cada sección ya está (o casi) en el navegador cuando renderSection inyecta su HTML, que viaja por fetch() por separado. El resultado: la home con 6 secciones inyectadas no se queda en blanco ni parpadea. Por si el CSS llegara dos veces, ui.js deduplica por URL absoluta antes de añadir <link> (injectStyles, ui.js:49-66).
El carrito y los favoritos viven en localStorage, que es texto editable por cualquiera (el usuario, otra pestaña, una extensión). Tratarlo como fuente confiable rompería la página con un JSON corrupto o inyectaría productos fantasma que ya no existen en el catálogo.
Por eso, al cargar (src/js/carrito.js:32-61), el contenido nunca se usa tal cual: se valida y normaliza de arriba abajo.
// src/js/carrito.js:40-55 (resumen)
const datos = JSON.parse(carritoGuardado); // dentro de try/catch
if (!Array.isArray(datos)) return []; // debe ser un array
return datos
.filter(item =>
velas.some(vela => vela.id === Number(item.id)) && // el producto existe en el catálogo
Number.isInteger(Number(item.quantity)) &&
Number(item.quantity) > 0 // cantidad entera y positiva
)
.map(item => ({
id: Number(item.id),
quantity: Math.min(99, Number(item.quantity)) // tope de cantidad
}));Si algo falla —JSON roto, formato inesperado— se devuelve un carrito vacío y la página renderiza normal. favoritos.js aplica la misma normalización sobre su clave.
Claves del ecosistema: lumina-carrito, lumina-favoritos, usuarios, usuarioActivo. Todas temporales: en Fase 2 pasan a la API (ver "Dos fases de arquitectura").
src/componentes/carrusel/carrusel.js implementa a mano lo que un carrusel de librería da gratis:
- Loop infinito duplicando la pista (
base + base,:223-229), midiendo el ciclo conoffsetLefty repitiendo hasta llenar el ancho visible (tope 8 repeticiones,:231-235). - Wrap del scroll: al pasar el ciclo,
scrollLeftretrocede un ciclo completo (:106-110) — visualmente infinito, con scroll nativo. - Drag vs click: las cards navegan al detalle, pero solo con un toque real. Con un
WeakMapse guarda dónde empezó elpointerdowny en elclickse compara: si el dedo se movió más de 6px o cambió elscrollLeft, fue un arrastre y no navega (:112-156). - Autoplay respetuoso:
setIntervalque se pausa al hacer hover y que no corre si el usuario tieneprefers-reduced-motionactivado (:164+). - Idempotente: un flag (
pista.dataset.carruselListo,:100-104) evita duplicar listeners si el carrusel se re-monta.
Menú en la columna "Desde" no es una página: es el Header / Navbar, el
componente que se repite en todas las páginas. Da acceso directo a Inicio
(el logo), Catálogo, Nosotros, Blog, Contáctanos, Carrito, Favoritos y Usuario.
La entrada de Usuario es condicional: sin sesión muestra Login, con sesión
muestra el área de cuenta (Mi cuenta).
| Sección | Archivo | Desde |
|---|---|---|
| Inicio | src/tienda/inicio/index.html |
Menú |
| Catálogo | src/tienda/catalogo/index.html |
Menú |
| Detalle de producto | src/tienda/catalogo/producto/index.html?slug=<slug-de-la-vela> |
Inicio, Catálogo |
| Crea tu vela | src/tienda/crear/index.html |
Aún sin enlace: se abre por URL (el creador paso a paso está en construcción) |
| Carrito | src/tienda/carrito/index.html |
Menú |
| Nosotros | src/tienda/nosotros/index.html |
Menú |
| Blog | src/tienda/blog/index.html |
Menú |
| Artículo del blog | src/tienda/blog/articulo/index.html?slug=<slug-del-articulo> |
Blog |
| Contáctanos | src/tienda/contacto/index.html |
Menú |
| Login | src/tienda/login/index.html |
Menú (sin sesión) |
| Registro | src/tienda/registro/index.html |
Login |
| Favoritos | src/tienda/favoritos/index.html |
Menú |
| Recuperar contraseña | (sin implementar aún) | Login |
| Mi cuenta | src/tienda/mi-cuenta/index.html |
Menú (con sesión) — área con pestañas: Información, Favoritos, Pedidos |
| Información (pestaña) | src/tienda/mi-cuenta/info/index.html |
Mi cuenta |
| Favoritos (pestaña) | src/tienda/mi-cuenta/favoritos/index.html |
Mi cuenta |
| Pedidos (pestaña) | src/tienda/mi-cuenta/pedidos/index.html |
Mi cuenta |
Las tres pestañas de Mi cuenta no se navegan como páginas: mi-cuenta/index.html
las trae con fetch() y las inyecta dentro del área de pestañas.
| Acción | Ocurre en |
|---|---|
| Agregar al carrito | Cards del catálogo, cards del carrusel, productos recomendados y lista de favoritos (src/js/carrito.js y sus componentes) |
| Editar cantidad / eliminar | src/tienda/carrito/index.html |
| Confirmar pedido (modal) | src/tienda/carrito/index.html |
| Sección | Archivo |
|---|---|
| Gestión de productos | src/admin/productos/index.html |
| Crear / actualizar producto (modal) | src/admin/producto-formulario/modal.html |
El panel de administración y los pedidos del admin son secciones pendientes de construir: hoy la administración es solo la gestión de productos.
HTML/CSS/JS sin build. El carrito y los pedidos viven en localStorage.
Funciona al abrir el archivo, pero no hay backend: los datos no sobreviven a
otro navegador ni a otra máquina.
- Base de datos MySQL con entidades y relaciones.
- API RESTful en Java / Spring Boot.
- Autenticación real para restringir el panel de admin.
- El catálogo consume la API con
GETyPOSTen lugar de un array local.
Qué cambia al pasar a fase 2: el carrito deja de leer localStorage y pasa a
llamar endpoints. El resto del frontend no se toca.
- Pasarela de pagos con tarjetas en tiempo real. El checkout solo genera una solicitud de confirmación, no cobra.
- Envíos con geolocalización o rastreo de guía.
- App móvil nativa (iOS/Android).
Los 5 pasos son un flujo dentro de src/tienda/crea-tu-vela/index.html, no 5 archivos HTML:
intención → aroma → color/diseño → mensaje → vista previa → agregar al carrito
Las intenciones disponibles: amor, calma, abundancia, bienestar y nuevos comienzos.
| Página | Contenido mínimo |
|---|---|
| Inicio | Presentación, banner con propuesta de valor, productos destacados, sección "Crea tu vela", intenciones, beneficios, acceso a catálogo y a login |
| Carrito | Productos con cantidad, subtotal y total; modificar cantidad y eliminar; estado vacío ("carrito vacío"); modal de confirmación de pedido |
| Nosotros | Historia, misión, visión, valores, compromiso con el bienestar, materiales biodegradables, filosofía |
| Contacto | Formulario: nombre, correo, asunto, mensaje + datos de contacto + redes |
| Login | Formulario de autenticación + enlace al registro |
| Registro | Formulario de creación de cuenta con animación de bienvenida al completar |
| Favoritos | Lista de productos favoritos y botón para vaciar favoritos |
| Mi cuenta | Área de cuenta con pestañas: Información de la cuenta, Favoritos y Pedidos |
Cada tarjeta de producto lleva: imagen, nombre, aroma, precio, disponibilidad, botón de ver detalle y opción de agregar al carrito.
Los filtros (categoría, aroma, precio, color), el orden por precio o novedad y la paginación funcionan con JavaScript, porque no hay servidor que consulten.