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.

Record the shipped extension surface in the plans

Damian Legawiecfee98a356bb1
diff --git a/CLAUDE.md b/CLAUDE.md
index 14a83bafcd..15f3e431e9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,7 +31,7 @@ Active plans (6.0 target, work pending):
- `6.0-inventory-operations.md` — StockTransfer lifecycle (draft → ready_to_ship → in_transit → received with partial receive), new `Spree::PurchaseOrder` + `Spree::Supplier` (renamed from Vendor — `Spree::Vendor` is the marketplace seller, see decisions.md 2026-07-14) replacing today's "external receive" hack, variant + stock-location stock history panels. Consumes the typed-movement primitives from `6.0-typed-stock-movements.md`.
- `6.0-replace-taxons-with-categories.md` — Split Taxon into Category (hierarchy) + Collection (flat/rule-based). **Shipped to 6-0-dev (PR #14302):** the Category surface (5.5–5.6) plus the 6.0 core — `spree_taxons`→`spree_categories` table rename + inheritance flip (`Spree::Category < Spree.base_class`, `Spree::Taxon` alias kept), the full `Collection` stack (model + rules + DB/Meilisearch manual sort + API), the taxon→category/collection data migration, and de-ruling Category. Pending (all 6.1): channel-aware `CollectionRules::AvailableOn` (ships interim now, rides with channels) + dropping `spree_taxon_rules`/`Taxonomy`. No brand feature in 6.0 — brands are modeled as a Category/Collection; `brand_taxon`/`brand_name` removed with `Taxonomy`.
- `6.0-delivery-method-rules.md` — `Spree::DeliveryMethodRule` STI on DeliveryMethod (design finalized 2026-07-29): ItemTotal/Weight rules first (Channel/Market/CustomerGroup later in lockstep with payment-method-rules), enforced solely in `Stock::Estimator`'s method filter so calculator- AND provider-priced methods obey eligibility; replaces the FlatRate-only bound preferences (one-release bridge + data task). Phase 1 rides the 6.0 core-rewrite finishing work.
-- `6.0-service-workflows.md` — Two-tier services doctrine (2026-07-30). **Tier 1 `app/services/`:** plain `ServiceModule` classes, hand-written `def call(cart:, ...)`, Ruby kwargs as the contract — the permanent default; no DSL, no new `run`-pipelines, no hand-rolled sagas. **Tier 2 `app/workflows/`:** `Spree::Workflow` — named steps inside a plain `def perform(order:, ...)` (the ActiveJob::Continuable shape; bare `super` turns parameters into readers). Vocabulary: `step`/`external_step` (+ `with:`, `on_flow_failure:`), `run_hooks` + class-level `hooks`, `failure`/`halt!`; plain `ApplicationRecord.transaction`/`with_lock`/`rescue`/`publish_event`; every step instrumented as `step.spree_workflow`. Money lives in `Carts::RecalculateTotals` (single totals seam; the completed-order branch is the post-placement resum — rows re-summed, never regenerated), statuses in `Orders::UpdateStatuses` (refreshes each fulfillment's state, then rolls up); Order/CartUpdater are 6.1-removed warning shells. Shared Cart/Order surface lives in `Spree::Purchase::*` concerns; completion side effects (newsletter, account creation, risk) run in the sync `OrderPlacedSubscriber` on order.placed. Reserved for flows needing hooks, compensation/external I/O, or replay — currently `Carts::Complete`, `Carts::AddItem`, `Carts::Recalculate`, `Carts::RecalculateTotals` (+ order twins) and `Orders::Cancel` (absorbed `Order#after_cancel`; gateway settlement is an external_step). A service graduates to the workflow tier when it earns a hook, never speculatively — but hooks on flows already in the tier ship deliberately on the 6.0 boundary (2026-08-02), since hook keys are public API and moving one later is breaking. **New models get no state machine** — plain `status` string + inclusion validation, transitions through workflows; gateway I/O never in a save callback. Three hook families, contracts settled 2026-08-02: **lifecycle** (past tense, read-only), **validate** (handler calls `workflow.reject!(message)` to veto), **context** (`set_*_context`/`get_provider_data` — handler returns a hash, `run_hooks` deep-merges all handlers and returns it; last writer wins on collision). Phase 3 waves: **Wave A** = two runtime additions (`run_hooks` returns merged hash, `reject!`) + hooks on existing workflows (AddItem, Complete, Recalculate, RecalculateTotals, Cancel, Resume); **Wave B** graduates `Fulfillments::Create`, `Payments::Capture`/`Refund`, `Payments::HandleWebhook`, `Carts::Merge`. No workflows for plain CRUD. Workflow Dependencies seams use `*_workflow` keys; legacy `*_service` names stay settable/readable with warnings until 6.1 but writes are stashed, never applied (old service classes aren't workflow-contract compatible). `Carts::Complete` battery must pass unmodified. **Durability = plain Rails:** long-running background work uses `ActiveJob::Continuable` directly (reference: `Spree::Imports::ProcessJob` — CSV spine with a row-number cursor; `CreateRowsJob`/`ProcessRowsJob` deprecated shells); workflows are synchronous request-cycle flows and are NOT jobs — Workflow-level durable execution ships only if the payout run proves the need.
+- `6.0-service-workflows.md` — Two-tier services doctrine (2026-07-30). **Tier 1 `app/services/`:** plain `ServiceModule` classes, hand-written `def call(cart:, ...)`, Ruby kwargs as the contract — the permanent default; no DSL, no new `run`-pipelines, no hand-rolled sagas. **Tier 2 `app/workflows/`:** `Spree::Workflow` — named steps inside a plain `def perform(order:, ...)` (the ActiveJob::Continuable shape; bare `super` turns parameters into readers). Vocabulary: `step`/`external_step` (+ `with:`, `on_flow_failure:`), `run_hooks` + class-level `hooks`, `failure`/`halt!`; plain `ApplicationRecord.transaction`/`with_lock`/`rescue`/`publish_event`; every step instrumented as `step.spree_workflow`. Money lives in `Carts::RecalculateTotals` (single totals seam; the completed-order branch is the post-placement resum — rows re-summed, never regenerated), statuses in `Orders::UpdateStatuses` (refreshes each fulfillment's state, then rolls up); Order/CartUpdater are 6.1-removed warning shells. Shared Cart/Order surface lives in `Spree::Purchase::*` concerns; completion side effects (newsletter, account creation, risk) run in the sync `OrderPlacedSubscriber` on order.placed. Reserved for flows needing hooks, compensation/external I/O, or replay — currently `Carts::Complete`, `Carts::AddItem`, `Carts::Recalculate`, `Carts::RecalculateTotals` (+ order twins) and `Orders::Cancel` (absorbed `Order#after_cancel`; gateway settlement is an external_step). A service graduates to the workflow tier when it earns a hook, never speculatively — but hooks on flows already in the tier ship deliberately on the 6.0 boundary (2026-08-02), since hook keys are public API and moving one later is breaking. **New models get no state machine** — plain `status` string + inclusion validation, transitions through workflows; gateway I/O never in a save callback. Three hook families, contracts settled 2026-08-02: **lifecycle** (past tense, read-only), **validate** (handler calls `workflow.reject!(message)` to veto), **context** (`set_*_context`/`get_provider_data` — handler returns a hash, `run_hooks` deep-merges all handlers and returns it; last writer wins on collision). Phase 3 **shipped (2026-08-02)**: `run_hooks` returns the merged hash and `Workflow#reject!` is public API; `validate`/context/lifecycle hooks live on AddItem, Complete, Recalculate, RecalculateTotals, Cancel and Resume; `Fulfillments::Create`, `Payments::Capture`/`Refund`, `Payments::HandleWebhook` and `Carts::Merge` moved to `app/workflows/` (seams `fulfillment_create_workflow`, `payment_capture_workflow`, `payment_refund_workflow`, `payments_handle_webhook_workflow`, `cart_merge_workflow`; legacy names readable one release). Payment workflows own the transaction boundary and guards — money movement stays in the model, called from an `external_step`. No workflows for plain CRUD. Workflow Dependencies seams use `*_workflow` keys; legacy `*_service` names stay settable/readable with warnings until 6.1 but writes are stashed, never applied (old service classes aren't workflow-contract compatible). `Carts::Complete` battery must pass unmodified. **Durability = plain Rails:** long-running background work uses `ActiveJob::Continuable` directly (reference: `Spree::Imports::ProcessJob` — CSV spine with a row-number cursor; `CreateRowsJob`/`ProcessRowsJob` deprecated shells); workflows are synchronous request-cycle flows and are NOT jobs — Workflow-level durable execution ships only if the payout run proves the need.
- `6.0-store-scoped-custom-field-definitions.md` — Add `store_id` + persisted `filter_key` to `Spree::MetafieldDefinition` (today global and computed), making uniqueness `(store_id, resource_type, filter_key)` with a DB index. Deferred from the 5.6 custom-field search/sort/filter work (schema change, not patch-safe). **Until then:** `filter_key` is a computed method — no Ransack predicates or `where`/`order` against it; definitions are global; uniqueness rests on a `CONCAT` validation with no index behind it.
Multi-version plans (some phases shipped, some pending):
diff --git a/docs/plans/6.0-service-workflows.md b/docs/plans/6.0-service-workflows.md
index 802751c519..52c5f3fa12 100644
--- a/docs/plans/6.0-service-workflows.md
+++ b/docs/plans/6.0-service-workflows.md
@@ -1,6 +1,6 @@
# 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
+**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
**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)
@@ -368,12 +368,18 @@ plan.
execution is deliberately not shipped — revisit with the payout run
per the note above.
-### Phase 3 — extension surface (2026-08-02, targets 6.0)
+### 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.
+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`.
+
**Wave A — runtime contracts + hooks on existing workflows.** Two runtime
additions first (both additive, neither changes existing behaviour):
@@ -404,10 +410,15 @@ orchestration and is currently hand-rolling what `Spree::Workflow` provides:
| Service today | Becomes | Hooks | Why it qualifies |
|---|---|---|---|
| `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!` / `#credit!` (model methods) | `Payments::Capture`, `Payments::Refund` | `before_capture`, `after_capture`, `before_refund`, `after_refund` | Gateway I/O currently runs wherever the caller happens to be, including inside transactions. `external_step` is exactly this |
+| `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 |
+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).
+
`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