A コーディング — コマンド・クエリ分離（CQS）× フラグ引数廃止 × null返却禁止 × 専用例外階層（available_qty 付き）× Protocol StockRepository 依存注入（フラッシュセール在庫予約 Bad→Good Ch4/Ch10/Ch13）

📋 コピー"""inventory_reservation.py — フラッシュセール在庫予約（在庫引当）

良いコード・悪いコードで学ぶ設計入門（改訂新版）
  Ch13: メソッド設計 — CQS、フラグ引数の廃止、null返却禁止
  Ch10: 例外の握り潰し回避（専用例外で失敗理由を型として表現）
  Ch4:  frozen dataclass(slots=True) による値オブジェクト
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Final, Protocol, TypedDict

MIN_RESERVATION_QTY: Final[int] = 1

class StockRow(TypedDict):
    sku: str
    quantity: int

# ── Protocol（依存性の注入）────────────────────────────────
class StockRepository(Protocol):
    def get_stock(self, sku: str) -> StockRow | None: ...
    def save_stock(self, sku: str, row: StockRow) -> None: ...

# ── 例外階層（null返却禁止の代替表現・Ch13）─────────────────
class StockError(Exception):
    """在庫関連エラーの基底クラス。"""

class SkuNotFoundError(StockError):
    def __init__(self, sku: str) -> None:
        super().__init__(f"SKU not found: {sku!r}")
        self.sku = sku

class InsufficientStockError(StockError):
    """Attributes:
        available_qty: 実際に確保可能な数量（呼び出し側が UI に表示可能）
    """
    def __init__(self, sku: str, requested_qty: int, available_qty: int) -> None:
        super().__init__(
            f"Insufficient stock for {sku!r}: "
            f"requested={requested_qty}, available={available_qty}"
        )
        self.sku = sku
        self.requested_qty = requested_qty
        self.available_qty = available_qty

# ── 値オブジェクト（Ch4: 不変の活用）───────────────────────
@dataclass(frozen=True, slots=True)
class ReservationResult:
    sku: str
    reserved_qty: int
    remaining_qty: int

# ── クエリ側 — 副作用なし（Ch13: CQS）───────────────────────
class StockAvailabilityChecker:
    def __init__(self, repository: StockRepository) -> None:
        self._repository = repository

    def is_available(self, sku: str, qty: int) -> bool:
        """在庫確認のみ行う（読み取り専用、状態変更なし）。"""
        row = self._repository.get_stock(sku)
        if row is None:
            return False  # クエリなので失敗も bool で表現、例外にしない
        return row["quantity"] >= qty

    def get_available_qty(self, sku: str) -> int:
        row = self._repository.get_stock(sku)
        return row["quantity"] if row is not None else 0

# ── コマンド側 — 副作用あり、null を返さない（Ch13）─────────
class StockReservationService:
    def __init__(self, repository: StockRepository) -> None:
        self._repository = repository

    def reserve(self, sku: str, qty: int) -> ReservationResult:
        """成功時は必ず ReservationResult を返し、失敗時は必ず StockError を送出する。

        Raises:
            ValueError: qty が MIN_RESERVATION_QTY 未満
            SkuNotFoundError: SKU が存在しない
            InsufficientStockError: 在庫不足
        """
        if qty < MIN_RESERVATION_QTY:
            raise ValueError(f"qty must be >= {MIN_RESERVATION_QTY}, got {qty}")

        row = self._repository.get_stock(sku)
        if row is None:
            raise SkuNotFoundError(sku)
        if row["quantity"] < qty:
            raise InsufficientStockError(sku, requested_qty=qty, available_qty=row["quantity"])

        row["quantity"] -= qty
        self._repository.save_stock(sku, row)
        return ReservationResult(sku=sku, reserved_qty=qty, remaining_qty=row["quantity"])

# ── 通知は別責務（単一責任・Ch13）───────────────────────────
class ReservationNotifier:
    def notify(self, result: ReservationResult) -> None:
        print(f"[Slack通知] {result.sku} を {result.reserved_qty} 個予約しました"
              f"（残り {result.remaining_qty} 個）")

# ── 呼び出し側 — 意図が明確 ─────────────────────────────────
def handle_flash_sale_order(checker, reservation_service, notifier, sku, qty) -> None:
    if not checker.is_available(sku, qty):
        print(f"予約不可: {sku} の在庫が不足しています（{checker.get_available_qty(sku)} 個のみ）")
        return
    try:
        result = reservation_service.reserve(sku, qty)
    except InsufficientStockError as e:
        print(f"予約失敗（在庫競合）: {e}")  # is_available と reserve の間の競合状態
        return
    notifier.notify(result)  # 通知は呼び出し側の任意判断