> 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_completa.md). # FASE 9 - IMPLEMENTACIÓN COMPLETA ✅ ## 📋 Resumen Ejecutivo **Fecha:** 2025-01-28\ **Estado:** ✅ COMPLETADO AL 100%\ **Commits:** * `7d629e2` - Modelos Eloquent (12 archivos) * `83481a3` - Archivos generados base (24 Requests + 12 Resources) * `0843d55` - Personalización completa (Validaciones, Resources, Controllers, Rutas) **Total de archivos creados:** 61 archivos * 12 Modelos Eloquent * 24 FormRequests (12 Store + 12 Update) * 12 API Resources * 12 API Controllers * 1 archivo de rutas actualizado *** ## 📦 Módulos Implementados ### 1. **Mensajes Hacienda** ✅ **Archivos:** * `app/Models/MensajeHacienda.php` * `app/Http/Requests/StoreMensajeHaciendaRequest.php` * `app/Http/Requests/UpdateMensajeHaciendaRequest.php` * `app/Http/Resources/MensajeHaciendaResource.php` * `app/Http/Controllers/MensajeHaciendaController.php` **Características:** * Validación de mensajes DGT (aceptación, rechazo, consulta) * Filtros: empresa\_id, tipo\_mensaje, estado, rango de fechas * Búsqueda: clave\_numerica, mensaje * Relaciones: empresa, comprobante **Endpoint:** `GET|POST /api/mensajes-hacienda` *** ### 2. **Tipos Comprobantes FE** ✅ **Archivos:** * `app/Models/TipoComprobanteFe.php` * `app/Http/Requests/StoreTipoComprobanteFeRequest.php` * `app/Http/Requests/UpdateTipoComprobanteFeRequest.php` * `app/Http/Resources/TipoComprobanteFeResource.php` * `app/Http/Controllers/TipoComprobanteFeController.php` **Características:** * Catálogo DGT de tipos de comprobante (01-09) * Validación: codigo\_dgt único, size:2 * Flags: requiere\_referencia, permite\_exportacion * Filtros: activo, requiere\_referencia * Búsqueda: codigo\_dgt, nombre **Endpoint:** `GET|POST /api/tipos-comprobantes-fe` *** ### 3. **Códigos Actividad Económica** ✅ **Archivos:** * `app/Models/CodigoActividadEconomica.php` * `app/Http/Requests/StoreCodigoActividadEconomicaRequest.php` * `app/Http/Requests/UpdateCodigoActividadEconomicaRequest.php` * `app/Http/Resources/CodigoActividadEconomicaResource.php` * `app/Http/Controllers/CodigoActividadEconomicaController.php` **Características:** * Catálogo de actividades económicas Costa Rica * Validación: codigo único max:10 * Fulltext search en descripcion * Filtros: activo, categoria\_principal * Búsqueda: codigo, descripcion, categoria **Endpoint:** `GET|POST /api/codigos-actividad-economica` *** ### 4. **Declaraciones Tributarias** ✅ **Archivos:** * `app/Models/DeclaracionTributaria.php` * `app/Http/Requests/StoreDeclaracionTributariaRequest.php` * `app/Http/Requests/UpdateDeclaracionTributariaRequest.php` * `app/Http/Resources/DeclaracionTributariaResource.php` * `app/Http/Controllers/DeclaracionTributariaController.php` **Características:** * Tipos: D104 (IVA), D101 (Renta), D103, D150, D151 * Validación: periodo\_fiscal regex `YYYY-MM` o `YYYY` * Cálculos: iva\_debito, iva\_credito, iva\_a\_pagar/favor * Estados: borrador, enviada, aceptada, rechazada, pagada * Filtros: empresa\_id, tipo\_declaracion, estado, periodo, rango fechas * Relaciones: empresa **Endpoint:** `GET|POST /api/declaraciones-tributarias` *** ### 5. **Retenciones Impuesto** ✅ **Archivos:** * `app/Models/RetencionImpuesto.php` * `app/Http/Requests/StoreRetencionImpuestoRequest.php` * `app/Http/Requests/UpdateRetencionImpuestoRequest.php` * `app/Http/Resources/RetencionImpuestoResource.php` * `app/Http/Controllers/RetencionImpuestoController.php` **Características:** * Tipos: renta, iva, otras * Validación: porcentaje\_retencion 0-100 * Periodo: regex `YYYY-MM` * Filtros: empresa\_id, proveedor\_id, tipo\_retencion, estado, periodo * Búsqueda: numero\_comprobante * Relaciones: empresa, proveedor, declaracion **Endpoint:** `GET|POST /api/retenciones-impuesto` *** ### 6. **Cuentas Bancarias** ✅ **Archivos:** * `app/Models/CuentaBancaria.php` * `app/Http/Requests/StoreCuentaBancariaRequest.php` * `app/Http/Requests/UpdateCuentaBancariaRequest.php` * `app/Http/Resources/CuentaBancariaResource.php` * `app/Http/Controllers/CuentaBancariaController.php` **Características:** * Validación IBAN Costa Rica: `^CR\d{20}$` size:22 * Tipos: corriente, ahorros, cliente, colones, dolares * Monedas: CRC, USD, EUR * Campo enmascarado: `numero_cuenta_enmascarado` * Filtros: empresa\_id, tipo\_cuenta, moneda, activa * Búsqueda: banco, iban, titular * Relaciones: empresa **Endpoint:** `GET|POST /api/cuentas-bancarias` *** ### 7. **Movimientos Bancarios** ✅ **Archivos:** * `app/Models/MovimientoBancario.php` * `app/Http/Requests/StoreMovimientoBancarioRequest.php` * `app/Http/Requests/UpdateMovimientoBancarioRequest.php` * `app/Http/Resources/MovimientoBancarioResource.php` * `app/Http/Controllers/MovimientoBancarioController.php` **Características:** * Tipos: deposito, retiro, transferencia\_entrada/salida, comision, interes, ajuste * Validación: monto not\_in:0 * Conciliación: fecha\_conciliacion required\_if:conciliado,true * Filtros: empresa\_id, cuenta\_bancaria\_id, tipo\_movimiento, conciliado, rango fechas * Búsqueda: numero\_referencia, descripcion, beneficiario * Relaciones: cuentaBancaria, empresa, asientoContable **Endpoint:** `GET|POST /api/movimientos-bancarios` *** ### 8. **Deducciones Legales** ✅ **Archivos:** * `app/Models/DeduccionLegal.php` * `app/Http/Requests/StoreDeduccionLegalRequest.php` * `app/Http/Requests/UpdateDeduccionLegalRequest.php` * `app/Http/Resources/DeduccionLegalResource.php` * `app/Http/Controllers/DeduccionLegalController.php` **Características:** * Tipos: ccss\_obrero, ccss\_patronal, ins\_laboral, ins\_lpt, impuesto\_renta, asociacion\_solidarista, embargo, prestamo, otros * Validación: porcentaje\_base/monto\_fijo mutuamente excluyentes (required\_without) * Aplica sobre: salario\_bruto, salario\_neto, monto\_especifico * Filtros: tipo, activa, es\_obligatoria * Búsqueda: codigo, nombre **Endpoint:** `GET|POST /api/deducciones-legales` *** ### 9. **Planillas CCSS** ✅ **Archivos:** * `app/Models/PlanillaCcss.php` * `app/Http/Requests/StorePlanillaCcssRequest.php` * `app/Http/Requests/UpdatePlanillaCcssRequest.php` * `app/Http/Resources/PlanillaCcssResource.php` * `app/Http/Controllers/PlanillaCcssController.php` **Características:** * Validación: periodo `YYYY-MM`, total\_empleados min:1 * Cálculos: total\_salarios, total\_cuota\_obrera, total\_cuota\_patronal, total\_a\_pagar * Estados: borrador, enviada, aceptada, rechazada, pagada * Archivos: archivo\_xml, archivo\_pdf * Filtros: empresa\_id, estado, periodo, rango fechas * Búsqueda: numero\_planilla * Relaciones: empresa, periodoNomina **Endpoint:** `GET|POST /api/planillas-ccss` *** ### 10. **Tipos Cliente** ✅ **Archivos:** * `app/Models/TipoCliente.php` * `app/Http/Requests/StoreTipoClienteRequest.php` * `app/Http/Requests/UpdateTipoClienteRequest.php` * `app/Http/Resources/TipoClienteResource.php` * `app/Http/Controllers/TipoClienteController.php` **Características:** * Validación: codigo único max:10 * Descuento: 0-100% * Días crédito: 0-365 * Filtros: activo * Búsqueda: codigo, nombre **Endpoint:** `GET|POST /api/tipos-clientes` *** ### 11. **Zonas Geográficas** ✅ **Archivos:** * `app/Models/ZonaGeografica.php` * `app/Http/Requests/StoreZonaGeograficaRequest.php` * `app/Http/Requests/UpdateZonaGeograficaRequest.php` * `app/Http/Resources/ZonaGeograficaResource.php` * `app/Http/Controllers/ZonaGeograficaController.php` **Características:** * Tipos: provincia, canton, distrito, zona\_ventas, ruta * Jerarquía: zona\_padre\_id (self-referencing) * Vendedor asignado: vendedor\_asignado\_id FK a empleados * Provincias incluidas: JSON array * Filtros: empresa\_id, tipo, activa, zona\_padre\_id, vendedor\_id * Búsqueda: codigo, nombre * Relaciones: empresa, zonaPadre, vendedorAsignado **Endpoint:** `GET|POST /api/zonas-geograficas` *** ### 12. **Logs Acceso Sistema** ✅ **Archivos:** * `app/Models/LogAccesoSistema.php` * `app/Http/Requests/StoreLogAccesoSistemaRequest.php` * `app/Http/Requests/UpdateLogAccesoSistemaRequest.php` * `app/Http/Resources/LogAccesoSistemaResource.php` * `app/Http/Controllers/LogAccesoSistemaController.php` **Características:** * Tipos evento: login\_exitoso, login\_fallido, logout, cambio\_password, reset\_password, bloqueo\_cuenta, desbloqueo\_cuenta * Validación: ip\_address IP format max:45 * Condicional: razon\_fallo required\_if:tipo\_evento,login\_fallido * Auditoría: user\_agent, sesion\_id, duracion\_sesion * Geolocalización: pais (ISO 3166-1 alpha-2), ciudad * Filtros: usuario\_id, tipo\_evento, ip\_address, rango fechas * Búsqueda: email, ip\_address, user\_agent * Relaciones: usuario * Métodos helper estáticos: registrarLoginExitoso(), registrarLoginFallido() **Endpoint:** `GET|POST /api/logs-acceso-sistema` *** ## 🔧 Patrones de Implementación ### **FormRequests - Validaciones** #### **Store (Creación):** ```php public function rules(): array { return [ 'empresa_id' => ['required', 'exists:empresas,id'], 'codigo' => ['required', 'string', 'max:10', 'unique:tabla,codigo'], 'tipo' => ['required', 'in:opcion1,opcion2,opcion3'], 'periodo' => ['required', 'regex:/^\d{4}-\d{2}$/'], 'porcentaje' => ['required', 'numeric', 'min:0', 'max:100'], 'monto' => ['required', 'numeric', 'min:0'], 'fecha' => ['required', 'date'], 'activo' => ['boolean'], ]; } ``` #### **Update (Actualización):** ```php public function rules(): array { $id = $this->route('model_name'); return [ 'empresa_id' => ['sometimes', 'exists:empresas,id'], 'codigo' => ['sometimes', 'unique:tabla,codigo,' . $id], 'tipo' => ['sometimes', 'in:opcion1,opcion2,opcion3'], 'periodo' => ['sometimes', 'regex:/^\d{4}-\d{2}$/'], // ... todos los campos 'sometimes' para PATCH ]; } ``` ### **Resources - Transformación** ```php public function toArray(Request $request): array { return [ 'id' => $this->id, 'codigo' => $this->codigo, 'nombre' => $this->nombre, 'monto' => (float) $this->monto, 'porcentaje' => (float) $this->porcentaje, 'activo' => (bool) $this->activo, 'fecha' => $this->fecha?->toISOString(), 'created_at' => $this->created_at?->toISOString(), // Relaciones 'empresa' => $this->whenLoaded('empresa', fn() => [ 'id' => $this->empresa->id, 'nombre' => $this->empresa->nombre, ]), ]; } ``` ### **Controllers - Filtrado y Búsqueda** ```php public function index(Request $request) { $query = Model::with(['relacion1', 'relacion2']); // Multi-tenancy if ($request->filled('empresa_id')) { $query->where('empresa_id', $request->empresa_id); } // Filtro por tipo if ($request->filled('tipo')) { $query->where('tipo', $request->tipo); } // Filtro por estado if ($request->filled('estado')) { $query->where('estado', $request->estado); } // Búsqueda if ($request->filled('search')) { $search = $request->search; $query->where(function($q) use ($search) { $q->where('campo1', 'like', "%{$search}%") ->orWhere('campo2', 'like', "%{$search}%"); }); } // Rango de fechas if ($request->filled('fecha_desde')) { $query->where('fecha', '>=', $request->fecha_desde); } if ($request->filled('fecha_hasta')) { $query->where('fecha', '<=', $request->fecha_hasta); } $results = $query->latest()->paginate($request->per_page ?? 15); return ModelResource::collection($results); } ``` *** ## 🎯 Validaciones Costa Rica Específicas ### **1. IBAN Costa Rica** ```php 'iban' => ['nullable', 'size:22', 'regex:/^CR\d{20}$/', 'unique:cuentas_bancarias,iban'] ``` * Formato: `CR` + 20 dígitos * Longitud total: 22 caracteres * Único en la tabla ### **2. Períodos Fiscales** ```php 'periodo_fiscal' => ['required', 'regex:/^\d{4}-\d{2}$|^\d{4}$/'] ``` * Mensual: `YYYY-MM` (ej: `2025-01`) * Anual: `YYYY` (ej: `2025`) ### **3. Códigos DGT** ```php 'codigo_dgt' => ['required', 'string', 'size:2', 'unique:tipos_comprobantes_fe,codigo_dgt'] ``` * Comprobantes: 01-09 * Exactamente 2 caracteres ### **4. Deducciones Mutuamente Excluyentes** ```php 'porcentaje_base' => ['required_without:monto_fijo', 'numeric', 'min:0', 'max:100'], 'monto_fijo' => ['required_without:porcentaje_base', 'numeric', 'min:0'] ``` * Debe tener porcentaje O monto fijo, no ambos *** ## 📊 Estadísticas del Proyecto ### **Archivos Creados:** | Tipo | Cantidad | | -------------- | --------- | | Modelos | 12 | | StoreRequests | 12 | | UpdateRequests | 12 | | Resources | 12 | | Controllers | 12 | | Rutas API | 12 grupos | | **TOTAL** | **61** | ### **Líneas de Código:** * **Validaciones:** \~600 líneas * **Resources:** \~500 líneas * **Controllers:** \~800 líneas * **Modelos:** \~1,200 líneas (de commit previo) * **Total:** \~3,100 líneas ### **Commits:** 1. `7d629e2` - 12 Modelos Eloquent 2. `83481a3` - 24 FormRequests + 12 Resources base 3. `0843d55` - Personalización completa (1,647 inserciones) *** ## 🚀 Uso de la API ### **Ejemplo: Crear Declaración IVA (D104)** **Request:** ```http POST /api/declaraciones-tributarias Content-Type: application/json { "empresa_id": 1, "tipo_declaracion": "D104", "periodo_fiscal": "2025-01", "fecha_inicio_periodo": "2025-01-01", "fecha_fin_periodo": "2025-01-31", "total_ventas_gravadas": 1500000.00, "total_ventas_exentas": 200000.00, "total_compras_gravadas": 800000.00, "total_iva_debito": 195000.00, "total_iva_credito": 104000.00, "iva_a_pagar": 91000.00, "estado": "borrador" } ``` **Response:** ```json { "id": 1, "empresa_id": 1, "tipo_declaracion": "D104", "periodo_fiscal": "2025-01", "fecha_inicio_periodo": "2025-01-01T00:00:00.000Z", "fecha_fin_periodo": "2025-01-31T00:00:00.000Z", "total_ventas_gravadas": 1500000.0, "total_ventas_exentas": 200000.0, "total_compras_gravadas": 800000.0, "total_iva_debito": 195000.0, "total_iva_credito": 104000.0, "iva_a_pagar": 91000.0, "iva_a_favor": 0.0, "estado": "borrador", "created_at": "2025-01-28T15:30:00.000Z", "empresa": { "id": 1, "nombre": "Empresa Demo SA" } } ``` ### **Ejemplo: Listar Cuentas Bancarias Activas** **Request:** ```http GET /api/cuentas-bancarias?empresa_id=1&activa=1&moneda=CRC&per_page=10 ``` **Response:** ```json { "data": [ { "id": 1, "empresa_id": 1, "banco": "Banco Nacional de Costa Rica", "numero_cuenta": "****5678", "iban": "CR12345678901234567890", "tipo_cuenta": "corriente", "moneda": "CRC", "saldo_actual": 5000000.0, "saldo_conciliado": 4950000.0, "es_principal": true, "activa": true, "empresa": { "id": 1, "nombre": "Empresa Demo SA" } } ], "links": {...}, "meta": {...} } ``` ### **Ejemplo: Filtrar Movimientos Bancarios por Rango** **Request:** ```http GET /api/movimientos-bancarios?cuenta_bancaria_id=1&fecha_desde=2025-01-01&fecha_hasta=2025-01-31&tipo_movimiento=deposito&conciliado=0 ``` *** ## ✅ Checklist de Completado ### **Modelos** * [x] MensajeHacienda * [x] TipoComprobanteFe * [x] CodigoActividadEconomica * [x] DeclaracionTributaria * [x] RetencionImpuesto * [x] CuentaBancaria * [x] MovimientoBancario * [x] DeduccionLegal * [x] PlanillaCcss * [x] TipoCliente * [x] ZonaGeografica * [x] LogAccesoSistema ### **FormRequests** * [x] 12 StoreRequests con validaciones completas * [x] 12 UpdateRequests con 'sometimes' * [x] Validaciones Costa Rica (IBAN, períodos, códigos DGT) * [x] Mensajes personalizados en español ### **Resources** * [x] 12 Resources con mapeo completo * [x] Formateo de decimales, fechas, booleanos * [x] Relaciones con whenLoaded() * [x] Campos sensibles enmascarados ### **Controllers** * [x] 12 Controllers con filtros y búsqueda * [x] Eager loading de relaciones * [x] Paginación configurable * [x] Mensajes en español ### **Rutas** * [x] 12 grupos apiResource registrados * [x] Documentación en routes/api.php ### **Control de Versiones** * [x] Commit de modelos (7d629e2) * [x] Commit de archivos base (83481a3) * [x] Commit de personalización (0843d55) * [x] Push a repositorio remoto *** ## 🔜 Próximos Pasos (Opcional) ### **1. Tests Automatizados** * Unit tests para validaciones * Feature tests para endpoints * Tests de relaciones Eloquent ### **2. Documentación Swagger** * Anotaciones OpenAPI en controllers * Schemas en `app/Http/Schemas/` * Generación con `php artisan l5-swagger:generate` ### **3. Permisos y Middleware** * Definir permisos RBAC * Aplicar middleware `permission:` a rutas * Seeds de permisos ### **4. Seeders de Datos** * Tipos comprobantes FE catálogo DGT * Códigos actividad económica * Deducciones legales estándar CCSS * Zonas geográficas Costa Rica (provincias, cantones, distritos) *** ## 📝 Notas Técnicas ### **Convenciones de Nombres:** * **Modelos:** Singular, PascalCase (MensajeHacienda) * **Tablas:** Plural, snake\_case (mensajes\_hacienda) * **Rutas:** Plural, kebab-case (mensajes-hacienda) * **Controllers:** Singular + Controller (MensajeHaciendaController) ### **Soft Deletes:** Todos los modelos implementan `SoftDeletes` mediante el trait `HasCustomSoftDeletes`. ### **Multi-tenancy:** Modelos con `empresa_id` implementan `BelongsToTenant` trait para scope automático. ### **Auditoría:** Trait `HasAuditFields` registra automáticamente `creado_por`, `actualizado_por`, `eliminado_por`. ### **Scope Activos:** Trait `HasActiveScope` provee scope `activos()` y método `esActivo()`. *** ## 🎓 Documentación Relacionada * [FASE\_9\_ARCHIVOS\_GENERADOS.md](/senselab-docs/docs/archive/fase_9_archivos_generados.md) - Documentación inicial * [DATABASE\_README.md](https://github.com/jeremy-sud/Senselab_Core_API/blob/main/docs/archive/DATABASE_README.md) - Estructura de base de datos * [API\_DOCUMENTATION.md](https://github.com/jeremy-sud/Senselab_Core_API/blob/main/docs/archive/API_DOCUMENTATION.md) - Documentación general API * [FORMREQUESTS\_USAGE\_GUIDE.md](https://github.com/jeremy-sud/Senselab_Core_API/blob/main/docs/archive/FORMREQUESTS_USAGE_GUIDE.md) - Guía de validaciones *** **Desarrollado por:** GitHub Copilot\ **Proyecto:** Senselab Core API\ **Framework:** Laravel 12.37.0\ **PHP:** 8.2+\ **Base de Datos:** MySQL 8.0+ --- # 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_completa.md?ask= ``` 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.