Uecko/Presupuestador_web
2
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
08f01e2b3b
Presupuestador_web/doc/ficha-proyecto.md

11 KiB
Raw Blame History

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:

yarn install
cd shared && yarn install
cd ../server && yarn install
cd ../client && yarn install

Desarrollo:

cd server && yarn dev
cd client && yarn dev

Build:

cd server && yarn build
cd client && yarn build

Tests:

cd shared && yarn test
cd server && yarn test
cd client && yarn test

Typecheck:

No existe un script dedicado de typecheck.

cd server && yarn build
cd client && yarn build

El build de servidor ejecuta tsc; el de cliente ejecuta tsc antes de Vite.

Lint:

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:

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.