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.

40.5 KB
Raw Blame

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::Import pipeline verbatim. No new models, jobs, state machine, or row processors. The legacy Spree::Admin::ImportsController and its Turbo Streams views stay in place untouched; the new endpoints live alongside under Spree::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 COUNT per watcher every 2s against counters that the pipeline already persists (rows_count, per-row status, 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 refetchInterval for push-triggered invalidation; the API contract does not change.
  • 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 paginated GET /imports/:id/rows?q[status_eq]=failed table (polled at ~5s while processing). Failures are the only actionable rows; a live scroll of successes is noise. large_import_threshold remains 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 a sample_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 /imports accepts attachment: <signed_id> — no multipart on the JSON API. (This refines the multipart/form-data note next to the imports checklist in 6.0-admin-api.md.)

  • Secret-key gating: an import is a bulk write. Mirror Spree::Export.required_scope with Spree::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 standalone write_imports scope, 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 webhooks delivery param), so it deep-links and survives refresh; closing mid-processing is safe — the import continues server-side. The /settings/imports history page (new audit settings-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_failed rows 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}> where subject is the imported resource (Spree::Product on the products page) — mirroring the server's write_<resource> scope model. No blanket Spree::Import subject in the dashboard Subject map. Backend enforcement is unchanged and remains authoritative.

  • Universal by registry. Everything is driven by Spree.import_types and Import#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 type text/csv, whitelisted type) return as regular 422s.
  • owner is polymorphic (multi-vendor extensions create Vendor-owned imports); for_store scopes the core Admin API to store-owned imports only — vendor dashboards override scope in their own extension controllers.
  • create runs start_mapping! synchronously — it reads the just-uploaded blob once to auto-assign columns, exactly as the legacy controller does.
  • destroy is inherited; the model's can_be_deleted? guard (above) makes the base controller render 422 while jobs may be running.
  • No Spree::Api::V3::HttpCaching module — 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 — adds data (parsed row hash) so the failure table can show the offending CSV values. Base already carries row_number, status, validation_errors, item_type/item_id, timestamps.
  • Admin::ImportMappingSerializer — id, schema_field, file_column, required (boolean). The complete_mapping endpoint accepts exactly these names back (read/write symmetry).
  • Register admin_import_serializer, admin_import_row_serializer, admin_import_mapping_serializer in Spree::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 in mapping with auto-assigned mappings; complete_mapping happy path + 422 (required field unmapped); show during processing returns counters; rows index filtered by status_eq; retry_failed_rows happy path + 422 (no failures / wrong status); destroy 422 while processing; 401/403 paths; secret-key scope filtering (a write_customers-only key sees no product imports).
  • Controller specs for the edge cases (unknown type falls back per registry, double-assigned file_column 422, 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 an Attachment with uploading state and a remove action. ImageUploadField is 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 passes transformFile to force content_type: 'text/csv' — Windows browsers report .csv as application/vnd.ms-excel and the model validation rejects it. Attachment and Progress were ported into dashboard-ui from 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 the Progress primitive with value={null} as the indeterminate "preparing" state.
  • Delimiter select (, ; | tab — the model's preferred_delimiter preference).
  • "Download template" link → authed fetch of GET /imports/template?type=…, Blob-URL download (same helper approach as use-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: ResourceTable over client.imports.list (number, type, status badge, completed/failed/total counts, created_at; row click sets ?import=<id>, opening the wizard dialog in place). Registered in packages/dashboard/src/nav/settings.ts under a new audit settings-nav group (settingsNav.addGroup({ key: 'audit', ... }), positioned after team), 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-3 edge-to-edge DialogContent, 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 on status per the poll contract:
    • Mapping: step indicator (Map fields → Process → Done, mirroring the legacy wizard); a table of schema_fields rows — label + required badge, a <Select> of csv_headers (+ "Not mapped", with items array per the Base UI label rule), the sample_row value 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…" while rows_count == 0, and the failed-rows table streaming in below as failures appear. A retry pass is derivable (completed + failed ≈ rows_count while processing) — show "Retrying failed rows · N remaining" driven by the shrinking failed_rows_count instead 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 when failed_rows_count > 0 (calls retryFailedRows; status flips to processing and the poll resumes automatically), and an "Import another" back-link. File-level failed shows processing_errors prominently.

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_scope narrows to the seller's own products. The ability cannot answer this — it grants capability, never tenancy, so write_products reaches 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 status column on a seller's import, and never add a path that lets an imported seller product reach active without Products::Approve.
  • A new row processor that resolves existing records must narrow by import.seller when one is present. accessible_by is 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 assigns store: and seller:.
  • Test a seller import with a user who holds their role on the seller. The :product_import factory defaults user to 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 — never adminClient, which a seller's panel has no credential for.

Migration Path

Single PR (decided 2026-07-10), in three internal layers:

  1. Backend — core additions (for_store, can_be_deleted?, rows_status_counts, sample_row, required_scope, retry_failed_rows transition, validation_errors reset on successful reprocess, ImportRow ransack whitelist, composite index migration), API controllers + routes + Admin serializers + dependency registrations, RSwag/controller specs, typegen pipeline.
  2. Admin SDK — client.imports resource, param/response types, MSW tests, changeset.
  3. SPA — ImportButton (dashboard-core) + locales, use-imports hooks, /settings/imports routes + audit nav 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/dashboard for 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_types entry (+ an ImportType union 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_mapping accepts exactly those names. No client-side field translation.
  • The legacy spree/admin import 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::HttpCaching in 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_rows endpoint + 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 scope revised 2026-07-11: in scope. Spree::ImportMailer#import_done (subscriber on import.completed, so retry passes email again) mirrors export_done, with the failed-rows count called out. The link mechanism is fully caller-provided — no respond_to?(:admin_*_url) probing in mailer views: every creating surface passes a results_url at create (the dashboard through the Admin API, validated against the store's allowed origins exactly like the password-reset redirect_url and 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_done was migrated to the same contract (spree_exports gained the preferences column; both legacy controllers and both v3 API controllers accept results_url).
  • Failed-rows CSV download → out of scope for now (retry + on-screen report cover the loop).
  • Navigation → yes: /settings/imports under a new audit settings-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 blanket Spree::Import subject (see Key Decisions).
  • Zombie processing imports (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)