A コーディング — StrEnum × 遷移テーブル × frozen dataclass replace() × Counter × aware datetime（在庫予約管理 Bad→Good）

📋 コピー"""reservation_manager.py — 在庫予約管理（Bad → Good リファクタリング）

良いコード・悪いコードで学ぶ設計入門（改訂新版）
  - Ch6: 条件分岐の整理（遷移テーブル × StrEnum で if-elif 根絶）
  - Ch7: コレクション操作の整理（Counter × dict.get() × プライベート化）
  - Ch10: 不変と副作用（frozen dataclass × aware datetime × replace()）
"""
from __future__ import annotations

import datetime
from collections import Counter
from dataclasses import dataclass, replace
from enum import StrEnum
from typing import Final

# ── 名前付き定数 ────────────────────────────────────────────────────────────
DEFAULT_STOCK: Final[int] = 0   # 未登録 SKU の初期在庫


# ── StrEnum でステータスを型安全に管理（Ch6: 文字列リテラル比較を廃絶）──────
class ReservationStatus(StrEnum):
    RESERVED  = "reserved"    # 在庫引き当て済み・未確定
    FULFILLED = "fulfilled"   # 出荷確定済み
    CANCELLED = "cancelled"   # キャンセル済み（在庫返却済み）


# ── 遷移テーブルで条件分岐を1箇所に集約（Ch6: DRY 違反を解消）──────────────
VALID_TRANSITIONS: Final[dict[ReservationStatus, frozenset[ReservationStatus]]] = {
    ReservationStatus.RESERVED:  frozenset({
        ReservationStatus.FULFILLED,
        ReservationStatus.CANCELLED,
    }),
    ReservationStatus.FULFILLED: frozenset(),   # 終端状態
    ReservationStatus.CANCELLED: frozenset(),   # 終端状態
}


# ── 値オブジェクト（Ch10: frozen=True で不変性を保証）──────────────────────
@dataclass(frozen=True, slots=True)
class Reservation:
    """予約1件を表す不変の値オブジェクト。

    Attributes:
        order_id:   注文ID（一意キー）。
        sku_id:     在庫管理単位ID。
        qty:        引き当て数量。
        status:     現在の予約ステータス。
        created_at: 予約作成日時（aware datetime, UTC）。
    """
    order_id:   str
    sku_id:     str
    qty:        int
    status:     ReservationStatus
    created_at: datetime.datetime  # 必ず UTC aware datetime


# ── カスタム例外 ──────────────────────────────────────────────────────────
class OutOfStockError(Exception):
    """在庫不足で予約できない場合に送出する。"""

class ReservationNotFoundError(KeyError):
    """指定された order_id の予約が存在しない場合に送出する。"""

class InvalidTransitionError(ValueError):
    """許可されていないステータス遷移を試みた場合に送出する。"""


# ── マネージャ本体 ──────────────────────────────────────────────────────────
class ReservationManager:
    """在庫の予約・引き当て・キャンセルを管理するクラス。"""

    def __init__(self, initial_stock: dict[str, int] | None = None) -> None:
        # プライベート化でカプセル化（Ch10）
        self._stock: dict[str, int] = dict(initial_stock or {})
        self._reservations: dict[str, Reservation] = {}

    def _transition(
        self,
        order_id: str,
        new_status: ReservationStatus,
    ) -> Reservation:
        """予約のステータスを遷移させる共通ロジック（Ch6: 条件分岐の集約）。

        cancel() と fulfill() の重複 if-elif をここに集約する。
        """
        r = self._reservations.get(order_id)  # dict.get() で安全アクセス（Ch7）
        if r is None:
            raise ReservationNotFoundError(f"予約が見つかりません: {order_id!r}")

        # 遷移テーブルを参照して許可チェック（if-elif は1行にもならない）
        if new_status not in VALID_TRANSITIONS[r.status]:
            raise InvalidTransitionError(
                f"{r.status!r} → {new_status!r} は許可されていない遷移です"
            )

        # frozen dataclass は replace() でイミュータブルに更新する（Ch10）
        updated = replace(r, status=new_status)
        self._reservations[order_id] = updated
        return updated

    def add_stock(self, sku_id: str, qty: int) -> None:
        """在庫を追加登録する。"""
        self._stock[sku_id] = self._stock.get(sku_id, DEFAULT_STOCK) + qty

    def reserve(self, order_id: str, sku_id: str, qty: int) -> Reservation:
        """在庫を引き当てて予約を作成する。"""
        # ── 引数バリデーション（問題①を解消）──────────────────────────────
        if not order_id or not sku_id:
            raise ValueError("order_id と sku_id は空文字列にできません")
        if qty <= 0:
            raise ValueError(f"qty は正の整数である必要があります: {qty}")
        if order_id in self._reservations:
            raise ValueError(f"order_id は既に予約済みです: {order_id!r}")

        available = self._stock.get(sku_id, DEFAULT_STOCK)
        if available < qty:
            raise OutOfStockError(
                f"在庫不足: sku_id={sku_id!r}, 要求={qty}, 在庫={available}"
            )

        self._stock[sku_id] = available - qty
        reservation = Reservation(
            order_id=order_id,
            sku_id=sku_id,
            qty=qty,
            status=ReservationStatus.RESERVED,
            # aware datetime で naive datetime 問題②を解消
            created_at=datetime.datetime.now(tz=datetime.UTC),
        )
        self._reservations[order_id] = reservation
        return reservation

    def cancel(self, order_id: str) -> Reservation:
        """予約をキャンセルし在庫を戻す。"""
        # 共通遷移ロジックに委譲（問題③④⑥を解消）
        updated = self._transition(order_id, ReservationStatus.CANCELLED)
        # キャンセル時のみ在庫を戻す
        self._stock[updated.sku_id] = (
            self._stock.get(updated.sku_id, DEFAULT_STOCK) + updated.qty
        )
        return updated

    def fulfill(self, order_id: str) -> Reservation:
        """予約を出荷確定に遷移させる。"""
        # cancel() との重複が完全に解消される（問題⑥）
        return self._transition(order_id, ReservationStatus.FULFILLED)

    def get_summary(self) -> dict[str, int]:
        """SKU 別の予約中（RESERVED）数量合計を返す。"""
        # Counter で手動ループを1表現に圧縮（問題⑤を解消: Ch7）
        return dict(
            Counter(
                {r.sku_id: r.qty
                 for r in self._reservations.values()
                 if r.status == ReservationStatus.RESERVED}
            )
        )