> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/docs/database/database_readme.md).

# Base de Datos - Senselab Core API

**Desarrollado por:** Senselab\
**País:** Costa Rica | Build with Sense\
**Desarrollador:** Jeremy Arias Solano

***

## ✅ Estado Actual

**Base de datos completamente configurada y funcional - PRODUCCIÓN LISTA**

### Estadísticas Generales

* ✅ **78 tablas** en total (65 originales + 12 nuevas FASE 9 + migrations)
* ✅ **77 migraciones CREATE** ejecutadas exitosamente
* ✅ **140 registros** de datos iniciales cargados (112 originales + 28 nuevos)
* ✅ **5 índices FULLTEXT** para búsquedas avanzadas (4 originales + 1 nuevo)
* ✅ **56 índices totales** optimizados (14 originales + 42 nuevos FASE 9)
* ✅ **Sistema RBAC** completo (68 permisos + 8 roles)

### Migraciones

* ✅ **77 migraciones CREATE** ejecutadas (65 originales + 12 nuevas FASE 9)
* ✅ **78 tablas totales** creadas (65 originales + 12 nuevas + migrations)
* ✅ Todas las **foreign keys** configuradas correctamente (76 FKs totales)
* ✅ Tipos de datos compatibles (INT UNSIGNED para tablas originales, BIGINT UNSIGNED para nuevas)
* ✅ **personal\_access\_tokens** (Laravel Sanctum) para autenticación API

### Tablas Estratégicas Adicionales (5)

Estas tablas se crean automáticamente por el sistema y no requieren migración:

1. **archivos** - Almacenamiento de archivos del sistema
2. **auditoria\_actividades** - Registro de auditoría de acciones
3. **sesiones\_usuarios** - Control de sesiones activas
4. **notificaciones** - Sistema de notificaciones
5. **configuraciones\_api** - Configuraciones de la API

**Total tablas:** 65 (originales) + 12 (FASE 9) + 1 (migrations) = **78 tablas**

### Índices de Optimización

#### Índices FULLTEXT (4 tablas)

Mejoran significativamente las búsquedas de texto:

1. **productos** - `nombre`, `codigo`, `descripcion`, `codigo_barras`
2. **clientes** - `nombre`, `email`, `identificacion`
3. **proveedores** - `nombre`, `email`, `identificacion`
4. **empresas** - `nombre`, `nombre_comercial`, `identificacion`

**Uso:**

```sql
SELECT * FROM productos 
WHERE MATCH(nombre, codigo, descripcion) AGAINST('laptop' IN BOOLEAN MODE);
```

#### Índices Compuestos (14 índices)

Optimizan queries frecuentes con múltiples condiciones:

* **productos**: `empresa_id + activo`, `categoria_id + tipo`
* **clientes**: `empresa_id + activo`, `tipo_cliente + provincia`
* **proveedores**: `empresa_id + activo`
* **ventas**: `empresa_id + fecha`, `cliente_id + estado`
* **compras**: `empresa_id + fecha`, `proveedor_id + estado`
* **asientos\_contables**: `empresa_id + fecha`, `periodo_id + tipo`
* **empleados**: `empresa_id + activo`, `departamento_id + cargo_id`
* **facturas\_electronicas**: `empresa_id + clave`, `estado + fecha_emision`

### Seeders Implementados (13 total)

Se han creado seeders para poblar datos iniciales en las siguientes tablas:

#### Datos Maestros (6 seeders - 96 registros)

1. **RegimenesTributariosSeeder** - 2 registros
   * Régimen Tradicional
   * Régimen Simplificado
2. **FormasPagoSeeder** - 6 registros
   * Efectivo, Tarjeta, Transferencia, Cheque, Crédito, Otros
3. **TiposCuentasSeeder** - 8 registros
   * Activo Corriente, Activo No Corriente, Pasivo Corriente, Pasivo No Corriente, Patrimonio, Ingresos, Costos, Gastos
4. **UnidadesMedidaSeeder** - 11 registros
   * Unidad, Kilogramo, Gramo, Litro, Mililitro, Metro, Metro cuadrado, Metro cúbico, Caja, Paquete, Servicio
