# Explicación del código

## Archivos y responsabilidades

| Archivo | Responsabilidad |
| --- | --- |
| `index.html` | Estructura semántica, secciones, formularios y controles. |
| `styles.css` | Diseño, distribución adaptable y temas de color. |
| `core.js` | Funciones de validación, fechas, métricas y tratamiento de registros; independientes de la pantalla. |
| `charts.js` | Gráficos SVG locales de progreso, sin librerías ni servicios externos. |
| `app.js` | Eventos de los controles, persistencia en el navegador y actualización de la interfaz. |
| `server.cjs` | Servidor HTTP local opcional con módulos nativos de Node.js. |
| `INICIAR.cmd` | Iniciador de Windows, abre el servidor o el archivo HTML. |
| `tests/*.test.cjs` | Pruebas automáticas mediante `node:test`. |
| `docs/` | Guías de uso, código y control de versiones. |

No se necesita un proceso de compilación. El navegador carga los archivos locales de la aplicación directamente. No hay dependencias de ejecución descargadas de un CDN.

## Recorrido de un dato

1. El usuario introduce una salida o carga el borrador del reloj.
2. La lógica comprueba campos obligatorios, formatos y rangos permitidos.
3. El controlador guarda el estado serializado como JSON en `localStorage`.
4. La interfaz calcula las métricas y reconstruye el historial y los gráficos.
5. La exportación genera un archivo JSON descargable; la importación valida antes de combinar registros.

La separación entre lógica y presentación permite probar fechas, ritmos y estadísticas sin abrir un navegador. Las fechas de los entrenamientos se tratan como días locales, evitando que una conversión a UTC cambie el día seleccionado.

## Modelo y persistencia

La clave de almacenamiento es `bitacora-trote:v1`. El objeto raíz tiene `version: 1`, una lista `runs` y `settings`. Cada salida tiene un `id`, `fecha` (`AAAA-MM-DD`), `tipo`, `km` y `seg`; los datos opcionales ausentes se normalizan a `null`, y las notas se guardan como texto. Los ajustes incluyen `startDate`, `weeklyGoal` (20 km inicialmente), `theme` (`dark`, `light` o `system`) y siete notas en `planNotes`.

Los respaldos se validan integralmente: hasta 5 MB y 5000 sesiones, identificadores no duplicados, fechas válidas y valores dentro de rangos. La combinación añade identificadores nuevos y conserva las sesiones y ajustes actuales en caso de coincidencia. El almacenamiento se escribe después de validar el estado completo. Si la lectura falla, los datos existentes no se eliminan automáticamente.

## Gráficos de progreso

Los gráficos se dibujan con SVG generado localmente, sin Chart.js. La distancia semanal cubre ocho semanas. Las otras series muestran hasta las últimas 100 sesiones que tengan los datos necesarios. El gráfico de ritmo diferencia los tipos por color: suave/largo azul, tempo/intervalos naranja, test/carrera verde y caminata lila.

La cadencia muestra valores registrados, sin asignar una zona ideal universal. La referencia de eficiencia utiliza `km * 60000 / (seg * fc)` (velocidad en metros/minuto dividida entre pulso medio) y toma solo salidas suaves o largas. Es una comparación orientativa: terreno, pausas, clima y otros factores pueden cambiar el valor; no mide salud ni sustituye una evaluación de rendimiento.

Las referencias de tiempos se generan en `app.js` desde el último test o carrera entre 3 y 42,3 km, con la fórmula `seg * (distanciaObjetivo / km)^1.06` para 5, 10 y 21,0975 km. La interfaz muestra la salida de origen y el exponente. Esta proyección se presenta separada del mejor 5 km observado que calcula `core.js`.

## Servidor opcional

`server.cjs` usa `node:http` y `node:fs/promises`. Expone solamente los nombres permitidos de la interfaz y las guías enlazadas, estas últimas como texto legible. No ofrece un explorador de carpetas ni endpoints para guardar datos. Rechaza métodos distintos de GET y HEAD, rutas no permitidas y escapes de ruta; no sirve `.git`, archivos privados ni respaldos. Entrega HTML, JavaScript y CSS con sus tipos MIME y `Cache-Control: no-store` para que una edición aparezca al recargar.

Escucha en `127.0.0.1:4173` de forma predeterminada, sin exponer el servicio a otros equipos. `PORT` permite elegir otro puerto. El cambio de puerto también cambia el origen del navegador y, por tanto, el almacenamiento que ve la app. Ctrl+C detiene el servidor.

## Modificar el proyecto

Edita los archivos con cualquier editor y recarga la página. Para cambios en cálculos, revisa primero `core.js` y añade pruebas que cubran el comportamiento esperado. Para cambios de interfaz, revisa `index.html`, `styles.css` y `app.js`, y prueba en ventana ancha y estrecha.

Ejecuta `npm test` después de cambiar lógica o servidor. Comprueba manualmente guardar, recargar, editar, exportar e importar. Evita usar datos personales reales en las pruebas o en commits.

## Alcance de la IA

Los agentes colaboraron durante el desarrollo y la revisión. La aplicación funciona con JavaScript local y cálculos explícitos; no incorpora una API de IA, reconocimiento automático de fotografías ni credenciales. Para añadir una integración futura habría que diseñar su autorización, privacidad y almacenamiento por separado.