Sistema de conversión y búsqueda de productos entre proveedores externos y el sistema local.
- Backend: Express + TypeScript + Prisma + PostgreSQL + Zod
- Frontend: React + Vite + TypeScript + Tailwind CSS
- Infra: Docker Compose (dev + prod)
├── backend/ # API REST
│ ├── config/ # Env + Prisma client
│ ├── middleware/ # Error handler + async handler
│ ├── repositories/ # Queries Prisma (paginación + filtros)
│ ├── routes/ # Endpoints REST
│ ├── services/ # Lógica de negocio
│ ├── validators/ # Schemas Zod (paginación + límites)
│ ├── prisma/ # Schema + seed + migrations (índices pg_trgm)
│ └── Dockerfile.prod # Multi-stage, no-root
├── frontend/ # SPA React
│ └── src/
│ ├── components/ # UI + paginación
│ ├── hooks/ # useProviders / useLocalProducts / useEquivalences / useSearch
│ ├── views/ # Vistas de la app
│ ├── services/ # Cliente HTTP → API
│ └── types.ts
├── docker-compose.yml # Dev (hot reload)
├── docker-compose.prod.yml # Prod (Nginx + no-root)
└── frontend/nginx.conf # Front prod + proxy /api
| Método | Ruta | Descripción |
|---|---|---|
| GET | /health |
Health check |
| GET | /health/db |
Health check con consulta a PostgreSQL |
| GET | /api/providers |
Listar proveedores |
| POST | /api/providers |
Crear proveedor |
| GET | /api/providers/:id |
Obtener proveedor |
| PUT | /api/providers/:id |
Actualizar proveedor |
| DELETE | /api/providers/:id |
Eliminar proveedor (borra sus equivalencias) |
| GET | /api/products |
Listar productos locales |
| POST | /api/products |
Crear producto local |
| GET | /api/products/:id |
Obtener producto local |
| PUT | /api/products/:id |
Actualizar producto local |
| DELETE | /api/products/:id |
Eliminar producto local (borra sus equivalencias) |
| GET | /api/equivalences |
Listar equivalencias |
| POST | /api/equivalences |
Crear equivalencia |
| GET | /api/equivalences/:id |
Obtener equivalencia |
| PUT | /api/equivalences/:id |
Actualizar equivalencia |
| DELETE | /api/equivalences/:id |
Eliminar equivalencia |
| GET | /api/search?q=... |
Búsqueda universal (código o nombre) |
Todas las rutas /api/* requieren un JWT de acceso válido de Supabase en el
encabezado Authorization: Bearer <access_token>. Los endpoints /health y
/health/db son públicos para los health checks del servicio.
La validación de inputs se hace con Zod en el backend: campos requeridos, sin espacios extremos (
trim),identeros positivos, y el update exige al menos un campo. Respuestas de error:400(validación),404(no existe),409(duplicado).
Los endpoints de listado (/api/providers, /api/products, /api/equivalences)
y /api/search están paginados (server-side). Parámetros de query:
| Parámetro | Descripción | Default | Máx. |
|---|---|---|---|
q |
Filtro de texto (código/nombre, con índices pg_trgm) |
— | 120 |
page |
Número de página | 1 | 200 |
limit |
Filas por página | 100 (50 en search) |
200 |
providerId |
Filtro por proveedor (/equivalences y /search) |
— | — |
Respuesta de listados:
Respuesta de /api/search:
{ "results": [...], "meta": { "page": 1, "limit": 50, "total": 7, "pageCount": 1 } }- CORS restringido a orígenes de
CORS_ORIGINS(coma-separados, defaulthttp://localhost:5173). - Autenticación Supabase en Express: valida la firma del JWT mediante el JWKS del proyecto, además del issuer, audiencia y expiración. El proyecto debe publicar claves asimétricas en el JWKS.
- El frontend usa únicamente la clave pública publishable/anon; nunca configures una clave
service_roleen variablesVITE_*. - Helmet,
express-rate-limit(global 600/15min, search 60/1min) yexpress.json({ limit: "1mb" }). compressiongzip ytrust proxy.- Índices GiN
pg_trgmpara búsqueda porILIKE %…%enproveedores,productos_localesyequivalencias. - Paginación real con
count + findManyen transacción (no se trae toda la tabla). - AbortController en el buscador (cancela fetch en vuelo al escribir).
cp env.example .env # configura el proyecto Supabase y la clave pública anon
docker compose up --build- Frontend: http://localhost:5173
- Backend: http://localhost:3000
- PostgreSQL (Docker): localhost:5433 — user
postgres/ passpostgres, base de datosproduct_mapper(tablas:proveedores,productos_locales,equivalencias). Conecta desde pgAdmin con esos datos.Nota: si tienes un PostgreSQL nativo instalado en Windows, dejará el puerto 5432 para sí mismo; el contenedor usa el 5433 para no chocar.
Configura .env antes del despliegue: define POSTGRES_USER, POSTGRES_PASSWORD
y POSTGRES_DB con valores propios y no reutilices las credenciales de desarrollo.
Si la contraseña contiene caracteres reservados de URL, codifícala para que
DATABASE_URL sea válida. CORS_ORIGINS debe contener los orígenes permitidos,
separados por comas.
Configura también SUPABASE_URL, VITE_SUPABASE_URL (URL del mismo proyecto),
VITE_SUPABASE_ANON_KEY (clave publishable/anon) y, opcionalmente,
SUPABASE_JWT_AUDIENCE (por defecto authenticated). Desactiva el registro
público en Supabase Auth y crea/invita únicamente las cuentas autorizadas desde
el panel de Supabase. No uses claves JWT legacy HS256: el backend valida tokens
con el JWKS público del proyecto.
docker compose -f docker-compose.prod.yml -p productmapper-prod up -d --build- Frontend: http://localhost:8080 (Nginx sirve el bundle y hace proxy
/apial backend). - Banco de datos separado (
postgres_data_prod), sin seed. - Imágenes multi-stage: backend no-root (
node), frontend no-root (nginxunprivileged). - Los servicios de producción incluyen health checks; Docker ignora archivos locales
node_modules, builds y.enval construir imágenes. - No se publican los puertos de PostgreSQL ni del backend al host.
En Render, define SUPABASE_URL y, si corresponde, SUPABASE_JWT_AUDIENCE en
el servicio backend. En el servicio frontend, define VITE_SUPABASE_URL y
VITE_SUPABASE_ANON_KEY como variables de entorno de build, además de
VITE_API_URL. Vuelve a desplegar el frontend al cambiar esas variables.
Requiere PostgreSQL corriendo y accesible.
# Backend
cd backend
cp ../env.example .env # ajusta DATABASE_URL a tu PG local
npm install
npx prisma generate
npx prisma migrate dev # aplica migraciones
npx prisma db seed # datos iniciales (opcional)
npm run dev
# Frontend (otra terminal)
cd frontend
npm install
npm run devLas migraciones viven en backend/prisma/migrations/ y se aplican automáticamente
al arrancar el contenedor (npx prisma migrate deploy). Tablas:
proveedoresproductos_localesequivalencias
Con:
- PK/FK correctas
UNIQUEenproductos_locales.codigoUNIQUEcompuesto enequivalencias (proveedor_id, codigo_proveedor)(evita duplicados)- Índices GIN
pg_trgmpara búsqueda tolerante por nombre y FKs indizadas (20260905000000_search_indexes)
cd backend
npx prisma db seed
{ "data": [...], "meta": { "page": 1, "limit": 100, "total": 123, "pageCount": 2 } }