5. **PermisosSeeder** - 68 registros
   * Generación dinámica: 17 módulos × 4 acciones (crear, leer, actualizar, eliminar)
   * Módulos: empresas, sucursales, almacenes, productos, categorias\_producto, clientes, proveedores, ventas, compras, inventario, cuentas\_contables, asientos\_contables, empleados, nomina, rutas, buses, facturacion\_electronica
6. **RolesSeeder** - 8 registros
   * Administrador, Gerente, Contador, Vendedor, Comprador, Bodeguero, Usuario, Auditor
   * El rol Administrador se asigna automáticamente todos los 68 permisos

#### Datos Demo/Test (3 seeders - 16 registros)

7. **CargosSeeder** - 7 registros
   * Gerente General, Contador, Vendedor, Cajero, Bodeguero, Conductor, Asistente Administrativo
8. **EmpresaDemoSeeder** - 2 registros
   * 1 Empresa: "Senselab" (3-101-123456)
   * 1 Sucursal: "Oficina Central"
9. **UsuarioAdminSeeder** - 7 registros
   * 1 Usuario: <admin@senselab.com> (password: admin123)
   * 6 Relaciones rol\_usuario (usuario con rol Administrador)
   * Asignación automática de todos los 68 permisos

#### Datos Costa Rica - FASE 9 (4 seeders - 28 registros)

10. **TiposComprobantesFESeeder** - 9 registros

* Tipos de comprobantes DGT: 01 (Factura), 02 (Nota Débito), 03 (Nota Crédito), 04 (Tiquete), 05 (Nota Débito Tiquete), 06 (Nota Crédito Tiquete), 07 (Comprobante Compra), 08 (Factura Exportación), 09 (Factura Compra)

11. **DeduccionesLegalesSeeder** - 6 registros

* CCSS Cuota Obrera (10.50%), CCSS Cuota Patronal (26.50%), INS Póliza Riesgos (1.00%), Ley Protección Trabajador (3.00%), Impuesto Renta (variable), Asociación Solidarista (5.00%)

12. **TiposClientesSeeder** - 6 registros

* Mayorista, Minorista, Distribuidor, Gobierno, Exportación, Consumidor Final

13. **ZonasGeograficasCRSeeder** - 7 registros

* 7 provincias de Costa Rica: San José, Alajuela, Cartago, Heredia, Guanacaste, Puntarenas, Limón

**Total de registros:** **140** (96 datos maestros + 16 datos demo/test + 28 datos Costa Rica)

### Factories Implementadas

Se han creado factories para testing de las siguientes entidades:

1. **EmpresaFactory** - Generación de empresas de prueba
2. **ClienteFactory** - Generación de clientes
3. **ProveedorFactory** - Generación de proveedores
4. **ProductoFactory** - Generación de productos
5. **UsuarioFactory** - Generación de usuarios
6. **SucursalFactory** - Generación de sucursales
7. **RolFactory** - Generación de roles
8. **PermisoFactory** - Generación de permisos
9. **UserFactory** - Factory original de Laravel

**Uso en Tests:**

```php
// Crear empresa con sucursales
$empresa = Empresa::factory()
    ->has(Sucursal::factory()->count(3))
    ->create();

// Crear producto con relaciones
$producto = Producto::factory()
    ->for($empresa)
    ->create();

// Crear usuario con roles
$usuario = Usuario::factory()
    ->hasAttached(Rol::factory()->count(2))
    ->create();
```

### Database Testing

Base de datos separada para tests: `api_db_testing`

```bash
# Crear base de datos de testing
sudo mysql -u root -e "CREATE DATABASE IF NOT EXISTS api_db_testing;"

# Los tests automáticamente usan RefreshDatabase
php artisan test
```

