Skip to content

Webshop - Asset, Panorama, Video, And Wheel Image Management

Overview

This document specifies the legacy asset/media capabilities that were missing migration-grade coverage for storefront APIs, admin image workflows, and the underlying data model.

Checklist coverage: - API-012 Front API asset-group and panorama endpoints - AD-015 Wheel image import/manage/recent changes - DM-010 Asset group/image/panorama/video entities

Primary legacy evidence: - _core/config/router.php - _cp/index.php - _admin/config/menu.php - _admin/config/routing.php - _admin/controller/classes/atx/articles/wheels/AdminWheelImagesController.php - _admin/model/classes/atx/articles/ArticleService.php - _core/model/dbclasses/atx/articles/WheelImageDAO.php - _core/model/dbclasses/atx/articles/ImageDAO.php - src/Atraxion/Asset/Controller/Api/AssetGroupController.php - src/Atraxion/Asset/Controller/Api/PanoramaController.php - src/Atraxion/Asset/Controller/Api/ImageController.php - src/Atraxion/Asset/Controller/Api/VideoController.php - src/Atraxion/Asset/Manager/AssetGroupManager.php - src/Atraxion/Asset/Form/UploadImageForm.php - src/Atraxion/Asset/Form/UploadProductImageForm.php - _core/config/doctrine/articles.assets.AssetGroup.orm.xml - _core/config/doctrine/articles.assets.Asset.orm.xml - _core/config/doctrine/articles.assets.Image.orm.xml - _core/config/doctrine/articles.assets.Panorama.orm.xml - _core/config/doctrine/articles.assets.PanoramaImage.orm.xml - _core/config/doctrine/articles.assets.Video.orm.xml

Legacy Capabilities (As-Is)

1. Storefront Asset/Panorama APIs (API-012)

Front routes under /_core/config/router.php expose: - GET /api/asset-groups - GET /api/asset-groups/for-product/{productId} - GET /api/asset-groups/for-product/{productId}/image - GET /api/asset-groups/for-product/{productId}/and-model/{vehicleModelId} - POST /api/panoramas - GET|PUT|DELETE /api/panoramas/{id} - POST /api/panoramas/{id}/upload

Behavior details: - Asset-group lookups are filter-based and product-aware (wheelTypeId, wheelColorId, tyreTypeId, vehicleModelId, productId). - findImageByProduct resolves primary image, chooses watermarked/non-watermarked path based on auth context, and falls back to configured default image. - Panorama upload persists multiple files and generates standard + watermarked + thumbnail derivatives.

2. Wheel Image Admin Workflow (AD-015)

Legacy admin module (admin.wheelImages) provides three primary tabs: - Import (importWheels, uploadWheels) - Manage (getWheels, getWheelsJson, copyImage, deleteImage, restoreImage) - Recent changes (getWheelsRecentChanges)

Behavior details: - Uses article_image table and filesystem folders for original/standard/thumbnail variants. - Applies invisible and visible watermark processing and stores crop metadata in sidecar JSON files. - Supports brand/type/color filtering, copy image between rows, and delete/restore. - Extended flow (uploadWheelImage2) supports vehicle-model gallery and article head-image (Foto) synchronization.

3. Asset Domain Model (DM-010)

Doctrine model uses grouped assets: - product_asset_group (AssetGroup) with uniqueness on category/type/color/model/product dimensions. - Joined inheritance root product_asset (Asset) for shared metadata/public/sort/update fields. - Specializations: - product_image (Image) - product_video (Video) - product_panorama (Panorama) - product_panorama_image (PanoramaImage)

Relationship model: - AssetGroup owns ordered collections of images, videos, panoramas (orphan removal). - Panorama owns ordered panorama images and optional primary image. - AssetGroup maintains optional primary image and product/category/type/model links.

