README

🚧 PAQUETE EN DESARROLLO ACTIVO - ALPHA

Este paquete se encuentra en fase de desarrollo activo (v0.1.0-alpha) y NO está listo para producción.

Progreso actual: 92% (7 de 9 fases completadas)

🔬 Buscamos colaboradores para testing en entornos reales antes de la release v1.0.0

⚠️ NO está disponible en Packagist - Solo instalación local para desarrollo y testing

🎯 ¿Qué es Lara Verifactu?

Paquete Laravel para cumplimiento normativo de Verifactu (AEAT) con arquitectura agnóstica que permite integración tanto en proyectos nuevos como en sistemas de facturación existentes.

📅 Fechas Importantes de la Normativa

29 de julio de 2025: Obligatorio para software de facturación
1 de enero de 2026: Obligatorio para empresas
1 de julio de 2026: Obligatorio para autónomos

✨ Características Implementadas

✅ Arquitectura Agnóstica: Funciona con tus modelos existentes o usa los nativos
✅ Cumplimiento Total AEAT: Implementación completa según especificaciones
✅ Integración Real AEAT: Cliente SOAP con certificados digitales (.p12/.pfx)
✅ Firma Digital XAdES-EPES: Firma XML según normativa
✅ Procesamiento Asíncrono: Sistema de colas para envíos no bloqueantes
✅ Cadena de Bloques: Generación y validación de hashes SHA-256
✅ Códigos QR: Generación automática para validación ciudadana
✅ Eventos Laravel: Sistema completo de eventos para extensibilidad
✅ PHPStan Nivel 8: Análisis estático estricto
✅ Laravel 12: Compatible con la última versión LTS

🔧 Requisitos Técnicos

PHP 8.3 o superior
Laravel 12.x
Extensiones: soap, openssl, dom, libxml

📊 Estado del Desarrollo

┌─────────────────────────────────────────────────────────┐
│  PROGRESO TOTAL: 92%                                    │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━    │
│                                                         │
│  ✅ Fase 1: Package Skeleton & Architecture    (100%)   │
│  ✅ Fase 2: Core Services                      (100%)   │
│  ✅ Fase 3: Database Layer                     (100%)   │
│  ✅ Fase 4: Service Integration                (100%)   │
│  ✅ Fase 5: Commands & Jobs                    (100%)   │
│  ✅ Fase 6: Events & Listeners                 (100%)   │
│  ✅ Fase 7: AEAT API Integration               (100%)   │
│  🚧 Fase 8: Testing & Documentation            (50%)    │
│  ⏳ Fase 9: Production Hardening               (0%)     │
│                                                         │
│  Tests: 120/120 ✅  |  PHPStan: Level 8 ✅              │
└─────────────────────────────────────────────────────────┘

🚀 Instalación (Desarrollo Local)

⚠️ IMPORTANTE: Este paquete NO está publicado en Packagist. Solo se puede instalar desde el repositorio local para desarrollo y testing.

Opción 1: Path Repository (Recomendado)

Clona el repositorio en tu workspace local:

cd ~/development/packages
git clone https://github.com/AichaDigital/lara-verifactu.git
cd lara-verifactu
composer install

En tu proyecto Laravel, añade el repositorio local en composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../packages/lara-verifactu",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "aichadigital/lara-verifactu": "@dev"
    }
}

Instala el paquete:

composer update aichadigital/lara-verifactu

Composer creará un symlink desde vendor/aichadigital/lara-verifactu a tu repositorio local.

Opción 2: Symlink Manual

# En tu proyecto Laravel
cd vendor
mkdir -p aichadigital
cd aichadigital
ln -s ~/development/packages/lara-verifactu lara-verifactu

Configuración Inicial

# Publicar configuración y migraciones
php artisan verifactu:install

# Configurar certificado digital en .env
VERIFACTU_ENVIRONMENT=sandbox
VERIFACTU_CERT_PATH=./certificates/tu_certificado.p12
VERIFACTU_CERT_PASSWORD=tu_password

# Probar conexión con AEAT
php artisan verifactu:test-connection

📚 Documentación

Instalación y Configuración

Uso Básico

Para Desarrolladores

🤝 Guía de Contribución
🏗️ Arquitectura del Paquete
🧪 Testing

💡 Uso Rápido

