Завдання відображається як виконане, але завантажується порожній файл? Окремий статус виконання та доставки

На сторінці завдання відображається "Виконано", але коли я натискаю кнопку "Завантажити", я отримую порожній файл. Проблема часто полягає не в самому тексті підказки, а в тому, що серверна частина лише записує кінець виконання алгоритму і не записує, чи готова доставка. Ця стаття написана для розробників, які займаються обробкою документів, асинхронними завданнями або інтеграцією перекладу. Після прочитання ви знатимете, як розділити статус виконання та статус доставки, щоб інтерфейс міг показувати користувачеві реальний прогрес.

У прикладах у цій статті використовуються синтетичні зразки, а код перевірено за зразком в ізольованому середовищі. Це не є гарантією всіх реальних файлів або ефектів продукту. Перед обробкою важливих документів збережіть оригінали та перегляньте їх відповідно до меж і пунктів прийняття в тексті.

Завантажується порожній файл, але завдання відображається як виконане? Висновок одним реченням

Спочатку розділіть «обробку завершено» на три стани: обробка, продукт і прийняття, а потім дозвольте інтерфейсу відображати лише підтверджений стан.

Принаймні розрізняйте обробку, продукт і прийняття

Кінець обробки означає, що обчислення зупинено; продукт готовий, а значить файл можна знайти; і приймання завершено, що означає, що файл відповідає угоді про доставку. Усі три не обов’язково відбуваються одночасно.

Помилка також повинна мати етапи і не може бути прихована піктограмою, що постійно обертається. Користувач знає, чи сталася помилка під час обробки, генерації чи перевірки, тому він знає, чи варто чекати, повторити чи відновити введення.

📊 Основне порівняння

Відверто заперечувати успішні стрибки

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")

Цей синтетичний кінцевий автомат не включає скасування черги, перегляд і видалення закінчення терміну дії. Виробничі впровадження мають масштабуватися відповідно до бізнесу, а не зводити всі події в бінарний файл «успіх/невдача».

Asynchronous messages may also be repeated or out of order, requiring the cooperation of version numbers, transactions, and idempotent processing. Інакше старі повідомлення можуть перезаписати новий статус, і те саме завдання може бути написане повторно.

Інтерфейсні підказки мають відповідати фактам

Кожен стан на інтерфейсі має відповідати факту, який може бути підтверджений на сервері та надавати відповідні доступні дії.

Навіть якщо завантаження пройшло успішно, це не означає, що вміст правильний.

HTTP 200 може повертати сторінку входу, поганий JSON або порожній документ. Під час прийняття слід перевірити принаймні такі пункти:

• Тип: чи відповідає очікуваний формат файлу
• Розмір: чи є файл порожнім або явно ненормальним
• Доступність аналізу: чи можна відкрити та проаналізувати файл нормально
• Очікуваний вміст: чи відповідає вміст вимогам завдання

Для перекладу мовна цілісність і перевірка термінології є перевірками вищого рівня, і їх не слід замінювати фразою «файл можна відкрити».

Зберігайте статус прозорим під час інтеграції можливостей перекладу

Після доступу до OmniDoc (портал продуктів) ваші власні продукти все ще мають зберігати власний статус зберігання та доставки. After the platform task is completed, it can be mapped to "Start receiving results" first, and then success will be displayed after confirming that the file is available. Це більше відповідає фактичному досвіду користувача, ніж безпосередня передача стану.

Джерела: Python enum

🎯 Який спосіб вам підходить?

якщо ви...

Якщо ваше завдання полягає лише у фоновому обчисленні та немає зовнішнього файлу доставки

Необхідно записати лише кінець обробки та стадії відмови, а продукт і приймання можна тимчасово опустити.

Якщо вам потрібно дозволити користувачам завантажувати результати

Перш ніж продукт буде відображено як доступний для завантаження, потрібно зачекати, доки продукт буде готовий і пройде схвалення.

Якщо у вас є доступ до сторонньої платформи обробки

Зіставте завершення платформи на «Почати отримання результатів», а потім відобразіть успіх після підтвердження файлу.

Якщо завдання можуть повторюватися або повертатися не в порядку

Додайте номер версії до стану та переконайтеся, що стан просувається лише через транзакції та ідемпотентну обробку.

❓ Часті запитання (FAQ)

1. Завдання відображається як виконане, чому його ще не можна завантажити?

Because the end of processing only means that the calculation has stopped, it also needs to be confirmed that the product is ready and passed acceptance, which means that the file meets the delivery agreement.

2. Завантаження повертає HTTP 200. Чи означає це, що з файлом немає проблем?

невизначений. HTTP 200 may return a login page, bad JSON, or a blank document, also requiring checks for type, size, parsing availability, and expected content.

3. Чому стан відмови має етапи?

The failure phase tells the user whether the problem is processing, generating, or checking, so they can decide to wait, retry, or fix the input.

4. Чи достатньо того, що файл можна відкрити для завдань перекладу?

недостатньо. Перевірки цілісності мови та термінології є перевірками вищого рівня, і їх не слід замінювати на «файл можна відкрити».

📝 Підсумок

Лише шляхом розділення статусу виконання та статусу доставки інтерфейс може повідомляти користувачеві про реальний прогрес. Лише коли продукт готовий і пройшов прийняття, він має відображатися як доступний для завантаження.

Спробуйте зараз: завантажте документ, щоб розпочати переклад, зберігаючи вихідний макет