Skip to content

Platform Export - Channel Updaters And Order Deserializers

Overview

This document specifies legacy platform-specific outbound update integrations and platform order deserializers that were missing from migration docs.

Checklist coverage: - PX-003 Check24 updater - PX-004 Euromaster updater - PX-005 Roadzila updater - PX-006 Easy4D updater - PX-007 AdTyres updater - PX-008 ZeroSeven updater - PX-009 Directory/file-based updater - PX-010 Platform order deserializers

Primary legacy evidence: - src/Atraxion/Platform/Updater/Check24OrderUpdater.php - src/Atraxion/Platform/Updater/EuromasterOrderUpdater.php - src/Atraxion/Platform/Updater/RoadzilaOrderUpdater.php - src/Atraxion/Platform/Updater/Easy4DOrderUpdater.php - src/Atraxion/Platform/Updater/AdTyresOrderUpdater.php - src/Atraxion/Platform/Updater/ZeroSevenOrderUpdater.php - src/Atraxion/Platform/Updater/DirectoryOrderUpdater.php - src/Atraxion/Platform/Updater/ProxyOrderUpdater.php - src/Atraxion/Platform/Updater/AggregateOrderUpdater.php - src/Atraxion/Platform/OrderMapper/Check24OrderDeserializer.php - src/Atraxion/Platform/OrderMapper/Check24TyreOrderDeserializer.php - src/Atraxion/Platform/OrderMapper/Check24SetOrderDeserializer.php - src/Atraxion/Platform/OrderMapper/EuromasterOrderDeserializer.php - src/Atraxion/Platform/ServiceProvider/PlatformServiceProvider.php - _admin/model/classes/atx/orders/PlatformOrderService.php - _admin/controller/classes/atx/orders/UpdatingPlatformOrderController.php - _shopupdating/cronjobs/atx/orders/getOrders.php

Legacy Capabilities (As-Is)

Updater Dispatch Model

AggregateOrderUpdater invokes all tagged updaters that report supports(platform) = true.

AbstractPlatformOrderUpdater drives common status updates: - Iterate order reservations - For delivery notes with tracking numbers: call updateTracking(...) - For invoices with PDF: call updateInvoice(...) - Write invoice/delivery-note link statuses (send or failed) and flush

ProxyOrderUpdater handles generic export-based channel updates using PlatformExportService and active platform exports.

Channel-Specific Updaters

Updater Supports condition Tracking behavior Invoice behavior
Check24OrderUpdater platform.interface == C24 Builds semicolon CSV and uploads via FTP for tracking exports; writes FileUploadLog entries Builds semicolon CSV and uploads via FTP for invoice exports; writes FileUploadLog entries
EuromasterOrderUpdater platform.interface == EM Writes semicolon CSV text file (*_ERM.txt) to FTP tracking exports Writes semicolon CSV text file ({invoiceId}.txt) to FTP invoice exports
RoadzilaOrderUpdater platform.orderNumberPrefix == ROADZI Calls Roadzila HTTP endpoint with state=shipped and tracking links Not implemented (commented as separate path)
Easy4DOrderUpdater platform.orderNumberPrefix == ER Builds XML payload and uploads via FTP helper for active non-tracking exports Explicitly deferred to ProxyOrderUpdater
AdTyresOrderUpdater currently hard-disabled (supports() returns false) Legacy HTTP form submission implementation exists but not active Not supported
ZeroSevenOrderUpdater platform.interface starts with 07ZR Appends tracking CSV rows to local filesystem in prod only Copies invoice PDF to local filesystem in prod only
DirectoryOrderUpdater local platform with zero exports and existing platform data directory Appends tracking CSV to APP_PLATFORMDATA_PATH/{short}/out/tracking/{reference}.csv Not implemented

Audit/Logging Behavior

Check24OrderUpdater and Easy4DOrderUpdater persist upload records in channel_platform_upload_log (FileUploadLog) with optional error message.

