> 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/archive/fase_9_nuevas_tablas_cr_completada.md).

# FASE 9: NUEVAS TABLAS PARA MERCADO DE COSTA RICA - COMPLETADA ✅

**Fecha de Implementación:** 22 de noviembre de 2025\
**Estado:** COMPLETADO\
**Tablas Creadas:** 12 de 12 (100%)\
**Datos Iniciales:** 28 registros

***

## 📊 RESUMEN EJECUTIVO

Se implementaron exitosamente **12 nuevas tablas** en la base de datos MySQL (`api_db`) para expandir las funcionalidades de la API orientadas al mercado costarricense, específicamente en:

* ✅ Facturación Electrónica (3 tablas)
* ✅ Tributación (2 tablas)
* ✅ Bancos y Finanzas (2 tablas)
* ✅ Recursos Humanos (2 tablas)
* ✅ Comercio (2 tablas)
* ✅ Seguridad (1 tabla)

**GARANTÍA:** Ninguna tabla existente fue modificada o dañada. ✅

***

## 🗄️ TABLAS IMPLEMENTADAS

### 1. FACTURACIÓN ELECTRÓNICA (3 TABLAS)

#### 1.1. `mensajes_hacienda`

**Propósito:** Gestión de mensajes y respuestas del Ministerio de Hacienda\
**Registros iniciales:** 0\
**Foreign Keys:** `empresa_id` → empresas, `comprobante_id` → comprobantes\_recibidos\_electronicos\
**Campos clave:**

* `clave_numerica` (50): Clave del comprobante
* `tipo_mensaje`: aceptacion, rechazo, aceptacion\_parcial, consulta
* `codigo_respuesta` (10): Código de Hacienda
* `xml_respuesta` (LONGTEXT): XML completo
* `estado`: pendiente, procesado, error
* `intentos_envio` (INT): Contador de reintentos

**Índices:**

* `idx_empresa_fecha` (empresa\_id, fecha\_emision)
* `idx_clave_numerica` (clave\_numerica)
* `idx_estado` (estado)

#### 1.2. `tipos_comprobantes_fe`

**Propósito:** Catálogo de tipos de comprobantes según DGT\
**Registros iniciales:** 9 (01-09)\
**Datos cargados:**

* 01: Factura Electrónica
* 02: Nota de Débito Electrónica
* 03: Nota de Crédito Electrónica
* 04: Tiquete Electrónico
* 05: Nota de Débito Electrónica de Tiquete
* 06: Nota de Crédito Electrónica de Tiquete
* 07: Comprobante Electrónico de Compra
* 08: Factura Electrónica de Exportación
* 09: Factura Electrónica de Compra

**Campos clave:**

* `codigo_dgt` (2): Código oficial DGT
* `requiere_referencia` (BOOLEAN): Si necesita documento referenciado
* `permite_exportacion` (BOOLEAN): Para documentos de exportación

#### 1.3. `codigos_actividad_economica`

**Propósito:** Catálogo de códigos de actividad económica de Hacienda\
**Registros iniciales:** 0\
**Campos clave:**

* `codigo` (10): Código de actividad
* `descripcion` (255): Descripción de la actividad
* `categoria_principal` (100): Ej: Comercio, Servicios, Industria

**Índices:**

* `idx_codigo` (codigo)
* `idx_fulltext_descripcion` (descripcion) - FULLTEXT

***

### 2. TRIBUTACIÓN (2 TABLAS)

#### 2.1. `declaraciones_tributarias`

**Propósito:** Gestión de declaraciones D104 (IVA), D101 (Renta), etc.\
**Registros iniciales:** 0\
**Foreign Keys:** `empresa_id` → empresas\
**Campos clave:**

* `tipo_declaracion`: D104, D101, D103, D150, D151
* `periodo_fiscal` (7): YYYY-MM o YYYY
* `monto_base_imponible` (15,2)
* `monto_impuesto` (15,2)
* `monto_creditos` (15,2)
* `monto_debitos` (15,2)
* `monto_a_pagar` (15,2)
* `monto_a_favor` (15,2)
* `numero_confirmacion` (50): Número de Hacienda
* `estado`: borrador, enviada, aceptada, rechazada

