A コーディング — 完全コンストラクタ・値オブジェクト・不変（キャンペーン予算 CampaignBudget Bad→Good Ch3）

概要

問題

EC企業の販促（MOps）システムには、広告配信キャンペーンの予算消化を追跡する CampaignBudget クラスが本番稼働している。

「良いコード・悪いコードで学ぶ設計入門」第3章（カプセル化：完全コンストラクタ、値オブジェクト、不変）の考え方を使って、CampaignBudget を再設計してください。

制約・前提条件

• Python 3.12+
• 金額（円）を表す値オブジェクト Money を導入すること。0円未満の Money は生成できないようにする
• CampaignBudget は「予算」「消化額」が揃っていない状態のインスタンスを一切生成できないようにする（完全コンストラクタ）
• CampaignBudget は生成後にフィールドを直接変更できない（不変）。支出を記録する操作は、新しいインスタンスを返すメソッドとして提供する
• 消化額が予算を超える状態（生成時・支出記録時のいずれも）を許可してはならず、超える場合は専用の例外を送出すること
• 負の金額を「支出」として記録しようとした場合の扱いも設計に含めること（Money の不変条件により自然に防げる設計が望ましい）

悪いコード (Before)

📋 コピーclass CampaignBudget:
    def __init__(self):
        self.total_yen = 0
        self.spent_yen = 0

    def set_total(self, total_yen):
        self.total_yen = total_yen

    def add_spend(self, amount):
        self.spent_yen += amount

# --- 呼び出し側（複数箇所に散らばっている） ---
budget = CampaignBudget()
budget.set_total(500_000)
budget.add_spend(200_000)

# 別の処理: 広告配信APIのレスポンスをそのまま加算
budget.add_spend(webhook_payload["cost_delta"])  # マイナス値が来ることもある

# さらに別の処理: 手動での予算調整
budget.spent_yen -= 50_000  # 属性を直接いじって「消化額を戻す」

ヒント（段階的開示）

from __future__ import annotations
from dataclasses import dataclass

MIN_YEN = 0

class InvalidMoneyError(ValueError): ...
class BudgetExceededError(ValueError): ...

@dataclass(frozen=True, slots=True)
class Money:
    yen: int

    def __post_init__(self) -> None:
        if self.yen < MIN_YEN:
            raise InvalidMoneyError(...)

    def add(self, other: Money) -> Money:
        return Money(...)

    def subtract(self, other: Money) -> Money:
        return Money(...)  # 負になる場合はMoney側の検証で自然にエラーになる

    def is_greater_than(self, other: Money) -> bool:
        return self.yen > other.yen

@dataclass(frozen=True, slots=True)
class CampaignBudget:
    total: Money
    spent: Money

    def __post_init__(self) -> None:
        if self.spent.is_greater_than(self.total):
            raise BudgetExceededError(...)

    @property
    def remaining(self) -> Money:
        return ...

    def record_spend(self, amount: Money) -> CampaignBudget:
        new_spent = ...
        return CampaignBudget(total=..., spent=...)

問題点分析（7点）

状態遷移の比較（SVG）— 可変オブジェクト vs 値オブジェクト

模範解答

📋 コピー"""販促キャンペーンの予算管理モジュール。

良いコード・悪いコードで学ぶ設計入門（改訂新版）
  Ch3: カプセル化 — 完全コンストラクタ・値オブジェクト・不変

金額(Money)とキャンペーン予算(CampaignBudget)をいずれも不正な状態で
生成できない値オブジェクトとして実装する。
"""
from __future__ import annotations

from dataclasses import dataclass

MIN_YEN = 0  # 金額の下限（これ未満の円は不正な値として扱う）


class InvalidMoneyError(ValueError):
    """金額が不正な値（0円未満）である場合に送出する例外。"""


class BudgetExceededError(ValueError):
    """キャンペーン予算の消化額が予算総額を超える場合に送出する例外。"""