Other updaters largely rely on exceptions/logging and do not consistently persist upload audit rows.

Platform Order Deserializers

Order deserialization classes currently documented by code but not migration specs:

  1. Check24OrderDeserializer
  2. Switches by payload shape:
  3. ORDER_HEADER present -> Check24TyreOrderDeserializer

  4. otherwise -> Check24SetOrderDeserializer

  5. Check24TyreOrderDeserializer

  6. Maps order number/date, invoice and delivery addresses, payment/bank fields, customer id
  7. Maps product lines by SUPPLIER_PID split to article/supplier ids

  8. Maps quantity/price, optional notes, optional order notice

  9. Check24SetOrderDeserializer

  10. Maps set-order envelope (order node)
  11. Creates separate order lines for wheel/tyre/TPMS quantities (a_anzahl, b_anzahl, c_anzahl)

  12. Uses fixed TPMS article id for TPMS lines

  13. EuromasterOrderDeserializer

  14. Maps order header, invoice and delivery addresses, transport cost, flags (neutral/express)
  15. Maps positions to order lines via supp_article_id split and net prices
  16. Sets internal cancellation notice and xml/customer identifiers

Deserializer usage is integrated in legacy import path: - _admin/model/classes/atx/orders/PlatformOrderService.php (makeOrderFromCheck24, makeOrderFromEuromaster) - Called from _admin/controller/classes/atx/orders/UpdatingPlatformOrderController.php during queue processing.

Current Gaps And Risks To Resolve In Migration

  1. Updater behavior is inconsistent by channel (FTP/API/local filesystem) with uneven idempotency guarantees.
  2. Audit logging is incomplete outside specific implementations (not all outbound writes are persisted as upload logs).
  3. RoadzilaOrderUpdater uses direct file_get_contents HTTP calls and plain token-from-URL pattern.
  4. AdTyresOrderUpdater is registered but functionally disabled (supports() === false).
  5. ZeroSevenOrderUpdater and DirectoryOrderUpdater rely on local filesystem paths and append semantics.
  6. Easy4DOrderUpdater splits responsibility with ProxyOrderUpdater, increasing double-send/missed-send risk if config is wrong.
  7. EuromasterOrderDeserializer references $fieldMap without local definition in current implementation.
  8. Check24 XML parsing relies on schema-shape assumptions and global XPath lookups that should be hardened.

Target Migration Specification (Symfony)

Scope

In-scope for this phase: - Channel-specific outbound status update adapters for Check24, Euromaster, Roadzila, Easy4D, AdTyres, ZeroSeven, and directory fallback - Explicit deserializer layer for Check24 and Euromaster import payloads - Unified audit logging for outbound delivery attempts

Out-of-scope for this phase: - Platform commercial onboarding UI redesign - Full replacement of legacy platform import controller workflow

Domain Rules To Preserve

  1. Updater dispatch is platform-capability based (supports) and may include both channel-specific and proxy/generic handlers.
  2. Tracking and invoice updates remain separate flows with independent status flags.
  3. Channel-specific payload format requirements (CSV/XML/API fields) must remain backward compatible.
  4. Platform import path still requires deterministic transformation from platform payload to internal order aggregate.

Required Improvements

  1. Add explicit idempotency keys per outbound update (invoice id + channel + export type).
  2. Standardize transport abstraction (no direct file_get_contents HTTP calls in adapters).
  3. Persist delivery attempts consistently for all updaters (success and failure).
  4. Add feature flags per channel adapter, including explicit state for disabled integrations (AdTyres).
  5. Validate and version incoming XML schemas for deserializers.
  6. Add structured error categorization (transport/auth/payload/configuration) for retries and alerting.
  7. Remove filesystem-only assumptions by introducing storage adapters for local-directory channels.

Suggested Target Components