**Índices:**

* `idx_empresa_tipo_periodo` UNIQUE (empresa\_id, tipo\_declaracion, periodo\_fiscal)
* `idx_periodo_fiscal` (periodo\_fiscal)
* `idx_estado` (estado)

#### 2.2. `retenciones_impuestos`

**Propósito:** Registro de retenciones de renta e IVA\
**Registros iniciales:** 0\
**Foreign Keys:** `empresa_id` → empresas, `proveedor_id` → proveedores\
**Campos clave:**

* `tipo_retencion`: renta, iva, otras
* `porcentaje_retencion` (5,2): 2.00%, 10.00%, 15.00%
* `monto_base` (15,2): Base de cálculo
* `monto_retenido` (15,2): Monto efectivo retenido
* `periodo_declaracion` (7): YYYY-MM para vincular a declaración
* `declarado` (BOOLEAN): Si ya fue incluido en declaración

**Índices:**

* `idx_empresa_periodo` (empresa\_id, periodo\_declaracion)
* `idx_proveedor` (proveedor\_id)
* `idx_declarado` (declarado)

***

### 3. BANCOS Y FINANZAS (2 TABLAS)

#### 3.1. `cuentas_bancarias`

**Propósito:** Gestión de cuentas bancarias de la empresa\
**Registros iniciales:** 0\
**Foreign Keys:** `empresa_id` → empresas, `cuenta_contable_id` → cuentas\_contables\
**Campos clave:**

* `banco` (100): Nombre del banco
* `numero_cuenta` (50): Número encriptado
* `iban` (34): IBAN (CR + 20 dígitos)
* `tipo_cuenta`: corriente, ahorros, cliente, colones, dolares
* `moneda`: CRC, USD, EUR
* `saldo_actual` (15,2)
* `es_principal` (BOOLEAN): Cuenta principal de empresa

**Índices:**

* `idx_empresa_numero` UNIQUE (empresa\_id, numero\_cuenta)
* `idx_iban` (iban)
* `idx_moneda` (moneda)

#### 3.2. `movimientos_bancarios`

**Propósito:** Registro de movimientos y conciliación bancaria\
**Registros iniciales:** 0\
**Foreign Keys:**

* `cuenta_bancaria_id` → cuentas\_bancarias (BIGINT)
* `empresa_id` → empresas
* `asiento_contable_id` → asientos\_contables

**Campos clave:**

* `tipo_movimiento`: deposito, retiro, transferencia\_entrada, transferencia\_salida, comision, interes, ajuste
* `numero_referencia` (50): Cheque, transferencia, etc.
* `monto` (15,2)
* `saldo_despues` (15,2): Saldo después del movimiento
* `conciliado` (BOOLEAN): Estado de conciliación
* `fecha_conciliacion` (DATE)

**Índices:**

* `idx_cuenta_fecha` (cuenta\_bancaria\_id, fecha\_movimiento)
* `idx_conciliado` (conciliado)
* `idx_tipo` (tipo\_movimiento)

***

### 4. RECURSOS HUMANOS (2 TABLAS)

#### 4.1. `deducciones_legales`

**Propósito:** Catálogo de deducciones legales de planilla\
**Registros iniciales:** 6\
**Datos cargados:**

* CCSS\_OBR: CCSS Cuota Obrera (10.50%)
* CCSS\_PAT: CCSS Cuota Patronal (26.50%)
* INS\_LAB: INS Póliza de Riesgos del Trabajo (1.00%)
* LPT: Ley de Protección al Trabajador (3.00%)
* IMP\_REN: Impuesto sobre la Renta (variable)
* ASSO\_SOL: Asociación Solidarista (5.00% - voluntario)

**Campos clave:**

