Senselab Core API 🚀

Desarrollado por Senselab
"No hacemos cualquier cosa. Hacemos cosas con sentido."
SenseLab, tecnología versátil con alma costarricense 🇨🇷

📋 Tabla de Contenidos

� Curso Completo y Glosario

¿Nuevo en el proyecto? Estos dos documentos te llevarán de cero a experto en la API completa.

Documento	Descripción
📘 Curso Completo: De Cero a Experto	Curso autodidacta integral — arquitectura, módulos, seguridad, testing, despliegue, IA, facturación electrónica y roadmap
📗 Glosario Completo de Terminología	Referencia exhaustiva de toda la terminología: modelos, servicios, DTOs, traits, eventos, jobs, observers, config y más

�🚀 Acerca del Proyecto

Senselab Core API es un sistema ERP empresarial completo desarrollado por Senselab con Laravel 12 y tecnologías modernas, diseñado específicamente para empresas costarricenses que requieren soluciones tecnológicas robustas, escalables y seguras.

Este proyecto representa más de 5 años de evolución en sistemas empresariales, implementando las mejores prácticas de desarrollo, seguridad y escalabilidad. Es la base tecnológica para la transformación digital de empresas medianas y grandes en Costa Rica.

🎯 Misión del Proyecto

Proporcionar una plataforma ERP integral, moderna y asequible que permita a las empresas costarricenses:

✅ Cumplir con normativas locales (DGT, HACIENDA, CAJA)
✅ Optimizar procesos operacionales
✅ Mejorar toma de decisiones con IA y análisis de datos
✅ Escalar sin limitaciones técnicas
✅ Integrar fácilmente con otros sistemas

📊 Estado del Proyecto

🔍 ÚLTIMA AUDITORÍA: 13 de Abril 2026 — Puntuación: 9.2/10 ⭐

📈 Estadísticas Verificadas (Abril 2026):

✅ 95 Controladores API implementados (100% completitud)
✅ 80 Policies RBAC implementadas (100% cobertura)
✅ Rutas API particionadas en 16 archivos (routes/api/)
✅ 98 Modelos Eloquent sincronizados con BD MySQL 8.0+
✅ 103 Migraciones de base de datos
✅ 81 Resources para transformación de respuestas JSON
✅ 159 Archivos de Tests — 1,261+ tests, 0 failing
✅ 67 Servicios incluyendo 10 servicios de IA integrados
✅ 63 DTOs (~65% cobertura de validación)
✅ 96 Factories para testing
✅ 0 Errores Críticos de base de datos o seguridad
✅ Sistema RBAC completo (68 permisos + 8 roles)
✅ PHPStan Level 8 — 0 errores
✅ Entorno Docker completamente funcional (Nginx, PHP-FPM, MySQL, Redis, PHPMyAdmin, Mailhog)
✅ Facturación Electrónica v4.4 implementada (XAdES-EPES) según normativa DGT — 38/38 brechas resueltas
✅ Módulo de IA con 10 servicios y 32+ endpoints (Google Gemini gratuito + fallback OpenAI)
✅ Generador de Módulos make:erp-module para crear módulos completos en segundos
✅ Calidad de Código PHPStan nivel 8 — 0 errores
✅ Cache Inteligente Redis con estrategia integral de cacheo
✅ Performance Optimización continua con tests de rendimiento
✅ Tests 1,261+ tests — 100% passing
✅ Seguridad Laravel Sanctum + RBAC + Rate Limiting + CORS + Encriptación AES-256
✅ API Versionado con prefijo /api/v1/ y /api/v2/ + header-based versioning + Sunset middleware
✅ Webhooks Event-Driven — 5 eventos, HMAC-SHA256, retry exponencial
✅ Reporting Engine — Dashboard KPIs, reportes financieros, exportación PDF/Excel/CSV
✅ Escalabilidad — Read Replicas, Laravel Horizon, ETags, OpenTelemetry distributed tracing
✅ Roadmap 100% — 22 fases completadas ✅

✅ FUNCIONALIDADES IA IMPLEMENTADAS (Febrero 2026):

✅ OCR de Facturas - Escaneo automático con Gemini Vision (92% precisión)
✅ Chatbot ERP - Asistente virtual con consultas en lenguaje natural
✅ Predicciones de Inventario - Análisis de demanda y alertas automáticas de stock
✅ Detección de Anomalías - Fraudes, errores contables, transacciones sospechosas (95% precisión)
✅ Generación de Contenido - Emails de cobro, agradecimiento, reportes automáticos
✅ Clasificación CABYS - Códigos tributarios automáticos para Costa Rica (98% precisión)
✅ Credit Scoring - Calificación de riesgo crediticio de clientes (0-100 basado en histórico)
✅ Análisis Financiero - Ratios, tendencias y proyecciones automáticas
✅ Optimización de Rutas - Para módulo de transporte (cuando esté disponible)
✅ Recomendaciones Inteligentes - Sugerencias de productos y clientes

✨ Características Principales

🔐 Autenticación y Autorización Avanzada

✅ Laravel Sanctum para autenticación segura por tokens API
✅ Sistema RBAC (Role-Based Access Control) con 68 permisos granulares
✅ 8 Roles predefinidos con permisos configurables:
- 👑 Administrador (acceso total)
- 💼 Gerente (gestión operacional)
- 📊 Contador (contabilidad)
- 🛍️ Vendedor (ventas)
- 📦 Comprador (compras)
- 📦 Bodeguero (inventario)
- 👤 Usuario (acceso básico)
- 🔍 Auditor (solo lectura en auditoría)
  
  Nota: Los 8 roles están definidos en RolesSeeder.
✅ Middleware CheckPermission para protección de rutas
✅ Métodos helper en modelo Usuario para validaciones RBAC
✅ Soporte para múltiples tokens por usuario
✅ Rate limiting por usuario y endpoint

💰 Facturación Electrónica Completa

✅ Emisión de comprobantes electrónicos según normativa DGT v4.4
✅ Generación automática de claves numéricas de 50 caracteres (validadas)
✅ Construcción de XML v4.4 (facturas, tiquetes, notas crédito/débito)
✅ Firma digital XAdES-EPES con certificados .p12 nativo
✅ Integración completa con Hacienda (OAuth 2.0 + Rate limiting)
✅ Procesamiento asíncrono con Laravel Queue (envío + consulta + respuesta)
✅ 7 endpoints REST API completos (CRUD + download XML + reenviar + anular + estadísticas)
✅ Ambientes configurables: Sandbox (ATV) y Producción
✅ Recepción de comprobantes electrónicos de proveedores
✅ Gestión de consecutivos automática y segura
✅ Integración con códigos CAByS (Clasificación de Actividades Económicas)
✅ Soporte para tipos: 01 (Factura), 02 (Nota Débito), 03 (Nota Crédito), 04 (Tiquete)
✅ Retry automático con backoff exponencial
✅ Estado de sincronización en tiempo real
📘 Guías completas: FACTURACION_ELECTRONICA_SETUP.md | FACTURACION_ELECTRONICA_API.md

📦 Gestión de Inventario Inteligente

✅ Control multi-almacén con soporte para ilimitados almacenes
✅ Seguimiento de stock en tiempo real (actualización instantánea)
✅ Gestión de entradas y salidas de inventario con auditoría
✅ Transferencias entre almacenes con validación de stock
✅ Kardex detallado por producto con histórico completo
✅ Clasificación de productos (categorías, códigos internos)
✅ Alertas automáticas cuando stock llega a mínimo
✅ Predicción de demanda con IA
✅ Soporte para variantes y atributos de productos
✅ Costo promedio y valuación FIFO

📊 Contabilidad Profesional

✅ Plan de cuentas configurable (5 dígitos según normativa costarricense)
✅ Asientos contables automáticos y manuales
✅ Cuentas por cobrar con seguimiento automático
✅ Cuentas por pagar con gestión de vencimientos
✅ Caja chica con control y reembolsos
✅ Reportes financieros (Estado de Resultados, Balance General, Flujo de Caja)
✅ Cierre contable automático y auditable
✅ Pistas de auditoría completas en cada asiento
✅ Soporte multi-moneda (colones, dólares, etc.)
✅ Integración con facturación (asientos automáticos)

👥 Recursos Humanos y Nómina

✅ Gestión de empleados completa con fotograma y documentos
✅ Cálculo de nómina automático y flexible
✅ Deducciones y bonificaciones configurables
✅ Periodos de pago personalizables
✅ Integración con CAJA (Costa Rica)
✅ Liquidación de empleados automática
✅ Reportes de nómina detallados
✅ Gestión de incapacidades y ausencias
✅ Historial laboral completo del empleado

🚌 Gestión de Transporte (Especializado)

✅ Gestión de rutas y horarios
✅ Control de flota de buses
✅ Asignación de unidades
✅ Ventas de boletos integradas
✅ Reportes de ocupación

🏢 Multi-Tenancy Avanzada

✅ Soporte para múltiples empresas en una sola instalación
✅ Aislamiento completo de datos por tenant
✅ Configuraciones independientes por empresa
✅ Bases de datos separadas por tenant (opcional)
✅ Domain mapping flexible
✅ Switching instantáneo entre tenants
📘 Guía de multi-tenancy: Ver config/multitenancy.php

🤖 Inteligencia Artificial Integrada

✅ 10 Servicios de IA implementados
✅ 32+ Endpoints IA bajo /api/ai/
✅ Google Gemini 2.0 Flash (gratuito + estable)
✅ OpenAI GPT-4 como fallback
✅ Procesamiento de imágenes (OCR de facturas)
✅ Análisis de texto (clasificación, resumen)
✅ Predicciones numéricas (demanda, riesgo)
✅ Cache inteligente para respuestas IA
✅ Rate limiting para servicios de IA

📚 Stack Tecnológico

Backend

Laravel 12.x - Framework PHP moderno y elegante
PHP 8.4+ - Lenguaje de programación
MySQL 8.0+ - Sistema de gestión de base de datos
Redis 7.0+ - Cache y sesiones en memoria
ElasticSearch (opcional) - Búsqueda avanzada

Frontend & Assets

Vite.js - Build tool moderno y rápido
Tailwind CSS (si aplica) - Utilidades de estilo
Alpine.js (si aplica) - JavaScript ligero interactivo
Axios - Cliente HTTP para JavaScript

