Files
Shubhankar45 4e5e95775d --
2026-10-27 12:03:31 +00:00

86 lines
3.1 KiB
Python

"""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, 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_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
),
},
)
# 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),
},
)