A コーディング — マジックナンバー・null問題・例外の握り潰し・YAGNI（返金処理 RefundHandler Bad→Good Ch10）

📋 コピー"""refund_processing.py — 返品承認後の返金処理

良いコード・悪いコードで学ぶ設計入門（改訂新版）
  Ch10: 設計の悪魔 — マジックナンバー、null問題、例外の握り潰し、YAGNI
"""
from __future__ import annotations

from dataclasses import dataclass
from enum import StrEnum


class OrderStatus(StrEnum):
    """注文のライフサイクル状態。"""

    PENDING = "pending"
    DELIVERED = "delivered"
    REFUNDED = "refunded"


class RefundReasonCode(StrEnum):
    """返金理由コード。"""

    QUALITY_DEFECT = "quality_defect"
    SHIPPING_DAMAGE = "shipping_damage"
    CUSTOMER_CHANGE_OF_MIND = "customer_change_of_mind"


# レガシーDBが返す整数ステータスコードを型安全な OrderStatus に変換する対応表。
# 生の整数はこの境界（get_order の直後）でのみ扱い、その先には漏らさない。
LEGACY_STATUS_CODE_TO_ORDER_STATUS: dict[int, OrderStatus] = {
    0: OrderStatus.PENDING,
    3: OrderStatus.DELIVERED,
    4: OrderStatus.REFUNDED,
}

# 返金額が注文金額に対してこの比率を超える場合、「上限超の返金」とみなす。
MAX_PARTIAL_REFUND_RATIO = 0.5

# 上限超の返金でも許可される理由コード。
ELIGIBLE_REASONS_FOR_LARGE_REFUND = frozenset(
    {RefundReasonCode.QUALITY_DEFECT, RefundReasonCode.SHIPPING_DAMAGE}
)


class OrderNotFoundError(Exception):
    """指定された注文IDが存在しない場合に送出する。"""


class RefundNotEligibleError(Exception):
    """返金条件を満たさない場合に送出する（未配送、理由コード不適合など）。"""


class PaymentGatewayError(Exception):
    """決済ゲートウェイ呼び出しが失敗した場合に送出する。

    原因の例外は `raise ... from exc` により `__cause__` に保持される。
    """


@dataclass(frozen=True, slots=True)
class RefundResult:
    """返金処理が成功したことを表す値オブジェクト。

    Attributes:
        order_id: 対象注文ID。
        refund_id: 決済ゲートウェイが発行した返金ID。
        amount: 返金額（円）。
        status: 更新後の注文ステータス。
    """

    order_id: str
    refund_id: str
    amount: int
    status: OrderStatus


class RefundProcessor:
    """注文の返金処理を担当する。

    Note:
        返金方式（全額/一部/店舗クレジット等）は現時点で1種類のみ運用されている。
        複数方式への対応が具体的に必要になった時点で第8章のストラテジパターンを
        導入すればよく、必要性が確認できていない現状では投機的な抽象化を避ける
        （YAGNI, 第10章）。旧実装にあった register_strategy/strategies は
        一度も呼ばれていなかったため削除した。
    """

    def __init__(self, gateway, db) -> None:
        self._gateway = gateway
        self._db = db

    def process(
        self, order_id: str, amount: int, reason_code: RefundReasonCode
    ) -> RefundResult:
        """返金を実行する。

        Args:
            order_id: 対象注文ID。
            amount: 返金希望額（円）。
            reason_code: 返金理由コード。

        Returns:
            成功時の RefundResult。

        Raises:
            OrderNotFoundError: 注文が存在しない場合。
            RefundNotEligibleError: 未配送、または上限比率超で理由コードが
                不適合な場合。
            PaymentGatewayError: 決済ゲートウェイ呼び出しが失敗した場合。
        """
        raw_order = self._db.get_order(order_id)
        if raw_order is None:
            raise OrderNotFoundError(f"order_id={order_id} が見つかりません")

        status = LEGACY_STATUS_CODE_TO_ORDER_STATUS[raw_order["status"]]
        if status is not OrderStatus.DELIVERED:
            raise RefundNotEligibleError(
                f"order_id={order_id} はステータス={status} のため返金対象外です"
            )

        if amount > raw_order["total"] * MAX_PARTIAL_REFUND_RATIO:
            if reason_code not in ELIGIBLE_REASONS_FOR_LARGE_REFUND:
                raise RefundNotEligibleError(
                    f"理由コード={reason_code} は半額超の返金には適用できません"
                )

        try:
            refund_id = self._gateway.refund(order_id, amount)
        except Exception as exc:
            # 原因の例外を cause として保持したまま専用例外に変換する。
            # ログ・監視基盤(DataDog等)が根本原因まで追跡できるようにする。
            raise PaymentGatewayError(
                f"order_id={order_id} の決済ゲートウェイ呼び出しに失敗しました"
            ) from exc

        self._db.update_status(order_id, OrderStatus.REFUNDED)
        return RefundResult(
            order_id=order_id,
            refund_id=refund_id,
            amount=amount,
            status=OrderStatus.REFUNDED,
        )


def handle_return_request(
    processor: RefundProcessor,
    order_id: str,
    amount: int,
    reason_code: RefundReasonCode,
) -> None:
    """返品申請を受けて返金を実行し、結果に応じて後続処理を行う。"""
    try:
        result = processor.process(order_id, amount, reason_code)
    except OrderNotFoundError:
        notify_ops_team(f"{order_id}: 注文が見つかりません")
    except RefundNotEligibleError as exc:
        notify_ops_team(f"{order_id}: 返金対象外 ({exc})")
    except PaymentGatewayError as exc:
        # exc.__cause__ に元の例外（ネットワークエラー等）が保持されている
        notify_ops_team(f"{order_id}: 決済ゲートウェイ障害 ({exc})")
    else:
        mark_return_completed(result.order_id, result.refund_id)