Ver documentación completa: [FASE\_4\_TESTING\_COMPLETADA.md](https://github.com/jeremy-sud/Senselab_Core_API/blob/main/docs/database/FASE_4_TESTING_COMPLETADA.md)

## 🚀 Comandos Disponibles

### Instalación Completa

```bash
# Ejecutar migraciones + seeders (fresh install con 112 registros)
php artisan migrate:fresh --seed
```

Este comando:

1. Elimina todas las tablas existentes
2. Ejecuta las 77 migraciones CREATE (65 originales + 12 FASE 9)
3. Ejecuta los 9 seeders en orden:
   * RegimenesTributariosSeeder (2)
   * FormasPagoSeeder (6)
   * TiposCuentasSeeder (8)
   * UnidadesMedidaSeeder (11)
   * PermisosSeeder (68)
   * RolesSeeder (7 + asignación de permisos)
   * CargosSeeder (7)
   * EmpresaDemoSeeder (2)
   * UsuarioAdminSeeder (7 + 6 relaciones rol\_usuario)
4. **Total insertado: 112 registros**

### Comandos Individuales

```bash
# Solo migraciones (sin seeders)
php artisan migrate

# Solo seeders (sin recrear tablas)
php artisan db:seed

# Seeder específico
php artisan db:seed --class=PermisosSeeder
php artisan db:seed --class=UsuarioAdminSeeder

# Limpiar base de datos (eliminar todas las tablas)
php artisan db:wipe

# Ver estado de la base de datos con conteos
php artisan db:show --counts

# Rollback de última migración
php artisan migrate:rollback

# Rollback de todas las migraciones
php artisan migrate:reset
```

### Credenciales de Acceso

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

```bash
# Login con cURL
curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "admin@senselab.com",
    "password": "admin123"
  }'
```

**Credenciales:**

* **Email:** <admin@senselab.com>
* **Password:** admin123
* **Rol:** Administrador
* **Permisos:** 68 (acceso total)
* **Empresa:** Senselab (ID: 1)

## 🧪 Testing con Factories

### Crear registros de prueba con Tinker

```bash
php artisan tinker
```

Dentro de Tinker:

```php
// Crear una empresa con sucursal y usuarios
$empresa = \App\Models\Empresa::factory()
    ->has(\App\Models\Sucursal::factory()->count(2))
    ->has(\App\Models\Usuario::factory()->count(5))
    ->create();

// Crear productos
$productos = \App\Models\Producto::factory()->count(20)->create([
    'empresa_id' => $empresa->id
]);

// Crear clientes
$clientes = \App\Models\Cliente::factory()->count(10)->create([
    'empresa_id' => $empresa->id
]);

// Crear proveedores
$proveedores = \App\Models\Proveedor::factory()->count(5)->create([
    'empresa_id' => $empresa->id
]);
```

## 📊 Estructura de la Base de Datos

### Tablas de Sistema

* **migrations** - Historial de migraciones ejecutadas
* **personal\_access\_tokens** - Tokens de autenticación (Laravel Sanctum)

### Tablas Principales (Empresas y Usuarios)

* **empresas** - Datos de las empresas (multi-tenancy)
* **sucursales** - Sucursales por empresa
* **usuarios** - Usuarios del sistema (Authenticatable + HasApiTokens)
* **roles** - Roles del sistema (7 roles predefinidos)
* **permisos** - Permisos granulares (68 permisos: 17 módulos × 4 acciones)
* **rol\_usuario** - Relación many-to-many entre usuarios y roles
* **rol\_permiso** - Relación many-to-many entre roles y permisos
* **empleados** - Empleados de las empresas
* **cargos** - Cargos/puestos de trabajo (7 cargos predefinidos)

### Módulo de Ventas

* **clientes** - Clientes
* **productos** - Catálogo de productos
* **ventas** - Ventas realizadas
* **detalle\_ventas** - Detalle de cada venta
* **formas\_pago** - Formas de pago disponibles

### Módulo de Compras

* **proveedores** - Proveedores
* **ordenes\_compra** - Órdenes de compra
* **detalle\_ordenes\_compra** - Detalle de órdenes

### Módulo de Inventario

* **almacenes** - Almacenes
* **entradas\_inventario** / **detalle\_entradas\_inventario**
* **salidas\_inventario** / **detalle\_salidas\_inventario**
* **inventario\_productos** - Stock por almacén

### Módulo Contable

* **cuentas\_contables** - Plan de cuentas
* **tipos\_cuentas** - Clasificación de cuentas
* **asientos\_contables** / **detalle\_asientos** - Asientos contables
* **cuentas\_por\_cobrar** / **pagos\_cuentas\_cobrar**
* **cuentas\_por\_pagar** / **pagos\_cuentas\_pagar**
* **presupuestos** / **detalle\_presupuestos**

### Módulo de Transporte

* **rutas** - Rutas de transporte
* **buses\_unidades** - Unidades de transporte
* **modelos\_buses** - Modelos de buses
* **horarios\_ruta** - Horarios por ruta
* **tiquetes\_detalle** - Detalle de tiquetes vendidos

### Módulo de Nómina

* **periodos\_nomina** - Períodos de nómina
* **nomina\_empleados** - Nómina de empleados
* **pagos\_nomina** - Pagos de nómina

### Otros Módulos

* **caja\_chica** / **movimientos\_caja\_chica**
* **cajas** - Cajas por sucursal
* **consecutivos\_fe** - Consecutivos de facturación electrónica
* **comprobantes\_recibidos\_electronicos**
* **etiquetas** / **entidad\_etiquetas** - Sistema de etiquetado
* **configuraciones** - Configuraciones por empresa

## 🔧 Correcciones Aplicadas

### Problema de Tipos de Datos

**Problema original:** Las migraciones usaban `id()` y `foreignId()` que generan `BIGINT UNSIGNED`, pero el esquema SQL usa `INT UNSIGNED`.

**Solución aplicada:**

* Cambiado `id()` por `increments('id')`
* Cambiado `foreignId()` y `unsignedBigInteger()` por `unsignedInteger()`
* Todas las foreign keys ahora son compatibles

### Migraciones Creadas

Se crearon 10 migraciones faltantes:

1. modelos\_buses
2. cajas
3. tipos\_cuentas
4. cuentas\_contables (corregida)
5. etiquetas
6. entidad\_etiquetas
7. presupuestos
8. detalle\_presupuestos
9. pagos
10. pagos\_nomina

### Migraciones Corregidas

Se corrigieron 4 migraciones existentes:

1. buses\_unidades - Nombre de tabla y campos
2. detalle\_asientos\_contables - Nombre de tabla y campos (debe/haber)
3. cuentas\_contables - Campo permite\_movimientos
4. horarios\_ruta - Campo fecha\_salida

## 📝 Notas Importantes

1. **Timestamps personalizados:** Las tablas usan `creado_en` y `actualizado_en` en lugar de `created_at` y `updated_at`
2. **Soft Deletes personalizados:** Se usa `activo` y `eliminado` en lugar de `deleted_at`
3. **Multi-tenant:** Todas las tablas operacionales tienen `empresa_id`
4. **Facturación Electrónica:** Campos preparados para integración con Hacienda Costa Rica
5. **Autenticación:** Laravel Sanctum con tokens personales por usuario
6. **RBAC:** Sistema completo de roles y permisos con 68 permisos granulares
7. **Seeders:** Ejecutar siempre en orden (DatabaseSeeder se encarga automáticamente)
8. **Credenciales demo:** <admin@senselab.com> / admin123 (solo en desarrollo)

## 🎯 Próximos Pasos

1. ✅ Configurar modelos Eloquent con relaciones → **COMPLETADO**
2. ✅ Crear controladores API → **COMPLETADO**
3. ✅ Implementar middleware de autenticación → **COMPLETADO (Sanctum + CheckPermission)**
4. ✅ Crear validaciones de request → **COMPLETADO (FormRequests)**
5. ✅ Implementar seeders de datos maestros → **COMPLETADO (9 seeders, 112 registros)**
6. 🔄 Implementar tests unitarios y de integración → **EN PROGRESO (FASE 4)**
7. 📝 Documentar API con Swagger/OpenAPI → **PENDIENTE (FASE 5)**
8. 🚀 Integración con Hacienda (Facturación Electrónica) → **PENDIENTE**
9. 📊 Dashboard y reportes → **PENDIENTE**
10. 📱 API versioning → **PENDIENTE**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/docs/database/database_readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.