"""The approval workflow for the revised business requirement. DRAFT --submit(MR)--> PENDING_ABM RETURNED --submit(MR)--> PENDING_ABM PENDING_ABM --approve(ABM)--> APPROVED (terminal, immutable) PENDING_ABM --return(ABM)--> RETURNED The Area Business Manager is the final approver; there is no Assistant General Manager stage. """ from dataclasses import dataclass from app.common.enums import EDITABLE_STATUSES, FIELD_ROLES, DCRStatus, Role, WorkflowAction from app.common.exceptions import ForbiddenError, InvalidStateTransitionError @dataclass(frozen=True) class Transition: from_status: DCRStatus action: WorkflowAction to_status: DCRStatus allowed_role: Role requires_reason: bool = False TRANSITIONS: tuple[Transition, ...] = ( Transition(DCRStatus.DRAFT, WorkflowAction.SUBMIT, DCRStatus.PENDING_ABM, Role.MR), Transition(DCRStatus.RETURNED, WorkflowAction.SUBMIT, DCRStatus.PENDING_ABM, Role.MR), Transition(DCRStatus.PENDING_ABM, WorkflowAction.APPROVE, DCRStatus.APPROVED, Role.ABM), Transition( DCRStatus.PENDING_ABM, WorkflowAction.RETURN, DCRStatus.RETURNED, Role.ABM, requires_reason=True, ), ) _INDEX: dict[tuple[DCRStatus, WorkflowAction], Transition] = { (t.from_status, t.action): t for t in TRANSITIONS } def find_transition(status: DCRStatus, action: WorkflowAction) -> Transition | None: return _INDEX.get((status, action)) def assert_transition(status: DCRStatus, action: WorkflowAction, role: Role) -> Transition: """Validate a requested move and return the transition to apply. Raises InvalidStateTransitionError (409) if the move does not exist from this status, and ForbiddenError (403) if it exists but this role may not make it. ADMIN never matches any transition — SEC-2: the System Administrator can never approve a report. """ transition = find_transition(status, action) if transition is None: raise InvalidStateTransitionError( f"Cannot {action.value.lower()} a report in status {status.value}", { "current_status": status.value, "attempted_action": action.value, "allowed_actions": sorted( t.action.value for t in TRANSITIONS if t.from_status == status ), }, ) # An SFE files and submits reports exactly as an MR does. if transition.allowed_role != (Role.MR if role in FIELD_ROLES else role): raise ForbiddenError( f"Role {role.value} may not {action.value.lower()} this report", {"required_role": transition.allowed_role.value, "your_role": role.value}, ) return transition def assert_editable(status: DCRStatus) -> None: """V9/V10 — report data may only change in DRAFT or RETURNED.""" if status not in EDITABLE_STATUSES: from app.common.exceptions import ReportLockedError raise ReportLockedError( f"A report in status {status.value} cannot be modified", { "current_status": status.value, "editable_statuses": sorted(s.value for s in EDITABLE_STATUSES), }, )