238 lines
10 KiB
Markdown
238 lines
10 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|