# Durango Energy — Documentación Completa del Proyecto

> Archivo consolidado para contexto profundo de IA. Generado para el estándar llms-full.txt.

---

## 1. Descripción General del Proyecto

**Durango Energy** es una plataforma de e-commerce y cotización especializada en productos de construcción, herraje e instalaciones de energía para el mercado mexicano. Su propósito principal es permitir que clientes industriales y particulares exploren un catálogo especializado de más de 577 productos, gestionen su carrito de forma persistente, calculen costos de envío reales y generen cotizaciones formales en PDF — todo en un único flujo integrado.

La plataforma soporta dos roles de usuario distintos:
- **Clientes:** Navegan el catálogo, gestionan su carrito, solicitan cotizaciones y consultan su historial.
- **Administradores:** Gestionan el catálogo de productos, administran cuentas de usuarios, revisan cotizaciones y monitorean ingresos desde un panel dedicado.

---

## 2. Stack Técnico

### Frontend
- **Framework:** React 18 + Vite + TypeScript
- **Estilos:** Tailwind CSS + CSS Variables (tema claro/oscuro)
- **Animaciones:** Framer Motion
- **Routing:** Wouter
- **Estado global:** Zustand (persistido en localStorage con clave `de_auth`)
- **Estado del servidor:** TanStack Query (React Query v5)
- **Generación de PDF:** jsPDF + jsPDF-autotable (client-side)
- **Iconos:** Lucide React
- **Fuentes:** Inter / Montserrat

### Backend
- **Framework:** Express 5 + TypeScript
- **Base de datos:** PostgreSQL
- **ORM:** Drizzle ORM
- **Validación:** Zod (drizzle-zod para schemas derivados de la BD)
- **Auth:** JWT (jsonwebtoken + bcryptjs), token almacenado como `de_token`
- **Correo electrónico:** Nodemailer con Gmail SMTP
- **Envíos:** Skydropx Pro API (margen del 10% aplicado automáticamente)
- **Tareas programadas:** node-cron (recordatorio de carrito abandonado cada hora)

### Monorepo
- **Gestor de paquetes:** pnpm workspaces
- **Node.js:** v24
- **Codegen de API:** Orval (genera React Query hooks y schemas Zod desde OpenAPI)
- **Bundler del servidor:** esbuild (bundle CJS)

---

## 3. Identidad de Marca

| Token | Valor | Uso |
|-------|-------|-----|
| Verde Corporativo | `#01A55E` | Color primario, CTAs, acentos positivos |
| Amarillo Energía | `#FFD900` | Color de acento, detalles de atención |
| Fondo | `#F8F9FA` | Background general de la app |
| Texto principal | `#1A1A1A` | Headings y texto de alto contraste |
| Texto secundario | `#6C757D` | Subtítulos y metadatos |

---

## 4. Estructura del Repositorio (Monorepo)

```
workspace/
├── artifacts/
│   ├── api-server/              # Servidor Express (API REST)
│   │   └── src/
│   │       ├── index.ts         # Entry point, cron jobs, middlewares globales
│   │       ├── routes/          # auth.ts, products.ts, cart.ts, addresses.ts,
│   │       │                    # quotes.ts, shipping.ts, admin.ts, reviews.ts
│   │       └── lib/
│   │           └── email.ts     # Plantillas y envío de correos (Nodemailer)
│   └── durango-energy/          # Frontend React + Vite
│       ├── public/              # Archivos estáticos (llms.txt, imágenes, favicon)
│       └── src/
│           ├── App.tsx          # Definición de rutas (Wouter)
│           ├── pages/           # Componentes de página
│           │   ├── Home.tsx
│           │   ├── Catalog.tsx
│           │   ├── ProductDetail.tsx
│           │   ├── Cart.tsx
│           │   ├── Shipping.tsx
│           │   ├── Checkout.tsx
│           │   ├── Login.tsx / Register.tsx
│           │   ├── Profile.tsx
│           │   ├── Quotes.tsx
│           │   ├── RegisterAdmin.tsx
│           │   ├── PrivacyPolicy.tsx
│           │   ├── SalesPolicy.tsx
│           │   ├── TermsConditions.tsx
│           │   └── admin/
│           │       ├── AdminDashboard.tsx
│           │       ├── AdminProducts.tsx
│           │       ├── AdminUsers.tsx
│           │       ├── AdminQuotes.tsx
│           │       └── AdminLogin.tsx
│           ├── components/      # Componentes reutilizables (Layout, UI, etc.)
│           ├── store/           # Zustand store (use-store.ts)
│           └── lib/             # Utilidades (utils.ts, formatCurrency, etc.)
├── lib/
│   ├── api-spec/                # Especificación OpenAPI + configuración Orval
│   ├── api-client-react/        # Hooks React Query generados automáticamente
│   ├── api-zod/                 # Schemas Zod generados desde OpenAPI
│   └── db/
│       └── src/schema/          # Tablas Drizzle: users, products, carts,
│                                # addresses, quotes, invites
├── scripts/                     # Utilidades de mantenimiento
└── pnpm-workspace.yaml
```

