JTP Logistics

README

JTP Logistics

Aplicación web para la gestión de rutas, flotas, cotizaciones, finanzas y equipo de una operación logística. Incluye dashboards por rol (administrador, transportista, colaborador, vendedor, desarrollador), autenticación con Better Auth, permisos granulares por módulo y base de datos PostgreSQL.

Dominio: www.jtplogistics.com (el dominio sin www redirige aquí)

Stack

Framework: Next.js 16 (App Router, React 19, React Compiler)
Base de datos: PostgreSQL sobre Neon con Prisma 7 (adapter serverless)
Autenticación: Better Auth (email/contraseña, sesiones, restablecimiento de contraseña)
UI: Tailwind CSS 4, shadcn/ui, Radix UI, Base UI, Lucide
Tablas de datos: TanStack Table (DataTable con filtros y ordenación)
Editor de texto enriquecido: Lexical (términos de cotización y blog del mural)
Fechas: react-day-picker vía el Calendar de shadcn
Documentos y datos: @react-pdf/renderer (cotizaciones), ExcelJS (exportar a Excel), Recharts (gráficas)
Otros: Cloudinary (imágenes), Resend (correos), Vitest (pruebas), Vercel Analytics / Speed Insights

Roles y permisos

Los roles se guardan en inglés en la BD: admin, carrier, collaborator, vendor, developer.

El administrador tiene acceso total. El colaborador no ve nada por defecto: el admin le enciende permisos módulo por módulo desde Colaboradores → editar, con cuatro niveles por módulo (leer, crear, editar, eliminar). Esos permisos viven como columnas booleanas en users (can_view_*, can_create_*, can_update_*, can_delete_*) y se aplican en dos capas:

Páginas: requireCollaboratorPermission() en el layout.tsx del módulo (redirige si no tiene permiso).
API: un gate por módulo (p. ej. gateTasks, gateMural) que responde 403.

El admin siempre pasa ambas capas sin necesidad de tener los flags encendidos.

Funcionalidades por rol

Administrador

Operaciones: Rutas (CRUD, origen/destino, tarifa objetivo, estado), Tipos de unidad, Tipos de incidencia, Embarques, Tabla de finanzas y Rentabilidad por ruta.
Reglas operativas: los registros de finanzas se generan automáticamente cuando un embarque se cierra.
Comercial: Cotizador (terrestre y marítimo), Proveedores (transportistas con perfil, rutas asignadas y rating), Clientes.
Equipo: Colaboradores (perfil y permisos), Vendedores, Organigrama, Mural.
Activos: Laptops, Celulares, Cuentas de correo (asignación a usuarios y dispositivos).
Otros: Ideas, Tareas, Sugerencias de transportistas, Usuarios, Historial de cambios (auditoría), Cuenta demo, Configuración.

Colaborador

Los mismos módulos que el admin, pero limitados a los permisos que el admin le encienda: rutas, cotizador, cotización marítima, tipos de unidad, mensajes, embarques, finanzas, clientes, proveedores, vendedores, colaboradores, laptops, celulares, correos, ideas, tareas, historial y mural.

Transportista (carrier)

Dashboard, perfil (datos comerciales, RFC, contactos), rutas asignadas, metas por ruta, sugerencias y mensajes.

Vendedor

Dashboard, perfil, cotizaciones asignadas y colaboradores a su cargo.

Desarrollador

Dashboard, perfil y tareas.

Almacén de credenciales de activos

Las contraseñas de laptops, celulares, cuentas de correo y las notas de contraseña de colaboradores no son credenciales de acceso a la plataforma: son datos que el administrador necesita poder consultar. Por eso se cifran de forma reversible (AES-256-GCM) en vez de guardarse con hash.

La llave vive en CREDENTIALS_ENCRYPTION_KEY, fuera de la base de datos: un volcado de la BD por sí solo no revela nada.
Los listados y detalles no devuelven la contraseña, solo hasPassword. El valor se pide de uno en uno a /api/credentials/<tipo>/<id> al pulsar el ojo.
Cada revelación queda en la bitácora de auditoría como acción revealed.
Los permisos son los del módulo: quien puede leer Laptops ve sus contraseñas. El admin siempre puede.
El formato guardado es v1:<iv>:<tag>:<datos>. Los valores sin ese prefijo se tratan como texto plano heredado y se devuelven tal cual, para que la app funcione durante una migración.
Para cifrar credenciales que sigan en claro: pnpm db:encrypt-credentials (simulación) y --apply para escribir. Es idempotente.