DevOps & Infrastructure

Docker - Containerización y desarrollo consistente
Docker Compose - Orquestación local de servicios
Nginx - Servidor web de alto rendimiento
PHP-FPM - Gestor de procesos PHP
GitHub Actions - CI/CD automatizado
Kubernetes (ready) - Orquestación en producción

Testing & Quality

PHPUnit - Framework de testing PHP
PHPStan - Análisis estático de código (nivel 8, 0 errores)
PHP CS Fixer - Formateo automático de código PSR-12
PHPMD - Detector de problemas comunes
PHPCPD - Detector de código duplicado
SonarQube - Análisis de calidad integral

Librerías Principales

Spatie Multitenancy - Multi-tenancy robusto
Laravel Sanctum - Autenticación API
Laravel Pennant - Feature flags
LFlamSparrow L5-Swagger - Documentación OpenAPI
DOMPdf - Generación de PDFs
Spatie Image - Procesamiento de imágenes
Google Gemini API - Inteligencia Artificial (gratuito)
OpenAI SDK - OpenAI como fallback
Sentry - Monitoreo de errores

💻 Requisitos del Sistema

Requisitos Mínimos

PHP: >= 8.4
Composer: >= 2.5
Node.js: >= 18.x (20.x o 22.x recomendado)
NPM/PNPM: >= 9.x (usamos PNPM por seguridad)
MySQL: >= 8.0 o MariaDB: >= 10.6
Redis (recomendado para producción): >= 7.0

Extensiones PHP Obligatorias

- OpenSSL              (criptografía)
- PDO                  (base de datos)
- Mbstring             (strings multibyte)
- Tokenizer            (parsing PHP)
- XML                  (procesamiento XML)
- Ctype                (clasificación de caracteres)
- JSON                 (soporte JSON)
- BCMath               (matemática arbitraria)
- Fileinfo             (tipo de archivos)

Extensiones PHP Recomendadas

- GD o Imagick         (procesamiento de imágenes)
- Intl                 (internacionalización)
- xdebug               (debugging - solo desarrollo)
- APCu                 (caché de opcode)

Requisitos de Sistema Operativo

OS	Versión	Estado
Ubuntu	20.04 LTS, 22.04 LTS, 24.04 LTS	✅ Recomendado
Debian	11, 12	✅ Soportado
CentOS/RHEL	8, 9	✅ Soportado
macOS	12+, Apple Silicon	✅ Soportado
Windows	10/11 + WSL2	✅ Con Docker

Requisitos de Hardware

Desarrollo Local:

CPU: 2+ cores
RAM: 4GB mínimo, 8GB recomendado
Disco: 5GB disponibles

Staging/Producción:

CPU: 4+ cores
RAM: 16GB mínimo, 32GB+ recomendado
Disco: 50GB+ SSD (según volumen de datos)
Ancho de banda: 10Mbps+

Requisitos de Red

Puerto 80/443 (HTTP/HTTPS) - API
Puerto 3306 (MySQL) - Base de datos
Puerto 6379 (Redis) - Cache
Puerto 8025 (Mailhog - solo desarrollo)

🔄 Versiones Soportadas

Ciclo de Vida

Versión	Rama	Status	Lanzamiento	Soporte
5.0.1	`main`	🟢 Activa	Abr 2026	Indefinido
4.x	`v4.x`	🟡 Mantenimiento	Mar 2026	Solo críticos
3.x	`v3.x`	🔴 EOL	Mar 2026	Finalizado
2.x	`v2.x`	🔴 EOL	Mar 2026	Finalizado
1.0	`v1.0`	🔴 EOL	Ene 2026	Finalizado

Compatibilidad de Navegadores

Para acceso a Swagger UI y dashboards:

Navegador	Versión	Estado
Chrome	120+	✅ Full support
Firefox	121+	✅ Full support
Safari	17+	✅ Full support
Edge	120+	✅ Full support

Compatibilidad de Herramientas

Laravel: 12.x
PHP: 8.4+
MySQL: 8.0+, 8.4 recomendado
PostgreSQL: No soportado en v1.0 (futuro)

✅ Cache optimizado en todos los controllers API con trait HasCacheableQueries
Controllers implementados: 95 (100% completitud)
TTL Strategy: Optimizado desde 10min a 24h según volatilidad
Tags por área: 58 tags únicos para invalidación granular

✅ SPRINT 7 - Completitud Controllers y Policies (COMPLETADO) 🎯

95 Controllers implementados (100% completitud)
80 Policies implementadas (100% cobertura RBAC)
Cache strategy contextual (5min - 24h TTL)
OpenAPI completo en todos los endpoints

✅ FASE 11 - Facturación Electrónica Costa Rica (COMPLETADA) 🇨🇷

Sistema completo de facturación electrónica según normativa DGT v4.4
10 Fases implementadas al 100%:
1. ✅ Configuración (.env + config/hacienda.php)
2. ✅ Base de datos (4 tablas: comprobantes, lineas_detalle, certificados, tokens)
3. ✅ Servicios base (HaciendaApiClient + OAuth + RateLimiter)
4. ✅ Generador de claves numéricas (50 caracteres - validado)
5. ✅ Constructor XML v4.4 (facturas, notas crédito/débito, tiquetes)
6. ✅ Firma digital XAdES-EPES (certificados .p12)
7. ✅ Jobs asíncronos (EnviarComprobante + ConsultarEstado + ProcesarRespuesta)
8. ✅ API REST (7 endpoints: CRUD + XML download + reenviar + anular + stats)
9. ✅ Tests automatizados
10. ✅ Documentación completa (Setup + API Reference + Troubleshooting)
Integración Hacienda: OAuth 2.0 + Rate limiting + Retry automático
Ambientes: Sandbox (ATV) y Producción configurables
Ver documentación: FACTURACION_ELECTRONICA_SETUP.md | FACTURACION_ELECTRONICA_API.md

🔑 Credenciales de Prueba

Después de ejecutar los seeders, puedes iniciar sesión con:

Email: [email protected]
Password: admin123

Este usuario tiene acceso completo con 68 permisos (todos los módulos del sistema).

🏢 Sobre Senselab

En SenseLab no vendemos software a la fuerza. Escuchamos, exploramos y luego construimos con sentido. Si busca un aliado tecnológico que entienda tanto de servidores como de píxeles, de bases de datos como de narrativa interactiva, hablemos.

"No hacemos cualquier cosa. Hacemos cosas con sentido." — SenseLab, tecnología versátil con alma costarricense.

Nuestros Servicios:

✨ Soluciones Tecnológicas Empresariales
💻 Desarrollo de Software (ERP, CRM, Sistemas a Medida)
🎨 Diseño Web Profesional
🖼️ Diseño Gráfico Corporativo

🎯 Capacidades del Sistema

Este ERP proporciona gestión integral de:

Autenticación y Autorización (Laravel Sanctum + RBAC con 68 permisos granulares)
Facturación Electrónica (integración completa con DGT/Hacienda de Costa Rica)
Inventario Multi-Almacén (control en tiempo real)
Contabilidad (plan de cuentas, asientos, reportes financieros)
Recursos Humanos y Nómina (gestión completa de empleados)
Gestión de Transporte (módulo especializado para empresas de buses)
Multi-Tenancy (soporte para múltiples empresas en una sola instalación)

El sistema está diseñado con las mejores prácticas de desarrollo, siguiendo los estándares de Laravel y con enfoque en escalabilidad, seguridad y facilidad de mantenimiento.

🔧 Instalación

📘 Para colaboradores nuevos: Revisa la Guía de Instalación Completa con instrucciones paso a paso, troubleshooting y verificación.

🐳 Instalación con Docker (Recomendado): Ve directamente a la sección Instalación con Docker o consulta la Guía Docker completa.

Opción A: Instalación con Docker 🐳 (Recomendada)

La forma más rápida y confiable de iniciar el proyecto en cualquier sistema operativo.

Instalación Automática

# 1. Clonar repositorio
git clone https://github.com/SenseLab-dev/Senselab_Core_API.git
cd Senselab_Core_API

# 2. Dar permisos al script
chmod +x docker/docker-start.sh

# 3. Ejecutar instalación completa (todo automático)
./docker/docker-start.sh

El script automáticamente:

✅ Verifica Docker y Docker Compose
✅ Construye contenedores optimizados
✅ Crea archivo .env
✅ Instala dependencias de Composer
✅ Genera APP_KEY
✅ Ejecuta migraciones y seeders
✅ Genera documentación Swagger
✅ Configura permisos

Usando Makefile

# Ver todos los comandos disponibles
make help

# Instalación completa en un comando
make install

# Comandos útiles
make up              # Iniciar contenedores
make down            # Detener contenedores
make logs            # Ver logs
make shell           # Acceder a shell de PHP
make test            # Ejecutar tests
make swagger         # Regenerar Swagger

Servicios Disponibles

Servicio	URL	Credenciales
API	http://localhost:8000	-
Swagger	http://localhost:8000/api/documentation	-
PHPMyAdmin	http://localhost:8080	senselab_user / senselab_password
Mailhog	http://localhost:8025	-

📖 Guía completa: DOCKER_GUIDE.md

Opción B: Instalación Manual (Tradicional)

1. Clonar el Repositorio

# Desde GitHub
git clone https://github.com/SenseLab-dev/Senselab_Core_API.git
cd Senselab_Core_API

# O desde GitHub Organization oficial
git clone https://github.com/SenseLab-dev/Senselab_Core_API.git
cd Senselab_Core_API

2. Instalar Dependencias

# Dependencias de PHP
composer install

# Dependencias de Node.js (usamos pnpm por seguridad)
pnpm install

3. Configurar Variables de Entorno

# Copiar archivo de ejemplo
cp .env.example .env

# Generar key de aplicación
php artisan key:generate

4. Configurar Base de Datos

Edita el archivo .env con tus credenciales:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=api_db
DB_USERNAME=senselab_user
DB_PASSWORD=senselab_password

5. Ejecutar Migraciones y Seeders

# Ejecutar migraciones
php artisan migrate

# Publicar migraciones de Sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

# Ejecutar seeders (carga 112 registros: 96 datos maestros + 16 datos demo)
php artisan db:seed

