路由不该什么都干：业务逻辑往哪放

# 反例：路由里堆满规则（节选）
@router.post("/orders")
async def create_order(body: OrderCreate, db: Session = Depends(get_db)) -> OrderRead:
    if body.quantity <= 0:
        raise HTTPException(400, "quantity")
    item = db.get(Item, body.item_id)
    if item is None:
        raise HTTPException(404, "item")
    if item.stock < body.quantity:
        raise HTTPException(409, "out of stock")
    total = item.price * body.quantity
    if body.coupon:
        total *= 0.9
    order = Order(item_id=item.id, quantity=body.quantity, total=total)
    item.stock -= body.quantity
    db.add(order)
    db.commit()
    send_email(...)  # 副作用
    return OrderRead.model_validate(order)

# shop/services/order_service.py
from sqlalchemy.orm import Session

from shop.models.item import Item
from shop.models.order import Order
from shop.schemas.order import OrderCreate


class OutOfStockError(Exception):
    pass


class ItemNotFoundError(Exception):
    pass


def create_order(db: Session, data: OrderCreate) -> Order:
    item = db.get(Item, data.item_id)
    if item is None:
        raise ItemNotFoundError(data.item_id)
    if item.stock < data.quantity:
        raise OutOfStockError()

    unit_price = item.price
    total = unit_price * data.quantity
    if data.coupon:
        total = round(total * 0.9, 2)

    order = Order(item_id=item.id, quantity=data.quantity, total=total)
    item.stock -= data.quantity
    db.add(order)
    db.commit()
    db.refresh(order)
    return order

# shop/api/v1/orders.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session

from shop.db.session import get_db
from shop.schemas.order import OrderCreate, OrderRead
from shop.services import order_service

router = APIRouter(prefix="/orders", tags=["orders"])


@router.post("", response_model=OrderRead, status_code=status.HTTP_201_CREATED)
def create_order_endpoint(
    body: OrderCreate,
    db: Session = Depends(get_db),
) -> OrderRead:
    try:
        order = order_service.create_order(db, body)
    except order_service.ItemNotFoundError as exc:
        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
    except order_service.OutOfStockError:
        raise HTTPException(status.HTTP_409_CONFLICT, detail="out of stock")
    return OrderRead.model_validate(order)

# tests/test_order_service.py
from sqlalchemy.orm import Session

from shop.models.item import Item
from shop.schemas.order import OrderCreate
from shop.services.order_service import OutOfStockError, create_order


def test_create_order_reduces_stock(db_session: Session) -> None:
    item = Item(name="pen", price=2.0, stock=5)
    db_session.add(item)
    db_session.commit()

    order = create_order(db_session, OrderCreate(item_id=item.id, quantity=2, coupon=None))
    db_session.refresh(item)

    assert order.total == 4.0
    assert item.stock == 3


def test_out_of_stock(db_session: Session) -> None:
    item = Item(name="pen", price=2.0, stock=1)
    db_session.add(item)
    db_session.commit()

    try:
        create_order(db_session, OrderCreate(item_id=item.id, quantity=3, coupon=None))
    except OutOfStockError:
        pass
    else:
        raise AssertionError("expected OutOfStockError")

def create_order(
    db: Session,
    data: OrderCreate,
    *,
    notifier: Callable[[Order], None] | None = None,
) -> Order:
    ...
    if notifier is not None:
        notifier(order)
    return order

# shop/api/errors.py 概念
from collections.abc import Callable
from typing import TypeVar

from fastapi import HTTPException

T = TypeVar("T")


def map_service_error(fn: Callable[..., T]) -> Callable[..., T]:
    def wrapper(*args, **kwargs) -> T:
        try:
            return fn(*args, **kwargs)
        except ItemNotFoundError as exc:
            raise HTTPException(404, detail=str(exc)) from exc
        except OutOfStockError:
            raise HTTPException(409, detail="out of stock") from exc
    return wrapper

# scripts/replay_order.py 概念
from shop.db.session import SessionLocal
from shop.schemas.order import OrderCreate
from shop.services.order_service import create_order


def main() -> None:
    with SessionLocal() as db:
        create_order(db, OrderCreate(item_id=1, quantity=1, coupon=None))


if __name__ == "__main__":
    main()