A コーディング — Protocol × match 文（CouponType）× heapq.nlargest × defaultdict × frozen dataclass × Decimal（キャンペーン売上集計 Bad→Good）

📋 コピー"""campaign_analyzer.py — クーポン適用 × カテゴリ別売上集計（Bad → Good リファクタリング）

良いコード・悪いコードで学ぶ設計入門（改訂新版）
  - Ch4: frozen=True dataclass × Decimal で不変値オブジェクト × 金額精度保証
  - Ch5: Protocol による依存関係の整理（テスタブル設計）
  - Ch6: match 文でクーポン種別の条件分岐を1箇所に集約（DRY × OCP）
  - Ch7: defaultdict + heapq.nlargest でコレクション操作を整理（効率化）
Python 3.12+ / match / Protocol / heapq / StrEnum / Decimal
"""
from __future__ import annotations

import heapq
from collections import defaultdict
from dataclasses import dataclass
from decimal import Decimal
from enum import StrEnum
from typing import Final, Protocol, TypeAlias

# ── 名前付き定数（マジックナンバー根絶）────────────────────────────────────
TOP_N: Final[int] = 5                             # Top-N SKU ランキングの件数
PERCENT_DIVISOR: Final[Decimal] = Decimal("100")  # % → 小数変換用除数
ZERO: Final[Decimal] = Decimal("0")               # Decimal のゼロ値（型一致のため）

# PEP 695 TypeAlias（Python 3.12+）。str の意味を明示する型エイリアス
CampaignId: TypeAlias = str


# ── 問題①②: マジックストリングを StrEnum で型安全化（Ch6）────────────────
class CouponType(StrEnum):
    """クーポン種別を型安全に管理する StrEnum。

    StrEnum は str のサブクラスなので json.dumps() にそのまま渡せる。
    match 文の case 節でリテラル比較が静的に検証される。
    """
    FIXED    = "fixed"     # 定額割引（円）
    PERCENT  = "percent"   # 割合割引（%）
    FREESHIP = "freeship"  # 送料無料


# ── 問題③⑥: dict でなく frozen=True dataclass で値オブジェクト化（Ch4）──
@dataclass(frozen=True, slots=True)
class Coupon:
    """クーポン1件を表す不変値オブジェクト。

    Attributes:
        coupon_id:   クーポンID。
        coupon_type: クーポン種別（CouponType）。
        value:       割引値（FIXED=円、PERCENT=%, FREESHIP は無視）。
    """
    coupon_id:   str
    coupon_type: CouponType
    value:       Decimal          # float ではなく Decimal（問題③の解消）


@dataclass(frozen=True, slots=True)
class Order:
    """注文1件を表す不変値オブジェクト。

    Attributes:
        order_id:     注文ID。
        sku_id:       商品SKU ID。
        category:     商品カテゴリ（例: "apparel", "electronics"）。
        subtotal:     小計（税抜き）。Decimal で精度を保証する。
        shipping_fee: 送料。Decimal で精度を保証する。
        coupon:       適用クーポン（なければ None）。
    """
    order_id:     str
    sku_id:       str
    category:     str
    subtotal:     Decimal         # float → Decimal（問題③の解消）
    shipping_fee: Decimal         # float → Decimal（問題③の解消）
    coupon:       Coupon | None


@dataclass(frozen=True, slots=True)
class CategorySummary:
    """カテゴリ別売上集計を表す不変値オブジェクト（問題⑥の解消）。

    Attributes:
        category:       商品カテゴリ名。
        order_count:    注文件数。
        gross_revenue:  クーポン適用前の総売上（小計合計）。
        total_discount: クーポン割引総額。
        net_revenue:    クーポン適用後の純売上。
    """
    category:       str
    order_count:    int
    gross_revenue:  Decimal
    total_discount: Decimal
    net_revenue:    Decimal


# ── 問題①: データソースを Protocol で抽象化（Ch5 依存関係整理）────────────
class OrderRepository(Protocol):
    """注文データを取得するデータソースのインターフェース。

    実装例: BigQueryOrderRepo / FileOrderRepo / FakeOrderRepo（テスト用）。
    Protocol にすることで CampaignAnalyzer はデータソースに依存しない。
    """
    def fetch_orders(self, campaign_id: CampaignId) -> list[Order]:
        """指定キャンペーンIDに紐づく注文一覧を返す。"""
        ...


