A コーディング — 退化コメント・コメントと実装の不一致・死んだコード・TODO書式（カート合計計算 Bad→Good Ch12）

📋 コピー"""cart_pricing.py — カート合計金額（小計・送料・割引・総額）の計算

良いコード・悪いコードで学ぶ設計入門（改訂新版）
  Ch12: コメント — 退化コメントの排除、コメントと実装の同期、目的（Why）の文書化
"""
from __future__ import annotations

from dataclasses import dataclass
from decimal import Decimal, ROUND_HALF_UP

# 送料改定（2025-10）以降の基準値。この金額（円）以上の小計、または
# プレミアム会員（会員ランク特典 2025-Q4, PROMO-2025-42）の場合に送料無料となる。
FREE_SHIPPING_THRESHOLD_YEN = Decimal("5000")

# 国内標準送料（2025-10 改定後の金額、円）。
STANDARD_SHIPPING_FEE_YEN = Decimal("990")

# まとめ買い促進キャンペーンの適用条件（販促企画チーム承認: PROMO-2025-88）。
# 小計がこの金額（円）以上の注文に CAMPAIGN_DISCOUNT_RATE を適用する。
CAMPAIGN_DISCOUNT_THRESHOLD_YEN = Decimal("10000")
CAMPAIGN_DISCOUNT_RATE = Decimal("0.10")


@dataclass(frozen=True, slots=True)
class CartTotal:
    """カート合計金額の内訳を保持する値オブジェクト。

    Attributes:
        subtotal: 小計（単価 × 数量、円）。
        shipping_fee: 送料（円）。無料条件を満たす場合は0。
        discount: キャンペーン割引額（円）。
        total: 小計 + 送料 - 割引の総額（円）。
    """

    subtotal: Decimal
    shipping_fee: Decimal
    discount: Decimal
    total: Decimal


def calculate_cart_total(
    unit_price: Decimal, quantity: int, is_premium_member: bool
) -> CartTotal:
    """カート合計金額（小計・送料・割引・総額）を計算する。

    送料はプレミアム会員のLTV向上施策（会員ランク特典 2025-Q4, PROMO-2025-42）
    として、小計が FREE_SHIPPING_THRESHOLD_YEN 以上、またはプレミアム会員の
    場合に無料となる。キャンペーン割引（CAMPAIGN_DISCOUNT_RATE）は、まとめ買い
    促進を目的として小計 CAMPAIGN_DISCOUNT_THRESHOLD_YEN 以上の注文に適用される
    （販促企画チーム承認: PROMO-2025-88）。

    Args:
        unit_price: 商品単価（円）。
        quantity: 数量。
        is_premium_member: プレミアム会員かどうか。

    Returns:
        小計・送料・割引額・総額を保持する CartTotal。

    Raises:
        ValueError: unit_price または quantity が0以下の場合。
    """
    if unit_price <= 0 or quantity <= 0:
        raise ValueError("unit_price と quantity は正の値である必要があります")

    subtotal = unit_price * quantity

    shipping_fee = STANDARD_SHIPPING_FEE_YEN
    if subtotal >= FREE_SHIPPING_THRESHOLD_YEN or is_premium_member:
        shipping_fee = Decimal("0")

    discount = Decimal("0")
    if subtotal >= CAMPAIGN_DISCOUNT_THRESHOLD_YEN:
        discount = (subtotal * CAMPAIGN_DISCOUNT_RATE).quantize(
            Decimal("1"), rounding=ROUND_HALF_UP
        )

    total = subtotal + shipping_fee - discount

    # TODO(kainuma): 軽減税率(8%)対象商品の税区分判定を追加する。
    # 現在は全商品を標準税率10%として扱っており、食品等が混在するカートの
    # 税額按分は未対応。 (Issue: MOPS-1421, 対応予定: 2026-Q4)

    return CartTotal(
        subtotal=subtotal, shipping_fee=shipping_fee, discount=discount, total=total
    )