# O todo junto (fresh install)
php artisan migrate:fresh --seed

Seeders incluidos:

RegimenesTributariosSeeder - 2 regímenes tributarios
FormasPagoSeeder - 6 formas de pago
TiposCuentasSeeder - 8 tipos de cuentas contables
UnidadesMedidaSeeder - 11 unidades de medida
PermisosSeeder - 68 permisos del sistema (17 módulos)
RolesSeeder - 8 roles (Administrador, Gerente, Contador, Vendedor, Comprador, Bodeguero, Usuario, Auditor)
CargosSeeder - 7 cargos de empleados
EmpresaDemoSeeder - Empresa demo "Senselab" + sucursal
UsuarioAdminSeeder - Usuario admin con todos los permisos

Total de registros: 112 (96 datos maestros + 16 datos demo/test)

6. Compilar Assets

# Desarrollo
pnpm run dev

# Producción
pnpm run build

7. Iniciar Servidor de Desarrollo

php artisan serve

El sistema estará disponible en http://localhost:8000

Credenciales de Acceso

Después de ejecutar los seeders, inicia sesión con:

Email: [email protected]
Password: admin123

Este usuario tiene acceso completo a todos los módulos (68 permisos).

🧪 Cómo Probar la API

Opción 1: Swagger UI (Recomendada) ⭐

La forma más fácil de probar todos los endpoints:

http://localhost:8000/api/documentation

Guía completa: COMO_PROBAR_API.md

Opción 2: Postman / Thunder Client / Insomnia

Herramientas profesionales para desarrollo de APIs.

Opción 3: cURL (Terminal)

# 1. Login (obtener token)
curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "admin123"
  }'

# 2. Usar el token
curl -X GET http://localhost:8000/api/productos \
  -H "Authorization: Bearer TU_TOKEN_AQUI" \
  -H "Accept: application/json"

📖 Guía completa con todas las opciones: COMO_PROBAR_API.md

⚙️ Configuración

Configuración de Multi-Tenancy

El sistema utiliza el paquete spatie/laravel-multitenancy. La configuración se encuentra en config/multitenancy.php.

Identificación del tenant

Header obligatorio: X-Empresa-Id (ID numérico de la empresa) cuando se consume desde localhost u orígenes sin subdominio dedicado.
Subdominios: también puedes apuntar a https://{subdominio}.api.senselab.com; el tenant_finder detectará automáticamente la empresa usando el parámetro TENANT_BASE_DOMAIN (definido en .env).
Ambos métodos validan que el usuario autenticado pertenezca al mismo empresa_id para evitar accesos cruzados.

Configuración de Base de Datos

Cada tenant (empresa) tiene su propia base de datos. El nombre se genera automáticamente:

tenant_{empresa_id}_{nombre_sanitizado}

Configuración de Facturación Electrónica

Para habilitar la facturación electrónica, configura:

HACIENDA_API_URL=https://api.comprobanteselectronicos.go.cr
HACIENDA_API_TOKEN=tu_token_de_hacienda

Cada empresa debe cargar su certificado de firma digital en el sistema.

🏗️ Arquitectura

Estructura de Directorios

senselab-core-api/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── API/          # Controladores de API
│   ├── Models/               # Modelos Eloquent
│   ├── Providers/            # Service Providers
│   └── Traits/               # Traits reutilizables
│       └── BelongsToTenant.php
├── config/                   # Archivos de configuración
├── database/
│   ├── migrations/
│   │   ├── landlord/        # Migraciones del sistema central
│   │   └── tenant/          # Migraciones de tenants
│   └── factories/           # Factories para testing
├── routes/
│   ├── api.php              # Rutas de API
│   └── web.php              # Rutas web
└── tests/                   # Tests automatizados

Patrón de Diseño

El proyecto sigue el patrón MVC (Model-View-Controller) con algunas extensiones:

Models: Lógica de negocio y relaciones de datos
Controllers: Manejo de requests HTTP
Traits: Comportamiento compartido (ej: BelongsToTenant)
Service Providers: Configuración de servicios

Base de Datos

Arquitectura Multi-Tenant

Base de datos central (landlord): Almacena información de empresas/tenants
Bases de datos por tenant: Cada empresa tiene su propia base de datos

Convenciones de Nomenclatura

Tablas: plural, snake_case (ej: ordenes_compra)
Columnas de timestamps: creado_en, actualizado_en
Soft deletes: columna eliminado (boolean)
Estado activo: columna activo (boolean)

📦 Módulos del Sistema

1. Gestión de Empresas

Modelos: Empresa, Sucursal, Configuracion
Funcionalidades: Registro de empresas, gestión de sucursales, configuraciones personalizadas

2. Inventario

Modelos: Producto, Almacen, EntradaInventario, SalidaInventario
Funcionalidades: Control de stock, movimientos de inventario, categorización

3. Ventas

Modelos: Venta, Cliente, CuentaPorCobrar
Funcionalidades: Registro de ventas, gestión de clientes, cuentas por cobrar

4. Compras

Modelos: OrdenCompra, CuentaPorPagar, ComprobanteRecibidoElectronico
Funcionalidades: Órdenes de compra, cuentas por pagar, recepción de comprobantes electrónicos

5. Contabilidad

Modelos: CuentaContable, AsientoContable, CajaChica
Funcionalidades: Plan de cuentas, asientos contables, caja chica

8. Facturación Electrónica

Modelos: ComprobanteElectronicoFe, FeLineaDetalle, FeCertificadoDigital, FeOAuthToken, ConsecutivoFe, Cabys
Servicios: HaciendaApiClient, ClaveNumericaGenerator, XmlComprobanteBuilder, FirmaDigitalService, OAuthTokenManager, RateLimiter
Jobs: EnviarComprobanteJob, ConsultarEstadoJob, ProcesarRespuestaJob
Controller: ComprobanteElectronicoController (7 endpoints REST)
Funcionalidades:
- Emisión de comprobantes electrónicos v4.4 (facturas, tiquetes, notas)
- Generación automática de claves numéricas de 50 caracteres
- Construcción y validación de XML según XSD oficial
- Firma digital XAdES-EPES con certificados .p12
- Envío asíncrono a API de Hacienda (OAuth 2.0)
- Consulta automática de estado (polling cada 30s)
- Procesamiento de respuestas (aceptado/rechazado)
- Descarga de XMLs (original, firmado, respuesta)
- Reenvío de comprobantes en error
- Anulación con notas de crédito
- Estadísticas y reportes
- Gestión de consecutivos
- Integración con códigos CAByS
- Soporte para ambientes Sandbox (ATV) y Producción

7. Transporte

Modelos: BusUnidad, HorarioRuta
Funcionalidades: Gestión de flota, rutas y horarios

8. Facturación Electrónica

Modelos: ConsecutivoFe, Cabys
Funcionalidades: Emisión de facturas electrónicas, gestión de consecutivos, códigos CAByS

🔌 API Reference

Autenticación

El sistema utiliza Laravel Sanctum para autenticación de API.

Endpoints de Autenticación:

Login

POST /api/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "admin123"
}

Respuesta:

{
  "user": {
    "id": 1,
    "nombre": "Administrador",
    "email": "[email protected]"
  },
  "token": "1|abc123def456...",
  "permisos": [
    "empresas.crear",
    "empresas.leer",
    "empresas.actualizar",
    "empresas.eliminar",
    ...
  ]
}

Logout

POST /api/logout
Authorization: Bearer {token}

Usuario Actual

GET /api/me
Authorization: Bearer {token}

Respuesta incluye usuario con todos sus permisos y roles

Headers Requeridos

Todos los endpoints (excepto /login) requieren:

Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
X-Empresa-Id: {id}

Usa el header X-Empresa-Id (o un subdominio dedicado) para indicar a qué empresa pertenece la solicitud. Si consumes la API desde https://{subdominio}.api.senselab.com, el header es opcional.

Protección por Permisos

Los endpoints están protegidos por el middleware CheckPermission. Ejemplos:

// Requiere permiso específico
Route::get('/empresas', [EmpresaController::class, 'index'])
    ->middleware('permission:empresas.leer');

// Requiere uno de varios permisos
Route::post('/ventas', [VentaController::class, 'store'])
    ->middleware('permission:ventas.crear,administrador');

Permisos disponibles (68 total):

{módulo}.crear - Crear registros
{módulo}.leer - Ver/listar registros
{módulo}.actualizar - Modificar registros
{módulo}.eliminar - Eliminar registros

Módulos: empresas, sucursales, almacenes, productos, categorias_producto, clientes, proveedores, ventas, compras, inventario, cuentas_contables, asientos_contables, empleados, nomina, rutas, buses, facturacion_electronica

Registro (Deshabilitado)

Por seguridad, el endpoint /register está comentado. Los usuarios se crean manualmente por administradores o mediante seeders.

Endpoints Principales

Ver documentación completa en API_DOCUMENTATION.md

Almacenes

GET    /api/almacenes           # Listar almacenes
POST   /api/almacenes           # Crear almacén
GET    /api/almacenes/{id}      # Ver almacén
PUT    /api/almacenes/{id}      # Actualizar almacén
DELETE /api/almacenes/{id}      # Eliminar almacén

Productos

GET    /api/productos           # Listar productos
POST   /api/productos           # Crear producto
GET    /api/productos/{id}      # Ver producto
PUT    /api/productos/{id}      # Actualizar producto
DELETE /api/productos/{id}      # Eliminar producto

Ventas

GET    /api/ventas              # Listar ventas
POST   /api/ventas              # Crear venta
GET    /api/ventas/{id}         # Ver venta
PUT    /api/ventas/{id}         # Actualizar venta
DELETE /api/ventas/{id}         # Eliminar venta

Clientes

GET    /api/clientes            # Listar clientes
POST   /api/clientes            # Crear cliente
GET    /api/clientes/{id}       # Ver cliente
PUT    /api/clientes/{id}       # Actualizar cliente
DELETE /api/clientes/{id}       # Eliminar cliente

Headers Requeridos

Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

🎨 Estructura del Proyecto

