PlanogramSystem - Locatel

Plataforma empresarial de ingeniería retail orientada a la creación, gestión y visualización en tiempo real de planogramas comerciales 3D y análisis financiero de inventario. Pasantías

¿Buscas el prototipo? Este repositorio es la versión completa (Next.js + SQL Server). El prototipo inicial en HTML/JS puro, que funciona sin backend, está en planogramademo y se puede probar en vivo en planogramademo.vercel.app.

---

Capturas

Inicio de sesión	Mis Tiendas
Góndolas por tienda	Editor 3D

_{Datos de demostración. Haz clic en una captura para verla en tamaño completo.}

---

Funcionalidades Principales

• Control de Acceso: Inicio de sesión con contraseñas cifradas (bcrypt) y sesiones basadas en JWT (Access Token de 15 min + Refresh Token de 7 días con renovación automática).
• Gestión de Tiendas: Creación, edición y eliminación de sucursales, con opción de clonar la distribución de góndolas de una tienda existente.
• Gestión de Góndolas: Mobiliario por tienda con pasillo, categoría y descripción; filtros por pasillo/categoría y duplicado de góndolas.
• Editor 3D Interactivo: Configuración de tipo de mobiliario, dimensiones, niveles y zócalo; colocación de productos con Drag & Drop, frentes (facings), alineación automática y deshacer/rehacer.
• Catálogo SAP: Búsqueda de productos por nombre o SKU, agrupados por categoría, con importación desde Excel.
• Análisis Financiero: Capacidad total en unidades, valorización en Bolívares (Bs.) y porcentaje de ocupación lineal por góndola.
• Reportes: Informes detallados en PDF y hojas de cálculo consolidadas en Excel, por góndola y por tienda (Reporte Global).

---

Arquitectura y Stack Tecnológico

El sistema ha sido estructurado con tecnologías de última generación para garantizar la escalabilidad, el alto rendimiento y la máxima fidelidad visual:

• Entorno de Ejecución (Runtime): Bun 1.1 para operaciones ultrarrápidas, gestión eficiente de dependencias y ejecución de scripts (también compatible con Node.js + npm).
• Framework Principal: Next.js 14 (App Router) en conjunto con React 18 y TypeScript para un desarrollo estructurado y libre de errores en tiempo de compilación.
• Gestión de Estado Global: Zustand para la manipulación y reactividad óptima del editor 3D en el cliente, evitando re-renderizados costosos.
• Estilos y Sistema de Diseño: Tailwind CSS para una interfaz moderna, limpia, cohesiva y responsiva con la paleta de identidad corporativa de Locatel.
• Persistencia y ORM: Microsoft SQL Server 2022 acoplado mediante Prisma ORM, asegurando integridad referencial estricta y consultas optimizadas.
• Autenticación: bcryptjs para el cifrado de contraseñas y JWT en cookies httpOnly, validados por el middleware de Next.js.
• Generadores de Reportes: jsPDF (con jspdf-autotable) para informes técnicos vectoriales y XLSX (SheetJS) para hojas de cálculo financieras detalladas.

---

Lógica de Negocio y Moneda Nacional (Bs.)

• Representación Monetaria: Todos los costos, valorizaciones de góndolas, subtotales de niveles y resúmenes consolidados financieros en pantalla se representan en Bolívares (Bs.).
• Exportación Coherente: Tanto las descargas de reportes técnicos detallados en PDF como las hojas de cálculo consolidadas de compras generadas en Excel adoptan la nomenclatura de Bolívares (Bs.) y formateo numérico localizado para las columnas de costo unitario y total.

---

Guía de Instalación y Despliegue

La solución soporta dos entornos: Desarrollo Local (híbrido con base de datos en Docker) y Producción en Contenedores (completamente Dockerizado).

Requisitos Previos

• Docker Desktop instalado y en ejecución.
• Bun instalado localmente (si vas a ejecutar en modo desarrollo). Alternativamente, Node.js 18+ con npm.

---

Opción A: Configuración para Desarrollo Local (Recomendado)

En este modo, la base de datos SQL Server corre dentro de un contenedor Docker, mientras que la aplicación web corre localmente en tu sistema operativo utilizando Bun para agilizar el desarrollo.

1. Levantar la Base de Datos: Copia la plantilla docker-compose.example.yml como docker-compose.yml, define tu propia contraseña en MSSQL_SA_PASSWORD e inicia únicamente la instancia de SQL Server:

   docker compose up db_planogramas -d

   Nota: La base de datos estará disponible externamente en el puerto 14333.