Current Gaps And Risks To Resolve In Migration

  1. Dual image systems remain active (article_image legacy flow and product_asset_* flow), increasing divergence risk.
  2. Legacy wheel image admin still performs direct filesystem operations and ad-hoc metadata sidecar handling.
  3. Front and CP/admin API surfaces overlap but are not documented as one coherent contract.
  4. Error handling is inconsistent (400 vs 404; null-handling not always explicit before remove/store calls).
  5. Some endpoints/controllers appear partially implemented or unused (for example create/upload variants that are not fully wired in routes).
  6. Asset-group primary-image correctness depends on sort-order conventions and post-update hooks.
  7. Media derivative generation (watermark/invisible-watermark/thumb) is synchronous and can become heavy under burst uploads.

Target Migration Specification (Symfony)

Scope

In-scope: - Unified contract for storefront and admin media APIs. - Replacement strategy for legacy wheel image admin flows. - Canonical data model for grouped assets/panoramas/videos.

Out-of-scope: - Frontend redesign of admin media UI. - CDN/image transformation platform selection.

Domain Rules To Preserve

  1. Assets are grouped by product-category context and optional fitment context (type/color/model/product).
  2. Product pages must resolve a deterministic primary image with fallback behavior.
  3. Panoramas are first-class grouped assets with ordered image frames.
  4. Uploaded media requires generated variants suitable for authenticated/internal and public contexts.
  5. Sort-order updates must deterministically define primary-image selection.

Required Improvements

  1. Consolidate to one authoritative media persistence model; deprecate article_image write paths after migration cutover.
  2. Version and document API contracts for both storefront and admin media operations.
  3. Standardize response/error semantics (not-found, validation, upload failures).
  4. Add idempotency keys and duplicate-file detection for upload endpoints.
  5. Move heavy image processing to queued/background jobs with delivery status tracking.
  6. Add audit logging for media mutations (upload, delete, reorder, primary-image changes).
  7. Gate admin-only media mutations behind explicit role/permission checks per endpoint.

Suggested Target Components

  • MediaAssetGroupService
  • MediaUploadService
  • MediaDerivativeJob (background image processing)
  • MediaApiController (versioned storefront/admin endpoints)
  • MediaAuditLogService
  • LegacyImageMigrationService (article_image -> product_asset_*)

Data Migration Notes

  1. Migrate article_image records into product_asset_group + product_image with deterministic mapping by category/type/color/model.
  2. Carry forward sequence/order into sortOrder and compute primary images explicitly.
  3. Preserve legacy relative paths and regenerate missing derivatives where needed.
  4. Preserve crop/offset metadata currently stored in sidecar JSON by moving to structured image metadata JSON.
  5. Keep article head-image (Foto/OnlyFoto) compatibility until consumers are switched to asset-group APIs.

Acceptance Scenarios (Gherkin)

Feature: Asset, panorama, and wheel-image migration coverage

  Scenario: Storefront resolves asset groups for a wheel product
    Given a wheel product has an asset group for its type and color
    When the storefront requests asset groups for that product
    Then the response should include images, videos, and panoramas in group context

  Scenario: Storefront image endpoint falls back to default image
    Given a product has no primary image file available
    When the storefront requests /api/asset-groups/for-product/{productId}/image
    Then the configured default product image should be returned

  Scenario: Admin uploads panorama frames to an existing panorama
    Given an existing panorama linked to an asset group
    When multiple frames are uploaded
    Then standard and thumbnail panorama images should be generated and persisted

  Scenario: Admin reorders images in an asset group
    Given an asset group with multiple images
    When sort order is updated
    Then image order should be persisted and primary-image selection should be deterministic

  Scenario: Legacy wheel image import creates usable product derivatives
    Given a wheel type/color upload in the legacy admin module
    When the upload is processed
    Then original, standard, and thumbnail variants should exist with watermark policy applied

  Scenario: Legacy image records are migrated to asset groups
    Given historical rows in article_image
    When migration runs
    Then equivalent product_asset_group and product_image records should exist with matching ordering

Open Decisions

  1. Should video management remain in the same asset-group API boundary or split into a dedicated media service.
  2. Should legacy wheel-image UI stay available read-only during transition or be replaced immediately.
  3. Should derivative generation stay local filesystem-based or move to object storage + async processor.
  4. Should storefront media APIs be public-cacheable by default or always protected by signed URLs.