Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Track every workflow and its extension points in the plan
Damian Legawiecca9ef646adc9
diff --git a/docs/plans/6.0-service-workflows.md b/docs/plans/6.0-service-workflows.mdindex 52c5f3fa12..6b8f468d42 100644--- a/docs/plans/6.0-service-workflows.md+++ b/docs/plans/6.0-service-workflows.md@@ -1,10 +1,10 @@# Service Workflows — one step DSL for services, sagas, hooks and events-**Status:** In Progress — Phase 1 shipped to 6-0-dev as a two-tier split (2026-07-30): `Spree::Workflow` (the DSL) powers the curated flows in `app/workflows/`; every other service stays a plain ServiceModule class. Phase 3 (extension surface: `run_hooks` returning a merged hash, `reject!`, validate/context hooks, four service graduations) shipped 2026-08-02+**Status:** In Progress — Phase 1 shipped to 6-0-dev as a two-tier split (2026-07-30): `Spree::Workflow` (the DSL) powers the curated flows in `app/workflows/`; every other service stays a plain ServiceModule class. Phase 3 (extension surface: `run_hooks` returning a merged hash, `reject!`, validate/context hooks, four service graduations) shipped 2026-08-02. See **Workflow and hook inventory** below for the 30 shipped workflows and their extension points, **To deliver** for what is still planned, and **Known gaps** for what is wrong in what shipped**Target:** Spree 6.0**Depends on:** `6.0-cart-order-split.md` (Carts::Complete is the reference implementation and stress test). Coordinates with: `6.0-multi-vendor-marketplace.md` (payout runs are the first durable-flow consumer), the Rails 8.1 floor decision (decisions.md 2026-07-29 — ActiveJob Continuations are the durability primitive).**Author:** Damian Legawiec + Claude (design session 2026-07-30)-**Last updated:** 2026-08-02+**Last updated:** 2026-08-03## Summary@@ -370,59 +370,165 @@ plan.### Phase 3 — extension surface (2026-08-02, targets 6.0) — **shipped**-Two waves that finish the extension surface on the 6.0 boundary, per decision-12. Wave A adds no classes; Wave B graduates four services that have already-earned the tier. Neither is a sweep — the list is closed.+Two waves finished the extension surface on the 6.0 boundary, per decision 12.+Wave A added the runtime contracts (`run_hooks` returning a merged hash,+`reject!`) plus hooks on the existing workflows; Wave B graduated four services+that had already earned the tier (`Fulfillments::Create`, `Payments::Capture`,+`Payments::Refund`, `Payments::HandleWebhook`, `Carts::Merge`). Returns,+exchanges and claims then arrived with hooks from the start.-Both landed 2026-08-02. `Hooks#dispatch` returns the merged hash,-`Workflow#reject!` is public API, and the four graduated flows kept their spec-batteries unmodified (28 fulfillment, 16 webhook, plus merge coverage moved to-`spec/workflows/`). Legacy `*_service`/`cart_merge_strategy` dependency names-stay readable one release through `LEGACY_WORKFLOW_KEYS`.+## Workflow and hook inventory-**Wave A — runtime contracts + hooks on existing workflows.** Two runtime-additions first (both additive, neither changes existing behaviour):+Every workflow in `app/workflows/`, its Dependencies seam and its hooks.+**This table is the checklist** — a new workflow is not done until it has a+seam, its hooks are declared, and the extension docs list them.-1. `run_hooks` collects handler return values and deep-merges them into a hash- it returns. Lifecycle hooks ignore it; context hooks consume it.-2. `reject!(message)` on `Spree::Workflow`, wrapping the existing failure path.+Hook kinds: **V** = validate (veto via `reject!`), **C** = context (handler+returns a hash, deep-merged), **L** = lifecycle (past tense, read-only).-Then the hooks themselves — each a `hooks :name` declaration plus a `run_hooks`-call at an existing seam, with no restructuring:+### Cart and checkout-| Workflow | Hook | Why |-|---|---|---|-| `Carts::AddItem` | `validate` | Reject an add before the line item is built — purchase limits, B2B eligibility, per-group rules |-| `Carts::Complete` | `validate` | Guard completion (fraud, credit hold, required custom fields) |-| `Carts::Complete` | `after_finalize` | We ship `before_finalize` only; there is no in-flow point after placement succeeds |-| `Carts::Recalculate` | `after_recalculate` | React to a repriced cart before the caller sees it |-| `Orders::Cancel` | `before_cancel` | Veto a cancellation (already-shipped guard, vendor policy) |-| `Orders::Resume` | `before_resume` | Symmetry with cancel |--Context hooks are **no longer blocked** (contracts resolved 2026-08-02), so-`Carts::Recalculate` also gains `set_promotion_context` and-`Carts::RecalculateTotals` gains `set_tax_line_context` — both consuming the-merged hash `run_hooks` now returns.--**Wave B — graduate four services.** Each carries external I/O or real-orchestration and is currently hand-rolling what `Spree::Workflow` provides:--| Service today | Becomes | Hooks | Why it qualifies |+| Workflow | Seam | Hooks | |+|---|---|---|---|+| `Carts::AddItem` | `cart_add_item_workflow` | `validate` (V), `after_item_added` (L) | ✅ |+| `Carts::Complete` | `carts_complete_workflow` | `validate` (V), `before_finalize` (L), `after_finalize` (L) | ✅ |+| `Carts::Recalculate` | `cart_recalculate_workflow` | `set_promotion_context` (C), `after_recalculate` (L) | ✅ |+| `Carts::RecalculateTotals` | `cart_recalculate_totals_workflow` | `set_tax_line_context` (C) | ✅ |+| `Carts::Merge` | `cart_merge_workflow` | `validate` (V), `after_merge` (L) | ✅ |++### Order++| Workflow | Seam | Hooks | |+|---|---|---|---|+| `Orders::Cancel` | `order_cancel_workflow` | `before_cancel` (V), `after_cancel` (L) | ✅ |+| `Orders::Resume` | `order_resume_workflow` | `before_resume` (V), `after_resume` (L) | ✅ |+| `Orders::Complete` | `order_complete_workflow` | — | ⬜ no hooks; draft-order completion funnels into `Carts::Complete`, so its hooks cover the flow. Revisit if a draft-only seam is asked for |+| `Orders::AddItem` | `order_add_item_service` | inherits AddItem's, own keys | ✅ |+| `Orders::Recalculate` | — | inherits Recalculate's, own keys | ✅ |+| `Orders::RecalculateTotals` | `order_recalculate_totals_workflow` | inherits, own keys | ✅ |++Twins subclass their cart counterpart and dispatch under **their own** key+(`orders.add_item.validate`, not the cart one), so an extension can target+admin draft-order edits without touching storefront carts.++### Fulfillment++| Workflow | Seam | Hooks | ||---|---|---|---|-| `Fulfillments::Create` (274 lines) | `app/workflows/spree/fulfillments/create.rb` | `validate`, `after_create`, `get_provider_data` | Hand-rolled `order.lock!`, `return failure` inside a transaction, unit movement + stock transfer + repricing + totals. The clearest case in the codebase |-| `Payment#capture!` / `Refund#perform!` (model methods) | `Payments::Capture`, `Payments::Refund` | `validate`, `before_capture`/`after_capture`, `before_refund`/`after_refund` | Gateway I/O ran wherever the caller happened to be, including inside transactions — `Refund` fired its credit from an `after_create` callback. The workflows own the boundary and the guards; the money movement stays in the model (state machine and capture events unchanged), called from an `external_step` |-| `Payments::HandleWebhook` | `app/workflows/spree/payments/handle_webhook.rb` | `after_handle` | Branchy dispatch over gateway callbacks with no compensation and no replay guard |-| `Carts::Merge` | `app/workflows/spree/carts/merge.rb` | `validate`, `after_merge` | Spans a transaction plus a totals recalculation; `validate` is where a store customizes merge policy |+| `Fulfillments::Create` | `fulfillment_create_workflow` | `validate` (V), `get_provider_data` (C), `after_create` (L) | ✅ |-Note on the in-transaction idempotency guard: `HandleWebhook` skips an-already-settled session with a plain `next` inside `order.with_lock`, not-`halt!` — `halt!` is forbidden inside a workflow-opened transaction (there is-nothing committed to halt with).+### Payment++| Workflow | Seam | Hooks | |+|---|---|---|---|+| `Payments::Capture` | `payment_capture_workflow` | `validate` (V), `before_capture` (L), `after_capture` (L) | ✅ |+| `Payments::Refund` | `payment_refund_workflow` | `validate` (V), `before_refund` (L), `after_refund` (L) | ✅ |+| `Payments::HandleWebhook` | `payments_handle_webhook_workflow` | `after_handle` (L) | ✅ |++### Returns++| Workflow | Seam | Hooks | |+|---|---|---|---|+| `Returns::Create` | `return_create_workflow` | `validate` (V), `after_create` (L) | ✅ |+| `Returns::Approve` | `return_approve_workflow` | `validate` (V), `after_approve` (L) | ✅ |+| `Returns::Receive` | `return_receive_workflow` | `validate` (V), `before_restock` (L), `after_receive` (L) | ✅ |+| `Returns::Refund` | `return_refund_workflow` | `validate` (V), `before_refund` (L), `after_refund` (L) | ✅ |+| `Returns::Cancel` | `return_cancel_workflow` | `validate` (V), `after_cancel` (L) | ✅ |++### Exchanges++| Workflow | Seam | Hooks | |+|---|---|---|---|+| `Exchanges::Create` | `exchange_create_workflow` | `validate` (V), `after_create` (L) | ✅ |+| `Exchanges::Approve` | `exchange_approve_workflow` | `validate` (V), `after_approve` (L) | ✅ |+| `Exchanges::Receive` | `exchange_receive_workflow` | `validate` (V), `before_restock` (L), `after_receive` (L) | ✅ |+| `Exchanges::Fulfill` | `exchange_fulfill_workflow` | `validate` (V), `before_settle` (L), `after_fulfill` (L) | ✅ |+| `Exchanges::Cancel` | `exchange_cancel_workflow` | `validate` (V), `after_cancel` (L) | ✅ |-`get_provider_data` on fulfillment creation is a context hook, using the same-collect-and-merge contract: handlers return provider-specific payload-(carrier account, service level, customs data) that the fulfillment provider-call consumes.+### Claims++| Workflow | Seam | Hooks | |+|---|---|---|---|+| `Claims::Create` | `claim_create_workflow` | `validate` (V), `after_create` (L) | ✅ |+| `Claims::Approve` | `claim_approve_workflow` | `validate` (V), `after_approve` (L) | ✅ |+| `Claims::Resolve` | `claim_resolve_workflow` | `validate` (V), `before_settle` (L), `after_resolve` (L) | ✅ |+| `Claims::Deny` | `claim_deny_workflow` | `validate` (V), `after_deny` (L) | ✅ |+| `Claims::Cancel` | `claim_cancel_workflow` | `validate` (V), `after_cancel` (L) | ✅ |++**Core handlers registered on these hooks.** Only one:+`Spree::Returns::EligibilityValidator` on `returns.create.validate` and+`exchanges.create.validate` — a per-market return window that staff bypass+(decisions.md 2026-08-03). Everything else is unregistered seam.++## To deliver++Planned workflows that do not exist yet. Each is a checklist item: a workflow+is not done until it has a Dependencies seam, its hooks are declared, and the+extension docs list them.++### 6.1 — OrderChange substrate (`6.1-order-change-substrate.md`)++Blocked on nothing in this plan; deliberately deferred so 6.0 does not also+carry a new schema surface and extension API.++| Workflow | Hooks | |+|---|---|---|+| `OrderChanges::Begin` | `after_begin` (L) | ⬜ |+| `OrderChanges::AddAction` | `validate` (V) | ⬜ |+| `OrderChanges::Request` | `after_request` (L) | ⬜ |+| `OrderChanges::Confirm` | `before_settle` (L), `after_confirm` (L) | ⬜ |+| `OrderChanges::Cancel` | `after_cancel` (L) | ⬜ |++`OrderChanges::Preview` stays a Tier 1 service — a pure read with no hooks and+no side effects.++### Candidates, not yet committed++Services that would qualify on external I/O or orchestration, listed so the+decision is deliberate rather than accidental. **None is scheduled** — the rule+still holds that a service graduates when it earns a hook, not speculatively.++| Service | Why it might qualify | |+|---|---|---|+| `Checkout::Complete` | Thin wrapper over `Carts::Complete`; if it stays, it should probably be deleted rather than graduated | ⬜ |+| `Orders::Approve` | Publishes an event and writes an approval record; a B2B multi-level flow would want `validate` | ⬜ |+| `GiftCards::Redeem` | Money movement, currently a model call | ⬜ |+| `StockReservations::Reserve` | Already called as a step from `Carts::AddItem`; a hook would let a store veto a reservation | ⬜ |+| Marketplace payout run | `6.0-multi-vendor-marketplace.md` — the first flow that may justify durable execution | ⬜ |++## Known gaps++Not new workflows — things wrong or missing in what already shipped.++- ⬜ **Extension-facing docs list only the pre-returns hooks.**+ `docs/developer/customization/workflows.mdx` documents 24 hook points; the+ fifteen returns/exchanges/claims workflows added since are missing from the+ reference table. The table is spec-asserted in core, so the spec needs+ extending alongside it.+- ⬜ **`Spree.hooks.clear!` wipes core registrations permanently.** The+ boot-time initializer runs once, so any spec or extension calling it+ silently disables `EligibilityValidator` for the rest of the process. Either+ narrow those call sites to `unregister`, or make core registrations+ restorable — deliberately not done yet, since the alternative adds a+ two-tier concept to a public registry.+- ⬜ **No UI-state coverage.** Workflow specs are thorough; the dashboard+ surfaces they drive have none. Four bugs shipped in the post-sale UI that+ spec batteries could not catch (empty dropdowns on terminal records, a stale+ sidebar count, a menu firing without a dialog, a disabled button with no+ explanation). A Playwright walk through open → approve → resolve asserting+ menu contents at each step would cover most of them.+- ⬜ **Wave B leftovers.** `Payments::Capture` and `Refund` own the transaction+ boundary and guards, but the money movement still lives in the model+ (`Payment#capture!`, `Refund#perform!` in an `after_create`). Moving it into+ the workflows is a larger change than the boundary fix and has not been+ scheduled.+- ⬜ **`get_provider_data` has no consumer.** Declared on+ `Fulfillments::Create`, but no fulfillment provider reads the merged hash+ yet. It is a published contract with no proof it fits the providers' needs.+- ⬜ **No post-sale subscribers or mailers.** `return.requested`,+ `return.approved`, `claim.resolved` and the rest are published and nothing+ listens, so a self-service return notifies nobody. The dashboard sidebar+ counter is the only signal a merchant gets.**Explicitly out of scope.** No workflows for CRUD. Creating, updating anddeleting a region, tax rate, API key or product is a controller plus a model@@ -430,10 +536,6 @@ save; wrapping those in workflow classes would add hundreds of pass-throughclasses with no hook, no compensation and no external I/O to justify them.Workflows are earned by orchestration, not by being a write.-**Sequencing.** Wave A first — it is additive and low-risk, and it settles the-`validate` contract that Wave B depends on. `6.1-order-change-substrate.md`-depends on both and must not start before they land.-## Constraints on Current Work- New services are plain sequential `ServiceModule` bodies (like