Interfaces/services: - PlatformOutboundUpdaterInterface - PlatformOutboundDispatcher - PlatformTrackingExporter - PlatformInvoiceExporter - PlatformOrderDeserializerInterface - PlatformOrderImportMapper - PlatformDeliveryLogService

Channel adapters: - Check24UpdaterAdapter - EuromasterUpdaterAdapter - RoadzilaUpdaterAdapter - Easy4DUpdaterAdapter - AdTyresUpdaterAdapter (disabled until validated) - ZeroSevenUpdaterAdapter - DirectoryUpdaterAdapter

Deserializer adapters: - Check24TyreOrderDeserializer - Check24SetOrderDeserializer - EuromasterOrderDeserializer

Operational Requirements

  1. Emit metrics by adapter and action (tracking, invoice): attempted, succeeded, failed, skipped.
  2. Record latency and payload size per outbound attempt.
  3. Alert on repeated failures by channel/export type threshold.
  4. Require replay tooling for failed attempts from persisted delivery logs.

Data Migration Notes

  1. Preserve channel_platform_upload_log history and invoice links.
  2. Preserve platform export configuration and server credentials references used by updater routing.
  3. Preserve interface/order-prefix conventions (C24, EM, ROADZI, ER, 07ZR*) while introducing explicit adapter mapping table.
  4. Backfill missing outbound-delivery records only where deterministic reconstruction is possible.

Acceptance Scenarios (Gherkin)

Feature: Platform-specific outbound updaters and deserializers

  Scenario: Check24 tracking update exports CSV and logs delivery
    Given platform interface is "C24" with active tracking export server
    And an order delivery note has tracking numbers
    When platform status update runs
    Then a tracking CSV should be uploaded
    And a platform upload log entry should be persisted

  Scenario: Euromaster invoice update exports text CSV file
    Given platform interface is "EM" with active invoice export server
    And an order invoice has a PDF
    When platform status update runs
    Then an invoice text file should be uploaded to the configured path

  Scenario: Roadzila cancelled order sends cancellation state
    Given platform order prefix is "ROADZI"
    And an order is cancelled
    When platform status update runs
    Then a Roadzila state update with "cancelled" should be sent

  Scenario: Easy4D sends tracking XML
    Given platform order prefix is "ER"
    And order tracking data exists
    When platform status update runs
    Then an XML tracking payload should be uploaded for active exports

  Scenario: AdTyres adapter remains inactive when disabled
    Given AdTyres adapter feature flag is disabled
    When platform status update runs
    Then no AdTyres outbound call should be executed

  Scenario: ZeroSeven writes files only in production
    Given platform interface starts with "07ZR"
    And environment is not production
    When platform status update runs
    Then no tracking or invoice files should be written

  Scenario: Directory fallback writes local tracking CSV
    Given platform is local with no exports and valid platform data directory
    And tracking data exists
    When platform status update runs
    Then tracking CSV rows should be appended under out/tracking

  Scenario: Check24 deserializer selects tyre variant by payload
    Given an incoming Check24 XML contains ORDER_HEADER
    When the payload is deserialized
    Then tyre-order deserialization rules should be applied

  Scenario: Check24 deserializer selects set variant by payload
    Given an incoming Check24 XML has legacy set-order shape without ORDER_HEADER
    When the payload is deserialized
    Then set-order deserialization rules should be applied

  Scenario: Euromaster XML is deserialized into internal order aggregate
    Given an incoming Euromaster order payload with positions
    When the payload is deserialized
    Then order header, addresses, and line items should be mapped to internal order fields

Open Decisions

  1. Should Roadzila and similar HTTP channels move to authenticated API clients with retries/circuit breakers immediately, or in a second hardening phase?
  2. Should local-directory adapters (ZeroSeven/Directory) be retained, replaced with managed object storage, or deprecated?
  3. Should AdTyres remain disabled permanently or be restored behind conformance tests?
  4. Should ProxyOrderUpdater remain combined with channel-specific adapters, or be split into a separate execution stage with explicit precedence?