# Ficha del proyecto ## 1. Identificación **Nombre del proyecto:** Presupuestador UECKO (`uecko-presupuestador`, versión raíz `1.1.5`). **Objetivo principal:** Aplicación web para que distribuidores creen, consulten, editen, dupliquen, envíen y descarguen presupuestos de mobiliario basados en un catálogo. Incluye autenticación, perfiles, gestión/listado de distribuidores y usuarios, generación de PDF de presupuestos y envío de incidencias. Evidencia principal: `doc/readme.adoc`, `client/src/Routes.tsx`, `server/src/infrastructure/express/api/routes/`. **Estado actual:** NO DETERMINADO. Hay configuración de despliegue, dominio de producción y variables de producción (`docker-compose.yml`, `Caddyfile`, `client/.env.production`), pero esto no acredita que esté actualmente desplegado ni que esté en mantenimiento. ## 2. Repositorio **Repositorio principal:** Ruta inspeccionada: `Z:\` (repositorio Git detectado). **Estructura general:** Repositorio único con tres paquetes principales, no un monorepo de workspaces completo: - `client/`: SPA React/Vite. - `server/`: API REST Express. - `shared/`: contratos DTO, entidades de valor, utilidades y validaciones compartidas. El `package.json` raíz declara únicamente `shared` como workspace. `client` y `server` son paquetes independientes con sus propios lockfiles y comandos. ## 3. Stack tecnológico **Backend:** - Node.js: `>=18.19.0` en raíz y `>=18` en `server/package.json`. La imagen Docker usa la etiqueta no fijada `node:lts-iron`. - TypeScript: `^5.5.4` en `server/package.json`. - Express: `^4.18.2`. - Autenticación: Passport `^0.7.0`, estrategias local por email y JWT (`passport-local`, `passport-jwt`), JWT y bcrypt. - ORM: Sequelize `^6.37.3`, con `sequelize-typescript` y `mysql2`. - Validación: Joi, `@joi/date`, `@reis/joi-luxon`; validaciones distribuidas entre DTO, entidades y controladores. - Logging: Morgan para solicitudes y Winston con rotación diaria. - Generación de PDF: Puppeteer, Puppeteer Report y Handlebars. - Documentación OpenAPI/Swagger: `express-openapi-validator` está declarado, pero no se localizó una especificación OpenAPI/Swagger ni uso observable de esta librería. **Frontend:** - TypeScript: `^5.5.4`. - React y React DOM: `^18.2.0`. - Vite: `^5.4.16`. - Routing: React Router DOM `^6.26.0`, con `createBrowserRouter`. - UI: configuración ShadCN/UI (`client/components.json`), componentes locales derivados de Radix UI y Radix UI como dependencia. - Tailwind CSS: `^3.4.13`; PostCSS y `tailwindcss-animate`. - Formularios: React Hook Form `^7.55.0`, `@hookform/resolvers` y Joi. - Estado remoto: TanStack React Query `^5.51.23`; cliente Axios y proveedores mediante Context. - Tablas: TanStack React Table `^8.20.1`. - Internacionalización: i18next, react-i18next y detector de idioma; recursos `es`, `en` y `ca`. - Otras bibliotecas relevantes: Axios, dnd-kit, React PDF, Recharts y Lucide. **Base de datos:** - Motor configurado por Sequelize: dialecto `mysql`. - Servicio contenedorizado: imagen `mariadb:latest`; por tanto la versión de MariaDB no está fijada y `11.5` no puede confirmarse. - Conexión mediante variables `MYSQL_*`; en producción el host previsto es el servicio `mariadb`. - Migraciones: no se localizaron migraciones formales. - Seeds: no se localizaron seeds formales. El servidor ejecuta inicialización propia mediante `initStructure()` e `insertUsers()` al arrancar. - La sincronización Sequelize se ejecuta con `{ force: false, alter: true }`. **Testing:** - Infraestructura Jest/ts-jest declarada en los tres paquetes. - Pruebas encontradas: 8 archivos de prueba: 2 en `client` y 6 en `shared`; no se localizaron pruebas bajo `server/src`. - Testing Library está declarada en cliente; Supertest está declarado en servidor, sin pruebas de servidor localizadas. - No hay evidencia de pruebas E2E con Cypress o Playwright. **Infraestructura / despliegue:** - Docker Compose con Caddy, MariaDB, backend, phpMyAdmin y un contenedor de espera de base de datos. - Caddy sirve `dist/client` y actúa como reverse proxy HTTPS hacia el backend. - El servicio frontend de Compose está comentado; el frontend se construye a `dist/client` y se monta directamente en Caddy. - No se localizaron workflows de GitHub Actions, GitLab CI ni otra configuración CI/CD. - Evidencia: `docker-compose.yml`, `Dockerfile.server`, `client/Dockerfile`, `Caddyfile`. ## 4. Arquitectura **Estilo arquitectónico:** Backend organizado por contextos funcionales y capas `domain` / `application` / `infrastructure`, sobre Express y Sequelize. Es razonable inferir una inspiración en puertos y adaptadores: hay interfaces de repositorio, casos de uso, adaptadores y mapeadores. No hay evidencia suficiente para afirmar cumplimiento uniforme de Clean Architecture o arquitectura hexagonal formal. **Organización principal:** - Backend: - Contextos: `auth`, `catalog`, `profile`, `sales`, `support`, `users` y `common`. - Las rutas Express construyen o invocan controladores. - Los controladores delegan en casos de uso y servicios de aplicación. - Los repositorios y modelos Sequelize residen en infraestructura. - `common` aporta controladores base, errores HTTP, adaptador Sequelize, transacciones y utilidades compartidas. - Frontend: - Organización principal por funcionalidad en `client/src/app`: autenticación, catálogo, distribuidores, presupuestos, configuración y soporte. - Componentes reutilizables en `components/`, UI base en `ui/`, hooks y proveedores en `lib/hooks/`. - `shared/lib` contiene DTOs, entidades de valor, criterios de consulta y utilidades consumidos por cliente y servidor. **Reglas arquitectónicas importantes:** - Las rutas API se agrupan bajo `/api/v1` y aplican middleware de contexto común. - Las rutas protegidas usan Passport y middleware `checkUser`; usuarios y distribuidores tienen controles adicionales para permisos administrativos o acceso propio. - El acceso a base de datos se concentra predominantemente en adaptadores, repositorios y modelos de infraestructura Sequelize. - Las llamadas HTTP del frontend se centralizan en el proveedor Axios y el `DataSourceProvider`. - React Query maneja el estado remoto; los providers Context manejan autenticación, fuente de datos, tema y avisos de cambios sin guardar. - El arranque del backend modifica potencialmente la estructura y datos de la base de datos mediante sincronización Sequelize e inicialización propia. ## 5. Convenciones relevantes - Backend: nombres frecuentes `*.useCase.ts`, `*.controller.ts`, `*.repository.ts`, `*.model.ts`, `*.mapper.ts` y `*.presenter.ts`. - Backend: los contextos usan directorios `domain`, `application` e `infrastructure`; los DTO compartidos suelen usar prefijos `I..._Request_DTO` e `I..._Response_DTO`. - Backend: validación recurrente con Joi y `RuleValidator`; los controladores de listados validan parámetros de consulta. - Backend: mapeadores separan entidades/modelos/DTO en varios contextos. - Backend: TypeScript estricto está activado, pero `noImplicitAny` es `false` y ESLint permite explícitamente `any`. - Frontend: componentes React en PascalCase; hooks con prefijo `use`; exports agrupados mediante múltiples `index.ts`. - Frontend: alias `@`, `@shared`, `@ui` y `@lib` configurados para importaciones. - Frontend: formularios construidos con React Hook Form y componentes de formulario reutilizables. - Frontend: React Query usa una fábrica de claves (`KeyBuilder`); mutaciones y consultas se encapsulan habitualmente en hooks. - Frontend: tablas reutilizables basadas en TanStack React Table y hooks asociados. - Frontend: i18n se basa en detección del navegador y usa español como fallback. **Convenciones no uniformes detectadas:** - Hay lockfiles Yarn en raíz, cliente y servidor, pero también `server/pnpm-lock.yaml`; no existe campo `packageManager` que resuelva la ambigüedad. - El root declara solo `shared` como workspace, aunque `client` y `server` son paquetes hermanos. - Existen convenciones de capas sólidas en el backend, pero rutas y composición de dependencias presentan mezcla de factories, llamadas directas a controladores y funciones de contexto. - Hay directorios y nombres de pruebas no homogéneos: `__test__`, `*.test.ts`, `*.test.tsx` y rutas con nombres de marcador. ## 6. Comandos habituales **Instalación:** ```bash yarn install cd shared && yarn install cd ../server && yarn install cd ../client && yarn install ``` **Desarrollo:** ```bash cd server && yarn dev cd client && yarn dev ``` **Build:** ```bash cd server && yarn build cd client && yarn build ``` **Tests:** ```bash cd shared && yarn test cd server && yarn test cd client && yarn test ``` **Typecheck:** No existe un script dedicado de typecheck. ```bash cd server && yarn build cd client && yarn build ``` El build de servidor ejecuta `tsc`; el de cliente ejecuta `tsc` antes de Vite. **Lint:** ```bash cd server && yarn lint cd client && yarn lint ``` **Formato:** NO DETERMINADO. Hay configuración Prettier en raíz, pero no se declara un script de formato. **Migraciones / seeds:** NO DETERMINADO como comandos. No se localizaron scripts ni herramientas de migración/seed declaradas. **Docker:** ```bash yarn docker:rebuild yarn docker:start yarn docker:stop yarn docker:restart yarn docker:logs yarn docker:build yarn docker:ps ``` ## 7. Documentación de referencia - `doc/readme.adoc`: especificación funcional y arquitectónica inicial; describe requisitos, roles, modelo conceptual y diseño propuesto. Debe leerse como documento de intención, no como reflejo automático de la implementación. - `package.json`, `server/package.json`, `client/package.json`, `shared/package.json`: fuente de verdad para scripts y dependencias declaradas. - `docker-compose.yml`, `Dockerfile.server`, `Caddyfile`: referencia de despliegue local/servidor. - `server/src/infrastructure/express/api/routes/`: contratos de rutas actualmente implementados. - `server/src/config/environments/`: configuración de ejecución y conexión por entorno. ## 8. Restricciones importantes - Node.js requiere como mínimo `18.19.0` según `package.json` raíz; servidor declara como mínimo Node 18. - Las rutas API se sirven bajo `/api/v1`. - El acceso a las rutas autenticadas exige JWT mediante Passport; varias operaciones de usuarios y distribuidores exigen permisos administrativos. - La configuración de producción limita CORS a `https://presupuestos.uecko.com`. - La aplicación cliente depende de `VITE_API_URL`. - La persistencia usa dialecto MySQL a través de Sequelize; el despliegue Docker suministra MariaDB. - El servidor puede alterar el esquema al iniciar debido a `sequelize.sync({ alter: true })`; no debe tratarse como un arranque sin efectos sobre la base de datos. - Los idiomas configurados en cliente son español, inglés y catalán. ## 9. Observaciones - Existe una separación real entre SPA, API y librería compartida, aunque los workspaces no abarcan todos los paquetes. - El dominio implementado gira alrededor de autenticación, catálogo, presupuestos, distribuidores, perfil, usuarios y soporte. - La documentación funcional describe también contratos y gestión del catálogo por fábrica, pero no toda esa funcionalidad se observa en las rutas implementadas; las decisiones deben contrastarse con código. - Hay pruebas unitarias, pero su cobertura es limitada y no se localizaron pruebas de API ni E2E. - No se localizaron CI/CD ni una especificación OpenAPI/Swagger usable.