Ingeniería de Software Aplicada
Gestión de Stock de Almacenes
StockMaster API es una solución avanzada de gestión de almacenes diseñada con un enfoque riguroso en la integridad del dato. Desarrollada en Laravel 11, esta API implementa tipado estricto y una arquitectura modular para garantizar que cada movimiento de stock sea atómico, trazable y seguro.
La seguridad se integra desde el núcleo mediante OAuth2 (Passport) y un sistema RBAC de granos finos. La automatización mediante observadores de modelos asegura que la auditoría sea silenciosa pero infalible, registrando cada cambio sin afectar el rendimiento de la aplicación.
Con su motor de valoración dinámica (FIFO, LIFO, AVG) e integración nativa con MariaDB InnoDB, StockMaster está preparado para los requerimientos contables más exigentes.
Diagrama de Capas del Sistema
Vista de Gestión Operativa
Stack Tecnológico Núcleo de la Aplicación
Database
MariaDB 10.11
Motor InnoDB con soporte para transacciones ACID y Vistas de valoración.
Core Framework
Laravel 11
Estructura moderna con sistema de servicios y repositorios desacoplados.
Language
PHP 8.2+
Uso de Strict Typing y Property Promotion para un código impecable.
Auth Standard
OAuth2 / Passport
Implementación de tokens industriales para aplicaciones de alta seguridad.
RBAC System
Spatie Permission
Control de acceso granular basado en roles: Admin, Worker y Viewer.
Documentation
Scramble OpenAPI
Documentación viva 100% interactiva sin mantenimiento manual.
Quality Control
TDD (PHPUnit)
Metodología Red-Green-Refactor aplicada a cada funcionalidad crítica.
Arch Patterns
S.O.L.I.D.
Cumplimiento estricto de principios para alta mantenibilidad.
Referencia Completa de API
Listado organizado de todos los puntos de acceso con sus validaciones técnicas y roles requeridos.
Autenticación y Perfil
Registro de Usuario
Requiere name (max:255), email (unique, format) y password (min:8, upper, symbol + confirmed).
Inicio de Sesión
Requiere email (format) y password. Limitado a 5 intentos/minuto.
Perfil Actual
Retorna JSON con datos básicos y roles asociados al token Bearer.
Categorías
Listar Categorías
Retorna todas las categorías con slugs automáticos.
Nueva Categoría
Requiere name (req, max:255, unique).
Mostrar una Categoría
Acceso directo por ID numérico.
Actualizar una Categoría
Acceso directo por ID numérico.
Borrado Seguro
Falla con 422 si hay productos asociados (Restringido).
Gestión de Productos
Listar Productos
Soporta paginación. Roles: Todos.
Crear Producto
Requiere SKU único, unit_price/unit_cost (numeric, min:0) y valuation_strategy (fifo, lifo, avg).
Ver Detalle
Búsqueda por ID. Retorna relaciones de categoría y proveedor.
Actualizar
Permite actualización parcial. SKU único excluyendo actual.
Eliminar
Protección de integridad: Falla si existen movimientos o stock asociado.
Buscar por SKU
Búsqueda de producto por código SKU único.
Productos por Almacén
Lista productos disponibles en un almacén específico.
Productos por Proveedor
Lista productos asociados a un proveedor específico.
Productos por Categoría
Lista productos pertenecientes a una categoría específica.
Almacenes y Logística
Listar Almacenes
Vista resumida con nombres y ubicaciones.
Crear Almacén
Requiere name (unique, max:255), location (max:500) y capacity (min:0).
Ficha de Almacén
Acceso directo por ID numérico.
Actualizar Almacén
Acceso directo por ID numérico.
Obtiene las métricas de capacidad de un almacén.
Acceso directo por ID numérico
Búsqueda por slug
Resolución automática de modelo vía slug para URLs amigables.
Mover Stock entre almacenes
Requiere product_id, source/dest (different) y quantity (min:1). Destino debe estar ACTIVO.
Métricas Capacidad
lista de todos los almacenes, incluidas sus métricas de capacidad.
Métricas Capacidad
lista de todos los almacenes, incluidas sus métricas de capacidad y el recuento de inventario.
Eliminar un Almacén
Elimina un almacén por ID numérico. Falla si hay si hay inventario asociado.
Gestión de Proveedores
Listar Proveedores
Vista resumida con nombres, slugs y estado (is_active).
Crear Proveedor
Requiere name (unique, max:255), email, phone y address.
Ficha de Proveedor
Acceso directo por ID numérico.
Actualizar Proveedor
Acceso directo por ID numérico.
Búsqueda por slug
Resolución automática de modelo vía slug para URLs amigables.
Activar Proveedor
Marca el proveedor como activo (is_active = true).
Desactivar Proveedor
Marca el proveedor como inactivo (is_active = false).
Métricas de Rendimiento
Retorna total_products, active_products y total_inventory_value.
Eliminar un Proveedor
Elimina un proveedor por ID numérico. Falla si hay productos asociados.
Estructura Arquitectónica
Organización profesional basada en el desacoplamiento de responsabilidades.
📂 API-StockMaster/ ├── 📂 app/ │ ├── 📂 DTO/ // Contenedores inmutables de datos │ ├── 📂 Domain/Inventory/ // Capa de Dominio: Algoritmos de Stock │ │ ├── 📂 Factories/ // Creación dinámica de estrategias │ │ └── 📂 Strategies/ // Implementaciones: FIFO, LIFO, AVG │ ├── 📂 Http/ │ │ ├── 📂 Controllers/Api/ // Manejo de peticiones (Thin Controllers) │ │ └── 📂 Resources/ // Transformación a JSON OpenAPI complatible │ ├── 📂 Repositories/ // Abstracción de acceso a datos │ └── 📂 Services/ // Orquestación de Lógica de Negocio ├── 📂 database/ // Migraciones con InnoDB y Seeders modulares └── 📂 tests/ // Feature y Unit tests (PHPUnit)
Fundamentos de Ingeniería
Patrones de Diseño de Alto Nivel
Repository Pattern
Centraliza la selección de datos. Evita que la lógica de negocio dependa de Eloquent.
Service Pattern
Mantiene los controladores 100% libres de lógica de negocio.
Strategy Pattern
Inyectamos dinámicamente el algoritmo de valoración según el producto.
Observer Pattern
Garantiza auditorías silenciosas detectando eventos de base de datos.
Desacoplamiento con DTOs
Prohibimos $request->all(). Transformamos peticiones en objetos inmutables
validados.
Traslados: El Corazón Logístico
Requisitos de Almacén
Condiciones de infraestructura antes de operar.
- ✔ Almacenes Origen/Destino deben existir en sistema.
- ✔ El Almacén de Destino debe estar Activo.
- ✔ IDs de origen y destino deben ser estrictamente distintos.
Validaciones Reales
Protección contra inconsistencias de inventario.
- 📊 Suficiencia de Stock: Verificación en tiempo real del almacén emisor.
- 🏗️ Control de Capacidad: El receptor debe tener espacio físico disponible.
Fallo Atómico (Rollback)
Nuestro sistema sigue el principio de "Todo o Nada". Si durante el proceso de traslado ocurre un error (falta de stock de último minuto, pérdida de conexión o violación de capacidad), la transacción completa se deshace (Rollback).
Esto garantiza que nunca existan "items fantasmales" que salieron de un almacén pero nunca llegaron al otro.
Flujo de Ejecución Técnica
Estado del Almacén
Entorno Sandbox
Admin
admin@stockmaster.com
Password$1234Worker
worker@stockmaster.com
Password$1234Viewer
viewer@stockmaster.com
Password$1234