feature: Invite an existing user to an Organisation as a manager

[Joe-Heffer-Shef]

This branches the workflow for situations where the user already exists. They must log in before being added to the Org as a manager to check their invitation token and auth credentials.

There's a few checkpoints along the way to check for edge case situations and inform the user.

flowchart TD                                                                                                                                                                                                                                                                                                  
    Start([User receives invitation email]) --> Click[User clicks invitation link]
    Click --> Accept[POST to MyOrganisationAcceptInviteView]                                                                                                                                                                                                                                                  
                                                                                                                                                                                                                                                                                                            
    Accept --> CheckExists{Does user<br/>already exist?}

    %% NEW USER FLOW
    CheckExists -->|No - New User| CallSuper[Call super.post<br/>Mark invitation accepted]
    CallSuper --> RedirectSignup[Redirect to<br/>Signup page]
    RedirectSignup --> SignupForm[User fills<br/>signup form]
    SignupForm --> CreateUser[Create new User<br/>account]
    CreateUser --> AddToOrg1[Add user to organisation<br/>Role: PROJECT_MANAGER]
    AddToOrg1 --> AutoLogin[Auto-login user]
    AutoLogin --> Dashboard1[Redirect to<br/>Dashboard]
    Dashboard1 --> End1([✅ Complete:<br/>New user joined])

    %% EXISTING USER FLOW
    CheckExists -->|Yes - Existing User| StoreSession[Store invitation key<br/>in session]
    StoreSession --> ShowMessage[Show message:<br/>'Account exists, please login']
    ShowMessage --> RedirectLogin[Redirect to<br/>Login page]

    RedirectLogin --> LoginForm[User enters<br/>credentials]
    LoginForm --> Authenticate{Authentication<br/>successful?}

    Authenticate -->|No| LoginError[Show error message]
    LoginError --> LoginForm

    Authenticate -->|Yes| CheckSession{Pending invitation<br/>in session?}
    CheckSession -->|No| Dashboard2[Redirect to<br/>Dashboard]
    Dashboard2 --> End2([✅ Complete:<br/>Normal login])

    CheckSession -->|Yes| AcceptAfterLogin[Redirect to<br/>AcceptInvitationAfterLoginView]

    AcceptAfterLogin --> ValidateInvite{Validate<br/>invitation}

    ValidateInvite -->|Invalid/Expired| ErrorInvalid[Show error:<br/>'Invalid invitation']
    ErrorInvalid --> ClearSession1[Clear session]
    ClearSession1 --> Dashboard3[Redirect to<br/>Dashboard]
    Dashboard3 --> End3([❌ Failed:<br/>Invalid invitation])

    ValidateInvite -->|Valid| CheckEmail{Email matches<br/>logged-in user?}

    CheckEmail -->|No| ErrorMismatch[Show error:<br/>'Email mismatch']
    ErrorMismatch --> Dashboard4[Redirect to<br/>Dashboard]
    Dashboard4 --> End4([❌ Failed:<br/>Wrong account])

    CheckEmail -->|Yes| CheckMember{Already a<br/>member?}

    CheckMember -->|Yes| ShowInfo[Show info:<br/>'Already a member']
    ShowInfo --> MarkAccepted1[Mark invitation<br/>as accepted]
    MarkAccepted1 --> ClearSession2[Clear session]
    ClearSession2 --> OrgPage1[Redirect to<br/>myorganisation]
    OrgPage1 --> End5([✅ Complete:<br/>Already member])

    CheckMember -->|No| AddToOrg2[Add user to organisation<br/>Role: PROJECT_MANAGER]
    AddToOrg2 --> MarkAccepted2[Mark invitation<br/>as accepted]
    MarkAccepted2 --> ClearSession3[Clear session]
    ClearSession3 --> ShowSuccess[Show success:<br/>'Added to organisation']
    ShowSuccess --> OrgPage2[Redirect to<br/>myorganisation]
    OrgPage2 --> End6([✅ Complete:<br/>Existing user joined])

    %% Styling
    classDef newUserPath fill:#e1f5e1,stroke:#4caf50,stroke-width:2px
    classDef existingUserPath fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
    classDef errorPath fill:#ffebee,stroke:#f44336,stroke-width:2px
    classDef successPath fill:#f1f8e9,stroke:#8bc34a,stroke-width:2px

    class CallSuper,RedirectSignup,SignupForm,CreateUser,AddToOrg1,AutoLogin,Dashboard1,End1 newUserPath
    class StoreSession,ShowMessage,RedirectLogin,LoginForm,Authenticate,CheckSession,AcceptAfterLogin,ValidateInvite,CheckEmail,CheckMember,AddToOrg2,MarkAccepted2,ClearSession3,ShowSuccess,OrgPage2,End6 existingUserPath
    class ErrorInvalid,ErrorMismatch,LoginError,End3,End4 errorPath
    class End1,End2,End5,End6 successPath

Loading