# ── メインクラス ──────────────────────────────────────────────────────────
class CampaignAnalyzer:
    """キャンペーン効果を集計・分析するクラス。

    OrderRepository を DI で受け取るため、テスト時にモックを差し込める。

    Attributes:
        _repo: 注文データ取得リポジトリ（Protocol に準拠した任意の実装）。
    """

    def __init__(self, repo: OrderRepository) -> None:
        # アンダースコアでカプセル化（外部から直接アクセスさせない）
        self._repo = repo

    def _apply_coupon(self, order: Order) -> Decimal:
        """注文にクーポンを適用して割引額を返す（問題②④の解消）。

        match 文（Python 3.10+）でクーポン種別を分岐する。
        StrEnum と組み合わせることで mypy が網羅性を静的検証できる。

        Args:
            order: 割引額を計算する対象注文。

        Returns:
            割引額（Decimal）。クーポンなしは ZERO。

        Raises:
            ValueError: 未知の CouponType が渡された場合（問題④の解消）。
        """
        if order.coupon is None:
            return ZERO  # クーポンなしは割引なし

        coupon = order.coupon
        match coupon.coupon_type:
            case CouponType.FIXED:
                # 定額割引: 割引額は小計を超えない（最大でも小計まで）
                return min(coupon.value, order.subtotal)

            case CouponType.PERCENT:
                # 割合割引: subtotal × (value / 100)、小数第2位まで丸め
                # float ではなく Decimal で計算（問題③の解消）
                discount = order.subtotal * coupon.value / PERCENT_DIVISOR
                return discount.quantize(Decimal("0.01"))

            case CouponType.FREESHIP:
                # 送料無料: shipping_fee 相当額を割引（Decimal で一致）
                return order.shipping_fee

            case _:
                # StrEnum を使っていれば通常到達しないが防衛的に送出（問題④の解消）
                raise ValueError(f"未知のクーポン種別: {coupon.coupon_type!r}")

    def summarize(self, campaign_id: CampaignId) -> list[CategorySummary]:
        """カテゴリ別の売上・割引サマリーを生成する（問題⑤⑥の解消）。

        Args:
            campaign_id: 集計対象のキャンペーンID。

        Returns:
            カテゴリ別 CategorySummary のリスト（net_revenue 降順）。
        """
        orders = self._repo.fetch_orders(campaign_id)

        # 問題⑤: 手動の if-else キー存在チェックを defaultdict で廃絶（Ch7）
        counts:    defaultdict[str, int]     = defaultdict(int)
        gross:     defaultdict[str, Decimal] = defaultdict(lambda: ZERO)
        discounts: defaultdict[str, Decimal] = defaultdict(lambda: ZERO)

        for order in orders:
            discount = self._apply_coupon(order)  # 割引計算は1箇所に集約
            counts[order.category]    += 1
            gross[order.category]     += order.subtotal
            discounts[order.category] += discount

        # 問題⑥: 生 dict でなく CategorySummary（frozen=True）で返す（Ch4）
        summaries = [
            CategorySummary(
                category=cat,
                order_count=counts[cat],
                gross_revenue=gross[cat],
                total_discount=discounts[cat],
                net_revenue=gross[cat] - discounts[cat],
            )
            for cat in counts
        ]
        return sorted(summaries, key=lambda s: s.net_revenue, reverse=True)

    def top_skus(self, campaign_id: CampaignId) -> list[tuple[str, Decimal]]:
        """純売上 Top-N の SKU リストを返す（問題⑦の解消）。

        heapq.nlargest は O(N log K)（K=TOP_N）。
        sorted()[:N] の O(N log N) より SKU 数が大きいほど効率的。

        Args:
            campaign_id: 集計対象のキャンペーンID。

        Returns:
            (sku_id, net_revenue) タプルリスト（net_revenue 降順、最大 TOP_N 件）。
        """
        orders = self._repo.fetch_orders(campaign_id)

        sku_net: defaultdict[str, Decimal] = defaultdict(lambda: ZERO)
        for order in orders:
            discount = self._apply_coupon(order)
            sku_net[order.sku_id] += order.subtotal - discount

        # 問題⑦: sorted()[:5] の代わりに heapq.nlargest で Top-N を効率取得（Ch7）
        return heapq.nlargest(TOP_N, sku_net.items(), key=lambda kv: kv[1])