README

Biblioteca PHP para el cálculo simple de fechas de vencimiento de PQR (Peticiones, Quejas y Reclamos) para Colombia.

Características

Múltiples estrategias de cálculo: Días hábiles, días calendario y horas
Soporte para festivos colombianos: Integración con cmixin/business-day
Manejo de suspensiones: Cálculo dinámico con traslapes y validaciones
Identificadores únicos: Soporte opcional para ULID en suspensiones
Tipos de PQR predefinidos: 14 tipos según normativa colombiana
Duplicación de plazos: Soporte para segunda instancia
Validaciones robustas: Control de errores y casos edge
Documentación completa: Lógica de negocio detallada en código
Cobertura total: 42 tests, 59 assertions

Instalación

composer require micrositios/pqrdeadline

Requisitos

PHP >= 8.1
nesbot/carbon ^3.0
cmixin/business-day ^1.16

Uso Básico

use Micrositios\PqrDeadline\DeadlineWrapper;
use Carbon\Carbon;

// Crear PQR
$createdAt = Carbon::now();
$requestType = 'peticion_general';
$doubleTerm = false;

// Calcular deadline
$wrapper = DeadlineWrapper::setup($requestType, $createdAt, $doubleTerm);
$deadline = $wrapper->calculateDeadline();

echo "Vencimiento: " . $deadline->format('Y-m-d H:i:s');

Estrategias de Cálculo

1. Días Hábiles (BusinessDaysDeadlineCalculator)

Uso: Mayoría de PQR (peticiones, quejas, reclamos, etc.)
Características: Excluye fines de semana y festivos colombianos
Inicio: Siguiente día hábil a la radicación

2. Días Calendario (CalendarDaysDeadlineCalculator)

Uso: Informes de congresistas
Características: Incluye todos los días (laborables, fines de semana, festivos)
Inicio: Día siguiente a la radicación

3. Horas (HoursDeadlineCalculator)

Uso: Reclamos de salud de riesgo vital, priorizado y simple
Características: Cálculo en horas exactas, independiente de días laborables
Inicio: Inmediato desde la hora de radicación

Tipos de PQR Soportados

Tipo	String	Plazo	Estrategia	Días Hábiles
Informe Congresistas	`informe_congresistas`	5 días	Calendario	No
Petición General	`peticion_general`	15 días	Hábiles	Sí
Petición Autoridades	`peticion_autoridades`	10 días	Hábiles	Sí
Consulta	`consulta`	30 días	Hábiles	Sí
Información Pública	`informacion_publica`	10 días	Hábiles	Sí
Copia Historia Clínica	`copia_historia_clinica`	3 días	Hábiles	Sí
Reclamo	`reclamo`	15 días	Hábiles	Sí
Queja	`queja`	15 días	Hábiles	Sí
Salud Riesgo Simple	`salud_riesgo_simple`	72 horas	Horas	No
Salud Riesgo Priorizado	`salud_riesgo_priorizado`	48 horas	Horas	No
Salud Riesgo Vital	`salud_riesgo_vital`	24 horas	Horas	No
Denuncia	`denuncia`	15 días	Hábiles	Sí
Sugerencia	`sugerencia`	15 días	Hábiles	Sí
Felicitación	`felicitacion`	15 días	Hábiles	Sí

Tests

Para ejecutar los tests y ver la documentación completa de pruebas, consulta tests/README.md.

# Ejecutar todos los tests
vendor/bin/phpunit

# Con formato legible
vendor/bin/phpunit --testdox

Total: 42 tests, 59 assertions cubriendo las 3 estrategias de cálculo.

Ejemplos de Uso

Forma Automática: Usando String

La forma más simple de usar la librería es con el método DeadlineWrapper::setup():

use Micrositios\PqrDeadline\DeadlineWrapper;
use Carbon\Carbon;

// Petición general (15 días hábiles)
$wrapper = DeadlineWrapper::setup(
    'peticion_general',
    Carbon::create(2024, 1, 15, 10, 30),
    false // no duplicar
);

$deadline = $wrapper->calculateDeadline();
// Resultado: 2024-02-05 23:59:59

Forma Automática: Con Suspensiones

use Micrositios\PqrDeadline\DeadlineWrapper;
use Carbon\Carbon;

// Petición general con suspensiones
$wrapper = DeadlineWrapper::setup(
    'peticion_general',
    Carbon::create(2024, 1, 15, 10, 30),
    false
);

// Agregar suspensiones usando injectSuspensions
$suspensions = [
    [
        'start_at' => Carbon::create(2024, 1, 20, 8, 0),
        'end_at' => Carbon::create(2024, 1, 22, 17, 0)
    ]
];

$deadline = $wrapper->injectSuspensions($suspensions)->calculateDeadline();

Forma Manual: Parámetros Explícitos

Para casos que requieren mayor control, pasa un array de parámetros a DeadlineWrapper::setup():

use Micrositios\PqrDeadline\DeadlineWrapper;
use Carbon\Carbon;

$params = [
    'created_at' => Carbon::create(2024, 1, 15, 9, 0),
    'base_days' => 15,
    'double_term' => false,
    'strategy' => 'business_days'
];