Senselab_Core_API/
├── app/
│   ├── Console/                     # Comandos Artisan personalizados
│   │   └── Commands/
│   │       └── MakeErpModule.php    # Generador de módulos
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── API/                 # Controladores REST (76 en API/)
│   │   │   │   ├── AuthController.php
│   │   │   │   ├── ProductoController.php
│   │   │   │   ├── ComprobanteElectronicoController.php
│   │   │   │   └── ...
│   │   │   └── ...                  # 95 controllers totales
│   │   ├── Requests/                # Form request validation (175)
│   │   └── Resources/               # API resources (81 total)
│   ├── Models/                      # Modelos Eloquent (98 total)
│   │   ├── Empresa.php
│   │   ├── Usuario.php
│   │   ├── Producto.php
│   │   └── ...
│   ├── DTOs/                        # Data Transfer Objects (63 total)
│   ├── Services/                    # Servicios de negocio (67)
│   │   ├── Hacienda/                # Facturación electrónica
│   │   ├── AI/                      # Servicios de IA (10)
│   │   ├── Export/                  # Exportación de reportes
│   │   └── ...                      # 44 servicios core
│   ├── Jobs/                        # Trabajos asíncronos (10)
│   │   ├── Hacienda/
│   │   └── ...
│   ├── Policies/                    # Políticas de autorización RBAC (80 total)
│   ├── Traits/                      # Comportamientos compartidos (13)
│   │   ├── BelongsToTenant.php
│   │   └── HasCustomSoftDeletes.php
│   └── Observers/                   # Event observers (4)
├── bootstrap/
│   ├── app.php                      # Bootstrap de aplicación
│   └── providers.php
├── config/
│   ├── app.php                      # Configuración general
│   ├── database.php                 # Conexiones para BD
│   ├── hacienda.php                 # Facturación electrónica
│   ├── multitenancy.php             # Configuración multi-tenant
│   └── ...
├── database/
│   ├── migrations/
│   │   ├── landlord/                # Tablas del sistema central
│   │   └── tenant/                  # Tablas por tenant (103 migraciones)
│   ├── factories/                   # Model factories para testing (96)
│   ├── seeders/                     # Data seeders (73 seeders)
│   └── scripts/                     # Scripts de utilidad
├── routes/
│   ├── api.php                      # Cargador de rutas API
│   ├── api/                         # Rutas particionadas (16 archivos)
│   ├── web.php                      # Rutas web
│   └── console.php                  # Rutas de consola
├── resources/
│   ├── views/                       # Vistas Blade (si aplica)
│   └── ...
├── storage/
│   ├── logs/                        # Archivos de log
│   ├── api-docs/                    # Documentación Swagger generada
│   └── ...
├── tests/
│   ├── Feature/                     # Tests de integración E2E
│   ├── Unit/                        # Tests unitarios
│   └── TestCase.php                 # Base test case
├── docker/                          # Configuración Docker
│   ├── nginx/
│   ├── php/
│   ├── mysql/
│   └── redis/
├── docs/                            # Documentación del proyecto
│   ├── api/
│   ├── guides/
│   ├── hacienda/
│   └── ...
├── .env.example                     # Archivo de ejemplo de configuración
├── composer.json                    # Dependencias PHP
├── package.json                     # Scripts de Node.js
├── Dockerfile                       # Imagen Docker
├── docker-compose.yml               # Composición de servicios
├── Makefile                         # Comandos útiles
├── phpunit.xml                      # Configuración PHPUnit
├── phpstan.neon                     # Configuración PHPStan
└── README.md                        # Este archivo

🧪 Testing

El proyecto cuenta con una suite completa de 1,261+ tests que verifican el funcionamiento de todos los componentes del sistema.

Estado Actual: ✅ 1,261+ tests passing (100% success rate)

Base de Datos de Testing

Se utiliza SQLite en memoria para testing (rápido y sin dependencias externas):

DB_CONNECTION=testing

Configurado automáticamente en phpunit.xml.

Ejecutar Tests

# Todos los tests
make test
# o
docker exec senselab_php php artisan test

# Tests específicos
php artisan test --filter=FacturacionElectronicaE2ETest
php artisan test --filter=ProductoTest
php artisan test --filter=AuthTest

# Con cobertura
make test-coverage
# o
docker exec senselab_php vendor/bin/phpunit --coverage-html coverage

# Tests en modo CI (como GitHub Actions)
make ci-test

Estructura de Tests

tests/
├── TestCase.php                                    # Base con helpers
├── Feature/                                        # Tests de integración (79 archivos)
├── Unit/                                           # Tests unitarios (68 archivos)
├── Contract/                                       # Contract tests (7 archivos)
└── Load/                                           # Tests de carga k6 (5 archivos)

🔄 CI/CD Pipeline

El proyecto utiliza GitHub Actions para integración y despliegue continuo.

Workflows Automatizados

1. Tests (`tests.yml`)

Trigger: Push o PR a main/develop

Ejecuta en cada commit:

✅ Suite completa de PHPUnit (1,261+ tests)
✅ PHPStan nivel 8 (análisis estático)
✅ PHP CS Fixer (PSR-12)
✅ Security check (vulnerabilidades)
✅ Coverage mínimo 70%

Estado:

2. Code Analysis (`code-analysis.yml`)

Trigger: Push o PR a main/develop

Quality gates:

✅ SonarQube analysis
✅ PHPMD (mess detector)
✅ PHPCPD (copy/paste detector)
✅ PHPCS (code sniffer)

3. Deploy Staging (`deploy-staging.yml`)

Trigger: Push a develop o manual

Pipeline:

Run tests
Build Docker image
Deploy a staging.senselab-core.com
Run migrations
Smoke tests
Notificación Slack

4. Deploy Production (`deploy-production.yml`)

Trigger: Release publicado o manual (requiere aprobación)

Pipeline:

Full test suite
Backup completo (DB + files)
Build Docker image
Zero-downtime deployment
Migrations
Smoke tests
Rollback automático si falla

Quality Gates

Métrica	Umbral	Actual
Tests Passing	100%	✅ 100%
Coverage	≥70%	✅ 90%
PHPStan	Nivel 8	✅ Nivel 8 (0 errores)
Complejidad	<10	✅ 7.2
Duplicación	<3%	✅ 1.8%
Vulnerabilidades	0	✅ 0

Comandos Locales

# Simular pipeline CI completo
make ci-test
make ci-quality
make ci-security

# Deploy manual
make deploy-staging    # Deploy a staging
make deploy-prod       # Deploy a producción

# Rollback
make rollback          # Rollback de producción

Documentación Completa

✅ 1,261+ tests passing (100%)
✅ 0 failures

🤖 Inteligencia Artificial

Senselab Core API integra inteligencia artificial avanzada con Google Gemini y OpenAI para automatizar y mejorar procesos empresariales.

Servicios de IA Disponibles

1. 📄 OCR de Facturas (Optical Character Recognition)

Escanea y extrae datos automáticamente de facturas (imágenes o PDFs).

Características:

✅ Reconocimiento óptico de caracteres con 92%+ precisión
✅ Extracción inteligente de campos:
- Datos del proveedor (RUC, nombre, dirección)
- Detalles de factura (número, fecha, monto)
- Líneas de detalle (descripción, cantidad, precio)
- Impuestos y totales
✅ Validación automática de estructura
✅ Almacenamiento en BD para auditoría
✅ Soporte para múltiples formatos: JPG, PNG, PDF

Endpoint:

POST /api/ai/ocr/facturas
Content-Type: multipart/form-data

Body:
  invoice: [archivo de imagen/PDF]
  empresa_id: 1

Caso de Uso: Importar automáticamente comprobantes de proveedores sin digitación manual.

2. 💬 Chatbot ERP (Asistente Virtual)

Consulta el sistema en lenguaje natural, sin conocer APIs ni SQL.

Características:

✅ Entiende preguntas en español
✅ Responde sobre:
- Inventario (¿Cuánto stock de X?)
- Ventas (¿Cuánto vendí este mes?)
- Clientes (¿Quién debe más?)
- Finanzas (¿Cuál es mi utilidad?)
- RH (¿Cuántos empleados tengo?)
✅ Genera reportes automáticos
✅ Detecta intención del usuario
✅ Historial de conversación

Endpoint:

POST /api/ai/chatbot/consultar
Content-Type: application/json

{
  "consulta": "¿Cuántos productos vendí en enero?",
  "contexto": "ventas",
  "empresa_id": 1
}

Respuesta:

{
  "respuesta": "En enero vendiste 42 productos...",
  "detalles": {
    "cantidad": 42,
    "monto": 15000,
    "productos": [...]
  }
}

3. 📈 Predicción de Demanda e Inventario

Predice qué productos se venderán más y alerta de faltantes.

Características:

✅ Análisis de histórico de ventas
✅ Detección de patrones estacionales
✅ Predicción de demanda (próximo mes)
✅ Alertas automáticas de stock bajo
✅ Recomendaciones de compra
✅ Análisis ABC (Pareto)

Endpoint:

GET /api/ai/inventory/predicciones?producto_id=5&meses=3

Caso de Uso: Evitar rupturas de stock y sobre-inventario.

4. 🚨 Detección de Anomalías

Identifica fraudes, errores contables y transacciones sospechosas.

Características:

✅ Detección de anomalías con 95%+ precisión
✅ Identifica:
- Transacciones fuera de patrón (monto inusual)
- Comportamiento anómalo de usuarios
- Errores de digitación (descuentos incorrectos)
- Posibles fraudes (devoluciones sospechosas)
- Discrepancias contables
✅ Scoring de riesgo (0-100)
✅ Notificaciones en tiempo real

Endpoint:

GET /api/ai/anomalies/detectar?fecha_inicio=2026-01-01&fecha_fin=2026-02-10

Respuesta:

{
    "anomalias": [
        {
            "id": 1,
            "tipo": "descuento_alto",
            "severity": "alto",
            "score": 87,
            "descripcion": "Descuento del 50% en venta tipicamente de 5%"
        }
    ]
}

5. ✍️ Generación Automática de Contenido

Crea emails, reportes y cartas profesionales.

Características:

✅ Plantillas inteligentes
✅ Genera:
- Cartas de cobro personalizadas
- Emails de agradecimiento
- Reportes ejecutivos
- Resúmenes de ventas
- Análisis de gestión
✅ Tonos adaptables (formal, amigable, urgente)
✅ Multi-idioma (español, inglés, etc.)

Endpoint:

POST /api/ai/content/generar
Content-Type: application/json

