"""The approval workflow for the revised business requirement. DRAFT --submit(MR)--> PENDING_AM RETURNED --submit(MR)--> PENDING_AM PENDING_AM --approve(AM)--> APPROVED (terminal, immutable) PENDING_AM --return(AM)--> RETURNED The Area Manager is the final approver; there is no General Manager stage. """ from dataclasses import dataclass from app.common.enums import EDITABLE_STATUSES, 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_AM, Role.MR), Transition(DCRStatus.RETURNED, WorkflowAction.SUBMIT, DCRStatus.PENDING_AM, Role.MR), Transition(DCRStatus.PENDING_AM, WorkflowAction.APPROVE, DCRStatus.APPROVED, Role.AM), Transition( DCRStatus.PENDING_AM, WorkflowAction.RETURN, DCRStatus.RETURNED, Role.AM, 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 ), }, ) if transition.allowed_role != 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), }, )