¿La tarea se muestra como completada, pero la descarga es un archivo vacío? Estado de ejecución y entrega separados

La página de tareas muestra "Completado", pero cuando hago clic en descargar, aparece un archivo vacío. El problema a menudo no es el texto del mensaje en sí, sino que el backend solo registra el final de la ejecución del algoritmo y no registra si la entrega está lista. Este artículo está escrito para desarrolladores que realizan procesamiento de documentos, tareas asincrónicas o integración de traducción. Después de leer, sabrá cómo separar el estado de ejecución y el estado de entrega para que la interfaz pueda mostrar el progreso real al usuario.

Los ejemplos de este artículo utilizan muestras sintéticas y el código se ha verificado en un entorno aislado. Esto no representa una garantía de todos los archivos reales o efectos del producto. Antes de procesar documentos importantes, conserve los originales y revíselos de acuerdo con los límites y elementos de aceptación del texto.

¿La descarga es un archivo vacío, pero la tarea se muestra como completada? Conclusión de una frase

Primero divida el "procesamiento completado" en tres estados: procesamiento, producto y aceptación, y luego deje que la interfaz solo muestre el estado confirmado.

Al menos diferenciar entre procesamiento, producto y aceptación.

El final del procesamiento significa que el cálculo se ha detenido; el producto está listo, lo que significa que se puede localizar el archivo; y se completa la aceptación, lo que significa que el fichero cumple con el acuerdo de entrega. Los tres no necesariamente ocurren al mismo tiempo.

Las fallas también deben tener etapas y no pueden ocultarse mediante un ícono que gira permanentemente. El usuario sabe si ocurrió un error durante el procesamiento, la generación o la verificación, por lo que sabe si debe esperar, volver a intentar o reparar la entrada.

📊 Comparación central

Negar explícitamente el éxito en el salto

from enum import Enum

class State(Enum):
    PROCESSING = "processing"
    ARTIFACT_READY = "artifact_ready"
    VERIFIED = "verified"
    FAILED = "failed"

def transition(state, event):
    allowed = {
        (State.PROCESSING, "stored"): State.ARTIFACT_READY,
        (State.PROCESSING, "error"): State.FAILED,
        (State.ARTIFACT_READY, "checks_passed"): State.VERIFIED,
        (State.ARTIFACT_READY, "error"): State.FAILED,
    }
    if (state, event) not in allowed:
        raise ValueError("invalid state transition")
    return allowed[(state, event)]

s = transition(State.PROCESSING, "stored")
assert s is State.ARTIFACT_READY
assert transition(s, "checks_passed") is State.VERIFIED
assert transition(s, "error") is State.FAILED
try:
    transition(State.PROCESSING, "checks_passed")
except ValueError:
    pass
else:
    raise AssertionError("cannot skip artifact readiness")

Esta máquina de estados sintéticos no incluye cancelación, revisión ni eliminación de vencimiento de cola. Las implementaciones de producción deben escalar según el negocio, en lugar de agrupar todos los eventos en un binario de "éxito/fracaso".

Los mensajes asincrónicos también pueden repetirse o estar desordenados, lo que requiere la cooperación de números de versión, transacciones y procesamiento idempotente. De lo contrario, los mensajes antiguos pueden sobrescribir el estado nuevo y la misma tarea puede escribirse repetidamente.

Las indicaciones del front-end deben corresponder a los hechos

Cada estado en el front-end debe corresponder a un hecho que pueda ser confirmado por el back-end y proporcionar las acciones disponibles correspondientes.

Incluso si la descarga se realiza correctamente, no significa que el contenido sea correcto.

HTTP 200 puede devolver una página de inicio de sesión, un JSON incorrecto o un documento en blanco. La aceptación deberá comprobar al menos los siguientes puntos:

• Tipo: si el formato del archivo es el esperado
• Tamaño: si el archivo está vacío o es obviamente anormal
• Disponibilidad de análisis: si el archivo se puede abrir y analizar normalmente
• Contenido esperado: si el contenido es consistente con los requisitos de la tarea

Para la traducción, la integridad del idioma y la revisión terminológica son comprobaciones de nivel superior y no deben reemplazarse por "el archivo se puede abrir".

Mantenga el estado transparente al integrar capacidades de traducción

Después de acceder a OmniDoc (portal de productos), sus propios productos aún deben mantener su propio estado de almacenamiento y entrega. Una vez completada la tarea de la plataforma, primero se puede asignar a "Comenzar a recibir resultados" y luego se mostrará el éxito después de confirmar que el archivo está disponible. Esto está más en línea con la experiencia real del usuario que transmitir directamente un estado.

Referencias: Python enum

🎯 ¿Qué método es el adecuado para ti?

si usted……

Si su tarea es solo un cálculo en segundo plano y no hay un archivo de entrega externo

Sólo es necesario registrar el final del procesamiento y las etapas de falla, y se puede omitir temporalmente el producto y la aceptación.

Si necesita permitir que los usuarios descarguen los resultados

Debe esperar hasta que el producto esté listo y haya pasado la aceptación antes de que se muestre como disponible para descargar.

Si tiene acceso a una plataforma de procesamiento de terceros

Asigne la finalización de la plataforma a "Comenzar a recibir resultados" y luego muestre el éxito después de confirmar el archivo.

Si las tareas pueden repetirse o devolverse fuera de orden

Agregue un número de versión al estado y asegúrese de que el estado solo avance a través de transacciones y procesamiento idempotente.

❓ Preguntas frecuentes (FAQ)

1. La tarea se muestra como completada, ¿por qué no se puede descargar todavía?

Debido a que el final del procesamiento solo significa que el cálculo se ha detenido, también es necesario confirmar que el producto está listo y aprobado, lo que significa que el archivo cumple con el acuerdo de entrega.

2. La descarga devuelve HTTP 200. ¿Significa esto que no hay ningún problema con el archivo?

incierto. HTTP 200 puede devolver una página de inicio de sesión, JSON incorrecto o un documento en blanco, lo que también requiere comprobaciones de tipo, tamaño, disponibilidad de análisis y contenido esperado.

3. ¿Por qué el estado de falla tiene etapas?

La fase de falla le dice al usuario si el problema se está procesando, generando o verificando, para que pueda decidir esperar, volver a intentar o corregir la entrada.

4. ¿Es suficiente que el archivo se pueda abrir para tareas de traducción?

no es suficiente. Las comprobaciones de terminología e integridad del idioma son comprobaciones de nivel superior y no deben sustituirse por "el archivo se puede abrir".

📝 Resumen

Solo separando el estado de ejecución y el estado de entrega la interfaz puede informarle al usuario el progreso real. Solo cuando el producto esté listo y pase la aceptación deberá mostrarse como disponible para descargar.

Pruébelo ahora: cargue el documento para comenzar la traducción, conservando el diseño original