{
  "tipo": "carta_cobro",
  "cliente_id": 5,
  "monto": 5000,
  "tono": "formal"
}

6. 📋 Clasificación CABYS Automática

Asigna códigos tributarios automáticamente (Costa Rica).

Características:

✅ Clasifica productos según normas DGT
✅ Precisión 98%
✅ Soporta 5,000+ categorías CABYS
✅ Validación contra base de DGT
✅ Sugerencias al usuario (no automático)

Endpoint:

POST /api/ai/cabys/clasificar
Content-Type: application/json

{
  "descripcion": "Laptop HP Pavilion 15 pulgadas",
  "empresa_id": 1
}

Respuesta:

{
    "propuestas": [
        {
            "codigo": "72.20.30.00.00",
            "descripcion": "Composición y reparación de máquinas de oficina",
            "confianza": 0.98
        }
    ]
}

7. 💰 Credit Scoring (Calificación de Riesgo)

Califica el riesgo crediticio de clientes automáticamente.

Características:

✅ Score de 0-100 (0=alto riesgo, 100=bajo riesgo)
✅ Analiza:
- Histórico de pagos
- Monto de deuda actual
- Plazo promedio pago
- Devoluciones y reclamos
- Antigüedad relación comercial
✅ Recomendaciones de crédito
✅ Alertas de clientes riesgosos

Endpoint:

GET /api/ai/credit/score?cliente_id=10

Respuesta:

{
    "cliente_id": 10,
    "score": 78,
    "categoria": "Bueno",
    "limite_recomendado": 50000,
    "recomendacion": "APROBAR - Cliente confiable",
    "analisis": {
        "tasa_pago_a_tiempo": 0.95,
        "promedio_dias_pago": 5,
        "devoluciones": "ninguna"
    }
}

8. 📊 Análisis Financiero Automático

Genera análisis financiero y ratios automáticamente.

Características:

✅ Calcula ratios (liquidez, rentabilidad, solvencia)
✅ Comparativas período a período
✅ Análisis de tendencias
✅ Proyecciones simples
✅ Benchmarks de industria

9. 🗺️ Optimización de Rutas

Optimiza rutas de transporte (función futura).

Características:

⏳ Próximamente en v1.2
Minimiza distancia y tiempo
Calcula costo de combustible

10. 🔍 Recomendaciones Inteligentes

Sugiere acciones basadas en datos históricos.

Características:

⏳ Próximamente
Recomendaciones de productos
Cross-selling automático

Configuración de IA

Variables de Entorno

# Google Gemini (GRATUITO - recomendado)
AI_PROVIDER=gemini
GEMINI_API_KEY=tu_api_key_aqui

# OpenAI como fallback
OPENAI_API_KEY=sk-...

Obtener API Keys Gratis

Google Gemini (Gratuito):

Ve a https://aistudio.google.com
Haz clic en "Get API Key"
Copia la key y pégalo en .env
Límites gratuitos: 60 requests/minuto (más que suficiente)

OpenAI (Pago):

Crea cuenta en https://openai.com
Ve a API Keys
Copia key en .env
Costo: ~$0.0005 por request (muy económico)

Ejemplos de Uso

Obtener Score Crediticio

use App\Services\AI\CreditScoringService;

// Dentro de un controller
public function obtenerScoreCliente($clienteId) {
    $service = new CreditScoringService();
    $score = $service->calcularScore($clienteId);

    return response()->json([
        'cliente_id' => $clienteId,
        'score' => $score->puntuacion,      // 0-100
        'riesgo' => $score->categoria,      // Bajo, Medio, Alto
        'limite' => $score->limiteRecomendado
    ]);
}

Generar Documento Carbon

use App\Services\AI\ContentGenerationService;

$service = new ContentGenerationService();
$carta = $service->generarCartaCobro(
    clienteId: 5,
    monto: 10000,
    tono: 'formal'
);

// $carta contiene el HTML formateado listo para enviar

Costo Estimado

Funcionalidad	Costo/Mes	Volumen
OCR Facturas	$0	ilimitado (con Gemini)
Chatbot	$0	ilimitado
Predicciones	$0-5	1000+ queries
Anomalías	$0	ilimitado
Generación Contenido	$0-10	100+ documentos
Total/Mes	$0-15	Émpresa mediana

Totalmente opcional: Si no configuras claves de IA, el sistema sigue funcionando sin esas features.

Documentación Completa

📘 Ver guía detallada: IA_FUNCIONALIDADES.md

📚 Documentación Swagger

El proyecto incluye documentación interactiva Swagger/OpenAPI para explorar y probar la API.

Acceder a Swagger UI

Una vez iniciado el servidor, accede a:

http://localhost:8000/api/documentation

Características

✅ Documentación interactiva: Prueba endpoints directamente desde el navegador
✅ Autenticación Bearer: Configura tu token una vez y úsalo en todas las peticiones
✅ Schemas completos: Modelos de datos documentados (Usuario, Producto, Rol, Permiso, etc.)
✅ Ejemplos de request/response: Ve datos de ejemplo para cada endpoint
✅ Filtros y parámetros: Documenta todos los query params disponibles

Endpoints Documentados

Autenticación

POST /api/login - Iniciar sesión y obtener token
POST /api/logout - Cerrar sesión
GET /api/user - Obtener usuario autenticado con permisos

Productos

GET /api/productos - Listar productos (filtros, búsqueda, paginación)
POST /api/productos - Crear producto
GET /api/productos/{id} - Obtener producto
PUT /api/productos/{id} - Actualizar producto
DELETE /api/productos/{id} - Eliminar producto (soft delete)

Usar Autenticación en Swagger

Haz login en POST /api/login con credenciales válidas
Copia el token de la respuesta
Haz clic en el botón "Authorize" (🔓)
Ingresa: Bearer {tu-token}
Ahora puedes probar todos los endpoints protegidos

Regenerar Documentación

Si modificas las anotaciones OpenAPI en los controllers:

php artisan l5-swagger:generate

🚀 Despliegue

Opción A: Despliegue con Docker (Recomendado)

Producción con Docker

# 1. Configurar variables de entorno para producción
cp .env.docker .env
# Editar .env con credenciales de producción

# 2. Iniciar en modo producción (con queue worker y scheduler)
make prod-up
# O
docker-compose --profile production up -d

# 3. Optimizar aplicación
make optimize

Ver guía completa: DOCKER_GUIDE.md

Opción B: Despliegue Tradicional

Preparación para Producción

Optimizar Configuración

php artisan config:cache
php artisan route:cache
php artisan view:cache

Compilar Assets

pnpm run build

Configurar Variables de Entorno

APP_ENV=production
APP_DEBUG=false
APP_URL=https://tu-dominio.com

# Configurar Redis para cache y sesiones
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

Configurar Permisos

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Servidor Web

Nginx (Recomendado)

