Una importación empresarial no debería obligar a escoger entre cancelar un lote completo por una fila defectuosa o incorporar datos dudosos. La cuarentena de datos en importaciones PHP ofrece una tercera opción: aceptar los registros válidos, aislar los que requieren atención y conservar suficiente contexto para resolverlos de forma segura.
La cuarentena no es simplemente una carpeta de errores ni una tabla donde guardar filas fallidas. Es un flujo operativo con reglas de clasificación, estados explícitos, corrección controlada y reintentos que no repiten efectos. Para diseñarlo, conviene acordar primero qué significa «válido» para el negocio y qué acciones puede realizar cada rol.
Clasifica los errores antes de decidir qué hacer con cada fila
Una importación suele combinar comprobaciones distintas. Separarlas permite explicar el resultado y decidir si el registro puede continuar, debe rechazarse o requiere revisión humana.
- Validación estructural: comprueba formato y contenido básico: columnas presentes, tipos de dato, fechas interpretables, campos obligatorios y límites razonables. Un archivo ilegible puede impedir procesar el lote; una fecha inválida en una sola fila normalmente no debería hacerlo.
- Reglas de negocio: comprueba condiciones del dominio, como un precio no negativo, un cliente activo o una categoría permitida. Algunas infracciones son rechazables; otras pueden depender de una decisión operativa.
- Conflictos con datos existentes: detecta, por ejemplo, un identificador externo ya asociado a otro registro o una actualización que parte de una versión obsoleta. No siempre se resuelven corrigiendo el archivo: pueden exigir conciliación o revisión.
Defina una política por tipo de error. Un campo opcional ausente puede admitir un valor predeterminado; una identidad ambigua no debería resolverse eligiendo arbitrariamente un registro. Evite tanto las reglas demasiado permisivas como clasificar todo defecto como error fatal. La decisión debe reflejar el impacto de aceptar el dato y el coste de detener el lote.
Modele estados y transiciones explícitos
Use estados con significado operativo, en vez de inferir la situación a partir de campos vacíos o mensajes de texto. Un modelo inicial puede incluir pending, accepted, rejected y needs_review. Añada estados como processing o resolved sólo si corresponden a transiciones reales de su flujo.
Documente qué permite cada transición. Por ejemplo, una fila pendiente se valida; si supera las reglas, se acepta, y si presenta un conflicto revisable, queda pendiente de revisión. Una fila corregida puede volver a validarse, pero una aceptada no debería procesarse otra vez como si fuera nueva. Registre el estado del lote por separado: un lote puede terminar con filas aceptadas y otras en cuarentena, por lo que «completado parcialmente» describe mejor el resultado que un único indicador de éxito o fracaso.
Los estados deben corresponder a decisiones comprobables. «Rechazada» debería significar que no se aplicó el cambio de negocio; «requiere revisión» indica que una persona debe tomar una decisión. Si se permite sobrescribir datos existentes, especifique quién puede hacerlo y bajo qué condiciones.
Conserva el original y explica cada decisión
Guarde la entrada original de la fila y, por separado, sus valores normalizados y el resultado de la validación. Esta separación permite investigar discrepancias —por ejemplo, diferencias entre una fecha recibida y su interpretación— sin convertir la versión transformada en la única evidencia disponible.
Una estructura de persistencia puede incluir un identificador del lote, número de fila, origen, referencia del archivo, contenido original, estado, errores detectados, fechas de creación y resolución, y actor responsable. Registre los motivos como códigos estables y mensajes legibles: un código como customer_id_ambiguous ayuda a filtrar y medir casos; el mensaje debe explicar qué dato revisar. Evite depender de texto libre como única lógica de clasificación.
Conserve también el contexto necesario para reproducir el análisis: versión o identificador de las reglas utilizadas, identificador externo y datos relevantes para el conflicto. No almacene secretos ni datos personales innecesarios en registros técnicos. Defina controles de acceso y un periodo de retención acorde con la sensibilidad y las obligaciones aplicables. Si el archivo completo puede contener información que no hace falta para resolver una fila, limite su exposición.
Corrige y reintenta sin duplicar efectos
Un reintento seguro empieza por distinguir la fila del intento de procesarla. Asigne una identidad estable a cada fila dentro de su ámbito, por ejemplo, una combinación de lote e índice de fila o una clave externa validada. En importaciones repetibles, defina además una clave de idempotencia que permita reconocer la misma operación. La elección depende de si volver a cargar el mismo archivo debe actualizar datos, ignorarlos o crear una nueva versión.
Al procesar una fila, aplique la escritura de negocio y el cambio de estado de forma atómica cuando sea posible: ambas operaciones se confirman juntas o ninguna lo hace. En PHP, una transacción de base de datos puede proteger cambios que usan la misma conexión; no vuelve atómica por sí sola una llamada a una API externa. Para efectos externos, use una estrategia compatible con el sistema receptor, como claves de idempotencia, una tabla de salida transaccional o una compensación diseñada para el caso.
Tras una corrección, vuelva a ejecutar las validaciones pertinentes y conserve el historial previo. No borre el error original: añada un nuevo intento con su resultado. Si las reglas o los datos de referencia cambian, indique qué versión se aplicó y evite que una repetición cambie silenciosamente una decisión ya aceptada. El reintento debe afectar sólo a los registros seleccionados y no volver a ejecutar indiscriminadamente todo el lote.
Diseña una revisión operativa y auditable
La interfaz de revisión debe ayudar a decidir, no limitarse a mostrar una excepción técnica. Incluya el valor recibido, el motivo, el campo afectado, el contexto relevante y, cuando sea seguro, una propuesta de corrección. Permita filtrar por estado, lote, tipo de error y antigüedad; deje claro qué filas ya produjeron efectos y cuáles no.
Registre quién revisó el caso, cuándo, qué valor modificó, la decisión tomada y el motivo. Diferencie la corrección de un operador de una transformación automática. Aplique permisos según responsabilidades: quien puede importar un archivo no necesariamente debe poder aprobar conflictos o alterar registros aceptados. Para cambios de alto impacto, considere una aprobación adicional.
Evite que la herramienta facilite sobrescribir información sin advertencia. Antes de aceptar una corrección, vuelva a comprobar unicidad, permisos y estado actual del registro. Si otra persona modificó el dato desde que se detectó el conflicto, presente esa condición para resolverla en vez de aplicar una actualización obsoleta.
Prueba fallos parciales y recuperación
Las pruebas deben cubrir tanto las reglas como el comportamiento del flujo. Incluya archivos con filas válidas e inválidas mezcladas, formatos inesperados, conflictos, errores temporales de base de datos y reintentos repetidos. Compruebe que una fila rechazada no impide aceptar las demás si esa es la política acordada, y que un fallo dentro de una transacción no deja efectos parciales.
- Reprocesar una fila con la misma clave de idempotencia no duplica registros ni acciones externas.
- Corregir un campo permite una nueva validación sin borrar el original ni el historial.
- Una fila ya aceptada no vuelve a aplicarse por el reintento de otra.
- Los conflictos detectados entre revisión y resolución no se sobrescriben silenciosamente.
- Los mensajes de error permiten actuar sin exponer datos sensibles innecesarios.
En producción, observe el volumen y la antigüedad de los registros en cuarentena, los motivos más frecuentes, la tasa de resolución y los fallos de reintento. Un aumento sostenido puede señalar un cambio en el sistema de origen, una regla desactualizada o instrucciones de carga poco claras. La cuarentena funciona cuando hace visibles esas causas y permite resolverlas con control, no cuando se convierte en un depósito indefinido de excepciones.