Mural (RH)

Tablero interno visible solo para el personal de JTP (admin y colaboradores con canViewMural). Transportistas y vendedores quedan fuera.

Agenda a 60 días: cumpleaños, aniversarios, vacaciones, eventos y capacitaciones.
Cumpleaños y aniversarios no se capturan a mano: se derivan de users.birth_date y employee_profiles.hire_date. Si esas fechas están vacías, la persona no aparece.
Blog: noticias con texto enriquecido (Lexical), portada y estado borrador/publicado.
Avisos: al publicar, al cambiar la fecha o el lugar y al cancelar una entrada se crea la notificación en el dashboard de cada persona y se manda un correo con la identidad de JTP. Quien publica o edita puede apagar el envío de correo.
Felicitación personal: el día de su cumpleaños o aniversario, la persona ve confeti y un mensaje al entrar al dashboard, con un botón para repetirlo. Si no es su día, el botón ni aparece.
Celebraciones del día: un cron de Vercel (vercel.json) dispara /api/cron/mural-greetings todos los días a las 14:00 UTC (8:00 en Guadalajara). Felicita a quien cumple años o aniversario y avisa al equipo ese mismo día. No hay resumen diario ni semanal: cada entrada avisa sola al crearse, editarse o cancelarse. Protegido con CRON_SECRET.

Para que RH administre el mural, el admin le enciende los cuatro permisos de Mural; al resto del equipo le basta con leer.

Estructura del proyecto

jtplogistics/
├── prisma/
│   ├── schema.prisma    # Modelos (users, routes, shipments, mural_*, etc.)
│   ├── seed.ts          # Datos de prueba (usuarios, rutas, activos)
│   └── migrations/      # SQL versionado (se escribe a mano, ver más abajo)
├── src/
│   ├── app/
│   │   ├── (auth)/            # login, register, forgot-password, reset-password
│   │   ├── admin/dashboard/
│   │   ├── carrier/dashboard/
│   │   ├── collaborator/dashboard/
│   │   ├── vendor/dashboard/
│   │   ├── developer/dashboard/
│   │   └── api/               # auth, admin, collaborator, carrier, vendor, mural, cron
│   ├── components/
│   │   ├── ui/                # shadcn + componentes base (DataTable, DatePicker, Lexical)
│   │   └── dashboard/         # componentes por módulo
│   ├── hooks/
│   ├── lib/                   # auth, db, validators, utils, config, data, correos
│   └── types/
├── public/
├── docs/
│   ├── conventions.md              # Convenciones de BD y datos
│   └── reporte-ciberseguridad.html # Controles de seguridad (imprimible a PDF)
├── instrumentation.ts   # Normalización de BETTER_AUTH_URL al arranque
├── vercel.json          # Cron del resumen diario del mural
└── next.config.ts

La interfaz y los textos visibles están en español; el código (rutas, variables, comentarios) en inglés.

Requisitos

Node.js 22+ (es la versión que usa CI)
pnpm — el proyecto no usa npm ni yarn
PostgreSQL (local o Neon)

Variables de entorno

Crear .env en la raíz (no se commitea). Ejemplo:

# Base de datos
DATABASE_URL="postgresql://..."

# Better Auth (en producción usar el dominio final CON www)
BETTER_AUTH_SECRET="..."   # mínimo 32 caracteres (openssl rand -base64 32)
BETTER_AUTH_URL="http://localhost:3000"

# Opcional: orígenes adicionales (CSRF)
# BETTER_AUTH_TRUSTED_ORIGINS=https://www.jtplogistics.com

# Cloudinary
CLOUDINARY_CLOUD_NAME="..."
CLOUDINARY_API_KEY="..."
CLOUDINARY_API_SECRET="..."

# Resend. Sin RESEND_API_KEY los correos solo se imprimen en consola (útil en dev).
RESEND_API_KEY="..."
EMAIL_FROM="JTP Logistics <[email protected]>"

# URL pública usada en los enlaces y el logo de los correos.
# Sin ella los correos salen sin logo ni botón (no se rompen, usan un respaldo).
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Secreto del cron del resumen diario del mural. Vercel lo manda como
# "Authorization: Bearer <valor>". Si está vacío, el endpoint no exige credencial
# (cómodo en local, nunca en producción).
CRON_SECRET=""

