Presupuestador_web/doc/ficha-proyecto.md

# 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.