2. Configurar Variables de Entorno: Crea un archivo .env en la raíz del proyecto (está ignorado por Git) apuntando al puerto externo de la base de datos. Usa la misma contraseña que definiste en el paso anterior:

   DATABASE_URL="sqlserver://127.0.0.1:14333;database=PlanogramaDB;user=sa;password=TU_CONTRASEÑA_SEGURA;encrypt=true;trustServerCertificate=true;"
   
   # Opcional en desarrollo, obligatorio en producción
   JWT_ACCESS_SECRET="una-cadena-larga-y-aleatoria"
   JWT_REFRESH_SECRET="otra-cadena-larga-y-aleatoria"

   ⚠️ Si no defines JWT_ACCESS_SECRET y JWT_REFRESH_SECRET, la aplicación usa valores por defecto incluidos en el código. Define siempre tus propios secretos fuera del entorno local. ⚠️

3. Instalar Dependencias: Descarga los paquetes necesarios utilizando Bun:

   bun install

4. Sincronizar Esquema y Cliente Prisma: Genera el cliente Prisma y empuja el esquema relacional a la base de datos de SQL Server:

   bun run prisma:generate
   bun run prisma:db

5. Crear el Usuario Administrador: Inserta el usuario inicial con contraseña cifrada:

   bun src/scripts/seed.ts

   Credenciales de desarrollo: admin / admin123..

   ⚠️ Estas credenciales son solo para desarrollo local. Cámbialas antes de desplegar en cualquier entorno compartido. ⚠️

6. Iniciar Servidor de Desarrollo: Lanza el servidor de Next.js localmente:

   bun run dev

   Accede al sistema desde http://localhost:3000.

7. (Opcional) Cargar Productos de Demostración: Con la sesión iniciada como administrador, visita http://localhost:3000/api/seed-products para cargar 30 productos de ejemplo en el catálogo.

¿Usas npm en lugar de Bun?

Los pasos son los mismos, cambiando los comandos:

npm install
npm run prisma:generate
npm run prisma:db
npx tsx src/scripts/seed.ts
npm run dev

---

Opción B: Despliegue Completo en Producción (Docker Compose)

Para desplegar la aplicación completa (Base de datos SQL Server + Servidor Web de Producción Next.js) en contenedores Docker autónomos:

1. Construir y compilar la Imagen Web: Compila la imagen local de Next.js ejecutando Docker en la raíz del proyecto:

   docker build -t planograma:v0.1.0 -f ./docker/Dockerfile .

2. Levantar el Stack de Producción: Inicia todos los servicios configurados en el orquestador:

   docker compose up -d

3. Monitorear Contenedores: Asegúrate de que los contenedores estén activos:

   docker compose ps

   La aplicación estará disponible de forma unificada en el puerto 3000.

---

Estructura del Código Fuente

/
├── prisma/                  # Esquema Prisma relacional e histórico de migraciones
├── docker/                  # Configuración de Dockerfile optimizado para producción con Alpine
├── docs/
│   └── screenshots/         # Capturas de pantalla usadas en este README
├── public/                  # Recursos estáticos (Logos, imágenes, iconos)
├── src/
│   ├── app/                 # Enrutamiento de Next.js (App Router) y APIs REST
│   │   ├── login/             # Pantalla de inicio de sesión
│   │   ├── stores/            # Listado de tiendas y detalle de góndolas por tienda
│   │   ├── editor/[gondolaId]/# Editor 3D de una góndola
│   │   └── api/               # Endpoints REST (auth, stores, gondolas, products)
│   ├── components/          # Componentes visuales y lógica modular del Planograma
│   │   ├── LoginPage.tsx      # Lógica y maquetación de control de acceso
│   │   ├── StoresDashboard.tsx# Vista y gestión de sucursales a nivel comercial
│   │   ├── StoreDetails.tsx   # Reporte consolidado financiero y de inventarios
│   │   └── PlanogramEditor.tsx# Editor visual 3D interactivo y lógica de estanterías
│   ├── scripts/             # Scripts de inicialización (usuario administrador)
│   ├── store/               # Stores de Zustand para estado global reactivo
│   ├── types/               # Tipos de TypeScript e interfaces del dominio
│   ├── utils/               # Helpers matemáticos, colisiones 3D, JWT y lógica de exportación
│   └── middleware.ts        # Protección de rutas y renovación automática de sesión
├── .gitignore               # Configuración de exclusiones de Git (Seguridad)
├── docker-compose.example.yml # Plantilla de Docker Compose (sin credenciales reales)
├── package.json             # Manifiesto de scripts y dependencias
└── README.md                # Documentación oficial de la plataforma

---

🔗 Proyectos Relacionados

• planogramademo: prototipo funcional en HTML/CSS/JS con persistencia en localStorage, sin backend. Demo en vivo: planogramademo.vercel.app (credenciales de prueba admin / planodemo).