Bump version to 0.21.0

CHANGELOG.md

@@ -4,6 +4,106 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.21.0] - 2026-09-25
+
+### Added
+- `Modules\Core\File` — a generic, storage-backend-agnostic file registry: `Models\File` (a
+  `files` table row per stored file — disk, path, original name, mime, size, a `purpose` tag,
+  and a nullable polymorphic owner), `Services\FileService` (store/retrieve/download/exists/
+  delete/list/`pruneUnowned`, delegating every actual byte-level operation to a
+  `Contracts\FileAdapterInterface` resolved per disk — `Adapters\LocalFileAdapter` today, the
+  same contextual-binding pattern `Shipping\Contracts\CarrierFulfillmentInterface` already uses
+  per carrier, so a future `S3FileAdapter` is one class and one more match arm, nothing else
+  changes), and `Http\Controllers\DownloadFileController` — a signed-URL-only route
+  (`files.download`) any consuming app can mint a link to, serving either inline (a preview) or
+  as a forced download (`?download=1`).
+- `Modules\Core\File\Http\Controllers\UploadFileController` — an abstract base for "accept an
+  upload, validate it, store it via `FileService`, return its id" endpoints. Which
+  extensions/sizes are acceptable is deliberately left to a concrete subclass's own
+  `purpose()`/`validationRules()` overrides (ordinary server-side PHP, never trusting anything
+  the request itself claims about its own limits) — a real policy decision that can differ per
+  site and even per product/field, not something a shared base class or config file could
+  express safely.
+- `boboko:file:prune-unowned {purpose}` — deletes every unowned `File` of a given purpose past
+  its grace period (`--hours`, default 24). Generic: any consuming app schedules it once per
+  purpose string it stores files under.
+- `Modules\Core\Cart\Events\CartLineAdded`/`Checkout\Events\OrderPlaced` listeners
+  (`File\Listeners\AttachCustomFieldFileToCartLine`/`TransferCustomFieldFileOwnership`) that
+  re-point a `File`'s ownership from unowned → the real `CartLine` once one exists, then from
+  that `CartLine` → the `OrderLine` an order is placed with — so a File referenced by a product
+  custom field survives the cart it originated from being cleared, without ever being copied.
+
+### Changed
+- The admin order-lines table's collapsible details dropdown (next to the existing price
+  breakdown) now shows a product's custom-field answers (`OrderLine.meta.custom_fields`) — a
+  bordered table matching the existing price-breakdown one, with a thumbnail preview and a
+  download-icon link for a file answer, resolved through `File\Services\FileService`'s signed
+  route. Previously never shown anywhere in the admin.
+- 3dealer's product custom-field photo upload (`CustomFieldUploadController`), cart line meta
+  (`CartController::customFieldsMeta()`), and pruning (formerly its own `PruneCustomFieldUploads`
+  command) now go through `Modules\Core\File` instead of a bespoke `Crypt::encryptString({disk,
+  path, name, mime})` reference scheme — a cart/order line's file answer is now just a `File`
+  row's `file_id`, with `File` as the single source of truth for every other detail.
+
+## [0.20.2] - 2026-09-25
+
+### Changed
+- Product custom fields (`Product::$custom_fields`) moved off the main product edit form onto
+  their own "Custom Fields" sub-page (`Modules\Core\Catalog\Filament\Pages\
+  ManageProductCustomFields`), alongside "Reviews" — the same admin pattern, registered from the
+  same `Review\Filament\Extensions\ProductResourceExtension` (CorePlugin only allows one
+  extension class per Lunar resource, and Review's already owns this one).
+- Each custom field's `label` and new `help_text` are now translatable per storefront language
+  (`{locale: string}`, e.g. `{en: "...", el: "..."}`) instead of a single plain string — entered
+  as a plain `TextInput` per configured language rather than Lunar's `TranslatedText` form
+  component, which turned out to only resolve its state path correctly as a top-level form
+  field, not nested inside a `Repeater` item (every value silently failed to save under that
+  combination). `help_text` is optional and, unlike `label`, shown only on the product page, not
+  the cart or checkout.
+- `Modules\Core\Catalog\Support\ProductDocumentLocalizer::withLocalizedFields()` now also
+  resolves each `custom_fields` item's `label`/`help_text` to a single string for the current
+  locale (falling back to the store's default language), the same `filled()`-over-`??` way as
+  every other translated field — the storefront and cart still only ever see one resolved
+  string per field, unaware the admin-side value became translatable. A product's custom fields
+  saved before this change (plain string `label`, no `help_text`) still resolve correctly.
+
+## [0.20.1] - 2026-09-24
+
+### Fixed
+- `Modules\Core\Catalog\Support\ProductDocumentLocalizer::withLocalizedFields()` — a translated
+  attribute (name, description, ...) saved blank for the current locale kept the empty string
+  instead of falling back to the store's default language, since `??` only falls back on a
+  missing/null key, not an empty one. A product with no English copy yet showed a blank
+  title/description on `/en/` instead of its Greek content.
+- `Modules\Core\Command\WipeCatalogCommand` — now also deletes every `CartLine` referencing a
+  `product_variant` purchasable as part of the wipe (line items only, `Cart` records themselves
+  are left alone). Previously, any cart still holding a line for a wiped variant crashed the
+  entire storefront on every page load (`PricingManager::for()` throws when the variant a line
+  points at no longer exists) until those dangling lines were removed by hand.
+- `Modules\Core\Command\MigrateImportCommand` now asks which language a Shopify export file's
+  own text is written in before importing, instead of silently assuming it matches the store's
+  default language — the two are independent facts, and a mismatch used to save every imported
+  product's name/description under the wrong language. Backing class renamed `DefaultLocale` →
+  `Modules\Core\MigrateImport\Services\ImportLocale` to stop implying that assumption.
+
+### Changed
+- `Modules\Core\MigrateImport` reorganized to match every other module's layout
+  (`Contracts/`, `DTOs/`, `Jobs/`, `Models/`, `Services/`) instead of loose files at each
+  namespace root — no behavior change, but every `use` of `Importer`, `ImportSpec`,
+  `ImporterFactory`, `ImportLocale`, `RunMigrateImportJob`, `ShopifyExportImporter`,
+  `ShopifyCsvReader`, `ProductGroup`, `JudgeMeExportImporter`, and `JudgeMeCsvReader` moved to
+  its new namespace.
+- `Modules\Core\MigrateImport\Shopify\Services\ShopifyExportImporter::import()` now dispatches
+  one `Jobs\ImportShopifyProductJob` per product (via `Bus::batch()`) instead of importing every
+  product inline in a single queued job. A large export's variants, resolvers, and media
+  downloads accumulating in one long-lived process routinely exceeded `queue:work`'s
+  `--memory` limit; the worker died mid-run, the container restarted, and the entire import
+  started over from the first row every time, never actually finishing. Splitting into one job
+  per product resets memory between products, and a restart now only repeats whichever single
+  product was in flight. `Modules\Core\Catalog\Services\SkuBackfillService::backfill()` moved
+  from running right after the import loop to the batch's `then()` callback, since it must wait
+  for every product job to finish rather than firing the moment jobs are merely queued.
+
 ## [0.20.0] - 2026-09-23
 
 ### Added

composer.json

@@ -2,7 +2,7 @@
   "name": "boboko/core",
   "description": "Core module — authentication and shared panel behaviour",
   "type": "library",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "autoload": {
     "psr-4": {
       "Modules\\Core\\": "src/"
@@ -43,6 +43,7 @@
         "Modules\\Core\\Providers\\CatalogServiceProvider",
         "Modules\\Core\\Providers\\CartServiceProvider",
         "Modules\\Core\\Providers\\ReviewServiceProvider",
+        "Modules\\Core\\Providers\\FileServiceProvider",
         "Modules\\Core\\Providers\\ShippingServiceProvider",
         "Modules\\Core\\Providers\\OrderServiceProvider",
         "Modules\\Core\\Providers\\PrivacyServiceProvider"

database/migrations/2026_09_25_000001_create_files_table.php

@@ -0,0 +1,50 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * A generic, storage-backend-agnostic file registry — Modules\Core\File\
+ * Services\FileService's own backing table. `disk`/`path` are whatever
+ * Laravel's Storage facade already understands (local, s3, ...); this
+ * table adds what Flysystem itself has no concept of: who a file
+ * belongs to, why it was uploaded, and whether anything still needs it.
+ *
+ * `owner_type`/`owner_id` are nullable — a file can (and, for a product
+ * custom-field photo, always does) exist before anything owns it yet: a
+ * shopper picks a photo on the product page and it's uploaded immediately
+ * (see 3dealer's CustomFieldUploadController), well before add-to-cart
+ * gives it a CartLine to belong to. FileService::attachOwner() re-points
+ * these columns once an owner exists, rather than creating a second row
+ * for the same physical file.
+ *
+ * `purpose` (e.g. 'custom-field-upload') lets one table serve unrelated
+ * future features without collision — FileService itself has no
+ * knowledge of what a purpose means, callers scope their own queries by
+ * it.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('files', function (Blueprint $table) {
+            $table->id();
+            $table->string('disk');
+            $table->string('path');
+            $table->string('original_name')->nullable();
+            $table->string('mime')->nullable();
+            $table->unsignedBigInteger('size')->nullable();
+            $table->string('purpose');
+            $table->nullableMorphs('owner');
+            $table->timestamps();
+
+            $table->index(['purpose', 'owner_type', 'owner_id']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('files');
+    }
+};

src/Catalog/Filament/Pages/ManageProductCustomFields.php

@@ -0,0 +1,162 @@
+<?php
+
+namespace Modules\Core\Catalog\Filament\Pages;
+
+use Filament\Forms\Components\Repeater;
+use Filament\Forms\Components\Select;
+use Filament\Forms\Components\TextInput;
+use Filament\Forms\Components\Toggle;
+use Filament\Schemas\Components\Group;
+use Filament\Schemas\Components\Section;
+use Filament\Schemas\Schema;
+use Illuminate\Support\Str;
+use Lunar\Admin\Filament\Resources\ProductResource;
+use Lunar\Admin\Support\Pages\BaseEditRecord;
+use Lunar\Models\Language;
+
+/**
+ * Own sub-page for Product::$custom_fields (see that column's own docblock
+ * on Modules\Core\Catalog\Models\Product) — used to be a collapsible
+ * Section inline on the main product edit form (Review\Filament\
+ * Extensions\ProductResourceExtension::extendForm()), moved out to match
+ * how Reviews already gets its own sub-page (ManageProductReviews) rather
+ * than crowding the main form with a second unrelated concern.
+ *
+ * Deliberately no ->statePath('') override, no custom mount()/
+ * handleRecordUpdate() — EditRecord::mount() already fills the form from
+ * $record->attributesToArray() (which includes custom_fields, a real cast
+ * + fillable column) onto the default 'data' statePath, and save() reads
+ * it straight back off via $this->form->getState(). An earlier version of
+ * this page used ->statePath('') to bind the repeater directly to the
+ * record's attributes (copying ManageProductPricing) — that repointed the
+ * Repeater at $this->data['custom_fields'] AS THE ROOT state path itself,
+ * so every "add item" click re-filled the whole form from the record's
+ * still-unsaved value and immediately discarded the new row before it
+ * ever reached the page. Reverting to the plain default form/statePath is
+ * both simpler and is what actually works — same as the original inline
+ * repeater on the main product form did before this became its own page.
+ *
+ * Registered from Review\Filament\Extensions\ProductResourceExtension, not
+ * here — CorePlugin only allows one extension class per Lunar resource,
+ * and Review's already owns ProductResource's extension slot (see that
+ * class's own docblock).
+ *
+ * `label`/`help_text` are each stored as {locale: string} (e.g. {en: "...",
+ * el: "..."}) — see translatedField()'s own docblock for why that's a
+ * hand-rolled TextInput per language rather than Lunar's TranslatedText
+ * component. A product saved before this change still has a plain string
+ * `label` and no `help_text` at all; itemLabel() below tolerates both
+ * shapes, and the storefront/cart resolve either shape the same way (see
+ * product-custom-fields.blade.php and CartController::
+ * customFieldsMeta()). `key`/`type`/`required` stay plain, single values —
+ * only shopper-facing copy needs a translation, not the field's own
+ * machine-facing configuration.
+ */
+class ManageProductCustomFields extends BaseEditRecord
+{
+    protected static string $resource = ProductResource::class;
+
+    public static function getNavigationIcon(): ?string
+    {
+        return 'heroicon-o-adjustments-horizontal';
+    }
+
+    public function getTitle(): string
+    {
+        return 'Custom Fields';
+    }
+
+    public static function getNavigationLabel(): string
+    {
+        return 'Custom Fields';
+    }
+
+    /**
+     * Without this, Filament's EditRecord defaults to every relation
+     * manager the WHOLE ProductResource defines (see HasRelationManagers::
+     * getAllRelationManagers(), which reads ProductResource::getRelations()
+     * regardless of which sub-page is rendering) — Channels, Customer
+     * Groups, Media, Pricing tabs all bleeding onto this page alongside the
+     * repeater below. This page has no relations of its own.
+     */
+    public function getRelationManagers(): array
+    {
+        return [];
+    }
+
+    /**
+     * A plain TextInput per configured language, named "{$field}.{locale}"
+     * so it resolves to a normal nested array under the repeater item
+     * (custom_fields.{item}.label.en, .label.el, ...) — NOT Lunar's
+     * TranslatedText component. That component's per-locale sub-fields
+     * set their own statePath to just the locale code itself
+     * (TranslatedText::prepareTranslateLocaleComponent()), which only
+     * resolves correctly when TranslatedText is used as a single
+     * top-level named field directly on a form's root state (exactly how
+     * every existing usage in this codebase uses it — Lunar's own
+     * product name/description). Nested inside a Repeater item here, that
+     * same statePath resolution silently failed to nest under the item's
+     * own label/help_text key at all, and every typed value was lost on
+     * save. Hand-rolling the per-locale inputs sidesteps that assumption
+     * entirely.
+     */
+    private function translatedField(string $field, string $label, string $helperText, bool $required): Group
+    {
+        $languages = Language::orderBy('default', 'desc')->get(['code', 'name', 'default']);
+
+        return Group::make(
+            $languages->map(fn (Language $language, int $index) => TextInput::make("{$field}.{$language->code}")
+                ->label($index === 0 ? $label : null)
+                ->hiddenLabel($index !== 0)
+                ->helperText($index === 0 ? $helperText : null)
+                ->prefix(Str::upper($language->code))
+                ->required($required && $language->default))->values()->all(),
+        )
+            ->columnSpanFull();
+    }
+
+    public function form(Schema $schema): Schema
+    {
+        return $schema
+            ->components([
+                Section::make('Custom Fields')
+                    ->description('Extra input the shopper fills in on this product\'s page before adding it to their cart — a reference photo, personalization text, etc.')
+                    ->schema([
+                        Repeater::make('custom_fields')
+                            ->hiddenLabel()
+                            ->schema([
+                                $this->translatedField('label', 'Label', 'Shown to the shopper above the field. Only the current storefront locale is shown on the cart and checkout.', required: true),
+                                $this->translatedField('help_text', 'Help text', 'Optional — shown under the label on the product page only, not on the cart or checkout.', required: false),
+                                Select::make('type')
+                                    ->label('Field type')
+                                    ->options([
+                                        'text' => 'Short text',
+                                        'textarea' => 'Long text',
+                                        'file' => 'File upload',
+                                    ])
+                                    ->default('text')
+                                    ->native(false)
+                                    ->live()
+                                    ->required(),
+                                TextInput::make('key')
+                                    ->label('Key')
+                                    ->helperText('Machine-facing identifier — stored on the order/cart line, used to look up this answer elsewhere. Cannot be changed once orders reference it.')
+                                    ->required()
+                                    ->alphaDash()
+                                    ->maxLength(64),
+                                Toggle::make('required')
+                                    ->label('Required')
+                                    ->helperText('Shopper cannot add this product to their cart without answering.')
+                                    ->default(false),
+                            ])
+                            ->columns(2)
+                            ->addActionLabel('Add a custom field')
+                            ->reorderable()
+                            ->collapsible()
+                            ->itemLabel(fn (array $state): ?string => is_array($state['label'] ?? null)
+                                ? collect($state['label'])->first(fn ($value) => filled($value))
+                                : ($state['label'] ?? null)),
+                    ]),
+            ]);
+    }
+}

src/Catalog/Services/SkuBackfillService.php

@@ -8,15 +8,16 @@ use Lunar\Models\ProductVariant;
  * Generates a SKU for every ProductVariant missing one — extracted out of
  * Command\BackfillMissingSkusCommand (which becomes a thin CLI wrapper
  * around this, keeping --dry-run/progress-bar concerns out of the
- * reusable logic) so MigrateImport\RunMigrateImportJob can also call it
- * directly, right after a Shopify import, with no CLI concerns at all.
+ * reusable logic) so MigrateImport\Shopify\Services\ShopifyExportImporter can
+ * also call it directly, once every product job in its import batch has
+ * finished (see that class's own import()), with no CLI concerns at all.
  *
  * Format is "SKU-P{product_id}-V{variant_id}": deterministic and
  * guaranteed unique without a uniqueness check, since product_id/
  * variant_id already are. Only variants with a null `sku` are touched —
  * not an importer bug when one shows up after a Shopify import, the
  * source CSV rows genuinely had no `Variant SKU` value (see
- * MigrateImport\Shopify\ShopifyExportImporter).
+ * MigrateImport\Shopify\Services\ShopifyExportImporter).
  */
 class SkuBackfillService
 {

src/Catalog/Support/ProductDocumentLocalizer.php

@@ -51,16 +51,62 @@ class ProductDocumentLocalizer
         $availableLocales = $this->languages->availableLocales();
 
         foreach ($this->translatedAttributeHandles() as $handle) {
-            $product[$handle] = $product[$handle.'_'.$locale] ?? $product[$handle.'_'.$fallbackLocale] ?? null;
+            // filled(), not ?? - a translated attribute saved blank for
+            // the current locale still has that {handle}_{locale} key in
+            // the document, just set to '' rather than absent. ?? only
+            // falls back on a missing/null key, so it kept the empty
+            // string instead of falling through to a locale that actually
+            // has content.
+            $product[$handle] = filled($product[$handle.'_'.$locale] ?? null)
+                ? $product[$handle.'_'.$locale]
+                : ($product[$handle.'_'.$fallbackLocale] ?? null);
 
             foreach ($availableLocales as $availableLocale) {
                 unset($product[$handle.'_'.$availableLocale]);
             }
         }
 
+        if (! empty($product['custom_fields'])) {
+            $product['custom_fields'] = $this->localizeCustomFields($product['custom_fields'], $locale, $fallbackLocale);
+        }
+
         return $product;
     }
 
+    /**
+     * Product::$custom_fields isn't an AttributeManifest attribute (it's a
+     * plain JSON column, see Catalog\Models\Product's own docblock), so it
+     * never goes through the {handle}_{locale} explosion above — the
+     * indexer copies it straight through (see ProductIndexer), meaning
+     * each item's `label`/`help_text` still arrives here as a raw
+     * {locale: string} object (or, for a product saved before those
+     * became translatable, a plain string). Resolved the same filled()-
+     * over-?? way as every other translated field above, to the same
+     * single current-locale string the storefront/cart already expect
+     * (see product-custom-fields.blade.php and CartController::
+     * customFieldsMeta()) — a repeater item has no other reason to reach
+     * the storefront untouched.
+     *
+     * @param  array<int, array<string, mixed>>  $fields
+     * @return array<int, array<string, mixed>>
+     */
+    private function localizeCustomFields(array $fields, string $locale, ?string $fallbackLocale): array
+    {
+        return array_map(function (array $field) use ($locale, $fallbackLocale) {
+            foreach (['label', 'help_text'] as $key) {
+                if (! is_array($field[$key] ?? null)) {
+                    continue;
+                }
+
+                $field[$key] = filled($field[$key][$locale] ?? null)
+                    ? $field[$key][$locale]
+                    : ($field[$key][$fallbackLocale] ?? null);
+            }
+
+            return $field;
+        }, $fields);
+    }
+
     /**
      * For the Meilisearch driver, Scout's paginateRaw() puts the whole raw response
      * (hits, query, processingTimeMs, ...) in items(), not a plain list of hits - the

src/Command/BackfillMissingSkusCommand.php

@@ -10,7 +10,7 @@ use Modules\Core\Catalog\Services\SkuBackfillService;
  * CLI wrapper (--dry-run, a progress bar) around Catalog\Services\
  * SkuBackfillService — see that class's own docblock for the actual
  * backfill logic, also called automatically after a Shopify import (see
- * MigrateImport\RunMigrateImportJob).
+ * MigrateImport\Jobs\RunMigrateImportJob).
  */
 class BackfillMissingSkusCommand extends Command
 {

src/Command/MigrateImportCommand.php

@@ -3,8 +3,9 @@
 namespace Modules\Core\Command;
 
 use Illuminate\Console\Command;
-use Modules\Core\MigrateImport\ImportSpec;
-use Modules\Core\MigrateImport\RunMigrateImportJob;
+use Lunar\Models\Language;
+use Modules\Core\MigrateImport\DTOs\ImportSpec;
+use Modules\Core\MigrateImport\Jobs\RunMigrateImportJob;
 
 class MigrateImportCommand extends Command
 {
@@ -62,11 +63,29 @@ class MigrateImportCommand extends Command
             $credentials = null;
         }
 
+        // Shopify's own product export is a flat CSV — one Title/Body
+        // (HTML)/etc. column per row, no per-locale columns at all — so
+        // its text is necessarily written in exactly one language, and
+        // there is no reliable way to detect which one from the file
+        // itself. Modules\Core\MigrateImport\Services\ImportLocale::code() used to
+        // (as its former name, DefaultLocale, admits) assume it always
+        // matched this store's own Lunar\Models\
+        // Language::getDefault(), which is often wrong (a store's default
+        // admin/storefront language and the language a given export
+        // happens to be written in are two independent facts) — every
+        // imported product's name/description then saved silently under
+        // the wrong language, invisible unless that language happened to
+        // also be selected when viewing/editing the product afterward.
+        $locale = $source === 'shopify' && $type === 'export'
+            ? $this->askImportLocale()
+            : null;
+
         $spec = new ImportSpec(
             source: $source,
             type: $type,
             filePath: $filePath,
             credentials: $credentials,
+            locale: $locale,
         );
 
         RunMigrateImportJob::dispatch($spec);
@@ -74,6 +93,26 @@ class MigrateImportCommand extends Command
         $this->info('Import queued.');
     }
 
+    /**
+     * Choices come from Language::all() — the same list an admin manages
+     * from the Filament panel (Settings > Languages) — not a hardcoded
+     * set, so a language this store doesn't have yet simply isn't
+     * offered here; the hint below says where to add it instead of this
+     * command silently accepting an arbitrary code Lunar has no row for.
+     */
+    private function askImportLocale(): string
+    {
+        $languages = Language::orderBy('default', 'desc')->get(['code', 'name']);
+
+        return $this->choice(
+            "Which language is the export file's own text (product titles, descriptions, etc.) written in?\n".
+            '  (Not necessarily this store\'s default language — the two are independent. '.
+            "If the language you need isn't listed, add it first from the admin panel under Languages.)",
+            $languages->mapWithKeys(fn (Language $language) => [$language->code => "{$language->name} ({$language->code})"])->all(),
+            $languages->first()?->code,
+        );
+    }
+
     // Answers are relative to storage/app/private/imports (e.g. "shopify" or
     // "shopify/products_export.csv"); absolute paths are used as-is. A
     // directory answer picks the first CSV file found inside it.

src/Command/WipeCatalogCommand.php

@@ -3,6 +3,7 @@
 namespace Modules\Core\Command;
 
 use Illuminate\Console\Command;
+use Lunar\Models\CartLine;
 use Lunar\Models\Product;
 use Modules\Core\Auth\Models\Staff;
 use Modules\Core\Auth\Services\OtpService;
@@ -15,9 +16,10 @@ use function Laravel\Prompts\text;
  * Irreversibly deletes every Product and everything that only exists
  * because of a product — variants, variant prices, product-option value
  * assignments, product images/media, product associations, the
- * ImportMapping rows tying them back to an external source, and the
- * Meilisearch product index. Deliberately does NOT touch catalog
- * STRUCTURE other products could still reference: ProductOption/
+ * ImportMapping rows tying them back to an external source, product-
+ * variant CartLine rows (line items only — Cart records themselves are
+ * left alone), and the Meilisearch product index. Deliberately does NOT
+ * touch catalog STRUCTURE other products could still reference: ProductOption/
  * ProductOptionValue definitions ("Size", "Color" as reusable option
  * types), Brands, Collections, Tags, Customer Groups — none of those are
  * products, they're config a merchant would otherwise have to rebuild
@@ -140,7 +142,7 @@ class WipeCatalogCommand extends Command
      * for the skipped products) whose 'image' ImportMapping rows then
      * caused a LATER Shopify re-import to silently reuse those now-
      * orphaned Media objects instead of importing fresh ones — see
-     * MigrateImport\Shopify\ShopifyExportImporter::resolveOrImportImage()'s
+     * MigrateImport\Shopify\Services\ShopifyExportImporter::resolveOrImportImage()'s
      * own docblock for that half of the same incident. Always re-querying
      * the first N remaining rows (never advancing an id cursor) guarantees
      * every product is actually visited exactly once, however many are
@@ -150,6 +152,18 @@ class WipeCatalogCommand extends Command
     {
         ImportMapping::whereIn('source_type', ['product', 'variant', 'image'])->delete();
 
+        // Only the line items — not the parent Cart rows. This command is
+        // meant for early-stage/setup use where no real customer carts
+        // matter yet, but a customer's Cart record also anchors their
+        // session/coupon/address state; deleting it outright is more than
+        // "the catalog is gone" calls for. Leaving every variant a cart
+        // line could reference about to be force-deleted below would
+        // otherwise reproduce the exact storefront crash this step exists
+        // to prevent: CartLine::purchasable() resolves to null,
+        // PricingManager::for() throws a TypeError on every page load that
+        // renders the cart drawer.
+        CartLine::where('purchasable_type', 'product_variant')->delete();
+
         while (true) {
             // withTrashed(): Product/ProductVariant both use SoftDeletes
             // — a plain query would stop seeing a product the moment

src/File/Adapters/LocalFileAdapter.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Modules\Core\File\Adapters;
+
+use Illuminate\Contracts\Filesystem\Filesystem;
+use Illuminate\Http\UploadedFile;
+use Modules\Core\File\Contracts\FileAdapterInterface;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+/**
+ * Wraps Laravel's own 'local' Storage disk — see FileAdapterInterface's
+ * own docblock for why this exists as a named adapter rather than every
+ * caller reaching for Storage::disk('local') directly: swapping to a
+ * different backend later (S3FileAdapter, say) means adding one class and
+ * one contextual-binding entry, touching nothing that already uses
+ * FileService.
+ */
+class LocalFileAdapter implements FileAdapterInterface
+{
+    public function __construct(
+        private readonly Filesystem $disk,
+    ) {}
+
+    public function store(UploadedFile $file, string $directory): string
+    {
+        return $this->disk->putFile($directory, $file);
+    }
+
+    public function exists(string $path): bool
+    {
+        return $this->disk->exists($path);
+    }
+
+    public function delete(string $path): void
+    {
+        $this->disk->delete($path);
+    }
+
+    public function retrieve(string $path, ?string $name = null): StreamedResponse
+    {
+        return $this->disk->response($path, $name);
+    }
+
+    public function download(string $path, ?string $name = null): StreamedResponse
+    {
+        return $this->disk->download($path, $name);
+    }
+}

src/File/Commands/PruneUnownedFilesCommand.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Modules\Core\File\Commands;
+
+use Illuminate\Console\Command;
+use Modules\Core\File\Services\FileService;
+
+/**
+ * Generic wrapper around FileService::pruneUnowned() — see that method's
+ * own docblock for what "unowned" means and why the grace period exists.
+ * Any caller (3dealer's product custom-field photo uploads today, some
+ * other future upload feature tomorrow, in this app or another consuming
+ * app) schedules this once per purpose string it stores files under; this
+ * command itself has no opinion about what any given purpose means.
+ */
+class PruneUnownedFilesCommand extends Command
+{
+    protected $signature = 'boboko:file:prune-unowned {purpose} {--hours=24 : Only delete unowned files older than this}';
+
+    protected $description = 'Delete unowned files of a given purpose past their grace period';
+
+    public function handle(FileService $files): int
+    {
+        $purpose = $this->argument('purpose');
+
+        $deleted = $files->pruneUnowned($purpose, now()->subHours((int) $this->option('hours')));
+
+        $this->info("Deleted {$deleted} unowned file(s) of purpose \"{$purpose}\".");
+
+        return self::SUCCESS;
+    }
+}

src/File/Contracts/FileAdapterInterface.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Modules\Core\File\Contracts;
+
+use Illuminate\Http\UploadedFile;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+/**
+ * One storage backend's actual byte-level operations — a disk name (see
+ * Modules\Core\File\Models\File::$disk) resolves to exactly one
+ * implementation of this via Modules\Core\File\Services\FileService's own
+ * contextual binding (see Providers\FileServiceProvider), the same
+ * pattern Shipping\Contracts\CarrierFulfillmentInterface uses to pick an
+ * AcsFulfillmentService/BoxNowFulfillmentService per carrier. FileService
+ * itself never touches a disk directly — every backend-specific detail
+ * (a local path, an S3 bucket/region, ...) lives entirely inside one
+ * adapter, so adding a new backend never touches FileService or any of
+ * its callers.
+ */
+interface FileAdapterInterface
+{
+    /**
+     * Stores the file under $directory, returning the path to record on
+     * the File row (Models\File::$path) — backend-specific (a relative
+     * local path, an S3 object key, ...), meaningful only to this same
+     * adapter.
+     */
+    public function store(UploadedFile $file, string $directory): string;
+
+    public function exists(string $path): bool;
+
+    public function delete(string $path): void;
+
+    /**
+     * Streams the file at $path straight to the browser, inline (the
+     * browser renders/previews it directly rather than prompting to save).
+     */
+    public function retrieve(string $path, ?string $name = null): StreamedResponse;
+
+    /**
+     * Same bytes as retrieve(), but as a forced attachment — the browser
+     * always prompts to save, even for a type it could otherwise preview
+     * (an image inline in a new tab).
+     */
+    public function download(string $path, ?string $name = null): StreamedResponse;
+}

src/File/Http/Controllers/DownloadFileController.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Modules\Core\File\Http\Controllers;
+
+use Illuminate\Http\Request;
+use Illuminate\Routing\Controller;
+use Modules\Core\File\Models\File;
+use Modules\Core\File\Services\FileService;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+/**
+ * Streams a File's bytes straight to the browser — inline by default (a
+ * browser-previewable type like an image opens/displays directly), or as
+ * a forced download with ?download=1 (e.g. an explicit "Download" button
+ * distinct from a thumbnail/preview link pointing at the same file). Only
+ * reachable via a short-lived signed URL — same auth model as
+ * Modules\Core\Shipping\Http\Controllers\DownloadShipmentLabelController
+ * (a valid signature IS the auth check, no separate staff/customer
+ * session check here) — so any caller that can mint a signed URL to this
+ * route (the storefront's own custom-field upload flow, or the admin
+ * order-line display) can hand a viewer a working link without this
+ * controller knowing anything about who they are or why they're allowed
+ * to see this particular file.
+ *
+ * Looks the File up manually from a plain {file} id rather than relying
+ * on implicit route-model-binding — registered via loadRoutesFrom() with
+ * no middleware group (see Providers\FileServiceProvider::boot()), so
+ * SubstituteBindings never runs and a type-hinted File parameter would
+ * silently resolve to an empty, non-existent model instead of 404ing.
+ */
+class DownloadFileController extends Controller
+{
+    public function __invoke(Request $request, int $file, FileService $files): StreamedResponse
+    {
+        if (! $request->hasValidSignature()) {
+            abort(401);
+        }
+
+        $file = File::findOrFail($file);
+
+        abort_unless($files->exists($file), 404);
+
+        return $request->boolean('download') ? $files->download($file) : $files->retrieve($file);
+    }
+}

src/File/Http/Controllers/UploadFileController.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace Modules\Core\File\Http\Controllers;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Validator;
+use Modules\Core\File\Services\FileService;
+
+/**
+ * The generic "accept an upload, validate it, store it via FileService,
+ * return its id" flow — what varies per use case (which extensions/sizes
+ * are acceptable) is deliberately NOT configurable here, and NEVER trusts
+ * anything the request itself claims about its own limits: a client could
+ * simply lie about them. purpose()/validationRules() are protected hooks
+ * a concrete subclass overrides instead — an ordinary PHP method a caller
+ * writes once per upload policy, not request input, so the actual limit
+ * enforced is always whatever server-side code says it is. Different
+ * products can even need different limits (a 3D-print reference photo
+ * vs. a video upload, say) — that's still a subclass's own store()
+ * override deciding which rule set applies to a given request, not
+ * something this base class or a shared config file could express.
+ */
+abstract class UploadFileController extends Controller
+{
+    /**
+     * The File row's `purpose` tag (see Models\File) — also the storage
+     * directory it lands under (FileService::store()'s single $purpose
+     * param doubles as both).
+     */
+    abstract protected function purpose(): string;
+
+    /**
+     * Laravel validation rules for the incoming request, keyed exactly as
+     * $request->all() would be. Must include a 'file' rule accepting an
+     * uploaded file — this class always reads the file from that key.
+     *
+     * @return array<string, array<int, mixed>>
+     */
+    abstract protected function validationRules(Request $request): array;
+
+    public function store(Request $request, FileService $files): JsonResponse
+    {
+        $validator = Validator::make(
+            $request->all(),
+            $this->validationRules($request),
+            $this->validationMessages($request),
+            $this->validationAttributes($request),
+        );
+
+        if ($validator->fails()) {
+            return response()->json(['error' => $validator->errors()->first('file')], 422);
+        }
+
+        $file = $files->store($request->file('file'), $this->purpose());
+
+        return response()->json(['file_id' => $file->id]);
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    protected function validationMessages(Request $request): array
+    {
+        return [];
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    protected function validationAttributes(Request $request): array
+    {
+        return [];
+    }
+}

src/File/Listeners/AttachCustomFieldFileToCartLine.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Modules\Core\File\Listeners;
+
+use Modules\Core\Cart\Events\CartLineAdded;
+use Modules\Core\File\Models\File;
+use Modules\Core\File\Services\FileService;
+
+/**
+ * A custom-field photo is uploaded (and gets its own File row, unowned)
+ * the moment a shopper picks it on the product page — before add-to-cart
+ * even runs (see 3dealer's CustomFieldUploadController). The storefront's
+ * add-to-cart request only carries that File's `id` in its custom_fields
+ * answer (see CartController::customFieldsMeta()); this is what actually
+ * gives the File an owner, once the real CartLine it belongs to exists.
+ *
+ * Listens for Cart\Events\CartLineAdded rather than reaching back into
+ * the cart after CartService::addLine() returns — that event already
+ * carries the exact CartLine Lunar resolved/created, with no need to
+ * re-match it by meta (ambiguous whenever two lines share a purchasable +
+ * similar meta).
+ */
+class AttachCustomFieldFileToCartLine
+{
+    public function __construct(
+        private readonly FileService $files,
+    ) {}
+
+    public function handle(CartLineAdded $event): void
+    {
+        $fileIds = collect($event->line->meta['custom_fields'] ?? [])
+            ->pluck('file_id')
+            ->filter()
+            ->all();
+
+        if ($fileIds === []) {
+            return;
+        }
+
+        File::query()
+            ->whereIn('id', $fileIds)
+            ->each(fn (File $file) => $this->files->attachOwner($file, $event->line));
+    }
+}

src/File/Listeners/TransferCustomFieldFileOwnership.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace Modules\Core\File\Listeners;
+
+use Lunar\Models\OrderLine;
+use Modules\Core\Checkout\Events\OrderPlaced;
+use Modules\Core\File\Models\File;
+use Modules\Core\File\Services\FileService;
+
+/**
+ * Lunar\Pipelines\Order\Creation\CreateOrderLines copies a CartLine's
+ * meta (custom_fields included) onto its new OrderLine verbatim — so an
+ * order's custom-field file answer keeps the exact same `file_id` its
+ * originating cart line's meta already had (see 3dealer's CartController::
+ * customFieldsMeta(), which stores only that id — File is the single
+ * source of truth for disk/path/name/mime, never duplicated into meta).
+ * That id is enough to find the File row directly, with no need to match
+ * an OrderLine back to "the" CartLine it came from.
+ *
+ * Re-points ownership (not a copy — the same File row) from whatever
+ * CartLine owned it to this OrderLine, so a customer's placed order keeps
+ * its file even after the cart it came from is later cleared (see
+ * Modules\Core\Cart\Services\CartService, or a checkout-complete cart
+ * reset) — FileService::pruneUnowned() only ever removes UNOWNED files,
+ * but a File left pointing at a since-deleted CartLine would be just as
+ * orphaned in practice; this listener is what keeps that from ever
+ * happening for a real, placed order.
+ *
+ * Listens for Checkout\Events\OrderPlaced, not an OrderLine model event —
+ * that's the one place in this codebase an order is reliably known to be
+ * placed exactly once (see that event's own docblock), and it hands over
+ * the whole Order with every line already loaded.
+ */
+class TransferCustomFieldFileOwnership
+{
+    public function __construct(
+        private readonly FileService $files,
+    ) {}
+
+    public function handle(OrderPlaced $event): void
+    {
+        foreach ($event->order->lines as $line) {
+            $this->transferLine($line);
+        }
+    }
+
+    private function transferLine(OrderLine $line): void
+    {
+        $fileIds = collect($line->meta['custom_fields'] ?? [])
+            ->pluck('file_id')
+            ->filter()
+            ->all();
+
+        if ($fileIds === []) {
+            return;
+        }
+
+        File::query()
+            ->whereIn('id', $fileIds)
+            ->each(fn (File $file) => $this->files->attachOwner($file, $line));
+    }
+}

src/File/Models/File.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Modules\Core\File\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+
+/**
+ * A row per physical file Modules\Core\File\Services\FileService has
+ * stored — see that migration's own docblock for why `owner_type`/
+ * `owner_id` are nullable and what `purpose` is for.
+ */
+class File extends Model
+{
+    protected $guarded = [];
+
+    protected function casts(): array
+    {
+        return [
+            'size' => 'integer',
+        ];
+    }
+
+    public function owner(): MorphTo
+    {
+        return $this->morphTo();
+    }
+}

src/File/Services/FileService.php

@@ -0,0 +1,135 @@
+<?php
+
+namespace Modules\Core\File\Services;
+
+use Illuminate\Contracts\Container\Container;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+use Modules\Core\File\Contracts\FileAdapterInterface;
+use Modules\Core\File\Models\File;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+/**
+ * Orchestrates the `files` table (ownership, purpose, cleanup — see that
+ * migration's own docblock) on top of whichever FileAdapterInterface a
+ * disk resolves to (see Providers\FileServiceProvider's contextual
+ * binding) — never touches a disk or a raw path itself. Knows nothing
+ * about custom fields, carts, or orders specifically; every caller
+ * (3dealer's custom-field upload flow today, some other future
+ * file-upload need tomorrow) supplies its own `purpose` string and owner
+ * model, and scopes its own queries by them.
+ *
+ * `purpose` also doubles as the storage directory a file lands under
+ * (store() passes it straight through as the adapter's own $directory) —
+ * one string to name both, rather than every caller supplying two
+ * near-identical values for what's really the same distinction ("which
+ * kind of upload is this").
+ */
+class FileService
+{
+    public function __construct(
+        private readonly Container $container,
+    ) {}
+
+    public function store(UploadedFile $file, string $purpose, string $disk = 'local'): File
+    {
+        $path = $this->adapter($disk)->store($file, $purpose);
+
+        return File::create([
+            'disk' => $disk,
+            'path' => $path,
+            'original_name' => $file->getClientOriginalName(),
+            'mime' => $file->getMimeType(),
+            'size' => $file->getSize(),
+            'purpose' => $purpose,
+        ]);
+    }
+
+    /**
+     * Re-points an existing File at its owner — called once an owner
+     * actually exists (e.g. a shopper's picked-but-not-yet-added photo
+     * gets a CartLine the moment it's added to the cart). Never creates a
+     * second row for the same physical file.
+     */
+    public function attachOwner(File $file, Model $owner): File
+    {
+        $file->update([
+            'owner_type' => $owner->getMorphClass(),
+            'owner_id' => $owner->getKey(),
+        ]);
+
+        return $file;
+    }
+
+    public function retrieve(File $file): StreamedResponse
+    {
+        return $this->adapter($file->disk)->retrieve($file->path, $file->original_name);
+    }
+
+    /**
+     * Same file as retrieve(), forced as a download (Content-Disposition:
+     * attachment) rather than served inline — for a button distinct from
+     * a preview link/thumbnail pointing at the same File.
+     */
+    public function download(File $file): StreamedResponse
+    {
+        return $this->adapter($file->disk)->download($file->path, $file->original_name);
+    }
+
+    public function exists(File $file): bool
+    {
+        return $this->adapter($file->disk)->exists($file->path);
+    }
+
+    public function delete(File $file): void
+    {
+        $this->adapter($file->disk)->delete($file->path);
+
+        $file->delete();
+    }
+
+    /**
+     * @return Collection<int, File>
+     */
+    public function list(string $purpose, ?Model $owner = null): Collection
+    {
+        return File::query()
+            ->where('purpose', $purpose)
+            ->when($owner, fn ($query) => $query
+                ->where('owner_type', $owner->getMorphClass())
+                ->where('owner_id', $owner->getKey()))
+            ->get();
+    }
+
+    /**
+     * Deletes every File of the given purpose that has no owner yet and
+     * is older than $olderThan — the grace period covers a shopper still
+     * on the page with a picked-but-not-yet-added file. An owned File
+     * (whatever the owner type) is never touched here; callers that want
+     * owned files gone too should delete() them explicitly wherever that
+     * ownership itself ends (e.g. a CartLine being removed).
+     *
+     * @return int number of files deleted
+     */
+    public function pruneUnowned(string $purpose, Carbon $olderThan): int
+    {
+        $files = File::query()
+            ->where('purpose', $purpose)
+            ->whereNull('owner_type')
+            ->where('created_at', '<', $olderThan)
+            ->get();
+
+        foreach ($files as $file) {
+            $this->delete($file);
+        }
+
+        return $files->count();
+    }
+
+    private function adapter(string $disk): FileAdapterInterface
+    {
+        return $this->container->make(FileAdapterInterface::class, ['disk' => $disk]);
+    }
+}

src/File/routes/web.php

@@ -0,0 +1,7 @@
+<?php
+
+use Illuminate\Support\Facades\Route;
+use Modules\Core\File\Http\Controllers\DownloadFileController;
+
+Route::get('files/{file}/download', DownloadFileController::class)
+    ->name('files.download');

src/MigrateImport/Contracts/Importer.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Modules\Core\MigrateImport\Contracts;
+
+use Modules\Core\MigrateImport\DTOs\ImportSpec;
+
+interface Importer
+{
+    public function import(ImportSpec $spec): void;
+}

src/MigrateImport/DTOs/ImportSpec.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Modules\Core\MigrateImport\DTOs;
+
+class ImportSpec
+{
+    /**
+     * @param  ?string  $locale  The language the export file's own text
+     *   (product titles, descriptions, option names, ...) is actually
+     *   written in — asked of the operator at import time (see
+     *   Command\MigrateImportCommand), since an export has no reliable
+     *   way to declare its own language and it does not necessarily match
+     *   this store's Lunar\Models\Language::getDefault(). Null for a
+     *   source/type this doesn't apply to (e.g. an API-based import with
+     *   no free-text file to attribute a single language to).
+     */
+    public function __construct(
+        public readonly string $source,
+        public readonly string $type,
+        public readonly ?string $filePath = null,
+        public readonly ?array $credentials = null,
+        public readonly ?string $locale = null,
+    ) {
+    }
+}

src/MigrateImport/DefaultLocale.php

@@ -1,13 +0,0 @@
-<?php
-
-namespace Modules\Core\MigrateImport;
-
-use Lunar\Models\Language;
-
-class DefaultLocale
-{
-    public static function code(): string
-    {
-        return Language::getDefault()->code;
-    }
-}

src/MigrateImport/ImportSpec.php

@@ -1,14 +0,0 @@
-<?php
-
-namespace Modules\Core\MigrateImport;
-
-class ImportSpec
-{
-    public function __construct(
-        public readonly string $source,
-        public readonly string $type,
-        public readonly ?string $filePath = null,
-        public readonly ?array $credentials = null,
-    ) {
-    }
-}

src/MigrateImport/Importer.php

@@ -1,8 +0,0 @@
-<?php
-
-namespace Modules\Core\MigrateImport;
-
-interface Importer
-{
-    public function import(ImportSpec $spec): void;
-}

src/MigrateImport/Jobs/RunMigrateImportJob.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Modules\Core\MigrateImport\Jobs;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+use Modules\Core\MigrateImport\DTOs\ImportSpec;
+use Modules\Core\MigrateImport\Services\ImporterFactory;
+
+class RunMigrateImportJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public function __construct(
+        public readonly ImportSpec $spec,
+    ) {
+    }
+
+    /**
+     * Just hands off to the right Importer and returns — for Shopify,
+     * that importer dispatches a job batch instead of importing inline
+     * (see Shopify\ShopifyExportImporter::import()) and this job's own
+     * work is done the moment that batch is queued, well before the
+     * batch's jobs actually run. The SKU backfill that used to happen
+     * right here, after import() returned, now happens in that batch's
+     * own then() callback instead — running it here would fire before a
+     * single product had actually been imported.
+     */
+    public function handle(): void
+    {
+        Log::info('Import started', ['source' => $this->spec->source, 'type' => $this->spec->type, 'file' => $this->spec->filePath]);
+
+        $importer = ImporterFactory::make($this->spec);
+        $importer->import($this->spec);
+
+        Log::info('Import job complete', ['source' => $this->spec->source]);
+    }
+}

src/MigrateImport/JudgeMe/Resolvers/ProductResolver.php

@@ -3,7 +3,6 @@
 namespace Modules\Core\MigrateImport\JudgeMe\Resolvers;
 
 use Lunar\Models\Product;
-use Lunar\Models\Url;
 
 class ProductResolver
 {

src/MigrateImport/JudgeMe/Services/JudgeMeCsvReader.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Modules\Core\MigrateImport\JudgeMe;
+namespace Modules\Core\MigrateImport\JudgeMe\Services;
 
 use RuntimeException;
 

src/MigrateImport/JudgeMe/Services/JudgeMeExportImporter.php

@@ -1,12 +1,12 @@
 <?php
 
-namespace Modules\Core\MigrateImport\JudgeMe;
+namespace Modules\Core\MigrateImport\JudgeMe\Services;
 
 use Throwable;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Log;
-use Modules\Core\MigrateImport\Importer;
-use Modules\Core\MigrateImport\ImportSpec;
+use Modules\Core\MigrateImport\Contracts\Importer;
+use Modules\Core\MigrateImport\DTOs\ImportSpec;
 use Modules\Core\MigrateImport\JudgeMe\Resolvers\ProductResolver;
 use Modules\Core\MigrateImport\Models\ImportMapping;
 use Modules\Core\Review\Models\ProductReview;
@@ -22,9 +22,22 @@ class JudgeMeExportImporter implements Importer
 
     public function import(ImportSpec $spec): void
     {
-        foreach ($this->csvReader->read($spec->filePath) as $row) {
+        $rows = $this->csvReader->read($spec->filePath);
+        $total = count($rows);
+        $imported = 0;
+
+        Log::info('JudgeMe import: starting', ['total' => $total]);
+
+        foreach ($rows as $row) {
             $this->importReview($row);
+            $imported++;
+
+            if ($imported % 100 === 0) {
+                Log::info('JudgeMe import: progress', ['imported' => $imported, 'total' => $total]);
+            }
         }
+
+        Log::info('JudgeMe import: finished', ['imported' => $imported, 'total' => $total]);
     }
 
     private function importReview(array $row): void

src/MigrateImport/RunMigrateImportJob.php

@@ -1,39 +0,0 @@
-<?php
-
-namespace Modules\Core\MigrateImport;
-
-use Illuminate\Bus\Queueable;
-use Illuminate\Contracts\Queue\ShouldQueue;
-use Illuminate\Foundation\Bus\Dispatchable;
-use Illuminate\Queue\InteractsWithQueue;
-use Illuminate\Queue\SerializesModels;
-use Modules\Core\Catalog\Services\SkuBackfillService;
-
-class RunMigrateImportJob implements ShouldQueue
-{
-    use Dispatchable;
-    use InteractsWithQueue;
-    use Queueable;
-    use SerializesModels;
-
-    public function __construct(
-        public readonly ImportSpec $spec,
-    ) {
-    }
-
-    public function handle(SkuBackfillService $skuBackfill): void
-    {
-        $importer = ImporterFactory::make($this->spec);
-        $importer->import($this->spec);
-
-        // Only Shopify's importer creates ProductVariant rows at all (see
-        // Shopify\ShopifyExportImporter) — JudgeMe never touches products,
-        // so running this for that source would just be a guaranteed
-        // no-op query every time. Source CSV rows genuinely can have no
-        // `Variant SKU` value; see SkuBackfillService's own docblock for
-        // why that's synthesized rather than treated as an importer bug.
-        if ($this->spec->source === 'shopify') {
-            $skuBackfill->backfill();
-        }
-    }
-}

src/MigrateImport/Services/ImportLocale.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace Modules\Core\MigrateImport\Services;
+
+use Lunar\Models\Language;
+
+/**
+ * The language every resolver in an import run writes product-facing text
+ * under (name, description, option names, ...) — NOT necessarily this
+ * store's own Lunar\Models\Language::getDefault(). An export file has no
+ * reliable way to declare its own language, and a store's default admin/
+ * storefront language is an independent fact from whatever language a
+ * given export happens to be written in — conflating the two (this
+ * class's own former name, DefaultLocale, said as much) used to silently
+ * save every imported product's text under the wrong language, invisible
+ * unless that language was also the one selected while viewing/editing
+ * the product afterward.
+ *
+ * Set once per import run from the operator's own answer (see
+ * Command\MigrateImportCommand::askImportLocale(), threaded through
+ * ImportSpec::$locale) at the top of Importer::import() — every resolver
+ * downstream (ProductAttributeResolver, ProductOptionResolver,
+ * CollectionResolver, ImportAttributeResolver) calls code() exactly as
+ * before, unaware anything changed. Falls back to Language::getDefault()
+ * only when nothing was ever set (e.g. an import path with no locale
+ * concept of its own — JudgeMe's reviews-only export never calls set()).
+ */
+class ImportLocale
+{
+    private static ?string $code = null;
+
+    public static function set(string $code): void
+    {
+        self::$code = $code;
+    }
+
+    public static function code(): string
+    {
+        return self::$code ?? Language::getDefault()->code;
+    }
+
+    /**
+     * A static property outlives a single request only inside a
+     * long-running worker process, where a queued job for one import
+     * must not leak its locale into the next — called at the end of
+     * every Importer::import() run, success or failure.
+     */
+    public static function reset(): void
+    {
+        self::$code = null;
+    }
+}

src/MigrateImport/Services/ImporterFactory.php

@@ -1,10 +1,12 @@
 <?php
 
-namespace Modules\Core\MigrateImport;
+namespace Modules\Core\MigrateImport\Services;
 
 use InvalidArgumentException;
-use Modules\Core\MigrateImport\JudgeMe\JudgeMeExportImporter;
-use Modules\Core\MigrateImport\Shopify\ShopifyExportImporter;
+use Modules\Core\MigrateImport\DTOs\ImportSpec;
+use Modules\Core\MigrateImport\Contracts\Importer;
+use Modules\Core\MigrateImport\JudgeMe\Services\JudgeMeExportImporter;
+use Modules\Core\MigrateImport\Shopify\Services\ShopifyExportImporter;
 
 class ImporterFactory
 {

src/MigrateImport/Shopify/DTOs/ProductGroup.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Modules\Core\MigrateImport\Shopify;
+namespace Modules\Core\MigrateImport\Shopify\DTOs;
 
 class ProductGroup
 {

src/MigrateImport/Shopify/Jobs/ImportShopifyProductJob.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace Modules\Core\MigrateImport\Shopify\Jobs;
+
+use Illuminate\Bus\Batchable;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Lunar\Models\CollectionGroup;
+use Lunar\Models\Currency;
+use Modules\Core\MigrateImport\Services\ImportLocale;
+use Modules\Core\MigrateImport\Shopify\DTOs\ProductGroup;
+use Modules\Core\MigrateImport\Shopify\Services\ShopifyExportImporter;
+
+/**
+ * One product per job — ShopifyExportImporter::import() used to loop over
+ * every ProductGroup inline, inside RunMigrateImportJob's own single
+ * process. A large export (hundreds of products, each with variants,
+ * media downloads and conversions) grew that one process's memory past
+ * queue:work's --memory limit (see docker-compose.yml), which kills the
+ * worker mid-job; the container then restarts and the WHOLE import
+ * re-runs from row one, never actually finishing. Splitting into one
+ * job per product means memory resets between jobs (a fresh worker
+ * process picks up each one), and a restart only repeats whichever
+ * single product was in flight — ImportMapping's own per-handle
+ * resolve()/record() already makes re-importing the same product cheap
+ * and idempotent.
+ */
+class ImportShopifyProductJob implements ShouldQueue
+{
+    use Batchable;
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    public function __construct(
+        private readonly ProductGroup $group,
+        private readonly string $imagesPath,
+        private readonly CollectionGroup $collectionGroup,
+        private readonly Currency $currency,
+        private readonly ?string $locale,
+    ) {
+    }
+
+    public function handle(ShopifyExportImporter $importer): void
+    {
+        if ($this->locale !== null) {
+            ImportLocale::set($this->locale);
+        }
+
+        try {
+            $importer->importProduct($this->group, $this->imagesPath, $this->collectionGroup, $this->currency);
+        } finally {
+            // A queue worker process outlives a single job — this must
+            // not leak into whichever product the same worker picks up
+            // next.
+            ImportLocale::reset();
+        }
+    }
+}

src/MigrateImport/Shopify/Resolvers/CollectionResolver.php

@@ -7,7 +7,7 @@ use Lunar\FieldTypes\TranslatedText;
 use Lunar\Models\Collection;
 use Lunar\Models\CollectionGroup;
 use Lunar\Models\Product;
-use Modules\Core\MigrateImport\DefaultLocale;
+use Modules\Core\MigrateImport\Services\ImportLocale;
 
 class CollectionResolver
 {
@@ -45,7 +45,7 @@ class CollectionResolver
             'collection_group_id' => $group->id,
             'attribute_data' => [
                 'name' => new TranslatedText(collect([
-                    DefaultLocale::code() => new Text($name),
+                    ImportLocale::code() => new Text($name),
                 ])),
             ],
         ]);

src/MigrateImport/Shopify/Resolvers/ImportAttributeResolver.php

@@ -8,7 +8,7 @@ use Lunar\Models\Attribute;
 use Lunar\Models\AttributeGroup;
 use Lunar\Models\Product;
 use Lunar\Models\ProductType;
-use Modules\Core\MigrateImport\DefaultLocale;
+use Modules\Core\MigrateImport\Services\ImportLocale;
 
 class ImportAttributeResolver
 {
@@ -40,7 +40,7 @@ class ImportAttributeResolver
                 [
                     'attribute_group_id' => $group->id,
                     'position' => $nextPosition++,
-                    'name' => [DefaultLocale::code() => $definition['label']],
+                    'name' => [ImportLocale::code() => $definition['label']],
                     'section' => 'main',
                     'type' => $definition['type'],
                     'required' => false,
@@ -49,7 +49,7 @@ class ImportAttributeResolver
                         ? ['richtext' => false]
                         : [],
                     'system' => false,
-                    'description' => [DefaultLocale::code() => ''],
+                    'description' => [ImportLocale::code() => ''],
                 ],
             );
 
@@ -62,7 +62,7 @@ class ImportAttributeResolver
         return AttributeGroup::firstOrCreate(
             ['attributable_type' => Product::morphName(), 'handle' => 'import'],
             [
-                'name' => [DefaultLocale::code() => 'Additional Details'],
+                'name' => [ImportLocale::code() => 'Additional Details'],
                 'position' => 100,
             ],
         );

src/MigrateImport/Shopify/Resolvers/ProductAttributeResolver.php

@@ -6,7 +6,7 @@ use Lunar\FieldTypes\Number;
 use Lunar\FieldTypes\Text;
 use Lunar\FieldTypes\TranslatedText;
 use Lunar\Models\ProductType;
-use Modules\Core\MigrateImport\DefaultLocale;
+use Modules\Core\MigrateImport\Services\ImportLocale;
 
 class ProductAttributeResolver
 {
@@ -43,7 +43,7 @@ class ProductAttributeResolver
         }
 
         return new TranslatedText(collect([
-            DefaultLocale::code() => new Text($value),
+            ImportLocale::code() => new Text($value),
         ]));
     }
 }

src/MigrateImport/Shopify/Resolvers/ProductOptionResolver.php

@@ -5,7 +5,7 @@ namespace Modules\Core\MigrateImport\Shopify\Resolvers;
 use Illuminate\Support\Str;
 use Lunar\Models\ProductOption;
 use Lunar\Models\ProductOptionValue;
-use Modules\Core\MigrateImport\DefaultLocale;
+use Modules\Core\MigrateImport\Services\ImportLocale;
 
 class ProductOptionResolver
 {
@@ -24,8 +24,8 @@ class ProductOptionResolver
         return ProductOption::query()->firstOrCreate(
             ['handle' => $handle],
             [
-                'name' => [DefaultLocale::code() => $name],
-                'label' => [DefaultLocale::code() => $name],
+                'name' => [ImportLocale::code() => $name],
+                'label' => [ImportLocale::code() => $name],
                 'shared' => true,
             ],
         );
@@ -46,7 +46,7 @@ class ProductOptionResolver
 
         return $existing ?? ProductOptionValue::create([
             'product_option_id' => $option->id,
-            'name' => [DefaultLocale::code() => $value],
+            'name' => [ImportLocale::code() => $value],
         ]);
     }
 }

src/MigrateImport/Shopify/Services/ShopifyCsvReader.php

@@ -1,8 +1,9 @@
 <?php
 
-namespace Modules\Core\MigrateImport\Shopify;
+namespace Modules\Core\MigrateImport\Shopify\Services;
 
 use RuntimeException;
+use Modules\Core\MigrateImport\Shopify\DTOs\ProductGroup;
 
 class ShopifyCsvReader
 {

src/MigrateImport/Shopify/Services/ShopifyExportImporter.php

@@ -1,9 +1,10 @@
 <?php
 
-namespace Modules\Core\MigrateImport\Shopify;
+namespace Modules\Core\MigrateImport\Shopify\Services;
 
 use Lunar\Models\TaxClass;
 use Lunar\Models\ProductOption;
+use Illuminate\Support\Facades\Bus;
 use Illuminate\Support\Facades\Log;
 use Lunar\Models\Collection;
 use Lunar\Models\CollectionGroup;
@@ -12,9 +13,13 @@ use Lunar\Models\Language;
 use Lunar\Models\Product;
 use Lunar\Models\ProductVariant;
 use Lunar\Models\Url;
-use Modules\Core\MigrateImport\ImportSpec;
-use Modules\Core\MigrateImport\Importer;
+use Modules\Core\Catalog\Services\SkuBackfillService;
+use Modules\Core\MigrateImport\Services\ImportLocale;
+use Modules\Core\MigrateImport\DTOs\ImportSpec;
+use Modules\Core\MigrateImport\Shopify\DTOs\ProductGroup;
+use Modules\Core\MigrateImport\Contracts\Importer;
 use Modules\Core\MigrateImport\Models\ImportMapping;
+use Modules\Core\MigrateImport\Shopify\Jobs\ImportShopifyProductJob;
 use Modules\Core\MigrateImport\Shopify\Resolvers\AssetResolver;
 use Modules\Core\MigrateImport\Shopify\Resolvers\BrandResolver;
 use Modules\Core\MigrateImport\Shopify\Resolvers\CollectionResolver;
@@ -46,9 +51,21 @@ class ShopifyExportImporter implements Importer
     ) {
     }
 
+    /**
+     * Dispatches one ImportShopifyProductJob per ProductGroup instead of
+     * importing them inline — see that job's own docblock for why (a
+     * single process holding every group in memory for the whole run
+     * kept exceeding queue:work's --memory limit on a large export,
+     * which kills the worker mid-run and restarts the entire import from
+     * scratch). Bus::batch()'s then() is what SkuBackfillService used to
+     * run right after this loop — now deferred until every product job
+     * in the batch has actually finished, since dispatching a batch
+     * itself returns immediately.
+     */
     public function import(ImportSpec $spec): void
     {
         $groups = $this->csvReader->read($spec->filePath);
+        $total = count($groups);
         $imagesPath = dirname($spec->filePath).'/files';
         $collectionGroup = CollectionGroup::firstOrCreate(
             ['handle' => 'shopify'],
@@ -56,12 +73,30 @@ class ShopifyExportImporter implements Importer
         );
         $currency = Currency::getDefault();
 
-        foreach ($groups as $group) {
-            $this->importProduct($group, $imagesPath, $collectionGroup, $currency);
-        }
+        Log::info('Shopify import: dispatching product jobs', ['total' => $total]);
+
+        $jobs = collect($groups)->map(fn (ProductGroup $group) => new ImportShopifyProductJob(
+            $group,
+            $imagesPath,
+            $collectionGroup,
+            $currency,
+            $spec->locale,
+        ))->all();
+
+        Bus::batch($jobs)
+            ->name("Shopify import: {$spec->filePath}")
+            ->then(function () use ($total) {
+                Log::info('Shopify import: all product jobs finished, backfilling missing SKUs', ['total' => $total]);
+                app(SkuBackfillService::class)->backfill();
+                Log::info('Shopify import: finished', ['total' => $total]);
+            })
+            ->catch(function ($batch, $e) {
+                Log::error('Shopify import: batch failed', ['error' => $e->getMessage()]);
+            })
+            ->dispatch();
     }
 
-    private function importProduct(
+    public function importProduct(
         ProductGroup $group,
         string $imagesPath,
         CollectionGroup $collectionGroup,
@@ -100,7 +135,12 @@ class ShopifyExportImporter implements Importer
             [
                 'element_type' => $product->getMorphClass(),
                 'element_id' => $product->id,
-                'language_id' => Language::getDefault()->id,
+                // ImportLocale, not Language::getDefault() — same
+                // reasoning as ProductAttributeResolver et al.: this
+                // product's handle/slug came from the export, written in
+                // whatever language the operator said the file is in,
+                // not necessarily this store's own default language.
+                'language_id' => Language::where('code', ImportLocale::code())->value('id'),
             ],
             [
                 'slug' => $group->handle,

src/Order/Filament/Extensions/OrderItemsTableExtension.php

@@ -3,22 +3,60 @@
 namespace Modules\Core\Order\Filament\Extensions;
 
 use Filament\Actions\BulkAction;
+use Filament\Support\Colors\Color;
 use Filament\Support\Exceptions\Halt;
+use Filament\Tables\Columns\Layout\Panel;
+use Filament\Tables\Columns\TextColumn;
 use Filament\Tables\Table;
+use Illuminate\Support\Facades\Blade;
+use Illuminate\Support\Facades\URL;
+use Illuminate\Support\HtmlString;
 use Lunar\Admin\Support\Extending\BaseExtension;
+use Lunar\Models\OrderLine;
+use Modules\Core\File\Models\File;
 
 /**
- * Same fix as OrderActionsExtension, applied to the order lines
- * table's "bulk_refund" toolbar action (Lunar\Admin\...\OrderItemsTable::
- * getBulkRefundAction()) — see that class's docblock for the underlying
- * Filament bug (failureNotification()+failure()+halt() never actually
- * sends the notification, because halt()'s Halt exception is caught before
- * Filament reaches the code that would send it).
+ * extendTable() has two unrelated jobs: the "bulk_refund" toolbar-action
+ * fix (see fixFailureNotification()'s own docblock — a genuine Filament
+ * bug), and adding a "Custom Fields" entry to each order line's own
+ * collapsible details dropdown (Lunar\Admin\...\OrderItemsTable::
+ * getOrderLinesTableColumns()'s Panel — the same one already showing
+ * stock level, notes, and the price_breakdowns table) — the shopper's
+ * answers to Product::$custom_fields (a reference photo, personalization
+ * text, ...), stored on OrderLine.meta by 3dealer's CartController::
+ * customFieldsMeta() and, until now, never shown anywhere in the admin.
+ *
+ * Finds that Panel via $table->getCollapsibleColumnsLayout() — NOT
+ * $table->getColumns(), which two earlier attempts at this both reached
+ * for. HasColumns::pushColumns() flattens every Panel/Split into leaf
+ * columns at table-build time and stores THAT flat list as
+ * $this->columns (what getColumns() returns); the original nested
+ * Panel/Stack objects actually used for rendering are kept separately —
+ * in $this->columnsLayout for a non-collapsible layout component, or
+ * $this->collapsibleColumnsLayout for one that IS collapsible (this
+ * order-lines Panel is, via ->collapsible()). So `$column instanceof
+ * Panel` over getColumns() can never match anything — Panel/Split
+ * instances simply never appear in that array at all — and a fix built
+ * on that check silently mutated nothing. A first attempt building a
+ * brand new Panel and re-calling $table->columns() on top of the
+ * existing setup fixed nothing either and instead rendered as a stray
+ * empty extra column outside the dropdown (caught by actually opening
+ * the order page). Mutates the found Panel's Stack in place via
+ * Stack::schema(), the one part of both earlier attempts that actually
+ * worked once the right object was found.
+ *
+ * Its own TextColumn rather than reusing the Panel's existing KeyValue:
+ * KeyValue's own Blade view HTML-escapes every value ({{ $value }}),
+ * which can't render a clickable link for a file answer.
  */
 class OrderItemsTableExtension extends BaseExtension
 {
     public function extendTable(Table $table): Table
     {
+        if ($table->getCollapsibleColumnsLayout() instanceof Panel) {
+            $this->addCustomFieldsColumn($table->getCollapsibleColumnsLayout());
+        }
+
         return $table->toolbarActions(
             array_map(
                 fn ($action) => $action instanceof BulkAction && $action->getName() === 'bulk_refund'
@@ -29,6 +67,88 @@ class OrderItemsTableExtension extends BaseExtension
         );
     }
 
+    private function addCustomFieldsColumn(Panel $panel): void
+    {
+        $stack = $panel->getComponents()[0] ?? null;
+
+        if ($stack === null) {
+            return;
+        }
+
+        $stack->schema([
+            ...$stack->getComponents(),
+            TextColumn::make('custom_fields')
+                ->label('Custom Fields')
+                ->visible(fn (OrderLine $record) => filled($record->meta['custom_fields'] ?? null))
+                ->getStateUsing(fn (OrderLine $record) => $this->renderCustomFields($record))
+                ->html(),
+        ]);
+    }
+
+    /**
+     * Same table markup/classes as this Panel's own existing KeyValue
+     * component (Lunar\Admin's price_breakdowns, right above this in the
+     * dropdown — see lunarpanel::tables.components.key-value) for visual
+     * consistency, rebuilt here rather than reused: KeyValue's Blade view
+     * HTML-escapes every value ({{ $value }}), which can't render a
+     * thumbnail/download link for a file answer.
+     */
+    private function renderCustomFields(OrderLine $record): HtmlString
+    {
+        $rows = collect($record->meta['custom_fields'] ?? [])
+            ->map(fn (array $field) => sprintf(
+                '<tr class="divide-x divide-gray-950/10 dark:divide-white/10"><td class="p-2 font-medium whitespace-nowrap">%s</td><td class="p-2">%s</td></tr>',
+                e($field['label']),
+                $field['type'] === 'file' ? $this->fileCell($field) : e($field['value'] ?? ''),
+            ))
+            ->implode('');
+
+        return new HtmlString(
+            '<div class="w-full mt-2 overflow-hidden overflow-x-auto ring-1 ring-inset ring-gray-950/10 dark:ring-white/10 rounded bg-white/70 dark:bg-white/5">'
+            .'<table class="min-w-full text-xs divide-y divide-gray-950/10 dark:divide-white/10"><tbody class="divide-y divide-gray-950/10 dark:divide-white/10">'
+            .$rows
+            .'</tbody></table></div>',
+        );
+    }
+
+    /**
+     * A thumbnail (previewable image types only — an inline-signed URL to
+     * the same File; see FileService::retrieve()) alongside an icon-only
+     * download link forcing Content-Disposition: attachment (FileService::
+     * download()) — two separate signed URLs, not one reused with a query
+     * string appended after signing, since a signature covers the exact
+     * query parameters present when it was minted.
+     */
+    private function fileCell(array $field): string
+    {
+        $file = File::find($field['file_id'] ?? null);
+
+        if ($file === null) {
+            return __('lunarpanel::global.na');
+        }
+
+        $previewUrl = URL::temporarySignedRoute('files.download', now()->addHours(2), ['file' => $file->id]);
+        $downloadUrl = URL::temporarySignedRoute('files.download', now()->addHours(2), ['file' => $file->id, 'download' => 1]);
+        $previewable = ['image/jpeg', 'image/png', 'image/webp', 'image/gif'];
+
+        $thumbnail = in_array($file->mime, $previewable, true)
+            ? sprintf(
+                '<a href="%s" target="_blank" rel="noopener"><img src="%s" alt="" style="width:2.5rem;height:2.5rem;object-fit:cover;border-radius:0.375rem;vertical-align:middle"></a>',
+                $previewUrl,
+                $previewUrl,
+            )
+            : '';
+
+        return sprintf(
+            '<div style="display:flex;align-items:center;gap:0.5rem">%s<span>%s</span><a href="%s" title="Download" style="color:rgb(%s);display:inline-flex">%s</a></div>',
+            $thumbnail,
+            e($file->original_name),
+            $downloadUrl,
+            Color::Blue[600],
+            Blade::render('<x-filament::icon icon="heroicon-o-arrow-down-tray" style="width:1rem;height:1rem"/>'),
+        );
+    }
+
     private function fixFailureNotification(BulkAction $action): BulkAction
     {
         $originalAction = $action->getActionFunction();

src/Providers/FileServiceProvider.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Modules\Core\Providers;
+
+use Illuminate\Support\Facades\Event;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\ServiceProvider;
+use InvalidArgumentException;
+use Modules\Core\Cart\Events\CartLineAdded;
+use Modules\Core\Checkout\Events\OrderPlaced;
+use Modules\Core\File\Adapters\LocalFileAdapter;
+use Modules\Core\File\Commands\PruneUnownedFilesCommand;
+use Modules\Core\File\Contracts\FileAdapterInterface;
+use Modules\Core\File\Listeners\AttachCustomFieldFileToCartLine;
+use Modules\Core\File\Listeners\TransferCustomFieldFileOwnership;
+
+class FileServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        // Same pattern as ShippingServiceProvider's CarrierFulfillmentInterface
+        // binding — a plain param ('disk' here, 'carrier' there) picks which
+        // concrete adapter Modules\Core\File\Services\FileService actually
+        // talks to. Adding a real S3FileAdapter later is one class plus one
+        // more match arm here; nothing that already calls FileService changes.
+        $this->app->bind(FileAdapterInterface::class, function ($app, array $params) {
+            $disk = $params['disk'] ?? 'local';
+
+            return match ($disk) {
+                'local' => new LocalFileAdapter(Storage::disk($disk)),
+                default => throw new InvalidArgumentException("No FileAdapterInterface available for disk \"{$disk}\"."),
+            };
+        });
+    }
+
+    public function boot(): void
+    {
+        // Signed-URL auth only, same model as Shipping\Http\Controllers\
+        // DownloadShipmentLabelController — see that route's own docblock.
+        // Migrations live in the shared database/migrations directory
+        // CoreServiceProvider already loads; nothing more to register here.
+        $this->loadRoutesFrom(__DIR__.'/../File/routes/web.php');
+
+        Event::listen(CartLineAdded::class, AttachCustomFieldFileToCartLine::class);
+        Event::listen(OrderPlaced::class, TransferCustomFieldFileOwnership::class);
+
+        if ($this->app->runningInConsole()) {
+            $this->commands([PruneUnownedFilesCommand::class]);
+        }
+    }
+}

src/Review/Filament/Extensions/ProductResourceExtension.php

@@ -2,94 +2,30 @@
 
 namespace Modules\Core\Review\Filament\Extensions;
 
-use Filament\Forms\Components\Repeater;
-use Filament\Forms\Components\Select;
-use Filament\Forms\Components\TextInput;
-use Filament\Forms\Components\Toggle;
-use Filament\Schemas\Components\Section;
-use Filament\Schemas\Schema;
 use Lunar\Admin\Support\Extending\ResourceExtension;
+use Modules\Core\Catalog\Filament\Pages\ManageProductCustomFields;
 use Modules\Core\Review\Filament\Pages\ManageProductReviews;
 
 /**
  * CorePlugin allows exactly one extension class per Lunar resource — this
  * one already owned ProductResource (adding the Reviews sub-page) before
- * Catalog needed its own product-form addition, so extendForm() lives
- * here too rather than competing for the same resource slot.
- *
- * extendForm() adds a "Custom Fields" repeater authoring Product::
- * $custom_fields (see the migration adding that column, and Modules\Core\
- * Catalog\Models\Product's own docblock on why this needed a first-party
- * Product subclass rather than being addable to the base Lunar model) —
- * per-product, customer-authored input (a reference photo upload, an
- * optional engraving textarea) rendered on the storefront product page,
- * NOT a Lunar ProductOption: an option's values are a fixed, admin-
- * authored list that define variants, which doesn't fit "the customer
- * uploads their own unique photo."
+ * Catalog needed its own product-page addition, so registering
+ * ManageProductCustomFields lives here too rather than competing for the
+ * same resource slot. See that page's own docblock for what it does and
+ * why it's a separate sub-page rather than a section on the main form.
  */
 class ProductResourceExtension extends ResourceExtension
 {
     public function extendPages(array $pages): array
     {
         $pages['reviews'] = ManageProductReviews::route('/{record}/reviews');
+        $pages['custom-fields'] = ManageProductCustomFields::route('/{record}/custom-fields');
 
         return $pages;
     }
 
     public function extendSubNavigation(array $pages): array
     {
-        return [...$pages, ManageProductReviews::class];
-    }
-
-    public function extendForm(Schema $schema): Schema
-    {
-        return $schema->components([
-            ...$schema->getComponents(),
-            $this->customFieldsSection(),
-        ]);
-    }
-
-    private function customFieldsSection(): Section
-    {
-        return Section::make('Custom Fields')
-            ->description('Extra input the shopper fills in on this product\'s page before adding it to their cart — a reference photo, personalization text, etc.')
-            ->collapsible()
-            ->collapsed(fn ($record) => blank($record?->custom_fields))
-            ->schema([
-                Repeater::make('custom_fields')
-                    ->hiddenLabel()
-                    ->schema([
-                        TextInput::make('label')
-                            ->label('Label')
-                            ->helperText('Shown to the shopper above the field.')
-                            ->required(),
-                        Select::make('type')
-                            ->label('Field type')
-                            ->options([
-                                'text' => 'Short text',
-                                'textarea' => 'Long text',
-                                'file' => 'File upload',
-                            ])
-                            ->default('text')
-                            ->native(false)
-                            ->live()
-                            ->required(),
-                        TextInput::make('key')
-                            ->label('Key')
-                            ->helperText('Machine-facing identifier — stored on the order/cart line, used to look up this answer elsewhere. Cannot be changed once orders reference it.')
-                            ->required()
-                            ->alphaDash()
-                            ->maxLength(64),
-                        Toggle::make('required')
-                            ->label('Required')
-                            ->helperText('Shopper cannot add this product to their cart without answering.')
-                            ->default(false),
-                    ])
-                    ->columns(2)
-                    ->addActionLabel('Add a custom field')
-                    ->reorderable()
-                    ->collapsible()
-                    ->itemLabel(fn (array $state): ?string => $state['label'] ?? null),
-            ]);
+        return [...$pages, ManageProductReviews::class, ManageProductCustomFields::class];
     }
 }