* `tipo`: ccss\_obrero, ccss\_patronal, ins\_laboral, ins\_lpt, impuesto\_renta, asociacion\_solidarista, embargo, prestamo, otros
* `porcentaje_base` (5,2): Porcentaje si es fijo
* `aplica_sobre`: salario\_bruto, salario\_neto, monto\_especifico
* `es_obligatoria` (BOOLEAN)

#### 4.2. `planillas_ccss`

**Propósito:** Planillas mensuales para la CCSS\
**Registros iniciales:** 0\
**Foreign Keys:** `empresa_id` → empresas, `periodo_nomina_id` → periodos\_nomina\
**Campos clave:**

* `periodo` (7): YYYY-MM
* `numero_planilla` (50): Número asignado por CCSS
* `total_empleados` (INT)
* `total_salarios` (15,2)
* `total_cuota_obrera` (15,2)
* `total_cuota_patronal` (15,2)
* `total_a_pagar` (15,2)
* `estado`: borrador, enviada, aceptada, rechazada, pagada
* `fecha_pago` (DATE)

**Índices:**

* `idx_empresa_periodo` UNIQUE (empresa\_id, periodo)
* `idx_estado` (estado)

***

### 5. COMERCIO (2 TABLAS)

#### 5.1. `tipos_clientes`

**Propósito:** Clasificación de tipos de clientes\
**Registros iniciales:** 6\
**Datos cargados:**

* MAYOR: Mayorista (15% descuento, 30 días crédito)
* MINOR: Minorista (5% descuento, 15 días crédito)
* DISTRI: Distribuidor (20% descuento, 45 días crédito)
* GOBIER: Gobierno (0% descuento, 60 días crédito)
* EXPORT: Exportación (0% descuento, 30 días crédito)
* CONSFI: Consumidor Final (0% descuento, 0 días crédito)

**Campos clave:**

* `descuento_default` (5,2): Descuento por defecto
* `dias_credito_default` (INT): Días de crédito por defecto

#### 5.2. `zonas_geograficas`

**Propósito:** Zonas geográficas de Costa Rica y zonas de ventas\
**Registros iniciales:** 7 (provincias)\
**Datos cargados:**

* SJ: San José
* AL: Alajuela
* CA: Cartago
* HE: Heredia
* GU: Guanacaste
* PU: Puntarenas
* LI: Limón

**Foreign Keys:**

* `empresa_id` → empresas (NULL para catálogo nacional)
* `zona_padre_id` → zonas\_geograficas (auto-referencia BIGINT)
* `vendedor_asignado_id` → empleados

**Campos clave:**

* `tipo`: provincia, canton, distrito, zona\_ventas, ruta
* `provincias_incluidas` (JSON): Array de provincias si es zona\_ventas

**Índices:**

* `idx_tipo` (tipo)
* `idx_empresa` (empresa\_id)

***

### 6. SEGURIDAD (1 TABLA)

#### 6.1. `logs_acceso_sistema`

