feat: add orders status transitions (finite state machine)

Author: adiffpirate

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help run stop test test-unit test-integration clean
+.PHONY: help run stop test test-unit test-integration clean migrations
 
 help:
 	@echo "Available commands:"
@@ -8,6 +8,7 @@ help:
 	@echo "  test-unit        - Run unit tests"
 	@echo "  test-integration - Run integration tests with fresh database"
 	@echo "  clean            - Clean up Docker containers and volumes"
+	@echo "  migrations msg   - Generate alembic migration via Docker (e.g. make migrations msg='add cancelled status')"
 
 run:
 	docker compose up --build -d
@@ -34,6 +35,10 @@ test-integration:
 	docker compose run --rm app python -m pytest tests/integration/ -v
 	$(MAKE) clean
 
+migrations:
+	@if [ -z "$(msg)" ]; then echo "Usage: make migrations msg='your message'"; exit 1; fi
+	docker compose run --rm app alembic revision --autogenerate -m "$(msg)"
+
 clean:
 	$(MAKE) stop
 	@echo "Cleaning all data..."

alembic/versions/814107d68bb6_add_cancelled_and_fulfilled_to_.py

@@ -0,0 +1,47 @@
+"""add CANCELLED and FULFILLED to OrderStatus enum
+
+Revision ID: 814107d68bb6
+Revises: 084d9bd91fca
+Create Date: 2026-04-27 05:13:11.551687
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '814107d68bb6'
+down_revision: Union[str, Sequence[str], None] = '084d9bd91fca'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # Rename old type, create new type with all values, reassign column
+    op.execute("ALTER TYPE orderstatus RENAME TO orderstatus_old")
+    op.execute(
+        "CREATE TYPE orderstatus AS ENUM "
+        "('RECEIVED', 'PROCESSING', 'FULFILLED', 'SHIPPED', 'DELIVERED', 'CANCELLED')"
+    )
+    op.execute(
+        "ALTER TABLE orders ALTER COLUMN status TYPE orderstatus "
+        "USING status::text::orderstatus"
+    )
+    op.execute("DROP TYPE orderstatus_old")
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.execute("ALTER TYPE orderstatus RENAME TO orderstatus_old")
+    op.execute(
+        "CREATE TYPE orderstatus AS ENUM "
+        "('RECEIVED', 'PROCESSING', 'SHIPPED', 'DELIVERED')"
+    )
+    op.execute(
+        "ALTER TABLE orders ALTER COLUMN status TYPE orderstatus "
+        "USING status::text::orderstatus"
+    )
+    op.execute("DROP TYPE orderstatus_old")

app/modules/orders/models.py

@@ -6,8 +6,10 @@
 class OrderStatus(str, enum.Enum):
     RECEIVED = "received"
     PROCESSING = "processing"
+    FULFILLED = "fulfilled"
     SHIPPED = "shipped"
     DELIVERED = "delivered"
+    CANCELLED = "cancelled"
 
 
 class Order(Base):

app/modules/orders/routes.py

@@ -3,6 +3,7 @@
 
 from app.db.session import get_db
 from . import service, schemas, repository
+from .service import InvalidOrderTransition
 from app.core.auth import get_current_user
 
 router = APIRouter()
@@ -53,6 +54,8 @@ def update_order(
         return service.update_order(repo, order_id, **updates)
     except ValueError:
         raise HTTPException(status_code=404, detail="Order not found")
+    except InvalidOrderTransition as e:
+        raise HTTPException(status_code=400, detail=str(e))
 
 
 @router.delete("/{order_id}", status_code=204)

app/modules/orders/service.py

@@ -1,4 +1,43 @@
-from . import repository
+from . import repository, models
+
+
+class InvalidOrderTransition(Exception):
+    """Raised when a requested status transition is not allowed."""
+    pass
+
+
+class OrderStateMachine:
+    """Finite state machine for order status transitions."""
+
+    TRANSITIONS = {
+        models.OrderStatus.RECEIVED: [
+            models.OrderStatus.PROCESSING,
+            models.OrderStatus.CANCELLED,
+        ],
+        models.OrderStatus.PROCESSING: [
+            models.OrderStatus.FULFILLED,
+            models.OrderStatus.CANCELLED,
+        ],
+        models.OrderStatus.FULFILLED: [
+            models.OrderStatus.SHIPPED,
+            models.OrderStatus.CANCELLED,
+        ],
+        models.OrderStatus.SHIPPED: [
+            models.OrderStatus.DELIVERED
+        ],
+        models.OrderStatus.DELIVERED: [],
+        models.OrderStatus.CANCELLED: [],
+    }
+
+    @classmethod
+    def validate_transition(cls, current: models.OrderStatus, target: models.OrderStatus) -> None:
+        allowed = cls.TRANSITIONS.get(current)
+        if allowed is None:
+            raise InvalidOrderTransition(f"Unknown status: {current}")
+        if target not in allowed:
+            raise InvalidOrderTransition(
+                f"Cannot transition from {current} to {target}"
+            )
 
 
 def create_order(repo: repository.OrderRepository, item: str):
@@ -21,6 +60,10 @@ def update_order(repo: repository.OrderRepository, order_id: int, **kwargs):
     order = repo.get_order(order_id)
     if not order:
         raise ValueError("Order not found")
+
+    if "status" in kwargs and kwargs["status"] is not None:
+        OrderStateMachine.validate_transition(order.status, kwargs["status"])
+
     for key, value in kwargs.items():
         if value is not None:
             setattr(order, key, value)

tests/integration/test_orders.py

@@ -135,3 +135,53 @@ def test_delete_order_not_found(client):
 def test_orders_without_auth_returns_401(client):
     response = client.get("/orders/")
     assert response.status_code == 401
+
+
+def test_update_order_cancel_from_received(client):
+    token = _login(client)
+    created = client.post("/orders/", json={"item": "cancel_me"}, headers={
+        "Authorization": f"Bearer {token}"
+    }).json()
+    order_id = created["id"]
+    assert created["status"] == "received"
+
+    response = client.put(f"/orders/{order_id}", json={"status": "cancelled"}, headers={
+        "Authorization": f"Bearer {token}"
+    })
+    assert response.status_code == 200
+    data = response.json()
+    assert data["status"] == "cancelled"
+
+    get_response = client.get(f"/orders/{order_id}", headers={
+        "Authorization": f"Bearer {token}"
+    })
+    assert get_response.status_code == 200
+    assert get_response.json()["status"] == "cancelled"
+
+
+def test_update_order_invalid_transition(client):
+    token = _login(client)
+    created = client.post("/orders/", json={"item": "terminal"}, headers={
+        "Authorization": f"Bearer {token}"
+    }).json()
+    order_id = created["id"]
+
+    # Advance through valid transitions to DELIVERED
+    for next_status in ["processing", "fulfilled", "shipped", "delivered"]:
+        response = client.put(f"/orders/{order_id}", json={"status": next_status}, headers={
+            "Authorization": f"Bearer {token}"
+        })
+        assert response.status_code == 200
+
+    # DELIVERED -> PROCESSING should fail
+    response = client.put(f"/orders/{order_id}", json={"status": "processing"}, headers={
+        "Authorization": f"Bearer {token}"
+    })
+    assert response.status_code == 400
+    assert "Cannot transition" in response.json()["detail"]
+
+    # Order should still be DELIVERED
+    get_response = client.get(f"/orders/{order_id}", headers={
+        "Authorization": f"Bearer {token}"
+    })
+    assert get_response.json()["status"] == "delivered"

tests/unit/test_orders.py

@@ -1,6 +1,8 @@
 from unittest.mock import MagicMock
+import pytest
 
 from app.modules.orders import service, repository, models
+from app.modules.orders.service import OrderStateMachine, InvalidOrderTransition
 
 
 def _make_mock_repo(order=None):
@@ -91,3 +93,74 @@ def test_delete_order_not_found():
         assert False, "Should have raised ValueError"
     except ValueError as e:
         assert str(e) == "Order not found"
+
+
+# ── FSM Unit Tests ──────────────────────────────────────────────────────────
+
+VALID_TRANSITIONS = [
+    (models.OrderStatus.RECEIVED, models.OrderStatus.PROCESSING),
+    (models.OrderStatus.RECEIVED, models.OrderStatus.CANCELLED),
+    (models.OrderStatus.PROCESSING, models.OrderStatus.FULFILLED),
+    (models.OrderStatus.PROCESSING, models.OrderStatus.CANCELLED),
+    (models.OrderStatus.FULFILLED, models.OrderStatus.SHIPPED),
+    (models.OrderStatus.FULFILLED, models.OrderStatus.CANCELLED),
+    (models.OrderStatus.SHIPPED, models.OrderStatus.DELIVERED),
+]
+
+INVALID_TRANSITIONS = [
+    (models.OrderStatus.RECEIVED, models.OrderStatus.FULFILLED),
+    (models.OrderStatus.RECEIVED, models.OrderStatus.SHIPPED),
+    (models.OrderStatus.RECEIVED, models.OrderStatus.DELIVERED),
+    (models.OrderStatus.PROCESSING, models.OrderStatus.SHIPPED),
+    (models.OrderStatus.PROCESSING, models.OrderStatus.DELIVERED),
+    (models.OrderStatus.FULFILLED, models.OrderStatus.DELIVERED),
+    (models.OrderStatus.FULFILLED, models.OrderStatus.RECEIVED),
+    (models.OrderStatus.SHIPPED, models.OrderStatus.PROCESSING),
+    (models.OrderStatus.SHIPPED, models.OrderStatus.CANCELLED),
+    (models.OrderStatus.DELIVERED, models.OrderStatus.PROCESSING),
+    (models.OrderStatus.DELIVERED, models.OrderStatus.DELIVERED),
+    (models.OrderStatus.CANCELLED, models.OrderStatus.PROCESSING),
+    (models.OrderStatus.CANCELLED, models.OrderStatus.CANCELLED),
+]
+
+
+@pytest.mark.parametrize("current, target", VALID_TRANSITIONS)
+def test_fsm_valid_transitions(current, target):
+    OrderStateMachine.validate_transition(current, target)
+
+
+@pytest.mark.parametrize("current, target", INVALID_TRANSITIONS)
+def test_fsm_invalid_transitions(current, target):
+    with pytest.raises(InvalidOrderTransition):
+        OrderStateMachine.validate_transition(current, target)
+
+
+def test_fsm_unknown_current_status():
+    with pytest.raises(InvalidOrderTransition):
+        OrderStateMachine.validate_transition("unknown", models.OrderStatus.PROCESSING)
+
+
+def test_fsm_unknown_target_status():
+    with pytest.raises(InvalidOrderTransition):
+        OrderStateMachine.validate_transition(models.OrderStatus.RECEIVED, "unknown")
+
+
+# ── Service Layer FSM Integration Tests ─────────────────────────────────────
+
+
+def test_update_order_invalid_status_transition():
+    order = _make_order()
+    repo = _make_mock_repo(order=order)
+    with pytest.raises(InvalidOrderTransition):
+        service.update_order(repo, 1, status="delivered")
+    repo._db.commit.assert_not_called()
+    repo._db.refresh.assert_not_called()
+
+
+def test_update_order_valid_status_transition():
+    order = _make_order()
+    repo = _make_mock_repo(order=order)
+    result = service.update_order(repo, 1, status="processing")
+    assert result.status == "processing"
+    repo._db.commit.assert_called_once()
+    repo._db.refresh.assert_called_once_with(order)