---

## 5. Esquema de Base de Datos

### `users`
| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | serial PK | Identificador único |
| nombre | text | Nombre completo |
| correo | text unique | Email (usado como username) |
| contrasena | text | Hash bcrypt de la contraseña |
| telefono | text | Teléfono de contacto (opcional) |
| tipo | text | `"EMPRESA"` o `"PARTICULAR"` |
| admin | boolean | true = administrador |
| admin_tipo | text | `"DESARROLLADOR"` o `"EMPLEADO"` |
| activo | boolean | Cuenta habilitada/bloqueada |
| created_at | timestamp | Fecha de registro |

### `products`
| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | serial PK | Identificador único |
| clave | text | SKU / clave del producto |
| nombre | text | Nombre del producto |
| descripcion | text | Descripción corta |
| specs_html | text | Especificaciones técnicas en HTML |
| precio_publico | numeric | Precio IVA incluido (÷ 1.16 para subtotal) |
| categoria | text | Categoría del catálogo |
| imagen_url | text | URL de imagen (S3) |
| activo | boolean | Visible en el catálogo |
| stock | integer | Unidades disponibles |
| opinions | jsonb | Array de reseñas de clientes |

### `carts`
| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | serial PK | Identificador único |
| user_id | integer FK | Referencia a users.id |
| items | jsonb | Array de `{ productId, quantity, nombre, precio }` |
| updated_at | timestamp | Última modificación |
| reminder_sent_at | timestamp | Marca para evitar envíos duplicados de recordatorio |

### `addresses`
| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | serial PK | Identificador único |
| user_id | integer FK | Referencia a users.id |
| nombre | text | Alias/nombre del destinatario |
| calle | text | Calle y número |
| colonia | text | Colonia/barrio |
| ciudad | text | Ciudad |
| estado | text | Estado de México |
| cp | text | Código postal |
| pais | text | País (default: México) |

### `quotes`
| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | serial PK | Identificador único |
| user_id | integer FK | Referencia a users.id |
| items | jsonb | Snapshot de los productos cotizados |
| address | jsonb | Snapshot de la dirección de entrega |
| subtotal | numeric | Suma sin IVA |
| iva | numeric | Monto de IVA (16%) |
| shipping_cost | numeric | Costo de envío seleccionado |
| total | numeric | Total final |
| estado | text | `"pendiente"` / `"completada"` / `"cancelada"` |
| created_at | timestamp | Fecha de generación |

### `invites`
| Columna | Tipo | Descripción |
|---------|------|-------------|
| id | serial PK | Identificador único |
| token | text unique | Token UUID de un solo uso |
| used | boolean | Si ya fue utilizado |
| created_at | timestamp | Fecha de creación |

---

## 6. Flujo Principal de Usuario

1. **Explorar el catálogo** (`/catalog`) — filtrar por categoría, buscar por texto.
2. **Ver producto** (`/product/:id`) — revisar especificaciones, precio con IVA, reseñas.
3. **Agregar al carrito** — el carrito persiste en la base de datos por usuario autenticado.
4. **Calcular envío** (`/shipping`) — ingresar o seleccionar dirección; se consultan tarifas reales vía Skydropx.
5. **Generar cotización** (`/checkout`) — revisión final; al confirmar se genera el PDF y se envían correos automáticos al cliente y a la empresa.
6. **Consultar historial** (`/quotes`) — listado de cotizaciones pasadas con opción de descarga.

---

## 7. Sistema de Correos Electrónicos

Al crear una cotización se envían dos emails automáticamente:

- **Email al cliente:** Resumen de la cotización con desglose de productos, subtotal, IVA, envío y total. Incluye botón para ver el carrito.
- **Email a la empresa:** Datos completos del cliente (nombre, correo, teléfono), detalle de productos y costos para seguimiento comercial.