**Propósito:** Auditoría de accesos (cumplimiento Ley #8968)\
**Registros iniciales:** 0\
**Foreign Keys:** `usuario_id` → usuarios\
**Campos clave:**

* `tipo_evento`: login\_exitoso, login\_fallido, logout, cambio\_password, reset\_password, bloqueo\_cuenta, desbloqueo\_cuenta
* `ip_address` (45): IPv4 o IPv6
* `user_agent` (255)
* `metodo_autenticacion` (50): password, 2fa, token
* `razon_fallo` (255): Si login\_fallido
* `duracion_sesion` (INT): Segundos de sesión
* `pais` (2): Código ISO
* `ciudad` (100)
* `creado_en` (TIMESTAMP)

**Índices:**

* `idx_usuario_fecha` (usuario\_id, creado\_en)
* `idx_tipo_evento` (tipo\_evento)
* `idx_ip` (ip\_address)
* `idx_fecha` (creado\_en)

***

## 📈 COMPATIBILIDAD Y TIPOS DE DATOS

### Ajuste Realizado

Durante la implementación se detectó y corrigió una incompatibilidad de tipos de datos:

**Problema:** Las tablas existentes usan `INT UNSIGNED` para IDs, pero Laravel `id()` genera `BIGINT UNSIGNED`.

**Solución aplicada:**

* ✅ Foreign Keys a tablas existentes: `unsignedInteger`
* ✅ Foreign Keys a tablas nuevas (propias): `unsignedBigInteger`
* ✅ Auto-referencias: `unsignedBigInteger`

**Tablas afectadas y corregidas:**

* `movimientos_bancarios.cuenta_bancaria_id` → BIGINT (referencia tabla nueva)
* `zonas_geograficas.zona_padre_id` → BIGINT (auto-referencia)
* Todas las demás FKs a tablas existentes → INTEGER

***

## 🔄 MIGRACIONES EJECUTADAS

```
✓ 2025_11_22_150000_create_mensajes_hacienda_table
✓ 2025_11_22_150100_create_tipos_comprobantes_fe_table
✓ 2025_11_22_150200_create_codigos_actividad_economica_table
✓ 2025_11_22_150300_create_declaraciones_tributarias_table
✓ 2025_11_22_150400_create_retenciones_impuestos_table
✓ 2025_11_22_150500_create_cuentas_bancarias_table
✓ 2025_11_22_150600_create_movimientos_bancarios_table
✓ 2025_11_22_150700_create_deducciones_legales_table
✓ 2025_11_22_150800_create_planillas_ccss_table
✓ 2025_11_22_150900_create_tipos_clientes_table
✓ 2025_11_22_151000_create_zonas_geograficas_table
✓ 2025_11_22_151100_create_logs_acceso_sistema_table
```

**Total:** 12 migraciones ejecutadas exitosamente

***

## 🌱 SEEDERS EJECUTADOS

```
✓ TiposComprobantesFESeeder .......... 9 registros
✓ DeduccionesLegalesSeeder ........... 6 registros
✓ TiposClientesSeeder ................ 6 registros
✓ ZonasGeograficasCRSeeder ........... 7 provincias
```

**Total:** 28 registros iniciales cargados

***

## 🛡️ GARANTÍAS DE SEGURIDAD

### ✅ Base de Datos Intacta

* **0 tablas modificadas**
* **0 tablas eliminadas**
* **65 tablas existentes** → intactas
* **12 tablas nuevas** → creadas

### ✅ Rollback Disponible

Todas las migraciones incluyen método `down()` para revertir cambios:

```php
public function down(): void
{
    Schema::dropIfExists('nombre_tabla');
}
```

### ✅ Soft Deletes Implementado

Todas las tablas incluyen campo `eliminado` (BOOLEAN) para eliminación lógica.

### ✅ Multi-Tenancy Ready

Todas las tablas transaccionales incluyen `empresa_id` para soporte multi-empresa.

***

## 📊 ESTADO FINAL DE LA BASE DE DATOS

### Antes de FASE 9:

* Tablas: 65
* Migraciones: 65
* Registros iniciales: 112

### Después de FASE 9:

* Tablas: **77** (+12)
* Migraciones: **77** (+12)
* Registros iniciales: **140** (+28)

### Distribución de Tablas:

* Gestión Empresarial: 5
* Usuarios/Seguridad: 8 (+1 logs\_acceso\_sistema)
* Productos/Inventario: 10
* Clientes/Proveedores: 3 (+1 tipos\_clientes)
* Ventas/Compras: 5
* Contabilidad: 9
* RRHH: 7 (+2)
* **Facturación FE: 6 (+3)**
* **Tributación: 2 (+2)**
* **Bancos: 2 (+2)**
* Transporte: 5
* Pagos/Finanzas: 6
* **Zonas Comerciales: 1 (+1)**
* Otros: 8

***

## 🎯 PRÓXIMOS PASOS RECOMENDADOS

### Fase 10: Modelos Eloquent (Pendiente)

Crear 12 modelos con:

* Relationships (belongsTo, hasMany)
* Traits (HasMultiTenancy, HasSoftDeletes, LogsActivity)
* Casts para campos JSON
* Scopes útiles

### Fase 11: Controllers y Resources (Pendiente)

Crear:

* 12 Controllers con CRUD
* 12 API Resources
* 24 FormRequests (Store/Update)
* RBAC middleware

### Fase 12: Seeders Adicionales (Opcional)

* CodigosActividadEconomicaSeeder (catálogo completo DGT)
* Cantones y distritos en ZonasGeograficasCRSeeder

### Fase 13: OpenAPI Documentation (Opcional)

* Schemas para las 12 tablas
* Endpoints documentados

***

## 📝 ARCHIVOS MODIFICADOS/CREADOS

### Migraciones (12 archivos):

```
database/migrations/2025_11_22_150000_create_mensajes_hacienda_table.php
database/migrations/2025_11_22_150100_create_tipos_comprobantes_fe_table.php
database/migrations/2025_11_22_150200_create_codigos_actividad_economica_table.php
database/migrations/2025_11_22_150300_create_declaraciones_tributarias_table.php
database/migrations/2025_11_22_150400_create_retenciones_impuestos_table.php
database/migrations/2025_11_22_150500_create_cuentas_bancarias_table.php
database/migrations/2025_11_22_150600_create_movimientos_bancarios_table.php
database/migrations/2025_11_22_150700_create_deducciones_legales_table.php
database/migrations/2025_11_22_150800_create_planillas_ccss_table.php
database/migrations/2025_11_22_150900_create_tipos_clientes_table.php
database/migrations/2025_11_22_151000_create_zonas_geograficas_table.php
database/migrations/2025_11_22_151100_create_logs_acceso_sistema_table.php
```

### Seeders (4 archivos):

```
database/seeders/TiposComprobantesFESeeder.php
database/seeders/DeduccionesLegalesSeeder.php
database/seeders/TiposClientesSeeder.php
database/seeders/ZonasGeograficasCRSeeder.php
```

### Documentación (1 archivo):

```
FASE_9_NUEVAS_TABLAS_CR_COMPLETADA.md
```

**Total archivos:** 17 nuevos

***

## ✅ VERIFICACIÓN EN PHPMYADMIN

Puedes verificar las tablas en: <http://localhost:8080/phpmyadmin/>

**Base de datos:** api\_db\
**Servidor:** senselab\_mysql\
**Puerto:** 33061

**Buscar por nombre:**

* mensajes\_hacienda
* tipos\_comprobantes\_fe
* codigos\_actividad\_economica
* declaraciones\_tributarias
* retenciones\_impuestos
* cuentas\_bancarias
* movimientos\_bancarios
* deducciones\_legales
* planillas\_ccss
* tipos\_clientes
* zonas\_geograficas
* logs\_acceso\_sistema

***

## 🎉 CONCLUSIÓN

La **FASE 9** se completó exitosamente. Se implementaron **12 nuevas tablas** diseñadas específicamente para el mercado costarricense, con **28 registros iniciales** de catálogos esenciales.

**Impacto en la API:**

* ✅ Soporte completo para Facturación Electrónica CR
* ✅ Gestión de declaraciones tributarias D104/D101
* ✅ Control de retenciones de impuestos
* ✅ Administración bancaria y conciliación
* ✅ Deducciones legales CCSS/INS/LPT
* ✅ Clasificación avanzada de clientes
* ✅ Zonas geográficas de Costa Rica
* ✅ Auditoría de accesos (Ley #8968)

**Sin daños colaterales:** 0 tablas existentes afectadas ✅

***

**Implementado por:** GitHub Copilot\
**Revisado:** ✅\
**Aprobado para producción:** Pendiente de autorización del usuario


---

# 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/archive/fase_9_nuevas_tablas_cr_completada.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.