コーディング設計 — 不変の活用 × 副作用排除

📋 コピーfrom dataclasses import dataclass
from decimal import ROUND_HALF_UP, Decimal


TAX_RATE = Decimal("0.10")


@dataclass(frozen=True)
class CartItem:
    """カートの商品1行を表す不変オブジェクト。

    frozen=True により属性への再代入を禁止し、外部からの破壊的変更を防ぐ。

    Args:
        name: 商品名。
        price: 単価（円）。1以上の整数。
        qty: 数量（個）。1以上の整数。
    """

    name: str
    price: int
    qty: int

    def __post_init__(self) -> None:
        if self.price < 1:
            raise ValueError(f"単価は1円以上が必要です: {self.price}")
        if self.qty < 1:
            raise ValueError(f"数量は1個以上が必要です: {self.qty}")

    @property
    def subtotal(self) -> int:
        """単価 × 数量の小計を返す（元の price を変更しない）。"""
        return self.price * self.qty


def calculate_total(items: list[CartItem], coupon_discount: int = 0) -> int:
    """カートの税込み合計金額を計算する。

    各変数は一度だけ代入し、副作用を持たない純粋な計算を行う。

    Args:
        items: カート内の商品リスト。
        coupon_discount: クーポン割引額（円）。デフォルト 0。

    Returns:
        税込み合計金額（円）。割引・税計算後がマイナスの場合は 0 を返す。
    """
    # 小計の合算（items は一切変更しない）
    subtotal_sum = sum(item.subtotal for item in items)

    # クーポン割引後（再代入なし: 新しい変数に意味のある名前で代入）
    discounted_amount = subtotal_sum - coupon_discount

    # 税額（Decimal で端数処理: 四捨五入）
    tax_amount = int(
        (Decimal(discounted_amount) * TAX_RATE).quantize(Decimal("1"), rounding=ROUND_HALF_UP)
    )

    # 税込み合計
    total_with_tax = discounted_amount + tax_amount

    # ゼロ下限（クーポン過大適用への防御）
    return max(total_with_tax, 0)