purchase-flow

PurchaseFlow 規約 — 受注処理パイプライン（EC-CUBE 4.4）

対象: src/Eccube/Service/PurchaseFlow/**, app/Plugin/{Code}/Service/PurchaseFlow/** 前提: Symfony 7.4 / PHP 8.2+

目的: 受注に関わる計算・検証・確定（送料/手数料/税/値引き/ポイント/在庫引当・採番）は、 コントローラや汎用 Service に直書きせず、PurchaseFlow のパイプライン上の Processor/Validator に置く。 これが EC-CUBE の受注処理の核心。Skill service と対で使う。

パイプラインの構造（PurchaseFlow::validate() の実行順）

PurchaseFlow は cart / shopping / order の 3 フローぶん存在し（PurchaseContext::CART_FLOW / SHOPPING_FLOW / ORDER_FLOW）、それぞれ別の Processor 群を持つ。validate() は次の順で実行する （各段階の間で金額の再集計 calculateAll() が走る）:

確定系は別メソッドで、validate() とは独立に呼ばれる:

validate() 内では removeDiscountItem() を全 DiscountProcessor について先に呼び、値引き明細をクリアしてから addDiscountItem() を呼ぶ。値引きは「いったん全消し→再計算で積み直す」のが大前提（後述）。

Item と ItemHolder の違い

• ItemInterface（明細1行）: OrderItem / CartItem。isProduct() / isDeliveryFee() / isCharge() / isDiscount() / isPoint() / isTax() で明細種別を判定し、getPrice() / getPriceIncTax() / getQuantity() / getProductClass() を持つ。送料・手数料・値引き・税も「明細の1行」として表現される点に注意。
• ItemHolderInterface（受注/カート全体）: Order / Cart。getItems()（ItemCollection）で明細を束ねる。 Order 固有の処理は instanceof Order でガードする（例: Cart には Shipping もポイントも無い）。
• PurchaseContext: 実行中コンテキスト。isCartFlow() / isShoppingFlow() / isOrderFlow() で どのフローかを判定でき、getOriginHolder()（フロー実行前の状態）/ getUser() を持つ。

基本ルール

• 追加先のコンポーネントを正しく選ぶ: 検証なら Validator、明細の付与/調整なら Preprocessor、値引きなら DiscountProcessor、在庫引当・採番など確定処理なら PurchaseProcessor。上表で対応づける。
• abstract 基底は validate()（protected）を override する。execute() は final で、InvalidItemException を捕捉して ProcessResult に変換する（自分で try/catch しない）。
• interface 系（ItemPreprocessor / ItemHolderPreprocessor / DiscountProcessor / PurchaseProcessor）は メソッドを実装する。PurchaseProcessor は AbstractPurchaseProcessor を継承すれば必要なメソッドだけ override 可。
• supports() で早期 return: フロー種別・Order か否か・店舗設定（BaseInfo）で適用可否を判定し、 対象外なら何もしない（AddPointProcessor::supports() が手本）。
• 金額計算は bcmath（bcadd / bcsub / bcmul / bccomp）。float 演算で組まない。 合計・税・送料・値引きの集計は PurchaseFlow::calculateAll() が各段階後に行うので、Processor 側は 明細（Item）を足し引きすることに集中する（合計の手計算は不要）。

エラーと警告の使い分け

• throwInvalidItemException() は ValidatorTrait のヘルパ。ProductClass を渡すと商品名つきメッセージになる。 メッセージは翻訳キーを渡す（trans() 相当が内部で走る）。
• ProcessResult は success() / warn() / error() のファクトリのみ（直接 new 不可）。addError のような メソッドは無い。例外を投げる→基底の execute() が ProcessResult に変換するのが正規フロー。

実装パターン

明細検証（ItemValidator）

namespace Eccube\Service\PurchaseFlow\Processor;

use Eccube\Entity\ItemInterface;
use Eccube\Service\PurchaseFlow\ItemValidator;
use Eccube\Service\PurchaseFlow\PurchaseContext;

class StockValidator extends ItemValidator
{
    #[\Override]
    protected function validate(ItemInterface $item, PurchaseContext $context): void
    {
        if (!$item->isProduct()) {
            return; // 商品明細以外は対象外
        }
        if ($item->getProductClass()->isStockUnlimited()) {
            return;
        }
        if ($item->getProductClass()->getStock() < $item->getQuantity()) {
            // ProductClass を渡すと商品名つきメッセージになる。常に warning 化される。
            $this->throwInvalidItemException('front.shopping.out_of_stock', $item->getProductClass());
        }
    }

    #[\Override]
    protected function handle(ItemInterface $item, PurchaseContext $context): void
    {
        // warning 後の自動補正（在庫数に丸める）
        $item->setQuantity($item->getProductClass()->getStock());
    }
}

受注前処理（ItemHolderPreprocessor）— 明細の付与・調整

class DeliveryFeePreprocessor implements ItemHolderPreprocessor
{
    #[\Override]
    public function process(ItemHolderInterface $itemHolder, PurchaseContext $context): void
    {
        if (!$itemHolder instanceof Order) {
            return; // Cart には Shipping が無い
        }
        // 1. 自分が前に作った明細を消す（ProcessorName で識別）
        // 2. 計算し直して付け直す（冪等にする）
        // OrderItem を new し、setProcessorName(self::class) で自前の明細に印を付ける
    }
}

冪等性が要: Preprocessor は validate() が複数回走っても結果が変わらないよう、 自分が追加した明細を getProcessorName() === self::class で識別して毎回いったん削除→再追加する （DeliveryFeePreprocessor が手本）。

値引き（DiscountProcessor）

interface DiscountProcessor // 実装する2メソッド
{
    public function removeDiscountItem(ItemHolderInterface $itemHolder, PurchaseContext $context): void;
    public function addDiscountItem(ItemHolderInterface $itemHolder, PurchaseContext $context): ?ProcessResult;
}

• removeDiscountItem() で自分の値引き明細を削除 → addDiscountItem() で追加。合計金額を超える値引きを作らない （超える場合は利用可能額まで丸めるかスキップし、ProcessResult::warn() を返す）。PointProcessor が手本。

確定処理（PurchaseProcessor）— 在庫引当・採番・ポイント付与

class StockReduceProcessor extends AbstractPurchaseProcessor
{
    #[\Override]
    public function prepare(ItemHolderInterface $itemHolder, PurchaseContext $context): void
    {
        if (!$itemHolder instanceof Order) {
            return;
        }
        // 在庫を引く。失敗時は ShoppingException / PurchaseException を投げる
    }

    #[\Override]
    public function rollback(ItemHolderInterface $itemHolder, PurchaseContext $context): void
    {
        // prepare の逆操作（在庫を戻す）を必ず実装する
    }
}

対象フローへの登録方法

PurchaseFlow への登録は 2 通り。どちらも「対象フロー（cart/shopping/order）」を指定する。

(A) コア: purchaseflow.yaml のタグで登録

app/config/eccube/packages/purchaseflow.yaml でサービス定義にタグを付ける。flow_type で対象フロー、 priority で実行順（降順＝大きいほど先）を指定する。

eccube.purchase.flow.item.validator.stock.validator:
    class: Eccube\Service\PurchaseFlow\Processor\StockValidator
    tags:
        - { name: eccube.item.validator, flow_type: cart, priority: 700 }

タグ名（PurchaseFlowPass の定数）と対応コンポーネント:

(B) プラグイン/Customize: 属性 #[CartFlow] / #[ShoppingFlow] / #[OrderFlow] で登録

Kernel が基底（ItemValidator 等）を registerForAutoconfiguration でタグ付けするため、 基底を継承/実装したクラスは自動でタグが付く。あとはどのフローに乗せるかを属性で宣言する （src/Eccube/Attribute/CartFlow.php 等）。flow_type ごとの YAML 配線は不要。

use Eccube\Attribute\CartFlow;
use Eccube\Attribute\ShoppingFlow;
use Eccube\Attribute\OrderFlow;
use Eccube\Service\PurchaseFlow\ItemValidator;

#[CartFlow]
#[ShoppingFlow]
#[OrderFlow] // 乗せたいフローだけ付ける
class SaleLimitOneValidator extends ItemValidator
{
    protected function validate(ItemInterface $item, PurchaseContext $context): void { /* ... */ }
}

