Document status, task polling, and edit lifecycle

This page documents the read and edit surfaces that sit on top of the upload pipeline:

api/views/document_processing_views/status_views.py
api/views/task_status_view.py
api/views/document_views.py

These endpoints are the main way clients observe or refine processing output after the initial upload.

Task polling versus document status

TaskStatusAPIView is the worker-facing poll endpoint. It is keyed by celery_task_id and only returns the document that belongs to the authenticated user. Its response shape includes the current status, file metadata, processing mode, schema info, and, when complete, extracted JSON data.

DocumentStatusAPIView is the document-facing status endpoint. It retrieves by document primary key and adds staff/ownership checks before returning status and extracted results.

The two endpoints are deliberately distinct because the first is queue-oriented and the second is document-oriented.

Metaprocessing metadata

MetaprocessingAPIView returns the minimal metadata needed by the UI to understand a file’s processing context: file_id and schema_id, plus ownership checks and the extracted payload when the record is complete.

Editable extraction semantics

ProcessingDocumentViewSet is the only place where users can refine extracted data after processing. The important invariants are:

only allowed states can be patched
the backend computes the diff rather than trusting the frontend’s claimed change list
edited_by is derived from the authenticated user
edit_history accumulates over time and is never silently lost
existing edit_history survives a patch that does not mention it

Source-grounded edit behavior

The tests in api/tests/test_document_edit_audit.py and api/tests/test_edit_history.py are the strongest evidence for this lifecycle:

diff generation on nested fields and line_items
one-time edit restriction for completed documents
audit log creation on edits
response shaping for edit_history
protection against storing edited_by = 'Unknown'

Failure modes

unknown task IDs return TASK_NOT_FOUND
completed or failed documents can expose distinct response shapes
edits on disallowed statuses are rejected before persistence
permission failures are returned when the user does not own the document

Validation

api/tests/test_document_edit_audit.py
api/tests/test_edit_history.py
tests/integration/test_async_document_processing.py
tests/integration/test_document_processing.py

Scope boundary

This page is about the observable lifecycle after upload. For upload-time validation, read Document upload and validation. For the worker implementation, read Services.