$wrapper = DeadlineWrapper::setup($params);
$deadline = $wrapper->calculateDeadline();

Forma Manual: Con Suspensiones

use Micrositios\PqrDeadline\DeadlineWrapper;
use Carbon\Carbon;

$params = [
    'created_at' => Carbon::create(2024, 1, 15, 9, 0),
    'base_days' => 15,
    'double_term' => false,
    'strategy' => 'business_days'
];

$suspensions = [
    [
        'start_at' => Carbon::create(2024, 1, 20, 8, 0),
        'end_at' => Carbon::create(2024, 1, 22, 17, 0)
    ]
];

$wrapper = DeadlineWrapper::setup($params);
$deadline = $wrapper->injectSuspensions($suspensions)->calculateDeadline();

Forma Avanzada: Estrategias Directas

Para máximo control, usa directamente las estrategias:

use Micrositios\PqrDeadline\Strategies\BusinessDaysDeadlineCalculator;
use Carbon\Carbon;

$calculator = new BusinessDaysDeadlineCalculator();

$params = [
    'created_at' => Carbon::create(2024, 1, 15, 9, 0),
    'base_days' => 15,
    'double_term' => false,
    'approximate_end_of_day' => true
];

$deadline = $calculator->calculate($params);

Forma Avanzada: Con Suspensiones

use Micrositios\PqrDeadline\Strategies\BusinessDaysDeadlineCalculator;
use Carbon\Carbon;

$calculator = new BusinessDaysDeadlineCalculator();

$params = [
    'created_at' => Carbon::create(2024, 1, 15, 9, 0),
    'base_days' => 15,
    'double_term' => false,
    'approximate_end_of_day' => true,
    'suspensions' => [
        [
            'start_at' => Carbon::create(2024, 1, 20, 8, 0),
            'end_at' => Carbon::create(2024, 1, 22, 17, 0)
        ]
    ]
];

$deadline = $calculator->calculate($params);

Arquitectura

src/
├── Contracts/
│   └── DeadlineCalculator.php          # Interface principal
├── Enums/
│   └── RequestType.php                 # Tipos de PQR
├── Strategies/
│   ├── BusinessDaysDeadlineCalculator.php     # Días hábiles
│   ├── CalendarDaysDeadlineCalculator.php     # Días calendario
│   ├── HoursDeadlineCalculator.php            # Horas
│   ├── AppliesDynamicSuspensions.php          # Trait suspensiones
│   └── StrategyFactory.php                    # Factory estrategias
└── DeadlineWrapper.php                # Wrapper principal

Contribuir

Fork el proyecto
Crear branch para feature (git checkout -b feature/nueva-funcionalidad)
Escribir tests para los cambios
Ejecutar tests (vendor/bin/phpunit)
Commit cambios (git commit -am 'Agregar nueva funcionalidad')
Push al branch (git push origin feature/nueva-funcionalidad)
Crear Pull Request

Estándares de Código

PSR-4 autoloading
PSR-12 coding style
PHPUnit para testing
Documentación en español
Cobertura de tests > 90%

Licencia

MIT License. Ver archivo LICENSE para más detalles.

Changelog

v1.1.0 (2025-09-04) 📅

Upgrade Carbon 3: Actualización a nesbot/carbon ^3.0 para mejor rendimiento
Compatibilidad mantenida: Todos los tests siguen pasando (42 tests, 59 assertions)
Dependencias actualizadas: Symfony Clock 7.3 y polyfills actualizados
API sin cambios: Misma interfaz pública, solo mejoras internas

v1.0.0 (2025-09-04) 🎉

Release estable oficial: Sistema completo de cálculo de deadlines para PQR
Documentación de lógica de negocio: Reglas específicas documentadas en todas las estrategias
Identificadores únicos: Soporte opcional para ULID en suspensiones
Cobertura completa: 42 tests, 59 assertions con 100% de éxito
Arquitectura madura: Tres estrategias consolidadas con manejo avanzado de traslapes
Reglas de negocio claras: BusinessDays (8AM-5PM, 8h=1día), CalendarDays (consecutivos), Hours (continuo)

v0.2.1

Reestructuración: DeadlineWrapper movido a directorio raíz
Eliminación de carpeta Support innecesaria
Namespace simplificado: Micrositios\PqrDeadline\DeadlineWrapper
Actualización de todas las referencias en documentación y ejemplos

v0.2.0

Limpieza y optimización del código base
Eliminación de clases no utilizadas (ErrorFactory, DomainException, validadores)
Simplificación de la arquitectura manteniendo funcionalidad completa
Actualización de documentación y ejemplos
42 tests, 59 assertions con 100% de éxito

v0.1.0

Implementación inicial con 3 estrategias de cálculo
14 tipos de PQR predefinidos
Soporte para festivos colombianos
Manejo avanzado de suspensiones
Suite completa de tests
Documentación completa

Mantenido por: Micrositios Versión: 1.1.0 PHP: >= 8.1

micrositios / pqrdeadline

Maintainers

Details