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.
Admin SPA CSV Import
Status: In Progress — open questions resolved and implemented in a single PR (2026-07-10)
Target: Spree 5.6
Depends on: 6.0-admin-spa.md, 6.0-admin-api.md, 5.5-admin-spa-csv-export.md (pattern precedent), 5.5-admin-api-key-scopes.md
Author: Damian Legawiec
Last updated: 2026-08-27
Summary
The legacy Rails admin (spree/admin) ships a full CSV import wizard: upload a file, map its columns onto an import schema, then watch a background pipeline process every row — with live UI updates pushed over Turbo Streams (ActionCable). The entire backend pipeline lives in core and is production-hardened: Spree::Import (STI: Products, Customers, ProductTranslations), Spree::ImportMapping, Spree::ImportRow, Spree::ImportSchema, the CreateRowsJob → ProcessRowsJob → ProcessGroupJob chain, row processors, and lifecycle events. The new React admin SPA (packages/dashboard) has none of it.
This plan brings imports to the SPA as a universal, registry-driven flow — one Admin API v3 surface, one SDK resource, one set of dashboard components that work for every type in Spree.import_types — mirroring the shipped CSV export architecture (5.5-admin-spa-csv-export.md). Live status uses API polling, not ActionCable: the SPA polls GET /imports/:id for a progress bar and counters, and replaces the legacy per-row live feed with a paginated failed-rows table that — unlike the legacy view — also works for large imports.
Key Decisions (do not deviate without discussion)
Reuse the existing
Spree::Importpipeline verbatim. No new models, jobs, state machine, or row processors. The legacySpree::Admin::ImportsControllerand its Turbo Streams views stay in place untouched; the new endpoints live alongside underSpree::Api::V3::Admin::ImportsController.Polling over ActionCable — this is a deliberate architecture decision, not a shortcut.
- The legacy "real-time" layer is Turbo Streams broadcasting server-rendered HTML partials (
imports/_row,_footer,_loader) from event subscribers (spree/admin/app/subscribers/spree/admin/import_row_subscriber.rb). None of that payload is usable by React; adopting ActionCable would mean building a new JSON channel protocol, not reusing anything. - Auth mismatch: ActionCable authenticates connections via cookies; the admin SPA holds its JWT in memory (
5.5-admin-auth-cookie-refresh.md). Passing tokens in the WS query string leaks them into proxy/server logs. - Reliability: WebSocket pushes have no replay — a dropped connection or a slept laptop silently loses progress updates mid-import. A poll always returns the full current state from the DB; the flow is self-healing by construction.
- Operational cost: no Redis/solid_cable requirement, no WS-aware proxy config for spree-starter deployments, nothing extra for secret-key API consumers (they poll the same endpoint).
- Actual load: one indexed
COUNTper watcher every 2s against counters that the pipeline already persists (rows_count, per-rowstatus,processing_groups_count/completed_groups_count). Negligible. - Precedent: the shipped export flow already polls (
packages/dashboard-core/src/hooks/use-export.ts, 2s interval). - Escape hatch: if a future release adds a shared realtime layer (e.g. notifications), the SPA swaps
refetchIntervalfor push-triggered invalidation; the API contract does not change.
- The legacy "real-time" layer is Turbo Streams broadcasting server-rendered HTML partials (
No live per-row feed; a polled failed-rows table instead. The legacy per-row Turbo appends only run for imports under
Spree::Config[:large_import_threshold](500 rows); large imports get counts only, with no row-level error visibility at all. The SPA shows the same UI for every size: progress bar + counters (polled at 2s), plus a paginatedGET /imports/:id/rows?q[status_eq]=failedtable (polled at ~5s while processing). Failures are the only actionable rows; a live scroll of successes is noise.large_import_thresholdremains a backend processing concern (bulk mode, events disabled) and is invisible to the UI.The mapping step stays. Column mapping is the genuinely valuable part of the legacy wizard (auto-assignment by header-name normalization, per-store metafield columns from
Import#schema_fields). The SPA renders it from data the API returns on create; the server stays the source of truth for mappings. The API additionally exposes asample_row(first data row) so the mapping UI can show an example value under each column — something the legacy UI never had.Upload via the shipped direct-uploads flow, then create with a signed blob id.
POST /api/v3/admin/direct_uploads+useDirectUpload(packages/dashboard-core/src/hooks/use-direct-upload.ts) already exist and already handle the Vite dev-proxy/CORS pitfalls.POST /importsacceptsattachment: <signed_id>— no multipart on the JSON API. (This refines themultipart/form-datanote next to the imports checklist in6.0-admin-api.md.)Secret-key gating: an import is a bulk write. Mirror
Spree::Export.required_scopewithSpree::Import.required_scope, but map every action to the write scope of the imported resource (Spree::Imports::Products→write_products). The index is filtered to the types the key can write. No standalonewrite_importsscope, same reasoning as exports.Overlay wizard, not a page (revised 2026-07-11 — originally a route under the settings shell). The upload step opens in a Sheet from the resource page toolbar; on create the wizard (mapping → progress → results, keyed off
import.status) opens in a full-window dialog using the bulk-price-editor shell — the user never leaves the table they were on. The open dialog is driven by an?import=<prefixed id>search param (same idiom as the webhooksdeliveryparam), so it deep-links and survives refresh; closing mid-processing is safe — the import continues server-side. The/settings/importshistory page (newauditsettings-nav group, future home for exports history and audit logs) reopens the same dialog on row click; there is no detail route.Retry failed rows ships in v1. The dispatcher already re-processes
pending_and_failedrows on any re-dispatch, so retry is one new state-machine transition (completed → processing, guarded on failures existing) + one endpoint + one button on the results screen. No new processing logic.Client-side gating is per target resource, not per
Spree::Import. The import button renders inside<Can I="create" a={subject}>wheresubjectis the imported resource (Spree::Producton the products page) — mirroring the server'swrite_<resource>scope model. No blanketSpree::Importsubject in the dashboardSubjectmap. Backend enforcement is unchanged and remains authoritative.Universal by registry. Everything is driven by
Spree.import_typesandImport#schema_fields. Adding a new import type (subclass + schema + row processor + registry entry) lights up the API, SDK types, and dashboard flow with no SPA changes beyond placing a button. This is the hook the translations plan (5.5-6.0-resource-translations-api.md, Phase 2 "generalize CSV across the registry") plugs into.
Design Details
What already exists (reused as-is)
| Piece | Location | Notes |
|---|---|---|
Spree::Import |
spree/core/app/models/spree/import.rb |
STI, polymorphic owner (Store), state machine on status: pending → mapping → completed_mapping → processing → completed | failed, rows_count counter cache, has_one_attached :attachment (private storage), preferred_delimiter preference |
Spree::ImportMapping |
.../import_mapping.rb |
schema_field ↔ file_column, auto-assign on start_mapping |
Spree::ImportRow |
.../import_row.rb |
raw row data (JSON), row_number, per-row status + validation_errors, polymorphic item link to the created record |
| Schemas | .../import_schemas/*.rb |
field name/label/required; Import#schema_fields appends per-store metafield definition columns |
| Jobs | spree/core/app/jobs/spree/imports/ |
CreateRowsJob (streams CSV → bulk upsert rows) → ProcessRowsJob (groups/batches) → ProcessGroupJob (processes, tracks completed_groups_count, completes import) |
| Row processors | spree/core/app/services/spree/imports/row_processors/ |
ProductVariant, Customer, ProductTranslation |
| Events | publishes_lifecycle_events |
import.completed, import.progress, import_row.completed/failed — webhook-ready, untouched |
| Event serializers | spree/api/app/serializers/spree/api/v3/import_serializer.rb, import_row_serializer.rb |
become the base classes for the new Admin serializers |
| Direct uploads | spree/api/.../admin/direct_uploads_controller.rb + useDirectUpload |
presign + browser PUT + signed_id, dev-proxy safe |
| Export SPA pattern | packages/dashboard-core/src/components/export-button.tsx, hooks/use-export.ts |
toolbar wiring via ResourceActionsContext, 2s polling, authed blob download |
Core changes (small, additive)
# spree/core/app/models/spree/import.rb
scope :for_store, ->(store) { where(owner: store) } # v3 ResourceController#scope calls model_class.for_store
# Deletable only when no jobs can be in flight. Base v3 destroy renders 422 otherwise.
def can_be_deleted?
%w[pending mapping completed failed].include?(status)
end
# New event, added INSIDE the existing `state_machine initial: :pending,
# attribute: :status` block (a bare `state_machine do` reopen would target
# the default :state attribute). Retry is cheap because the dispatcher
# already targets pending_and_failed rows — a transition + re-dispatch.
event :retry_failed_rows do
transition from: :completed, to: :processing, if: ->(import) { import.rows.failed.exists? }
end
after_transition on: :retry_failed_rows, do: :process_rows_async
# Note: the existing `after_transition to: :completed` hooks re-fire when the
# retry pass finishes — a second `import.completed` event is correct (it did
# complete again).
# Memoized per-status row counts for the poll payload — one grouped COUNT per request.
def rows_status_counts
@rows_status_counts ||= rows.group(:status).count
end
class << self
# Mirror of Spree::Export.required_scope, but imports WRITE the resource:
# Spree::Imports::Products => :products => gated by `write_products`.
def required_scope
return nil if self == Spree::Import
to_s.demodulize.underscore.to_sym
end
end
# spree/core/app/models/spree/import_row.rb
self.whitelisted_ransackable_attributes = %w[status row_number]
ImportRow#process! and #bulk_process! additionally clear validation_errors when a previously-failed row succeeds — today a stale error message survives a successful retry (process! never resets it).
One migration:
class AddImportIdStatusIndexToSpreeImportRows < ActiveRecord::Migration[7.2]
def change
# Powers the per-poll grouped status counts and the failed-rows listing
# without a full scan on 100k-row imports.
add_index :spree_import_rows, [:import_id, :status]
end
end
No changes to the state machine, jobs, events, or processors. In particular the import.progress event cadence (every 10 groups, large imports only) is irrelevant to the SPA — polling reads counters straight from the DB.
Admin API: routes
# spree/api/config/routes.rb — admin v3 namespace, next to exports
resources :imports, only: [:index, :show, :create, :destroy] do
collection do
get :template
end
member do
patch :complete_mapping
patch :retry_failed_rows
get :download
end
resources :rows, only: [:index], controller: 'import_rows'
end
GET :id/download streams the originally uploaded CSV — the audit trail for what was actually imported (same inline-streaming rationale as the exports download). The serializer exposes original_filename / original_byte_size / original_file_url, surfaced as a row action on the history page and a download button in the wizard header.
Admin API: ImportsController
Follows the shipped ExportsController closely (type resolution against the trusted registry, scope-limited index filtering, dynamic scoped_resource_name).
module Spree::Api::V3::Admin
class ImportsController < ResourceController
include ActiveStorage::SetCurrent
skip_scope_check! only: :index # index spans types; `scope` filters to writable ones
# POST /api/v3/admin/imports
# { type: 'Spree::Imports::Products', attachment: '<signed blob id>', preferred_delimiter: ',' }
# Saves, then advances into mapping (auto-assigns file columns), returns the
# mapping payload so the SPA can render the mapping step from this response.
def create
@resource = build_resource
authorize_resource!(@resource, :create)
if @resource.save
@resource.start_mapping!
render json: serialize_resource(@resource), status: :created
else
render_errors(@resource.errors)
end
end
# PATCH /api/v3/admin/imports/:id/complete_mapping
# { mappings: [{ schema_field: 'sku', file_column: 'SKU Code' }, ...] }
# Atomically applies the submitted mappings, then transitions to
# completed_mapping (which enqueues CreateRowsJob). 422 when required
# schema fields remain unmapped or a file column is double-assigned.
def complete_mapping
# update mappings in a transaction, keyed by schema_field;
# then: @resource.mapping_done? ? @resource.complete_mapping! : render_errors(...)
end
# PATCH /api/v3/admin/imports/:id/retry_failed_rows
# Re-dispatches processing over the rows still `failed` (the dispatcher's
# pending_and_failed scope picks them up). 422 unless the import is
# `completed` with failures. Named to avoid the `retry` Ruby keyword.
def retry_failed_rows
# @resource.retry_failed_rows! → serialize; invalid transition → 422
end
# GET /api/v3/admin/imports/template?type=Spree::Imports::Products
# text/csv header row built from the type's schema_fields (includes the
# store's metafield columns) — the "Download template" link in the dialog.
def template
# send_data headers_csv, filename: 'products_import_template.csv', type: 'text/csv'
end
protected
def model_class = Spree::Import
def serializer_class = Spree.api.admin_import_serializer
def scope_includes = [:user, :mappings]
# Every action on an import maps to the write scope of the imported
# resource — creating is a bulk write, and status/rows expose the
# uploaded data, so read-only keys get nothing.
def action_kind = 'write'
def scoped_resource_name
import_class&.required_scope || :all
end
def permitted_params
params.permit(:type, :attachment, :preferred_delimiter)
end
def build_resource
klass = resolve_import_type(permitted_params[:type]) || Spree::Import
klass.new(
permitted_params.except(:type).merge(owner: current_store, user: try_spree_current_user)
)
end
# Same trusted-registry constantize pattern as ExportsController#resolve_export_type.
end
end
Notes:
attachment=accepts the signed blob id natively (has_one_attached). The existing model validations (content typetext/csv, whitelistedtype) return as regular 422s.owneris polymorphic (multi-vendor extensions create Vendor-owned imports);for_storescopes the core Admin API to store-owned imports only — vendor dashboards overridescopein their own extension controllers.createrunsstart_mapping!synchronously — it reads the just-uploaded blob once to auto-assign columns, exactly as the legacy controller does.destroyis inherited; the model'scan_be_deleted?guard (above) makes the base controller render 422 while jobs may be running.- No
Spree::Api::V3::HttpCachingmodule — the show endpoint is a poll target and must always return fresh state (caching is opt-in per controller, so this means simply not including it).
Admin API: ImportRowsController
Nested index only — the failure report. Uses the standard set_parent machinery (parent lookup via the imports scope, so store isolation and scope gating come from the parent).
module Spree::Api::V3::Admin
class ImportRowsController < ResourceController
# belongs_to import; index only
# GET /api/v3/admin/imports/:import_id/rows?q[status_eq]=failed&sort=row_number
def model_class = Spree::ImportRow
def serializer_class = Spree.api.admin_import_row_serializer
end
end
Admin API: serializers
Per the serializer split rule, Admin extends the existing V3 (event) serializers; mappings get a fresh Admin serializer (they never appear in events or the Store API).
module Spree::Api::V3::Admin
class ImportSerializer < V3::ImportSerializer
# Always: everything the poll needs.
attributes :processing_errors, :preferred_delimiter
attribute(:completed_rows_count) { |import| import.rows_status_counts['completed'] || 0 }
attribute(:failed_rows_count) { |import| import.rows_status_counts['failed'] || 0 }
attribute(:schema_fields) { |import| import.schema_fields } # [{ name, label, required }]
many :mappings, serializer: 'Spree::Api::V3::Admin::ImportMappingSerializer'
# Mapping-state only: computing these downloads the attached blob, which a
# 2s processing poll must never do. `mapping?` guards both.
attribute(:csv_headers) { |import| import.csv_headers if import.mapping? }
attribute(:sample_row) { |import| import.mapping? ? first_data_row(import) : nil }
# first_data_row reads only the first CSV data line (CSV.foreach + first),
# never a full-file parse.
end
end
Admin::ImportRowSerializer < V3::ImportRowSerializer— addsdata(parsed row hash) so the failure table can show the offending CSV values. Base already carriesrow_number,status,validation_errors,item_type/item_id, timestamps.Admin::ImportMappingSerializer—id,schema_field,file_column,required(boolean). Thecomplete_mappingendpoint accepts exactly these names back (read/write symmetry).- Register
admin_import_serializer,admin_import_row_serializer,admin_import_mapping_serializerinSpree::Api::Dependencies.
The poll contract
GET /imports/:id drives the whole wizard; the SPA switches UI on status:
status |
SPA state | Notable payload |
|---|---|---|
mapping |
mapping step | mappings (auto-assigned), schema_fields, csv_headers, sample_row |
completed_mapping |
progress ("Preparing rows…", indeterminate) | rows are being created; rows_count still 0 |
processing |
progress bar | rows_count, completed_rows_count, failed_rows_count; indeterminate while rows_count == 0 |
completed |
results | final counters; failed rows via the rows endpoint; retry_failed_rows re-enters processing |
failed |
file-level error | processing_errors (e.g. malformed CSV from CreateRowsJob's discard_on) |
Terminal statuses (completed, failed) stop the poll. Because the wizard is a page (not a fire-and-forget toast like exports), there is no client-side timeout — leaving the page stops polling, returning resumes it.
Backend tests + type generation
- RSwag integration specs (
spree/api/spec/integration/api/v3/admin/imports_spec.rb): create with signed blob → 201 inmappingwith auto-assigned mappings;complete_mappinghappy path + 422 (required field unmapped); show during processing returns counters; rows index filtered bystatus_eq;retry_failed_rowshappy path + 422 (no failures / wrong status); destroy 422 whileprocessing; 401/403 paths; secret-key scope filtering (awrite_customers-only key sees no product imports). - Controller specs for the edge cases (unknown
typefalls back per registry, double-assignedfile_column422, template CSV includes metafield columns). - Full pipeline after serializer work:
typelizer:generate→generate:zod→ integration specs →rswag:specs:swaggerize(the lefthook pre-commit covers 1–2).
Admin SDK: client.imports
readonly imports = {
list, get, delete, // standard resource shapes
create: (params: ImportCreateParams) => ..., // { type, attachment: signedId, preferred_delimiter? }
completeMapping: (id: string, params: { mappings: ImportMappingParam[] }) =>
this.request<AdminImport>('PATCH', `/imports/${id}/complete_mapping`, { body: params }),
retryFailedRows: (id: string) =>
this.request<AdminImport>('PATCH', `/imports/${id}/retry_failed_rows`),
rows: {
list: (importId: string, params?: ListParams) => ..., // PaginatedResponse<AdminImportRow>
},
}
ImportType union mirrors the registry ('Spree::Imports::Products' | 'Spree::Imports::Customers' | 'Spree::Imports::ProductTranslations'). The template download is not an SDK method — like the export download, it's an authed fetch in the dashboard (the SDK layer is JSON-only). MSW tests + changeset.
Dashboard
ImportButton (packages/dashboard-core/src/components/import-button.tsx) — sits beside export-button.tsx, same toolbar slot. Props: { type: ImportType; subject: SubjectName; onCreated: (imp: AdminImport) => void } — dashboard-core must not know app routes or dialogs, so what happens after create is the app's callback (the index pages set the ?import= search param, which opens the wizard dialog). The button wraps itself in <Can I="create" a={subject}> (per-context gating — see Key Decisions) and opens a Sheet containing:
- CSV picker → the universal
FileUploadField(dashboard-core): dropzone + direct upload on pick + the attached file rendered as anAttachmentwith uploading state and a remove action.ImageUploadFieldis now a thin image preset of the same component (same props, so the logo/avatar/category call sites stayed drop-in), which answers "why two upload components" with: there's one. The import button passestransformFileto forcecontent_type: 'text/csv'— Windows browsers report.csvasapplication/vnd.ms-exceland the model validation rejects it.AttachmentandProgresswere ported intodashboard-uifrom the shadcn Base UI registry (cn-*preset classes flattened to plain utilities, matching the package's pre-CSS-layer style); the wizard's processing bar is theProgressprimitive withvalue={null}as the indeterminate "preparing" state. - Delimiter select (
,;|tab — the model'spreferred_delimiterpreference). - "Download template" link → authed fetch of
GET /imports/template?type=…, Blob-URL download (same helper approach asuse-export.ts). - Submit →
imports.create({ type, attachment: signedId, preferred_delimiter })→onCreated.
Hooks (packages/dashboard/src/hooks/use-imports.ts) — store-scoped query keys throughout:
const TERMINAL = new Set(['completed', 'failed'])
export function useImport(id: string) {
return useQuery({
queryKey: useResourceKey('imports', id),
queryFn: () => adminClient.imports.get(id),
refetchInterval: (query) =>
TERMINAL.has(query.state.data?.status ?? '') ? false : 2000,
})
}
Plus useImports() (history list), useImportRows(id, params) (5s refetchInterval while the parent import is non-terminal), useCreateImport(), useCompleteMapping(id), useDeleteImport().
Routes, dialog + nav:
routes/_authenticated/$storeId/settings/imports/index.tsx— history:ResourceTableoverclient.imports.list(number, type, status badge,completed/failed/totalcounts, created_at; row click sets?import=<id>, opening the wizard dialog in place). Registered inpackages/dashboard/src/nav/settings.tsunder a newauditsettings-nav group (settingsNav.addGroup({ key: 'audit', ... }), positioned afterteam), entry{ key: 'settings.imports', path: '/imports', group: 'audit' }— the group is the future home for exports history and audit logs.components/spree/imports/import-wizard-dialog.tsx— the wizard as a full-window dialog (bulk-price-editor shell:!inset-3edge-to-edgeDialogContent, custom header with type · number, status badge and an X close). Rendered by the products, customers and history pages, opened by their?import=search param, switching onstatusper the poll contract:- Mapping: step indicator (Map fields → Process → Done, mirroring the legacy wizard); a table of
schema_fieldsrows — label + required badge, a<Select>ofcsv_headers(+ "Not mapped", withitemsarray per the Base UI label rule), thesample_rowvalue as muted helper text. "Start import" disabled until every required field is mapped client-side; server 422s render as a banner. - Processing:
<Progress>bar from(completed + failed) / rows_count, counter copy ("1,240 of 5,000 rows processed · 12 failed"), indeterminate "Preparing rows…" whilerows_count == 0, and the failed-rows table streaming in below as failures appear. A retry pass is derivable (completed + failed ≈ rows_countwhileprocessing) — show "Retrying failed rows · N remaining" driven by the shrinkingfailed_rows_countinstead of the (already full) bar. - Results: success/partial summary (completed vs failed counts), paginated failed-rows table (row number, error message, expandable raw
data), a "Retry failed rows (N)" button whenfailed_rows_count > 0(callsretryFailedRows; status flips toprocessingand the poll resumes automatically), and an "Import another" back-link. File-levelfailedshowsprocessing_errorsprominently.
- Mapping: step indicator (Map fields → Process → Done, mirroring the legacy wizard); a table of
Wiring: inside the existing <ResourceTable actions={(ctx) => …}> render prop (ResourceActionsContext, packages/dashboard-core/src/components/resource-table.tsx) on the products index (type="Spree::Imports::Products" subject={Subject.Product}) and customers index (type="Spree::Imports::Customers" + the customer subject from the Subject map), next to the existing ExportButton. Unlike ExportButton, ImportButton ignores the context — imports don't consume filters. The Getting Started "Add products" task also offers it (a registered add_products slot body: manual CTA + "Import products from CSV"; the created import lands on the products page with the wizard open). Product translations import stays backend-only until the translations dashboard work (5.5-6.0-resource-translations-api.md) surfaces it.
i18n: dashboard-core keys under admin.components.import_button.*, app keys under admin.imports.* — added to all six locale files (en, de, fr, zh-CN, ar, pl) in both packages.
Frontend tests: Vitest for the pure logic the wizard hangs off (isImportActive — the poll's continue/stop predicate — and the import-types helpers); exports shipped with zero frontend coverage, don't repeat that. Plus a Playwright e2e spec driving the full wizard with an inline CSV — upload, auto-mapped columns with sample values, start, poll-driven progress, completion summary, failure report with raw row data, retry cycle, and the blocked-until-required-fields-mapped path. UI-only assertions per the testing conventions; Date.now() suffixes on imported record names. Note: the e2e Rails server pins ActiveJob to the :test adapter, so global-setup writes a guarded initializer into the generated dummy app switching it to :async (DASHBOARD_E2E=1 only, removed in teardown) — without it the pipeline never runs and the wizard sits at "Preparing rows…" forever.
Seller panel imports (2026-08-27)
A marketplace seller lists their catalog by CSV through the same pipeline, on
their own branch (/api/v3/seller/imports). The upload, the mapping step, the
row processors and the wizard are all the operator's — what differs is who
owns the result and how far a row can reach.
Products only. Customers belong to the marketplace and translations of
catalog copy are its merchandising, so the seller branch allowlists
Spree::Imports::Products and refuses the rest, matching the line the seller
products endpoint already draws around tags, categories and product types.
Imports and exports now carry the same tenancy pair (2026-08-27). An import
used to hold a polymorphic owner that was a Store or a Seller, never both,
so a seller's import had no store on it and the operator's store-scoped list
could not include it. An export already had store_id — plus a
belongs_to :seller whose column was never created, so filtering exports by
seller raised PG::UndefinedColumn.
Both tables now carry store_id (always present) and a nullable seller_id
(null = the operator's own), which fixes the export bug and gives operators
their sellers' imports for free: the base controller roots the admin index at
model_class.for_store(current_store), and for_store now comes from
SingleStoreResource. Import#owner survives as a deprecated reader through
6.1, and the serializer emits owner_type/owner_id from the new pair so
existing clients see the same answer.
Operators read seller rows; they do not act on them. A retry re-runs writes
into the seller's own catalog and nothing on the import would record that the
operator caused them, so retry_failed_rows and destroy refuse a
seller-owned import with a 422 while every read spans the store.
The import's ability is built against its owner. Import#current_ability
resolved roles against the store, and a seller's staff hold theirs on the
Spree::Seller — so a seller's ability compiled zero rules and every
accessible_by through it came back empty. That is invisible on a first
import (nothing to find) and breaks the second one: the row cannot see the
product it already created, tries to create it again, and fails on slug
uniqueness. Variant rows, which only ever look the product up, failed
outright. Passing resource: owner fixes both.
Two narrowings, both in the row processor. They cannot live in a controller: rows are processed in a background job, long after any request scope is gone.
- Ownership. A product created by a seller's import is stamped with that seller. Without it the rows would belong to the store — invisible in the seller's own panel and unattributable at commission time. It has to happen before the variants save, because SKU uniqueness is scoped to the variant's resolved seller (which is what lets two sellers list the same part number).
- Reach.
product_scopenarrows to the seller's own products. The ability cannot answer this — it grants capability, never tenancy, sowrite_productsreaches every product in the class. Without the narrowing a CSV naming another seller's slug would edit their listing.
A seller's CSV cannot extend the marketplace's vocabulary. The processor
creates records for values it does not recognise, which on a seller's import
would write into shared state: product_type (read-only for the seller
audience) is looked up but never created, tags are skipped entirely (they
are tenanted to the store, so a new one joins the marketplace's own
vocabulary), and category1..3 are skipped (the categories resource has no
seller audience at all). All three match what the seller products endpoint
already refuses.
Imported stock lands in the seller's own warehouse. set_stock falls back
to Variant#default_stock_location, which answers the store's — so an
inventory_count column would deposit a seller's goods in the marketplace's
location. The processor passes the seller's default location instead, falling
back to the store's when they have none.
Stock is per location, named in stock_location (amended 2026-10-06, see
decisions.md). A row's inventory_count and inventory_backorderable are the
shelf count and setting at one location: the one stock_location names, or the
owner's default when it is blank. The export writes the default location on
the full row and adds a stock-only row per further location holding stock,
modelled on the price-only rows for extra currencies. Names are matched without
regard to case. An operator's file covers the marketplace's locations and, for
a seller's product, that seller's too; on import a name on a seller's product
resolves to the seller's own location first, so the seller's wins when both
owners use the name — the rule cartons follow. A seller's file and import
cover only their own locations: unlike cartons, a seller never falls back to
the marketplace's, since they may pack into a marketplace carton but must never
set the marketplace's shelf. An unknown name fails the row before anything on
it is written.
The CSV's status column is ignored on a seller's import. A seller
reaches active only through review, so an uploaded status,active would
otherwise publish to the marketplace catalog with nobody having looked at it —
the same hole 6.0-seller-product-submission.md closed for the JSON endpoint.
Imported products land as draft and the seller submits each for review.
Spree::Import/Spree::ImportRow joined the products catalog resource.
An import is a bulk product write and nothing else, which is already why
write_<resource> is the key gating every import endpoint. Without the
subjects, a principal whose capability comes from catalog keys alone — every
seller — would pass the key gate on write_products and then be refused by
the authorize! immediately behind it. Operators are unaffected: the admin
role grants can :manage, :all and never consults the subject list.
The wizard moved into @spree/dashboard-core and reads its data through
the registered PanelApiClient, so both panels render one definition. Its one
route-bound piece — where "View records" goes — is an injected onViewRecords
prop, since the two panels file their catalogs under different route trees.
Constraints
- Never read the CSV
statuscolumn on a seller's import, and never add a path that lets an imported seller product reachactivewithoutProducts::Approve. - A new row processor that resolves existing records must narrow by
import.sellerwhen one is present.accessible_byis not a substitute — it answers capability, not tenancy. - A row processor that creates a record the CSV named must ask whether a seller may create it. Product types, tags and categories are the marketplace's; a new find-or-create in this file needs the same check, or a CSV becomes a way around what the seller endpoint refuses.
- A new import or export field goes on both models. They are the same kind of record and drifted once already; a tenancy or attribution field added to one and not the other is how that happens again.
- Never write
owner:on an import. It is a deprecated bridge kept for API clients — internal code assignsstore:andseller:. - Test a seller import with a user who holds their role on the seller. The
:product_importfactory defaultsuserto a store admin, whose blanket access hides every scoping bug in this file — which is exactly how the empty-ability bug above survived its first round of specs. - A new seller-reachable import type is added to the controller's
allowlist deliberately, never by widening it to
Spree::Import.available_types. - New import UI goes into
@spree/dashboard-core, taking its data by prop or through the registered client — neveradminClient, which a seller's panel has no credential for.
Migration Path
Single PR (decided 2026-07-10), in three internal layers:
- Backend — core additions (
for_store,can_be_deleted?,rows_status_counts,sample_row,required_scope,retry_failed_rowstransition,validation_errorsreset on successful reprocess, ImportRow ransack whitelist, composite index migration), API controllers + routes + Admin serializers + dependency registrations, RSwag/controller specs, typegen pipeline. - Admin SDK —
client.importsresource, param/response types, MSW tests, changeset. - SPA —
ImportButton(dashboard-core) + locales,use-importshooks,/settings/importsroutes +auditnav group, toolbar wiring on products/customers, Playwright spec.
Secret-key attribution note: Spree::Import requires a user (row processors resolve products through import.current_ability), so key-authenticated creates attribute to the key's created_by admin when present and 422 otherwise — JWT (dashboard) flows are unaffected.
Constraints on Current Work
- Do not introduce ActionCable/WebSockets/SSE into
packages/dashboardfor this or any single feature. If a genuine realtime need accumulates (notifications, collaborative editing), design a shared layer in its own plan first; import progress explicitly does not qualify. - New import types plug into the registry, not the UI. Adding one = Import subclass + schema + row processor +
Spree.import_typesentry (+ anImportTypeunion member). Never hardcode type-specific logic in the dashboard flow beyond button placement. - The SPA must never branch on
large_import_threshold. It's a backend processing knob; the UI contract is identical for 10 rows and 100k rows. - Read/write symmetry on mappings. The serializer exposes
schema_field/file_column;complete_mappingaccepts exactly those names. No client-side field translation. - The legacy
spree/adminimport wizard stays untouched — other surfaces still mount it. Changes to import behavior (new schema columns, processors) happen in core where both admins share them. - Poll endpoints stay cache-free. Never include
Spree::Api::V3::HttpCachingin imports controllers.
Open Questions
None — all resolved 2026-07-10:
- Status transport → polling only; no WebSocket/ActionCable/SSE.
- Retry failed rows → in scope for v1 (state-machine transition +
retry_failed_rowsendpoint + results-screen button; see Design Details). - Cancel a processing import → out of scope (requires cooperative job cancellation; destroy stays blocked mid-flight).
- Completion email →
out of scoperevised 2026-07-11: in scope.Spree::ImportMailer#import_done(subscriber onimport.completed, so retry passes email again) mirrorsexport_done, with the failed-rows count called out. The link mechanism is fully caller-provided — norespond_to?(:admin_*_url)probing in mailer views: every creating surface passes aresults_urlat create (the dashboard through the Admin API, validated against the store's allowed origins exactly like the password-resetredirect_urland silently dropped otherwise; the legacy Rails admin sets its own import page URL in its controller). It persists as an Import preference — the email fires at the end of an async multi-job pipeline (and again after retry passes), so the URL must be record state, not a threaded parameter. The mailer appends?import=<id>; no URL means no button.export_donewas migrated to the same contract (spree_exportsgained thepreferencescolumn; both legacy controllers and both v3 API controllers acceptresults_url). - Failed-rows CSV download → out of scope for now (retry + on-screen report cover the loop).
- Navigation → yes:
/settings/importsunder a newauditsettings-nav group (see Design Details). - Orders import type → skipped (registry has no
Spree::Imports::Orders; separate backend effort if ever). - XLSX → skipped; CSV only.
- Client-side gating → per-context resource ability (
<Can I="create" a="Spree::Product">), not a blanketSpree::Importsubject (see Key Decisions). - Zombie
processingimports (dead last worker never re-checks completion) → accepted as-is; worker restarts cover it in practice. No sweeper, no poll backoff.
References
- Legacy pipeline:
spree/core/app/models/spree/import.rb,import_row.rb,import_mapping.rb,import_schemas/,spree/core/app/jobs/spree/imports/,spree/core/app/services/spree/imports/row_processors/ - Legacy admin UI:
spree/admin/app/controllers/spree/admin/imports_controller.rb,.../import_mappings_controller.rb,.../import_rows_controller.rb,spree/admin/app/views/spree/admin/imports/,spree/admin/app/subscribers/spree/admin/import_subscriber.rb,import_row_subscriber.rb - Export precedent (architecture to mirror):
docs/plans/5.5-admin-spa-csv-export.md,spree/api/app/controllers/spree/api/v3/admin/exports_controller.rb,packages/dashboard-core/src/components/export-button.tsx,packages/dashboard-core/src/hooks/use-export.ts - Upload flow:
spree/api/app/controllers/spree/api/v3/admin/direct_uploads_controller.rb,packages/dashboard-core/src/hooks/use-direct-upload.ts - Event serializers (bases):
spree/api/app/serializers/spree/api/v3/import_serializer.rb,import_row_serializer.rb - Related plans:
6.0-admin-api.md(imports endpoint checklist §Imports),5.5-admin-api-key-scopes.md,5.5-6.0-resource-translations-api.md(Phase 2 CSV generalization)