Presupuestador_web/AGENTS.md

AGENTS.md

Alcance y seguridad

Este repositorio es Presupuestador UECKO: una SPA para elaboración de presupuestos de mobiliario y una API REST para autenticación, catálogo, distribuidores, usuarios, perfiles, presupuestos y soporte.

Antes de editar:

1. Ejecuta git status --short.
2. Conserva los cambios existentes que no pertenezcan a la tarea.
3. Inspecciona el patrón del contexto, feature o componente equivalente antes de introducir una abstracción nueva.
4. No expongas ni copies secretos desde stack.env, archivos .env o configuraciones de entorno.

No hagas commits, push, reset, rebase, instalaciones de dependencias, regeneración de lockfiles, migraciones ni operaciones Docker o de base de datos sin petición explícita.

Estructura

• client/: SPA React 18 creada con Vite.
• server/: API REST Express, Passport y Sequelize.
• shared/: DTOs, entidades de valor, criterios de consulta, validadores y utilidades compartidas.
• doc/readme.adoc: especificación funcional e intención arquitectónica inicial. Contrasta siempre sus requisitos y endpoints con el código antes de asumir que están implementados.
• dist/: salida de build; no editar manualmente.
• docker-compose.yml, Dockerfile.server, Caddyfile: despliegue Docker/Caddy.

El package.json raíz solo declara shared como workspace. client y server tienen paquetes y lockfiles propios.

Runtime y gestor de paquetes

• Node.js: el raíz exige >=18.19.0; servidor exige >=18.
• TypeScript: ^5.5.4 en client, server y shared.
• Usa Yarn para los comandos existentes. Hay un server/pnpm-lock.yaml adicional: no lo elimines, regeneres ni deduzcas que pnpm es el gestor elegido sin una tarea específica.
• No hay versión de Node fijada mediante .nvmrc, .node-version o .tool-versions.
• El sistema operativo no está impuesto por el repositorio.

Arquitectura backend

El backend está organizado por contextos bajo server/src/contexts:

• auth
• catalog
• profile
• sales
• support
• users
• common

En los contextos se repite la estructura:

• domain: entidades, errores, interfaces de repositorio y reglas de dominio.
• application: casos de uso y servicios de aplicación.
• infrastructure: controladores Express, repositorios, mapeadores, modelos Sequelize y composición de dependencias.

El flujo observable es:

routes Express -> middleware -> controller -> caso de uso/servicio -> repositorio/adaptador -> Sequelize/modelo

Mantén esta separación cuando el contexto existente la use. No conviertas una tarea local en una reestructuración arquitectónica.

Las rutas API se montan en /api/v1 desde:

• server/src/infrastructure/express/app.ts
• server/src/infrastructure/express/api/v1.ts
• server/src/infrastructure/express/api/routes/

Usa controladores, casos de uso, repositorios, mapeadores y DTOs ya existentes como referencia al extender un contexto.

Persistencia

