Enganche

Marketplace de demanda para producción e instalación de sistemas de aluminio y vidrio — piloto v1 (Cali, lanzando a nivel nacional desde el día uno).

Especificación completa del producto en docs/SPEC.md.

Origen de este repo

Este no es el primer intento: DOUGLAS292/Backend_app y DOUGLAS292/frontend-conect fueron un prototipo previo (FastAPI + Supabase, HTML/Bootstrap plano, oct. 2025) sobre la misma idea. Se revisaron antes de arrancar este repo y se rescató lo reutilizable:

• Las categorías de "tipo de proyecto" del formulario de ofertas original están en lib/constants/proyectos.ts, reorganizadas por nivel de complejidad.
• El resto se reconstruye desde cero en Next.js + PostgreSQL/PostGIS, el stack que define docs/SPEC.md §3, porque el modelo de datos de Enganche (8 tablas, máquina de estados, comisión, garantías, geolocalización) es bastante más amplio que el prototipo original.

Estado

Fase 0 — esqueleto de datos ✅

• 7 tablas: usuarios, publicaciones, postulaciones, mensajes, calificaciones, comisiones, garantias (ciudades_piloto existió hasta sept-2026, eliminada al cambiar el periodo de gracia de "por ciudad" a "por usuario" — ver Fase 4)
• Extensión PostGIS + índices GIST para ST_DWithin / ST_Distance
• Reglas de negocio impuestas a nivel de base de datos: - un solo postulante elegida activo por publicación (índice único parcial) - rating_promedio y trabajos_completados recalculados por trigger
• Runner de migraciones propio (npm run migrate), sin dependencias pesadas
• Endpoint /api/health para verificar la conexión a PostGIS

Fase 1 — Auth + Registro (OTP por WhatsApp) ✅

• Login/registro sin contraseñas, formulario de dos pasos: /entrar (celular → código de 6 dígitos) y /registro (perfil, solo para celulares nuevos)
• Códigos OTP de un solo uso: hasheados (AUTH_SECRET como pepper), expiran a los 5 minutos, máximo 5 intentos, 60s de espera entre reenvíos (tabla otps, migración 0012)
• usuarios.celular nunca se confía del cliente al crear la cuenta: sale de una cookie firmada (JWT, 15 min) que solo existe tras pasar el OTP
• Sesión sin contraseña vía cookie httpOnly firmada (JWT, 30 días) — lib/auth/session.ts
• Envío por WhatsApp Business Cloud API (Meta) — lib/auth/whatsapp.ts. Mientras no configures WHATSAPP_ACCESS_TOKEN, el código se imprime en la consola del servidor y viaja en la respuesta de /api/auth/otp/solicitar, para poder probar todo el flujo hoy mismo sin esperar la aprobación de Meta.

Pendiente de tu lado, no bloquea seguir con Fase 2: dar de alta un WhatsApp Business Account en Meta Business Manager, activar la Cloud API para un número, y crear + hacer aprobar una plantilla de mensaje categoría "Authentication" (ej. enganche_otp, en español, con un parámetro de cuerpo para el código). Ese proceso lo controla Meta y puede tardar de horas a un par de días — no es algo que yo pueda hacer por ti. Con WHATSAPP_ACCESS_TOKEN / WHATSAPP_PHONE_NUMBER_ID / WHATSAPP_OTP_TEMPLATE puestos en .env (o en Vercel al desplegar), el envío real se activa solo, sin tocar código.

Fase 2 — Publicar + feed por cercanía ✅

• /publicar — formulario de oferta (tipo de trabajo, nivel del sistema con sugerencias de proyecto, cantidad, valor libre, entrega, ciudad) con captura opcional de ubicación exacta (Geolocation API del navegador)
• /feed — pide tu ubicación al abrir y consulta con ST_DWithin / ST_Distance (radio ajustable 2–50 km, default 10 km); si no hay ubicación, cae a filtrar por ciudad escrita a mano — nunca deja al usuario sin poder ver ofertas
• Filtros por tipo de trabajo y nivel del sistema
• /publicaciones/[id] — detalle con reputación del autor (rating, trabajos completados, verificado); postularse queda para Fase 3
• Consultas geoespaciales verificadas contra la base real vía el conector MCP de Supabase (0 m en el mismo punto, excluida a 10 km desde Bogotá, encontrada a 500 km) — no solo compiladas, probadas con datos
• Desplegado en producción en Vercel + Supabase (pooler sa-east-1), probado de punta a punta por Douglas: login, registro, publicar y ver ofertas funcionando en enganche.vercel.app

Fase 3 — Postulación + chat ✅

• "Postularme" — cualquiera puede postularse a cualquier oferta abierta (sin filtro por perfil, como pide el spec); no se puede postular dos veces a la misma oferta ni a la propia
• El autor ve sus postulantes (reputación incluida) y elige uno — la publicación pasa a en_proceso y las demás postulaciones quedan pendiente, no rechazadas
• Regla central impuesta por la base de datos, no solo por el código: solo puede haber un postulante elegida a la vez por publicación (índice único parcial) — probado forzando el error contra la base real
• Reapertura: si el elegido no responde, el autor reabre la oferta → vuelve a abierta, el elegido pasa a rechazada, y los demás postulantes siguen disponibles sin tener que volver a postularse — probado contra la base real, coincide exactamente con el spec
• Botón "Cancelar publicación" (abierta → cancelada)
• Chat 1-a-1 por publicación, solo entre el autor y el elegido — el celular de la otra parte se revela ahí (nunca antes), con enlace directo a WhatsApp
• /postulaciones — "Mis postulaciones" con el estado de cada una