server {
    listen 80;
    server_name tu-dominio.com;
    root /ruta/al/proyecto/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Tareas Programadas

Configurar cron para ejecutar el scheduler de Laravel:

* * * * * cd /ruta/al/proyecto && php artisan schedule:run >> /dev/null 2>&1

Supervisord para Queues

[program:senselab-core-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /ruta/al/proyecto/artisan queue:work redis --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/ruta/al/proyecto/storage/logs/worker.log

⚡ Performance y Escalabilidad

Optimizaciones Implementadas

1. Cache Inteligente con Redis

56 Controllers con cache automático (100% cobertura)
90%+ hit rate en endpoints de catálogos
60-95% mejora en velocidad de respuesta
TTL configurable: 5 minutos a 24 horas según volatilidad de datos
Invalidación por tags para control granular

Ejemplo de cache en acción:

- Endpoint SIN cache: 450ms
- Endpoint CON cache: 15ms
- Mejora: 30x más rápido

2. Paginación Automática

Límite por defecto: 15 items
Máximo configurable: 100 items
Cursor-based pagination para grandes datasets
Meta información: total, página, por página

3. Índices de Base de Datos

Índices primarios en todas las tablas
Índices compuestos en queries frecuentes
Índices de texto completo para búsqueda
Foreign keys con índices automáticos

4. Consultas Optimizadas

Eager loading por defecto (evita N+1)
Select específicas de columnas necesarias
Índices de ordenamiento
Uso de raw queries solo cuando es crítico

5. Compresión de Respuestas

# Gzip automático en Nginx
gzip on;
gzip_types application/json application/javascript text/plain text/css;
gzip_vary on;

Compresión típica:

JSON response: 50KB → 5KB (90% compresión)

Benchmarks Actuales

Operación	Sin Cache	Con Cache	Mejora
Listar productos	450ms	15ms	30x
Obtener usuario	200ms	5ms	40x
Buscar clientes	800ms	25ms	32x
Reportes HQ	3500ms	100ms	35x

Escalabilidad Horizontal

✅ Stateless API (sin sesiones locales)
✅ Redis compartido para cache distribuido
✅ Database connection pooling
✅ Load balancing ready
✅ Kubernetes ready (deployment files disponibles)

Límites y Capacidad

Métrica	Límite	Estado
Usuarios concurrentes	10,000+	✅ Testeado
Registros base datos	10M+	✅ Soportado
Query timeout	60s	⚙️ Configurable
Upload máximo	100MB	⚙️ Configurable
API rate limit	1000 req/min	⚙️ Por usuario

🔒 Seguridad

Medidas Implementadas

1. Autenticación y Autorización

✅ Laravel Sanctum para tokens seguros
✅ RBAC granular (68 permisos)
✅ Middleware CheckPermission en todas las rutas
✅ Token expiration configurable
✅ Revocación de tokens
✅ Rate limiting por usuario

Ejemplo protección:

Route::post('/facturas', [FacturaController::class, 'store'])
    ->middleware('permission:facturacion_electronica.crear');

2. Validación de Datos

✅ Form Requests validación en servidor
✅ Reglas custom para casos específicos
✅ Sanitización automática de inputs
✅ Type casting en modelos
✅ Validación de enum para campos específicos

3. Encriptación

✅ APP_KEY para encriptación general
✅ Campos sensibles encriptados (certificados, tokens)
✅ Certificados digitales .p12 protegidos
✅ Passwords hasheados con Bcrypt
✅ HTTPS obligatorio en producción

4. Protección CORS

// config/cors.php permite solicitudes desde dominios específicos
'allowed_origins' => [
    'https://app.senselab.com',
    'https://*.senselab.com'
],

5. Protección CSRF

✅ Habilitado en rutas web (no aplica a API)
✅ Token validation automático
✅ Double submit cookie pattern

6. Headers de Seguridad

# Nginx headers
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header X-XSS-Protection "1; mode=block";
add_header Strict-Transport-Security "max-age=31536000" always;
add_header Content-Security-Policy "default-src 'self'";

7. Backup y Recuperación

✅ Backups automáticos diarios
✅ Copias de BD encriptadas
✅ Versionado de archivos
✅ Timestamp en backups
✅ Verificazione de integridad

Localización: storage/backups/

8. Auditoría Completa

Todos los cambios son registrados:

Quién cambió (usuario)
Qué cambió (campo/valor)
Cuándo cambió (timestamp)
Dónde cambió (IP, navegador)
Por qué cambió (referencia)

Tabla: audits (multi-tenant)

9. Prevención de SQL Injection

✅ Eloquent ORM (no strings concatenados)
✅ Parameterized queries automáticas
✅ Validación de entrada
✅ Escape automático

10. Certificados Digitales Seguros

Para facturación electrónica:

✅ Almacenamiento seguro de .p12
✅ Encriptación en base de datos
✅ Validación de expiración
✅ Renovación automática (notificación)
✅ Auditoría de uso

Scanning de Seguridad

# Verificar vulnerabilidades conocidas
composer audit

# Análisis estático con PHPStan (nivel 8)
make phpstan

# OWASP Top 10 check
make security-check

Reportar Vulnerabilidades

Por favor, NO publiques vulnerabilidades en GitHub Issues.
Envía un email a: [email protected] con:

Descripción del problema
Pasos para reproducir
Impacto potencial
Sistema operativo y versiones

📊 Logging y Monitoreo

Sistema de Logs

1. Logs de Aplicación

Localización: storage/logs/laravel.log

Niveles:

🔴 ERROR - Errores no controlados
🟡 WARNING - Advertencias importantes
🟢 INFO - Información general
⚪ DEBUG - Detalles de depuración

Configuración:

# En .env
LOG_CHANNEL=stack
LOG_LEVEL=info

2. Logs Específicos de Facturación

Localización: storage/logs/hacienda.log

Registra:

Envíos a Hacienda
Respuestas recibidas
Errores de transmisión
Cambios de estado

3. Logs de Acceso API

Localización: storage/logs/api-access.log

Información por request:

IP del cliente
Usuario autenticado
Endpoint accedido
Método HTTP
Código de respuesta
Tiempo de ejecución
Parámetros (no sensibles)

4. Logs de Auditoría

Tabla: audits (base de datos)

Registra:

Creación de registros
Actualización de campos
Eliminación (soft delete)
Cambios RBAC
Accesos sensibles

Monitoreo Proactivo

Sentry Integration

SENTRY_LARAVEL_DSN=https://[email protected]/project-id

Características:

Detección automática de errores
Alertas en tiempo real
Agrupación de errores
Análisis de rendimiento
Source maps para depuración

Métricas y KPIs

Dashboard recomendado: Grafana

Métricas clave:

Tasa de error (< 0.1%)
P95 latencia (< 500ms)
Cache hit rate (> 85%)
DB connection pool
Queue backlog
API rate limit hits

Health Check

# Endpoint de health check
curl http://localhost:8000/api/health

# Respuesta
{
  "status": "healthy",
  "timestamp": "2026-02-11T10:30:00Z",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  }
}

🔧 Troubleshooting

Problemas Comunes

1. Error "SQLSTATE[HY000]"

Síntoma: No puede conectar a base de datos

Soluciones:

# Verificar credenciales en .env
cat .env | grep DB_

# Verificar que MySQL está corriendo
sudo systemctl status mysql

# Con Docker
docker-compose logs mysql

# Recrear la conexión
php artisan db:seed --class=DatabaseSeeder

2. Error "Unauthenticated"

Síntoma: Token inválido o expirado

Soluciones:

# Generar nuevo token
curl -X POST http://localhost:8000/api/login \
  -d "[email protected]&password=admin123"

# Verificar token
curl -H "Authorization: Bearer TOKEN" \
  http://localhost:8000/api/me

3. Error "Permission Denied"

Síntoma: Usuario no tiene permiso para acción

Verificar:

# Ver permisos del usuario
php artisan tinker
>>> $user = User::find(1);
>>> $user->permissions()->get();

# Asignar permiso manualmente
>>> $user->permissions()->attach(PermissionId);

4. Cache Inconsistente

Síntoma: Datos obsoletos en respuestas

Soluciones:

# Limpiar cache completamente
php artisan cache:clear
php artisan cache:forget *

# Con Redis
redis-cli FLUSHDB

# Remuestrear datos
php artisan db:seed --class=PermisosSeeder

5. Error de Facturación Electrónica

Síntoma: Comprobante rechazado por Hacienda

Verificar:

✅ Certificado digital válido y no expirado
✅ Empresa habilitada en Hacienda
✅ Ambiente correcto (ATV vs Producción)
✅ Consecutivo sin duplicados
✅ Campos obligatorios completos
✅ XML válido según XSD

Ver logs:

tail -f storage/logs/hacienda.log

6. Tests Fallando

Síntoma: "SQLSTATE[42S02] Table doesn't exist"

Soluciones:

# Usar base de datos de testing
php artisan test --database=testing

# Recrear base de datos de testing
php artisan migrate:fresh --database=testing

# Ejecutar seeders para testing
php artisan db:seed --database=testing

7. Problema: "Driver not found"

Síntoma: Error con extensión PHP

Soluciones:

# Verificar extensiones instaladas
php -m | grep -i pdo

# Instalar extensión faltante
sudo apt-get install php8.4-pdo-mysql

# Reiniciar PHP-FPM
sudo systemctl restart php8.4-fpm

Logs Útiles para Debugging

# Log de aplicación principal
tail -f storage/logs/laravel.log

# Log de Hacienda
tail -f storage/logs/hacienda.log

# Logs de Docker
docker-compose logs -f php
docker-compose logs -f mysql
docker-compose logs -f redis

# Logs del sistema
journalctl -xe

Comandos de Diagnóstico

# Ver estado de la aplicación
php artisan health

# Información del proyecto
php artisan about

# Listar rutas registradas
php artisan route:list

# Verificar caché
php artisan cache:clear

# Revisar workers de queue (si está activo)
php artisan queue:failed

❓ FAQ (Preguntas Frecuentes)

¿Cuál es el costo del ERP?

Senselab Core API es Open Source bajo la licencia AGPLv3. Esto significa que puedes usarlo, modificarlo y distribuirlo libremente, siempre que mantengas la misma licencia y compartas tus mejoras. Para usos comerciales sin las restricciones de la AGPLv3, contacta a [email protected].

¿Necesito soporte técnico?

Sí, ofrecemos:

✅ Soporte por email: [email protected]
✅ Issues en GitHub: Reportar problema
✅ Documentación completa: Está en /docs

¿Soporta multi-empresa?

Sí, con arquitectura multi-tenant completa. Cada empresa:

Tiene su propia base de datos
Usuarios independientes
Configuraciones propias
Datos completamente aislados

¿Puedo usar PostgreSQL?

En v1.0: No, solo MySQL 8.0+ PostgreSQL estará soportado en v1.2 (Q3 2026)

¿Qué tan madura es la IA?

Muy madura:

✅ 7+ meses de desarrollo
✅ 405+ tests pasando
✅ 92-98% precisión en OCR/clasificación
✅ Fallback automático si falla

¿Es seguro para producción?

Sí, totalmente. Implementa:

✅ Encriptación de datos sensibles
✅ Auditoría completa
✅ Backups automáticos
✅ Rate limiting
✅ RBAC granular
✅ Validaciones en servidor

¿Cuánto tiempo toma instalar?

Docker: 3-5 minutos
Manual: 15-30 minutos (según experiencia)

¿Debo pagar a proveedores de IA?

Optativo:

Google Gemini: Gratuito (capa free es suficiente)
OpenAI: Pago (fallback, ~$0.002/request)

¿Cuál es el ciclo de versiones?

Versión menor: Cada mes (+features)
Patch: Según sea necesario (bugs)
Mayor: Anual (arquitectura/framework)

¿Hay plan de migración de otros ERPs?

Ofrecemos:

📘 Guías de migración
🔧 Scripts de importación
📊 Mapeo de datos
Email: [email protected]

¿Puedo usar esto como template?

Sí, es perfecto para:

✅ Template base para nuevos proyectos
✅ Aprender arquitectura Laravel
✅ Boilerplate personalizable
✅ Referencia de buenas prácticas

📖 Mejores Prácticas

Desarrollo

Convenciones de Código

// 1. Nombres descriptivos en español
public function obtenerProductosPorCategoria($categoriaId) { }
// NOT: function getProds($id) { }

// 2. Métodos cortos (< 20 líneas idealmente)
public function crearProducto(CreateProductRequest $request) {
    $producto = Producto::create($request->validated());
    ProductoCreado::dispatch($producto);
    return new ProductoResource($producto);
}

// 3. Usar early returns
public function store(Request $request) {
    if (!$this->puedeCrear()) {
        return response()->forbidden();
    }

    return $this->crear($request);
}

// 4. Validación en FormRequest
public function rules() {
    return [
        'nombre' => 'required|string|max:100',
        'email' => 'required|email|unique:usuarios',
        'edad' => 'integer|between:18,100',
    ];
}

Type Hints y Return Types

// ✅ Siempre usar type hints
public function buscar(string $termino): Collection {
    return $this->usuarios
        ->where('nombre', 'like', "%{$termino}%")
        ->get();
}

// ✗ Evitar tipos genéricos
public function buscar($termino) {
    // ...
}

Composición sobre Herencia

// ✅ Usar traits
class Producto extends Model {
    use BelongsToTenant;
    use HasCacheableQueries;
}

// En lugar de
class Producto extends TenantModel { }

Testing

Nomenclatura de Tests

// ✅ Descriptivo y específico
public function test_producto_valida_nombre_requerido() { }
public function test_usuario_sin_permiso_no_puede_crear_factura() { }

// ✗ Genérico
public function test_producto() { }
public function test_usuario() { }

Arrange-Act-Assert Pattern

public function test_crear_producto() {
    // Arrange
    $datos = ['nombre' => 'Producto Test', 'precio' => 100];

    // Act
    $response = $this->postJson('/api/productos', $datos);

    // Assert
    $response->assertCreated();
    $this->assertDatabaseHas('productos', $datos);
}

Deployment

Pre-Deploy Checklist

Todos los tests pasando (make test)
PHPStan sin errores (make phpstan)
Code style válido (make pint)
Migrations listas (php artisan migrate:status)
Cache limpio (php artisan cache:clear)
Documentación actualizada
Versión actualizada (tags Git)
Changelog actualizado

Rollback Rápido

# Si algo falla en producción
make rollback

# O manual
git revert HEAD
php artisan migrate:rollback
redis-cli FLUSHDB

🚀 Roadmap y Futuras Funcionalidades

🎉 Roadmap original completado al 100% (22 fases). Las siguientes son funcionalidades futuras planificadas.

✅ Completado en v5.0 (FASES 18–22)

API Versionado — Prefijo v1/v2, header-based versioning, Sunset middleware (FASE 18)
PHPStan 0 Errores — Level 8 estricto, +17 DTOs (FASE 19.7)
Webhooks Event-Driven — 5 eventos, HMAC-SHA256, retry exponencial (FASE 20)
Reporting Engine — Dashboard KPIs, reportes financieros, exportación PDF/Excel/CSV (FASE 21)
Escalabilidad — Read Replicas, Laravel Horizon, ETags, OpenTelemetry (FASE 22)
Hacienda v4.4 Compliance — 38/38 brechas resueltas (100%)

Corto Plazo (Q1-Q2 2026)

PostgreSQL Support - Soporte para Postgres
GraphQL API - Alternativa a REST
Mobile App - Aplicación iOS/Android nativa
SMS Integration - Notificaciones por SMS
Integraciones Bancarias - Conciliación automática

Mediano Plazo (Q3-Q4 2026)

Machine Learning - Predicciones más precisas
Blockchain - Trazabilidad de transacciones
Marketplace - Integración B2B
POS System - Sistema punto de venta integrado
E-Commerce - Tienda en línea integrada

Largo Plazo (2027+)

AI Co-pilot - Asistente IA conversacional
Predicción Fiscal - Planificación tributaria
Automatización RPA - Procesos sin código
Análisis Predictivo - Forecasting avanzado
Soluciones Verticales - Apps para industrias específicas

Votación Comunitaria

¿Qué feature quieres que sea prioridad? Vota aquí: GitHub Discussions

📐 Diagramas de Arquitectura

El proyecto incluye 8 diagramas Mermaid que documentan visualmente la arquitectura, flujos y métricas del sistema.

#	Diagrama	Descripción
01	Arquitectura Multi-Tenant	Topología completa: Nginx → Laravel → Landlord/Tenant DBs → Redis
02	Flujo Facturación Electrónica	Secuencia XAdES-EPES completa con Hacienda
03	Ciclo de Vida Dato IA	Pipeline de 5 etapas de datos para IA
04	Precisión Servicios IA	Métricas de precisión por servicio
05	ERD Módulo Contable	Entidades: Empresa → CuentaContable → AsientoContable
06	ERD Módulo Logística	Entidades: Ruta → HorarioRuta → BusUnidad → Venta
07	Matriz RBAC Seguridad	8 roles × 17 módulos + enforcement dual
08	Benchmarks Redis	Comparativas de rendimiento + arquitectura cache

📁 Ver todos: docs/diagrams/README.md

📚 Documentación Completa

Toda la documentación del proyecto vive en docs/. A continuación los documentos más relevantes organizados por categoría.

Archivos Raíz del Proyecto

Archivo	Descripción
CHANGELOG.md	Historial de cambios por versión
ROADMAP.md	Roadmap completo — 22/22 fases (100%)
ESTADO_ACTUAL_PROYECTO.md	Estado actual del proyecto, comandos útiles y métricas
SECURITY.md	Política de seguridad y reporte de vulnerabilidades

Guías y Tutoriales

Guía	Descripción
Guía de Testing	Cómo ejecutar y escribir tests (Unit, Feature, Contract, Load)
CI/CD Pipeline	Configuración de los 9 workflows de GitHub Actions
Multi-Tenancy	Arquitectura Spatie multi-tenant con BD aislada
Webhooks	Integración de webhooks con HMAC-SHA256
Contribuir al Proyecto	Guía para colaboradores: estándares, PRs, code review
Backup Strategy	Estrategia de respaldos y recuperación
Sentry Setup	Configuración de observabilidad con Sentry
Docker Quickstart	Inicio rápido con Docker en 5 minutos
Generador de Módulos	CLI para generar controladores, modelos, policies y tests
Datos de Testeo	Seeders y factories para ambiente de desarrollo

Referencia API y Arquitectura

Documento	Descripción
Modelos y Relaciones	Mapa de relaciones Eloquent entre los 98 modelos
Policies Guide	Los 80 policies y 68 permisos del sistema RBAC
FormRequests Summary	Resumen de las 175 validaciones FormRequest
Controllers Summary	Los 95 controladores documentados
API Resources	Los 81 API Resources del sistema
Database Config	Configuración de MySQL, read replicas y Redis

Facturación Electrónica (Hacienda)

Documento	Descripción
Análisis Completo DGT v4.4	Análisis de la normativa v4.4 y compliance 38/38
Comparativo Hacienda v4.4	Comparativa con versiones anteriores
Plan Implementación v4.4	Plan ejecutado para migrar a v4.4

Valoración Comercial y Pricing

Documento	Descripción
💰 Valoración Comercial y Pricing	Estrategia de pricing SaaS 4 tiers, valoración $120K-$150K
🔍 Estudio de Mercado ERP 2026	Investigación competitiva: 8 ERPs analizados (Alegra, Odoo, SAP, etc.)

Auditorías Técnicas

Auditoría	Puntuación	Fecha
Auditoría Técnica (última)	9.2/10	13 abr 2026
Auditoría Técnica	—	24 mar 2026
Auditoría Técnica	—	9 mar 2026

Otros Recursos

Recurso	Descripción
Release Checklist	Checklist para publicar nuevas versiones
Known Warnings	Warnings conocidos y su justificación
Pendientes del Proyecto	Tareas pendientes y mejoras futuras
Índice de Documentación	Índice maestro de toda la documentación
Sprints Históricos	18 documentos de sprints completados
Archivo Histórico	75+ documentos del historial del proyecto

🤝 Contribuir

¡Apreciamos todas las contribuciones! El proyecto es 100% Open Source y cualquiera puede contribuir.

Procedimiento de Contribución

Fork el proyecto en GitHub
```
# En GitHub UI: botón "Fork"
```

Clona tu fork localmente

git clone https://github.com/TU_USUARIO/Senselab_Core_API.git
cd Senselab_Core_API
git remote add upstream https://github.com/SenseLab-dev/Senselab_Core_API.git

Crea una rama para tu feature

# Siempre partir de develop
git checkout develop
git pull upstream develop

# Crear rama (nombre descriptivo)
git checkout -b feature/agregar-facturacion-pdf
# o
git checkout -b fix/corregir-bug-login
# o
git checkout -b docs/mejorar-readme

Haz cambios y commit

# Editar archivos...
git add .
git commit -m "feat: agregar soporte para facturas PDF

- Implementar generador de PDFs
- Agregar tests para nueva funcionalidad
- Actualizar documentación"

Sube tu rama

git push origin feature/agregar-facturacion-pdf

Abre Pull Request en GitHub
- Describe qué problema resuelves
- Incluye screenshots si aplica
- Referencia issues relacionados (#123)
Espera revisión y feedback
- El equipo revisará tu código
- Puede pedir cambios
- Una vez aprobado, será mergeado

Guía de Estándares de Código

PHP - PSR-12 Compliant

// ✅ Correcto
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\Producto;

class ProductoController extends Controller
{
    /**
     * Obtener lista de productos con paginación
     *
     * @param Request $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function index(Request $request): JsonResponse
    {
        $productos = Producto::paginate(
            $request->get('limit', 15)
        );

        return response()->json($productos);
    }

    /**
     * Validar que el producto existe
     *
     * @param int $id
     * @return Producto
     * @throws ModelNotFoundException
     */
    private function obtenerProducto(int $id): Producto
    {
        return Producto::findOrFail($id);
    }
}

// ✗ Incorrecto
function getProds() { }  // Nombres cortos
public function index(){} // Sin espacios

Convenciones Locales

Variables y métodos: español descriptivo (obtenerProductosPorCategoria)
Clases y namespaces: PascalCase en inglés (ProductoController)
Constantes: UPPER_SNAKE_CASE (MAX_DESCRIPCION_LENGTH = 255)
Booleanos: prefijo es o tiene (esActivo, tienePermiso)

Documentación (PHPDoc)

/**
 * Crear un nuevo producto en el sistema
 *
 * @param CreateProductRequest $request Datos validados del producto
 * @return \Illuminate\Http\JsonResponse Respuesta con producto creado
 * @throws \Exception Si hay error al crear
 *
 * @see ProductoController::update() Método relacionado
 */
public function store(CreateProductRequest $request): JsonResponse
{
    // ...
}

Testing

// ✅ Nombres claros y específicos
public function test_crear_producto_requiere_nombre() { }
public function test_usuario_sin_permiso_no_puede_eliminar_producto() { }
public function test_validar_precio_debe_ser_mayor_que_cero() { }

// Todos los tests deben tener arrange-act-assert
#[Test]
public function crear_producto_valido(): void
{
    // Arrange
    $datos = [
        'nombre' => 'Producto Test',
        'precio' => 100.00,
        'empresa_id' => 1
    ];

    // Act
    $response = $this->postJson('/api/productos', $datos);

    // Assert
    $response->assertCreated();
    $this->assertDatabaseHas('productos', $datos);
}

Checklist Antes de Enviar PR

Código sigue PSR-12
Todo está documentado (PHPDoc + comentarios en lógica compleja)
Tests nuevos/actualizados y todos pasan
No hay breaking changes (documentarlos si los hay)
Commits tienen mensajes descriptivos (convención Conventional Commits)
Rama actualizada con latest develop
README actualizado (si aplica)
Changelog actualizado (si aplica)

Conventional Commits

Sigue este formato en mensajes de commit:

<tipo>(<scope>): <descripción corta>

<descripción larga - opcional>

Fixes #123

Tipos:

feat: Nueva funcionalidad
fix: Corrección de bug
docs: Cambios en documentación
style: Formateo de código (PSR-12)
refactor: Reorganización sin cambiar comportamiento
perf: Mejora de performance
test: Agregar o actualizar tests
security: Correcciones de seguridad
chore: Cambios en build, deps, etc.

Ejemplos:

git commit -m "feat(permisos): agregar permiso para auditar cambios"
git commit -m "fix(cache): corregir invalidación en multi-tenant"
git commit -m "docs: mejorar guía de instalación"
git commit -m "test(facturacion): agregar 5 casos de prueba nuevos"

Áreas de Contribución

Área	Dificultad	Ayuda Necesaria
📚 Docs	Fácil	Siempre
🐛 Bug Fixes	Fácil-Media	Issue labels: `bug`
✨ Features	Media-Difícil	Issues abiertos
🧪 Tests	Fácil-Media	Coverage < 100%
⚡ Performance	Difícil	Benchmarks establecidos

Código de Conducta

Esperamos que todos los contribuyentes sean respetuosos y constructivos.

No toleramos:

Lenguaje ofensivo o discriminatorio
Abuso o acoso
Spam o auto-promoción inapropiada

Sí valoramos:

Feedback constructivo
Ayuda a otros contribuyentes
Documentación clara
Tests de calidad

📄 Licencia

Este proyecto se lanza bajo la licencia GNU Affero General Public License v3 (AGPLv3) para que cualquier mejora vuelva a la comunidad.

💼 Planes Comerciales

Ofrecemos planes comerciales para empresas que requieran:

🚀 Alta disponibilidad (High Availability).
🧩 Módulos adicionales exclusivos.
🛠️ Soporte prioritario y SLAs personalizados.

Ver licencia completa

📞 Soporte y Contacto

Canales de Soporte

Canal	Respuesta	Mejor Para
Email	24-48h	Consultas serias, reportes de seguridad
GitHub Issues	24-72h	Bugs, features, preguntas
Discussions	1-2 días	Conversaciones, ideas

Contactos

Corporativo:

📧 Email: [email protected]
🌐 Web: senselab.com
🌐 Web Alt: senselab.com

Técnico/Desarrollo:

📧 Email Dev: [email protected]
🐙 GitHub Org: SenseLab-dev

Comunidad:

📚 Repo Dev: Senselab Repositorio para Developers
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Reportar Problemas

Para Bugs

Abre un issue con:

## Descripción

[Explica brevemente]

## Pasos para Reproducir

1. Hacer esto...
2. Luego esto...

## Comportamiento Esperado

[Qué debería pasar]

## Comportamiento Actual

[Qué está pasando]

## Sistema Operativo

-   OS: [e.g. Ubuntu 22.04]
-   PHP: [e.g. 8.3.1]
-   Laravel: [e.g. 12.0]

## Logs

[Pega error relevante aquí]

Para Seguridad

NUNCA publiques vulnerabilidades en GitHub Issues.

Envía email privado a: [email protected]

Incluye:

Descripción clara del problema
Pasos detallados para reproducir
Impacto potencial
Tu información de contacto
Versión afectada

🙏 Agradecimientos

Frameworks y Librerías

Laravel Framework - El framework PHP más elegante y moderno
Spatie Multitenancy - Solución robusta de multi-tenancy
Laravel Sanctum - Autenticación API segura
DOMPdf - Generación de PDFs
Google Gemini AI - Servicios de IA
PhpUnit - Framework de testing

Comunidad

Comunidad Laravel Costa Rica
Comunidad PHP española
Stack Overflow y Laravel Forum
Todos nuestros contribuidores y usuarios

Organizaciones

Senselab - Patrono principal del proyecto
Empresa familiar costarricense | Build with Sense

👥 Equipo

Desarrollador Principal y Arquitecto

Jeremy Arias Solano

Co-fundador de Senselab
Arquitecto de software y desarrollador completo de Senselab Core API
Especialista en Laravel, PHP y sistemas ERP
Diseño, desarrollo, testing y mantenimiento integral
GitHub: @jeremy-sud

En Desarrollo

Estamos siempre buscando:

✨ Backend Developers - Laravel, PHP, MySQL
🎨 Frontend Developers - Vue/React (futuro)
📱 Mobile Developers - React Native (futuro)
📊 DevOps Engineers - Docker, K8s
📖 Technical Writers - Documentación

¿Interesado? Contáctanos: [email protected]

"No hacemos cualquier cosa. Hacemos cosas con sentido."

Senselab
Soluciones Tecnológicas Completas
SenseLab | Tecnología versátil con alma costarricense

📧 [email protected]

_{© 2026 Senselab - Todos los derechos reservados}
_{Licencia AGPLv3 — Opciones comerciales disponibles}

Última actualización: 14 de Abril 2026

Versión: 5.0.1

Estado: ✅ Producción-Ready (Recomendado)

Name		Name	Last commit message	Last commit date
Latest commit History 413 Commits
.gitbook/assets		.gitbook/assets
.github		.github
.sonarlint		.sonarlint
.vscode		.vscode
app		app
bootstrap		bootstrap
config		config
database		database
docker		docker
docs		docs
kubernetes		kubernetes
public		public
resources/views		resources/views
routes		routes
scripts		scripts
storage		storage
tests		tests
vendor		vendor
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.docker		.env.docker
.env.example		.env.example
.env.testing		.env.testing
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
.php-cs-fixer.php		.php-cs-fixer.php
ANEXOS Y ESTRUCTURAS_V4.4.pdf		ANEXOS Y ESTRUCTURAS_V4.4.pdf
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
ESTADO_ACTUAL_PROYECTO.md		ESTADO_ACTUAL_PROYECTO.md
Guia_IdP.pdf		Guia_IdP.pdf
GuiaparaCredencialesEntornodepruebas.pdf		GuiaparaCredencialesEntornodepruebas.pdf
LICENSE		LICENSE
MH-DCN-PRO01-MAN-001-Asignacion_Roles_y_Perfiles_SIGAF_Adm_Ctral.pdf		MH-DCN-PRO01-MAN-001-Asignacion_Roles_y_Perfiles_SIGAF_Adm_Ctral.pdf
MH-DCN-PRO01-MAN-002-Asignacion_y_Exclusion_Roles_y_Perfiles_Sistema_Gestor.pdf		MH-DCN-PRO01-MAN-002-Asignacion_y_Exclusion_Roles_y_Perfiles_Sistema_Gestor.pdf
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
SIAA-ATENA-DUA-GUIA-TECNICA.pdf		SIAA-ATENA-DUA-GUIA-TECNICA.pdf
SUMMARY.md		SUMMARY.md
artisan		artisan
codecov.yml		codecov.yml
composer.json		composer.json
composer.lock		composer.lock
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.staging.yml		docker-compose.staging.yml
docker-compose.yml		docker-compose.yml
estructura 4.4.pdf		estructura 4.4.pdf
infection.json5		infection.json5
package.json		package.json
phpmd.xml		phpmd.xml
phpstan-baseline.neon		phpstan-baseline.neon
phpstan-no-baseline.neon		phpstan-no-baseline.neon
phpstan.neon		phpstan.neon
phpunit.xml		phpunit.xml
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
production_credentials_to_change.txt		production_credentials_to_change.txt
sonar-project.properties		sonar-project.properties
vite.config.js		vite.config.js

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Senselab Core API 🚀

📋 Tabla de Contenidos

� Curso Completo y Glosario

�🚀 Acerca del Proyecto

🎯 Misión del Proyecto

📊 Estado del Proyecto

✨ Características Principales

🔐 Autenticación y Autorización Avanzada

💰 Facturación Electrónica Completa

📦 Gestión de Inventario Inteligente

📊 Contabilidad Profesional

👥 Recursos Humanos y Nómina

🚌 Gestión de Transporte (Especializado)

🏢 Multi-Tenancy Avanzada

🤖 Inteligencia Artificial Integrada

📚 Stack Tecnológico

Backend

Frontend & Assets

DevOps & Infrastructure

Testing & Quality

Librerías Principales

💻 Requisitos del Sistema

Requisitos Mínimos

Extensiones PHP Obligatorias

Extensiones PHP Recomendadas

Requisitos de Sistema Operativo

Requisitos de Hardware

Requisitos de Red

🔄 Versiones Soportadas

Ciclo de Vida

Compatibilidad de Navegadores

Compatibilidad de Herramientas

🔑 Credenciales de Prueba

🏢 Sobre Senselab

🎯 Capacidades del Sistema

🔧 Instalación

Opción A: Instalación con Docker 🐳 (Recomendada)

Instalación Automática

Usando Makefile

Servicios Disponibles

Opción B: Instalación Manual (Tradicional)

1. Clonar el Repositorio

2. Instalar Dependencias

3. Configurar Variables de Entorno

4. Configurar Base de Datos

5. Ejecutar Migraciones y Seeders

6. Compilar Assets

7. Iniciar Servidor de Desarrollo

Credenciales de Acceso

🧪 Cómo Probar la API

Opción 1: Swagger UI (Recomendada) ⭐

Opción 2: Postman / Thunder Client / Insomnia

Opción 3: cURL (Terminal)

⚙️ Configuración

Configuración de Multi-Tenancy

Identificación del tenant

Configuración de Base de Datos

Configuración de Facturación Electrónica

🏗️ Arquitectura

Estructura de Directorios

Patrón de Diseño

Base de Datos

Arquitectura Multi-Tenant

Convenciones de Nomenclatura

📦 Módulos del Sistema

1. Gestión de Empresas

2. Inventario

3. Ventas

4. Compras

5. Contabilidad

8. Facturación Electrónica

7. Transporte

8. Facturación Electrónica

🔌 API Reference

Autenticación

1. Tests (`tests.yml`)

2. Code Analysis (`code-analysis.yml`)

3. Deploy Staging (`deploy-staging.yml`)

4. Deploy Production (`deploy-production.yml`)