# Llave del almacén de credenciales de activos (contraseñas de laptops,
# celulares, cuentas de correo y notas de colaborador). Generar con:
#   openssl rand -base64 32
CREDENTIALS_ENCRYPTION_KEY=""

Notas:

En Vercel, VERCEL_URL se rellena automáticamente y se usa para trustedOrigins si hace falta.
NEXT_PUBLIC_APP_URL se incrusta en el bundle durante el build: al cambiarla hay que redesplegar para que surta efecto.
⚠️ CREDENTIALS_ENCRYPTION_KEY no se puede perder. Sin ella, las contraseñas de activos guardadas quedan irrecuperables. Debe existir una copia fuera de Vercel (gestor de contraseñas o resguardo físico).

Cómo arrancar

# Instalar dependencias (también corre prisma generate)
pnpm install

# Aplicar migraciones
pnpm db:migrate:deploy

# (Opcional) Poblar datos de prueba
pnpm db:seed

# (Opcional) Sembrar configuración de portada/branding
pnpm db:seed-settings

# (Opcional) Crear cuenta demo transportista
pnpm db:create-demo-carrier

# Desarrollo
pnpm dev

Abrir http://localhost:3000. Para entrar con datos de prueba, ver el mensaje al final de pnpm db:seed (correos y contraseñas por rol).

Migraciones

pnpm db:migrate (prisma migrate dev) está roto en este proyecto: falla al crear la shadow database en Neon.

El flujo que sí funciona:

Editar prisma/schema.prisma.
Crear a mano prisma/migrations/<AAAAMMDDHHMMSS>_<nombre>/migration.sql con el SQL correspondiente.
Aplicarla con pnpm db:migrate:deploy.
Regenerar el cliente con pnpm db:generate.

Ojo: db:migrate:deploy aplica contra la base de datos de DATABASE_URL, que es la BD real compartida. Revisar el SQL antes de correrlo.

Scripts

Comando	Descripción
`pnpm dev`	Servidor de desarrollo
`pnpm build`	Build de producción
`pnpm start`	Servidor de producción
`pnpm lint`	ESLint
`pnpm test`	Pruebas con Vitest
`pnpm test:watch`	Pruebas en modo watch
`pnpm db:generate`	Generar Prisma Client
`pnpm db:migrate`	Migraciones en desarrollo (roto, ver arriba)
`pnpm db:migrate:deploy`	Aplicar migraciones
`pnpm db:seed`	Ejecutar seed
`pnpm db:seed-settings`	Seed de ajustes/configuración
`pnpm db:create-demo-carrier`	Crear cuenta demo transportista
`pnpm db:encrypt-credentials`	Cifrar credenciales de activos que sigan en claro
`pnpm db:assign-route-creator`	Asignar creador a rutas existentes
`pnpm db:sync-route-destination-states`	Sincronizar estados destino de rutas
`pnpm db:studio`	Abrir Prisma Studio

Pruebas

pnpm test corre Vitest sobre la lógica pura (sin BD ni red): coincidencia de embarques y finanzas, búsqueda, fechas de cumpleaños y aniversarios, y armado de los correos de felicitación.

Los módulos con lógica que valga la pena probar se separan de los que tocan Prisma —por ejemplo mural-celebrations.ts (puro) frente a mural-celebrations-query.ts (BD)— porque importar @/lib/db en una prueba falla si no hay DATABASE_URL.

CI (.github/workflows/ci.yml) corre en cada push y PR: typecheck, lint, test y build.

Notas de operación

Finanzas: no se recomienda el alta manual; el flujo principal es generar los registros al cerrar embarques.
Seed: inserta los tipos de incidencia sin duplicar (skipDuplicates), pero reinicia otras entidades de prueba.
Correos: todos los envíos (mural, felicitaciones, alertas de ruta, auth) salen por Resend con el remitente de EMAIL_FROM.

Despliegue (Vercel)

Conectar el repositorio a Vercel.
Configurar las variables de entorno, incluyendo DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL (con la URL final, https://www.jtplogistics.com) y CRON_SECRET.
Desplegar. El build usa pnpm build; si BETTER_AUTH_URL no trae protocolo, se normaliza a https:// al arrancar.
El cron de vercel.json queda registrado solo, sin configuración extra en el panel.

Convenciones

Reglas de base de datos, nombres y validaciones: docs/conventions.md.

En resumen: tablas y columnas en snake_case, código en camelCase, correos y slugs normalizados a minúsculas, y los roles guardados en inglés.