@dataclass(frozen=True, slots=True)
class Money:
    """日本円の金額を表す値オブジェクト。

    生成された瞬間から必ず0円以上であることが保証される（完全コンストラクタ）。
    インスタンスは不変であり、加減算の結果は常に新しいインスタンスとして返す。

    Attributes:
        yen: 円単位の金額。0以上の整数のみ許可する。

    Raises:
        InvalidMoneyError: yenがMIN_YEN未満の場合。
    """
    yen: int

    def __post_init__(self) -> None:
        if self.yen < MIN_YEN:
            raise InvalidMoneyError(
                f"金額は{MIN_YEN}円以上である必要があります: {self.yen}円"
            )

    def add(self, other: Money) -> Money:
        """他のMoneyを加算した新しいMoneyを返す。

        Args:
            other: 加算する金額。

        Returns:
            加算後の新しいMoneyインスタンス。
        """
        return Money(self.yen + other.yen)

    def subtract(self, other: Money) -> Money:
        """他のMoneyを減算した新しいMoneyを返す。

        Args:
            other: 減算する金額。

        Returns:
            減算後の新しいMoneyインスタンス。

        Raises:
            InvalidMoneyError: 減算結果が0円未満になる場合
                （Moneyの__post_init__による検証を通じて送出される）。
        """
        return Money(self.yen - other.yen)

    def is_greater_than(self, other: Money) -> bool:
        """自身がotherより大きい金額かどうかを返す。"""
        return self.yen > other.yen


@dataclass(frozen=True, slots=True)
class CampaignBudget:
    """販促キャンペーンの予算と消化額を表す値オブジェクト。

    「予算」と「消化額」が揃っていない状態のインスタンスは生成できず
    （完全コンストラクタ）、消化額が予算を超える組み合わせも生成できない。
    生成後は不変であり、支出の記録はrecord_spend()が新しいインスタンスを
    返すことで表現する（外部からの直接書き換えを禁止）。

    Attributes:
        total: キャンペーンの総予算。
        spent: これまでの消化額。

    Raises:
        BudgetExceededError: spentがtotalを超えている場合。
    """
    total: Money
    spent: Money

    def __post_init__(self) -> None:
        if self.spent.is_greater_than(self.total):
            raise BudgetExceededError(
                f"消化額が予算を超えています: "
                f"spent={self.spent.yen}円, total={self.total.yen}円"
            )

    @property
    def remaining(self) -> Money:
        """残予算を返す。"""
        return self.total.subtract(self.spent)

    def record_spend(self, amount: Money) -> CampaignBudget:
        """支出を記録した新しいCampaignBudgetを返す。

        自身のフィールドは一切変更せず、支出反映後の新しいインスタンスを
        生成して返す。これにより「いつ・どの呼び出しで消化額が変わったか」が
        コード上のメソッド呼び出しに必ず対応し、属性への直接代入による
        追跡不能な変更を構造的に防ぐ。

        Args:
            amount: 今回記録する支出額（0円未満はMoneyの生成時点で拒否される）。

        Returns:
            支出反映後の新しいCampaignBudgetインスタンス。

        Raises:
            BudgetExceededError: 記録後の消化額が予算を超える場合。
        """
        new_spent = self.spent.add(amount)
        return CampaignBudget(total=self.total, spent=new_spent)

📋 コピーbudget = CampaignBudget(total=Money(500_000), spent=Money(0))
budget = budget.record_spend(Money(200_000))
print(budget.spent.yen, budget.remaining.yen)
# => 200000 300000

try:
    budget.record_spend(Money(400_000))  # 200,000 + 400,000 = 600,000 > 500,000
except BudgetExceededError as e:
    print(e)
    # => 消化額が予算を超えています: spent=600000円, total=500000円

try:
    Money(-50_000)  # webhookの異常なcost_deltaに相当
except InvalidMoneyError as e:
    print(e)
    # => 金額は0円以上である必要があります: -50000円

ポイント解説

実務への応用

MOpsの予算管理バッチ（Argo Workflows / Cloud Run上で広告配信APIのwebhookを受け続けるサービス）では、外部APIのレスポンス異常値がそのまま内部状態を汚染するリスクが常にある。Moneyのような値オブジェクトで「そもそも不正な値はオブジェクトとして存在できない」設計にしておけば、バリデーションをif文で都度書く必要がなくなり、レビュー時にも「このクラスのインスタンスが存在する＝条件を満たしている」と読める。

今日のまとめ

次のステップ

• 発展問題1: 複数の広告チャネル（Google/Meta/LINE）ごとのCampaignBudgetを1つのCampaignBudgetPoolとして集約管理し、「チャネル別予算の合計がキャンペーン全体予算を超えないこと」という上位の不変条件を、各CampaignBudgetの不変性を保ったままどう表現するか設計する
• 発展問題2: record_spend()が同時に複数のワーカーから呼ばれるケースを想定し、Cloud SQL上の永続化と組み合わせた楽観的ロック（バージョン番号 or total/spentを条件にしたUPDATE）を実装する
• 参考: 「良いコード・悪いコードで学ぶ設計入門」第3章（カプセル化）、第5章（実践カプセル化：プリミティブ型執着）

自己評価（あとで記入）