Pendiente para más adelante (no bloquea Fase 4): las notificaciones reales (push / WhatsApp) de "fuiste elegido" y "se reabrió la oferta" que pide el spec — hoy el cambio de estado ocurre correctamente en la base, pero avisar al usuario fuera de la app depende del mismo WhatsApp Business API que Fase 1 dejó pendiente de aprobación por Meta.

Fase 4 — Cierre + calificación + comisión ✅

• "Marcar trabajo completado" (autor, solo desde en_proceso) — genera la comisión automáticamente, sin depender de que nadie califique
• Periodo de gracia por usuario (cambiado de "por ciudad" a "por usuario" en sept-2026, ver docs/SPEC.md): el primer trabajo completado de cada usuario le arranca 30 días sin comisión en toda la plataforma, sin importar la ciudad; pasado ese plazo personal cobra el 3% normal — probado contra la base real: mismo usuario gratis en su primer trabajo y cobrando en el segundo, en ciudades distintas
• completada_en nuevo en publicaciones (migración 0013, ya aplicada en producción) para poder contar los 30 días de garantía
• Calificación mutua (autor ↔ ganador), independiente y no bloqueante para el cobro — reutiliza el trigger de rating_promedio de Fase 0, confirmado con datos reales (5 ★ → rating_promedio recalculado solo)
• trabajos_completados también se incrementa solo al completar (trigger de Fase 0), sin código nuevo — confirmado con datos reales
• Reporte de garantía (autor, dentro de 30 días de completada) + el autor marca "atendida" / "no atendida"; el ganador ve el reporte y coordina por el chat
• Comisión: el ganador (responsable_pago_id) se marca "pagada" desde la app; la confirmación final queda para el admin en Fase 5

Pendiente para más adelante: notificaciones reales de "comisión pendiente

48h" y de reportes de garantía (mismo bloqueo de WhatsApp Business API de Fase 1); y el criterio exacto de cómo un no_atendido reduce reputación más allá de quedar registrado como dato — el spec lo deja como "insumo", sin fórmula, así que se define cuando haya casos reales.

Fase 5 — Panel de comisiones (admin) ✅

• usuarios.es_admin (migración 0014, ya aplicada en producción) — marca a Douglas como el único admin del piloto
• /admin — vista de solo lectura de todas las comisiones (pendiente, marcada pagada, confirmada), con totales por estado, ciudad, sistema y el responsable de pago (nombre + celular)
• "Confirmar pago recibido" — el admin cierra el ciclo de una comisión marcada_pagada → confirmada, con confirmada_en; probado contra la base real (transición correcta, y no confirma dos veces la misma comisión)
• El link "Panel admin" solo aparece en el home si usuario.es_admin; /admin redirige a / si el usuario no es admin (o no hay sesión)

Con esto cierra el plan de 5 fases del spec. Lo que queda pendiente es externo a la app: la aprobación de Meta para WhatsApp Business API (Fase 1), y las notificaciones push/WhatsApp reales que dependen de esa misma aprobación (mencionadas en Fase 3 y Fase 4).

Siguiente: por definir con Douglas — candidatos naturales son pulir UI/UX, notificaciones, o abrir el piloto a más usuarios reales en Cali.

Poner esto a andar

1. Base de datos (PostgreSQL + PostGIS)

Recomendado para el piloto: Supabase (gratis para empezar, PostGIS viene preinstalado, connection string lista en Project Settings → Database → Connection string → URI). Railway es la alternativa si prefieres eso.

2. Variables de entorno

cp .env.example .env
# completa DATABASE_URL con la connection string de Supabase/Railway
# genera y pega un AUTH_SECRET:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Deja WHATSAPP_* vacío por ahora — sin esas variables, el login funciona igual en modo desarrollo (el código OTP sale en pantalla). Ver Fase 1 arriba.

3. Instalar y migrar

npm install
npm run migrate   # crea las 8 tablas + triggers + extensión PostGIS

4. Correr en local

npm run dev

Abre http://localhost:3000 — el botón "Verificar conexión a PostGIS" confirma que DATABASE_URL y la extensión quedaron bien configuradas.

Estructura

db/migrations/       Migraciones SQL numeradas (tablas, índices, triggers)
scripts/migrate.mjs  Runner de migraciones (sin dependencias de ORM)
lib/db.ts            Pool de conexión a Postgres (pg)
lib/auth/            OTP, sesión (JWT en cookie) y envío por WhatsApp
lib/validation/       Normalización de celular colombiano
lib/constants/        Listas de referencia para los formularios (Fase 2)
app/entrar/           Paso 1-2 del login: celular → código
app/registro/         Perfil, solo para celulares nuevos verificados
app/publicar/         Formulario de oferta (con ubicación opcional)
app/feed/             Feed por cercanía con filtros
app/publicaciones/[id] Detalle: postularse, elegir, reabrir, cancelar, cerrar
app/publicaciones/[id]/chat  Chat 1-a-1 autor ↔ elegido
app/postulaciones/     "Mis postulaciones" del usuario
app/api/auth/         Rutas de login/registro/sesión
app/api/publicaciones/ Ofertas, postulación, cierre, comisión, garantías
app/admin/            Panel de comisiones, solo para usuarios.es_admin
app/api/admin/        Confirmar comisiones marcadas como pagadas
app/                  Next.js App Router
docs/SPEC.md          Especificación técnica completa del producto

Probar el login hoy mismo (sin WhatsApp real)

1. npm run dev, abre http://localhost:3000/entrar
2. Escribe cualquier celular colombiano (10 dígitos, empieza en 3)
3. Como WHATSAPP_ACCESS_TOKEN no está configurado, el código de 6 dígitos aparece directo en la pantalla ("Modo desarrollo") — cópialo
4. Verifica el código → si el celular es nuevo, te lleva a /registro a completar el perfil; si ya existe, entra directo