Consult AS Technology
8407fc24c3
- Servicio de automatizaciones con estado persistido en SQLite (índice RR, dedup de recordatorios) - Webhook Monday procesa create_item del board Leads y asigna vendedor - Crons: polling cada 5 min (respaldo sin webhook público) + escaneo diario 9am - Endpoints admin: /api/automatizaciones/estado, /round-robin/run, /inactividad/preview - 15 tests nuevos (70/70 verdes)
76 lines
4.8 KiB
Markdown
76 lines
4.8 KiB
Markdown
# FRASA API Gateway
|
|
|
|
Backend Node.js que conecta las 3 apps web del ecosistema FRASA (cotizador :3001, alta-clientes :3002, cobranza :3003) con Monday.com y da persistencia real (Prisma + SQLite en dev, Postgres 16 en prod).
|
|
|
|
## Stack
|
|
|
|
Express 5 · TypeScript estricto · zod · Prisma (SQLite dev) · multer 2 · vitest
|
|
|
|
## Cómo correr en dev
|
|
|
|
```bash
|
|
npm install
|
|
npx prisma migrate dev # crea/actualiza prisma/dev.db
|
|
npm run dev # tsx watch en :3000
|
|
```
|
|
|
|
Las credenciales de Monday y los board IDs se leen del `.env` raíz del ecosistema (`../.env`); el servicio también acepta un `.env` local (Prisma CLI lo requiere para `DATABASE_URL`). El token NUNCA se imprime en logs.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
npm test # vitest: fórmulas del cotizador (fixture U-101), cobranza, monday.service con fetch mockeado
|
|
```
|
|
|
|
## Endpoints (prefijo /api)
|
|
|
|
| Método | Ruta | Descripción |
|
|
|---|---|---|
|
|
| GET | `/api/health` | `{status, monday: 'up'|'down'}` |
|
|
| GET | `/api/unidades` | Inventario desde Monday (`?disponibles=true` filtra) |
|
|
| GET | `/api/unidades/:codigo` | Una unidad (404 si no existe) |
|
|
| POST | `/api/cotizaciones` | Calcula propuesta (server-side), persiste y crea Oportunidad en Monday |
|
|
| GET | `/api/cotizaciones` · `/api/cotizaciones/:id` | Consulta |
|
|
| POST | `/api/clientes` | Alta de cliente: persiste payload completo, crea Contacto y Apartado en Monday |
|
|
| GET | `/api/clientes/:id` | Cliente con documentos |
|
|
| POST | `/api/clientes/:id/documentos` | Multipart (campo `archivos`, máx 10, pdf/jpg/png, 10 MB) |
|
|
| GET | `/api/clientes/:id/documentos` | Lista documentos |
|
|
| POST | `/api/planes` | Crea plan de pago con calendario generado |
|
|
| GET | `/api/planes` · `/api/planes/:id` | Con saldo/status calculados |
|
|
| GET | `/api/planes/cobranza-del-dia` | Urgencias de cobranza (`?diasAnticipacion=7`) |
|
|
| POST | `/api/planes/:id/abonos` | Aplica abono (estricto al centavo) |
|
|
| POST | `/api/planes/:id/notas` | Agrega nota a la bitácora |
|
|
| POST | `/api/planes/:id/cancelar` | Cancela el plan |
|
|
| POST | `/api/webhooks/monday` | Handshake `challenge`; `create_item` en Leads dispara round-robin |
|
|
| GET | `/api/automatizaciones/estado` | Índice RR actual, vendedores, último escaneo |
|
|
| POST | `/api/automatizaciones/round-robin/run` | Pasada manual de asignación round-robin |
|
|
| GET | `/api/automatizaciones/inactividad/preview` | Leads que serían recordados hoy (solo lectura) |
|
|
|
|
## Automatizaciones de Monday (tablero Leads)
|
|
|
|
- **Round-robin de vendedores**: leads sin persona en la columna people `Vendedor` reciben el siguiente vendedor de la lista rotativa. La lista viene de `MONDAY_RR_USER_IDS` (coma-separados) o, si está vacía, de los usuarios no-guest del workspace (cacheados en BD). El índice se persiste en la tabla `AutomatizacionState` (sobrevive reinicios).
|
|
- **Recordatorio de inactividad**: leads con estado no terminal (`DESCARTADO` es el único terminal) y más de `INACTIVIDAD_DIAS` (default 10) sin actualizarse reciben un update en el item. Dedup por día: clave `recordatorio:<itemId>:<fecha>` en `AutomatizacionState`.
|
|
- **Disparadores**: webhook `POST /api/webhooks/monday` (evento `create_item` en el board Leads) y, como respaldo mientras no haya URL pública, crons con node-cron: `POLL_CRON` (default `*/5 * * * *`) para round-robin y `0 9 * * *` para inactividad. Los crons se apagan con `MONDAY_AUTOMATIONS_ENABLED=false`.
|
|
|
|
## Notas de arquitectura
|
|
|
|
- **Monday service** (`src/services/monday.service.ts`): resuelve column IDs por TÍTULO en runtime (los slugs autogenerados nunca se hardcodean), paginación por cursor, retry con backoff ante 429/complejidad, `column_values` siempre via `JSON.stringify` en variables, cache de unidades 5 min con invalidación tras escrituras.
|
|
- **Cálculos del cotizador** (`src/services/cotizacion.service.ts`): port exacto del Excel de producción (quirks incluidos: Infonavit usa precio de lista en mensualidades; enganche bancario sobre precio lista). NO corregir.
|
|
- **Cobranza** (`src/services/cobranza.service.ts`): espejo de la lógica del frontend; los controllers mapean Prisma → dominio, ejecutan las funciones puras y persisten.
|
|
- **Dinero como `Float`** por ahora — TODO prod: `Decimal` en Postgres.
|
|
- **Webhooks de Monday no están firmados** → el payload se trata como no confiable; el evento solo es un disparador y el round-robin re-consulta el tablero vía API antes de escribir.
|
|
|
|
## TODO producción (pendientes deliberados)
|
|
|
|
- Auth (JWT ya hay vars en .env), helmet, rate-limit — es red interna por ahora.
|
|
- Postgres 16 (`provider = "postgresql"`, `Decimal`), Redis para cache de unidades.
|
|
- CORS restringido a los orígenes de las apps.
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
docker build -t frasa-api-gateway .
|
|
docker run -p 3000:3000 --env-file ../.env frasa-api-gateway
|
|
# El arranque corre `prisma migrate deploy` antes de levantar el server
|
|
```
|