Skip to content

Report Status State Machine

The Report Status State Machine defines the lifecycle and valid transitions for report generation tasks within the system^[001-TODO__code_copy.md]. It tracks the progression of a report from an initial request through to successful generation or failure, utilizing specific statuses and queue-based mechanisms to handle long-running or asynchronous operations^[001-TODO__code_copy.md].

States

The lifecycle of a report is characterized by three primary states defined in the ReportStatus enumeration^[001-TODO__code_copy.md]:

  • RUNNING (0): Represents the initial state where the report request has been received and is currently being processed^[001-TODO__code_copy.md].
  • SUCCESS (1): The terminal state indicating that the report document was generated successfully and the file path has been persisted^[001-TODO__code_copy.md].
  • FAIL (2): The terminal state indicating that the report generation process failed to complete, often resulting in an error message being logged^[001-TODO__code_copy.md].

State Transitions

The transition between states is managed through database updates and Message Queue workflows^[001-TODO__code_copy.md].

Initialization

When a report is requested, a new record is created in the database with the status set to RUNNING^[001-TODO__code_copy.md]. A message containing the query details is then sent to a Message Queue (specifically RabbitMQ) trigger the asynchronous generation process^[001-TODO__code_copy.md].

Success Transition

If the document generation process completes without error, the system updates the record's status from RUNNING to SUCCESS^[001-TODO__code_copy.md]. This update transactionally saves the generated filePath to the database^[001-TODO__code_copy.md].

Failure Transition

A report transitions to the FAIL state under specific error conditions or timeouts^[001-TODO__code_copy.md]:

  • Immediate Failure: If an error occurs during generation, the status is updated to FAIL, and an errorMessage is recorded^[001-TODO__code_copy.md].
  • Timeout Handling: The system utilizes a Delay Queue mechanism. If a task remains in the RUNNING state for a configured duration (e.g., 5 minutes), it is routed to a Dead Letter Queue^[001-TODO__code_copy.md]. A listener consumes this message and explicitly updates the database status to FAIL with the message "make report timeout"^[001-TODO__code_copy.md].