• Sequelize usa dialecto mysql; Docker suministra MariaDB mediante mariadb:latest.
• La configuración de conexión está en server/src/config/environments/.
• El adaptador principal está en server/src/contexts/common/infrastructure/sequelize/SequelizeAdapter.ts.
• Los modelos se localizan dinámicamente mediante el patrón **/*.model.{js,ts}.
• Las asociaciones de modelos se configuran después del registro.
• La configuración Sequelize usa convenciones underscored, timestamps, utf8mb4 y utf8mb4_unicode_ci.
• Los repositorios y la infraestructura Sequelize son el lugar habitual para el acceso a persistencia; evita introducir consultas de base de datos en rutas o componentes.

No hay migraciones ni seeds formales localizados. El arranque de server/src/infrastructure/http/server.ts ejecuta:

sequelizeConn.sync({ force: false, alter: true })
initStructure(...)
insertUsers()

Por ello, no inicies el backend, Docker Compose ni scripts de infraestructura contra una base de datos sin confirmar que la operación está dentro del alcance. No sustituyas este comportamiento por una estrategia de migraciones sin una tarea explícita.

Autenticación y autorización

• Passport se configura en server/src/contexts/auth/infrastructure/express/passport/.
• Existen estrategias local por email y JWT.
• Las rutas autenticadas usan el middleware checkUser.
• Las operaciones administrativas usan middleware como checkIsAdmin; el acceso propio se controla con checkAdminOrSelf cuando corresponde.
• En frontend, autenticación se centraliza en client/src/lib/hooks/useAuth/ y Axios añade la autorización desde client/src/lib/axios/setupInterceptors.ts.
• Las rutas de la SPA se protegen con ProtectedRoute.

No confundas autenticación con autorización. Al añadir una ruta o mutación protegida, reutiliza el middleware y patrón de permisos más cercano.

Frontend

• Punto de entrada: client/src/main.tsx.
• Providers globales: client/src/App.tsx.
• Rutas: client/src/Routes.tsx, mediante React Router y carga diferida.
• Features: client/src/app/.
• Componentes reutilizables: client/src/components/.
• Primitivas UI: client/src/ui/.
• Hooks, Context y utilidades: client/src/lib/.

La comunicación HTTP se centraliza mediante:

• client/src/lib/axios/
• client/src/lib/hooks/useDataSource/
• DataSourceProvider

No introduzcas peticiones Axios directas desde componentes si el proveedor de datos y hooks existentes pueden expresar la operación.

React Query gestiona datos remotos. Usa las claves de consulta de client/src/lib/hooks/useQueryKey/KeyBuilder.ts y los hooks existentes de useDataSource o del feature antes de crear claves o wrappers nuevos.

Los formularios usan React Hook Form y componentes en client/src/components/Forms/. Para tablas, reutiliza client/src/components/DataTable/, los hooks relacionados y TanStack React Table. Para diálogos, botones y primitivas visuales, busca primero equivalentes en components/ y ui/.

La internacionalización se configura en client/src/locales/i18n.ts; los idiomas disponibles son es, en y ca, con español como fallback. Todo texto nuevo visible para usuarios debe seguir el patrón de traducciones existente cuando afecte a una zona internacionalizada.

Convenciones de código

Backend

Patrones de nombres frecuentes:

• Casos de uso: *.useCase.ts
• Controladores: *.controller.ts
• Repositorios: *.repository.ts
• Modelos: *.model.ts
• Mapeadores: *.mapper.ts
• Presentadores: *.presenter.ts

Los DTO compartidos usan habitualmente nombres como I..._Request_DTO e I..._Response_DTO.

La validación usa repetidamente Joi y RuleValidator, en DTOs, entidades y controladores. Sigue el patrón del endpoint o DTO equivalente.

Frontend

• Componentes React: PascalCase.
• Hooks: prefijo use.
• Barrel exports: hay numerosos index.ts; manténlos cuando trabajes en directorios que ya los usen.
• Alias configurados: @, @shared, @ui y @lib.
• Hay mezcla de nombres en inglés y comentarios/UI en español. No impongas una normalización global dentro de cambios acotados.

Tipado

TypeScript está en modo strict en cliente y servidor. El servidor mantiene noImplicitAny: false y ESLint permite any; el cliente lo reporta como advertencia. No amplíes any sin necesidad: prefiere tipos compartidos, DTOs, genéricos o unknown cuando el dato externo necesite validación.

Mantén las comprobaciones explícitas de null y undefined en rutas y datos opcionales; strictNullChecks está activo en el servidor.

Errores y asincronía

• El backend dispone de abstracciones de errores y respuesta HTTP bajo server/src/contexts/common/infrastructure/express/.
• Los controladores se ejecutan mediante handleRequest cuando el patrón del endpoint lo utiliza.
• Los errores de Axios se procesan en client/src/lib/axios/setupInterceptors.ts.
• React Query expone estados y errores a través de hooks; conserva el manejo de carga, error y mutación del feature equivalente.

Usa async/await o devuelve explícitamente promesas según el patrón cercano. No ocultes errores de operaciones remotas ni introduzcas manejadores globales paralelos sin necesidad.

Testing y validación

Jest y ts-jest están configurados en los tres paquetes.

Pruebas localizadas:

• Cliente: pruebas de tabla de catálogo y paginación.
• Shared: pruebas unitarias de entidades de valor y criterios de consulta.
• Servidor: no se localizaron pruebas bajo server/src.
• No se localizaron pruebas E2E ni configuración Cypress/Playwright.

Ejecuta la validación más acotada y pertinente para el cambio. Los comandos reales son:

# Tests
cd shared && yarn test
cd server && yarn test
cd client && yarn test

# Lint
cd server && yarn lint
cd client && yarn lint

# Build / comprobación TypeScript
cd server && yarn build
cd client && yarn build

No existe un script dedicado de typecheck ni de formato. El build de cliente elimina y recrea dist/client; no lo ejecutes si la tarea exige estrictamente no generar archivos.

Desarrollo y Docker

# Desarrollo backend
cd server && yarn dev

# Desarrollo frontend
cd client && yarn dev

# Docker desde la raíz
yarn docker:rebuild
yarn docker:start
yarn docker:stop
yarn docker:restart
yarn docker:logs
yarn docker:build
yarn docker:ps

Docker Compose incluye Caddy, backend, MariaDB, phpMyAdmin y un servicio de espera de base de datos. El servicio frontend está comentado: Caddy sirve dist/client directamente y actúa como reverse proxy del backend.

No reconstruyas contenedores, no levantes servicios y no ejecutes docker compose down como efecto colateral de cambios de código o revisiones.

Documentación y cambios funcionales

Consulta antes de modificar funcionalidades de presupuestos:

• doc/readme.adoc: alcance e intención funcional inicial.
• Rutas actuales en server/src/infrastructure/express/api/routes/.
• DTOs compartidos en shared/lib/contexts/.
• Feature frontend correspondiente bajo client/src/app/.
• Casos de uso y repositorios del contexto backend implicado.

La especificación describe más capacidades de las que se observan necesariamente en rutas actuales. No implementes ni presupongas contratos, gestión completa de catálogo, pedidos o contratos solo porque aparezcan en la documentación de planificación.

Entrega

Al finalizar una tarea:

1. Resume los archivos modificados.
2. Indica las validaciones ejecutadas y su resultado.
3. Indica las validaciones no ejecutadas y por qué.
4. Señala cualquier inconsistencia relevante encontrada, sin modificarla fuera del alcance.
5. No incluyas secretos, tokens, contraseñas ni valores de entorno sensibles.