Comandos Artisan

# Probar conexión y certificado AEAT
php artisan verifactu:test-connection
php artisan verifactu:test-connection --cert-info

# Registrar factura en AEAT
php artisan verifactu:register {invoice_id}
php artisan verifactu:register --all

# Reintentar envíos fallidos
php artisan verifactu:retry-failed

# Verificar integridad blockchain
php artisan verifactu:verify-blockchain

# Ver estado del sistema
php artisan verifactu:status

Uso Programático

use AichaDigital\LaraVerifactu\Facades\Verifactu;
use AichaDigital\LaraVerifactu\Models\Invoice;

// Registrar factura
$invoice = Invoice::find(1);
$registry = Verifactu::register($invoice);

// Verificar blockchain
$isValid = Verifactu::verifyBlockchain();

// Obtener registros pendientes
$pending = Verifactu::getPendingRegistries();

🏗️ Arquitectura

Principios de Diseño

Contract-First: Interfaces antes que implementaciones
Agnostic: Funciona con cualquier modelo que implemente los contratos
SOLID: Principios aplicados rigurosamente
Event-Driven: Extensible mediante eventos Laravel

Estructura del Paquete

lara-verifactu/
├── src/
│   ├── Contracts/          # Interfaces
│   ├── Models/             # Eloquent models (modo nativo)
│   ├── Services/           # Lógica de negocio
│   ├── Commands/           # Artisan commands
│   ├── Jobs/               # Queue jobs
│   ├── Events/             # Event classes
│   ├── Listeners/          # Event listeners
│   ├── Exceptions/         # Custom exceptions
│   ├── Enums/              # Enumerations
│   └── Support/            # Helper classes
├── tests/
│   ├── Unit/               # Unit tests
│   ├── Feature/            # Feature tests
│   └── Pest.php
├── config/
│   └── verifactu.php       # Configuración
├── database/
│   ├── migrations/         # Database migrations
│   └── factories/          # Model factories
└── resources/
    └── lang/               # Translations

🧪 Testing

# Ejecutar todos los tests
composer test

# Tests con cobertura
composer test:coverage

# Análisis estático (PHPStan)
composer analyse

# Formatear código (Laravel Pint)
composer format

# Code quality (PHP Insights)
composer insights

Estado Actual de Tests

✅ 120 tests passing
✅ Coverage: >85%
✅ PHPStan Level 8
✅ PSR-12 Code Style

🤝 Contribuir

¡Las contribuciones son bienvenidas! Este paquete está en desarrollo activo y buscamos colaboradores para:

🧪 Testing en entornos reales
📖 Mejorar documentación
🐛 Reportar bugs
💡 Sugerir mejoras
🔧 Implementar features

Por favor, lee CONTRIBUTING.md para detalles sobre nuestro proceso de desarrollo.

Áreas que Necesitan Ayuda

Testing en Sandbox AEAT: Probar envíos reales al sandbox
Casos de Uso: Documentar diferentes escenarios de integración
Modelos Personalizados: Testing con modelos existentes en proyectos reales
Performance: Optimizaciones para alto volumen de facturas
Documentación: Ejemplos y guías de uso

🐛 Reportar Issues

Si encuentras un bug o tienes una sugerencia:

Busca si ya existe un issue similar
Si no existe, crea uno nuevo
Incluye:
- Versión de Laravel
- Versión de PHP
- Descripción detallada del problema
- Pasos para reproducir
- Código de ejemplo si es posible

📝 Changelog

Consulta CHANGELOG.md para ver todos los cambios del proyecto.

🔒 Seguridad

Si descubres alguna vulnerabilidad de seguridad, por favor envía un email a security@aichadigital.com en lugar de usar el issue tracker.

📄 Licencia

The MIT License (MIT). Por favor, consulta License File para más información.

🙏 Créditos

Aicha Digital
Basado en especificaciones de AEAT Verifactu
Inspirado en Spatie Laravel Packages
Todos los contribuidores

📞 Soporte

📧 Email: support@aichadigital.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

⚠️ Recordatorio: Este paquete está en desarrollo activo y NO debe usarse en producción.
Release estable (v1.0.0) estimada para Q2 2025

Made with ❤️ by Aicha Digital

aichadigital / lara-verifactu

Maintainers

Details