Encapsulate application state transitions logic in the Application model

[mrogaski]

As noted in views.ApplicationStatusView, the logic for validating and applying state transitions should be encapsulated and direct updates to the status should be prevented.

An example why this is necessary is that models.get_legal_state_changes doesn't appear to allow applications to enter the ASSIGNMENT_PENDING or ASSIGNMENT states.

stateDiagram-v2
    [*] --> APPLIED
    APPLIED --> INVITATION_PENDING
    APPLIED --> INVITED
    APPLIED --> REJECTION_PENDING
    APPLIED --> REJECTED
    APPLIED --> WITHDRAWN
    INVITATION_PENDING --> APPLIED
    INVITATION_PENDING --> INVITED
    INVITATION_PENDING --> CONFIRMED
    INVITATION_PENDING --> WITHDRAWN
    INVITED --> CONFIRMED
    INVITED --> DECLINED
    INVITED --> WITHDRAWN
    REJECTION_PENDING --> APPLIED
    REJECTION_PENDING --> REJECTED
    REJECTION_PENDING --> WITHDRAWN
    ASSIGNMENT_PENDING --> ASSIGNED
    ASSIGNMENT_PENDING --> WITHDRAWN
    ASSIGNED --> WITHDRAWN
    CONFIRMED --> WITHDRAWN

Loading

Enforcing the use of a setter method on the Application model should fix this.

[davidmreed]

@mrogaski The name of the function get_legal_state_changes() is poorly chosen. What that method returns is actually the state changes that a given user can make by clicking a button in the UI, not the states that it is permissible for the record to enter.

The assignment-related stages are entered by using Crew Builder to assign a role, and then sending a schedule email. They can't be set directly from the Application's action buttons.

This supports your overall point, of course! And I'd love to have that logic encapsulated more cleanly.

[miketheman]

Nice visualization, makes it look very much like a Finite State Machine to me!

One potential library that helps encapsulate these concepts might be https://docs.viewflow.io/fsm/index.html

[mrogaski]

I've used the precursor, django-fsm, before and really liked its API. It looks like they've continued the API and it can be used independently of the rest of Viewflow, so it's worth considering.