• 手本は app/Plugin/PurchaseProcessors/Service/PurchaseFlow/Processor/SaleLimitOneValidator.php。
• PurchaseFlowPass は YAML 配線済みなら属性での二重登録を防ぐ（alreadyWired()）。(A) と (B) を併用しない。
• 属性方式は priority を指定できない（属性だけでは順序制御不可）。実行順が重要なら (A) の YAML タグを使う。

よくある間違い

• ❌ 在庫引当・採番・ポイント付与・送料/値引き計算をコントローラや汎用 Service に直書き → ✅ 該当 Processor/Validator を拡張する
• ❌ 検証なのに ItemHolderPreprocessor、明細付与なのに Validator、と取り違える → ✅ パイプライン表で役割に合うコンポーネントを選ぶ
• ❌ abstract 基底の execute() を override / 自前で try-catch → ✅ validate()（protected）だけ override。execute() は final
• ❌ ProcessResult を new する / addError() を探す → ✅ 例外（throwInvalidItemException / InvalidItemException）を投げ、基底に変換させる
• ❌ ItemValidator で「購入を止めたい」のに止まらない → ✅ ItemValidator は常に warning。中断したい検証は ItemHolderValidator/PostValidator で warning なしの error にする
• ❌ Preprocessor で明細を追加しっぱなし（再実行で多重化） → ✅ setProcessorName(self::class) で印を付け、毎回削除→再追加で冪等にする
• ❌ 値引きで合計金額を超える明細を作る → ✅ 利用可能額まで丸めるかスキップし ProcessResult::warn() を返す
• ❌ 金額を float / +・* で計算 → ✅ bcadd/bcsub/bcmul/bccomp を使う
• ❌ Cart でも getShippings() / getCustomer() を呼ぶ → ✅ instanceof Order でガード（Cart には Shipping もポイントも無い）
• ❌ PurchaseProcessor の rollback() を実装し忘れる → ✅ prepare() の逆操作（在庫戻し等）を必ず実装する
• ❌ 属性方式で実行順を制御しようとする → ✅ 順序が要るなら YAML タグの priority（降順）で指定する
• ❌ (A) YAML タグと (B) 属性を両方付ける → ✅ どちらか一方。コアは YAML、プラグイン/Customize は属性が定石

実行・確認方法

コンソール・QA ツール（PHPUnit / PHPStan / PHP-CS-Fixer / Rector）の実行方法は AGENTS.md「開発コマンド」を参照。

• パイプラインに実際にどの Processor が、どの順で乗っているかは PurchaseFlow::dump()（__toString()）で ツリー表示できる。登録できているか・順序が意図どおりかの確認に使う。
• プラグインでエンティティ拡張を伴う場合はプロキシ再生成（bin/console eccube:generate:proxies）を忘れない。

---

実装・改修後は、Skill service（責務分離）と review-responsibility で点検すること。 プラグインから追加する場合は Skill plugin も参照。