API REST para gestión de pedidos y facturación B2B (mayorista).
Sistema completo con manejo de stock reservado, ciclo de vida de facturas y operaciones transaccionales.
Sin ORM - queries SQL puras.

Sistemas B2B mayoristas necesitan:

• ✅ Reservar stock cuando un pedido se confirma (no cuando se paga)
• ✅ Liberar stock si el pedido se cancela
• ✅ Descontar stock real solo al entregar
• ✅ Todo dentro de transacciones ACID para que no haya inconsistencias

Este proyecto implementa exactamente eso, con SQL puro y sin ORM.

• Node.js + Express
• MySQL (mysql2/promise)
• bcrypt
• crypto (tokens)
• dotenv
• jsonwebtoken (JWT)

src/
├── handlers/          # Controladores (req/res)
├── utils/             # Validaciones, query builders
├── config/            # DB connection pool
├── middlewares/       # auth, adminOnly, activeClientOnly
├── routes/            # Definición de endpoints
└── server.js          # Configuración Express

Routes → Middlewares → Handlers → Utils → Database

• Separar responsabilidades
• Reutilizar lógica (query builders, validaciones)
• Mantener el código limpio y testeable
• Control de acceso por roles (admin / cliente)

• JWT para proteger rutas sensibles
• authMiddleware → verifica token y busca el estado actual del cliente en DB
• adminOnly → restringe rutas a usuarios con is_admin = true
• activeClientOnly → solo permite operaciones de escritura a clientes con status = 'active'
• El status no se guarda en el token, se consulta en cada request (consistencia garantizada)

• Helpers en utils/validations.js
• Validación de UUID, email, password, token, etc.
• Whitelist de columnas permitidas para búsquedas dinámicas
• Validación de enums (status, payment_terms)

• stock → stock físico real
• reserved_stock → stock reservado en pedidos confirmados
• Ciclo: draft → confirm (reserva) → deliver (descarga)

• Confirmación: valida stock, reserva, genera número/fechas
• Entrega: descuenta stock real y libera reserva
• Cancelación: libera stock reservado

• Un solo invoice por cliente en draft
• Items en invoice_items
• Cantidad 0 = eliminar item

• Arquitectura en capas
• Queries SQL puras (sin ORM)
• Placeholders parametrizados (SQL injection safe)
• UUID como primary keys
• Hash de contraseñas con bcrypt
• Token de verificación con crypto
• JWT con middlewares de autenticación y roles
• Soft delete con is_active / status
• Búsquedas dinámicas con whitelist
• Rangos numéricos y de fechas (BETWEEN, >=, <=)
• Batch updates (INSERT ... ON DUPLICATE KEY UPDATE)
• Transacciones SQL (BEGIN / COMMIT / ROLLBACK)
• Manejo de errores consistente
• Documentación con devlog.md y CHANGELOG.md

git clone https://github.com/DarioFGonzalez/fullstack-express-mysql-raw.git
cd fullstack-express-mysql-raw/server
npm install
cp .env.example .env
npm run dev

• Paginación en listados
• Webhook real de pagos (MercadoPago)
• Dashboard de administración
• Tests unitarios y de integración
• Documentación con Swagger

Dario Fernando Gonzalez