From a2bdd0e0754871de796891a1584a5a3675122db0 Mon Sep 17 00:00:00 2001 From: Miguel Barra Date: Mon, 27 Jul 2026 17:47:00 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20actualizar=20documentaci=C3=B3n=20t?= =?UTF-8?q?=C3=A9cnica=20y=20agregar=20CONTRIBUTING.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 72 ++++++++++++++- CONTRIBUTING.md | 99 +++++++++++++++++++++ app/opengraph-image.tsx | 146 +++++++++++++++--------------- components/DashboardHome.tsx | 4 +- components/HistoryChart.tsx | 4 +- docs/INDEX.md | 88 ++++++++++++++++++ docs/api.md | 152 ++++++++++++++++++++++++++++++++ docs/architecture.md | 117 ++++++++++++++++++++++++ docs/authentication.md | 59 +++++++++++++ docs/code/app.md | 117 ++++++++++++++++++++++++ docs/code/components.md | 88 ++++++++++++++++++ docs/code/hooks.md | 31 +++++++ docs/code/lib.md | 40 +++++++++ docs/code/root.md | 54 ++++++++++++ docs/code/types.md | 18 ++++ docs/components.md | 149 +++++++++++++++++++++++++++++++ docs/database.md | 57 ++++++++++++ docs/dependencies.md | 40 +++++++++ docs/environment.md | 63 +++++++++++++ docs/folder-structure.md | 106 ++++++++++++++++++++++ docs/glossary.md | 34 +++++++ docs/hooks.md | 108 +++++++++++++++++++++++ docs/migracion-banco-central.md | 62 ++++++------- docs/patterns.md | 43 +++++++++ docs/project-overview.md | 54 ++++++++++++ docs/roadmap.md | 42 +++++++++ docs/routes.md | 144 ++++++++++++++++++++++++++++++ docs/services.md | 105 ++++++++++++++++++++++ docs/state-management.md | 61 +++++++++++++ docs/technical-debt.md | 47 ++++++++++ hooks/useIndicadorHistory.ts | 43 +++++---- hooks/useIndicadores.ts | 17 ++-- lib/bcentral-client.ts | 13 ++- 33 files changed, 2137 insertions(+), 140 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/INDEX.md create mode 100644 docs/api.md create mode 100644 docs/architecture.md create mode 100644 docs/authentication.md create mode 100644 docs/code/app.md create mode 100644 docs/code/components.md create mode 100644 docs/code/hooks.md create mode 100644 docs/code/lib.md create mode 100644 docs/code/root.md create mode 100644 docs/code/types.md create mode 100644 docs/components.md create mode 100644 docs/database.md create mode 100644 docs/dependencies.md create mode 100644 docs/environment.md create mode 100644 docs/folder-structure.md create mode 100644 docs/glossary.md create mode 100644 docs/hooks.md create mode 100644 docs/patterns.md create mode 100644 docs/project-overview.md create mode 100644 docs/roadmap.md create mode 100644 docs/routes.md create mode 100644 docs/services.md create mode 100644 docs/state-management.md create mode 100644 docs/technical-debt.md diff --git a/AGENTS.md b/AGENTS.md index caeace2..cf0837f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,74 @@ +# Agent Guidelines — Pulso (Dashboard Indicadores Económicos de Chile) + -# This is NOT the Next.js you know +## ⚠️ Next.js Version Constraint -This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. +This version of Next.js has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. + +--- + +## 🎯 System Context & Stack + +- **Framework**: Next.js 16 (App Router, Turbopack) + React 19 + TypeScript. +- **Styling**: Tailwind CSS v4 (`@import "tailwindcss";` in `app/globals.css`). +- **Data Fetching**: SWR for client-side hydration, server-side caching & snapshot engine in `lib/bcentral-client.ts` and `lib/indicadores-snapshot.ts`. +- **External API**: Banco Central de Chile SI3 (`SieteRestWS`). Latin-1 encoding handled server-side. +- **Testing**: Vitest + Testing Library (unit/component), Playwright (E2E). + +--- + +## 🚦 Execution Boundaries + +### Always + +- Keep environment secrets (`BCENTRAL_USER`, `BCENTRAL_PASS`) restricted to server-side executions (`lib/`, Route Handlers). NEVER add the `NEXT_PUBLIC_` prefix to secret variables. +- Run tests (`npm run test`) and linter (`npm run lint`) after making code modifications. +- Preserve existing API fallback mechanisms: when the external Banco Central API fails, return last-known-good cached data or handle gracefully. +- Follow TypeScript strict mode without using `any` or disabling type checks. + +### Ask First + +- Adding or upgrading npm dependencies in `package.json`. +- Modifying environment variable schemas or altering `.env.example`. +- Changing API route contracts under `/api/indicadores/`. + +### Never + +- Expose raw Banco Central credentials to the client browser. +- Perform direct external HTTP calls to `si3.bcentral.cl` from Client Components (all external requests MUST route through server-side handlers). +- Commit code that breaks existing Vitest unit tests or Playwright E2E suites. + +--- + +## 🛠️ Verification & Development Commands + +| Command | Purpose | +| ---------------------- | --------------------------------------------------------------- | +| `npm run dev` | Start development server with Turbopack (http://localhost:3000) | +| `npm run build` | Validate production build | +| `npm run start` | Serve production build locally | +| `npm run lint` | Execute ESLint checks | +| `npm run format` | Format codebase using Prettier | +| `npm run format:check` | Check code formatting without modifying files | +| `npm run test` | Run unit and component test suite (Vitest) | +| `npm run test:watch` | Run Vitest in interactive watch mode | +| `npm run test:e2e` | Run End-to-End tests (Playwright) | + +--- + +## 📂 Key Architecture & Map + +``` +app/ + page.tsx → Home page (SSR + SWRConfig fallback) + api/indicadores/route.ts → GET snapshot of 10 economic indicators + api/indicadores/[codigo]/[anio]/ → GET historical annual series for an indicator + dev/ui/ → Component showcase (blocked in prod via proxy.ts) +components/ → UI Components (DashboardHome, IndicatorCard, HistoryChart, Converter) +hooks/ → Custom hooks (useIndicadores, useIndicadorHistory, useFavoritos) +lib/ → Services (bcentral-client.ts, indicadores-snapshot.ts) +types/ → Domain TypeScript definitions (indicador.ts) +docs/ → Complete internal technical documentation +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7805928 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Guía de Contribución — Pulso + +¡Gracias por tu interés en contribuir a **Pulso**! Este documento proporciona las directrices e instrucciones necesarias para configurar tu entorno de desarrollo, ejecutar pruebas, seguir el estilo de código del proyecto y enviar tus cambios mediante Pull Requests. + +--- + +## 🚀 Requisitos Previos + +- **Node.js**: `v26.0.0` o superior. +- **npm**: Administrador de paquetes por defecto. +- **Git**: Sistema de control de versiones. + +--- + +## 🛠️ Configuración del Entorno Local + +1. **Clonar el repositorio**: + + ```bash + git clone https://github.com/mbarradev-debug/pulso.git + cd pulso + ``` + +2. **Instalar dependencias**: + + ```bash + npm install + ``` + +3. **Configurar variables de entorno**: + Copia el archivo de plantilla `.env.example` a `.env.local`: + + ```bash + cp .env.example .env.local + ``` + + Abre `.env.local` y completa las credenciales de la API SI3 del Banco Central de Chile (`BCENTRAL_USER` y `BCENTRAL_PASS`). Si no posees una cuenta, puedes registrarte gratuitamente en [si3.bcentral.cl](https://si3.bcentral.cl). + +4. **Iniciar el servidor de desarrollo**: + ```bash + npm run dev + ``` + Abre [http://localhost:3000](http://localhost:3000) en tu navegador. + +--- + +## 🧪 Verificación y Pruebas + +Antes de subir tus cambios, asegúrate de que todos los linters, formateadores y suites de pruebas pasen exitosamente: + +| Comando | Descripción | +| ---------------------- | ----------------------------------------------------------- | +| `npm run lint` | Ejecuta ESLint para validar reglas de código | +| `npm run format` | Aplica Prettier en todo el proyecto | +| `npm run format:check` | Verifica que los archivos sigan el formato esperado | +| `npm run test` | Corre los tests unitarios y de componentes con Vitest | +| `npm run test:e2e` | Corre los tests End-to-End con Playwright | +| `npm run build` | Valida que la compilación de producción compile sin errores | + +--- + +## ⚓ Git Hooks y Commits + +Este proyecto utiliza **Husky** y **lint-staged** para verificar automáticamente los archivos en staging antes de crear un commit. + +- Al ejecutar `git commit`, Husky correrá automáticamente ESLint y Prettier sobre los archivos modificados. +- Si se detectan errores, corrige los fallos antes de reintentar el commit. + +--- + +## 🔄 Flujo de Trabajo para Pull Requests (PRs) + +1. **Crear una rama funcional**: + + ```bash + git checkout -b feature/nombre-de-tu-mejora + ``` + +2. **Realizar commits claros e informativos**: + - Agrupa cambios lógicos en commits independientes. + - Escribe mensajes de commit descriptivos en presente indicativo. + +3. **Integración Continua (CI)**: + Cada PR hacia `main` activará automáticamente los workflows de GitHub Actions (`.github/workflows/ci.yml`), verificando: + - Linting y verificación de formato. + - Comprobación de tipos de TypeScript. + - Pruebas unitarias en Vitest. + - Pruebas E2E en Playwright. + - Build de producción Next.js. + +--- + +## 📚 Documentación Interna + +Para comprender a fondo la arquitectura, el modelo de datos, la resiliencia ante fallos del Banco Central y los patrones utilizados, consulta el índice de documentación en: + +- [`docs/INDEX.md`](docs/INDEX.md) +- [`docs/architecture.md`](docs/architecture.md) +- [`AGENTS.md`](AGENTS.md) diff --git a/app/opengraph-image.tsx b/app/opengraph-image.tsx index 7b0fee3..4d6b656 100644 --- a/app/opengraph-image.tsx +++ b/app/opengraph-image.tsx @@ -16,94 +16,90 @@ const trendBg = { up: 'rgba(52, 211, 153, 0.12)', down: 'rgba(248, 113, 113, 0.1 export default function Image() { return new ImageResponse( - ( -
-
-
+
+
+
+
+ P +
+
+ Pulso +
+
+
+ Indicadores económicos de Chile en tiempo real +
+
+ +
+ {indicators.map((indicator) => ( +
+
{indicator.code}
- P -
-
- Pulso + {indicator.value}
-
-
- Indicadores económicos de Chile en tiempo real -
-
- -
- {indicators.map((indicator) => (
-
- {indicator.code} -
-
- {indicator.value} -
-
- {indicator.delta} -
+ {indicator.delta}
- ))} -
+
+ ))}
- ), - { ...size } +
, + { ...size }, ); } diff --git a/components/DashboardHome.tsx b/components/DashboardHome.tsx index af75d37..959949e 100644 --- a/components/DashboardHome.tsx +++ b/components/DashboardHome.tsx @@ -28,7 +28,9 @@ export function DashboardHome() { const codigosVisibles = useMemo( () => - soloFavoritos ? codigosOrdenados.filter((codigo) => favoritos.includes(codigo)) : codigosOrdenados, + soloFavoritos + ? codigosOrdenados.filter((codigo) => favoritos.includes(codigo)) + : codigosOrdenados, [soloFavoritos, codigosOrdenados, favoritos], ); diff --git a/components/HistoryChart.tsx b/components/HistoryChart.tsx index 652768d..25ad6f4 100644 --- a/components/HistoryChart.tsx +++ b/components/HistoryChart.tsx @@ -72,7 +72,9 @@ export function HistoryChart({ codigo, fechaReferencia, unidadMedida }: HistoryC return data.filter((punto) => new Date(punto.fecha) >= corte).length; }; // "1A" siempre queda visible como respaldo, aunque no alcance el minimo. - return RANGOS.filter((r) => r === '1A' || contarEnRango(MESES_POR_RANGO[r]) >= MIN_PUNTOS_RANGO); + return RANGOS.filter( + (r) => r === '1A' || contarEnRango(MESES_POR_RANGO[r]) >= MIN_PUNTOS_RANGO, + ); }, [data, fechaAncla]); const rangosVisiblesKey = rangosVisibles.join(','); diff --git a/docs/INDEX.md b/docs/INDEX.md new file mode 100644 index 0000000..77efe6f --- /dev/null +++ b/docs/INDEX.md @@ -0,0 +1,88 @@ +# Documentación Técnica Interna — Proyecto Pulso + +Bienvenido a la documentación oficial del sistema **Pulso**, el panel de control de indicadores económicos de Chile en tiempo real desarrollado sobre **Next.js 16 (App Router)**, **React 19**, **TypeScript** y **TailwindCSS v4**. + +Este conjunto de documentos constituye la especificación de arquitectura, diseño técnico y funcionamiento interno orientada a ingenieros de software, arquitectos y mantenedores del sistema. + +--- + +## 🏛️ Por qué elegimos esta estructura de documentación + +La documentación ha sido estructurada en archivos Markdown independientes dentro del directorio `docs/`, complementada con documentación granular por carpeta en `docs/code/` y comentarios JSDoc directamente en el código fuente. + +### Justificación de Diseño: + +1. **Navegabilidad y Mantenibilidad**: Evitamos un único archivo monolítico inviable de mantener. Cada dominio de arquitectura (Rutas, Estado, Servicios, API, Deuda Técnica, etc.) posee su propio documento enfocado. +2. **Convención Estándar del Ecosistema TypeScript / Next.js**: Organizada respetando la estructura física del proyecto `app/`, `components/`, `hooks/`, `lib/`, `types/`, facilitando el mapeo mental entre la lectura teórica y la inspección del código. +3. **Documentación a Dos Niveles**: + - **Nivel Sistema / Arquitectura (`docs/*.md`)**: Explica las decisiones de alto nivel, patrones de diseño, flujos de datos integrales y modelos conceptuales. + - **Nivel Código Fuente (`docs/code/*.md` y JSDoc en `.ts/.tsx`)**: Documenta exhaustivamente cada archivo, componente, interfaz y función con firmas, algoritmos, casos borde y diagramas de flujo. + +--- + +## 📚 Índice General de Navegación + +### 1. Documentación de Arquitectura y Sistema + +- 🏗️ [Arquitectura y Decisiones de Diseño](architecture.md) — Visión general, migración a Banco Central SI3, resiliencia y patrón Adapter. +- 📋 [Resumen del Proyecto y Objetivos](project-overview.md) — Propósito del producto, requerimientos no funcionales y alcance. +- 📂 [Estructura de Carpetas](folder-structure.md) — Árbol del proyecto, responsabilidades y mapa de dependencias. +- 🛣️ [Rutas de la Aplicación (App Router)](routes.md) — Mapeo de rutas públicas, endpoints internos y middlewares. +- 🧩 [Componentes React](components.md) — Sistema de diseño y especificación técnica de la UI. +- ⚓ [Custom Hooks](hooks.md) — hooks de datos (`useIndicadores`, `useIndicadorHistory`) y estado (`useFavoritos`). +- 🛠️ [Servicios y Clientes Backend](services.md) — Cliente HTTP del Banco Central de Chile y motor de snapshot. +- 🔌 [Endpoints de API Interna](api.md) — Documentación de Route Handlers `/api/indicadores`. +- 💾 [Estrategia de Datos y Caché](database.md) — In-memory caching, ISR, Data Cache y localStorage. +- 🔐 [Autenticación y Seguridad](authentication.md) — Modelo de acceso público, secretos de API y Dev Proxy guard. +- 🔄 [Gestión del Estado](state-management.md) — Hydration con SWR, External Store Observer y estado local. +- 🌐 [Variables de Entorno y Configuración](environment.md) — Variables requeridas, tsconfig, Tailwind v4 y herramientas. +- 📦 [Análisis de Dependencias](dependencies.md) — Desglose de librerías del runtime y desarrollo en `package.json`. +- 📐 [Patrones de Diseño Identificados](patterns.md) — Adapter, Resilient Cache with Fallback, Observer, SSR Hydration. +- ⚠️ [Deuda Técnica y Diagnóstico](technical-debt.md) — Puntos de riesgo, acoplamientos y optimizaciones recomendadas. +- 🗺️ [Roadmap Técnico](roadmap.md) — Propuestas futuras de escalabilidad y mejoras UI. +- 📖 [Glosario](glossary.md) — Términos del dominio económico chileno y jerga técnica. + +--- + +### 2. Documentación Granular de Código Fuente (`docs/code/`) + +- 📄 [Carpeta App (`docs/code/app.md`)](code/app.md) — Páginas, layouts, metadata y route handlers. +- 📄 [Carpeta Components (`docs/code/components.md`)](code/components.md) — Todos los componentes UI. +- 📄 [Carpeta Hooks (`docs/code/hooks.md`)](code/hooks.md) — Todos los custom hooks. +- 📄 [Carpeta Lib (`docs/code/lib.md`)](code/lib.md) — Cliente de API, snapshot engine y formateadores. +- 📄 [Carpeta Types (`docs/code/types.md`)](code/types.md) — Definiciones TypeScript del dominio. +- 📄 [Archivos Raíz y Configuración (`docs/code/root.md`)](code/root.md) — `proxy.ts`, configs de build, linting y testing. + +--- + +## ⚡ Diagrama de Flujo General del Sistema + +El siguiente diagrama resume cómo fluye la información desde la petición del usuario hasta la consulta externa al Banco Central de Chile: + +```mermaid +sequenceDiagram + autonumber + actor Usuario + participant Browser as Navegador / Client Component + participant NextServer as Next.js Server (App Router) + participant SnapshotEngine as indicadores-snapshot (Lib) + participant BCentralClient as bcentral-client (Lib) + participant BCAPI as API Banco Central (SI3 SieteRestWS) + + Usuario->>NextServer: GET / (Navegación inicial) + Note over NextServer: Server Component (app/page.tsx) + NextServer->>SnapshotEngine: obtenerSnapshot() + par 10 Peticiones Concurrentes + SnapshotEngine->>BCentralClient: getUltimoValor('uf') + SnapshotEngine->>BCentralClient: getUltimoValor('dolar') + SnapshotEngine->>BCentralClient: getUltimoValor('euro') + SnapshotEngine->>BCentralClient: getUltimoValor(...) + end + BCentralClient->>BCAPI: GET /SieteRestWS.ashx?function=GetSeries×eries=... + BCAPI-->>BCentralClient: HTTP 200 (JSON ISO-8859-1) + BCentralClient-->>SnapshotEngine: Objeto Indicador (adaptado) + SnapshotEngine-->>NextServer: IndicadoresSnapshot (o fallback desde cache) + NextServer-->>Browser: HTML Renderizado + SWRConfig fallback data + Note over Browser: Client Components (DashboardHome) + Browser->>Browser: Hidratación SWR (sin flash de datos) +``` diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..8337998 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,152 @@ +# Especificación de la API Interna (Route Handlers) + +Este documento contiene la especificación de API para los endpoints expuestos por los Route Handlers de **Pulso** bajo la ruta `/api/`. + +--- + +## 📡 Endpoint 1: Obtenedor de Snapshot Global + +### `GET /api/indicadores` + +#### Propósito: + +Devuelve una fotografía (snapshot) con los valores más recientes de los 10 indicadores económicos soportados. + +#### Firma del Handler: + +```typescript +export async function GET(): Promise; +``` + +#### Modificadores de Caché Next.js: + +- `export const dynamic = 'force-static'`: Fuerza al compilador de Next.js a tratar la respuesta de este handler como estática dentro del Data Cache. +- `export const revalidate = 300`: Indica un periodo de revalidación en segundo plano (ISR) de 300 segundos (5 minutos). + +#### Diagrama de Secuencia Interno: + +```mermaid +sequenceDiagram + participant Client as Cliente HTTP / Browser + participant Route as Route Handler (GET /api/indicadores) + participant Engine as obtenerSnapshot() + participant BC as Banco Central API + + Client->>Route: GET /api/indicadores + Route->>Engine: obtenerSnapshot() + par 10 Consultas Concurrentes + Engine->>BC: getUltimoValor('uf') + Engine->>BC: getUltimoValor('dolar') + Engine->>BC: getUltimoValor(...) + end + BC-->>Engine: Respuestas JSON + Engine-->>Route: Objeto IndicadoresSnapshot | null + alt Snapshot Existente + Route-->>Client: HTTP 200 OK (JSON Snapshot) + else Fallo Total (Snapshot null) + Route-->>Client: HTTP 502 Bad Gateway (Error JSON) + end +``` + +#### Respuestas HTTP: + +##### HTTP 200 OK: + +```json +{ + "version": "2.0", + "autor": "Banco Central de Chile", + "fecha": "2026-07-27T17:19:29.000Z", + "uf": { + "codigo": "uf", + "nombre": "Unidad de fomento (UF)", + "unidad_medida": "Pesos", + "fecha": "2026-07-27T04:00:00.000Z", + "valor": 39412.87 + }, + "dolar": { + "codigo": "dolar", + "nombre": "Dólar observado", + "unidad_medida": "Pesos", + "fecha": "2026-07-25T04:00:00.000Z", + "valor": 963.12 + } +} +``` + +##### HTTP 502 Bad Gateway: + +```json +{ + "error": "No se pudo obtener ningun indicador desde el Banco Central" +} +``` + +--- + +## 📡 Endpoint 2: Obtenedor de Serie Histórica por Año + +### `GET /api/indicadores/[codigo]/[anio]` + +#### Propósito: + +Devuelve el desglose de observaciones de la serie histórica de un indicador específico durante un año calendario determinado. + +#### Parámetros de URL: + +- `codigo`: `string` — Identificador del indicador (ej: `'uf'`, `'dolar'`, `'ipc'`). +- `anio`: `string` — Año numérico de 4 dígitos (ej: `'2026'`). + +#### Validaciones y Códigos de Error: + +1. **Código Inexistente**: + Si `codigo` no está en la lista inmutable `INDICADOR_CODIGOS`: + - Status: `HTTP 400 Bad Request` + - Body: + + ```json + { + "error": "codigo invalido: bitcoin. Valores soportados: uf, ivp, dolar, euro, ipc, utm, imacec, tpm, libra_cobre, tasa_desempleo" + } + ``` + +2. **Año Formato/Rango Inválido**: + Si `anio` no son 4 dígitos o es menor a 1970 o mayor al año actual: + - Status: `HTTP 400 Bad Request` + - Body: + + ```json + { + "error": "anio invalido: 1850. Debe ser un numero de 4 digitos entre 1970 y 2026" + } + ``` + +3. **Fallo en API Externa**: + Si el Banco Central de Chile rechaza la consulta o vence el timeout: + - Status: `HTTP 502 Bad Gateway` + - Body: + ```json + { + "error": "Banco Central fallo para dolar: Tiempo de espera agotado al consultar la serie F073.TCO.PRE.Z.D" + } + ``` + +#### Respuesta de Éxito (HTTP 200 OK): + +```json +{ + "codigo": "uf", + "nombre": "Unidad de fomento (UF)", + "unidad_medida": "Pesos", + "serie": [ + { + "fecha": "2026-01-01T00:00:00.000Z", + "valor": 39350.1 + }, + { + "fecha": "2026-01-02T00:00:00.000Z", + "valor": 39352.45 + } + ] +} +``` diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..6d79718 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,117 @@ +# Arquitectura del Sistema y Decisiones de Diseño + +Este documento describe la arquitectura técnica de **Pulso**, explicando las decisiones de diseño fundamentales, la evolución desde servicios externos legacy hacia la API oficial del **Banco Central de Chile**, y los patrones de tolerancia a fallos implementados. + +--- + +## 📐 Visión de Arquitectura + +**Pulso** adopta una arquitectura modular basada en **Next.js 16 (App Router)** utilizando una separación clara entre: + +1. **Capa de Dominio y Tipos (`types/`)**: Define la estructura inmutable de los datos de indicadores (`Indicador`, `IndicadoresSnapshot`, `SerieHistorica`). +2. **Capa de Integración Externa y Adaptadores (`lib/`)**: Encapsula el acceso HTTP a la API externa del Banco Central (`bcentral-client.ts`), realiza la decodificación binaria de juegos de caracteres legacy (`ISO-8859-1`), y mantiene el caché estático de resiliencia (`indicadores-snapshot.ts`). +3. **Capa de API Proxy Interna (`app/api/`)**: Expone Route Handlers normalizados (`/api/indicadores` y `/api/indicadores/[codigo]/[anio]`) configurados con generación estática/ISR (`revalidate = 300`). +4. **Capa de Gestión de Estado y Hooks (`hooks/`)**: Provee hooks reactivos para hidratación en el cliente mediante SWR (`useIndicadores`, `useIndicadorHistory`) y sincronización de preferencias del usuario mediante `useSyncExternalStore` (`useFavoritos`). +5. **Capa de Interfaz de Usuario (`components/` y `app/`)**: Componentes de React 19 optimizados con TailwindCSS v4 y animación mediante Canvas/Chart.js para visualización de gráficos. + +```mermaid +graph TD + subgraph UI ["Capa de Presentación (React 19)"] + Page["app/page.tsx (Server Component)"] + Dashboard["DashboardHome (Client Component)"] + Chart["HistoryChart"] + Conv["Converter"] + Card["IndicatorCard"] + end + + subgraph Hooks ["Capa de Hooks React"] + uInd["useIndicadores()"] + uHist["useIndicadorHistory()"] + uFav["useFavoritos()"] + end + + subgraph API ["Capa de Endpoints Next.js (App Router)"] + R1["GET /api/indicadores"] + R2["GET /api/indicadores/[codigo]/[anio]"] + end + + subgraph Domain ["Capa de Dominio & Resiliencia"] + Snap["indicadores-snapshot.ts (obtenerSnapshot)"] + BCClient["bcentral-client.ts (BancoCentralClient)"] + Cache[("cachePorIndicador (In-Memory Map)")] + end + + subgraph External ["Servicio Externo"] + BCAPI["API Banco Central de Chile (SI3 SieteRestWS)"] + end + + Page -->|SSR Hydration| Snap + Dashboard --> uInd + Dashboard --> uFav + Chart --> uHist + Conv --> uInd + uInd --> R1 + uHist --> R2 + R1 --> Snap + R2 --> BCClient + Snap --> BCClient + Snap <--> Cache + BCClient -->|HTTP / ISO-8859-1| BCAPI +``` + +--- + +## 🔄 Migración de mindicador.cl a Banco Central (SI3 SieteRestWS) + +### 1. El Problema Original + +La aplicación dependía originalmente de `mindicador.cl`. Debido a problemas severos de disponibilidad e intermitencias en dicho servicio público, se decidió migrar la fuente de datos a la API oficial del **Banco Central de Chile (SI3 / SieteRestWS)**. + +### 2. Desafíos de Integración Técnicos + +La API del Banco Central de Chile presenta características particulares que requirieron decisiones de diseño específicas: + +| Desafío en Banco Central | Solución Arquitectónica Implementada | +| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **1 llamada por serie (vs 1 llamada global)** | Se migró el snapshot de 1 request a **10 requests en paralelo** usando `Promise.all`. Las pruebas demostraron que 10 llamadas concurrentes responden en ~0.23s sin activar rate limits. | +| **Respuesta en codificación `ISO-8859-1` (Latin-1)** | Fetch API decodifica JSON como `UTF-8` por defecto, corrompiendo caracteres como tildes o la "ñ" en `dólar`. Se implementó lectura de `ArrayBuffer` crudo y decodificación explícita con `new TextDecoder('iso-8859-1')`. | +| **Códigos HTTP siempre 200** | La API del Banco Central retorna status HTTP `200` aun en situaciones de error (credenciales inválidas, serie inexistente), reportando fallos en el cuerpo JSON (`Codigo !== 0`). Se creó la clase `BancoCentralApiError` para inspeccionar el cuerpo y lanzar excepciones. | +| **Formatos de fecha no estándar** | Las respuestas devuelven fechas en formato `DD-MM-YYYY`. Se creó un parser personalizado (`parseFechaBanco`) para convertir las cadenas a estándares ISO 8601 UTC. | +| **Días sin mercado y relleno de datos** | Indicadores financieros (dólar, euro) marcan días hábiles/fines de semana con `statusCode: "ND"` o los omiten. Se filtra estrictamente por `statusCode === "OK"`. | + +--- + +## 🛡️ Patrón de Resiliencia: Fallback Por Indicador + +Dado que la obtención de datos requiere 10 llamadas independientes al Banco Central, un fallo parcial (por ejemplo, timeout en la serie del IPC) no debe romper la visualización de los otros 9 indicadores ni tirar abajo toda la aplicación. + +### Estrategia de Caché Individual: + +```typescript +const cachePorIndicador = new Map(); +``` + +1. **Consulta Individual con Catch In-line**: Cada indicador se consulta de forma independiente dentro de `obtenerConFallback(codigo)`. +2. **Actualización Selectiva**: Si la llamada a `getUltimoValor(codigo)` tiene éxito, actualiza el valor en `cachePorIndicador` y lo retorna. +3. **Graceful Degradation**: Si la llamada falla (error de red, timeout de 8s o error del Banco Central), se captura la excepción, se registra el error en consola y se devuelve el último valor válido almacenado en el `Map` en memoria. +4. **Fallo Total**: Si un indicador nunca pudo ser consultado (arranque en frío) y la API falla, la clave quedará `undefined`. Si **todos** los 10 indicadores fallan y no hay caché, la función `obtenerSnapshot()` retorna `null`, permitiendo al Route Handler devolver un código HTTP `502 Bad Gateway`. + +--- + +## ⚡ Patrón de Hidratación de Estado en SSR con SWR + +Para prevenir el molesto "flash de esqueleto de carga" (Layout Shift) al recargar la página en el cliente, la aplicación utiliza una estrategia de hidratación isomórfica: + +1. **Server Component (`app/page.tsx`)**: Ejecuta `obtenerSnapshot()` durante el renderizado en el servidor. +2. **Inyección en SWR (``)**: Encapsula el Client Component `` inyectando el snapshot inicial bajo la clave `/api/indicadores`. +3. **Hydration en Cliente**: Cuando React se hidrata en el navegador, `useIndicadores()` lee inmediatamente del caché de SWR inyectado en el render inicial sin disparar un loader, e inicia la revalidación en segundo plano (`isValidating`). + +--- + +## 🔐 Middleware Dev Proxy Security Guard + +En el directorio `/app/dev/ui`, existe una página de demostración de componentes UI (Storybook liviano). Para evitar que esta ruta sea expuesta en entornos de producción: + +1. El archivo `proxy.ts` exporta una función middleware matcher `/dev/ui`. +2. Si `process.env.NODE_ENV === 'production'`, el proxy intercepta la petición y retorna una respuesta `NextResponse` con status `404 Not Found`. +3. Adicionalmente, el Server Component en `app/dev/ui/page.tsx` invoca `notFound()` como mecanismo de defensa en profundidad. diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 0000000..3e475bd --- /dev/null +++ b/docs/authentication.md @@ -0,0 +1,59 @@ +# Autenticación, Autorización y Seguridad + +Este documento describe el modelo de seguridad, gestión de credenciales y protección de entornos aplicado en **Pulso**. + +--- + +## 🔐 Modelo de Usuario y Acceso Público + +**Pulso** es una aplicación pública de libre acceso que no requiere registro de usuarios, inicio de sesión (Login/Logout), Json Web Tokens (JWT), ni manejo de cookies de sesión o autenticación en el cliente. + +- **Frontend**: Acceso 100% anónimo para cualquier cliente. +- **Preferencias**: Las listas de favoritos se persisten localmente en la máquina del usuario (`localStorage`) sin enviar identificadores a ningún servidor. + +--- + +## 🔑 Credenciales de Integración Backend + +Aunque la aplicación es pública para el usuario final, la comunicación entre el servidor de Next.js y el servicio **SI3 del Banco Central de Chile** requiere autenticación mediante credenciales asignadas: + +```typescript +const user = process.env.BCENTRAL_USER; +const pass = process.env.BCENTRAL_PASS; +``` + +### Reglas de Seguridad de Credenciales: + +1. **Aislamiento en Servidor**: Las variables `BCENTRAL_USER` y `BCENTRAL_PASS` se consumen **únicamente** en `lib/bcentral-client.ts` dentro del entorno Node.js del servidor. +2. **Sin Prefijo `NEXT_PUBLIC_`**: Al no usar el prefijo `NEXT_PUBLIC_`, el compilador de Next.js excluye tajantemente estas variables del bundle JavaScript enviado al cliente/navegador, evitando cualquier fuga o exposición de credenciales secretas. + +--- + +## 🛡️ Protección de Rutas de Desarrollo (Dev Proxy) + +El proyecto incluye una herramienta de desarrollo visual en la ruta `/dev/ui`. Para prevenir que usuarios externos o motores de búsqueda accedan a esta interfaz en producciones desplegadas: + +### 1. Capa de Middleware Proxy (`proxy.ts`): + +```typescript +export function proxy() { + if (process.env.NODE_ENV === 'production') { + return new NextResponse(null, { status: 404 }); + } + return NextResponse.next(); +} + +export const config = { + matcher: '/dev/ui', +}; +``` + +### 2. Capa de Servidor (`app/dev/ui/page.tsx`): + +```typescript +if (process.env.NODE_ENV === 'production') { + notFound(); +} +``` + +Esta estrategia de **defensa en profundidad** asegura que en producción la ruta devuelva un código HTTP `404 Not Found`, ocultando su existencia por completo. diff --git a/docs/code/app.md b/docs/code/app.md new file mode 100644 index 0000000..157047b --- /dev/null +++ b/docs/code/app.md @@ -0,0 +1,117 @@ +# Documentación de Código: Carpeta `app/` + +Esta carpeta contiene la infraestructura de rutas, renderizado de servidor, endpoints de API internos y metadatos SEO utilizando el enrutador **App Router** de Next.js. + +--- + +## 📂 Archivos en `app/` + +### 1. `app/layout.tsx` + +- **Resumen**: Layout raíz obligatorio de Next.js. Define la estructura `` y ``, carga las fuentes tipográficas de Google Fonts, incluye la hoja de estilos global `globals.css` e integra las analíticas de Vercel (`@vercel/analytics`). +- **Por qué existe**: Garantizar una envoltura HTML uniforme y accesible para todas las páginas del sitio. +- **Dependencias**: + - Importa: `next/font/google` (`Fira_Sans`, `Fira_Code`), `@vercel/analytics/next`, `./globals.css`. + - Exporta: `metadata` (Metadata), `default function RootLayout`. +- **Explicación del Código**: + Configura las fuentes con variables CSS `--font-fira-sans` y `--font-fira-mono`. Aplica la clase `dark` al elemento `` forzando el tema oscuro (`colorScheme: 'dark'`). + +--- + +### 2. `app/page.tsx` + +- **Resumen**: Server Component principal de la Home Page (`/`). +- **Por qué existe**: Realizar la carga inicial de datos en el servidor (`obtenerSnapshot()`) e inyectarla en el contenedor `` para que el Client Component `` se hidrate sin flashes de carga. +- **Dependencias**: + - Importa: `swr` (`SWRConfig`), `@/components/DashboardHome`, `@/hooks/useIndicadores` (`ENDPOINT_INDICADORES`), `@/lib/indicadores-snapshot` (`obtenerSnapshot`). + - Exporta: `metadata` (Metadata), `default async function Home`. +- **Casos Borde**: Si `obtenerSnapshot()` retorna `null`, `` recibe un objeto `fallback` vacío `{}`, permitiendo que el cliente reintente la carga vía SWR. + +--- + +### 3. `app/error.tsx` + +- **Resumen**: Error Boundary global de la aplicación (`'use client'`). +- **Por qué existe**: Capturar excepciones no controladas durante el renderizado y ofrecer una interfaz accesible de recuperación. +- **Dependencias**: + - Exporta: `default function Error({ error, unstable_retry })`. +- **Flujo Interno**: Registra el error en consola mediante `useEffect` y muestra un mensaje contextual con un botón que ejecuta `unstable_retry()`. + +--- + +### 4. `app/loading.tsx` + +- **Resumen**: Componente de interfaz de carga global. +- **Por qué existe**: Actuar como estado de espera (Suspense fallback) durante navegaciones o carga de datos en el servidor. +- **Dependencias**: Importa `@/components/Skeleton`. + +--- + +### 5. `app/not-found.tsx` + +- **Resumen**: Página de error 404. +- **Por qué existe**: Renderizar una vista amigable cuando la ruta solicitada no existe. +- **Dependencias**: Importa `next/link`. + +--- + +### 6. `app/globals.css` + +- **Resumen**: Hoja de estilos global. +- **Por qué existe**: Importar TailwindCSS v4 (`@import "tailwindcss";`) y definir tokens CSS globales de color, tipografía y animaciones (`@keyframes fade-in`). + +--- + +### 7. `app/robots.ts` + +- **Resumen**: Generador programático de `robots.txt`. +- **Por qué existe**: Configurar directivas para motores de búsqueda, permitiendo la indexación de `/` y bloqueando `/dev/ui` y `/api/`. + +--- + +### 8. `app/sitemap.ts` + +- **Resumen**: Generador programático de `sitemap.xml`. +- **Por qué existe**: Proveer el mapa del sitio para optimización en motores de búsqueda (SEO). + +--- + +### 9. `app/opengraph-image.tsx` + +- **Resumen**: Generador dinámico de imagen OpenGraph PNG (1200x630). +- **Por qué existe**: Producir la tarjeta visual de previsualización que se muestra cuando la URL del sitio se comparte en redes sociales (Twitter, WhatsApp, LinkedIn). +- **Dependencias**: Importa `next/og` (`ImageResponse`). + +--- + +### 10. `app/dev/ui/page.tsx` + +- **Resumen**: Playground / Showcase de componentes UI. +- **Por qué existe**: Permitir probar visualmente todos los componentes base del sistema en desarrollo. +- **Seguridad**: Ejecuta `notFound()` en producciones. + +--- + +### 11. `app/api/indicadores/route.ts` + +- **Resumen**: Route Handler para GET `/api/indicadores`. +- **Por qué existe**: Servir el snapshot JSON actual de los 10 indicadores económicos. +- **Configuración**: `dynamic = 'force-static'`, `revalidate = 300`. +- **Flujo Interno**: + 1. Invoca `obtenerSnapshot()`. + 2. Si retorna `null`, responde con HTTP 502 Bad Gateway. + 3. De lo contrario, responde con HTTP 200 OK y el snapshot JSON. + +--- + +### 12. `app/api/indicadores/[codigo]/[anio]/route.ts` + +- **Resumen**: Route Handler para GET `/api/indicadores/[codigo]/[anio]`. +- **Por qué existe**: Retornar las observaciones de una serie histórica para un año específico. +- **Validaciones**: + 1. Valida si `codigo` es un `IndicadorCodigo` válido (HTTP 400 en caso contrario). + 2. Valida si `anio` es un número de 4 dígitos entre 1970 y el año actual (HTTP 400 en caso contrario). +- **Flujo Interno**: + 1. Deriva el rango `firstdate` y `lastdate` usando `rangoDelAnio(anioNum)`. + 2. Invoca `getSerieHistorica(codigo, firstdate, lastdate)`. + 3. Retorna la serie en JSON o un HTTP 502 si el Banco Central falla. diff --git a/docs/code/components.md b/docs/code/components.md new file mode 100644 index 0000000..afb770e --- /dev/null +++ b/docs/code/components.md @@ -0,0 +1,88 @@ +# Documentación de Código: Carpeta `components/` + +Esta carpeta alberga los componentes React de interfaz de usuario de **Pulso**. + +--- + +## 📂 Archivos en `components/` + +### 1. `components/DashboardHome.tsx` + +- **Responsabilidad**: Orquestador principal del dashboard. +- **Props**: Ninguna (Componente contenedor de alto nivel). +- **Estado**: + - `indicadorSeleccionado` (`IndicadorCodigo`): Indicador mostrado en el gráfico. + - `mostrarConversor` (`boolean`): Visibilidad del conversor. + - `soloFavoritos` (`boolean`): Filtro de la grilla. +- **Flujo Visual**: + ```mermaid + graph TD + DH[DashboardHome] --> Header[Header / Stats & Controls] + DH --> Chart[HistoryChart] + DH --> Conv[Converter (Opcional)] + DH --> Grid[Grilla de IndicatorCard] + ``` + +--- + +### 2. `components/IndicatorCard.tsx` + +- **Responsabilidad**: Presentar la tarjeta individual de un indicador económico. +- **Props**: + - `codigo`: `IndicadorCodigo` + - `indicador?`: `Indicador` + - `error?`: `boolean` + - `isLoading?`: `boolean` + - `seleccionado?`: `boolean` + - `onSelect?`: `() => void` +- **Comportamiento**: Soporta eventos de teclado (`Enter`, `Space`) cuando `onSelect` está configurado. + +--- + +### 3. `components/HistoryChart.tsx` + +- **Responsabilidad**: Gráfico de series temporales dinámicas mediante `Chart.js`. +- **Props**: + - `codigo`: `IndicadorCodigo` + - `fechaReferencia?`: `string | Date` + - `unidadMedida?`: `string` +- **Selección de Rango**: Pestañas para `'1M'`, `'1A'`, `'2A'`. Oculta `'1M'` dinámicamente si hay menos de 3 observaciones disponibles. + +--- + +### 4. `components/Converter.tsx` + +- **Responsabilidad**: Calculadora de conversión entre Pesos Chilenos (CLP) e indicadores económicos. +- **Estado**: `codigo`, `direccion`, `montoTexto`. +- **Lógica Borde**: Detecta si el indicador es de unidad `'Porcentaje'` para bloquear el cálculo monetario e informar el valor porcentual actual. + +--- + +### 5. `components/FavoritesToggle.tsx` + +- **Responsabilidad**: Botón interactivo en forma de estrella para agregar/quitar favoritos. +- **Props**: `activo`, `onToggle`, `className`. + +--- + +### 6. `components/VariationBadge.tsx` + +- **Responsabilidad**: Insignia para mostrar variaciones numéricas porcentuales con flechas de tendencia (`↑`, `↓`, `–`). + +--- + +### 7. `components/Button.tsx` + +- **Responsabilidad**: Componente base de botón UI con variantes `primary` y `secondary`. + +--- + +### 8. `components/Skeleton.tsx` + +- **Responsabilidad**: Bloque animado para representar estados de carga (_Skeleton loader_). + +--- + +### 9. `components/Spinner.tsx` + +- **Responsabilidad**: Indicador de carga animado circular accesible. diff --git a/docs/code/hooks.md b/docs/code/hooks.md new file mode 100644 index 0000000..72a9602 --- /dev/null +++ b/docs/code/hooks.md @@ -0,0 +1,31 @@ +# Documentación de Código: Carpeta `hooks/` + +Esta carpeta contiene los custom hooks de React desarrollados para la gestión de datos remotos y estado local en **Pulso**. + +--- + +## 📂 Archivos en `hooks/` + +### 1. `hooks/useIndicadores.ts` + +- **Responsabilidad**: Obtener la fotografía actual de los indicadores desde `/api/indicadores` con SWR. +- **Exportaciones**: + - `ENDPOINT_INDICADORES`: Constante `/api/indicadores`. + - `useIndicadores()`: Hook principal. +- **Retorno**: `{ data, isLoading, isValidating, error }`. + +--- + +### 2. `hooks/useIndicadorHistory.ts` + +- **Responsabilidad**: Obtener las series históricas multianuales consolidadas de un indicador. +- **Firma**: `useIndicadorHistory(codigo: IndicadorCodigo, fechaAncla: Date)` +- **Estrategia**: Consulta en paralelo los 3 años requeridos para cubrir hasta 24 meses hacia atrás desde la fecha ancla. + +--- + +### 3. `hooks/useFavoritos.ts` + +- **Responsabilidad**: Administrar la lista de indicadores preferidos persistida en `localStorage`. +- **Implementación**: Utiliza `useSyncExternalStore` para evitar parpadeos de hidratación en SSR y mantener la sincronización multi-pestaña mediante eventos `storage`. +- **Retorno**: `{ favoritos, toggleFavorito, esFavorito }`. diff --git a/docs/code/lib.md b/docs/code/lib.md new file mode 100644 index 0000000..f580b2a --- /dev/null +++ b/docs/code/lib.md @@ -0,0 +1,40 @@ +# Documentación de Código: Carpeta `lib/` + +Esta carpeta alberga la lógica de negocio central, clientes de integración externa y funciones utilitarias de formateo. + +--- + +## 📂 Archivos en `lib/` + +### 1. `lib/bcentral-client.ts` + +- **Responsabilidad**: Cliente HTTP para consumir la API SieteRestWS / SI3 del Banco Central de Chile. +- **Exportaciones**: + - `BancoCentralApiError`: Clase de excepción personalizada. + - `getSerieHistorica(codigo, firstdate, lastdate)`: Retorna la serie histórica parseada. + - `getUltimoValor(codigo, options?)`: Retorna el punto más reciente disponible. + - `getCodigoSerieBancoCentral(codigo)`: Mapea un código interno al código de serie del Banco Central. +- **Características Clave**: + - Parsea la respuesta binaria con `new TextDecoder('iso-8859-1')`. + - Valida el status funcional `Codigo === 0`. + - Implementa un timeout de 8 segundos vía `AbortController`. + +--- + +### 2. `lib/indicadores-snapshot.ts` + +- **Responsabilidad**: Motor de resiliencia y gestión de caché en memoria volatil. +- **Exportaciones**: + - `obtenerSnapshot()`: Retorna `Promise`. +- **Estrategia**: Consulta los 10 indicadores en paralelo mediante `Promise.all` e implementa fallback por indicador utilizando un `Map` persistente durante el ciclo de vida del proceso en servidor Node.js. + +--- + +### 3. `lib/format.ts` + +- **Responsabilidad**: Formatear valores numéricos y fechas según convenciones chilenas (`es-CL`). +- **Exportaciones**: + - `formatCLP(valor: number): string` + - `formatPorcentaje(valor: number): string` + - `formatFecha(fecha: string | Date): string` + - `formatValorPorUnidad(valor: number, unidadMedida?: string): string` diff --git a/docs/code/root.md b/docs/code/root.md new file mode 100644 index 0000000..3555413 --- /dev/null +++ b/docs/code/root.md @@ -0,0 +1,54 @@ +# Documentación de Código: Archivos Raíz y Configuración + +Este documento detalla los archivos de configuración y scripts ubicados en la raíz del repositorio de **Pulso**. + +--- + +## 📂 Archivos en la Raíz + +### 1. `proxy.ts` + +- **Responsabilidad**: Middleware de protección para la ruta `/dev/ui`. +- **Funcionamiento**: Intercepta peticiones a `/dev/ui`. Si `process.env.NODE_ENV === 'production'`, retorna un código HTTP `404 Not Found`. + +--- + +### 2. `next.config.ts` + +- **Responsabilidad**: Objeto de configuración principal para la compilación y ejecución de Next.js. + +--- + +### 3. `tsconfig.json` + +- **Responsabilidad**: Configuración del compilador TypeScript (modo estricto, alias `@/*`, target ES2017). + +--- + +### 4. `eslint.config.mjs` + +- **Responsabilidad**: Reglas de análisis de código estático (ESLint v9 Flat Config). + +--- + +### 5. `postcss.config.mjs` + +- **Responsabilidad**: Integración de PostCSS con `@tailwindcss/postcss` v4. + +--- + +### 6. `vitest.config.ts` & `vitest-setup.ts` + +- **Responsabilidad**: Configuración del runner de pruebas unitarias Vitest con entorno `jsdom` (configurado en `http://localhost:3000` para `localStorage`) y limpieza automática de DOM. + +--- + +### 7. `playwright.config.ts` + +- **Responsabilidad**: Configuración de pruebas automatizadas End-to-End con Playwright sobre la compilación de producción (`npm run build && npm run start`). + +--- + +### 8. `package.json` + +- **Responsabilidad**: Manifiesto de dependencias, información del proyecto y scripts npm (`dev`, `build`, `start`, `lint`, `format`, `test`, `test:e2e`). diff --git a/docs/code/types.md b/docs/code/types.md new file mode 100644 index 0000000..830bff0 --- /dev/null +++ b/docs/code/types.md @@ -0,0 +1,18 @@ +# Documentación de Código: Carpeta `types/` + +Esta carpeta contiene los contratos de tipos e interfaces de TypeScript del sistema. + +--- + +## 📂 Archivos en `types/` + +### 1. `types/indicador.ts` + +- **Responsabilidad**: Definir las estructuras de datos fundamentales para los indicadores económicos. +- **Exportaciones**: + - `INDICADOR_CODIGOS`: Lista inmutable de códigos soportados (`uf`, `ivp`, `dolar`, `euro`, `ipc`, `utm`, `imacec`, `tpm`, `libra_cobre`, `tasa_desempleo`). + - `IndicadorCodigo`: Tipo union de códigos válidos. + - `Indicador`: Interface de un indicador puntual (`codigo`, `nombre`, `unidad_medida`, `fecha`, `valor`). + - `IndicadoresSnapshot`: Interface del snapshot completo con campos opcionales para resiliencia. + - `SerieHistoricaPunto`: Interface de una observación puntual (`fecha`, `valor`). + - `SerieHistorica`: Interface de una serie temporal completa. diff --git a/docs/components.md b/docs/components.md new file mode 100644 index 0000000..3ed5e28 --- /dev/null +++ b/docs/components.md @@ -0,0 +1,149 @@ +# Sistema de Componentes React UI + +Este documento especifica la arquitectura de interfaz de usuario de **Pulso**, detallando cada componente React, sus propiedades (props), estado interno, accesibilidad y ciclo de renderizado. + +--- + +## 🧩 Catálogo de Componentes + +### 1. `DashboardHome` + +- **Archivo**: `components/DashboardHome.tsx` +- **Tipo**: Client Component (`'use client'`). +- **Propósito**: Contenedor principal de la interfaz del dashboard. Coordina la barra superior, el selector de indicador destacado, la grilla de tarjetas, el conversor y el filtro de favoritos. +- **Estado Interno**: + - `indicadorSeleccionado`: `IndicadorCodigo` (por defecto `'dolar'`). Define qué indicador se grafica en ``. + - `mostrarConversor`: `boolean` (por defecto `false`). Controla la visibilidad de la sección de conversión. + - `soloFavoritos`: `boolean` (por defecto `false`). Filtra la grilla para mostrar únicamente los indicadores marcados como favoritos. + - `soloFavoritosAnterior`: Control de estado durante la renderización para ajustar automáticamente el indicador seleccionado si el seleccionado previo deja de estar visible al filtrar. +- **Hooks Utilizados**: `useIndicadores()`, `useFavoritos()`, `useMemo()`, `useState()`. +- **Estructura JSX Notable**: + - Encabezado con título, timestamp de última actualización formateado con `formatFecha()`, spinner de validación en segundo plano y botones de alternancia (Favoritos / Conversor). + - Sección superior con `` del indicador seleccionado. + - Sección opcional con ``. + - Grilla responsiva (`grid-cols-1 min-[360px]:grid-cols-2 sm:grid-cols-[repeat(auto-fit,minmax(150px,1fr))]`) con las tarjetas ``. + +--- + +### 2. `IndicatorCard` + +- **Archivo**: `components/IndicatorCard.tsx` +- **Tipo**: Client Component (`'use client'`). +- **Propósito**: Renderizar una tarjeta individual con la información de un indicador económico. +- **Props Interface**: + +```typescript +interface IndicatorCardProps { + codigo: IndicadorCodigo; + indicador?: Indicador; + error?: boolean; + isLoading?: boolean; + seleccionado?: boolean; + onSelect?: () => void; +} +``` + +- **Hooks Utilizados**: `useFavoritos()`. +- **Accesibilidad**: Si `onSelect` está presente, la tarjeta actúa como botón accesible (`role="button"`, `tabIndex={0}`, `aria-pressed={seleccionado}`, y escucha de teclas `Enter` y `Space`). +- **Estados de Renderizado**: + 1. **Loading (`isLoading === true`)**: Muestra bloques ``. + 2. **No Disponible (`error || !indicador`)**: Muestra un texto secundario "Dato no disponible". + 3. **Éxito**: Muestra el nombre recortado (`truncate`), el valor formateado con `formatValorPorUnidad()` y el botón ``. + +--- + +### 3. `HistoryChart` + +- **Archivo**: `components/HistoryChart.tsx` +- **Tipo**: Client Component (`'use client'`). +- **Propósito**: Visualizar la evolución histórica de un indicador mediante un gráfico de líneas dinámico. +- **Props Interface**: + +```typescript +interface HistoryChartProps { + codigo: IndicadorCodigo; + fechaReferencia?: string | Date; + unidadMedida?: string; +} +``` + +- **Estado y Selección de Rango**: + - Soporta tres rangos: `'1M'` (1 mes), `'1A'` (1 año), `'2A'` (2 años). + - Filtra dinámicamente los rangos visibles mediante `MIN_PUNTOS_RANGO = 3`. Si un indicador mensual tiene menos de 3 puntos en 1 mes, la pestaña `'1M'` se oculta automáticamente para evitar mostrar gráficos vacíos o distorsionados. +- **Integración con Chart.js**: + - Utiliza `react-chartjs-2` registrado con `CategoryScale`, `LinearScale`, `PointElement`, `LineElement`, `Tooltip`, `Filler`. + - Obtiene colores de variables CSS (`getCssVar('--up')` / `getCssVar('--down')`) para ajustar dinámicamente el color de la línea según la tendencia (verde si el valor final ≥ inicial, rojo si descendió). + - Personalización de Tooltips para formatear valores y fechas con la configuración regional de Chile. + +--- + +### 4. `Converter` + +- **Archivo**: `components/Converter.tsx` +- **Tipo**: Client Component (`'use client'`). +- **Propósito**: Calculadora bidireccional para convertir montos entre Pesos Chilenos (CLP) e Indicadores (ej: UF a CLP o CLP a Dólar). +- **Estado Interno**: + - `codigo`: `IndicadorCodigo` (por defecto `'uf'`). + - `direccion`: `'clpAIndicador' | 'indicadorAClp'`. + - `montoTexto`: `string` (por defecto `'100000'`). +- **Lógica de Cálculo**: + - Si el indicador es de tipo `'Porcentaje'` (ej: IPC, TPM, Imacec, Tasa de desempleo), el conversor detecta que no es una unidad convertible en dinero y muestra un mensaje informativo con el valor actual. + - De lo contrario, calcula `monto / valor` o `monto * valor` utilizando `useMemo`. + - Botón de Inversión (`handleSwap`): Invierte la dirección y recalcula el monto manteniendo el valor equivalente. + +--- + +### 5. `FavoritesToggle` + +- **Archivo**: `components/FavoritesToggle.tsx` +- **Tipo**: Client Component (`'use client'`). +- **Propósito**: Botón de estrella interactivo para marcar o desmarcar un indicador como favorito. +- **Props Interface**: + +```typescript +interface FavoritesToggleProps { + activo: boolean; + onToggle: () => void; + className?: string; +} +``` + +- **Comportamiento**: Detiene la propagación del evento (`event.stopPropagation()`) para prevenir que el clic dispare el `onSelect` de la tarjeta contenedora ``. + +--- + +### 6. `VariationBadge` + +- **Archivo**: `components/VariationBadge.tsx` +- **Tipo**: Componente Presentacional. +- **Propósito**: Mostrar pequeñas insignias numéricas con la variación porcentual y flechas indicadoras de tendencia (`↑` verde para positivo, `↓` rojo para negativo, `–` gris para neutro). +- **Props Interface**: + +```typescript +interface VariationBadgeProps { + value: number; + size?: 'default' | 'lg'; + className?: string; +} +``` + +--- + +### 7. `Button` + +- **Archivo**: `components/Button.tsx` +- **Propósito**: Botón UI estándar con variantes `primary` (fondo acento) y `secondary` (borde sutil), estados disabled y estilos de foco accesibles (`focus-visible`). + +--- + +### 8. `Skeleton` + +- **Archivo**: `components/Skeleton.tsx` +- **Propósito**: Bloque con animación de pulso (`animate-pulse`) para representar estados de carga en componentes. Acepta propiedades `width`, `height` o clases utilitarias de Tailwind. + +--- + +### 9. `Spinner` + +- **Archivo**: `components/Spinner.tsx` +- **Propósito**: Indicador circular giratorio (`animate-spin`) con atributo `role="status"` y `aria-label="Actualizando"` para tecnologías de asistencia. diff --git a/docs/database.md b/docs/database.md new file mode 100644 index 0000000..43aac87 --- /dev/null +++ b/docs/database.md @@ -0,0 +1,57 @@ +# Estrategia de Almacenamiento y Caché de Datos + +Este documento describe la arquitectura de almacenamiento, persistencia y cachés utilizada por la aplicación **Pulso**. + +--- + +## 💾 Ausencia de Base de Datos Tradicional + +El proyecto **Pulso** no utiliza una base de datos relacional (PostgreSQL, MySQL) ni NoSQL (MongoDB, Redis) persistida en disco. La aplicación funciona como un **proxy inteligente con resiliencia en memoria** frente a la API del Banco Central de Chile. + +--- + +## 🗄️ Capas de Caché del Sistema + +La arquitectura implementa tres niveles de caché complementarios: + +```mermaid +graph TD + subgraph Browser ["1. Navegador del Usuario"] + LS["localStorage ('pulso.favoritos')"] + SWR["SWR Memory Cache"] + end + + subgraph NextServer ["2. Servidor Next.js (Node.js Process)"] + MapCache["lib/indicadores-snapshot.ts (cachePorIndicador Map)"] + DataCache["Next.js Data Cache (revalidate = 300)"] + end + + subgraph Remote ["3. API Externa"] + BCentral["Banco Central de Chile"] + end + + SWR -->|Petición /api/indicadores| DataCache + DataCache -->|ISR / Revalidate| MapCache + MapCache -->|Fetch GetSeries| BCentral + LS <-->|State Synchronization| Browser +``` + +### 1. Caché en Memoria Volátil del Proceso (`cachePorIndicador`) + +- **Ubicación**: `lib/indicadores-snapshot.ts` +- **Mecanismo**: `const cachePorIndicador = new Map()` +- **Propósito**: Mantiene el último valor exitoso conocido para cada uno de los 10 indicadores de forma independiente. +- **Tolerancia a Fallos**: Si la API del Banco Central experimenta una caída momentánea en la serie de un indicador, el sistema sirve el valor almacenado en este `Map` en lugar de responder con un error. + +### 2. Next.js Data Cache & Incremental Static Regeneration (ISR) + +- **Ubicación**: Route Handlers (`app/api/indicadores/route.ts` y `.../[codigo]/[anio]/route.ts`) y `lib/bcentral-client.ts`. +- **Mecanismo**: `export const dynamic = 'force-static'`, `export const revalidate = 300` y `{ next: { revalidate: 300 } }` en las llamadas `fetch`. +- **Propósito**: Garantizar que el servidor de Next.js almacene en caché las respuestas durante 5 minutos (300 segundos), reduciendo drásticamente la carga de peticiones sobre la infraestructura pública del Banco Central. + +### 3. Almacenamiento Local del Cliente (`localStorage`) + +- **Ubicación**: Navegador web del cliente. +- **Clave**: `'pulso.favoritos'` +- **Formato**: Arreglo JSON serializado (ej: `["uf", "dolar"]`). +- **Propósito**: Persistir la selección de indicadores preferidos del usuario entre sesiones de navegación sin requerir una cuenta de usuario o base de datos en servidor. diff --git a/docs/dependencies.md b/docs/dependencies.md new file mode 100644 index 0000000..22027bc --- /dev/null +++ b/docs/dependencies.md @@ -0,0 +1,40 @@ +# Análisis de Dependencias + +Este documento analiza las bibliotecas y paquetes de software especificados en el archivo `package.json` de **Pulso**. + +--- + +## 📦 Dependencias de Producción (`dependencies`) + +| Paquete | Versión | Propósito / Rol en la Aplicación | +| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `next` | `16.2.11` | Framework principal del proyecto. Proveedor de App Router, Server Components, Route Handlers y optimización de assets. | +| `react` | `19.2.4` | Biblioteca de UI central. Aprovecha características de React 19 como `useSyncExternalStore` y Server Actions. | +| `react-dom` | `19.2.4` | Renderizador DOM para React. | +| `swr` | `2.4.2` | Biblioteca de Data Fetching para React. Maneja el caché del cliente, revalidación en foco e hidratación desde el servidor (`SWRConfig`). | +| `chart.js` | `4.5.1` | Motor gráfico basado en Canvas 2D. Utilizado para renderizar las curvas temporales de series históricas de manera fluida y optimizada. | +| `react-chartjs-2` | `5.3.1` | Wrapper de React para integrar componentes declarativos de `chart.js`. | +| `@vercel/analytics` | `2.0.1` | Módulo de analíticas en tiempo real para recopilar métricas de uso y rendimiento en la nube de Vercel. | + +--- + +## 🛠️ Dependencias de Desarrollo (`devDependencies`) + +| Paquete | Versión | Propósito / Rol en la Aplicación | +| ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- | +| `typescript` | `^5` | Lenguaje de programación con sistema de tipos estático. | +| `tailwindcss` | `^4` | Framework CSS utilitario v4. | +| `@tailwindcss/postcss` | `^4` | Plugin de PostCSS para procesar estilos de TailwindCSS v4. | +| `vitest` | `^4.1.10` | Runner de pruebas unitarias ultrarrápido integrado con Vite. | +| `@testing-library/react` | `^16.3.2` | Utilidades para probar componentes de React simulando la perspectiva del usuario. | +| `@testing-library/jest-dom` | `^7.0.0` | Matchers de Jest/Vitest personalizados para aserciones sobre el DOM (`toBeInTheDocument`, etc.). | +| `@testing-library/user-event` | `^14.6.1` | Simulación realista de eventos de teclado y ratón en los tests. | +| `jsdom` | `^29.1.1` | Implementación pura en Node.js de los estándares DOM y HTML Web APIs para pruebas. | +| `@playwright/test` | `^1.62.0` | Framework de pruebas End-to-End para automatizar navegadores reales (Chromium). | +| `eslint` | `^9` | Linter de código estático. | +| `eslint-config-next` | `16.2.11` | Reglas oficiales de linting recomendadas por el equipo de Next.js. | +| `eslint-config-prettier` | `^10.1.8` | Desactiva reglas de ESLint que puedan entrar en conflicto con Prettier. | +| `prettier` | `^3.9.6` | Formateador de código automático. | +| `husky` | `^9.1.7` | Gestor de Git Hooks para ejecutar validaciones en pre-commit. | +| `lint-staged` | `^17.2.0` | Ejecuta linters y formateadores únicamente sobre los archivos agregados al Git Staging Area. | +| `cross-env` | `^10.1.0` | Permite definir variables de entorno en comandos de scripts de forma multiplataforma (Windows/macOS/Linux). | diff --git a/docs/environment.md b/docs/environment.md new file mode 100644 index 0000000..3131d55 --- /dev/null +++ b/docs/environment.md @@ -0,0 +1,63 @@ +# Variables de Entorno y Configuración del Entorno + +Este documento describe todas las variables de entorno, archivos de configuración del proyecto y herramientas de tooling utilizadas en **Pulso**. + +--- + +## 🔑 Variables de Entorno + +Para que la aplicación pueda consultar la API del Banco Central de Chile, es indispensable configurar las credenciales oficiales en las variables de entorno del servidor. + +### Lista de Variables: + +| Variable | Tipo | Requerida | Entorno | Descripción | Ejemplo | +| --------------- | --------- | --------- | -------- | -------------------------------------------------------------------------------------------- | ---------------------- | +| `BCENTRAL_USER` | `string` | **Sí** | Servidor | Nombre de usuario / Email registrado en la plataforma SieteRestWS del Banco Central de Chile | `mi_usuario@correo.cl` | +| `BCENTRAL_PASS` | `string` | **Sí** | Servidor | Contraseña asociada a la cuenta del Banco Central de Chile | `SecretPass123!` | +| `CI` | `boolean` | No | CI/CD | Variable inyectada automáticamente por entornos de Integración Continua (GitHub Actions) | `true` | + +### Archivos de Configuración de Entorno: + +- `.env.example`: Archivo de plantilla seguro para ser commiteado en el repositorio (contiene claves sin valores sensibles). +- `.env.local`: Archivo de configuración local no commiteado (ignorado en `.gitignore`) que contiene los secretos reales para desarrollo. + +> [!IMPORTANT] +> **Ninguna variable debe llevar el prefijo `NEXT_PUBLIC_`**. Las credenciales del Banco Central deben permanecer estrictamente restringidas a las ejecuciones dentro del servidor Node.js. + +--- + +## ⚙️ Archivos de Configuración del Proyecto + +### 1. `next.config.ts` + +- Configuración principal del framework Next.js. Define opciones del compilador y soporte de TypeScript. + +### 2. `tsconfig.json` + +- Configuración del compilador de TypeScript: + - `target`: `ES2017` + - `strict`: `true` (Modo estricto activado). + - `moduleResolution`: `"bundler"` + - `paths`: Alias de importación `@/*` mapeado al directorio raíz `./*`. + +### 3. `postcss.config.mjs` & TailwindCSS v4 + +- Configuración de PostCSS que integra `@tailwindcss/postcss` v4. +- TailwindCSS v4 utiliza la directiva `@import "tailwindcss";` dentro de `app/globals.css` junto con variables CSS nativas (`--color-surface`, `--color-accent`, etc.). + +### 4. `eslint.config.mjs` + +- Configuración Flat Config de ESLint v9 integrada con `eslint-config-next` y `eslint-config-prettier`. + +### 5. `vitest.config.ts` & `vitest-setup.ts` + +- Entorno de pruebas unitarias Vitest: + - Utiliza `jsdom` simulando la URL `http://localhost:3000` para dar soporte a `localStorage`. + - Importa `@testing-library/jest-dom` y ejecuta limpieza automática de DOM en `afterEach`. + - Excluye el directorio `e2e/**` (reservado para Playwright). + +### 6. `playwright.config.ts` + +- Configuración de pruebas End-to-End: + - Ejecuta los tests contra la compilación real de producción (`npm run build && npm run start`). + - Utiliza navegador Chromium y servidor local en puerto 3000. diff --git a/docs/folder-structure.md b/docs/folder-structure.md new file mode 100644 index 0000000..e3fe76c --- /dev/null +++ b/docs/folder-structure.md @@ -0,0 +1,106 @@ +# Estructura de Carpetas y Responsabilidades + +Este documento proporciona una guía completa de la organización física de archivos en el repositorio de **Pulso**, explicando la responsabilidad de cada carpeta y las convenciones del proyecto. + +--- + +## 🌳 Árbol Completo del Proyecto + +``` +pulso/ +├── .claude/ # Configuraciones locales de herramientas AI +├── .github/ # Workflows de CI/CD (GitHub Actions) +├── .husky/ # Git Hooks (pre-commit, lint-staged) +├── app/ # Rutas y páginas de Next.js (App Router) +│ ├── api/ # Route Handlers de la API interna +│ │ └── indicadores/ # Endpoints /api/indicadores y /api/indicadores/[codigo]/[anio] +│ ├── dev/ # Entorno de desarrollo aislado +│ │ └── ui/ # Showcase / Playground de componentes UI +│ ├── error.tsx # Error Boundary global de la aplicación +│ ├── favicon.ico # Favicon del sitio +│ ├── globals.css # Estilos globales y tokens CSS de Tailwind v4 +│ ├── layout.tsx # Root Layout (Fuentes, Analytics, HTML wrapper) +│ ├── loading.tsx # UI de carga inicial (Skeleton fallback) +│ ├── not-found.tsx # Página 404 personalizada +│ ├── opengraph-image.tsx # Generación dinámica de imagen OpenGraph (@vercel/og) +│ ├── page.tsx # Server Component principal de la Home Page +│ ├── robots.ts # Generador de robots.txt +│ └── sitemap.ts # Generador de sitemap.xml +├── components/ # Componentes React de UI reutilizables +│ ├── Button.tsx # Botón estándar reutilizable con variantes +│ ├── Converter.tsx # Herramienta de conversión de divisas e indicadores +│ ├── Converter.test.tsx # Tests unitarios del conversor +│ ├── DashboardHome.tsx # Dashboard principal (Client Component) +│ ├── FavoritesToggle.tsx # Botón tipo estrella para favoritos +│ ├── HistoryChart.tsx # Gráfico de líneas (Chart.js / react-chartjs-2) +│ ├── IndicatorCard.tsx # Tarjeta individual de indicador +│ ├── IndicatorCard.test.tsx # Tests unitarios de IndicatorCard +│ ├── Skeleton.tsx # Loader genérico tipo esqueleto con animación +│ ├── Spinner.tsx # Indicador de carga animado tipo spinner +│ └── VariationBadge.tsx # Badge visual de variaciones porcentuales (↑ / ↓) +├── docs/ # Documentación técnica completa del proyecto +│ ├── code/ # Documentación granular de cada archivo por carpeta +│ └── *.md # Arquitectura, servicios, componentes, etc. +├── e2e/ # Pruebas End-to-End con Playwright +│ ├── dashboard.spec.ts # Tests E2E de interacción en el dashboard +│ └── mocks.ts # Mocks de red para simular respuestas de API +├── hooks/ # Custom Hooks de React +│ ├── useFavoritos.ts # Hook de sincronización de favoritos (localStorage) +│ ├── useFavoritos.test.tsx # Tests unitarios de useFavoritos +│ ├── useIndicadores.ts # Hook de carga de snapshot vía SWR +│ ├── useIndicadores.test.tsx# Tests unitarios de useIndicadores +│ ├── useIndicadorHistory.ts # Hook de carga de series históricas multianuales +│ └── useIndicadorHistory.test.tsx # Tests unitarios de useIndicadorHistory +├── lib/ # Utilidades backend, clientes HTTP y lógica de negocio +│ ├── bcentral-client.ts # Cliente HTTP del Banco Central (SI3 SieteRestWS) +│ ├── bcentral-client.test.ts# Tests unitarios del cliente del Banco Central +│ ├── format.ts # Formateadores numéricos y de fechas es-CL +│ └── indicadores-snapshot.ts# Motor de resiliencia y caché de snapshots +├── public/ # Archivos estáticos públicos (imágenes, fuentes, etc.) +├── types/ # Definiciones e interfaces TypeScript +│ └── indicador.ts # Modelos de datos del dominio +├── AGENTS.md # Reglas del entorno para agentes de IA +├── eslint.config.mjs # Configuración de ESLint v9 (Flat Config) +├── next.config.ts # Configuración de Next.js +├── package.json # Dependencias y scripts del proyecto +├── playwright.config.ts # Configuración de Playwright E2E +├── postcss.config.mjs # Configuración de PostCSS / TailwindCSS v4 +├── proxy.ts # Middleware Dev Proxy para bloqueo de /dev/ui en prod +├── tsconfig.json # Configuración del compilador TypeScript +├── vitest.config.ts # Configuración del test runner Vitest +└── vitest-setup.ts # Script de inicialización de entornos de prueba Vitest +``` + +--- + +## 🏢 Responsabilidades por Carpeta + +### 1. `app/` (Next.js App Router) + +- **Responsabilidad**: Enrutamiento, layouts, metadatos SEO, renderizado en servidor (SSR) y endpoints de API internos. +- **Interacciones**: Consume la capa `lib/` para obtener datos e hidrata los Client Components en `components/`. +- **Convenciones**: Uso de Server Components por defecto, optando por `'use client'` únicamente cuando se requiere interactividad o estado. + +### 2. `components/` (UI Components) + +- **Responsabilidad**: Presentación visual e interacción con el usuario. +- **Interacciones**: Consumen hooks de `hooks/`, utilidades de `lib/format.ts` y tipos de `types/indicador.ts`. +- **Convenciones**: Componentes funcionales orientados a accesibilidad, con soporte de eventos de teclado y estilos expresados mediante utilidades CSS de Tailwind v4. + +### 3. `hooks/` (Custom React Hooks) + +- **Responsabilidad**: Encapsular estado del cliente, efectos secundarios y lógica de llamadas de datos reactivas. +- **Interacciones**: Utilizan `useSWR` para caché de datos remotos y `useSyncExternalStore` para almacenamiento local (`localStorage`). + +### 4. `lib/` (Core Business Logic & External API Clients) + +- **Responsabilidad**: Comunicación directa con APIs externas, transformación de formatos de datos, decodificación de caracteres y gestión de caché en memoria volatil. +- **Interacciones**: Es la única capa que interactúa con el mundo exterior (Banco Central de Chile) y no posee dependencias hacia componentes de UI o hooks. + +### 5. `types/` (TypeScript Definitions) + +- **Responsabilidad**: Definición de contratos de tipos e interfaces inmutables compartidas a través de toda la aplicación. + +### 6. `e2e/` (Pruebas de Integración End-to-End) + +- **Responsabilidad**: Pruebas automáticas basadas en Playwright contra el servidor en construcción de producción (`npm run build && npm run start`). diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..90412d7 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,34 @@ +# Glosario de Términos + +Este glosario define los términos del dominio económico chileno y los conceptos técnicos propios de la arquitectura de **Pulso**. + +--- + +## 🇨🇱 Términos Económicos del Dominio + +| Término | Significado / Descripción | +| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **UF (Unidad de Fomento)** | Unidad de cuenta reajustable no monetaria utilizada en Chile para contratos financieros, préstamos hipotecarios y previsión. Su valor se reajusta diariamente según el IPC. | +| **IVP (Índice de Valor Promedio)** | Índice de reajustabilidad diario derivado de la tasa de inflación expresado en pesos chilenos. | +| **Dólar Observado** | Tipo de cambio promedio ponderado de las operaciones de compra y venta de dólares estadounidenses realizadas por los bancos comerciales en Chile. | +| **Euro** | Cotización de la moneda oficial de la Eurozona expresada en Pesos Chilenos (CLP). | +| **IPC (Índice de Precios al Consumidor)** | Indicador mensual emitido por el Instituto Nacional de Estadísticas (INE) que mide la variación media de los precios de una canasta de bienes y servicios. | +| **UTM (Unidad Tributaria Mensual)** | Unidad económica utilizada en Chile para efectos tributarios, multas y pagos de derechos de aduana. Se reajusta mensualmente. | +| **Imacec (Índice Mensual de Actividad Económica)** | Estimación que resume la actividad de los distintos sectores de la economía chilena en un mes determinado. Mapea la evolución del PIB. | +| **TPM (Tasa de Política Monetaria)** | Tasa de interés de referencia fijada por el Consejo del Banco Central de Chile para gestionar la liquidez y la inflación. | +| **Libra de Cobre** | Precio internacional del cobre refinado cotizado en la Bolsa de Metales de Londres (BML), medido en dólares por libra. Es la principal exportación de Chile. | +| **Tasa de Desempleo** | Porcentaje de la fuerza de trabajo chilena que se encuentra desocupada durante un período determinado (fuente INE). | + +--- + +## 💻 Términos Técnicos de Arquitectura + +| Término | Significado / Descripción | +| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **SI3 / SieteRestWS** | Nombre del servicio web RESTful expuesto oficialmente por el Banco Central de Chile para la consulta programática de series estadísticas. | +| **GetSeries** | Nombre de la función remota de la API del Banco Central utilizada para extraer observaciones históricas o actuales de una serie temporal. | +| **App Router** | Sistema de enrutamiento basado en carpetas introducido en Next.js (directorio `/app`) que utiliza Server Components por defecto. | +| **ISR (Incremental Static Regeneration)** | Patrón de Next.js que permite actualizar páginas estáticas en segundo plano en intervalos definidos (`revalidate`) sin reconstruir todo el sitio. | +| **SWR (Stale-While-Revalidate)** | Estrategia de caché que devuelve primero los datos cacheados (stale), envía la petición de revalidación en segundo plano y finalmente actualiza el estado. | +| **Latin-1 (ISO-8859-1)** | Estándar de codificación de caracteres de 8 bits para lenguajes occidentales. Utilizado por la API del Banco Central de Chile. | +| **Fallback por Indicador** | Mecanismo de resiliencia de Pulso que evita fallar globalmente cuando 1 de las 10 peticiones concurrentes al Banco Central falla, utilizando el último valor conocido. | diff --git a/docs/hooks.md b/docs/hooks.md new file mode 100644 index 0000000..dd5059d --- /dev/null +++ b/docs/hooks.md @@ -0,0 +1,108 @@ +# Custom React Hooks + +Este documento especifica la implementación y comportamiento de los custom hooks desarrollados para **Pulso**. + +--- + +## ⚓ `useIndicadores` + +- **Archivo**: `hooks/useIndicadores.ts` +- **Propósito**: Consumir la fotografía actual de todos los indicadores desde el endpoint `/api/indicadores` con soporte de caché reactivo y deduplicación. + +### Firma: + +```typescript +export function useIndicadores(): { + data: IndicadoresSnapshot | undefined; + isLoading: boolean; + isValidating: boolean; + error: Error | undefined; +}; +``` + +### Configuración SWR: + +- **Endpoint Key**: `ENDPOINT_INDICADORES = '/api/indicadores'` +- **`revalidateOnFocus`**: `true` (Revalida automáticamente cuando el usuario regresa a la pestaña). +- **`dedupingInterval`**: `60_000` ms (Evita peticiones duplicadas durante 1 minuto). + +### Flujo Interno: + +1. Invoca `useSWR(ENDPOINT_INDICADORES, fetcher)`. +2. El `fetcher` realiza un `fetch('/api/indicadores')` y valida `response.ok`. Si el servidor responde con status de error (ej: 502), extrae el JSON de error y lanza una excepción. +3. Retorna `{ data, isLoading, isValidating, error }`. + +--- + +## ⚓ `useIndicadorHistory` + +- **Archivo**: `hooks/useIndicadorHistory.ts` +- **Propósito**: Cargar y consolidar la serie histórica de un indicador a lo largo de un rango de hasta 3 años calendario. + +### Firma: + +```typescript +export function useIndicadorHistory( + codigo: IndicadorCodigo, + fechaAncla: Date, +): { + data: SerieHistoricaPunto[] | undefined; + isLoading: boolean; + isValidating: boolean; + error: Error | undefined; +}; +``` + +### Por qué existe la carga multianual: + +El selector de historial de la UI permite ver hasta 24 meses hacia atrás (`2A`). Un rango de 24 meses a contar de la `fechaAncla` (ej: Enero 2026) abarca 3 años calendario diferentes (2026, 2025 y 2024). Puesto que la API interna expone datos por año (`/api/indicadores/[codigo]/[anio]`), el hook consulta concurrentemente el año de la fecha ancla y los 2 años anteriores (`ANIOS_HACIA_ATRAS = 2`). + +### Flujo Interno: + +```mermaid +flowchart TD + A[Inicio: useIndicadorHistory] --> B[Obtener año de fechaAncla] + B --> C[Generar arreglo de 3 años: anio, anio-1, anio-2] + C --> D[Promise.all con fetchSerieAnioSeguro] + D --> E{¿Al menos 1 año trajo datos?} + E -- No --> F[Lanzar Error: No se pudo obtener el histórico] + E -- Sí --> G[Aplanar arreglos con .flat] + G --> H[Ordenar descendentemente por fecha] + H --> I[Retornar serie consolidada en data] +``` + +### Tolerancia a Fallos Interna (`fetchSerieAnioSeguro`): + +Si la petición para un año específico falla (por ejemplo, el indicador no existía en 1970 o hubo un error puntual), `fetchSerieAnioSeguro` captura el error silenciosamente y retorna un arreglo vacío `[]` para no cancelar las respuestas válidas de los otros años. + +--- + +## ⚓ `useFavoritos` + +- **Archivo**: `hooks/useFavoritos.ts` +- **Propósito**: Gestionar la lista de indicadores marcados como favoritos por el usuario, manteniéndola persistida en `localStorage` y sincronizada en tiempo real entre múltiples pestañas del navegador. + +### Firma: + +```typescript +export function useFavoritos(): { + favoritos: IndicadorCodigo[]; + toggleFavorito: (codigo: IndicadorCodigo) => void; + esFavorito: (codigo: IndicadorCodigo) => boolean; +}; +``` + +### Por qué usa `useSyncExternalStore`: + +El uso tradicional de `localStorage` mediante `useState` y `useEffect` causa problemas de **Hydration Mismatch** en Next.js (el servidor renderiza HTML sin favoritos, y el cliente re-renderiza tras la hidratación causando un salto visual). + +Al utilizar `useSyncExternalStore`: + +1. **Server Snapshot (`getServerSnapshot`)**: Devuelve un arreglo vacío constante (`[]`) durante el SSR. +2. **Client Snapshot (`getSnapshot`)**: Lee de un caché en memoria respaldado por `localStorage`. +3. **Suscripción (`subscribe`)**: Escucha eventos nativos `storage` del objeto `window`. Si el usuario marca un favorito en una pestaña, todas las demás pestañas abiertas actualizan su interfaz instantáneamente. + +### Métodos Exportados: + +- **`toggleFavorito(codigo)`**: Agrega el código si no existe, o lo remueve si ya estaba presente, actualizando el almacenamiento y notificando a los suscriptores. +- **`esFavorito(codigo)`**: Función memorizada con `useCallback` que retorna un booleano indicando si el código está en la lista. diff --git a/docs/migracion-banco-central.md b/docs/migracion-banco-central.md index a987841..8311417 100644 --- a/docs/migracion-banco-central.md +++ b/docs/migracion-banco-central.md @@ -31,18 +31,18 @@ El usuario aportó `series.xlsx` — el catálogo completo de series públicas d ## Mapeo confirmado: código app → código Banco Central -| Código app | Nombre mostrado | Código BC | Nombre serie (BC) | Cuadro (BC) | Frecuencia | -|---|---|---|---|---|---| -| `uf` | UF | `F073.UFF.PRE.Z.D` | Unidad de fomento (UF) | Indicadores de reajustabilidad diario | Diaria | -| `ivp` | IVP | `F073.IVP.PRE.Z.D` | Índice de valor promedio (IVP) | Indicadores de reajustabilidad diario | Diaria | -| `dolar` | Dólar observado | `F073.TCO.PRE.Z.D` | Dólar observado | Tipo de cambio | Diaria hábil | -| `euro` | Euro | `F072.CLP.EUR.N.O.D` | Euro (Eurozona) | Tipo de cambio nominal distintas monedas (CLP por unidad de moneda extranjera) | Diaria hábil | -| `ipc` | IPC | `F074.IPC.VAR.Z.Z.C.M` | IPC General | IPC, variación mensual, información histórica (%) | Mensual | -| `utm` | UTM | `F073.UTR.PRE.Z.M` | Unidad tributaria mensual (UTM) | Indicadores de reajustabilidad | Mensual | -| `imacec` | Imacec | `F032.IMC.V12.Z.Z.2018.Z.Z.0.M` | Imacec | Indicador mensual de actividad económica, contribución año/año, referencia 2018 (%) | Mensual | -| `tpm` | TPM | `F022.TPM.TIN.D001.NO.Z.D` | Tasa de política monetaria (TPM) | Tasas de interés de referencia de la política monetaria | Diaria (vigente hasta próximo cambio de la política) | -| `libra_cobre` | Libra de cobre | `F019.PPB.PRE.100.D` | Cobre refinado BML (USD/libra) | Precios de productos básicos | Diaria | -| `tasa_desempleo` | Tasa de desempleo | `F049.DES.TAS.INE9.10.M` | Tasa de desocupación nacional (INE) | Tasas de desocupación, nacional y por región, INE (%) | Mensual | +| Código app | Nombre mostrado | Código BC | Nombre serie (BC) | Cuadro (BC) | Frecuencia | +| ---------------- | ----------------- | ------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------- | +| `uf` | UF | `F073.UFF.PRE.Z.D` | Unidad de fomento (UF) | Indicadores de reajustabilidad diario | Diaria | +| `ivp` | IVP | `F073.IVP.PRE.Z.D` | Índice de valor promedio (IVP) | Indicadores de reajustabilidad diario | Diaria | +| `dolar` | Dólar observado | `F073.TCO.PRE.Z.D` | Dólar observado | Tipo de cambio | Diaria hábil | +| `euro` | Euro | `F072.CLP.EUR.N.O.D` | Euro (Eurozona) | Tipo de cambio nominal distintas monedas (CLP por unidad de moneda extranjera) | Diaria hábil | +| `ipc` | IPC | `F074.IPC.VAR.Z.Z.C.M` | IPC General | IPC, variación mensual, información histórica (%) | Mensual | +| `utm` | UTM | `F073.UTR.PRE.Z.M` | Unidad tributaria mensual (UTM) | Indicadores de reajustabilidad | Mensual | +| `imacec` | Imacec | `F032.IMC.V12.Z.Z.2018.Z.Z.0.M` | Imacec | Indicador mensual de actividad económica, contribución año/año, referencia 2018 (%) | Mensual | +| `tpm` | TPM | `F022.TPM.TIN.D001.NO.Z.D` | Tasa de política monetaria (TPM) | Tasas de interés de referencia de la política monetaria | Diaria (vigente hasta próximo cambio de la política) | +| `libra_cobre` | Libra de cobre | `F019.PPB.PRE.100.D` | Cobre refinado BML (USD/libra) | Precios de productos básicos | Diaria | +| `tasa_desempleo` | Tasa de desempleo | `F049.DES.TAS.INE9.10.M` | Tasa de desocupación nacional (INE) | Tasas de desocupación, nacional y por región, INE (%) | Mensual | 10 de los 12 códigos actuales tienen equivalente confirmado en el catálogo del Banco Central. @@ -50,10 +50,10 @@ El usuario aportó `series.xlsx` — el catálogo completo de series públicas d ## Indicadores a eliminar -| Código app | Motivo | -|---|---| -| `bitcoin` | **No existe** en el catálogo del Banco Central (0 coincidencias buscando "bitcoin"/"cripto" en 30.867 series) — el Banco Central no publica precios de criptoactivos. Se elimina de `INDICADOR_CODIGOS`, tipos, UI y tests. | -| `dolar_intercambio` | Ya estaba descontinuado en mindicador.cl desde 2014-11-13 (ver memoria `mindicador_cadencias`). No se evaluó contra el catálogo de BC porque de todas formas no aporta valor — se elimina también. | +| Código app | Motivo | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `bitcoin` | **No existe** en el catálogo del Banco Central (0 coincidencias buscando "bitcoin"/"cripto" en 30.867 series) — el Banco Central no publica precios de criptoactivos. Se elimina de `INDICADOR_CODIGOS`, tipos, UI y tests. | +| `dolar_intercambio` | Ya estaba descontinuado en mindicador.cl desde 2014-11-13 (ver memoria `mindicador_cadencias`). No se evaluó contra el catálogo de BC porque de todas formas no aporta valor — se elimina también. | ## Shape real de la respuesta (confirmado 2026-07-27, `GetSeries` sobre `uf`) @@ -204,20 +204,20 @@ Esto está directamente relacionado con la "Decisión de diseño pendiente" de l ### Archivos con la palabra "mindicador" en sí (branding, docs, tests) — scope más amplio, confirmado por grep -| Archivo | Qué contiene | -|---|---| -| `README.md` | 6 menciones — descripción del proyecto, instrucciones de setup, tabla de arquitectura, sección "Particularidades de los datos de mindicador.cl" | -| `app/layout.tsx` | Título del sitio: `"Dashboard mindicador.cl"` | -| `app/page.tsx` | Título de metadata: `"Dashboard mindicador.cl — Vista general"` | -| `components/DashboardHome.tsx` | Texto visible en la UI: `"mindicador.cl"` | -| `lib/mindicador-client.ts` | El cliente entero (`MindicadorApiError`, `BASE_URL`, mensajes de error) — se reemplaza completo por el cliente de SI3 | -| `app/api/indicadores/route.ts` | Import de `getSnapshot` + mensaje de error `"...consultar mindicador.cl"` | -| `app/api/indicadores/[codigo]/[anio]/route.ts` | Import de `getHistorico` + mismo mensaje de error | -| `app/api/indicadores/route.test.ts` | Fixture con `autor: 'mindicador.cl'` | -| `hooks/useIndicadores.test.tsx` | Fixture + mensajes de error de test | -| `hooks/useIndicadorHistory.test.tsx` | Mensaje de error de test | -| `e2e/mocks.ts` | Función `mockMindicadorApi()`, fixture `autor: 'mindicador.cl'` | -| `e2e/dashboard.spec.ts` | Import y uso de `mockMindicadorApi` | +| Archivo | Qué contiene | +| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `README.md` | 6 menciones — descripción del proyecto, instrucciones de setup, tabla de arquitectura, sección "Particularidades de los datos de mindicador.cl" | +| `app/layout.tsx` | Título del sitio: `"Dashboard mindicador.cl"` | +| `app/page.tsx` | Título de metadata: `"Dashboard mindicador.cl — Vista general"` | +| `components/DashboardHome.tsx` | Texto visible en la UI: `"mindicador.cl"` | +| `lib/mindicador-client.ts` | El cliente entero (`MindicadorApiError`, `BASE_URL`, mensajes de error) — se reemplaza completo por el cliente de SI3 | +| `app/api/indicadores/route.ts` | Import de `getSnapshot` + mensaje de error `"...consultar mindicador.cl"` | +| `app/api/indicadores/[codigo]/[anio]/route.ts` | Import de `getHistorico` + mismo mensaje de error | +| `app/api/indicadores/route.test.ts` | Fixture con `autor: 'mindicador.cl'` | +| `hooks/useIndicadores.test.tsx` | Fixture + mensajes de error de test | +| `hooks/useIndicadorHistory.test.tsx` | Mensaje de error de test | +| `e2e/mocks.ts` | Función `mockMindicadorApi()`, fixture `autor: 'mindicador.cl'` | +| `e2e/dashboard.spec.ts` | Import y uso de `mockMindicadorApi` | Nuevo con la migración (no es solo borrar texto): reemplazo completo de `lib/mindicador-client.ts` por un cliente equivalente para SI3, y un adaptador que traduzca la respuesta de `GetSeries` (`Series`/`SeriesInfos`) al shape actual (`Indicador`, `IndicadoresSnapshot`, `SerieHistorica`) para no tener que tocar los componentes downstream. @@ -228,7 +228,7 @@ Nuevo con la migración (no es solo borrar texto): reemplazo completo de `lib/mi **Decidido:** el snapshot usa **fallback por indicador**, no por snapshot completo. - El caché deja de ser un `IndicadoresSnapshot` único que se reemplaza atómicamente, y pasa a ser un valor cacheado **por cada uno de los 10 códigos**. -- En cada refresh se disparan las 10 llamadas a `GetSeries` en paralelo (ya confirmado seguro y rápido, ~0,2s — ver sección de rate limits). Cada llamada que responde bien actualiza *solo ese* valor en el caché; cada una que falla deja el valor cacheado anterior de *ese* indicador, sin tocar el resto. +- En cada refresh se disparan las 10 llamadas a `GetSeries` en paralelo (ya confirmado seguro y rápido, ~0,2s — ver sección de rate limits). Cada llamada que responde bien actualiza _solo ese_ valor en el caché; cada una que falla deja el valor cacheado anterior de _ese_ indicador, sin tocar el resto. - El snapshot servido es "lo mejor disponible por indicador en ese momento" — mezcla de datos frescos con, ocasionalmente, algún valor stale puntual, en vez de todo-fresco-o-todo-stale. - **Falla total** (los 10 fallan, ej. Banco Central caído): mismo comportamiento que hoy — se sirve el último snapshot completo bueno en caché, o error si nunca hubo uno (arranque en frío). diff --git a/docs/patterns.md b/docs/patterns.md new file mode 100644 index 0000000..14ebb9b --- /dev/null +++ b/docs/patterns.md @@ -0,0 +1,43 @@ +# Patrones de Diseño Identificados + +Este documento describe los patrones de diseño de software y arquitectura detectados y aplicados en el código fuente de **Pulso**. + +--- + +## 📐 1. Patrón Adaptador (Client Adapter Pattern) + +- **Ubicación**: `lib/bcentral-client.ts` +- **Problema**: La API del Banco Central de Chile devuelve objetos complejos con nombres de propiedades en español/inglés (`Series.Obs[].indexDateString`, `value` en string, `statusCode`, etc.) y codificación legacy `ISO-8859-1`. Los componentes de la interfaz de usuario de Pulso esperan un contrato estandarizado (`Indicador`, `SerieHistorica`). +- **Solución**: `bcentral-client.ts` actúa como un adaptador que traduce la estructura interna de la API externa hacia los modelos del dominio de Pulso, abstrayendo a los componentes React de los cambios en el proveedor externo. + +--- + +## 🛡️ 2. Patrón de Caché de Resiliencia con Fallback (Resilient Fallback Engine) + +- **Ubicación**: `lib/indicadores-snapshot.ts` +- **Problema**: Con 10 llamadas independientes al servidor del Banco Central, la probabilidad de que 1 llamada falle debido a un parpadeo de red es mayor. Descartar todo el snapshot por 1 error sería perjudicial para la experiencia de usuario. +- **Solución**: Se implementó una estrategia donde cada indicador se consulta de forma aislada y guarda su valor exitoso en un `Map` compartido en memoria. En caso de fallo en una serie puntual, el sistema aplica un fallback sirviendo el último valor bueno conocido de ese indicador específico. + +--- + +## 👁️ 3. Patrón Observador de Almacenamiento Externo (External Store Observer) + +- **Ubicación**: `hooks/useFavoritos.ts` +- **Problema**: La sincronización de favoritos mediante `localStorage` suele producir errores de hidratación en Next.js App Router si se intenta leer del navegador durante el renderizado inicial en el servidor. +- **Solución**: Se aplica el patrón Observer utilizando la API nativa de React 19 `useSyncExternalStore`. El hook se suscribe a los cambios del `StorageEvent` en el objeto `window` y notifica a los componentes suscriptores para que se actualicen en tiempo real tanto dentro de la misma pestaña como en otras pestañas abiertas. + +--- + +## ⚡ 4. Patrón de Hidratación Estática SWR (SSR SWR Hydration) + +- **Ubicación**: `app/page.tsx` y `hooks/useIndicadores.ts` +- **Problema**: Los sitios que cargan datos del cliente frecuentemente muestran esqueletos de carga visuales al iniciar, seguidos de un salto de contenido (Layout Shift). +- **Solución**: El Server Component invoca la lógica de snapshot en el servidor y la inyecta mediante ``. El cliente inicia con los datos pre-cargados sin estados de carga intermedios. + +--- + +## 🔒 5. Patrón Proxy Guard (Security Middleware) + +- **Ubicación**: `proxy.ts` +- **Problema**: La ruta de pruebas UI `/dev/ui` debe estar deshabilitada en el entorno de producción. +- **Solución**: Un middleware ligero intercepta las peticiones coincidentes con la ruta `/dev/ui` y evalúa `NODE_ENV`. Si es producción, retorna un código HTTP `404 Not Found` cortando la cadena de procesamiento de inmediato. diff --git a/docs/project-overview.md b/docs/project-overview.md new file mode 100644 index 0000000..5a85414 --- /dev/null +++ b/docs/project-overview.md @@ -0,0 +1,54 @@ +# Visión General del Proyecto y Objetivos + +**Pulso** es una aplicación web moderna orientada al mercado chileno que ofrece un panel de control en tiempo real para el seguimiento de indicadores económicos clave: **Unidad de Fomento (UF)**, **Dólar Observado**, **Euro**, **IPC**, **UTM**, **Imacec**, **Tasa de Política Monetaria (TPM)**, **Libra de Cobre**, **IVP** y **Tasa de Desempleo**. + +--- + +## 🎯 Objetivos de Producto + +1. **Información Macroeconómica Accesible**: Proporcionar a ciudadanos, profesionales y empresas una plataforma rápida, clara y sin distracciones para consultar los valores oficiales publicados por el Banco Central de Chile. +2. **Resiliencia Operativa**: Garantizar una disponibilidad del 99.9% frente a interrupciones externas mediante cachés en memoria y estrategias de degradación elegante (_graceful degradation_). +3. **Conversión y Herramientas Útiles**: Incluir herramientas de cálculo financiero rápido (conversor CLP ⇄ Indicadores) y visualización de series históricas de hasta 2 años. +4. **Experiencia de Usuario Inmediata**: Eliminar latencias percibidas mediante renderizado estático en el servidor (SSR/ISR) e hidratación transparente con SWR en el cliente. + +--- + +## 🚀 Requerimientos No Funcionales + +### 1. Rendimiento y Carga Útil + +- **First Contentful Paint (FCP)** < 1.0s. +- **Time to Interactive (TTI)** < 1.5s. +- Rendimiento de 100/100 en auditorías de Google Lighthouse. +- Los gráficos se renderizan mediante Canvas (`chart.js`) aprovechando aceleración por hardware. + +### 2. SEO y Metadatos + +- Etiquetas Metadata de Next.js configuradas dinámicamente. +- OpenGraph e imágenes pre-generadas mediante `@vercel/og` (`app/opengraph-image.tsx`). +- Inclusión de Sitemap XML estandarizado (`app/sitemap.ts`) y directivas para motores de búsqueda (`app/robots.ts`). + +### 3. Accesibilidad (a11y) + +- Cumplimiento de estándares WCAG 2.1 Nivel AA. +- Soporte completo para navegación por teclado (atributos `tabIndex`, `onKeyDown`, `aria-pressed`, `aria-label`). +- Utilización de fuentes tipográficas legibles con buen contraste sobre fondo oscuro (Dark Mode nativo). + +--- + +## 📊 Lista de Indicadores Soportados + +| Indicador | Nombre Oficial Banco Central | Código Interno | Unidad de Medida | Frecuencia | +| ------------------ | ------------------------------------- | ---------------- | ---------------- | ------------------------ | +| **UF** | Unidad de fomento (UF) | `uf` | Pesos | Diaria | +| **IVP** | Índice de valor promedio (IVP) | `ivp` | Pesos | Diaria | +| **Dólar** | Dólar observado | `dolar` | Pesos | Diaria hábil | +| **Euro** | Euro | `euro` | Pesos | Diaria hábil | +| **IPC** | Índice de Precios al Consumidor (IPC) | `ipc` | Porcentaje | Mensual | +| **UTM** | Unidad Tributaria Mensual (UTM) | `utm` | Pesos | Mensual | +| **Imacec** | Imacec | `imacec` | Porcentaje | Mensual | +| **TPM** | Tasa de Política Monetaria (TPM) | `tpm` | Porcentaje | Diaria / Cambio Política | +| **Libra de Cobre** | Libra de cobre | `libra_cobre` | Dólar | Diaria | +| **Tasa Desempleo** | Tasa de desempleo | `tasa_desempleo` | Porcentaje | Mensual | + +_Nota: Los indicadores como Bitcoin o Dólar Intercambio fueron excluidos formalmente por no formar parte del catálogo de series oficiales publicadas por el Banco Central de Chile._ diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..efae569 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,42 @@ +# Roadmap Técnico y Futuras Mejoras + +Este documento presenta una hoja de ruta con propuestas de evolución técnica y nuevas funcionalidades sugeridas para **Pulso**. + +--- + +## 🗺️ Roadmap de Evolución + +```mermaid +timeline + title Hoja de Ruta de Desarrollo - Pulso + section Corto Plazo (Q3) + Badge Staleness UI : Indicador visual en tarjetas cuando un dato sea stale + Soporte Formato USD : Mejorar formato de Libra de Cobre + section Mediano Plazo (Q4) + Decimación de Datos : Plugin de downsampling para Chart.js + Rango de 5 Años : Ampliar el selector de historial + section Largo Plazo (Q1-Q2) + Alertas y Notificaciones : PWA Web Push notifications para variaciones de UF + Exportación CSV/JSON : Descarga de datos históricos para analistas +``` + +--- + +## 🚀 Propuestas Detalladas + +### 1. Distinción Visual de Datos Stale/Cacheados (Corto Plazo) + +- **Objetivo**: Si un indicador específico falla en la API del Banco Central y se sirve el valor de fallback del caché, agregar una insignia visual discreta (ej: badge "Dato en caché") en la `IndicatorCard` para brindar transparencia al usuario. + +### 2. Formato Multimoneda Explícito (Corto Plazo) + +- **Objetivo**: Modificar `lib/format.ts` para que `formatValorPorUnidad` soporte formatear de manera nativa la unidad de medida `'Dolar'` (para la Libra de Cobre) utilizando `Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })`. + +### 3. Ampliación del Selector de Historial a 5 Años (`5A`) (Mediano Plazo) + +- **Objetivo**: Permitir a los usuarios analizar tendencias macroeconómicas de largo plazo. +- **Requerimiento Técnico**: Implementar reducción de puntos en el servidor o cliente mediante `chartjs-plugin-decimation` para mantener la fluidez del gráfico sin sobrecargar la memoria del navegador. + +### 4. Modo PWA y Notificaciones (Largo Plazo) + +- **Objetivo**: Convertir Pulso en una Progressive Web App (PWA) instalable en teléfonos móviles y escritorios, añadiendo notificaciones Push cuando la UF sufra reajustes o el Dólar supere umbrales configurables. diff --git a/docs/routes.md b/docs/routes.md new file mode 100644 index 0000000..1794b01 --- /dev/null +++ b/docs/routes.md @@ -0,0 +1,144 @@ +# Rutas y Enrutamiento (Next.js App Router) + +Este documento detalla todas las rutas de páginas web y endpoints de API expuestos por la aplicación **Pulso**, junto con su comportamiento de renderizado, parámetros, headers y middlewares asociados. + +--- + +## 🌐 Páginas Públicas y de Desarrollo + +### 1. Home Page (`/`) + +- **Archivo**: `app/page.tsx` +- **Tipo de Renderizado**: Server Component con Server-Side Rendering (SSR) e hidratación SWR. +- **Propósito**: Vista principal del dashboard de indicadores económicos. +- **Flujo de Carga**: + 1. El servidor invoca `obtenerSnapshot()` de `lib/indicadores-snapshot.ts`. + 2. Construye el árbol HTML inicial y lo envuelve en un proveedor ``. + 3. Renderiza el Client Component ``. + 4. En el navegador, SWR hidrata los datos inmediatamente desde la propiedad `fallback` sin mostrar esqueletos de carga. + +### 2. UI Showcase / Playground (`/dev/ui`) + +- **Archivo**: `app/dev/ui/page.tsx` +- **Tipo de Renderizado**: Dynamic Server Component (`export const dynamic = 'force-dynamic'`). +- **Acceso**: Únicamente en entorno de desarrollo (`process.env.NODE_ENV !== 'production'`). +- **Protección**: + - Middleware Guard (`proxy.ts`): Intercepta la ruta en producción y retorna `404 Not Found`. + - In-page Guard: Ejecuta `notFound()` si `NODE_ENV === 'production'`. +- **Propósito**: Proporcionar un catálogo visual aislado para probar componentes como `Button`, `VariationBadge`, `Skeleton`, `IndicatorCard`, `HistoryChart` y `Converter`. + +### 3. Error Boundary Global + +- **Archivo**: `app/error.tsx` +- **Tipo**: Client Component (`'use client'`). +- **Propósito**: Capturar errores no manejados en el renderizado de cualquier subárbol de componentes. +- **Interfaz**: Muestra una tarjeta con mensaje de error, código de digest (si existe) y un botón "Reintentar" que ejecuta la función `unstable_retry()`. + +### 4. UI de Carga Global (`/loading`) + +- **Archivo**: `app/loading.tsx` +- **Propósito**: Fallback de visualización nativo de React Suspense durante la transición o carga de páginas Server Components. Muestra la estructura con bloques `Skeleton`. + +### 5. Página 404 (`/not-found`) + +- **Archivo**: `app/not-found.tsx` +- **Propósito**: Renderizado elegante cuando un usuario intenta acceder a una ruta inexistente. Incluye un botón para volver al inicio (`/`). + +--- + +## 🔌 API Route Handlers (`/api/`) + +### 1. GET `/api/indicadores` + +- **Archivo**: `app/api/indicadores/route.ts` +- **Estrategia de Carga**: `export const dynamic = 'force-static'`, `export const revalidate = 300` (5 minutos). +- **Propósito**: Retornar el snapshot actual de los 10 indicadores económicos. +- **Respuesta de Éxito (HTTP 200)**: + +```json +{ + "version": "2.0", + "autor": "Banco Central de Chile", + "fecha": "2026-07-27T21:19:29.000Z", + "uf": { + "codigo": "uf", + "nombre": "Unidad de fomento (UF)", + "unidad_medida": "Pesos", + "fecha": "2026-07-27T04:00:00.000Z", + "valor": 39412.87 + }, + "dolar": { + "codigo": "dolar", + "nombre": "Dólar observado", + "unidad_medida": "Pesos", + "fecha": "2026-07-25T04:00:00.000Z", + "valor": 963.12 + } +} +``` + +- **Respuesta de Error (HTTP 502 Bad Gateway)**: + +```json +{ + "error": "No se pudo obtener ningun indicador desde el Banco Central" +} +``` + +_(Ocurre si las 10 llamadas al Banco Central fallan y no existe ningún valor previo en el caché en memoria)._ + +--- + +### 2. GET `/api/indicadores/[codigo]/[anio]` + +- **Archivo**: `app/api/indicadores/[codigo]/[anio]/route.ts` +- **Estrategia de Carga**: `export const dynamic = 'force-static'`, `export const revalidate = 300`. +- **Parámetros de Ruta**: + - `codigo`: Debe ser un valor válido del tipo `IndicadorCodigo` (`uf`, `dolar`, `euro`, etc.). + - `anio`: Cadena numérica de 4 dígitos entre `1970` y el año en curso. +- **Validaciones**: + - Si `codigo` no pertenece a `INDICADOR_CODIGOS` → HTTP 400 Bad Request. + - Si `anio` no es un número de 4 dígitos dentro del rango válido → HTTP 400 Bad Request. +- **Respuesta de Éxito (HTTP 200)**: + +```json +{ + "codigo": "dolar", + "nombre": "Dolar observado", + "unidad_medida": "Pesos", + "serie": [ + { "fecha": "2026-01-02T00:00:00.000Z", "valor": 912.45 }, + { "fecha": "2026-01-05T00:00:00.000Z", "valor": 915.1 } + ] +} +``` + +- **Respuesta de Error (HTTP 502 Bad Gateway)**: + +```json +{ + "error": "Banco Central fallo para dolar: Tiempo de espera agotado al consultar la serie F073.TCO.PRE.Z.D" +} +``` + +--- + +## 📄 Archivos de Metadatos y SEO + +### 1. `app/robots.ts` + +Genera el archivo `robots.txt` del sitio: + +- Permite indexación a todos los agentes (`User-Agent: *`). +- Bloquea el acceso a `/dev/ui` y endpoints `/api/`. +- Declara la ubicación del sitemap: `https://pulso-cyan-zeta.vercel.app/sitemap.xml`. + +### 2. `app/sitemap.ts` + +Genera el archivo `sitemap.xml`: + +- Incluye la URL raíz (`https://pulso-cyan-zeta.vercel.app`) con prioridad `1.0` y frecuencia de cambio `daily`. + +### 3. `app/opengraph-image.tsx` + +Genera dinámicamente la imagen de vista previa OpenGraph (1200x630 PNG) utilizando la biblioteca `@vercel/og` (`ImageResponse`). Muestra el logotipo de Pulso y una grilla estilizada con ejemplos de los principales indicadores. diff --git a/docs/services.md b/docs/services.md new file mode 100644 index 0000000..b3a556d --- /dev/null +++ b/docs/services.md @@ -0,0 +1,105 @@ +# Servicios y Módulos de Integración (Backend & Core) + +Este documento detalla la capa de servicios e integración externa de **Pulso**, responsable de comunicarse con la API del Banco Central de Chile, gestionar el almacenamiento en memoria y formatear valores numéricos. + +--- + +## 🏛️ Cliente del Banco Central: `lib/bcentral-client.ts` + +- **Responsabilidad**: Encapsular el protocolo HTTP, autenticación, decodificación binaria y manejo de errores de la API **SieteRestWS / SI3** del Banco Central de Chile. +- **Constantes de Configuración**: + - `BASE_URL`: `'https://si3.bcentral.cl/SieteRestWS/SieteRestWS.ashx'` + - `REQUEST_TIMEOUT_MS`: `8000` (8 segundos). + - `REVALIDATE_SECONDS`: `300` (5 minutos). +- **Mapeo Inmutable de Series (`SERIES`)**: + Almacena los códigos alfanuméricos oficiales de las series del Banco Central para cada indicador: + - `uf`: `F073.UFF.PRE.Z.D` + - `ivp`: `F073.IVP.PRE.Z.D` + - `dolar`: `F073.TCO.PRE.Z.D` + - `euro`: `F072.CLP.EUR.N.O.D` + - `ipc`: `F074.IPC.VAR.Z.Z.C.M` + - `utm`: `F073.UTR.PRE.Z.M` + - `imacec`: `F032.IMC.V12.Z.Z.2018.Z.Z.0.M` + - `tpm`: `F022.TPM.TIN.D001.NO.Z.D` + - `libra_cobre`: `F019.PPB.PRE.100.D` + - `tasa_desempleo`: `F049.DES.TAS.INE9.10.M` + +### Excepción Personalizada: `BancoCentralApiError` + +Clase que extiende de `Error` incorporando atributos específicos: + +- `codigoSerie`: `string` +- `codigoRespuesta`: `number | undefined` + +### Funciones Internas y Exportadas: + +#### 1. `llamarGetSeries(codigoSerie, firstdate, lastdate)` (Privada) + +- **Flujo Interno**: + 1. Verifica existencia de variables de entorno `BCENTRAL_USER` y `BCENTRAL_PASS`. Si faltan, lanza `BancoCentralApiError`. + 2. Construye la URL con `searchParams` (`function=GetSeries`). + 3. Crea un `AbortController` con timeout de 8000ms. + 4. Realiza el `fetch` configurado con `{ next: { revalidate: 300 } }`. + 5. Obtiene el body como `ArrayBuffer` crudo. + 6. **Decodificación ISO-8859-1**: `new TextDecoder('iso-8859-1').decode(buffer)` para preservar tildes y caracteres en español. + 7. Parsea el JSON y valida `data.Codigo === 0`. Si es distinto de cero, lanza `BancoCentralApiError`. + +#### 2. `getSerieHistorica(codigo, firstdate, lastdate)` (Pública) + +- **Propósito**: Consultar una serie temporal histórica en un rango de fechas explícito. +- **Retorno**: `Promise` con puntos filtrados (`statusCode === "OK"`) y parseados. + +#### 3. `getUltimoValor(codigo, options?)` (Pública) + +- **Propósito**: Obtener la observación más reciente disponible para un indicador (por defecto busca 120 días hacia atrás). +- **Algoritmo**: Consulta la serie histórica, ordena las observaciones por fecha cronológicamente y selecciona el último elemento mediante `puntoOrdenado.at(-1)`. + +--- + +## 📸 Motor de Snapshots: `lib/indicadores-snapshot.ts` + +- **Responsabilidad**: Coordinar la creación del snapshot consolidado de los 10 indicadores administrando el caché en memoria volatil. + +### Estructura de Caché: + +```typescript +const cachePorIndicador = new Map(); +``` + +### Funciones: + +#### 1. `obtenerConFallback(codigo: IndicadorCodigo)` (Privada) + +- **Propósito**: Obtener el valor más reciente de un indicador individual con tolerancia a fallos. +- **Flujo**: + 1. Invoca `getUltimoValor(codigo)`. + 2. Si tiene éxito, guarda el resultado en `cachePorIndicador.set(codigo, indicador)` y lo retorna. + 3. Si falla (captura de excepción), registra el error en `console.error` y retorna el último valor almacenado en `cachePorIndicador.get(codigo)`. + +#### 2. `obtenerSnapshot()` (Pública) + +- **Propósito**: Generar la fotografía completa de la economía. +- **Flujo**: + 1. Ejecuta `Promise.all(INDICADOR_CODIGOS.map(obtenerConFallback))` para consultar los 10 indicadores en paralelo. + 2. Construye un objeto con todos los indicadores válidos obtenidos. + 3. Si ningún indicador tiene datos (`length === 0`), retorna `null`. + 4. Retorna un objeto `IndicadoresSnapshot` con versión `'2.0'`, autor `'Banco Central de Chile'` y fecha ISO actual. + +--- + +## 🔣 Módulo de Formato: `lib/format.ts` + +- **Responsabilidad**: Formatear valores numéricos y fechas respetando las convenciones culturales y monetarias de Chile (`es-CL`). + +### Instancias de Formateadores (`Intl`): + +- `clpFormatter`: Formato moneda CLP (`style: 'currency'`, `currency: 'CLP'`, sin decimales). +- `porcentajeFormatter`: Formato porcentual con exactamente 2 decimales. +- `fechaFormatter`: Formato de fecha larga (`timeZone: 'America/Santiago'`). + +### Funciones Exportadas: + +1. `formatCLP(valor: number): string` → Ejemplo: `963.12` → `"$963"` +2. `formatPorcentaje(valor: number): string` → Ejemplo: `0.35` → `"+0,35%"`, `-2.4` → `"-2,40%"` +3. `formatFecha(fecha: string | Date): string` → Ejemplo: `"2026-07-27"` → `"27 de julio de 2026"` +4. `formatValorPorUnidad(valor: number, unidadMedida?: string): string` → Evalúa si `unidadMedida === 'Porcentaje'` para delegar en `formatPorcentaje` o `formatCLP`. diff --git a/docs/state-management.md b/docs/state-management.md new file mode 100644 index 0000000..972247b --- /dev/null +++ b/docs/state-management.md @@ -0,0 +1,61 @@ +# Gestión del Estado + +Este documento explica cómo fluye el estado de la información a lo largo de la aplicación **Pulso**, detallando el manejo de datos remotos, el estado local y la sincronización con almacenamiento en cliente. + +--- + +## 🔄 Flujo de Estado Global y Servidor-Cliente + +La aplicación no utiliza librerías de estado global pesado como Redux o Zustand. En su lugar, el estado se administra mediante tres patrones ligeros especializados: + +```mermaid +flowchart TD + subgraph Server ["Server-Side State"] + SSR["obtenerSnapshot() en app/page.tsx"] + end + + subgraph Hydration ["Hydration Bridge"] + SWRConf[""] + end + + subgraph Client ["Client-Side State"] + SWRHook["useIndicadores() (SWR Cache)"] + SyncStore["useFavoritos() (useSyncExternalStore)"] + ReactState["useState (Selección de indicador / UI)"] + end + + SSR --> SWRConf + SWRConf --> SWRHook + SWRHook --> ReactState + SyncStore --> ReactState +``` + +--- + +## 1. Estado de Datos Remotos (SWR Engine) + +- **Implementación**: `useSWR` en `hooks/useIndicadores.ts` y `hooks/useIndicadorHistory.ts`. +- **Estrategia**: + - **Server-Side Injection**: El servidor Next.js ejecuta la consulta durante el SSR y la pasa a `` mediante la propiedad `fallback`. + - **Cliente**: `useSWR` lee del caché de hidratación. No dispara peticiones duplicadas gracias a `dedupingInterval: 60000` y realiza revalidación en segundo plano cuando la ventana recupera el foco (`revalidateOnFocus: true`). + +--- + +## 2. Estado de Preferencias del Usuario (`useSyncExternalStore`) + +- **Implementación**: `hooks/useFavoritos.ts`. +- **Patrón**: Observer Pattern sobre `localStorage` de la Web API. +- **Ventajas**: + - Garantiza **seguridad de renderizado isomórfico** sin discrepancias de hidratación en React 19. + - Sincroniza en tiempo real entre múltiples pestañas del navegador abiertas usando la escucha del evento nativo `window.addEventListener('storage', ...)`. + +--- + +## 3. Estado Local de Componente (`useState` & `useMemo`) + +- **Ubicación**: Principalmente en `DashboardHome.tsx`, `Converter.tsx` y `HistoryChart.tsx`. +- **Casos de Uso**: + - `indicadorSeleccionado`: Guarda qué indicador se está visualizando activamente en el gráfico. + - `soloFavoritos`: Booleano que conmuta la visibilidad de la grilla principal. + - `mostrarConversor`: Booleano para desplegar u ocultar la sección del conversor. + - `montoTexto` / `direccion`: Valores de entrada del formulario en el conversor. diff --git a/docs/technical-debt.md b/docs/technical-debt.md new file mode 100644 index 0000000..2285236 --- /dev/null +++ b/docs/technical-debt.md @@ -0,0 +1,47 @@ +# Deuda Técnica, Riesgos y Diagnóstico + +Este documento analiza de forma crítica y transparente la deuda técnica existente en el proyecto **Pulso**, clasificando áreas de riesgo, acoplamientos y recomendaciones de refactorización para mantenedores futuros. + +--- + +## ⚠️ Diagnóstico de Deuda Técnica + +### 1. Sincronización Manual de Constantes de Caché (`revalidate = 300`) + +- **Ubicación**: `lib/bcentral-client.ts`, `app/api/indicadores/route.ts` y `app/api/indicadores/[codigo]/[anio]/route.ts`. +- **Descripción**: La constante `REVALIDATE_SECONDS = 300` definida en `lib/bcentral-client.ts` requiere coincidir de forma idéntica con el valor exportado `export const revalidate = 300` en los Route Handlers. +- **Causa**: Next.js App Router requiere que la exportación `export const revalidate` sea un **literal numérico estático** evaluable en tiempo de compilación; no permite importar una constante declarada en otro módulo. +- **Riesgo**: Si un desarrollador actualiza `REVALIDATE_SECONDS` en la librería pero olvida modificar las exportaciones en las rutas, el comportamiento de caché en servidor y la revalidación HTTP quedarán desincronizados. + +--- + +### 2. Relleno de Fechas Futuras en la API del Banco Central + +- **Ubicación**: `lib/bcentral-client.ts` (`getUltimoValor`). +- **Descripción**: La API del Banco Central de Chile tiene la particularidad de responder con el último valor publicado repetido consecutivamente para fechas futuras cuando se solicita un rango que sobrepasa el día actual. +- **Impacto**: La función `getUltimoValor` toma literalmente la última observación ordenada cronológicamente con `statusCode === "OK"`. Para la UF o el Dólar no genera distorsiones severas, pero en indicadores con desfase de publicación mensual (IPC o Imacec), la fecha del snapshot podría reflejar una fecha reciente que simplemente repite el valor del mes anterior. + +--- + +### 3. Ausencia de Agregación/Decimación en Series Históricas Extensas + +- **Ubicación**: `components/HistoryChart.tsx`. +- **Descripción**: Al seleccionar el rango de 2 años (`2A`), la serie devuelta contiene más de 700 puntos individuales que se renderizan directamente en la instancia de Canvas mediante Chart.js. +- **Riesgo**: Aunque los navegadores modernos procesan 700 puntos sin problemas, si en el futuro se amplía el selector a 5 o 10 años (~3.600 puntos), el rendimiento de renderizado en dispositivos móviles de gama baja podría verse degradado. +- **Solución Recomendada**: Integrar el plugin de decimación (`chartjs-plugin-decimation`) o realizar un downsampling de datos en el servidor/hook antes de pasarlo al componente. + +--- + +### 4. Decodificación Manual de Charset `ISO-8859-1` + +- **Ubicación**: `lib/bcentral-client.ts` (`llamarGetSeries`). +- **Descripción**: Debido a que la API del Banco Central de Chile responde en codificación Latin-1 (`ISO-8859-1`) a pesar de retornar JSON, se utiliza `response.arrayBuffer()` y `new TextDecoder('iso-8859-1').decode(buffer)`. +- **Riesgo**: Depende del soporte del navegador/Node.js para la API global `TextDecoder`. En entornos de ejecución antiguos o severamente restringidos sin soporte completo de ICU, esto podría requerir un polyfill. + +--- + +### 5. Tratamiento del Indicador `libra_cobre` en Formateador Monetario + +- **Ubicación**: `lib/format.ts` (`formatValorPorUnidad`). +- **Descripción**: La moneda del precio de la libra de cobre es Dólares estadounidense (`USD`), pero `formatValorPorUnidad` utiliza por defecto `formatCLP()` cuando la unidad de medida no es `'Porcentaje'`. +- **Riesgo**: El valor se formatea con el símbolo de peso chileno (`$`) en lugar de especificar claramente que el valor está cotizado en dólares o centavos de dólar. diff --git a/hooks/useIndicadorHistory.ts b/hooks/useIndicadorHistory.ts index afbcbe1..ec11064 100644 --- a/hooks/useIndicadorHistory.ts +++ b/hooks/useIndicadorHistory.ts @@ -3,19 +3,26 @@ import useSWR from 'swr'; import type { IndicadorCodigo, SerieHistorica, SerieHistoricaPunto } from '@/types/indicador'; -async function fetchSerieAnio(codigo: IndicadorCodigo, anio: number): Promise { +async function fetchSerieAnio( + codigo: IndicadorCodigo, + anio: number, +): Promise { const response = await fetch(`/api/indicadores/${codigo}/${anio}`); if (!response.ok) { const body = await response.json().catch(() => null); throw new Error( - body?.error ?? `Error al consultar historico de ${codigo} (${anio}): estado ${response.status}`, + body?.error ?? + `Error al consultar historico de ${codigo} (${anio}): estado ${response.status}`, ); } const data: SerieHistorica = await response.json(); return data.serie; } -async function fetchSerieAnioSeguro(codigo: IndicadorCodigo, anio: number): Promise { +async function fetchSerieAnioSeguro( + codigo: IndicadorCodigo, + anio: number, +): Promise { try { return await fetchSerieAnio(codigo, anio); } catch { @@ -33,22 +40,20 @@ export function useIndicadorHistory(codigo: IndicadorCodigo, fechaAncla: Date) { const anioAncla = fechaAncla.getFullYear(); const anios = Array.from({ length: ANIOS_HACIA_ATRAS + 1 }, (_, i) => anioAncla - i); - const { - data, - error, - isLoading, - isValidating, - } = useSWR(['historico', codigo, anioAncla], async () => { - const series = await Promise.all(anios.map((anio) => fetchSerieAnioSeguro(codigo, anio))); - - if (series.every((serie) => serie.length === 0)) { - throw new Error(`No se pudo obtener el historico de ${codigo}`); - } - - return series - .flat() - .sort((a, b) => new Date(b.fecha).getTime() - new Date(a.fecha).getTime()); - }); + const { data, error, isLoading, isValidating } = useSWR( + ['historico', codigo, anioAncla], + async () => { + const series = await Promise.all(anios.map((anio) => fetchSerieAnioSeguro(codigo, anio))); + + if (series.every((serie) => serie.length === 0)) { + throw new Error(`No se pudo obtener el historico de ${codigo}`); + } + + return series + .flat() + .sort((a, b) => new Date(b.fecha).getTime() - new Date(a.fecha).getTime()); + }, + ); return { data, isLoading, isValidating, error }; } diff --git a/hooks/useIndicadores.ts b/hooks/useIndicadores.ts index 7440518..c17ee23 100644 --- a/hooks/useIndicadores.ts +++ b/hooks/useIndicadores.ts @@ -17,15 +17,14 @@ async function fetcher(url: string): Promise { } export function useIndicadores() { - const { - data, - error, - isLoading, - isValidating, - } = useSWR(ENDPOINT_INDICADORES, fetcher, { - revalidateOnFocus: true, - dedupingInterval: 60_000, - }); + const { data, error, isLoading, isValidating } = useSWR( + ENDPOINT_INDICADORES, + fetcher, + { + revalidateOnFocus: true, + dedupingInterval: 60_000, + }, + ); return { data, isLoading, isValidating, error }; } diff --git a/lib/bcentral-client.ts b/lib/bcentral-client.ts index 54ee513..0195087 100644 --- a/lib/bcentral-client.ts +++ b/lib/bcentral-client.ts @@ -1,4 +1,9 @@ -import type { Indicador, IndicadorCodigo, SerieHistorica, SerieHistoricaPunto } from '@/types/indicador'; +import type { + Indicador, + IndicadorCodigo, + SerieHistorica, + SerieHistoricaPunto, +} from '@/types/indicador'; const BASE_URL = 'https://si3.bcentral.cl/SieteRestWS/SieteRestWS.ashx'; const REQUEST_TIMEOUT_MS = 8000; @@ -36,7 +41,11 @@ const SERIES: Record = { nombre: 'Unidad Tributaria Mensual (UTM)', unidadMedida: 'Pesos', }, - imacec: { codigoSerie: 'F032.IMC.V12.Z.Z.2018.Z.Z.0.M', nombre: 'Imacec', unidadMedida: 'Porcentaje' }, + imacec: { + codigoSerie: 'F032.IMC.V12.Z.Z.2018.Z.Z.0.M', + nombre: 'Imacec', + unidadMedida: 'Porcentaje', + }, tpm: { codigoSerie: 'F022.TPM.TIN.D001.NO.Z.D', nombre: 'Tasa de Politica Monetaria (TPM)',