Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.md
index 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 and
deleting 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-through
classes 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