Adicionalmente, un **cron job horario** detecta carritos inactivos por más de 24 horas y envía un recordatorio de carrito abandonado al cliente (una sola vez por abandono, controlado por `reminder_sent_at`).

---

## 8. Lógica de Precios

- `precio_publico` incluye IVA al 16%.
- **Subtotal** = `precio_publico / 1.16`
- **IVA** = `precio_publico - subtotal`
- **Total** = `subtotal + iva + shipping_cost`
- Los envíos de Skydropx se incrementan un 10% como margen operativo.

---

## 9. Sistema de Autenticación

- JWT almacenado en localStorage con clave `de_token`.
- Payload incluye: `id`, `nombre`, `correo`, `admin`, `admin_tipo`, `isAdmin`.
- Zustand store persistido con clave `de_auth` incluye el usuario como `de_user`.
- Rutas de administrador protegidas mediante middleware `requireAdmin` en el servidor.
- Tipo de admin `"DESARROLLADOR"` tiene privilegios adicionales sobre empleados.
- Registro de admins mediante tokens de invitación de un solo uso (`/register-admin?token=...`).

---

## 10. Panel de Administración

### Dashboard (`/admin`)
- Ingresos reales: suma de cotizaciones con estado `"completada"`.
- Tarjetas de resumen por estado con totales monetarios.
- Barra de progreso: ingresos confirmados vs total cotizado.

### Gestión de Productos (`/admin/products`)
- CRUD completo del catálogo.
- Activar/desactivar visibilidad por producto.
- Subida de imágenes a AWS S3.

### Gestión de Usuarios (`/admin/users`)
- Lista separada de administradores y clientes.
- Columnas: ID, Nombre, Correo, Teléfono, Tipo, Estado/Acceso.
- Bloquear/desbloquear cuentas de clientes.
- Eliminar empleados (solo rol Desarrollador).
- Generar enlaces de invitación para nuevos administradores.

### Gestión de Cotizaciones (`/admin/quotes`)
- Tabla paginada de todas las cotizaciones del sistema.
- Filtros por estado con contadores.
- Cambio de estado inline con actualización inmediata de la UI.
- Badges de color: amarillo (pendiente), verde (completada), rojo (cancelada).

---

## 11. Integraciones de Terceros

| Servicio | Propósito |
|----------|-----------|
| **Skydropx Pro** | Cálculo de tarifas de envío reales |
| **AWS S3** | Almacenamiento de imágenes de productos |
| **Gmail SMTP** | Envío de correos de cotización y recordatorios |
| **PostgreSQL** | Base de datos principal (provista por Replit) |

---

## 12. Categorías Principales del Catálogo

El catálogo de Durango Energy está organizado en las siguientes categorías de productos industriales y de construcción:

| Categoría | Descripción |
|-----------|-------------|
| **Equipos Industriales** | Maquinaria y equipo especializado para proyectos de construcción, manufactura y operación industrial. Incluye compresores, generadores, bombas y equipos de elevación. |
| **Herramientas de Construcción** | Herramientas manuales, eléctricas, neumáticas y de medición para obra civil y acabados. Incluye taladros, rotomartillos, niveles, cortadoras y accesorios. |
| **Materiales Eléctricos** | Conductores eléctricos, tableros de distribución, interruptores, contactos, canalizaciones, transformadores, protecciones y accesorios para instalaciones industriales y residenciales. |
| **Soluciones de Energía** | Paneles solares fotovoltaicos, inversores de red y de isla, baterías de almacenamiento (litio y plomo), sistemas de monitoreo, controladores de carga y accesorios para instalaciones de energía renovable. |
| **Herraje Industrial** | Tornillería, pernos, tuercas, arandelas, varillas roscadas, anclajes, elementos de fijación estructural y accesorios de sujeción para aplicaciones industriales y de construcción. |

Todos los productos tienen precios listados en **MXN con IVA al 16% incluido**. El subtotal y el IVA se desglosan en la cotización formal.

---

## 13. Consideraciones de SEO y GEO

- Plataforma orientada a clientes industriales y de construcción en México.
- Términos clave: cotización de materiales de construcción, herraje industrial, equipos de energía, presupuesto de obra, envío a toda la República Mexicana.
- Los precios incluyen IVA (16%) según la normativa fiscal mexicana.
- Documentación legal disponible: aviso de privacidad, política de ventas, términos y condiciones.